docguard-cli 0.21.1 → 0.22.0

package/README.md

@@ -3,7 +3,9 @@
 > **The enforcement layer for Spec-Driven Development.**
 > Validate. Score. Enforce. Ship documentation that AI agents can actually use.
 
+[![CI](https://github.com/raccioly/docguard/actions/workflows/ci.yml/badge.svg)](https://github.com/raccioly/docguard/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/docguard-cli)](https://www.npmjs.com/package/docguard-cli)
+[![npm downloads](https://img.shields.io/npm/dw/docguard-cli)](https://www.npmjs.com/package/docguard-cli)
 [![PyPI](https://img.shields.io/pypi/v/docguard-cli)](https://pypi.org/project/docguard-cli/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js](https://img.shields.io/badge/Node.js-18%2B-green)](https://nodejs.org)
@@ -18,6 +20,8 @@
 > ```
 > Runs against a baked-in sample project with intentional drift and shows you the findings + a clear path to fixing them.
 
+![DocGuard demo](assets/demo.gif)
+
 ---
 
 ## Table of Contents
@@ -67,7 +71,7 @@ graph TD
     Commands --> setup["setup wizard"]
     Commands --> other["diff · init · fix · trace · impact · sync<br/>explain · memory · upgrade · agents · hooks · badge · ci · watch"]
 
-    guard --> Validators["Validators (23)"]
+    guard --> Validators["Validators (24)"]
     generate --> Scanners["Scanners (4)<br/>routes · schemas · doc-tools · speckit"]
     score --> Scoring["Weighted Scoring<br/>8 categories"]
     diagnose --> Validators
@@ -95,7 +99,7 @@ graph TD
 Recent highlights across the v0.16 → v0.19 line:
 
 - **`docguard explain <validator>`** — `docguard explain freshness` prints purpose, rules, common
-  failures, and fix recipes for any of the 23 validators. No need to dig into source.
+  failures, and fix recipes for any of the 24 validators. No need to dig into source.
 - **`docguard memory --diff`** — surface what changed in your canonical docs between two refs
   (`HEAD~10..HEAD` by default). Great for code review and changelog drafting.
 - **`docguard score --diff`** — see exactly which validators moved the score up or down between
@@ -237,7 +241,7 @@ DocGuard is a [community extension](https://github.com/github/spec-kit/blob/main
 specify extension add docguard
 ```
 
-This installs DocGuard's slash commands (`/docguard.guard`, `/docguard.review`, `/docguard.fix`, `/docguard.score`) into your AI agent's command palette.
+This installs DocGuard's slash commands (`/docguard.init`, `/docguard.guard`, `/docguard.review`, `/docguard.fix`, `/docguard.update`) into your AI agent's command palette.
 
 ---
 
@@ -250,7 +254,7 @@ DocGuard ships **14 commands** (the "Daily 5" + 9 situational tools, including t
 | Command | What It Does |
 |:--------|:-------------|
 | `init`  | Bootstrap a project (`--wizard` for interactive · `--with <name>` for scaffolders) |
-| `guard` | Validate against canonical docs — 23 validators |
+| `guard` | Validate against canonical docs — 24 validators |
 | `diff`  | Show gaps between docs and code (`--since <ref>` for impact mode) |
 | `sync`  | Refresh code-truth doc sections — keeps memory always up to date |
 | `score` | CDD maturity score (0-100; `--diff` for delta between refs) |
@@ -259,6 +263,7 @@ DocGuard ships **14 commands** (the "Daily 5" + 9 situational tools, including t
 
 | Command | Purpose |
 |:--------|:--------|
+| `demo` | Zero-install showcase — runs guard against a baked-in drifting fixture (`npx docguard-cli demo`) |
 | `diagnose` | AI orchestrator — guard → emit fix prompts in one command |
 | `fix` | Generate AI fix instructions for specific docs (`--doc <name> --format prompt`) |
 | `fix --write` | Apply deterministic fixes (no AI — version bumps, counts, anchors, sections) |
@@ -343,7 +348,7 @@ $ npx docguard-cli generate
 
 ## 🔍 Validators
 
-DocGuard runs **23 automated validators** on every `guard` check. Every one is **language-aware** as of v0.16 — patterns for Python (`test_*.py`), Rust (`tests/*.rs`), Go (`*_test.go`), Java (`*Test.java`), Ruby (`*_spec.rb`), PHP, and JS/TS all match.
+DocGuard runs **24 automated validators** on every `guard` check. Every one is **language-aware** as of v0.16 — patterns for Python (`test_*.py`), Rust (`tests/*.rs`), Go (`*_test.go`), Java (`*Test.java`), Ruby (`*_spec.rb`), PHP, and JS/TS all match.
 
 | # | Validator | What It Checks | Default |
 |:--|:----------|:--------------|:--------|
@@ -370,6 +375,7 @@ DocGuard runs **23 automated validators** on every `guard` check. Every one is *
 | 21 | **Generated-Staleness** | `source=code` sections match scanner output; `status: draft` doc age | ✅ On |
 | 22 | **Canonical-Sync** | DocGuard's own README count claims match code-truth (DocGuard repo only — N/A elsewhere) | ✅ On |
 | 23 | **Metrics-Consistency** | Hardcoded numbers match actual counts | ✅ On |
+| 24 | **Surface-Sync** | Item-level enumerable drift — names in doc tables/lists (commands, validators, etc.) match code-truth (opt-in via `surfaceSync.surfaces`; N/A unless configured) | ✅ On |
 
 **Per-validator controls** (in `.docguard.json`):
 ```json
@@ -437,10 +443,11 @@ DocGuard provides AI agent slash commands for integrated workflows. Installed au
 
 | Command | What It Does |
 |:--------|:-------------|
-| `/docguard.guard` | Run quality validation — check all 23 validators |
+| `/docguard.init` | Initialize Canonical-Driven Development in a new or existing project |
+| `/docguard.guard` | Run quality validation — check all 24 validators |
 | `/docguard.review` | Analyze doc quality and suggest improvements |
 | `/docguard.fix` | Generate targeted fix prompts for specific issues |
-| `/docguard.score` | Show CDD maturity score with category breakdown |
+| `/docguard.update` | Update canonical docs after code changes — detect drift and sync documentation |
 
 These commands are installed into your AI agent's command directory:
 
@@ -657,6 +664,12 @@ See [CONTRIBUTING.md](CONTRIBUTING.md#research--academic-credits) for full citat
 
 ---
 
+## ⭐ Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=raccioly/docguard&type=Date)](https://star-history.com/#raccioly/docguard&Date)
+
+---
+
 ## 📄 License
 
 [MIT](LICENSE) — Free to use, modify, and distribute.

package/cli/commands/explain.mjs

@@ -150,6 +150,17 @@ const EXPLAINERS = {
     example: 'AGENTS.md says "22 validators" and `docguard guard` shows 22 active validators',
     standard: 'CDD principle: documented metrics match reality',
   },
+  surfaceSync: {
+    title: 'Surface-Sync — every code-derived list entry is documented',
+    what: 'Item-level check (complementing canonical-sync\'s count-level check). For each configured surface (e.g. commands → `cli/commands/*.mjs`), compares the discovered files against the names appearing in table rows / bullet lists in target docs (README.md, AGENTS.md). Warns when a code item is missing from the doc, or a doc item is missing from code.',
+    why:  'Counts can match while lists drift — README claimed "14 commands" while the table only listed 13 (demo was missing). Count validators celebrated; users hit "command not found" anyway. This check catches that case.',
+    triggers: [
+      ['Surface "X" drift: N in code but missing from README.md', 'Add the missing items to the relevant table / bullet list in the target doc. Or, if intentional (deprecation alias, scaffolder behind --with), add the names to the surface\'s `ignore` list in .docguard.json.'],
+      ['Surface "X" drift: N listed in README.md but not found in code', 'A documented item no longer exists in code. Either remove it from the doc (it was deleted) or restore the file/command (it was deleted by mistake).'],
+    ],
+    example: '`cli/commands/demo.mjs` exists and `| `demo` | Zero-install preview |` appears in README.md\'s commands table',
+    standard: 'CDD principle: documented surfaces match implemented surfaces',
+  },
   crossReference: {
     title: 'Cross-Reference — internal markdown links resolve',
     what: 'Scans canonical docs for `[text](./OTHER.md#anchor)` and `#anchor` links. Verifies the target file exists and the anchor matches a heading.',

package/cli/commands/guard.mjs

@@ -141,6 +141,7 @@ import { validateTodoTracking } from '../validators/todo-tracking.mjs';
 import { validateSchemaSync } from '../validators/schema-sync.mjs';
 import { validateSpecKitIntegration } from '../validators/spec-kit.mjs';
 import { validateCanonicalSync } from '../validators/canonical-sync.mjs';
+import { validateSurfaceSync } from '../validators/surface-sync.mjs';
 
 /**
  * Internal guard — returns structured data, no console output, no process.exit.
@@ -215,6 +216,7 @@ export function runGuardInternal(projectDir, config) {
     { key: 'specKit', name: 'Spec-Kit', fn: () => validateSpecKitIntegration(projectDir, config) },
     { key: 'crossReference', name: 'Cross-Reference', fn: () => validateCrossReferences(projectDir, config) },
     { key: 'generatedStaleness', name: 'Generated-Staleness', fn: () => validateGeneratedStaleness(projectDir, config) },
+    { key: 'surfaceSync', name: 'Surface-Sync', fn: () => validateSurfaceSync(projectDir, config) },
     // Metrics-Consistency runs post-loop (needs guard results)
   ];
 

package/cli/commands/memory.mjs

@@ -84,8 +84,18 @@ export function runMemory(projectDir, config, flags) {
   // ── Text output ──
   console.log(`${c.bold}🧠 DocGuard Memory${c.reset} ${c.dim}— ${config.projectName}${c.reset}\n`);
 
+  // Label is `Claim match rate` (not `Accuracy`) to disambiguate from the
+  // score-level `Accuracy` metric in `docguard score`, which is a weighted
+  // average across the entire accuracy axis (apiSurface, environment, drift,
+  // metadata-sync, etc.) and uses a different denominator. Both numbers are
+  // legitimate, but the same word was pointing at two different calculations
+  // — users saw "Accuracy 0%" here and "Accuracy 93%" in `score` on the same
+  // project and reasonably read it as a contradiction. This metric is the
+  // strict per-claim ratio (matched claims / total checked claims, restricted
+  // to domains that actually have any claims).
   const accColor = overallAccuracy >= 90 ? c.green : overallAccuracy >= 70 ? c.yellow : c.red;
-  console.log(`  ${c.bold}Accuracy:${c.reset} ${accColor}${overallAccuracy}%${c.reset} ${c.dim}(${totalMatched}/${totalChecks} doc claims match code)${c.reset}\n`);
+  console.log(`  ${c.bold}Claim match rate:${c.reset} ${accColor}${overallAccuracy}%${c.reset} ${c.dim}(${totalMatched}/${totalChecks} doc claims match code)${c.reset}`);
+  console.log(`  ${c.dim}   ↳ See ${c.cyan}docguard score${c.dim} for the weighted accuracy axis across all domains.${c.reset}\n`);
 
   if (totalChecks === 0) {
     console.log(`  ${c.dim}No applicable domains found — add canonical docs (API-REFERENCE.md, DATA-MODEL.md, ENVIRONMENT.md) and rerun.${c.reset}`);

package/cli/commands/upgrade.mjs

@@ -274,6 +274,18 @@ export async function runUpgrade(projectDir, _config, flags) {
         process.exit(1);
       }
       console.log(`  ${c.green}✓ CLI upgraded.${c.reset}`);
+      // Validator-count drift: a CLI upgrade often adds or removes validators,
+      // which changes the "N validators" / "N checks" totals that Metrics-
+      // Consistency scans for in markdown. Without a clear nudge here, a
+      // previously-green project goes red on the very next `docguard guard`
+      // for a reason the user did not cause. The fix is mechanical (replace
+      // hardcoded counts via fix --write) but the user has to know to run it.
+      // We don't auto-run fix --write from this process — the just-installed
+      // binary has the new validator list, but THIS process is still the OLD
+      // binary, so running fix here would use stale counts.
+      console.log(`  ${c.yellow}ℹ  Validator/check totals may have shifted with this upgrade.${c.reset}`);
+      console.log(`     Run ${c.cyan}docguard fix --write${c.reset} ${c.dim}to refresh hardcoded counts in your docs${c.reset}`);
+      console.log(`     ${c.dim}(picks up the new totals from the just-installed CLI).${c.reset}`);
     }
 
     if (schemaBehind && projectSchema) {

package/cli/docguard.mjs

@@ -230,7 +230,7 @@ const _KNOWN_VALIDATORS = [
   'security', 'architecture', 'freshness', 'traceability', 'docsDiff',
   'apiSurface', 'metadataSync', 'docsCoverage', 'docQuality', 'todoTracking',
   'schemaSync', 'specKit', 'crossReference', 'generatedStaleness',
-  'metricsConsistency',
+  'canonicalSync', 'surfaceSync', 'metricsConsistency',
 ];
 
 function _kebabToCamel(k) {

package/cli/scanners/routes.mjs

@@ -108,8 +108,14 @@ function scanNextJsRoutes(dir) {
       const content = readFileSafe(filePath);
       if (!content) return;
 
-      // Path from directory structure
-      const relDir = relative(resolve(dir, appDir.split('/')[0]), dirname(filePath));
+      // Path from directory structure. The HTTP base in Next.js App Router is
+      // `/api/...` — Next strips everything up to and including the `app/`
+      // segment. Compute the relative path from the directory ABOVE `api/`
+      // so both `app/api` (no src layout) and `src/app/api` (src layout)
+      // produce `/api/<segments>`. Previously `appDir.split('/')[0]` stripped
+      // only `src/` for the src layout, leaking `app/` into the emitted path.
+      const apiBase = appDir.slice(0, appDir.lastIndexOf('/'));
+      const relDir = relative(resolve(dir, apiBase), dirname(filePath));
       const apiPath = '/' + relDir
         .replace(/\\/g, '/')
         .replace(/\[\.\.\.(\w+)\]/g, ':$1*')  // Catch-all [...slug]

package/cli/shared-source.mjs

@@ -217,6 +217,15 @@ export function grepEnvUsage(projectDir, config = {}) {
     new RegExp(`process\\.env\\.${NAME}`, 'g'),
     new RegExp(`process\\.env\\[\\s*['"]${NAME}['"]\\s*\\]`, 'g'),
     new RegExp(`import\\.meta\\.env\\.${NAME}`, 'g'),
+    // Python: `os.environ["X"]`, `os.environ.get("X")`, `os.getenv("X")`. The
+    // `explain` command and ENVIRONMENT.md templates have always told users
+    // these forms are scanned, but the implementation only handled JS. On a
+    // Python project this caused every documented env var to be reported as
+    // "in docs, not in code" — a silent 0% accuracy. Patterns cover bracket
+    // access, .get(), and the standalone os.getenv() function.
+    new RegExp(`os\\.environ\\[\\s*['"]${NAME}['"]\\s*\\]`, 'g'),
+    new RegExp(`os\\.environ\\.get\\s*\\(\\s*['"]${NAME}['"]`, 'g'),
+    new RegExp(`os\\.getenv\\s*\\(\\s*['"]${NAME}['"]`, 'g'),
   ];
   // Vite injects these at build time; they are not user-set env vars.
   const VITE_INTRINSICS = new Set(['DEV', 'PROD', 'MODE', 'BASE_URL', 'SSR']);

package/cli/validators/docs-diff.mjs

@@ -42,6 +42,17 @@ export function validateDocsDiff(projectDir, config) {
     diffTests(projectDir, config),
   ];
 
+  // Limit how many offending names are inlined in a single warning — keeps
+  // the line readable on terminals while still naming the specific files so
+  // the warning is actually actionable. Without these names the user gets a
+  // bare count ("1 documented but not found in code") with no path to debug.
+  const MAX_INLINE = 5;
+  const fmtList = (arr) => {
+    const shown = arr.slice(0, MAX_INLINE).map(v => `\`${v}\``).join(', ');
+    const extra = arr.length - MAX_INLINE;
+    return extra > 0 ? `${shown} (+${extra} more)` : shown;
+  };
+
   for (const result of checks) {
     if (!result) continue;
 
@@ -53,9 +64,13 @@ export function validateDocsDiff(projectDir, config) {
       passed++;
     } else {
       const parts = [];
-      if (undocumented > 0) parts.push(`${undocumented} in code but not documented`);
-      if (stale > 0) parts.push(`${stale} documented but not found in code`);
-      warnings.push(`${result.title} drift: ${parts.join(', ')}`);
+      if (undocumented > 0) {
+        parts.push(`${undocumented} in code but not documented: ${fmtList(result.onlyInCode)}`);
+      }
+      if (stale > 0) {
+        parts.push(`${stale} documented but not found in code: ${fmtList(result.onlyInDocs)}`);
+      }
+      warnings.push(`${result.title} drift: ${parts.join('; ')}`);
     }
   }
 

package/cli/validators/environment.mjs

@@ -64,6 +64,19 @@ export function validateEnvironment(projectDir, config) {
       if (SYSTEM.has(m[1])) continue; // v0.16-P4: prose mentions of system vars are not docs
       documented.add(m[1]);
     }
+    // Also extract markdown table rows where the first column is a bare env
+    // var name (no backticks). Real-world ENVIRONMENT.md docs frequently use
+    // pipe tables with un-backticked names — the backtick-only regex above
+    // silently misses every suffixed variant (DYNAMODB_TABLE_JOBS,
+    // DYNAMODB_TABLE_SOURCES, …) and they get reported as undocumented.
+    // Match `| VAR_NAME |` anywhere on the line; require the row to also
+    // contain a second `|` (real table row), not a stray pipe in prose.
+    const tableRe = /^\s*\|\s*([A-Z][A-Z0-9_]*[A-Z0-9])\s*\|/gm;
+    while ((m = tableRe.exec(content)) !== null) {
+      if (m[1].length < 3) continue;
+      if (SYSTEM.has(m[1])) continue;
+      documented.add(m[1]);
+    }
     for (const envFile of ['.env.example', '.env.template']) {
       const p = resolve(projectDir, envFile);
       if (!existsSync(p)) continue;

package/cli/validators/freshness.mjs

@@ -6,7 +6,7 @@
  * but the code has already been implemented and committed.
  */
 
-import { existsSync, readdirSync, statSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { resolve, join, extname } from 'node:path';
 import { execSync, execFileSync } from 'node:child_process';
 
@@ -34,6 +34,26 @@ const IGNORE_DIRS = new Set([
   'templates', 'configs', 'Research',
 ]);
 
+/**
+ * Read the `<!-- docguard:last-reviewed YYYY-MM-DD -->` header from a doc file.
+ * Returns the parsed Date when present, null otherwise (file missing, header
+ * absent, or date unparseable). The header is the authoritative review date
+ * — it represents an explicit human review action that `git log` cannot see
+ * (e.g., the reviewer read the file, confirmed it still matches reality, and
+ * stamped the header without touching content, so there is no commit to find).
+ */
+function readLastReviewedDate(absPath) {
+  try {
+    const content = readFileSync(absPath, 'utf-8');
+    const m = content.match(/<!--\s*docguard:last-reviewed\s+(\d{4}-\d{2}-\d{2})\s*-->/);
+    if (!m) return null;
+    const d = new Date(m[1] + 'T00:00:00Z');
+    return isNaN(d.getTime()) ? null : d;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Get the last git commit date for a file.
  * Returns null if the file isn't tracked or git isn't available.
@@ -170,7 +190,15 @@ export function validateFreshness(dir, config) {
     const docPath = resolve(dir, docFile);
     if (!existsSync(docPath)) continue;
 
-    const docDate = getLastGitDate(docFile, dir);
+    // Prefer the explicit `<!-- docguard:last-reviewed YYYY-MM-DD -->` header
+    // over the git commit date. A reviewer who reads a doc and stamps the
+    // header without changing content has signaled "I confirmed this is still
+    // current" — git log cannot see that signal, so it would falsely flag the
+    // doc as stale despite the explicit review. Fall back to git log only when
+    // the header is absent. Symmetric with the ALCOA+ "review metadata present"
+    // check in score.mjs, which reads the same header.
+    const reviewedDate = readLastReviewedDate(docPath);
+    const docDate = reviewedDate || getLastGitDate(docFile, dir);
     if (!docDate) {
       // File exists but isn't tracked in git yet
       results.push({
@@ -212,7 +240,9 @@ export function validateFreshness(dir, config) {
   // ── 2. Check CHANGELOG.md was updated in the last 5 code commits ──
   const changelogPath = resolve(dir, config.requiredFiles?.changelog || 'CHANGELOG.md');
   if (existsSync(changelogPath)) {
-    const changelogDate = getLastGitDate(config.requiredFiles?.changelog || 'CHANGELOG.md', dir);
+    const changelogDate =
+      readLastReviewedDate(changelogPath) ||
+      getLastGitDate(config.requiredFiles?.changelog || 'CHANGELOG.md', dir);
     if (changelogDate && latestCodeDate) {
       const daysDiff = Math.floor((latestCodeDate - changelogDate) / (1000 * 60 * 60 * 24));
       if (daysDiff > 7) {

package/cli/validators/surface-sync.mjs

@@ -0,0 +1,365 @@
+/**
+ * Surface-Sync Validator — item-level drift detection for enumerable surfaces.
+ *
+ * Complements canonical-sync (which checks NUMERIC count claims) by checking
+ * that each individual ITEM in a code-derived list is actually documented as
+ * a list entry in the target markdown file(s). Catches the "demo command
+ * exists in code, the count matches, but it's missing from the README's
+ * command table" class of drift — invisible to count-based checks.
+ *
+ * Why this exists: canonical-sync was passing 3/3 on a docguard repo whose
+ * README's command table omitted `demo` entirely. The count matched ("14
+ * commands" = 14 user-facing commands in --help) but the table only listed
+ * 13 of them. Without an item-level check, a doc can be silently wrong while
+ * every count-based validator celebrates. That's exactly the credibility hit
+ * the user reported.
+ *
+ * How it works: for each configured surface (commands, validators, slash
+ * commands, templates, anything enumerable), we:
+ *   1. Discover the code-truth set from a glob pattern + basename extractor
+ *   2. For each target doc, parse all markdown tables and bullet lists,
+ *      collecting backticked tokens that look like identifiers from the
+ *      FIRST column / item position only (not arbitrary prose mentions)
+ *   3. Diff the two sets and warn on items present in code but absent from
+ *      the doc, OR present in the doc but missing from code (likely
+ *      removed / renamed)
+ *
+ * Scoped to list contexts on purpose: scanning every backtick would produce
+ * false positives every time someone wrote `--verbose` or `process.env.X`
+ * in prose. A table row or bullet item is a deliberate inventory signal —
+ * docguard treats those as the doc's authoritative list, ignores the rest.
+ *
+ * Default: N/A. The validator is OFF unless the project's .docguard.json
+ * declares at least one surface under `validators.surfaceSync.surfaces`.
+ * This keeps the upgrade path safe for projects that don't opt in.
+ *
+ * Config shape (in .docguard.json):
+ *   {
+ *     "validators": { "surfaceSync": true },
+ *     "surfaceSync": {
+ *       "surfaces": [
+ *         {
+ *           "name": "commands",
+ *           "glob": "cli/commands/*.mjs",
+ *           "extract": "basename-no-ext",  // "basename" or "basename-no-ext"
+ *           "ignore": ["setup", "impact"],  // known aliases / non-public items
+ *           "docs": ["README.md"]
+ *         }
+ *       ]
+ *     }
+ *   }
+ *
+ * Severity: MEDIUM. Wrong-list drift is real but rarely a build-breaker —
+ * users can still read the doc and discover the missing surface via --help.
+ * Demoting to LOW makes drift invisible; promoting to HIGH would conflict
+ * with the existing reality that many projects ship slightly-stale READMEs.
+ *
+ * Zero NPM runtime dependencies — pure Node.js built-ins only.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { resolve, join, basename, extname, relative, dirname } from 'node:path';
+
+/**
+ * Expand a simple glob (only supports `*` at the leaf segment level —
+ * sufficient for `cli/commands/*.mjs`, `templates/*.md.template`, etc.).
+ * Recursive `**` is NOT supported by design — surface lists live in
+ * known shallow directories; deep recursion would be a configuration
+ * smell, not a feature.
+ */
+function expandGlob(projectDir, glob) {
+  const slash = glob.lastIndexOf('/');
+  const dir = slash >= 0 ? glob.slice(0, slash) : '.';
+  const pattern = slash >= 0 ? glob.slice(slash + 1) : glob;
+  const absDir = resolve(projectDir, dir);
+  if (!existsSync(absDir)) return [];
+
+  // Convert glob to regex: escape regex specials, then `*` → `.*`
+  const rx = new RegExp('^' + pattern
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*/g, '.*') + '$');
+
+  try {
+    return readdirSync(absDir)
+      .filter(name => rx.test(name))
+      .map(name => join(absDir, name))
+      .filter(full => {
+        try { return statSync(full).isFile(); } catch { return false; }
+      });
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Extract the surface name from a file path according to the configured rule.
+ * `basename`        → keep the full filename: `guard.mjs`
+ * `basename-no-ext` → strip the single trailing extension: `guard`
+ *
+ * `basename-no-ext` strips ONLY the last extension on purpose. For files like
+ * `ARCHITECTURE.md.template`, `basename-no-ext` returns `ARCHITECTURE.md` —
+ * which is the canonical doc name the template generates. If the user wants
+ * the bare `ARCHITECTURE`, they can use a custom extractor (not yet supported).
+ */
+function applyExtractor(filePath, extractor) {
+  const base = basename(filePath);
+  if (extractor === 'basename') return base;
+  if (extractor === 'basename-no-ext') {
+    const ext = extname(base);
+    return ext ? base.slice(0, -ext.length) : base;
+  }
+  // Unknown extractor → fall back to bare basename. Don't throw — a future
+  // CLI version might introduce more extractors, and we want old configs to
+  // degrade gracefully rather than crash a guard run.
+  return base;
+}
+
+/**
+ * Slice a markdown document down to a single section, identified by a heading
+ * substring match (case-insensitive). The slice runs from that heading to the
+ * next heading of equal or higher level (so a `##` section ends at the next
+ * `##` or `#`, but `###` subsections are included).
+ *
+ * Returns the original `content` if `heading` is falsy. Returns an empty string
+ * if the heading isn't found — callers treat that as "section absent, no
+ * documented tokens here," which surfaces as a "missing-from-doc" warning for
+ * every code item (correctly: the section the user said to scope to does not
+ * exist in this doc).
+ */
+function sliceSection(content, heading) {
+  if (!heading) return content;
+  const lines = content.split('\n');
+  const needle = String(heading).toLowerCase().replace(/^#+\s*/, '').trim();
+  if (!needle) return content;
+
+  // Find the start: any heading line whose text (after stripping `#`s) contains
+  // the configured heading. Substring match keeps the config tolerant of
+  // emoji prefixes and trailing decorations in the actual document.
+  let startIdx = -1;
+  let startLevel = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^(#{1,6})\s+(.+?)\s*$/);
+    if (!m) continue;
+    const headingText = m[2].toLowerCase();
+    if (headingText.includes(needle)) {
+      startIdx = i;
+      startLevel = m[1].length;
+      break;
+    }
+  }
+  if (startIdx === -1) return '';
+
+  // Find the end: next heading of <= startLevel depth.
+  let endIdx = lines.length;
+  for (let i = startIdx + 1; i < lines.length; i++) {
+    const m = lines[i].match(/^(#{1,6})\s+/);
+    if (m && m[1].length <= startLevel) {
+      endIdx = i;
+      break;
+    }
+  }
+  return lines.slice(startIdx, endIdx).join('\n');
+}
+
+/**
+ * Parse a markdown file (or a slice of one) and return the set of tokens
+ * found in "list contexts" — table rows (first column) and bullet items.
+ * Backtick-wrapped only. This deliberately ignores backticks in prose,
+ * code blocks, and headings.
+ *
+ * Code blocks (```...```) are stripped first so that a fenced shell example
+ * like `npx docguard-cli demo` cannot inflate the documented set with the
+ * `demo` token. Tables and bullets remain the only authoritative inventory.
+ */
+function extractDocumentedTokens(content) {
+  const tokens = new Set();
+  // Strip fenced code blocks — shell examples, json snippets, mermaid blocks,
+  // and any inline reference inside them is NOT a list entry.
+  const stripped = content.replace(/```[\s\S]*?```/g, '');
+
+  // Normalize a captured token. Strips a leading `docguard ` or `/` (common
+  // doc conventions for command tables and slash-command lists), reduces
+  // multi-word forms to the first token, and lower-cases — downstream
+  // comparison is case-insensitive so README's `**API-Surface**` matches
+  // code-truth `api-surface`.
+  const normalize = (raw) => {
+    if (!raw) return '';
+    const cleaned = String(raw).trim()
+      .replace(/^docguard\s+/i, '')
+      .replace(/^\//, '');
+    const firstToken = cleaned.split(/\s+/)[0];
+    return firstToken.toLowerCase();
+  };
+
+  // Pattern A: backticked token in a list context.
+  //   - Start of a table row:                 `| `name` | … |`
+  //   - Numbered-cell table row:              `| 1 | `name` | … |`
+  //   - Bullet list item:                     `- `name` …`
+  // Restricting to these contexts keeps prose backticks out of the
+  // documented set; a backticked `--verbose` mid-paragraph is not a list
+  // entry and must not inflate the set.
+  const backtickListRe =
+    /(?:^\s*\|\s*(?:\d+\s*\|\s*)?|^\s*[-*+]\s+)`([^`\n]+)`/gim;
+  let m;
+  while ((m = backtickListRe.exec(stripped)) !== null) {
+    const t = normalize(m[1]);
+    if (t) tokens.add(t);
+  }
+
+  // Pattern B: bolded token in a table row. Matches the validators-style
+  // tables that use `| N | **Name** | description |` — backticks alone
+  // miss every entry in those tables. Restricted to lines starting with
+  // `|` so prose-level **bold** is not pulled in.
+  const boldRowRe = /^\s*\|.*?\*\*([^*\n]+)\*\*/gim;
+  while ((m = boldRowRe.exec(stripped)) !== null) {
+    const t = normalize(m[1]);
+    if (t) tokens.add(t);
+  }
+
+  return tokens;
+}
+
+/**
+ * Validate surface drift for a single surface against its target docs.
+ * Returns warnings, fixes, passed count, and total count.
+ */
+function checkSurface(projectDir, surface) {
+  const out = { warnings: [], fixes: [], passed: 0, total: 0 };
+  const name = surface.name || 'unnamed';
+  const extractor = surface.extract || 'basename-no-ext';
+  const ignore = new Set(surface.ignore || []);
+  const docs = Array.isArray(surface.docs) && surface.docs.length > 0
+    ? surface.docs
+    : ['README.md'];
+
+  // Discover code-truth set from glob.
+  if (!surface.glob || typeof surface.glob !== 'string') {
+    out.warnings.push(
+      `surfaceSync: surface "${name}" has no \`glob\` — skipping. Add a glob like "cli/commands/*.mjs".`
+    );
+    return out;
+  }
+  const files = expandGlob(projectDir, surface.glob);
+  // Lower-case code-truth to keep comparison case-insensitive — README
+  // commonly uses display-cased identifiers (`**API-Surface**`, `Freshness`)
+  // while file basenames are lowercase (`api-surface.mjs`). The `ignore`
+  // list is matched against the case-folded form, so users can write
+  // either `["Setup"]` or `["setup"]` and it works.
+  const ignoreLower = new Set([...ignore].map(s => String(s).toLowerCase()));
+  const codeTruth = new Set(
+    files
+      .map(f => applyExtractor(f, extractor).toLowerCase())
+      .filter(token => !ignoreLower.has(token))
+  );
+  if (codeTruth.size === 0) {
+    // No items discovered — surface is N/A for this project. Don't warn
+    // (the user has explicitly enabled the surface, but the glob found
+    // nothing — maybe they renamed a directory; surface up the info but
+    // do NOT escalate into a check failure).
+    return out;
+  }
+
+  // For each target doc, compute documented set and diff.
+  for (const docRel of docs) {
+    const docPath = resolve(projectDir, docRel);
+    if (!existsSync(docPath)) {
+      // Doc doesn't exist — silently skip; another validator (structure)
+      // covers missing-doc cases.
+      continue;
+    }
+
+    let content;
+    try {
+      content = readFileSync(docPath, 'utf-8');
+    } catch {
+      continue;
+    }
+
+    // Optional section scope: restrict scanning to a single heading's body.
+    // Without this, every backticked first-column token in the doc is
+    // pooled into one "documented" set — and a commands surface ends up
+    // matching against the validators table too, producing cross-table
+    // false positives. Section-scoping is the user's per-surface override
+    // when one doc lists multiple surfaces.
+    const scope = surface.section
+      ? sliceSection(content, surface.section)
+      : content;
+
+    const documented = extractDocumentedTokens(scope);
+    out.total++;
+
+    const missingFromDoc = [...codeTruth].filter(t => !documented.has(t));
+    // missingFromCode tells you about items the doc lists that don't exist
+    // in code — usually removed or renamed surfaces. Filter through `ignore`
+    // too so deprecation aliases listed in the doc don't fire warnings.
+    const missingFromCode = [...documented]
+      .filter(t => !codeTruth.has(t) && !ignoreLower.has(t))
+      // Only consider tokens that match the surface naming convention to
+      // avoid pulling in unrelated backticked items from a different table
+      // that happens to be in the same doc.
+      .filter(t => surfaceNameLooksValid(t));
+
+    if (missingFromDoc.length === 0 && missingFromCode.length === 0) {
+      out.passed++;
+      continue;
+    }
+
+    const parts = [];
+    if (missingFromDoc.length > 0) {
+      const shown = missingFromDoc.slice(0, 8).map(t => `\`${t}\``).join(', ');
+      const extra = missingFromDoc.length - 8;
+      const tail = extra > 0 ? ` (+${extra} more)` : '';
+      parts.push(`${missingFromDoc.length} in code but missing from ${docRel}: ${shown}${tail}`);
+    }
+    if (missingFromCode.length > 0) {
+      const shown = missingFromCode.slice(0, 8).map(t => `\`${t}\``).join(', ');
+      const extra = missingFromCode.length - 8;
+      const tail = extra > 0 ? ` (+${extra} more)` : '';
+      parts.push(`${missingFromCode.length} listed in ${docRel} but not found in code: ${shown}${tail}`);
+    }
+    out.warnings.push(`Surface "${name}" drift: ${parts.join('; ')}`);
+  }
+
+  return out;
+}
+
+/**
+ * Loose sanity filter for tokens before reporting them as "missing from code".
+ * Real surface names are short identifiers; if a regex catches something
+ * that looks like prose, drop it silently.
+ */
+function surfaceNameLooksValid(t) {
+  return typeof t === 'string'
+    && t.length >= 2
+    && t.length <= 64
+    && /^[a-z][a-z0-9_.-]*$/i.test(t);
+}
+
+/**
+ * Public entry point. Returns N/A when no surfaces are configured — by
+ * design, this validator is opt-in. Projects that don't declare surfaces
+ * see zero noise.
+ */
+export function validateSurfaceSync(projectDir, config) {
+  const surfaceCfg = (config && config.surfaceSync && Array.isArray(config.surfaceSync.surfaces))
+    ? config.surfaceSync.surfaces
+    : [];
+
+  const result = { errors: [], warnings: [], fixes: [], passed: 0, total: 0 };
+
+  if (surfaceCfg.length === 0) {
+    // No surfaces configured → N/A. The validator infrastructure surfaces
+    // this as "nothing to validate" rather than a fail.
+    return result;
+  }
+
+  for (const surface of surfaceCfg) {
+    const r = checkSurface(projectDir, surface);
+    result.warnings.push(...r.warnings);
+    result.fixes.push(...r.fixes);
+    result.passed += r.passed;
+    result.total += r.total;
+  }
+
+  return result;
+}

package/cli/validators/traceability.mjs

@@ -64,6 +64,10 @@ const TRACE_MAP = {
   'API-REFERENCE.md': {
     sourcePatterns: [
       { label: 'Route handlers', glob: /(routes?|controllers?|handlers?)\// },
+      // Next.js App Router (and Pages Router) — `app/api/`, `src/app/api/`,
+      // `pages/api/`, `src/pages/api/`. Without this, a perfectly-populated
+      // Next.js API tree gets reported as "API-REFERENCE.md — unlinked doc".
+      { label: 'Next.js API routes', glob: /(^|\/)(app|pages)\/api\// },
       { label: 'OpenAPI spec', glob: /(openapi|swagger)\.(json|ya?ml)/ },
       { label: 'API middleware', glob: /middleware\// },
     ],
@@ -115,6 +119,15 @@ export function validateTraceability(projectDir, config) {
   const projectFiles = [];
   scanDir(projectDir, projectDir, projectFiles);
 
+  // Scan source files for `// @doc <filename>.md` annotations. An annotation
+  // is an explicit author signal that a source file documents (or is
+  // documented by) a canonical doc. It is the user-facing escape hatch when
+  // a project's directory layout doesn't match the built-in TRACE_MAP globs
+  // (e.g. a route file outside any `routes/` / `app/api/` tree). The
+  // annotation is also shown in templates and templates/commands docs, so
+  // users have been told it works — actually honoring it is the fix here.
+  const docAnnotations = scanDocAnnotations(projectFiles, projectDir);
+
   // ── Part 1: Source Traceability (existing) ──
   for (const [docName, traceInfo] of Object.entries(TRACE_MAP)) {
     // Skip docs not in the user's required list
@@ -129,6 +142,14 @@ export function validateTraceability(projectDir, config) {
       continue;
     }
 
+    // Explicit `// @doc <docName>` annotation counts as a link regardless of
+    // whether the file path matches any built-in pattern. Checked first so
+    // path-pattern misses don't drown out explicit author intent.
+    if (docAnnotations.has(docName) && docAnnotations.get(docName).size > 0) {
+      passed++;
+      continue;
+    }
+
     // Count matching source files
     // ⚡ Bolt: Fast early return using .some() instead of .filter()
     let hasSource = false;
@@ -354,6 +375,50 @@ function getRequirementDocPaths(projectDir, config) {
 
 // ── Helpers ────────────────────────────────────────────────────────────────
 
+/**
+ * Scan code files for `// @doc <name>.md` annotations. Returns a Map from
+ * canonical doc basename → Set of source file paths that annotate it.
+ *
+ * Annotation forms accepted:
+ *   - `// @doc API-REFERENCE.md`
+ *   - `// @doc docs-canonical/API-REFERENCE.md`  (basename is what matters)
+ *   - `/* @doc API-REFERENCE.md *​/`              (block comment, single line)
+ *   - `# @doc API-REFERENCE.md`                  (Python / Ruby comment style)
+ *
+ * Only the basename of the referenced doc is keyed; callers compare against
+ * the doc basename (e.g. `API-REFERENCE.md`). We cap how many files we open
+ * to keep this scan O(N) and stop reading the rest of a file after the
+ * first 4 KB — annotations belong at the top of a file by convention, and
+ * reading every byte of every source file just to find a header comment
+ * would balloon scan time on large monorepos.
+ */
+function scanDocAnnotations(projectFiles, projectDir) {
+  const map = new Map();
+  const annotationRe = /(?:\/\/|\/\*|#)\s*@doc\s+(\S+\.md)/g;
+  const CODE_EXT = new Set(['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '.py', '.rb', '.go', '.rs', '.java']);
+  const HEAD_BYTES = 4096;
+
+  for (const relPath of projectFiles) {
+    const ext = extname(relPath);
+    if (!CODE_EXT.has(ext)) continue;
+    const full = resolve(projectDir, relPath);
+    let content;
+    try { content = readFileSync(full, 'utf-8'); } catch { continue; }
+    // Annotations live near the top of the file. Slicing avoids reading
+    // megabytes of bundled / minified output looking for a header comment.
+    const head = content.length > HEAD_BYTES ? content.slice(0, HEAD_BYTES) : content;
+    if (!head.includes('@doc')) continue;
+    annotationRe.lastIndex = 0;
+    let m;
+    while ((m = annotationRe.exec(head)) !== null) {
+      const docName = basename(m[1]);
+      if (!map.has(docName)) map.set(docName, new Set());
+      map.get(docName).add(relPath);
+    }
+  }
+  return map;
+}
+
 function scanDir(rootDir, dir, files) {
   let entries;
   try { entries = readdirSync(dir); } catch { return; }

package/docs/quickstart.md

@@ -68,7 +68,7 @@ diagnose  →  AI reads prompts  →  AI fixes docs  →  guard verifies
 ## Verify
 
 ```bash
-npx docguard-cli guard        # Pass/fail check (23 validators)
+npx docguard-cli guard        # Pass/fail check (24 validators)
 npx docguard-cli score        # 0-100 maturity score
 ```
 

package/extensions/spec-kit-docguard/README.md

@@ -4,7 +4,7 @@ Enterprise-grade Canonical-Driven Development (CDD) enforcement and **AI-readabl
 
 ## Features
 
-- **23 Validators** — Structure, Security, Doc Quality, Test-Spec, Drift-Comments, API-Surface, Freshness, Cross-Reference, and 13 more
+- **24 Validators** — Structure, Security, Doc Quality, Test-Spec, Drift-Comments, API-Surface, Freshness, Cross-Reference, and 13 more
 - **Language-agnostic** — JS/TS, Python, Rust, Go, Java/Kotlin, Ruby, PHP, C#. Polyglot/monorepo-aware.
 - **AI-powered Generate** — `generate --plan` builds the code-truth skeleton in `<!-- docguard:section -->` markers and emits a structured agent task manifest; the AI writes the prose.
 - **Always up to date** — `sync` surgically refreshes code-truth doc sections in place, **preserves human prose**, flags prose for agent review.

package/extensions/spec-kit-docguard/extension.yml

@@ -3,7 +3,7 @@ schema_version: "1.0"
 extension:
   id: "docguard"
   name: "DocGuard — CDD Enforcement"
-  version: "0.21.1"
+  version: "0.22.0"
   description: "Canonical-Driven Development enforcement as a true spec-kit extension. LLM-first design with 19 automated validators, 4 AI behavior skills, spec-kit skill chaining, and workflow hooks. Zero NPM runtime dependencies."
   author: "Ricardo Accioly"
   repository: "https://github.com/raccioly/docguard"

package/extensions/spec-kit-docguard/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.0
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.21.1 -->
+<!-- docguard:version: 0.22.0 -->
 
 # DocGuard Fix Skill
 

package/extensions/spec-kit-docguard/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.0
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.21.1 -->
+<!-- docguard:version: 0.22.0 -->
 
 # DocGuard Guard Skill
 

package/extensions/spec-kit-docguard/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.0
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.21.1 -->
+<!-- docguard:version: 0.22.0 -->
 
 # DocGuard Review Skill
 

package/extensions/spec-kit-docguard/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.0
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.21.1 -->
+<!-- docguard:version: 0.22.0 -->
 
 # DocGuard Score Skill
 

package/extensions/spec-kit-docguard/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.0
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docguard-cli",
-  "version": "0.21.1",
+  "version": "0.22.0",
   "description": "The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation.",
   "type": "module",
   "bin": {

package/schemas/docguard-config.schema.json

@@ -102,6 +102,8 @@
         "specKit":            { "type": "boolean" },
         "crossReference":    { "type": "boolean" },
         "generatedStaleness":{ "type": "boolean" },
+        "canonicalSync":     { "type": "boolean" },
+        "surfaceSync":       { "type": "boolean" },
         "metricsConsistency":{ "type": "boolean" }
       },
       "additionalProperties": false
@@ -149,6 +151,30 @@
         }
       },
       "additionalProperties": true
+    },
+    "surfaceSync": {
+      "type": "object",
+      "description": "Surface-Sync validator: item-level drift between code-derived enumerables (commands, validators, templates) and the lists in target docs (README.md, AGENTS.md). Default: N/A unless `surfaces` is declared.",
+      "properties": {
+        "surfaces": {
+          "type": "array",
+          "description": "Enumerable surfaces to check. Each surface compares code-truth (from a glob) against documented list entries in target markdown files.",
+          "items": {
+            "type": "object",
+            "properties": {
+              "name":    { "type": "string", "description": "Human-readable surface name used in warnings (e.g. \"commands\")." },
+              "glob":    { "type": "string", "description": "Glob discovering the code-truth files (e.g. `cli/commands/*.mjs`). Only leaf `*` supported." },
+              "extract": { "type": "string", "enum": ["basename", "basename-no-ext"], "description": "How to derive the surface name from each file path." },
+              "ignore":  { "type": "array", "items": { "type": "string" }, "description": "Surface names to skip (e.g. known deprecation aliases)." },
+              "docs":    { "type": "array", "items": { "type": "string" }, "description": "Target markdown files to scan for documented list entries." },
+              "section": { "type": "string", "description": "Optional heading text to scope the scan (substring match, case-insensitive). Without it, the entire doc is scanned and tables for OTHER surfaces produce cross-table false positives. Use when one doc lists multiple surfaces." }
+            },
+            "required": ["name", "glob"],
+            "additionalProperties": false
+          }
+        }
+      },
+      "additionalProperties": true
     }
   },
   "additionalProperties": true