docguard-cli 0.21.1__tar.gz → 0.22.1__tar.gz

{docguard_cli-0.21.1/extensions/spec-kit-docguard → docguard_cli-0.22.1/.agent}/skills/docguard-fix/SKILL.md

@@ -6,10 +6,10 @@ description: AI-driven documentation repair with structured research workflow, t
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.21.1
+  version: 0.22.1
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.21.1 -->
+<!-- docguard:version: 0.22.1 -->
 
 # DocGuard Fix Skill
 

{docguard_cli-0.21.1/extensions/spec-kit-docguard → docguard_cli-0.22.1/.agent}/skills/docguard-guard/SKILL.md

@@ -7,10 +7,10 @@ description: Run DocGuard guard validation against Canonical-Driven Development
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.21.1
+  version: 0.22.1
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.21.1 -->
+<!-- docguard:version: 0.22.1 -->
 
 # DocGuard Guard Skill
 
@@ -24,7 +24,7 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 ## Goal
 
-Execute DocGuard's 19-validator guard suite against the current project, parse structured results, triage findings by severity and impact, and produce an actionable remediation plan. This skill transforms raw CLI output into an AI-digestible quality assessment.
+Execute DocGuard's full guard validator suite against the current project, parse structured results, triage findings by severity and impact, and produce an actionable remediation plan. This skill transforms raw CLI output into an AI-digestible quality assessment.
 
 ## Pre-Execution Checks
 

{docguard_cli-0.21.1/extensions/spec-kit-docguard → docguard_cli-0.22.1/.agent}/skills/docguard-review/SKILL.md

@@ -6,10 +6,10 @@ description: Cross-document consistency analysis and quality assessment. Perform
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.21.1
+  version: 0.22.1
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.21.1 -->
+<!-- docguard:version: 0.22.1 -->
 
 # DocGuard Review Skill
 

{docguard_cli-0.21.1 → docguard_cli-0.22.1}/.agent/skills/docguard-score/SKILL.md

@@ -6,10 +6,10 @@ description: CDD maturity assessment with category-aware improvement roadmap. Ru
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.21.1
+  version: 0.22.1
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.21.1 -->
+<!-- docguard:version: 0.22.1 -->
 
 # DocGuard Score Skill
 

{docguard_cli-0.21.1 → docguard_cli-0.22.1}/.agent/skills/docguard-sync/SKILL.md

@@ -4,7 +4,7 @@ description: Keep canonical documentation ALWAYS UP TO DATE. Refreshes code-trut
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.21.1
+  version: 0.22.1
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
 

{docguard_cli-0.21.1 → docguard_cli-0.22.1}/.docguard.json

@@ -40,5 +40,40 @@
     "environment": true,
     "freshness": true
   },
-  "severity": {}
+  "severity": {},
+  "surfaceSync": {
+    "surfaces": [
+      {
+        "name": "commands",
+        "glob": "cli/commands/*.mjs",
+        "extract": "basename-no-ext",
+        "ignore": [
+          "agents", "hooks", "ci", "badge", "llms", "publish",
+          "setup", "impact"
+        ],
+        "docs": ["README.md"],
+        "section": "Usage"
+      },
+      {
+        "name": "validators",
+        "glob": "cli/validators/*.mjs",
+        "extract": "basename-no-ext",
+        "ignore": [
+          "drift",
+          "doc",
+          "doc-sections",
+          "drift-comments"
+        ],
+        "docs": ["README.md"],
+        "section": "Validators"
+      },
+      {
+        "name": "slash-commands",
+        "glob": "templates/commands/*.md",
+        "extract": "basename-no-ext",
+        "docs": ["README.md"],
+        "section": "Slash Commands"
+      }
+    ]
+  }
 }

docguard_cli-0.22.1/.github/dependabot.yml

@@ -0,0 +1,23 @@
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    groups:
+      all-npm:
+        patterns: ["*"]
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    groups:
+      all-pip:
+        patterns: ["*"]
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    groups:
+      all-actions:
+        patterns: ["*"]

{docguard_cli-0.21.1 → docguard_cli-0.22.1}/.github/workflows/ci.yml

