docguard-cli 0.27.0 → 0.29.0

package/cli/commands/memory.mjs

@@ -21,8 +21,12 @@
  * Zero NPM dependencies. Pure orchestration of existing diff helpers.
  */
 
+import { existsSync, readFileSync, readdirSync, mkdirSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { c } from '../shared.mjs';
 import { diffRoutes, diffEntities, diffEnvVars, diffTechStack } from './diff.mjs';
+import { buildMemoryPlan } from '../scanners/memory-plan.mjs';
+import { runGuardInternal } from './guard.mjs';
 
 /**
  * Compute an accuracy score for a single domain. Returns:
@@ -47,7 +51,118 @@ function _domainAccuracy(d) {
   };
 }
 
+// ── Context pack (v0.29) ─────────────────────────────────────────────────────
+
+/** H2 sections of AGENTS.md whose heading reads like rules/conventions/workflow. */
+function extractConventions(agentsMd, capLines = 60) {
+  const out = [];
+  const lines = agentsMd.split('\n');
+  let taking = false;
+  for (const line of lines) {
+    const h2 = line.match(/^##\s+(.+)$/);
+    if (h2) taking = /rules|conventions|workflow/i.test(h2[1]);
+    if (taking) {
+      out.push(line);
+      if (out.length >= capLines) {
+        out.push('<!-- truncated — read AGENTS.md for the full rules -->');
+        break;
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * `docguard memory --pack` — write .docguard/context-pack.md: a compact,
+ * code-truth-stamped session-start context for an AI agent. Everything in it
+ * is derived from scanners (buildMemoryPlan) and guard — numbers, not prose —
+ * so it can't hallucinate and is always regenerable.
+ */
+function runMemoryPack(projectDir, config, flags) {
+  const plan = buildMemoryPlan(projectDir, config);
+  const guard = runGuardInternal(projectDir, config);
+  const lines = [];
+
+  lines.push(`# Context Pack — ${config.projectName}`);
+  lines.push('');
+  lines.push(`<!-- Generated by \`docguard memory --pack\` ${new Date().toISOString()} — regenerate, don't edit -->`);
+  lines.push('');
+  lines.push(`**Guard:** ${guard.status} — ${guard.passed}/${guard.total} checks (${guard.errors} error(s), ${guard.warnings} warning(s))`);
+  lines.push('');
+
+  lines.push('## Code-truth surface');
+  lines.push('');
+  lines.push(`- Stack: ${plan.profile.languages.join(', ') || 'unknown'}${plan.profile.frameworks.length ? ` · ${plan.profile.frameworks.join(', ')}` : ''} · kind: ${plan.profile.kind}`);
+  lines.push(`- Modules: ${plan.surface.modules.length} · Endpoints: ${plan.surface.endpoints.length} · Entities: ${plan.surface.entities.length} · Env vars: ${plan.surface.envVars.length}`);
+  lines.push(`- Tests: ${plan.surface.tests.totalFiles} files, ${plan.surface.tests.totalCases} cases`);
+  lines.push('');
+
+  const docsDir = resolve(projectDir, 'docs-canonical');
+  if (existsSync(docsDir)) {
+    lines.push('## Canonical docs');
+    lines.push('');
+    let entries = [];
+    try { entries = readdirSync(docsDir).filter(f => f.endsWith('.md')).sort(); } catch { /* ignore */ }
+    for (const doc of entries) {
+      let reviewed = '';
+      try {
+        const m = readFileSync(resolve(docsDir, doc), 'utf-8').match(/docguard:last-reviewed\s+(\d{4}-\d{2}-\d{2})/);
+        if (m) reviewed = ` (last-reviewed ${m[1]})`;
+      } catch { /* ignore */ }
+      lines.push(`- docs-canonical/${doc}${reviewed}`);
+    }
+    lines.push('');
+  }
+
+  const agentsPath = resolve(projectDir, 'AGENTS.md');
+  if (existsSync(agentsPath)) {
+    let conventions = [];
+    try { conventions = extractConventions(readFileSync(agentsPath, 'utf-8')); } catch { /* ignore */ }
+    if (conventions.length > 0) {
+      lines.push('## Project rules (from AGENTS.md)');
+      lines.push('');
+      lines.push(...conventions);
+      lines.push('');
+    }
+  }
+
+  const driftPath = resolve(projectDir, 'DRIFT-LOG.md');
+  if (existsSync(driftPath)) {
+    try {
+      const drift = readFileSync(driftPath, 'utf-8');
+      const entries = drift.match(/^##\s+.+$/gm) || [];
+      if (entries.length > 0) {
+        lines.push('## Known drift');
+        lines.push('');
+        lines.push(`- ${entries.length} logged deviation(s); latest: ${entries[entries.length - 1].replace(/^##\s+/, '')}`);
+        lines.push('');
+      }
+    } catch { /* ignore */ }
+  }
+
+  lines.push('---');
+  lines.push('Verify claims: `docguard verify --semantic` · Full docs: `llms-full.txt`');
+  lines.push('');
+  const content = lines.join('\n');
+
+  if (flags.stdout) {
+    console.log(content);
+    return;
+  }
+  const outDir = resolve(projectDir, '.docguard');
+  if (!existsSync(outDir)) mkdirSync(outDir, { recursive: true });
+  const outPath = resolve(outDir, 'context-pack.md');
+  writeFileSync(outPath, content, 'utf-8');
+  console.log(`${c.bold}🧠 DocGuard Context Pack${c.reset}`);
+  console.log(`${c.green}✅ Wrote ${outPath}${c.reset} ${c.dim}(${lines.length} lines — load at agent session start)${c.reset}`);
+  console.log('');
+}
+
 export function runMemory(projectDir, config, flags) {
+  // v0.29: --pack writes the agent context pack and exits — a separate output
+  // artifact, not a display mode of the accuracy drill-down below.
+  if (flags.pack) return runMemoryPack(projectDir, config, flags);
+
   const isJson = flags.format === 'json';
   const wantsDiff = flags.diff || (flags.args || []).includes('--diff');
 

package/cli/commands/score.mjs

@@ -9,6 +9,8 @@ import { execSync } from 'node:child_process';
 import { c, docHasSection } from '../shared.mjs';
 import { validateSecurity } from '../validators/security.mjs';
 import { runGuardInternal } from './guard.mjs';
+import { extractSemanticClaims } from '../scanners/semantic-claims.mjs';
+import { assessAgentReadability } from '../scanners/agent-readability.mjs';
 
 /**
  * Detect whether the project configures a test runner (the "Check 3" of the
@@ -299,11 +301,17 @@ export function runScore(projectDir, config, flags) {
   console.log(`  ${c.dim}─────────────────────────────────${c.reset}`);
 
   for (const attr of alcoa.attributes) {
-    const icon = attr.met ? `${c.green}✅` : `${c.yellow}⚠️`;
-    const status = attr.met ? `${c.green}${attr.evidence}` : `${c.yellow}${attr.gap}`;
-    console.log(`  ${icon} ${attr.name.padEnd(16)}${c.reset} — ${status}${c.reset}`);
+    // `unverified` is a third state: not a green pass, but not a red gap either —
+    // "checked the structure, can't confirm the facts." Render it neutrally (🔍,
+    // cyan) so it reads as a to-do, not a failure.
+    const unverified = attr.status === 'unverified';
+    const icon = attr.met ? `${c.green}✅` : unverified ? `${c.cyan}🔍` : `${c.yellow}⚠️`;
+    const tone = attr.met ? c.green : unverified ? c.cyan : c.yellow;
+    const body = attr.met ? attr.evidence : attr.gap;
+    console.log(`  ${icon} ${attr.name.padEnd(16)}${c.reset} — ${tone}${body}${c.reset}`);
     if (!attr.met && attr.fix) {
-      console.log(`  ${c.dim}     Fix: ${attr.fix}${c.reset}`);
+      const verb = unverified ? 'Verify' : 'Fix';
+      console.log(`  ${c.dim}     ${verb}: ${attr.fix}${c.reset}`);
     }
   }
 
@@ -314,6 +322,22 @@ export function runScore(projectDir, config, flags) {
   }
   console.log('');
 
+  // ── Agent Readability (v0.29) ──
+  // Display-only, like ALCOA+ — never feeds the gating CDD grade. Answers the
+  // 2026 question: can an AI consumer FIND, QUOTE, and TRUST these docs?
+  const agentRead = assessAgentReadability(projectDir, config);
+  console.log(`  ${c.bold}🤖 Agent Readability${c.reset} ${c.dim}(how well AI consumers can read this repo)${c.reset}`);
+  console.log(`  ${c.dim}─────────────────────────────────${c.reset}`);
+  for (const m of agentRead.metrics) {
+    const icon = m.score >= 60 ? `${c.green}✅` : `${c.yellow}⚠️`;
+    const tone = m.score >= 60 ? c.green : c.yellow;
+    console.log(`  ${icon} ${m.label.padEnd(28)}${c.reset} — ${tone}${m.detail}${c.reset}`);
+    if (m.fix) console.log(`  ${c.dim}     Fix: ${m.fix}${c.reset}`);
+  }
+  const arColor = agentRead.score >= 75 ? c.green : agentRead.score >= 40 ? c.yellow : c.red;
+  console.log(`\n  ${arColor}${c.bold}Agent Readability: ${agentRead.score}% (${agentRead.grade})${c.reset}`);
+  console.log('');
+
   // Badge snippet
   const bColor = totalScore >= 90 ? 'brightgreen' : totalScore >= 80 ? 'green' : totalScore >= 70 ? 'yellowgreen' : totalScore >= 60 ? 'yellow' : totalScore >= 50 ? 'orange' : 'red';
   const badgeUrl = `https://img.shields.io/badge/CDD_Score-${totalScore}%2F100_(${grade})-${bColor}`;
@@ -411,14 +435,54 @@ function computeAlcoaCompliance(projectDir, config, scores) {
   });
 
   // 5. Accurate — Do docs match the code?
-  const accurate = scores.drift >= 80 && scores.docQuality >= 50;
-  attributes.push({
-    name: 'Accurate',
-    met: accurate,
-    evidence: accurate ? `Drift: ${scores.drift}%, doc quality: ${scores.docQuality}%` : null,
-    gap: !accurate ? `Drift: ${scores.drift}%, doc quality: ${scores.docQuality}% — docs may be inaccurate` : null,
-    fix: !accurate ? 'Run docguard diagnose to find doc/code mismatches' : null,
-  });
+  //
+  // Field report #6: this attribute used to read `met` purely from structural
+  // signals (drift markers + prose quality). That let it show ✅ "100%" while a
+  // watched doc stated a factually wrong number — the confidence-inverting false
+  // negative the field report is about. Structure passing is necessary but NOT
+  // sufficient for "accurate"; the factual claims (counts/limits/enums) have to be
+  // verified against code, and DocGuard's deterministic core can't do that — only
+  // an agent via `verify --semantic` can. So we add a third, honest state:
+  //   met        — structure sound AND no unverified factual claims exist
+  //   unverified — structure sound BUT documented claims remain unchecked vs code
+  //   unmet      — structural drift/quality below bar
+  // `unverified` counts as not-met for the ALCOA percentage (so the score stops
+  // overclaiming), but renders as a neutral 🔍 (not a ⚠️ failure) — "I haven't
+  // confirmed this," not "this is wrong." This is display-only: it never touches
+  // the gating CDD grade (totalScore), which CI thresholds read.
+  const structurallyAccurate = scores.drift >= 80 && scores.docQuality >= 50;
+  let unverifiedClaims = 0;
+  if (structurallyAccurate) {
+    try { unverifiedClaims = extractSemanticClaims(projectDir, config).length; } catch { /* extractor best-effort */ }
+  }
+  if (!structurallyAccurate) {
+    attributes.push({
+      name: 'Accurate',
+      met: false,
+      status: 'unmet',
+      evidence: null,
+      gap: `Drift: ${scores.drift}%, doc quality: ${scores.docQuality}% — docs may be inaccurate`,
+      fix: 'Run docguard diagnose to find doc/code mismatches',
+    });
+  } else if (unverifiedClaims > 0) {
+    attributes.push({
+      name: 'Accurate',
+      met: false,
+      status: 'unverified',
+      evidence: null,
+      gap: `Structure sound (drift ${scores.drift}%, quality ${scores.docQuality}%), but ${unverifiedClaims} documented claim(s) (counts/limits/enums) are unverified against code`,
+      fix: 'Run docguard verify --semantic to check the documented values against the code',
+    });
+  } else {
+    attributes.push({
+      name: 'Accurate',
+      met: true,
+      status: 'met',
+      evidence: `Drift: ${scores.drift}%, doc quality: ${scores.docQuality}%, no unverified factual claims`,
+      gap: null,
+      fix: null,
+    });
+  }
 
   // 6. Complete — Are all required docs present?
   const complete = scores.structure >= 80;

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`);
+}