docguard-cli 0.27.0 → 0.28.0

package/README.md

@@ -63,7 +63,7 @@ DocGuard is an official [GitHub Spec Kit](https://github.com/github/spec-kit) co
 
 ```mermaid
 graph TD
-    CLI["CLI Entry<br/>docguard.mjs"] --> Commands["Commands (16)"]
+    CLI["CLI Entry<br/>docguard.mjs"] --> Commands["Commands (17)"]
     Commands --> guard["guard"]
     Commands --> generate["generate"]
     Commands --> score["score"]
@@ -250,7 +250,7 @@ This installs DocGuard's slash commands (`/docguard.init`, `/docguard.guard`, `/
 
 ## Usage
 
-DocGuard ships **16 commands** (the "Daily 5" + 11 situational tools, including the zero-install `demo`). Six additional one-shot scaffolders are accessed via `docguard init --with <name>`. Eight v0.19 commands continue to work as deprecation aliases through v0.20.x — see [MIGRATION-v0.20.md](docs-implementation/MIGRATION-v0.20.md).
+DocGuard ships **17 commands** (the "Daily 5" + 12 situational tools, including the zero-install `demo`). Six additional one-shot scaffolders are accessed via `docguard init --with <name>`. Eight v0.19 commands continue to work as deprecation aliases through v0.20.x — see [MIGRATION-v0.20.md](docs-implementation/MIGRATION-v0.20.md).
 
 **The Daily 5** — what you'll reach for 95% of the time:
 
@@ -274,6 +274,7 @@ DocGuard ships **16 commands** (the "Daily 5" + 11 situational tools, including
 | `generate` | Reverse-engineer docs from existing codebase (`--plan` for AI scan) |
 | `agent` | One-shot agent task graph — ordered, pre-filled code-truth, per-task verify (`--format json`) |
 | `explain <warning\|CODE>` | Paste any warning — or a finding code like `SEC001` — to get the validator's docstring, fix path, and how to suppress |
+| `verify --semantic` | Extract documented numbers/limits/enums (retention days, rate limits, GSI/role counts, status enums) as a task list for an agent to check against code — the semantic-drift class regex/AST can't see |
 | `feedback` | Report likely false positives back to DocGuard — local-first record + a 1-click prefilled, redacted GitHub issue (zero typing) |
 | `memory` | Per-domain accuracy headline (endpoints / entities / env / tech) |
 | `memory --diff` | Drill into which specific claims don't match code |

package/cli/commands/explain.mjs

@@ -111,13 +111,14 @@ const EXPLAINERS = {
   },
   freshness: {
     title: 'Freshness — docs updated alongside code',
-    what: 'For each canonical doc, counts code commits since the doc\'s last commit. >10 commits = stale.',
+    what: 'For each canonical doc it picks a "last updated" date by PRECEDENCE, then counts code commits since (>10 = stale): (1) an explicit `<!-- docguard:last-reviewed YYYY-MM-DD -->` marker — a human review signal git cannot see, so it WINS; (2) `<!-- docguard:status approved -->`; (3) the git commit date; (4) for an uncommitted file with no marker, it asks you to commit OR add a marker. CHANGELOG.md follows the SAME precedence — a marker satisfies it before any commit, which matters in a pre-commit edit/review loop. `docguard init` now stamps a `last-reviewed` marker into every canonical doc so freshness is marker-based and consistent from day one.',
     why:  'Docs drift silently. This validator surfaces the drift before it becomes invisible.',
     triggers: [
-      ['code commits since last doc update', 'Run `docguard sync --write` to refresh code-truth sections, then review the prose for accuracy.'],
+      ['code commits since last doc update', 'Run `docguard sync --write` to refresh code-truth sections, then review the prose and update (or add) the `<!-- docguard:last-reviewed YYYY-MM-DD -->` marker.'],
+      ['not yet committed to git', 'A canonical doc has no git history and no marker. Commit it, or add `<!-- docguard:last-reviewed YYYY-MM-DD -->` (or `<!-- docguard:status approved -->`) so freshness is satisfiable before the commit.'],
       ['DRIFT-LOG.md may be stale', 'DRIFT comments in code outpaced log entries. Add the entries.'],
     ],
-    example: 'ARCHITECTURE.md last committed within 10 code commits',
+    example: 'ARCHITECTURE.md carries `<!-- docguard:last-reviewed 2026-06-19 -->` (or was committed within 10 code commits)',
     standard: 'CDD principle: docs and code commit together',
   },
   traceability: {
@@ -134,12 +135,13 @@ const EXPLAINERS = {
     standard: 'ISO/IEC/IEEE 29148 (requirements traceability)',
   },
   apiSurface: {
-    title: 'API-Surface — endpoints in code match API-REFERENCE.md',
-    what: 'Compares routes scanned from code (Express, Next, FastAPI, Spring, etc.) against endpoints listed in API-REFERENCE.md and OpenAPI specs.',
-    why:  'Documented but missing endpoints are dead links. Endpoints in code that aren\'t documented are invisible.',
+    title: 'API-Surface — endpoints in code match API-REFERENCE.md (and the spec matches the routes)',
+    what: 'Compares routes scanned from code (Express, Next, FastAPI, Spring, etc.) against endpoints listed in API-REFERENCE.md and OpenAPI specs. When an OpenAPI spec exists it is the authoritative surface — so it ALSO diffs the spec against the actually-registered code routes, catching a spec that declares a phantom endpoint (the doc reconciles clean against a wrong spec otherwise). That spec-vs-route check is conservative: it only runs when code routes are actually scannable.',
+    why:  'Documented but missing endpoints are dead links. Endpoints in code that aren\'t documented are invisible. And a spec nobody implements is a lie the doc check can\'t see.',
     triggers: [
       ['documented but absent', 'API-REFERENCE.md lists an endpoint that scanRoutes() can\'t find. Remove or fix the doc; `fix --write` removes when marked.'],
       ['present but undocumented', 'A route exists in code but API-REFERENCE.md doesn\'t list it. Add it.'],
+      ['declares', 'The OpenAPI spec declares an endpoint that no Express/Fastify/etc. route registers in code — i.e. "declares METHOD /path but no route registers it". Either implement the route or remove the phantom endpoint from the spec (the API-REFERENCE doc reconciles clean against the spec, so this is the only check that catches it).'],
     ],
     example: 'GET /api/users in src/routes/users.ts AND in API-REFERENCE.md\'s Endpoints table',
     standard: 'OpenAPI 3.1',

package/cli/commands/guard.mjs

@@ -462,12 +462,17 @@ export function runGuard(projectDir, config, flags) {
 
   // ── JSON output ──
   if (flags.format === 'json') {
-    console.log(JSON.stringify(data, null, 2));
     // Use severity-aware effective counts for exit code; raw counts stay in the JSON
     // for display tools that want to show the full picture.
-    if (data.effectiveErrors > 0) process.exit(1);
-    if (data.effectiveWarnings > 0) process.exit(2);
-    process.exit(0);
+    const code = data.effectiveErrors > 0 ? 1 : data.effectiveWarnings > 0 ? 2 : 0;
+    // v0.28: set exitCode + return instead of process.exit(). A large JSON
+    // payload (>~8 KB) written to a PIPE flushes asynchronously; an immediate
+    // process.exit() truncates it mid-string, so a CI consumer parsing stdout
+    // gets "Unterminated string in JSON" on exactly the big reports that matter.
+    // Returning lets Node drain stdout and exit naturally with process.exitCode.
+    process.exitCode = code;
+    process.stdout.write(JSON.stringify(data, null, 2) + '\n');
+    return;
   }
 
   // ── Text output ──
@@ -707,7 +712,8 @@ export function runGuard(projectDir, config, flags) {
   }
 
   // v0.5: severity-aware exit codes (see runGuardInternal for the rollup).
-  if (data.effectiveErrors > 0) process.exit(1);
-  if (data.effectiveWarnings > 0) process.exit(2);
-  process.exit(0);
+  // v0.28: exitCode + return (not process.exit) so the buffered text output
+  // flushes to a pipe before the process exits — same truncation fix as the
+  // JSON path above.
+  process.exitCode = data.effectiveErrors > 0 ? 1 : data.effectiveWarnings > 0 ? 2 : 0;
 }

package/cli/commands/init.mjs

@@ -78,6 +78,20 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const TEMPLATES_DIR = resolve(__dirname, '../../templates');
 
+/**
+ * v0.28 (field report #11): inject a `<!-- docguard:last-reviewed DATE -->`
+ * marker right after the first H1, so a canonical doc has a freshness signal the
+ * Freshness validator reads directly (not git mtime). No-op if one is present.
+ */
+function stampLastReviewed(content, date) {
+  const marker = `<!-- docguard:last-reviewed ${date} -->`;
+  const lines = content.split('\n');
+  const h1 = lines.findIndex(l => /^#\s/.test(l));
+  if (h1 === -1) return `${marker}\n\n${content}`;
+  lines.splice(h1 + 1, 0, '', marker);
+  return lines.join('\n');
+}
+
 // ── Readline helper ──────────────────────────────────────────────────────
 
 function askQuestion(prompt) {
@@ -263,7 +277,15 @@ export async function runInit(projectDir, config, flags) {
     if (existsSync(templatePath)) {
       const content = readFileSync(templatePath, 'utf-8');
       const today = new Date().toISOString().split('T')[0];
-      const processed = content.replace(/YYYY-MM-DD/g, today);
+      let processed = content.replace(/YYYY-MM-DD/g, today);
+      // v0.28 (field report #11): every canonical doc must ship with a freshness
+      // marker so the Freshness validator is marker-based (consistent across docs,
+      // and satisfiable in a pre-commit review loop) rather than silently falling
+      // back to git mtime. Templates now all carry one; this is the belt-and-
+      // suspenders guarantee for any future template that forgets.
+      if (mapping.dest.startsWith('docs-canonical/') && !/docguard:last-reviewed/.test(processed)) {
+        processed = stampLastReviewed(processed, today);
+      }
       writeFileSync(destPath, processed, 'utf-8');
       created.push(mapping.dest);
       console.log(`  ${c.green}✅${c.reset} Created: ${c.cyan}${mapping.dest}${c.reset}`);

package/cli/commands/sync-tests.mjs

@@ -0,0 +1,272 @@
+/**
+ * `docguard sync --tests` — reconcile the TEST-SPEC Source-to-Test Map from disk.
+ *
+ * Background (LLM field report #10): the source→test table in TEST-SPEC.md is
+ * hand-maintained, so plain `docguard sync` (which only refreshes
+ * docguard:generated code-truth SECTIONS) reports "nothing drifted" even when the
+ * table has a ghost service (source deleted), a ghost test (test file deleted),
+ * and N services that gained tests. The Test-Spec validator already detects the
+ * ghosts; this writes the reconciliation back.
+ *
+ * SAFETY — this edits a human-curated table, so it does ONLY the two unambiguous
+ * operations and previews by default (`--write` applies):
+ *   - REMOVE a row whose SOURCE file no longer exists on disk (ghost service).
+ *   - APPEND a row for a co-located source↔test pair found on disk but absent
+ *     from the table (newly-covered service).
+ * Ghost TEST references (source still exists, test file gone) are REPORTED but
+ * never auto-edited — blanking a hand-maintained status/notes cell is too
+ * destructive, and the Test-Spec validator already warns on them.
+ *
+ * Zero npm dependencies — pure Node.js built-ins.
+ */
+
+import { existsSync, readFileSync, writeFileSync, readdirSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { c } from '../shared.mjs';
+import { shouldIgnore } from '../shared-ignore.mjs';
+
+const TEST_SPEC_DOC = 'docs-canonical/TEST-SPEC.md';
+const CODE_EXT = /\.[cm]?[jt]sx?$/;
+const TEST_RE = /\.(test|spec)\.[cm]?[jt]sx?$/;
+const WALK_SKIP = new Set(['node_modules', 'dist', 'build', 'coverage', '.git', '.next', '__pycache__', '.venv', 'vendor']);
+
+// ── On-disk discovery ──────────────────────────────────────────────────────
+
+function walkCodeFiles(projectDir, config) {
+  const out = [];
+  const visit = (absDir, relDir) => {
+    let entries;
+    try { entries = readdirSync(absDir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (e.name.startsWith('.')) continue;
+      if (WALK_SKIP.has(e.name)) continue;
+      const relPath = relDir ? `${relDir}/${e.name}` : e.name;
+      if (e.isDirectory()) { visit(resolve(absDir, e.name), relPath); continue; }
+      if (!CODE_EXT.test(e.name)) continue;
+      if (shouldIgnore(relPath, config)) continue;
+      out.push(relPath);
+    }
+  };
+  visit(resolve(projectDir), '');
+  return out;
+}
+
+const dirOf = (p) => (p.includes('/') ? p.slice(0, p.lastIndexOf('/')) : '');
+const baseOf = (p) => (p.includes('/') ? p.slice(p.lastIndexOf('/') + 1) : p);
+const stemOf = (b) => b.replace(CODE_EXT, '').replace(/\.(test|spec)$/, '');
+
+/**
+ * Discover co-located source↔test pairs on disk. A test counts as covering a
+ * source when their stems match AND the test sits in the same directory or a
+ * sibling `__tests__/`. Conservative by design — cross-directory basename
+ * collisions (two `index.ts`) would pollute the table, so they're excluded.
+ *
+ * @returns {Array<{ source: string, test: string }>}
+ */
+export function discoverTestPairs(projectDir, config = {}) {
+  const files = walkCodeFiles(projectDir, config);
+  const tests = files.filter((f) => TEST_RE.test(f));
+  const sources = files.filter((f) => !TEST_RE.test(f));
+  const pairs = [];
+  for (const src of sources) {
+    const sDir = dirOf(src);
+    const sStem = stemOf(baseOf(src));
+    const match = tests.find((t) => {
+      if (stemOf(baseOf(t)) !== sStem) return false;
+      const tDir = dirOf(t);
+      return tDir === sDir || tDir === `${sDir}/__tests__` || (sDir === '' && tDir === '__tests__');
+    });
+    if (match) pairs.push({ source: src, test: match });
+  }
+  return pairs;
+}
+
+// ── Table parsing (mirrors test-spec.mjs column detection) ─────────────────
+
+const isPathLike = (v) => !!v && !/\s/.test(v) && (/[\\/]/.test(v) || /\.[A-Za-z0-9]{1,6}$/.test(v));
+const splitRow = (line) => {
+  const parts = line.split('|');
+  parts.shift();
+  parts.pop();
+  return parts.map((s) => s.trim());
+};
+
+/**
+ * Locate the Source-to-Test Map table and classify its rows against disk.
+ * @returns {null | { headerLine, sepLine, sourceIdx, testIdxs, ncols, keep:string[],
+ *                    removed:object[], ghostTests:object[], blockStart, blockEnd }}
+ */
+function parseMapTable(content, projectDir) {
+  const sectionRe = /## (?:Service-to-Test Map|Source-to-Test Map)[\s\S]*?(?=\n## |$)/;
+  const m = sectionRe.exec(content);
+  if (!m) return null;
+  const sectionStart = m.index;
+  const sectionText = m[0];
+  const sectionLines = sectionText.split('\n');
+
+  // Find the FIRST pipe table inside the section (header + separator + rows).
+  let headerLineIdx = -1;
+  for (let i = 0; i < sectionLines.length - 1; i++) {
+    if (sectionLines[i].trim().startsWith('|') && /^\s*\|[\s|:-]+\|\s*$/.test(sectionLines[i + 1])) {
+      headerLineIdx = i;
+      break;
+    }
+  }
+  if (headerLineIdx === -1) return null;
+
+  const header = splitRow(sectionLines[headerLineIdx]).map((h) => h.toLowerCase());
+  const ncols = header.length;
+  let sourceIdx = header.findIndex((h) => /\bsource\b/.test(h));
+  if (sourceIdx < 0) sourceIdx = 0;
+  let statusIdx = header.findIndex((h) => /\bstatus\b/.test(h));
+  if (statusIdx < 0) statusIdx = ncols - 1;
+  let testIdxs = header.map((h, i) => (/\btest\b|\be2e\b/.test(h) ? i : -1)).filter((i) => i >= 0 && i !== sourceIdx && i !== statusIdx);
+  if (testIdxs.length === 0) { const fb = sourceIdx === 1 ? 0 : 1; if (fb !== statusIdx && fb < ncols) testIdxs = [fb]; }
+
+  // Walk data rows after the separator until the table ends (a non-pipe line).
+  const keep = [];           // raw row lines to retain
+  const removed = [];        // { source } ghost-source rows dropped
+  const ghostTests = [];     // { source, test } source exists but a test ref is gone
+  const documentedSources = new Set();
+  let dataEndIdx = headerLineIdx + 2;
+  for (let i = headerLineIdx + 2; i < sectionLines.length; i++) {
+    const line = sectionLines[i];
+    if (!line.trim().startsWith('|')) break;
+    dataEndIdx = i + 1;
+    const cells = splitRow(line);
+    const rawSource = (cells[sourceIdx] || '').replace(/`/g, '').trim();
+    // Template/example/placeholder rows are left untouched.
+    if (!rawSource || rawSource.startsWith('<!--') || rawSource.startsWith('*') || !isPathLike(rawSource)) {
+      keep.push(line);
+      continue;
+    }
+    if (!existsSync(resolve(projectDir, rawSource))) {
+      removed.push({ source: rawSource });
+      continue; // drop ghost-source row
+    }
+    documentedSources.add(rawSource);
+    // Source exists — report (don't edit) any dead test reference.
+    for (const ti of testIdxs) {
+      const t = (cells[ti] || '').replace(/`/g, '').trim();
+      if (isPathLike(t) && !existsSync(resolve(projectDir, t))) ghostTests.push({ source: rawSource, test: t });
+    }
+    keep.push(line);
+  }
+
+  return {
+    sectionStart,
+    headerAbsLine: headerLineIdx,
+    sepLine: sectionLines[headerLineIdx + 1],
+    headerLine: sectionLines[headerLineIdx],
+    sourceIdx, testIdxs, statusIdx, ncols,
+    keep, removed, ghostTests, documentedSources,
+    // absolute char offsets of the table block within `content`
+    blockStartLine: headerLineIdx,
+    blockEndLine: dataEndIdx,
+    sectionLines,
+    sectionTextStart: sectionStart,
+  };
+}
+
+/**
+ * Compute the reconciliation. Pure: returns the diff + the rewritten content.
+ * @returns {{ applicable:boolean, removed:object[], added:object[], ghostTests:object[], newContent:string|null, reason?:string }}
+ */
+export function reconcileTestMap(content, projectDir, config) {
+  const parsed = parseMapTable(content, projectDir);
+  if (!parsed) {
+    return { applicable: false, removed: [], added: [], ghostTests: [], newContent: null, reason: 'no Source-to-Test Map table found' };
+  }
+  const pairs = discoverTestPairs(projectDir, config);
+  const added = pairs.filter((p) => !parsed.documentedSources.has(p.source));
+
+  // Build the new table block: header, separator, kept rows, appended rows.
+  const newRowFor = ({ source, test }) => {
+    const cells = new Array(parsed.ncols).fill('—');
+    cells[parsed.sourceIdx] = `\`${source}\``;
+    if (parsed.testIdxs.length) cells[parsed.testIdxs[0]] = `\`${test}\``;
+    cells[parsed.statusIdx] = '⚠️ auto-added — verify';
+    return `| ${cells.join(' | ')} |`;
+  };
+  const addedRows = added.map(newRowFor);
+  const newBlock = [parsed.headerLine, parsed.sepLine, ...parsed.keep, ...addedRows].join('\n');
+
+  // Splice the new block back into the original section text, then back into content.
+  const sectionLines = parsed.sectionLines.slice();
+  const before = sectionLines.slice(0, parsed.blockStartLine);
+  const after = sectionLines.slice(parsed.blockEndLine);
+  const newSection = [...before, newBlock, ...after].join('\n');
+  const oldSection = parsed.sectionLines.join('\n');
+  const newContent = content.slice(0, parsed.sectionTextStart) + newSection + content.slice(parsed.sectionTextStart + oldSection.length);
+
+  const changed = parsed.removed.length > 0 || added.length > 0;
+  return {
+    applicable: true,
+    removed: parsed.removed,
+    added,
+    ghostTests: parsed.ghostTests,
+    newContent: changed ? newContent : null,
+  };
+}
+
+// ── CLI ────────────────────────────────────────────────────────────────────
+
+export function runSyncTests(projectDir, config, flags) {
+  const apply = !!flags.write;
+  const isJson = flags.format === 'json';
+  const docPath = resolve(projectDir, TEST_SPEC_DOC);
+
+  if (!existsSync(docPath)) {
+    if (isJson) { console.log(JSON.stringify({ applicable: false, reason: 'TEST-SPEC.md not present' }, null, 2)); return; }
+    console.log(`${c.yellow}TEST-SPEC.md not found — run ${c.cyan}docguard init${c.yellow} first.${c.reset}\n`);
+    return;
+  }
+
+  const content = readFileSync(docPath, 'utf-8');
+  const r = reconcileTestMap(content, projectDir, config);
+
+  if (isJson) {
+    console.log(JSON.stringify({
+      applicable: r.applicable, applied: apply && !!r.newContent,
+      removed: r.removed, added: r.added, ghostTests: r.ghostTests, reason: r.reason || null,
+    }, null, 2));
+    if (apply && r.newContent) writeFileSync(docPath, r.newContent, 'utf-8');
+    return;
+  }
+
+  console.log(`${c.bold}🔄 DocGuard Sync --tests — ${config.projectName}${c.reset}`);
+  console.log(`${c.dim}   ${TEST_SPEC_DOC} · ${apply ? 'Applying' : 'Dry run (use --write to apply)'}${c.reset}\n`);
+
+  if (!r.applicable) {
+    console.log(`  ${c.yellow}No Source-to-Test Map table found in TEST-SPEC.md.${c.reset}`);
+    console.log(`  ${c.dim}Add a "## Source-to-Test Map" table (col 1 = source, last col = status), then re-run.${c.reset}\n`);
+    return;
+  }
+
+  if (r.removed.length === 0 && r.added.length === 0 && r.ghostTests.length === 0) {
+    console.log(`  ${c.green}✅ Source-to-Test Map matches disk — nothing to reconcile.${c.reset}\n`);
+    return;
+  }
+
+  if (r.removed.length) {
+    console.log(`  ${apply ? c.green : c.yellow}${apply ? '✅ Removed' : '• Remove'} ${r.removed.length} ghost-source row(s) (source file deleted):${c.reset}`);
+    for (const x of r.removed) console.log(`     ${c.dim}- ${x.source}${c.reset}`);
+  }
+  if (r.added.length) {
+    console.log(`  ${apply ? c.green : c.yellow}${apply ? '✅ Added' : '• Add'} ${r.added.length} newly-covered source(s):${c.reset}`);
+    for (const x of r.added) console.log(`     ${c.dim}+ ${x.source} → ${x.test}${c.reset}`);
+  }
+  if (r.ghostTests.length) {
+    console.log(`  ${c.yellow}⚠ ${r.ghostTests.length} ghost test reference(s) (source exists, test file gone) — fix by hand:${c.reset}`);
+    for (const x of r.ghostTests) console.log(`     ${c.dim}~ ${x.source} → ${x.test} (missing)${c.reset}`);
+  }
+
+  if (apply && r.newContent) {
+    writeFileSync(docPath, r.newContent, 'utf-8');
+    console.log(`\n  ${c.green}↻ ${TEST_SPEC_DOC} updated. Review the ⚠️ auto-added rows, then ${c.cyan}docguard guard${c.green}.${c.reset}\n`);
+  } else if (!apply) {
+    console.log(`\n  ${c.dim}Apply: ${c.cyan}docguard sync --tests --write${c.reset}\n`);
+  } else {
+    console.log('');
+  }
+}

package/cli/commands/sync.mjs

@@ -20,6 +20,7 @@ import { c } from '../shared.mjs';
 import { buildMemoryPlan } from '../scanners/memory-plan.mjs';
 import { getSection, replaceSection } from '../writers/sections.mjs';
 import { hasGeneratedMarker } from '../writers/api-reference.mjs';
+import { runSyncTests } from './sync-tests.mjs';
 
 function gitChangedFiles(projectDir, since) {
   const run = (args) => {
@@ -77,6 +78,11 @@ function sectionTouchedByChanges(sectionId, changedFiles) {
 }
 
 export function runSync(projectDir, config, flags) {
+  // v0.28 (field report #10): `--tests` reconciles the hand-maintained TEST-SPEC
+  // Source-to-Test Map from disk (ghost-source removal + new co-located pairs) —
+  // a distinct path from the generated code-truth section refresh below.
+  if (flags.tests) return runSyncTests(projectDir, config, flags);
+
   const plan = buildMemoryPlan(projectDir, config);
   const apply = !!flags.write;
   const isJson = flags.format === 'json';

package/cli/commands/verify.mjs

@@ -0,0 +1,67 @@
+/**
+ * Verify Command — `docguard verify --semantic` (LLM field report #5).
+ *
+ * Surfaces the semantic claims in the canonical docs (documented numbers, limits,
+ * and enums) as a structured verification task list for the agent to check
+ * against the code. DocGuard does the deterministic discovery; the LLM does the
+ * judgment — the same division of labour as `docguard agent`.
+ *
+ * Read-only. JSON is the machine artifact (the agent-executable task list);
+ * text is the human summary.
+ *
+ *   docguard verify [--semantic] [--format json]
+ */
+
+import { c } from '../shared.mjs';
+import { detectAgentMode } from '../ensure-skills.mjs';
+import { extractSemanticClaims, buildSemanticVerifyTasks } from '../scanners/semantic-claims.mjs';
+
+export function runVerify(projectDir, config, flags) {
+  const isJson = flags.format === 'json';
+  const claims = extractSemanticClaims(projectDir, config);
+  const tasks = buildSemanticVerifyTasks(claims);
+
+  if (isJson) {
+    console.log(JSON.stringify({
+      command: 'verify --semantic',
+      project: config.projectName,
+      claimCount: tasks.length,
+      // How to act on this: each task is a claim to confirm against the code.
+      howToVerify: 'For each task, read the cited code (or grep for the constant/config), compare it to the documented value, and report any mismatch with both values. DocGuard cannot judge these — they require reading the code.',
+      tasks,
+    }, null, 2));
+    return;
+  }
+
+  console.log(`${c.bold}🔬 DocGuard Verify — semantic claims${c.reset}`);
+  console.log(`${c.dim}   ${config.projectName} · documented numbers / limits / enums to check against code${c.reset}\n`);
+
+  if (tasks.length === 0) {
+    console.log(`  ${c.green}✅ No semantic claims found in the canonical docs.${c.reset}`);
+    console.log(`  ${c.dim}(Looks for numbers with units — days/ms/req-s/GSIs/roles/… — and status/enum lists.)${c.reset}\n`);
+    return;
+  }
+
+  // Group by doc for a readable summary.
+  const byDoc = new Map();
+  for (const t of tasks) {
+    if (!byDoc.has(t.doc)) byDoc.set(t.doc, []);
+    byDoc.get(t.doc).push(t);
+  }
+
+  console.log(`  ${c.yellow}${tasks.length} claim(s) to verify against the code:${c.reset}\n`);
+  for (const [doc, ts] of byDoc) {
+    console.log(`  ${c.bold}${doc}${c.reset}`);
+    for (const t of ts) {
+      const val = t.kind === 'enum' ? `enum ${t.value}` : `${t.value}${t.unit ? ` ${t.unit}` : ''}`;
+      const cited = t.citedCode ? `${c.cyan}${t.citedCode}${c.reset}` : `${c.dim}(no cited code — grep for it)${c.reset}`;
+      console.log(`    ${c.yellow}•${c.reset} L${t.line} ${c.dim}${t.section ? `[${t.section}] ` : ''}${c.reset}${c.bold}${val}${c.reset} → check ${cited}`);
+    }
+    console.log('');
+  }
+
+  const mode = detectAgentMode(projectDir);
+  const cmd = mode === 'llm' ? '/docguard.verify' : 'docguard verify --semantic --format json';
+  console.log(`  ${c.dim}This is the highest-value bug class and DocGuard can't judge it — an agent must.${c.reset}`);
+  console.log(`  ${c.dim}Get the machine task list: ${c.cyan}${cmd}${c.dim}, then read each cited file and confirm the value.${c.reset}\n`);
+}

package/cli/docguard.mjs

@@ -44,6 +44,7 @@ import { runUpgrade } from './commands/upgrade.mjs';
 import { runImpact } from './commands/impact.mjs';
 import { runExplain } from './commands/explain.mjs';
 import { runFeedback } from './commands/feedback.mjs';
+import { runVerify } from './commands/verify.mjs';
 import { runMemory } from './commands/memory.mjs';
 import { runDemo } from './commands/demo.mjs';
 import { runAgent } from './commands/agent.mjs';
@@ -87,6 +88,7 @@ ${c.bold}Tools (situational, but day-to-day useful)${c.reset}
   ${c.green}generate${c.reset}   Reverse-engineer canonical docs from existing code (${c.cyan}--plan${c.reset} for AI scan)
   ${c.green}agent${c.reset}      One-shot agent task graph — ordered tasks, pre-filled code-truth, per-task verify (${c.cyan}--format json${c.reset})
   ${c.green}explain${c.reset}    Explain a validator key, warning text, or finding code (${c.cyan}docguard explain SEC001${c.reset})
+  ${c.green}verify${c.reset}     Extract documented numbers/limits/enums for an agent to check vs code (${c.cyan}--semantic${c.reset})
   ${c.green}feedback${c.reset}   Report likely false positives back to DocGuard (local-first + 1-click prefilled issue)
   ${c.green}memory${c.reset}     Show what DocGuard remembers (${c.cyan}--diff${c.reset} drills into drift)
   ${c.green}trace${c.reset}      Requirements traceability matrix (${c.cyan}--reverse${c.reset} for code→doc map)
@@ -232,13 +234,14 @@ const COMMAND_HELP = {
     examples: ['docguard diff', 'docguard diff --since HEAD~5'],
   },
   sync: {
-    summary: 'Refresh code-truth doc sections (preview by default).',
-    usage: 'docguard sync [--write] [--since <ref>]',
+    summary: 'Refresh code-truth doc sections (preview by default). `--tests` reconciles the TEST-SPEC Source-to-Test Map from disk.',
+    usage: 'docguard sync [--write] [--since <ref>] [--tests]',
     flags: [
       ['--write', 'Apply the refresh (default is a dry-run preview)'],
       ['--since <ref>', 'Only sync sections whose source files changed since <ref>'],
+      ['--tests', 'Reconcile the TEST-SPEC Source-to-Test Map: drop ghost-source rows, append newly-covered source↔test pairs (report ghost tests). Pair with --write to apply.'],
     ],
-    examples: ['docguard sync', 'docguard sync --write'],
+    examples: ['docguard sync', 'docguard sync --write', 'docguard sync --tests', 'docguard sync --tests --write'],
   },
   fix: {
     summary: 'Generate AI fix instructions for docs (or apply deterministic fixes).',
@@ -287,6 +290,15 @@ const COMMAND_HELP = {
     flags: [['--format json', 'Machine-readable list of reportable findings + URLs']],
     examples: ['docguard feedback'],
   },
+  verify: {
+    summary: 'Extract the semantic claims in your canonical docs — documented numbers, limits, and enums (retention days, rate limits, GSI/role counts, status enums) — as a verification task list the agent checks against the code. This is the highest-value bug class (a doc value that drifted from code) and the one regex/AST cannot judge. DocGuard finds the claims; the LLM confirms them.',
+    usage: 'docguard verify [--semantic] [--format json]',
+    flags: [
+      ['--semantic', 'Extract documented numbers/limits/enums to verify against code (the current — and default — mode)'],
+      ['--format json', 'Machine-readable task list (the agent-executable artifact)'],
+    ],
+    examples: ['docguard verify --semantic', 'docguard verify --semantic --format json'],
+  },
 };
 
 function printCommandHelp(command) {
@@ -355,6 +367,14 @@ async function main() {
       flags.auto = true;
     } else if (args[i] === '--write') {
       flags.write = true;
+    } else if (args[i] === '--tests') {
+      // v0.28 (field report #10): `docguard sync --tests` reconciles the
+      // TEST-SPEC Source-to-Test Map from disk.
+      flags.tests = true;
+    } else if (args[i] === '--semantic') {
+      // v0.28 (field report #5): `docguard verify --semantic` extracts
+      // documented numbers/enums/limits for the agent to check against code.
+      flags.semantic = true;
     } else if (args[i] === '--plan') {
       flags.plan = true;
     } else if (args[i] === '--since' && args[i + 1]) {
@@ -518,6 +538,8 @@ async function main() {
     // feedback only writes its own .docguard/feedback/ — it must NOT scaffold
     // skills or touch source, so it's gated out of ensureSkills like the rest.
     'feedback',
+    // verify only reads docs and emits a task list — pure report.
+    'verify',
   ]);
 
   // Silent auto-check: install skills/commands if missing. Skip entirely in
@@ -663,6 +685,12 @@ async function main() {
       // redacted, capped GitHub issue URL. Opt-in; nothing filed automatically.
       runFeedback(projectDir, config, flags);
       break;
+    case 'verify':
+      // v0.28 (field report #5): extract documented numbers/limits/enums as a
+      // verification task list for the agent to check against code (semantic
+      // drift — the class regex/AST can't see). Read-only.
+      runVerify(projectDir, config, flags);
+      break;
     case 'memory':
       runMemory(projectDir, config, flags);
       break;

package/cli/scanners/semantic-claims.mjs

@@ -0,0 +1,154 @@
+/**
+ * Semantic claim extractor (LLM field report #5).
+ *
+ * The highest-value class of doc bug is SEMANTIC: a documented number/enum/limit
+ * that no longer matches the code — DLP retention "30 days" vs code 730, a status
+ * enum "PENDING/IDLE" vs "WAITING", "100/min" vs "500 req/s", "29+ roles" vs 44,
+ * "4 GSIs" vs 6. Regex/AST can't judge these (the doc value and the code value
+ * are both just numbers), so they slip through every deterministic validator.
+ *
+ * DocGuard is zero-dependency and does NOT call an LLM itself. So this is an
+ * EXTRACTOR: it surfaces the verifiable claims — value, unit, doc:line, section,
+ * and the nearest cited code path — as a structured task list. The agent running
+ * `docguard verify --semantic` does the actual comparison against the code. This
+ * mirrors the `docguard agent` task-graph: deterministic discovery, LLM judgment.
+ *
+ * Precision over recall: a number is only a claim when it carries a recognized
+ * unit (days/ms/req-s/GSIs/roles/…); an enum only when it's a list of 2+
+ * UPPER_SNAKE tokens in a status/state/enum context. Bare version strings, dates,
+ * and prose numbers are ignored.
+ *
+ * Zero npm dependencies — pure Node.js built-ins.
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+
+// Numbers are only claims when adjacent to a recognized unit.
+const NUMBER_PATTERNS = [
+  { kind: 'duration', re: /\b(\d+(?:\.\d+)?)\s*(milliseconds?|ms|seconds?|secs?|minutes?|mins?|hours?|hrs?|days?|weeks?|months?|years?)\b/gi },
+  { kind: 'rate',     re: /\b(\d+)\s*(?:\/|\bper\b|\breq(?:uests?)?\s*\/?)\s*(s|sec|seconds?|min|minutes?|hours?|h)\b/gi },
+  { kind: 'count',    re: /\b(\d+)\s*\+?\s*(GSIs?|LSIs?|indexes|indices|roles?|permissions?|scopes?|tables?|queues?|topics?|buckets?|endpoints?|routes?|validators?|columns?|fields?|shards?|partitions?|replicas?|retries|workers?|threads?|connections?)\b/gi },
+];
+
+// A list of 2+ UPPER_SNAKE tokens separated by / , | or "or" — an enum claim,
+// but only when the line or its heading reads like a status/state/enum context.
+const ENUM_LIST_RE = /\b[A-Z][A-Z0-9_]{2,}(?:\s*(?:\/|,|\||\bor\b)\s*[A-Z][A-Z0-9_]{2,}){1,}\b/g;
+const ENUM_CONTEXT_RE = /\b(status|state|enum|values?|one of|phase|stage|transitions?)\b/i;
+
+// A code path mentioned in or near the claim — the agent's starting point.
+const CITED_CODE_RE = /`?([\w./-]+\.(?:ts|tsx|js|mjs|cjs|jsx|py|go|rs|java|kt|rb|php|sql|yaml|yml|json))`?(?::(\d+))?/;
+
+const MAX_CLAIMS = 80;
+
+/** Canonical docs + the root docs where limits/counts commonly live. */
+function claimSourceDocs(projectDir) {
+  const docs = [];
+  const canonical = resolve(projectDir, 'docs-canonical');
+  if (existsSync(canonical)) {
+    try {
+      for (const f of readdirSync(canonical)) {
+        if (f.toLowerCase().endsWith('.md')) docs.push(`docs-canonical/${f}`);
+      }
+    } catch { /* ignore */ }
+  }
+  for (const root of ['README.md', 'AGENTS.md']) {
+    if (existsSync(resolve(projectDir, root))) docs.push(root);
+  }
+  return docs;
+}
+
+/** True if a line is inside a fenced code block (toggled by the caller). */
+function findCitedCode(lines, idx) {
+  // Search the claim line first, then the immediately adjacent lines. A tight
+  // window avoids cross-attributing a path from an unrelated nearby claim (e.g.
+  // a rate limit grabbing the retention doc's cited file three lines up).
+  for (let d = 0; d <= 1; d++) {
+    for (const j of d === 0 ? [idx] : [idx - d, idx + d]) {
+      if (j < 0 || j >= lines.length) continue;
+      const m = CITED_CODE_RE.exec(lines[j]);
+      if (m) return m[2] ? `${m[1]}:${m[2]}` : m[1];
+    }
+  }
+  return null;
+}
+
+/**
+ * Extract semantic claims from a project's canonical docs.
+ * @returns {Array<{ doc, line, section, kind, subkind, value, unit, text, citedCode }>}
+ */
+export function extractSemanticClaims(projectDir, config = {}) {
+  const claims = [];
+  const seen = new Set();
+
+  for (const doc of claimSourceDocs(projectDir)) {
+    let content;
+    try { content = readFileSync(resolve(projectDir, doc), 'utf-8'); } catch { continue; }
+    const lines = content.split('\n');
+    let section = '';
+    let inFence = false;
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      if (/^\s*```/.test(line)) { inFence = !inFence; continue; }
+      if (inFence) continue; // numbers in code samples are examples, not claims
+      const h = line.match(/^#{1,6}\s+(.*)$/);
+      if (h) { section = h[1].trim(); continue; }
+
+      const lineNo = i + 1;
+      const push = (claim) => {
+        const key = `${doc}:${lineNo}:${claim.kind}:${claim.value}:${claim.unit || ''}`;
+        if (seen.has(key)) return;
+        seen.add(key);
+        claims.push({ doc, line: lineNo, section, citedCode: findCitedCode(lines, i), text: line.trim().slice(0, 200), ...claim });
+      };
+
+      for (const { kind, re } of NUMBER_PATTERNS) {
+        re.lastIndex = 0;
+        let m;
+        while ((m = re.exec(line)) !== null) {
+          push({ kind: 'number', subkind: kind, value: m[1], unit: m[2].toLowerCase() });
+        }
+      }
+
+      if (ENUM_CONTEXT_RE.test(line) || ENUM_CONTEXT_RE.test(section)) {
+        ENUM_LIST_RE.lastIndex = 0;
+        let m;
+        while ((m = ENUM_LIST_RE.exec(line)) !== null) {
+          // Skip all-caps acronym runs joined by slash that are really one token.
+          const values = m[0].split(/\s*(?:\/|,|\||\bor\b)\s*/).filter(Boolean);
+          if (values.length >= 2) push({ kind: 'enum', subkind: 'enum-list', value: values.join('/'), unit: null });
+        }
+      }
+
+      if (claims.length >= MAX_CLAIMS) return claims;
+    }
+  }
+  return claims;
+}
+
+/**
+ * Turn extracted claims into agent-executable verification tasks (one per claim).
+ * Pure — reused by the command and any task-graph consumer.
+ */
+export function buildSemanticVerifyTasks(claims) {
+  return claims.map((c, i) => {
+    const where = c.citedCode ? ` Start at the cited code: ${c.citedCode}.` : ' No code path is cited nearby — grep the codebase for the relevant constant/config.';
+    const what = c.kind === 'enum'
+      ? `the enum/status set "${c.value}"`
+      : `the ${c.subkind} value ${c.value}${c.unit ? ` ${c.unit}` : ''}`;
+    return {
+      id: `verify.semantic.${i + 1}`,
+      doc: c.doc,
+      line: c.line,
+      section: c.section,
+      kind: c.kind,
+      value: c.value,
+      unit: c.unit,
+      citedCode: c.citedCode,
+      claim: c.text,
+      instruction: `Verify ${what} documented in ${c.doc}:${c.line}${c.section ? ` (section "${c.section}")` : ''} against the code.${where} If the code disagrees, the doc (or the code) is wrong — report the mismatch with both values.`,
+      confidence: 'requires-human',
+    };
+  });
+}

package/cli/validators/api-surface.mjs

@@ -208,10 +208,56 @@ export function computeApiSurfaceDrift(projectDir, config) {
   };
 }
 
+/**
+ * v0.28 (field report #4): diff the OpenAPI spec against the routes actually
+ * REGISTERED in code. When a spec exists, resolveApiSurface treats it as ground
+ * truth and the API-REFERENCE doc reconciles against it — so a spec that declares
+ * a phantom endpoint (no Express/Fastify route registers it) passes doc-vs-spec
+ * clean while the spec itself is wrong. This catches that.
+ *
+ * Conservative on purpose: only runs when code routes are actually scannable.
+ * If the scanner finds zero routes (unsupported framework, dynamically-registered
+ * routes), we can't tell "no route" from "scanner blind", so we skip rather than
+ * flag every spec endpoint as phantom. Reuses compareEndpoints so path-param /
+ * mount-prefix normalization matches the rest of the validator.
+ *
+ * @returns {{ applicable:boolean, specPath:string|null, routeCount:number,
+ *             matched:object[], specDeclaredNoRoute:object[], reason?:string }}
+ */
+export function computeSpecVsRouteDrift(projectDir, config) {
+  const specs = findAllOpenApiSpecs(projectDir, config);
+  if (specs.length === 0) {
+    return { applicable: false, specPath: null, routeCount: 0, matched: [], specDeclaredNoRoute: [], reason: 'no openapi spec' };
+  }
+  const spec = specs[0]; // authoritative (sourceRoot first, root last)
+  const framework = detectFramework(projectDir, config);
+  const routes = scanRoutesDeep(projectDir, { framework }, { openapi: { found: false } }, { config });
+  if (routes.length === 0) {
+    return { applicable: false, specPath: spec.relPath, routeCount: 0, matched: [], specDeclaredNoRoute: [], reason: 'no routes scannable' };
+  }
+  // documentedButAbsent = in the SPEC (first arg) but absent from the ROUTES
+  // (second arg) = spec-declares-but-no-route.
+  const cmp = compareEndpoints(
+    spec.endpoints.map(e => ({ method: e.method, path: e.path })),
+    routes.map(r => ({ method: r.method, path: r.path }))
+  );
+  return {
+    applicable: true,
+    specPath: spec.relPath,
+    routeCount: routes.length,
+    matched: cmp.matched,
+    specDeclaredNoRoute: cmp.documentedButAbsent,
+  };
+}
+
 export function validateApiSurface(projectDir, config) {
   const errors = [];
   const warnings = [];
   const fixes = [];
+  const trim = (arr) => {
+    const shown = arr.slice(0, MAX_REPORTED);
+    return { shown, extra: arr.length - shown.length };
+  };
 
   // v0.14-P2: when --changed-only scoping is active and NONE of the changed
   // files look like route/spec/controller files, this validator has nothing
@@ -256,19 +302,39 @@ export function validateApiSurface(projectDir, config) {
     );
   }
 
+  // ── #4: spec declares an endpoint with no registered route ──
+  // Independent of the API-REFERENCE doc — it checks the spec against code, so it
+  // runs even when no doc exists. Conservative (only when routes are scannable).
+  const specRoute = computeSpecVsRouteDrift(projectDir, config);
+  let specRouteTotal = 0;
+  let specRoutePassed = 0;
+  if (specRoute.applicable) {
+    specRouteTotal = specRoute.matched.length + specRoute.specDeclaredNoRoute.length;
+    specRoutePassed = specRoute.matched.length;
+    if (specRoute.specDeclaredNoRoute.length) {
+      const { shown, extra } = trim(specRoute.specDeclaredNoRoute);
+      for (const e of shown) {
+        warnings.push(
+          `OpenAPI spec (${specRoute.specPath}) declares ${e.method} ${e.path} but no route registers it in code — ` +
+          `the spec may be wrong, and the API-REFERENCE doc reconciles clean against it, hiding the gap.`
+        );
+      }
+      if (extra > 0) warnings.push(`…and ${extra} more spec-declared endpoint(s) with no registered route`);
+    }
+  }
+
   if (!drift.applicable) {
-    // Nothing to validate against the API-REFERENCE doc.
-    return { errors, warnings, passed: 0, total: 0, fixes, authoritativeSpec: drift.source };
+    // Nothing to validate against the API-REFERENCE doc — but the spec-vs-route
+    // check above may still have produced findings.
+    return {
+      errors, warnings, passed: specRoutePassed, total: specRouteTotal, fixes,
+      authoritativeSpec: drift.source || specRoute.specPath,
+    };
   }
 
   const { documentedButAbsent, presentButUndocumented, matched, confidence, source } = drift;
-  const total = matched.length + documentedButAbsent.length + presentButUndocumented.length;
-  const passed = matched.length;
-
-  const trim = (arr) => {
-    const shown = arr.slice(0, MAX_REPORTED);
-    return { shown, extra: arr.length - shown.length };
-  };
+  const total = matched.length + documentedButAbsent.length + presentButUndocumented.length + specRouteTotal;
+  const passed = matched.length + specRoutePassed;
 
   // documented-but-absent → deterministic remove-endpoint fixes
   if (documentedButAbsent.length) {

package/cli/validators/architecture.mjs

@@ -97,11 +97,11 @@ function validateConfigLayers(projectDir, config, layers, results) {
       const relPath = relative(projectDir, file);
       const imports = extractImports(content);
 
-      for (const imp of imports) {
-        if (!imp.startsWith('.') && !imp.startsWith('/')) continue;
+      for (const { spec } of imports) {
+        if (!spec.startsWith('.') && !spec.startsWith('/')) continue;
 
         for (const forbiddenDir of layer.forbidden) {
-          if (imp.includes(forbiddenDir) || imp.includes(`/${forbiddenDir}/`)) {
+          if (spec.includes(forbiddenDir) || spec.includes(`/${forbiddenDir}/`)) {
             results.total++;
             results.errors.push(
               `${relPath}: ${layer.name} layer imports from forbidden layer (${forbiddenDir})`
@@ -135,14 +135,19 @@ function buildImportGraph(projectDir, config) {
 
       const resolvedImports = [];
       for (const imp of imports) {
-        if (!imp.startsWith('.') && !imp.startsWith('/')) continue;
+        if (!imp.spec.startsWith('.') && !imp.spec.startsWith('/')) continue;
 
         // Resolve relative imports
         const fromDir = dirname(file);
-        const resolved = resolveImport(fromDir, imp, projectDir);
+        const resolved = resolveImport(fromDir, imp.spec, projectDir);
         if (resolved) {
-          resolvedImports.push(resolved);
-          graph.edges.push({ from: relPath, to: resolved });
+          graph.edges.push({ from: relPath, to: resolved, dynamic: imp.dynamic });
+          // v0.28 (field report #2): a dynamic `await import()` does NOT create a
+          // load-time edge — it's the canonical way to BREAK an import cycle. So
+          // it's excluded from the cycle-detection adjacency (fileMap) while still
+          // recorded in graph.edges for layer-boundary checks (an import is still
+          // an import for layering).
+          if (!imp.dynamic) resolvedImports.push(resolved);
         }
       }
 
@@ -153,26 +158,33 @@ function buildImportGraph(projectDir, config) {
   return graph;
 }
 
+/**
+ * Extract a file's imports as `{ spec, dynamic }`. `dynamic:true` marks a
+ * runtime `import('…')` — which does NOT create a load-time dependency edge and
+ * is the canonical way to break an import cycle (field report #2). ES `import …
+ * from` and CommonJS `require()` are load-time (static).
+ */
 function extractImports(content) {
   const imports = [];
 
-  // ES module imports
+  // ES module imports (static, load-time). `import\s+` requires whitespace after
+  // `import`, so it never matches a dynamic `import(` call.
   const esImportRegex = /import\s+(?:.*?\s+from\s+)?['"]([^'"]+)['"]/g;
   let match;
   while ((match = esImportRegex.exec(content)) !== null) {
-    imports.push(match[1]);
+    imports.push({ spec: match[1], dynamic: false });
   }
 
-  // Dynamic imports
+  // Dynamic imports (runtime — NOT a load-time cycle edge)
   const dynamicRegex = /import\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
   while ((match = dynamicRegex.exec(content)) !== null) {
-    imports.push(match[1]);
+    imports.push({ spec: match[1], dynamic: true });
   }
 
-  // CommonJS require
+  // CommonJS require (static, load-time)
   const requireRegex = /require\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
   while ((match = requireRegex.exec(content)) !== null) {
-    imports.push(match[1]);
+    imports.push({ spec: match[1], dynamic: false });
   }
 
   return imports;

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

@@ -3,7 +3,7 @@ schema_version: "1.0"
 extension:
   id: "docguard"
   name: "DocGuard — CDD Enforcement"
-  version: "0.27.0"
+  version: "0.28.0"
   description: "Canonical-Driven Development enforcement as a true spec-kit extension. LLM-first design with automated validators, 4 AI behavior skills, spec-kit skill chaining, and workflow hooks. One pinned runtime dependency (@babel/parser); pure Node.js otherwise."
   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.27.0
+  version: 0.28.0
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.27.0 -->
+<!-- docguard:version: 0.28.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.27.0
+  version: 0.28.0
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.27.0 -->
+<!-- docguard:version: 0.28.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.27.0
+  version: 0.28.0
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.27.0 -->
+<!-- docguard:version: 0.28.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.27.0
+  version: 0.28.0
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.27.0 -->
+<!-- docguard:version: 0.28.0 -->
 
 # DocGuard Score Skill
 

package/extensions/spec-kit-docguard/skills/docguard-sync/SKILL.md

@@ -4,10 +4,10 @@ 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.27.0
+  version: 0.28.0
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
-<!-- docguard:version: 0.27.0 -->
+<!-- docguard:version: 0.28.0 -->
 
 # DocGuard Sync Skill
 

package/package.json

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

package/templates/ENVIRONMENT.md.template

@@ -1,5 +1,10 @@
 # Environment & Configuration
 
+<!-- docguard:version 0.1.0 -->
+<!-- docguard:status draft -->
+<!-- docguard:last-reviewed YYYY-MM-DD -->
+<!-- docguard:owner @your-github-username -->
+
 > **Canonical document** — Design intent. This file documents everything needed to run this project.  
 > Last updated: YYYY-MM-DD
 

package/templates/REQUIREMENTS.md.template

@@ -2,6 +2,8 @@
 
 <!-- docguard:version 0.1.0 -->
 <!-- docguard:status draft -->
+<!-- docguard:last-reviewed YYYY-MM-DD -->
+<!-- docguard:owner @your-github-username -->
 
 > Tracks functional requirements, non-functional requirements, and success criteria.
 > Use requirement IDs (FR-001, NFR-001, SC-001) for traceability back to code and tests.

package/templates/SECURITY.md.template

@@ -1,6 +1,11 @@
 # Security
 
-> **Canonical document** — Design intent. This file defines the security model.  
+<!-- docguard:version 0.1.0 -->
+<!-- docguard:status draft -->
+<!-- docguard:last-reviewed YYYY-MM-DD -->
+<!-- docguard:owner @your-github-username -->
+
+> **Canonical document** — Design intent. This file defines the security model.
 > Last updated: YYYY-MM-DD
 
 ---

package/templates/TEST-SPEC.md.template

@@ -1,5 +1,10 @@
 # Test Specification
 
+<!-- docguard:version 0.1.0 -->
+<!-- docguard:status draft -->
+<!-- docguard:last-reviewed YYYY-MM-DD -->
+<!-- docguard:owner @your-github-username -->
+
 > **Canonical document** — Design intent. This file declares what tests MUST exist.  
 > Last updated: YYYY-MM-DD