@@ -15,7 +15,7 @@ jobs:
         node-version: [18, 20, 22]
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0 # Full git history for freshness validator
 
@@ -81,7 +81,7 @@ jobs:
     if: startsWith(github.ref, 'refs/tags/v')
     needs: test
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: actions/setup-node@v6
         with:
           node-version: 20

{docguard_cli-0.21.1 → docguard_cli-0.22.1}/.github/workflows/release.yml

@@ -19,7 +19,7 @@ jobs:
       version: ${{ steps.check.outputs.version }}
       changed: ${{ steps.check.outputs.changed }}
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 2 # Need previous commit to compare
 
@@ -49,7 +49,7 @@ jobs:
       matrix:
         node-version: [18, 20, 22]
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
       - uses: actions/setup-node@v6
@@ -68,7 +68,7 @@ jobs:
     outputs:
       tag: v${{ needs.detect-version.outputs.version }}
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0 # Fetch all history + tags for reliable tag detection
 
@@ -125,7 +125,7 @@ jobs:
     needs: [detect-version, create-release]
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
 
       - name: Build extension ZIP
         run: |
@@ -150,7 +150,7 @@ jobs:
     needs: [detect-version, test, create-release]
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: actions/setup-node@v6
         with:
           node-version: 20
@@ -166,7 +166,7 @@ jobs:
     needs: [detect-version, test, create-release]
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: actions/setup-python@v6
         with:
           python-version: '3.12'
@@ -189,3 +189,139 @@ jobs:
         env:
           TWINE_USERNAME: __token__
           TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+
