From f1092090f5b89b9ead7c20da781399099021b278 Mon Sep 17 00:00:00 2001
From: fOuttaMyPaint <154358121+TMHSDigital@users.noreply.github.com>
Date: Sat, 23 May 2026 14:35:23 -0400
Subject: [PATCH] docs: reconcile narrative docs with v1.9.5 reality
- Update standards-doc count to 18 in .cursorrules, AGENTS.md,
CLAUDE.md, and CONTRIBUTING.md (was 9 or 17 depending on file)
- docs/index.html: standards grid expanded from 8 to 18 cards
matching standards/README.md order; footer version updated from
v1.5.0 to v1.9.5; standards count badge corrected to 18
- ROADMAP.md: Current Status updated to v1.9.5 with accurate
prior-milestone list; Release Plan table updated with six Released
range rows for v1.7.x through v1.9.x; speculative v1.7.0,
v1.8.0, v1.9.0 narrative sections replaced with accurate content
derived from git history and release notes; new sections added for
v1.7.1-v1.7.5, v1.8.1-v1.8.5, and v1.9.1-v1.9.5
Patch range rows in the Release Plan table are deliberate: they
group closely related patch series by theme rather than listing each
patch individually. This is not a per-patch policy but a readability
choice for series that shipped in rapid succession.
standards/drift-checker.config.json intentionally left unstaged
(Windows CRLF phantom, no content change).
Signed-off-by: fOuttaMyPaint <154358121+TMHSDigital@users.noreply.github.com>
---
.cursorrules | 2 +-
AGENTS.md | 2 +-
CLAUDE.md | 2 +-
CONTRIBUTING.md | 2 +-
ROADMAP.md | 89 ++++++++++++++++++++++++++++++++++++-------------
docs/index.html | 16 +++++++--
6 files changed, 82 insertions(+), 31 deletions(-)
diff --git a/.cursorrules b/.cursorrules
index e625490..4ac8166 100644
--- a/.cursorrules
+++ b/.cursorrules
@@ -3,7 +3,7 @@ You are working on Developer Tools Directory, a meta-repository that catalogs, s
## Repo structure
- `registry.json` -- single source of truth for all 9 tool repos (name, type, counts, links, status)
-- `standards/` -- 9 Markdown docs defining conventions (folder structure, CI/CD, manifests, pages, commits, README, AGENTS.md, versioning)
+- `standards/` -- 18 Markdown docs defining conventions (folder structure, CI/CD, manifests, pages, commits, README, AGENTS.md, versioning, and more)
- `scaffold/create-tool.py` -- Python repo generator using Jinja2 templates
- `scaffold/templates/` -- Jinja2 templates producing a standards-compliant repo
- `site-template/` -- shared GitHub Pages build system for tool repos (build_site.py + template.html.j2 + fonts)
diff --git a/AGENTS.md b/AGENTS.md
index 6a3dcb6..349ab86 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -9,7 +9,7 @@ This file tells AI coding agents how the Developer Tools Directory repo works an
This is a **meta-repository** -- it does not contain a Cursor plugin or MCP server itself. It catalogs, standardizes, and scaffolds other TMHSDigital developer tool repos. It contains:
- **`registry.json`** -- single source of truth for all tool repos. README, CLAUDE.md, and the catalog site's embedded registry are generated from it by `scripts/sync_from_registry.py`.
-- **`standards/`** -- 17 Markdown docs defining conventions for folder structure, CI/CD, plugin manifests, GitHub Pages, commits, README format, AGENTS.md format, versioning, testing, skills, rules, MCP servers, security, licensing, scope, lifecycle, and writing style.
+- **`standards/`** -- 18 Markdown docs defining conventions for folder structure, CI/CD, plugin manifests, GitHub Pages, commits, README format, AGENTS.md format, versioning, release-doc-sync, testing, skills, rules, MCP servers, security, licensing, scope, lifecycle, and writing style.
- **`scaffold/`** -- Python repo generator (`create-tool.py`) with Jinja2 templates that produce a fully standards-compliant new tool repo.
- **`scripts/`** -- automation utilities. `sync_from_registry.py` regenerates all derived artifacts from `registry.json`.
- **`site-template/`** -- shared GitHub Pages build system for tool repos. `build_site.py` reads `.cursor-plugin/plugin.json`, `site.json`, `skills/`, `rules/`, and `mcp-tools.json` from a tool repo and renders `docs/index.html` via `template.html.j2`. Self-hosts Inter and JetBrains Mono fonts. Tool repos clone this directory in CI and run the build script at deploy time.
diff --git a/CLAUDE.md b/CLAUDE.md
index 3e6a165..b05e027 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -16,7 +16,7 @@ Developer Tools Directory is a **meta-repository** that catalogs, standardizes,
```
Developer-Tools-Directory/
registry.json # Source of truth for all tool repos
- standards/ # 17 convention docs (structure, CI/CD, testing, MCP, security, licensing, etc.)
+ standards/ # 18 convention docs (structure, CI/CD, testing, MCP, security, licensing, etc.)
scaffold/
create-tool.py # Python repo generator (Jinja2)
templates/ # Jinja2 templates for new repos
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index f66a118..855564f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -24,7 +24,7 @@ Thank you for your interest in contributing. This guide covers everything you ne
```
Developer-Tools-Directory/
registry.json # Tool catalog (source of truth)
- standards/ # Convention documentation (9 docs)
+ standards/ # Convention documentation (18 docs)
scaffold/
create-tool.py # Repo generator script
templates/ # Jinja2 templates for new repos
diff --git a/ROADMAP.md b/ROADMAP.md
index b1094a5..cd19503 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -4,10 +4,18 @@
## Current Status
-**v1.6.3** - Patch release. Resolves drafter-body detection and branch-protection residuals from the version-scheme migration. `release.yml` now treats a drafter body of `## What's Changed / * No changes` as empty and falls through to the commit-log fallback. `main` is now protected by a GitHub ruleset (`main protection`) with 7 required status checks including `feat/fix commits require VERSION bump`, squash-merge only, no force pushes, no deletion, empty bypass list. Documentation across AGENTS.md, CLAUDE.md, CONTRIBUTING.md, `.github/workflows/README.md`, and `standards/ci-cd.md` updated to reflect the PR-based workflow.
+**v1.9.5** - Patch release. Removes `paths-ignore` from the meta-repo `release.yml` so content-only changes still gate releases on commit prefix. Companion fix removes `paths-ignore` from the scaffold `release.yml.j2` template so generated repos get the same behavior.
Prior milestones in this line:
+- **v1.9.4** - docs: update release-doc-sync header comment to reflect the @v1 / @v1.X floating-tag convention.
+- **v1.9.3** - fix: align scaffold output with current ecosystem patterns (ref #45).
+- **v1.9.2** - fix: release-doc-sync default meta-repo-ref changed to `v1` (floating major tag).
+- **v1.9.1** - fix: stale-counts policy correction; example sections and dialogue lines added to aggregate-scan skip list (DTD#37).
+- **v1.9.0** - CI maintenance. Node 24-compatible GitHub Actions versions, dependabot coverage extended to github-actions ecosystem, Sponsor button and FUNDING.yml, stale-counts DTD#12 skip for AGENTS.md and CLAUDE.md.
+- **v1.8.x** - release-doc-sync composite action (v1.8.0) plus fixes for checkout pollution, workspace cleanup, label-sync self-healing, floating-tag automation in `release.yml`, and version-bump-check parser.
+- **v1.7.x** - drift checker in two phases: Phase 1 (agents-template standard, scaffold updates, workflow docs); Phase 2 (core library, additional checks, CI integration, token separation, exit-code propagation).
+- **v1.6.3** - Drafter-body fix and branch-protection ruleset. `release.yml` treats a drafter body of `## What's Changed / * No changes` as empty. `main protection` ruleset established with 7 required checks.
- **v1.6.2** - Release-drafter decoupling. Release-drafter no longer computes its own version; change-note aggregation only. Versioning is fully driven by the `VERSION` file and `release.yml`.
- **v1.6.1** - `VERSION`-file-driven releases. Replaces conventional-commit auto-bump with an authoritative `VERSION` file; `feat:`/`fix:` commits require a VERSION bump enforced by CI.
- **v1.6.0** - Standards and Governance. Nine new standards docs, registry-to-artifact sync automation, DCO + inbound license grant, scope and lifecycle principles, public-repo safety hardening.
@@ -26,9 +34,12 @@ Prior milestones in this line:
| v1.6.1 | VERSION-file-driven releases | Released |
| v1.6.2 | Release-drafter decoupling | Released |
| v1.6.3 | Drafter-body fix and branch-protection ruleset | Released |
-| v1.7.0 | Sync Everywhere and Agent-File Drift | Planned |
-| v1.8.0 | Observability and Feedback | Planned |
-| v1.9.0 | Standards Versioning | Planned |
+| v1.7.0 | Drift Checker Foundation | Released |
+| v1.7.1 - v1.7.5 | Drift Checker Complete | Released |
+| v1.8.0 | Release Doc Sync | Released |
+| v1.8.1 - v1.8.5 | Release Doc Sync Fixes | Released |
+| v1.9.0 | CI Maintenance | Released |
+| v1.9.1 - v1.9.5 | Scaffold and Pipeline Fixes | Released |
---
@@ -181,38 +192,68 @@ Close the content, automation, and governance gaps identified in the v1.5 audit.
---
-## v1.7.0 - Sync Everywhere and Agent-File Drift
+## v1.7.0 - Drift Checker Foundation
-Extend the single-source-of-truth pattern beyond the directory repo.
+Phase 1 of the drift checker project. Established the agents-template standard, updated scaffold templates, and aligned workflow documentation with the branch-protection ruleset.
-- Generate `AGENTS.md` and `CLAUDE.md` sections in every tool repo from `registry.json` where they duplicate registry data
-- Add a `standards-version` frontmatter to every tool repo's `AGENTS.md` so the directory can audit compliance
-- Aggregate changelog workflow pulling each tool repo's `CHANGELOG.md` into a weekly digest on the catalog site
-- Cross-tool integration guidance: when to share code, when to duplicate, how to version shared modules
+- `standards/agents-template.md` added, documenting the required structure for AI agent guidance files in tool repos
+- Scaffold updated to generate compliant `AGENTS.md` from the new template
+- Workflow documentation across `AGENTS.md`, `CLAUDE.md`, and `.github/workflows/README.md` updated to reflect the active `main protection` ruleset
---
-## v1.8.0 - Observability and Feedback
+## v1.7.1 - v1.7.5 - Drift Checker Complete
-Empirical signals to drive standards revision.
+Phase 2: the drift checker itself. Automated detection of tool-repo policy drift surfaced as GitHub issues.
-- Opt-in telemetry spec for MCP tool invocation counts
-- npm download aggregator on the catalog site (public data)
-- `docs/INSIGHTS.md` generated weekly showing top tools/skills by signal
-- CI check flagging skills not invoked in the last 90 days as dormant
-- Feedback loop: standards changes must cite an empirical observation or user report
+- `scripts/drift_check/` core library: checks for standards-version signals in `AGENTS.md`, `CLAUDE.md`, skills, and rules files against the meta-repo `VERSION`
+- Additional policy checks: broken standards links, required references, stale aggregate counts in markdown
+- CI integration: runs on push to `main` (when checker code or standards change), weekly on schedule, and on demand via `workflow_dispatch`
+- Token split: `DRIFT_CHECK_TOKEN` for cross-repo sparse-checkout reads, `GITHUB_TOKEN` for issue writes
+- Exit-code propagation fix for the composite action caller
---
-## v1.9.0 - Standards Versioning
+## v1.8.0 - Release Doc Sync
-Version the ecosystem itself.
+Composite action for keeping `CHANGELOG.md`, `CLAUDE.md`, and `ROADMAP.md` in sync after an automated release.
-- Each standards doc gets a `standards-version` header
-- A per-standard changelog
-- Tool repos pin the standards version they claim to meet
-- Directory emits a compliance matrix per tool by standards version
-- Principles doc maintains its own version and changelog
+- `.github/actions/release-doc-sync/action.yml` composite action checks out the tool repo, runs the sync script, commits and pushes any drift
+- Designed for use in tool-repo `release.yml` workflows: `uses: TMHSDigital/Developer-Tools-Directory/.github/actions/release-doc-sync@v1`
+- `standards/release-doc-sync.md` documents the contract between the action and calling repos
+
+---
+
+## v1.8.1 - v1.8.5 - Release Doc Sync Fixes
+
+Correctness fixes for the composite action and related CI machinery.
+
+- Checkout pollution: action no longer contaminates the caller's working tree
+- Defensive workspace cleanup added on failure paths
+- Label-sync self-healing: ports the self-healing pattern to the meta-repo `label-sync.yml`
+- Floating-tag automation: `release.yml` now creates and updates `v1` and `v1.X` floating tags on every release
+- Version-bump-check parser: fixed silent pass-all bug affecting PRs with multi-line commit subjects
+
+---
+
+## v1.9.0 - CI Maintenance
+
+Routine maintenance to keep the CI stack current and discoverable.
+
+- GitHub Actions bumped to Node 24-compatible versions across all workflows
+- Dependabot coverage extended to the `github-actions` ecosystem
+- Sponsor button added via `.github/FUNDING.yml`
+- Stale-counts check: `AGENTS.md` and `CLAUDE.md` skipped wholesale by filename regardless of config (DTD#12); aggregate-truth for those files belongs in a per-repo validate-counts job
+
+---
+
+## v1.9.1 - v1.9.5 - Scaffold and Pipeline Fixes
+
+- Stale-counts policy correction: example sections and roleplay dialogue lines excluded from aggregate scanning (DTD#37)
+- release-doc-sync `action.yml` default `meta-repo-ref` corrected to `v1` (floating major tag)
+- Scaffold `release.yml.j2` template: `paths-ignore` removed so content-only changes still gate releases on commit prefix
+- Scaffold output aligned with current ecosystem patterns (ref #45)
+- Meta-repo `release.yml`: `paths-ignore` removed for the same reason as the scaffold fix
---
diff --git a/docs/index.html b/docs/index.html
index 6929f95..6e85270 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -257,7 +257,7 @@ Developer Tools Directory
@@ -308,7 +318,7 @@ Scaffold Generator