+  # ── Step 7: Sync Spec Kit community catalog ────────────────────────────
+  # Inlined here (rather than triggered via workflow_run from a sibling
+  # workflow) because workflow_run-triggered jobs get 401 on the
+  # `gh repo sync … --source github/spec-kit` API call even with a valid
+  # PAT in secrets. Same-workflow secret access is consistent — fixes the
+  # auto-sync that was failing on every release since the workflow_run
+  # auth quirk surfaced.
+  sync-catalog:
+    needs: [detect-version, build-extension, publish-npm, publish-pypi]
+    if: needs.detect-version.outputs.changed == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout docguard repo
+        uses: actions/checkout@v6
+
+      - name: Get version and metadata
+        id: meta
+        run: |
+          VERSION="${{ needs.detect-version.outputs.version }}"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "tag=v${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "download_url=https://github.com/raccioly/docguard/releases/download/v${VERSION}/spec-kit-docguard-v${VERSION}.zip" >> "$GITHUB_OUTPUT"
+          echo "updated_at=$(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$GITHUB_OUTPUT"
+          echo "✅ Version: $VERSION"
+
+      - name: Extract release notes from CHANGELOG
+        id: notes
+        run: |
+          VERSION="${{ steps.meta.outputs.version }}"
+          NOTES=$(awk "/^## \\[${VERSION}\\]/{found=1; next} /^## \\[/{if(found) exit} found{print}" CHANGELOG.md)
+          if [ -z "$NOTES" ]; then
+            NOTES="Updated to v${VERSION}. See [CHANGELOG](https://github.com/raccioly/docguard/blob/main/CHANGELOG.md) for details."
+          fi
+          echo "$NOTES" > /tmp/changelog-section.md
+          echo "✅ Release notes extracted ($(wc -l < /tmp/changelog-section.md) lines)"
+
+      - name: Sync fork with upstream
+        env:
+          GH_TOKEN: ${{ secrets.SPECKIT_PR_TOKEN }}
+        run: |
+          gh repo sync raccioly/spec-kit --source github/spec-kit --branch main --force
+          echo "✅ Fork synced with upstream"
+
+      - name: Checkout spec-kit fork (fresh after sync)
+        uses: actions/checkout@v6
+        with:
+          repository: raccioly/spec-kit
+          token: ${{ secrets.SPECKIT_PR_TOKEN }}
+          path: spec-kit-fork
+          ref: main
+
+      - name: Update catalog.community.json
+        working-directory: spec-kit-fork
+        run: |
+          VERSION="${{ steps.meta.outputs.version }}"
+          DOWNLOAD_URL="${{ steps.meta.outputs.download_url }}"
+          UPDATED_AT="${{ steps.meta.outputs.updated_at }}"
+          cp ${{ github.workspace }}/.github/scripts/patch-catalog.py /tmp/patch-catalog.py
+          python3 /tmp/patch-catalog.py "$VERSION" "$DOWNLOAD_URL" "$UPDATED_AT"
+
+      - name: Create or update branch
+        working-directory: spec-kit-fork
+        run: |
+          BRANCH="update-docguard"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git checkout -B "$BRANCH"
+          git add extensions/catalog.community.json extensions/README.md
+          git commit -m "chore: update DocGuard extension to v${{ steps.meta.outputs.version }}" || echo "No changes to commit"
+          git push --force origin "$BRANCH"
+          echo "✅ Branch $BRANCH pushed"
+
+      - name: Create or update PR
+        working-directory: spec-kit-fork
+        env:
+          GH_TOKEN: ${{ secrets.SPECKIT_PR_TOKEN }}
+        run: |
+          VERSION="${{ steps.meta.outputs.version }}"
+          BRANCH="update-docguard"
+          PR_TITLE="chore: update DocGuard extension to v${VERSION}"
+
+          cat > /tmp/pr-body.md << 'HEADER'
+          ## DocGuard Community Extension Update
+
+          Updates the DocGuard community extension catalog entry.
+
+          ### Changes
+          HEADER
+
+          echo "- Version: **v${VERSION}**" >> /tmp/pr-body.md
+          echo "- Download: \`spec-kit-docguard-v${VERSION}.zip\`" >> /tmp/pr-body.md
+          echo "- Repository: https://github.com/raccioly/docguard" >> /tmp/pr-body.md
+          echo "" >> /tmp/pr-body.md
+          echo "### Release Notes" >> /tmp/pr-body.md
+          echo "" >> /tmp/pr-body.md
+          cat /tmp/changelog-section.md >> /tmp/pr-body.md
+          echo "" >> /tmp/pr-body.md
+          echo "---" >> /tmp/pr-body.md
+          echo "*This PR was automatically generated by the DocGuard release pipeline.*" >> /tmp/pr-body.md
+
+          EXISTING_PR=$(gh pr list \
+            --repo github/spec-kit \
+            --head "raccioly:${BRANCH}" \
+            --state open \
+            --json number \
+            --jq '.[0].number' 2>/dev/null || echo "")
+
+          if [ -z "$EXISTING_PR" ] || [ "$EXISTING_PR" = "null" ]; then
+            EXISTING_PR=$(gh pr list \
+              --repo github/spec-kit \
+              --state open \
+              --search "head:raccioly:${BRANCH}" \
+              --json number \
+              --jq '.[0].number' 2>/dev/null || echo "")
+          fi
+
+          if [ -n "$EXISTING_PR" ] && [ "$EXISTING_PR" != "null" ]; then
+            echo "Found existing PR #${EXISTING_PR} — updating title and body..."
+            gh pr edit "$EXISTING_PR" \
+              --repo github/spec-kit \
+              --title "$PR_TITLE" \
+              --body-file /tmp/pr-body.md
+            echo "✅ Updated existing PR #${EXISTING_PR} to v${VERSION}"
+          else
+            PR_URL=$(gh pr create \
+              --repo github/spec-kit \
+              --head "raccioly:${BRANCH}" \
+              --base main \
+              --title "$PR_TITLE" \
+              --body-file /tmp/pr-body.md 2>&1) && {
+              echo "✅ Created new PR: $PR_URL"
+            } || {
+              echo "⚠️ Could not create or find PR — branch was force-pushed with v${VERSION} content"
+            }
+          fi

{docguard_cli-0.21.1 → docguard_cli-0.22.1}/.github/workflows/sync-speckit-catalog.yml

@@ -1,11 +1,16 @@
-name: Sync DocGuard to Spec Kit Community Catalog
-
-# Triggers after the release workflow completes, or manually
+name: Sync DocGuard to Spec Kit Community Catalog (Manual)
+
+# Manual recovery only. The automatic post-release sync now runs inside
+# release.yml itself (see the `sync-catalog` job there). This workflow
+# is kept for one-off catalog updates outside the release flow, e.g.
+# fixing a stale entry, retrying after upstream maintenance, or pushing
+# a metadata-only refresh.
+#
+# The previous workflow_run trigger was removed because it caused
+# repeatable HTTP 401s on `gh repo sync ... --source github/spec-kit`
+# despite the PAT being valid — a known GitHub Actions auth quirk for
+# cross-workflow secret usage in workflow_run contexts.
 on:
-  workflow_run:
-    workflows: ["Auto Release — Tag, GitHub Release, npm, PyPI"]
-    types: [completed]
-    branches: [main]
   workflow_dispatch:
     inputs:
       version:
@@ -19,12 +24,10 @@ permissions:
 jobs:
   sync-catalog:
     runs-on: ubuntu-latest
-    # Only run if the release workflow succeeded (or manual trigger)
-    if: ${{ github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success' }}
 
     steps:
       - name: Checkout docguard repo
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
 
       - name: Get version and metadata
         id: meta
@@ -71,7 +74,7 @@ jobs:
           echo "✅ Fork synced with upstream"
 
       - name: Checkout spec-kit fork (fresh after sync)
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
         with:
           repository: raccioly/spec-kit
           token: ${{ secrets.SPECKIT_PR_TOKEN }}

{docguard_cli-0.21.1 → docguard_cli-0.22.1}/.gitignore

@@ -1,6 +1,9 @@
 # Dependencies
 node_modules/
 
+# Build artifacts (npm pack output — never commit)
+*.tgz
+
 # Internal research (not part of the public package)
 Research/
 
@@ -34,3 +37,4 @@ dist/
 *.egg-info/
 __pycache__/
 .venv
+.docguard/

{docguard_cli-0.21.1 → docguard_cli-0.22.1}/.jules/palette.md

@@ -5,3 +5,7 @@
 ## 2024-04-16 - Context-Aware Status Bar Tooltips
 **Learning:** VS Code extension status bar items can display multiple forms of feedback, but static tooltips fail to explain state changes. Providing context-aware tooltip text (e.g., explaining why a threshold warning icon appears) greatly improves the usability for developers monitoring CLI outputs inline.
 **Action:** Always map status bar dynamic properties (icon, text, backgroundColor) to corresponding informative tooltips that explain what the visual change means.
+
+## 2024-05-18 - Yielding Event Loop for Loading States
+**Learning:** When updating UI elements like VS Code extension `statusBarItem` to show a loading state (e.g., adding a spinner and changing tooltip) immediately prior to a synchronous, blocking operation (like `execSync`), the changes won't render unless you explicitly yield the event loop.
+**Action:** Use `await new Promise(r => setTimeout(r, 0))` right after the UI update to allow the editor time to render the visual changes before the main thread blocks.

{docguard_cli-0.21.1 → docguard_cli-0.22.1}/AGENTS.md

@@ -41,7 +41,7 @@
 | Command | Purpose |
 |---------|---------|
 | `diagnose` | **Primary** — identify issues + generate AI fix prompts |
-| `guard` | Validate project (CI gate) — 23 validators |
+| `guard` | Validate project (CI gate) — 24 validators |
 | `generate` | Reverse-engineer docs from code |
 | `fix --doc <name>` | AI prompt for specific document |
 | `score` | CDD maturity score (0-100) |

{docguard_cli-0.21.1 → docguard_cli-0.22.1}/CHANGELOG.md

@@ -7,6 +7,160 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.22.1] - 2026-05-29
+
+Self-audit + field-feedback patch. Honest fixes only — no doc-gaming. The
+remaining guard warnings (Spec-Kit on bugfix specs, negation-load, docs-diff
+test files, freshness lag, the demo↔docguard import cycle) are deferred to
+v0.23.0 because the *correct* fix is improving the validators, not papering
+over the docs. `sync --write` confirmed the freshness warnings are git-age
+lag, not real code-truth drift, so they were left honest rather than date-bumped.
+
+### Fixed
+- **Stale validator counts in scaffolded files** — `extensions/spec-kit-docguard/skills/docguard-guard/SKILL.md`
+  ("19-validator") and `extensions/spec-kit-docguard/commands/guard.md` ("19-validator", "20 total")
+  hardcoded counts that drift every release and shipped into user projects. Reworded to be count-free,
+  matching the already-fixed `templates/commands/docguard.guard.md`. (Field report, Issue 1.)
+- **REQUIREMENTS.md non-functional requirements were unfilled web-service boilerplate**
+  ("200ms p95", "99.9% uptime SLA") — nonsensical for a zero-dependency CLI and untraced.
+  Rewrote NFR-001/002/003 to DocGuard's real, test-backed NFRs (injection-safe subprocess
+  spawns, zero runtime deps, cross-process plan cache) and traced each to its regression test
+  via `@req` tags. Clears the 3 Traceability warnings honestly.
+- **`specs/002-fix-test-discovery/plan.md`** — added the Spec-Kit-mandated `Summary` and
+  `Project Structure` sections (real content).
+
+### Added / Improved
+- **`docguard explain canonical-sync`** — the count-level companion validator was missing from
+  the explainer table; added it. (Field report, Issue 10.)
+- **Test-Spec validator note** now points to the expected table format and `docguard explain` when
+  it finds no service-to-test mappings, instead of a dead-end message. (Field report, Issue 4.)
+
+### Docs
+- **README "What's New" no longer over-claims language-aware trace mapping for `guard`.** The
+  multilingual patterns live in the standalone `docguard trace` command; the guard-time
+  Traceability validator is JS/TS-first today, with language parity on the v0.23 roadmap.
+  (Field report, Issue 3 — honesty fix pending the full validator port.)
+
+## [0.22.0] - 2026-05-28
+
+### Added — Surface-Sync validator (item-level enumerable drift)
+
+`canonical-sync` already checks NUMERIC count claims in the README (ships
+N commands, N validators, mermaid diagram counts). But running the docguard
+repo through itself showed `canonical-sync` passing 3/3 while the README's
+command table silently omitted `demo` — the count matched, the table was
+wrong, the user hit "command not found" anyway. Count-level checks miss
+item-level drift.
+
+**Surface-Sync** is the item-level complement. For each configured surface
+(commands, validators, slash commands, templates — anything enumerable), it
+compares code-truth (from a glob) against the names appearing in table rows
+and bullet items in target docs. Warns on items present in code but missing
+from the doc, and on items listed in the doc but missing from code.
+
+Key behaviors:
+
+- **N/A by default.** Returns "nothing to validate" unless the project's
+  `.docguard.json` declares at least one surface under `surfaceSync.surfaces`.
+  Existing docguard projects upgrade safely with zero new noise.
+- **Section-scoped scanning.** Each surface can specify a `section` heading;
+  the validator restricts scanning to that section so a README containing
+  both a Commands table and a Validators table doesn't produce cross-table
+  false positives.
+- **Format-aware extraction.** Recognises documented entries written as
+  `` `name` ``, `**Name**`, `| `name` |`, `| N | **Name** |`, and bullet
+  items. Strips leading `docguard ` / `/` prefixes and folds case so README's
+  `**API-Surface**` matches file basename `api-surface.mjs`.
+- **Code-block immune.** Fenced code blocks are stripped before scanning so
+  shell examples don't inflate the documented set.
+- **`ignore` list per surface.** Known deprecation aliases, scaffolders
+  behind `init --with`, and display-name-vs-filename mismatches can be
+  silenced without disabling the surface entirely.
+
+Config shape (in `.docguard.json`):
+
+```json
+{
+  "surfaceSync": {
+    "surfaces": [
+      {
+        "name": "commands",
+        "glob": "cli/commands/*.mjs",
+        "extract": "basename-no-ext",
+        "ignore": ["setup", "impact"],
+        "docs": ["README.md"],
+        "section": "Usage"
+      }
+    ]
+  }
+}
+```
+
+DocGuard's own `.docguard.json` now declares three surfaces (commands,
+validators, slash-commands) so the project polices its own README on every
+`guard` run. Run `docguard explain surfaceSync` for fix guidance.
+
+### Fixed — eight field-test bugs from v0.20.0
+
+Confirmed running v0.20.0 against two real projects (a Python codebase for
+the v0.20.0 cycle and a Next.js 15 App Router codebase). All eight were
+reproduced in the source, fixed surgically, and pinned with regression
+tests. Specs: `specs/004-v020-env-var-false-negative/`, `specs/005-hugocross-next-bugs/`.
+
+- **API-Surface emits wrong path for Next.js App Router with `src/` layout**
+  — `src/app/api/health/route.ts` was reported as `GET /app/api/health`
+  instead of `GET /api/health`. Caused the validator to fire two false
+  warnings per route (documented-missing + undocumented-in-code) on every
+  `src/app/api/` file. `cli/scanners/routes.mjs`.
+
+- **Freshness validator ignored `<!-- docguard:last-reviewed YYYY-MM-DD -->`**
+  — header was generated into every template, recommended in the freshness
+  fix text itself, checked by `score` for ALCOA+, but never read by
+  `validateFreshness`. The reviewer's explicit "I reviewed this" signal
+  had zero effect. The header now overrides the git-log fallback.
+  `cli/validators/freshness.mjs`.
+
+- **Environment-vars in pipe-table rows (no backticks) were treated as
+  undocumented** — projects using `| VAR_NAME | description | required |`
+  table syntax were silently flagged for every var. The doc parser only
+  matched backtick-quoted names; it now also extracts the first column of
+  markdown pipe-table rows. `cli/validators/environment.mjs`.
+
+- **Docs-Diff warning was unactionable** — emitted `"N documented but not
+  found in code"` with no filename. Now lists up to 5 paths inline with
+  `(+N more)` for the long-tail. `cli/validators/docs-diff.mjs`.
+
+- **Traceability ignored `// @doc` annotations AND missed Next.js App
+  Router paths** — templates told users `// @doc API-REFERENCE.md` would
+  link a source file to a canonical doc; the scanner never read the
+  annotation. Compound: the `API-REFERENCE.md` TRACE_MAP only matched
+  `routes/`, `controllers/`, `handlers/`, `openapi/swagger`, and
+  `middleware/` — none of which cover `app/api/`. Added an annotation
+  scanner (top-of-file, multi-language comment syntax) and an
+  `(app|pages)/api/` glob. `cli/validators/traceability.mjs`.
+
+- **`docguard upgrade --apply` silently broke Metrics-Consistency** — when
+  a CLI upgrade added or removed validators, the project's hardcoded "N
+  validators" counts in markdown went stale and the very next
+  `docguard guard` failed Metrics-Consistency. The user did nothing wrong.
+  `upgrade --apply` now prints an explicit nudge to run `fix --write`
+  using the just-installed binary (the current process holds the OLD CLI's
+  validator list, so it cannot apply the fix itself). `cli/commands/upgrade.mjs`.
+
+- **Python env-vars were never scanned at all** — `grepEnvUsage` walked
+  `.py` files but the regex list was JS-only (`process.env.*`,
+  `import.meta.env.*`). Every documented Python env var read as "in docs,
+  not in code". Added patterns for `os.environ["X"]`, `os.environ.get("X")`,
+  and `os.getenv("X")`. The `explain` command's claim that Python was
+  supported now actually holds. `cli/shared-source.mjs`.
+
+- **`docguard memory` "Accuracy" overlapped `docguard score` "Accuracy"
+  with different denominators** — same word, same project, wildly different
+  numbers. Renamed the per-claim metric in `memory` to **"Claim match
+  rate"** (matched claims / total claims) so it no longer collides with
+  the score's weighted accuracy axis across all signals. JSON field name
+  unchanged for backward compatibility. `cli/commands/memory.mjs`.
+
 ## [0.21.1] - 2026-05-26
 
 **Security patch — closes issue #190.** Command injection vulnerability in