docguard-cli 0.12.0 → 0.13.1

package/README.md

@@ -17,7 +17,7 @@
 - [What is DocGuard?](#what-is-docguard)
 - [Quick Start](#-quick-start)
 - [Spec Kit Integration](#-spec-kit-integration)
-- [Commands](#-commands)
+- [Usage](#usage)
 - [Validators](#-validators)
 - [Templates](#-templates)
 - [AI Agent Support](#-ai-agent-support)
@@ -343,7 +343,7 @@ DocGuard provides AI agent slash commands for integrated workflows. Installed au
 
 | Command | What It Does |
 |:--------|:-------------|
-| `/docguard.guard` | Run quality validation — check all 21 validators |
+| `/docguard.guard` | Run quality validation — check all 22 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 |

package/cli/commands/fix.mjs

@@ -21,6 +21,7 @@ import { c } from '../shared.mjs';
 import { computeApiSurfaceDrift } from '../validators/api-surface.mjs';
 import { removeEndpoints, hasGeneratedMarker } from '../writers/api-reference.mjs';
 import { applyMechanicalFixes } from '../writers/mechanical.mjs';
+import { loadFixMemory } from '../writers/fix-memory.mjs';
 import { runGuardInternal } from './guard.mjs';
 
 const API_DOC = 'docs-canonical/API-REFERENCE.md';
@@ -281,6 +282,55 @@ export function applyAllMechanicalFixes(projectDir, config, { force = false } =
   return { applied, skipped, total: fixes.length };
 }
 
+/**
+ * M-2 — `docguard fix --history` shows the audit log of mechanical fixes
+ * that have been applied to this project. Reads `.docguard/fixed.json`
+ * and pretty-prints (or emits JSON when --format json).
+ */
+function runHistoryMode(projectDir, flags) {
+  const mem = loadFixMemory(projectDir);
+  const isJson = flags.format === 'json';
+
+  if (isJson) {
+    console.log(JSON.stringify(mem, null, 2));
+    return;
+  }
+
+  if (mem.entries.length === 0) {
+    console.log(`${c.bold}🗂  DocGuard Fix History${c.reset}`);
+    console.log(`${c.dim}   No fixes recorded yet. Run \`docguard fix --write\` to start the audit log.${c.reset}`);
+    return;
+  }
+
+  console.log(`${c.bold}🗂  DocGuard Fix History${c.reset} ${c.dim}(${mem.entries.length} entries, newest first)${c.reset}\n`);
+
+  // Group by date for readability
+  const byDate = new Map();
+  for (const e of mem.entries) {
+    const day = (e.appliedAt || '').slice(0, 10);
+    if (!byDate.has(day)) byDate.set(day, []);
+    byDate.get(day).push(e);
+  }
+
+  // Show the most recent N days (cap output at 20 entries)
+  let printed = 0;
+  for (const [day, dayEntries] of byDate) {
+    if (printed >= 20) break;
+    console.log(`  ${c.cyan}${day}${c.reset} ${c.dim}(${dayEntries.length} fix${dayEntries.length > 1 ? 'es' : ''})${c.reset}`);
+    for (const e of dayEntries.slice(0, 5)) {
+      if (printed >= 20) break;
+      const time = (e.appliedAt || '').slice(11, 16);
+      console.log(`     ${c.dim}${time}${c.reset} ${e.type} → ${c.cyan}${e.file}${c.reset} ${c.dim}${e.summary || ''}${c.reset}`);
+      printed++;
+    }
+    if (dayEntries.length > 5) console.log(`     ${c.dim}... ${dayEntries.length - 5} more on this day${c.reset}`);
+  }
+
+  if (mem.entries.length > 20) {
+    console.log(`\n  ${c.dim}... ${mem.entries.length - 20} older entries. Use ${c.cyan}--format json${c.dim} for the full log.${c.reset}`);
+  }
+}
+
 function runWriteMode(projectDir, config, flags) {
   const isJson = flags.format === 'json';
   const { applied, skipped, total } = applyAllMechanicalFixes(projectDir, config, { force: flags.force });
@@ -321,6 +371,11 @@ export function runFix(projectDir, config, flags) {
   const autoFix = flags.auto || false;
   const specificDoc = flags.doc || null;
 
+  // M-2: --history shows the audit trail of past mechanical fixes.
+  if (flags.history) {
+    return runHistoryMode(projectDir, flags);
+  }
+
   // --write: deterministically APPLY mechanical fixes (no LLM). Currently:
   // remove API-REFERENCE.md endpoints the OpenAPI spec confirms no longer exist.
   if (flags.write) {

package/cli/commands/guard.mjs

@@ -10,6 +10,7 @@
 import { c, resolveSeverity } from '../shared.mjs';
 import { detectAgentMode, isSpecKitInitialized } from '../ensure-skills.mjs';
 import { checkUpgradeStatus } from './upgrade.mjs';
+import { changedFilesSince, isGitRepo } from '../shared-git.mjs';
 import { validateStructure, validateDocSections } from '../validators/structure.mjs';
 import { validateDrift } from '../validators/drift.mjs';
 import { validateChangelog } from '../validators/changelog.mjs';
@@ -27,6 +28,7 @@ import { validateMetricsConsistency } from '../validators/metrics-consistency.mj
 import { validateDocsCoverage } from '../validators/docs-coverage.mjs';
 import { validateDocQuality } from '../validators/doc-quality.mjs';
 import { validateCrossReferences } from '../validators/cross-reference.mjs';
+import { validateGeneratedStaleness } from '../validators/generated-staleness.mjs';
 import { validateTodoTracking } from '../validators/todo-tracking.mjs';
 import { validateSchemaSync } from '../validators/schema-sync.mjs';
 import { validateSpecKitIntegration } from '../scanners/speckit.mjs';
@@ -103,6 +105,7 @@ export function runGuardInternal(projectDir, config) {
     { key: 'schemaSync', name: 'Schema-Sync', fn: () => validateSchemaSync(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) },
     // Metrics-Consistency runs post-loop (needs guard results)
   ];
 
@@ -197,7 +200,7 @@ function liteValidatorsConfig() {
     'structure', 'docsSync', 'drift', 'changelog', 'testSpec', 'environment',
     'security', 'architecture', 'freshness', 'traceability', 'docsDiff',
     'apiSurface', 'metadataSync', 'docsCoverage', 'docQuality', 'todoTracking',
-    'schemaSync', 'specKit', 'crossReference', 'metricsConsistency',
+    'schemaSync', 'specKit', 'crossReference', 'generatedStaleness', 'metricsConsistency',
   ];
   const out = {};
   for (const k of all) out[k] = CHANGED_ONLY_VALIDATORS.includes(k);
@@ -212,8 +215,22 @@ export function runGuard(projectDir, config, flags) {
   // fast subset (Docs-Sync, Environment, API-Surface). Designed for husky/
   // lefthook hooks; expects to finish in under 2 seconds.
   if (flags.changedOnly) {
-    config = { ...config, validators: liteValidatorsConfig() };
-    console.log(`${c.cyan}⚡ docguard guard --changed-only${c.reset} ${c.dim}(running ${CHANGED_ONLY_VALIDATORS.length} fast validators only — pre-commit lite mode)${c.reset}\n`);
+    // Compute the set of changed files since the given ref (default HEAD~1 —
+    // the pre-commit common case: "files changed in this commit vs the last
+    // committed state"). Validators that opt into `config.changedFiles` can
+    // scope to this list; others run normally over the whole tree.
+    const ref = flags.since || 'HEAD~1';
+    const changed = isGitRepo(projectDir) ? changedFilesSince(projectDir, ref) : [];
+    config = {
+      ...config,
+      validators: liteValidatorsConfig(),
+      changedFiles: changed,
+      changedSinceRef: ref,
+    };
+    const label = changed.length > 0
+      ? `${changed.length} file(s) changed since ${ref}`
+      : `no changes since ${ref} — running all ${CHANGED_ONLY_VALIDATORS.length} lite validators on full tree`;
+    console.log(`${c.cyan}⚡ docguard guard --changed-only${c.reset} ${c.dim}(${label})${c.reset}\n`);
   }
 
   const data = runGuardInternal(projectDir, config);

package/cli/commands/impact.mjs

@@ -0,0 +1,169 @@
+/**
+ * Impact Command — S-11
+ *
+ * After a commit (or before opening a PR), shows which canonical doc
+ * sections reference any file that changed since `--since` (default HEAD~1).
+ * Combines the L-2 reverse-trace logic with the changed-files diff so you
+ * get "you should re-read these doc sections" in one command.
+ *
+ * Use cases:
+ *   - Post-commit hook: `docguard impact --since HEAD~1` runs after each
+ *     commit and reminds the developer which docs to update.
+ *   - PR prep: `docguard impact --since main` shows the doc surface area
+ *     touched by the whole branch.
+ *
+ * JSON mode emits a structured `{ changedFiles, affectedDocs }` payload
+ * for CI integrations and PR-comment bots.
+ *
+ * @req SC-S11-001 — impact reports per-file → doc mappings
+ * @req SC-S11-002 — files with no doc references are listed as "no impact"
+ * @req SC-S11-003 — --format json emits parseable structured output
+ * @req SC-S11-004 — non-code files (.md, .json, etc.) are skipped from impact analysis
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { resolve, basename } from 'node:path';
+
+import { c } from '../shared.mjs';
+import { changedFilesSince, isGitRepo } from '../shared-git.mjs';
+
+/**
+ * File extensions we consider "code" for the purposes of impact analysis.
+ * Match the set used by other validators (Docs-Sync, Freshness).
+ */
+const CODE_EXTENSIONS = /\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|rb|php|cs|swift)$/;
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Find canonical doc references for a single file. Reuses the same three
+ * match strategies as trace --reverse for consistency: direct path,
+ * basename, backticked module name.
+ */
+function findReferences(file, docs) {
+  const refs = [];
+  const normalized = file.replace(/^\.\//, '');
+  const base = basename(normalized);
+  const stem = base.replace(/\.[^.]+$/, '');
+  const stemRe = new RegExp(`\`${escapeRegex(stem)}\``);
+  for (const [docName, lines] of docs) {
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      let kind = null;
+      if (line.includes(normalized)) kind = 'path';
+      else if (line.includes(base)) kind = 'basename';
+      else if (stemRe.test(line)) kind = 'module';
+      if (kind) {
+        refs.push({ doc: docName, line: i + 1, kind });
+      }
+    }
+  }
+  return refs;
+}
+
+export function runImpact(projectDir, _config, flags) {
+  const isJson = flags.format === 'json';
+  const since = flags.since || 'HEAD~1';
+
+  if (!isGitRepo(projectDir)) {
+    if (isJson) {
+      console.log(JSON.stringify({ since, error: 'not a git repository', changedFiles: [], affectedDocs: [] }, null, 2));
+    } else {
+      console.error(`${c.red}Not a git repository — impact requires git history.${c.reset}`);
+    }
+    process.exit(1);
+  }
+
+  const changed = changedFilesSince(projectDir, since);
+  // Filter to code files only — markdown/json/yaml changes don't have "doc
+  // impact" in the same sense; they ARE the docs (or config).
+  const codeChanged = changed.filter(f => CODE_EXTENSIONS.test(f));
+
+  // Index canonical docs once
+  const docsDir = resolve(projectDir, 'docs-canonical');
+  const docsIndex = new Map(); // docName → lines[]
+  if (existsSync(docsDir)) {
+    try {
+      for (const f of readdirSync(docsDir)) {
+        if (!f.endsWith('.md')) continue;
+        try {
+          const content = readFileSync(resolve(docsDir, f), 'utf-8');
+          docsIndex.set(f, content.split('\n'));
+        } catch { /* skip unreadable */ }
+      }
+    } catch { /* skip if dir unreadable */ }
+  }
+
+  // Compute per-file references
+  const fileImpact = []; // { file, references: [{doc, line, kind}] }
+  for (const f of codeChanged) {
+    fileImpact.push({ file: f, references: findReferences(f, docsIndex) });
+  }
+
+  // Roll up: which docs are affected, with all source files
+  const docMap = new Map(); // doc → Set<file>
+  for (const { file, references } of fileImpact) {
+    for (const r of references) {
+      if (!docMap.has(r.doc)) docMap.set(r.doc, new Set());
+      docMap.get(r.doc).add(file);
+    }
+  }
+  const affectedDocs = Array.from(docMap.entries()).map(([doc, files]) => ({
+    doc,
+    files: Array.from(files),
+  }));
+
+  // ── JSON output ──
+  if (isJson) {
+    console.log(JSON.stringify({
+      since,
+      changedFiles: codeChanged,
+      ignoredFiles: changed.filter(f => !CODE_EXTENSIONS.test(f)),
+      affectedDocs,
+      timestamp: new Date().toISOString(),
+    }, null, 2));
+    return;
+  }
+
+  // ── Text output ──
+  console.log(`${c.bold}📊 DocGuard Impact${c.reset} ${c.dim}(since ${since})${c.reset}\n`);
+
+  if (changed.length === 0) {
+    console.log(`  ${c.green}✅ No file changes since ${since}.${c.reset}`);
+    return;
+  }
+  if (codeChanged.length === 0) {
+    console.log(`  ${c.dim}No code files changed (${changed.length} non-code files: ${changed.slice(0, 3).join(', ')}${changed.length > 3 ? '…' : ''}).${c.reset}`);
+    return;
+  }
+
+  console.log(`  ${c.cyan}${codeChanged.length}${c.reset} code file(s) changed.\n`);
+
+  if (affectedDocs.length === 0) {
+    console.log(`  ${c.yellow}⚠ No canonical docs reference any of the changed files.${c.reset}`);
+    console.log(`  ${c.dim}This often means the changed code is undocumented. Consider:${c.reset}`);
+    console.log(`  ${c.dim}  - Running ${c.cyan}docguard generate --plan${c.dim} to add doc skeletons${c.reset}`);
+    console.log(`  ${c.dim}  - Reviewing whether the change belongs in an existing doc${c.reset}`);
+    return;
+  }
+
+  console.log(`  ${c.green}${affectedDocs.length}${c.reset} canonical doc(s) reference the changed files:\n`);
+  for (const { doc, files } of affectedDocs) {
+    console.log(`  ${c.cyan}${doc}${c.reset} ${c.dim}(${files.length} file${files.length > 1 ? 's' : ''})${c.reset}`);
+    for (const f of files.slice(0, 5)) {
+      console.log(`     ${c.dim}via${c.reset} ${f}`);
+    }
+    if (files.length > 5) console.log(`     ${c.dim}... ${files.length - 5} more${c.reset}`);
+  }
+
+  // List code files with NO doc references — these may need new docs
+  const orphaned = fileImpact.filter(fi => fi.references.length === 0).map(fi => fi.file);
+  if (orphaned.length > 0) {
+    console.log(`\n  ${c.yellow}${orphaned.length} changed file(s) have NO canonical doc reference:${c.reset}`);
+    for (const f of orphaned.slice(0, 5)) console.log(`     ${c.dim}• ${f}${c.reset}`);
+    if (orphaned.length > 5) console.log(`     ${c.dim}... ${orphaned.length - 5} more${c.reset}`);
+    console.log(`  ${c.dim}These may be undocumented — review whether they belong in an existing doc.${c.reset}`);
+  }
+}

package/cli/commands/sync.mjs

@@ -34,6 +34,48 @@ function gitChangedFiles(projectDir, since) {
   return [...new Set([...committed, ...working])];
 }
 
+/**
+ * L-1: Map each `source: 'code'` section ID to a predicate that returns true
+ * when one of the changed file paths could plausibly affect it. Conservative
+ * by design — when in doubt we run the section's sync, never skip it.
+ *
+ * The predicates are matched against project-relative POSIX paths (the form
+ * `git diff --name-only` returns).
+ */
+const SECTION_FILE_MATCHERS = {
+  'tech-stack':        (p) => /package\.json$|pyproject\.toml$|Cargo\.toml$|go\.mod$|pom\.xml$|Gemfile$/.test(p),
+  'frontend-modules':  (p) => /(^|\/)(src\/)?(stores|hooks|contexts|features)\//.test(p),
+  'endpoints-table':   (p) => /(^|\/)(routes|controllers|handlers|app\/api)\//.test(p)
+                              || /\.(yaml|yml|json)$/i.test(p) && /openapi|swagger/i.test(p),
+  'entities-table':    (p) => /(^|\/)(models|schemas|entities)\//.test(p)
+                              || /\.prisma$/.test(p),
+  'relationships':     (p) => /(^|\/)(models|schemas|entities)\//.test(p)
+                              || /\.prisma$/.test(p),
+  'screens-table':     (p) => /(^|\/)(screens|pages|app)\//.test(p)
+                              || /\.(tsx|jsx)$/.test(p),
+  'flows':             (p) => /(^|\/)(screens|pages|app|routes)\//.test(p),
+  'integrations-table':(p) => /package\.json$|pyproject\.toml$|requirements.*\.txt$|Cargo\.toml$/.test(p),
+  'features-table':    (p) => /(^|\/)(features|domains)\//.test(p),
+  'features':          (p) => /(^|\/)(features|domains)\//.test(p),
+  'env-vars-table':    (p) => /\.env(\..+)?$|(^|\/)config\//.test(p)
+                              || /\.(ts|tsx|js|jsx|mjs|py|go|rs|java|kt|rb)$/.test(p), // any code may use env
+  'setup':             (p) => /\.env(\..+)?$|(^|\/)config\//.test(p),
+};
+
+/**
+ * Decide whether a given code-truth section should be re-synced based on the
+ * set of changed files. Returns true when:
+ *   - changedFiles is null/empty (no scope info → sync everything), OR
+ *   - any changed file matches the section's known source patterns, OR
+ *   - the section has no matcher registered (unknown → conservative: sync)
+ */
+function sectionTouchedByChanges(sectionId, changedFiles) {
+  if (!changedFiles || changedFiles.length === 0) return true;
+  const matcher = SECTION_FILE_MATCHERS[sectionId];
+  if (!matcher) return true; // unknown section → don't accidentally skip it
+  return changedFiles.some(matcher);
+}
+
 export function runSync(projectDir, config, flags) {
   const plan = buildMemoryPlan(projectDir, config);
   const apply = !!flags.write;
@@ -63,6 +105,14 @@ export function runSync(projectDir, config, flags) {
       const existing = getSection(content, sec.id);
       if (!existing) continue; // sync refreshes sections that already exist
       if (existing.body.trim() === String(sec.body).trim()) continue; // already current
+      // L-1: when --since is provided, only update sections whose underlying
+      // source files appear in the changed set. Avoids spurious updates when
+      // the section's CONTENT would naturally drift (e.g. timestamp-driven
+      // counters) but no real source file changed.
+      if (changed !== null && !sectionTouchedByChanges(sec.id, changed)) {
+        skipped.push({ doc: doc.path, reason: `section ${sec.id} unchanged since ${flags.since} (no underlying source files in diff)` });
+        continue;
+      }
       codeSectionChanged = true;
       updates.push({ doc: doc.path, section: sec.id, status: apply ? 'updated' : 'stale' });
       if (apply) { content = replaceSection(content, sec.id, sec.body).content; docChanged = true; }

package/cli/commands/trace.mjs

@@ -84,7 +84,112 @@ const TRACE_MAP = {
   },
 };
 
+/**
+ * L-2 / S-3 — Reverse trace: given a code file, find which canonical doc
+ * sections mention it. Mirror of the forward trace (doc → code).
+ *
+ * Match strategies (each yields a hit):
+ *   1. Direct path match: full project-relative path appears in doc text.
+ *   2. Basename match: e.g. `users.ts` appears (covers cases where the doc
+ *      refers to the file by name without the full path).
+ *   3. Module name match: file stem (e.g. `users`) appears as a fenced
+ *      `code` reference. Tighter than 2 — avoids matching common nouns.
+ *
+ * Output: one line per (doc, match-line) pair, with the surrounding context.
+ */
+export function runTraceReverse(projectDir, config, flags) {
+  const target = flags.args && flags.args[0];
+  if (!target) {
+    console.error(`${c.red}Error: trace --reverse requires a target path${c.reset}`);
+    console.log(`Usage: ${c.cyan}docguard trace --reverse <code-path>${c.reset}`);
+    console.log(`Example: ${c.cyan}docguard trace --reverse src/routes/users.ts${c.reset}`);
+    process.exit(1);
+  }
+
+  // Suppress chrome in JSON mode so stdout stays parseable.
+  const isJson = flags.format === 'json';
+  if (!isJson) {
+    console.log(`${c.bold}🔄 DocGuard Trace (reverse) — ${target}${c.reset}`);
+    console.log(`${c.dim}   Finding canonical doc sections that reference this file...${c.reset}\n`);
+  }
+
+  const docsDir = resolve(projectDir, 'docs-canonical');
+  if (!existsSync(docsDir)) {
+    if (isJson) {
+      console.log(JSON.stringify({ target, matches: [], error: 'no docs-canonical/ directory' }, null, 2));
+    } else {
+      console.log(`  ${c.yellow}No docs-canonical/ directory found.${c.reset}`);
+    }
+    return;
+  }
+
+  // Normalize the target path: strip leading ./
+  const normalized = target.replace(/^\.\//, '');
+  const base = basename(normalized);
+  const stem = base.replace(/\.[^.]+$/, '');
+
+  const matches = []; // { doc, line, content, kind }
+  for (const f of readdirSync(docsDir)) {
+    if (!f.endsWith('.md')) continue;
+    const docPath = resolve(docsDir, f);
+    let content;
+    try { content = readFileSync(docPath, 'utf-8'); } catch { continue; }
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      let kind = null;
+      if (line.includes(normalized)) kind = 'path';
+      else if (line.includes(base)) kind = 'basename';
+      else if (new RegExp(`\`${escapeRegex(stem)}\``).test(line)) kind = 'module';
+      if (kind) {
+        matches.push({ doc: f, line: i + 1, content: line.trim(), kind });
+      }
+    }
+  }
+
+  if (flags.format === 'json') {
+    console.log(JSON.stringify({
+      target: normalized,
+      matches,
+      timestamp: new Date().toISOString(),
+    }, null, 2));
+    return;
+  }
+
+  if (matches.length === 0) {
+    console.log(`  ${c.yellow}⚠️  No canonical doc references "${normalized}"${c.reset}`);
+    console.log(`  ${c.dim}Consider documenting this file in docs-canonical/ARCHITECTURE.md or DATA-MODEL.md${c.reset}`);
+    return;
+  }
+
+  // Group by doc for readable output
+  const byDoc = new Map();
+  for (const m of matches) {
+    if (!byDoc.has(m.doc)) byDoc.set(m.doc, []);
+    byDoc.get(m.doc).push(m);
+  }
+
+  console.log(`  ${c.green}✅ ${matches.length} reference(s) across ${byDoc.size} doc(s):${c.reset}\n`);
+  for (const [doc, hits] of byDoc) {
+    console.log(`  ${c.cyan}${doc}${c.reset} ${c.dim}(${hits.length} hit${hits.length > 1 ? 's' : ''})${c.reset}`);
+    for (const h of hits.slice(0, 5)) {
+      const trimmed = h.content.length > 80 ? h.content.slice(0, 77) + '…' : h.content;
+      console.log(`     ${c.dim}L${h.line} [${h.kind}]${c.reset} ${trimmed}`);
+    }
+    if (hits.length > 5) console.log(`     ${c.dim}... ${hits.length - 5} more${c.reset}`);
+  }
+}
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
 export function runTrace(projectDir, config, flags) {
+  // L-2: dispatch to reverse mode when --reverse is set.
+  if (flags.reverse) {
+    return runTraceReverse(projectDir, config, flags);
+  }
+
   console.log(`${c.bold}🔗 DocGuard Trace — ${config.projectName}${c.reset}`);
   console.log(`${c.dim}   Directory: ${projectDir}${c.reset}`);
   console.log(`${c.dim}   Generating requirements traceability matrix...${c.reset}\n`);

package/cli/docguard.mjs

@@ -41,6 +41,7 @@ import { runTrace } from './commands/trace.mjs';
 import { runLlms } from './commands/llms.mjs';
 import { runSetup } from './commands/setup.mjs';
 import { runUpgrade } from './commands/upgrade.mjs';
+import { runImpact } from './commands/impact.mjs';
 import { ensureSkills } from './ensure-skills.mjs';
 
 // ── Shared constants (imported to break circular dependencies) ──────────
@@ -381,6 +382,15 @@ async function main() {
       flags.apply = true;
     } else if (args[i] === '--changed-only') {
       flags.changedOnly = true;
+    } else if (args[i] === '--reverse') {
+      flags.reverse = true;
+    } else if (args[i] === '--history') {
+      flags.history = true;
+    } else if (!args[i].startsWith('--') && i > 0) {
+      // Positional args go into flags.args for commands that take them (e.g.
+      // `docguard trace --reverse <path>`). Skip the command itself (i === 0).
+      flags.args = flags.args || [];
+      flags.args.push(args[i]);
     } else if (args[i] === '--doc' && args[i + 1]) {
       flags.doc = args[i + 1];
       i++;
@@ -505,6 +515,9 @@ async function main() {
     case 'update':
       await runUpgrade(projectDir, config, flags);
       break;
+    case 'impact':
+      runImpact(projectDir, config, flags);
+      break;
     default:
       console.error(`${c.red}Unknown command: ${command}${c.reset}`);
       console.log(`Run ${c.cyan}docguard --help${c.reset} for usage.`);

package/cli/validators/cross-reference.mjs

@@ -155,14 +155,103 @@ export function extractRefs(content, sourcePath) {
  * Resolve a target file path relative to a source markdown file.
  * Returns the absolute path or null if the file doesn't exist.
  */
+/**
+ * S-12: Suggest the closest matching anchor when a broken-anchor warning
+ * fires. Uses a cheap two-pass match:
+ *   1. Exact substring match (anchor is contained in or contains a heading)
+ *   2. Levenshtein-like edit-distance within a budget (max 3 edits)
+ *
+ * Returns the best-matching slug string, or null when no candidate scores
+ * well enough to suggest with confidence. Suggestion threshold tuned so
+ * cosmetic typos surface but unrelated headings don't false-positive.
+ *
+ * @param {string} broken - the slug the user wrote (e.g. "athena-setup")
+ * @param {Set<string>} candidates - anchors that exist in the target doc
+ * @returns {string|null}
+ */
+export function suggestAnchor(broken, candidates) {
+  if (!broken || !candidates || candidates.size === 0) return null;
+
+  // Pass 1: substring containment — high-confidence match. Both sides must
+  // be at least 4 chars to avoid spurious matches against very short anchors
+  // (e.g. `#a` would otherwise match any broken slug containing the letter a).
+  const MIN_SUBSTRING = 4;
+  for (const c of candidates) {
+    if (c.length < MIN_SUBSTRING || broken.length < MIN_SUBSTRING) continue;
+    if (c.startsWith(broken) || broken.startsWith(c) || c.includes(broken) || broken.includes(c)) {
+      // Additionally require >= 50% overlap of the shorter into the longer.
+      // Avoids "user-id" matching "user-management-and-administration" via
+      // the bare "user" prefix.
+      const overlap = Math.min(c.length, broken.length) / Math.max(c.length, broken.length);
+      if (overlap >= 0.5) return c;
+    }
+  }
+
+  // Pass 2: edit distance — pick the closest if within budget.
+  let best = null;
+  let bestDist = Infinity;
+  for (const c of candidates) {
+    // Cheap early-out: huge length difference can't be within budget.
+    if (Math.abs(c.length - broken.length) > 8) continue;
+    const d = editDistance(broken, c);
+    if (d < bestDist) { bestDist = d; best = c; }
+  }
+  // Budget: max(3, length / 5) — proportional to slug length but cap small.
+  const budget = Math.max(3, Math.floor(broken.length / 5));
+  if (bestDist <= budget) return best;
+  return null;
+}
+
+/**
+ * Levenshtein edit distance. O(m·n) time, O(min) space. We bound input
+ * size before calling (S-12's pass 2 pre-filters), so a textbook impl is
+ * fine. Adding a dependency for one cheap routine isn't worth it.
+ */
+function editDistance(a, b) {
+  if (a === b) return 0;
+  if (!a.length) return b.length;
+  if (!b.length) return a.length;
+  let prev = new Array(b.length + 1);
+  let curr = new Array(b.length + 1);
+  for (let j = 0; j <= b.length; j++) prev[j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(
+        prev[j] + 1,        // deletion
+        curr[j - 1] + 1,    // insertion
+        prev[j - 1] + cost, // substitution
+      );
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[b.length];
+}
+
 function resolveTarget(sourcePath, targetRel, projectDir) {
   if (!targetRel) return null;
-  // Try relative to source's directory first
-  const fromSource = resolve(dirname(sourcePath), targetRel);
-  if (existsSync(fromSource)) return fromSource;
-  // Also try from project root (some authors write `docs-canonical/X.md`)
-  const fromRoot = resolve(projectDir, targetRel);
-  if (existsSync(fromRoot)) return fromRoot;
+  // B-6: try BOTH the literal path and the URL-decoded form. CommonMark
+  // accepts `[name](../WU%20Documentation/foo.md)` for paths with spaces,
+  // and the decoded form (`../WU Documentation/foo.md`) is what hits the
+  // filesystem. The angle-bracket form `<../WU Documentation/foo.md>` is
+  // already non-URL-encoded by the time it reaches us. Try literal first
+  // (handles paths that legitimately contain `%`), then decoded.
+  const candidates = [targetRel];
+  try {
+    const decoded = decodeURIComponent(targetRel);
+    if (decoded !== targetRel) candidates.push(decoded);
+  } catch {
+    // Malformed % escapes — fall back to literal-only.
+  }
+  for (const cand of candidates) {
+    // Try relative to source's directory first
+    const fromSource = resolve(dirname(sourcePath), cand);
+    if (existsSync(fromSource)) return fromSource;
+    // Also try from project root (some authors write `docs-canonical/X.md`)
+    const fromRoot = resolve(projectDir, cand);
+    if (existsSync(fromRoot)) return fromRoot;
+  }
   return null;
 }
 
@@ -183,7 +272,15 @@ function collectCanonicalDocs(projectDir) {
       }
     } catch {}
   }
-  for (const f of ['AGENTS.md', 'CHANGELOG.md', 'DRIFT-LOG.md', 'ROADMAP.md', 'README.md']) {
+  // Standard root-level docs that are commonly cross-referenced. We index
+  // them so links like [CONTRIBUTING.md](CONTRIBUTING.md#some-section) can
+  // resolve. The list is conservative — adding everything would pull in
+  // boilerplate (LICENSE, NOTICE) that doesn't have meaningful headings.
+  for (const f of [
+    'README.md', 'AGENTS.md', 'CHANGELOG.md', 'DRIFT-LOG.md', 'ROADMAP.md',
+    'CONTRIBUTING.md', 'CODE_OF_CONDUCT.md', 'SECURITY.md',
+    'PHILOSOPHY.md', 'STANDARD.md', 'COMPARISONS.md',
+  ]) {
     const p = resolve(projectDir, f);
     if (existsSync(p)) docs.push(p);
   }
@@ -266,8 +363,13 @@ export function validateCrossReferences(projectDir, _config = {}) {
         const matches = anchors && (anchors.has(ref.anchor) || anchors.has(normalizedAnchor));
         if (!matches) {
           const where = targetPath === docPath ? 'same doc' : basename(targetPath);
+          // S-12: suggest the closest matching anchor when there's a near-miss.
+          // Three of five wu user-fixes were "heading renamed, link not updated"
+          // — a suggested-slug hint makes those deterministic-fixable.
+          const suggestion = anchors ? suggestAnchor(normalizedAnchor, anchors) : null;
+          const hint = suggestion ? ` (did you mean #${suggestion}?)` : '';
           warnings.push(
-            `${docName}:${ref.line} — broken anchor: "#${ref.anchor}" in ${where} doesn't match any heading`
+            `${docName}:${ref.line} — broken anchor: "#${ref.anchor}" in ${where} doesn't match any heading${hint}`
           );
           continue;
         }

package/cli/validators/docs-sync.mjs

@@ -80,6 +80,17 @@ export function validateDocsSync(projectDir, config) {
     return results; // No canonical docs to check against
   }
 
+  // N-1: When the guard runs in --changed-only mode, config.changedFiles is
+  // populated with paths that changed since the given ref. We use it to scope
+  // route/service checks to ONLY the files actually changed — turning a
+  // whole-tree scan into a surgical check. If the list is empty (no changes,
+  // or git unavailable), we fall back to scanning everything.
+  const changedSet = config && Array.isArray(config.changedFiles) && config.changedFiles.length > 0
+    ? new Set(config.changedFiles)
+    : null;
+  // Closure: true if the given relative path should be considered.
+  const inScope = (relPath) => !changedSet || changedSet.has(relPath);
+
   // Find route/API files (monorepo-aware) and check they're mentioned in docs.
   // Note: bare 'api' is intentionally excluded — it collides with frontend
   // API client conventions (src/api/client.ts). Backend routes use
@@ -95,6 +106,8 @@ export function validateDocsSync(projectDir, config) {
       const relPath = file.replace(projectDir + '/', '');
       if (isTestFile(relPath)) continue;
       if (!isValidRouteFile(relPath)) continue;
+      // N-1: skip files outside the --changed-only scope.
+      if (!inScope(relPath)) continue;
 
       results.total++;
       const name = basename(file, ext);
@@ -118,6 +131,8 @@ export function validateDocsSync(projectDir, config) {
 
       const relPath = file.replace(projectDir + '/', '');
       if (isTestFile(relPath)) continue;
+      // N-1: skip files outside the --changed-only scope.
+      if (!inScope(relPath)) continue;
 
       results.total++;
       const name = basename(file, ext);

package/cli/validators/freshness.mjs

@@ -10,6 +10,24 @@ import { existsSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, extname } from 'node:path';
 import { execSync, execFileSync } from 'node:child_process';
 
+// B-5 fix (v0.13.1): use a defensive import. If `shared-git.mjs` is missing
+// or unloadable in the end-user install (whatever the root cause — partial
+// upgrade, package corruption, weird module resolution), we fall back to
+// the original inline implementation below. The worst-case outcome is
+// "rename detection doesn't work", NOT "validator crashes with a useless
+// ReferenceError". Reported by wu-whatsappinbox v0.13.x feedback.
+let _sharedGetLastCommitDate = null;
+try {
+  const mod = await import('../shared-git.mjs');
+  if (mod && typeof mod.getLastCommitDate === 'function') {
+    _sharedGetLastCommitDate = mod.getLastCommitDate;
+  }
+} catch {
+  // Silently fall back. Test in tests/freshness-resilience.test.mjs verifies
+  // the validator stays operational when the import goes sideways.
+  _sharedGetLastCommitDate = null;
+}
+
 const IGNORE_DIRS = new Set([
   'node_modules', '.git', '.next', 'dist', 'build',
   'coverage', '.cache', '__pycache__', '.venv', 'vendor',
@@ -21,6 +39,19 @@ const IGNORE_DIRS = new Set([
  * Returns null if the file isn't tracked or git isn't available.
  */
 function getLastGitDate(filePath, dir) {
+  // Prefer the shared-git --follow-aware path when available (v0.13+ default).
+  // Fall back to inline implementation if the import failed at module load —
+  // this guarantees the validator never throws a ReferenceError even in
+  // environments where ESM resolution is broken.
+  if (_sharedGetLastCommitDate) {
+    try {
+      return _sharedGetLastCommitDate(dir, filePath);
+    } catch {
+      // fall through to inline
+    }
+  }
+  // Inline pre-v0.13 implementation — works without rename detection, but
+  // is guaranteed to not throw a "not defined" error.
   try {
     const result = execFileSync(
       'git',

package/cli/validators/generated-staleness.mjs

@@ -0,0 +1,152 @@
+/**
+ * Generated-Doc Staleness Validator — M-1 / S-7
+ *
+ * Re-runs the memory-plan scanner and compares each `source=code` section's
+ * expected body against what's actually committed in the canonical docs.
+ * Flags sections where the doc says one thing but the scanner produces
+ * another — that's drift, and it means either:
+ *   (a) Code changed and `docguard sync --write` hasn't been run, OR
+ *   (b) Someone hand-edited a code-truth section (which shouldn't happen —
+ *       human prose belongs in source=human sections).
+ *
+ * Why this matters: K-1's auto-fix Action runs `fix --write` (mechanical
+ * fixes) but doesn't run `sync --write` (memory refresh). Projects that
+ * skip the nightly sync recipe accumulate hidden drift in source=code
+ * sections. This validator surfaces it as a warning so CI can catch it.
+ *
+ * Cheap: just diffs in-memory strings; no extra git or filesystem walk
+ * beyond what memory-plan already does.
+ *
+ * @req SC-M1-001 — flag source=code sections whose body differs from scanner output
+ * @req SC-M1-002 — no warning when sections match
+ * @req SC-M1-003 — N/A when no canonical docs exist
+ * @req SC-M1-004 — N/A when no source=code sections present in any doc
+ */
+
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { resolve, basename } from 'node:path';
+
+import { buildMemoryPlan } from '../scanners/memory-plan.mjs';
+import { getSection } from '../writers/sections.mjs';
+
+/**
+ * S-7: how long a generated doc may sit in `status: draft` before we warn.
+ * 14 days is the v0.13.1 default — long enough to absorb a typical sprint,
+ * short enough to surface forgotten skeletons before they rot.
+ */
+const DRAFT_STALENESS_DAYS = 14;
+
+/**
+ * Parse the frontmatter `status:` field from a markdown doc.
+ * Returns the trimmed value or null. Tolerant of either YAML-style
+ * fences (`---`) or HTML-comment-style (`<!-- status: draft -->`) markers.
+ */
+function extractDocStatus(content) {
+  if (!content) return null;
+  // YAML frontmatter: --- ... ---
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  if (fmMatch) {
+    const sm = fmMatch[1].match(/^\s*status:\s*(\S+)\s*$/m);
+    if (sm) return sm[1].toLowerCase();
+  }
+  // Inline `<!-- status: draft -->` marker (common in docguard:generated docs).
+  const inline = content.match(/<!--\s*status:\s*(\w+)\s*-->/i);
+  if (inline) return inline[1].toLowerCase();
+  return null;
+}
+
+export function validateGeneratedStaleness(projectDir, config = {}) {
+  const result = { errors: [], warnings: [], passed: 0, total: 0 };
+
+  // Build the canonical memory plan (what the docs SHOULD contain). If this
+  // fails or produces no docs, the validator is N/A.
+  let plan;
+  try {
+    plan = buildMemoryPlan(projectDir, config);
+  } catch {
+    return { ...result, applicable: false };
+  }
+  if (!plan || !Array.isArray(plan.docs) || plan.docs.length === 0) {
+    return { ...result, applicable: false };
+  }
+
+  // Walk each doc's source=code sections and compare against on-disk content.
+  let anySourceCodeSection = false;
+  const draftThresholdDays = (config.draftStalenessDays != null)
+    ? Number(config.draftStalenessDays)
+    : DRAFT_STALENESS_DAYS;
+
+  for (const doc of plan.docs) {
+    const fullPath = resolve(projectDir, doc.path);
+    if (!existsSync(fullPath)) continue;
+    let content;
+    try { content = readFileSync(fullPath, 'utf-8'); } catch { continue; }
+
+    // S-7: a docguard:generated doc with frontmatter `status: draft` that
+    // hasn't been updated in N days is probably a forgotten skeleton.
+    // Counted as a check (so total reflects it) and warned when stale.
+    const status = extractDocStatus(content);
+    if (status === 'draft') {
+      result.total++;
+      try {
+        const mtime = statSync(fullPath).mtime;
+        const ageDays = (Date.now() - mtime.getTime()) / (1000 * 60 * 60 * 24);
+        if (ageDays > draftThresholdDays) {
+          result.warnings.push(
+            `${basename(doc.path)} has been in \`status: draft\` for ${Math.floor(ageDays)} days. ` +
+            `Promote to status:current or remove. Run \`/docguard.fix --doc ${basename(doc.path)}\` to draft the prose.`
+          );
+        } else {
+          result.passed++;
+        }
+      } catch {
+        // Couldn't stat the file — skip the staleness check, don't count it.
+        result.total--;
+      }
+    }
+
+    for (const sec of doc.sections) {
+      if (sec.source !== 'code') continue;
+      anySourceCodeSection = true;
+
+      const onDisk = getSection(content, sec.id);
+      // If the section isn't present in the doc at all, that's a Structure /
+      // Doc Sections concern — not ours. Skip without counting.
+      if (!onDisk) continue;
+
+      result.total++;
+      const expected = String(sec.body || '').trim();
+      const actual = String(onDisk.body || '').trim();
+
+      if (expected === actual) {
+        result.passed++;
+        continue;
+      }
+
+      // Compute a short diff hint — first changed line — so the warning is
+      // actionable without dumping the whole section.
+      const exp = expected.split('\n');
+      const act = actual.split('\n');
+      let firstDiff = -1;
+      for (let i = 0; i < Math.max(exp.length, act.length); i++) {
+        if (exp[i] !== act[i]) { firstDiff = i; break; }
+      }
+      const hint = firstDiff >= 0
+        ? ` (first drift at line ${firstDiff + 1} of section: "${(act[firstDiff] || '').slice(0, 60)}…" vs scanner: "${(exp[firstDiff] || '').slice(0, 60)}…")`
+        : '';
+
+      result.warnings.push(
+        `${basename(doc.path)} → section "${sec.id}" is stale${hint}. Run \`docguard sync --write\` to refresh code-truth sections.`
+      );
+    }
+  }
+
+  // S-7: even when no source=code sections exist, a draft-status check
+  // counts the validator as applicable. Only return N/A when we genuinely
+  // had nothing to evaluate.
+  if (!anySourceCodeSection && result.total === 0) {
+    return { ...result, applicable: false };
+  }
+
+  return result;
+}

package/cli/validators/structure.mjs

@@ -19,23 +19,33 @@ export function validateStructure(projectDir, config) {
     }
   }
 
-  // Check agent file (any one is fine)
-  results.total++;
-  const agentFileFound = config.requiredFiles.agentFile.some(f =>
-    existsSync(resolve(projectDir, f))
-  );
-  if (agentFileFound) {
-    results.passed++;
-  } else {
-    results.errors.push(`Missing agent file: ${config.requiredFiles.agentFile.join(' or ')}`);
+  // Check agent file (any one is fine) — defensive: tolerate missing config
+  // shapes (B-5 class of safety net: never let a config gap leak as a
+  // ReferenceError / TypeError into the user's guard output).
+  const agentFiles = Array.isArray(config.requiredFiles?.agentFile)
+    ? config.requiredFiles.agentFile
+    : (typeof config.requiredFiles?.agentFile === 'string' ? [config.requiredFiles.agentFile] : []);
+  if (agentFiles.length > 0) {
+    results.total++;
+    const agentFileFound = agentFiles.some(f =>
+      existsSync(resolve(projectDir, f))
+    );
+    if (agentFileFound) {
+      results.passed++;
+    } else {
+      results.errors.push(`Missing agent file: ${agentFiles.join(' or ')}`);
+    }
   }
 
-  // Check changelog
-  results.total++;
-  if (existsSync(resolve(projectDir, config.requiredFiles.changelog))) {
-    results.passed++;
-  } else {
-    results.errors.push(`Missing required file: ${config.requiredFiles.changelog}`);
+  // Check changelog — same defensive pattern.
+  const changelogPath = config.requiredFiles?.changelog;
+  if (changelogPath) {
+    results.total++;
+    if (existsSync(resolve(projectDir, changelogPath))) {
+      results.passed++;
+    } else {
+      results.errors.push(`Missing required file: ${changelogPath}`);
+    }
   }
 
   // Check drift log

package/cli/writers/fix-memory.mjs

@@ -0,0 +1,133 @@
+/**
+ * Fix Memory — M-2 / S-10
+ *
+ * Persists a JSON log of every mechanical fix `docguard fix --write` applies,
+ * stored at `.docguard/fixed.json`. Two purposes:
+ *
+ *   1. **Audit trail.** Users (and reviewers) can ask "what did the bot
+ *      change in this repo and when?" without digging through git history.
+ *      Especially valuable for the K-1 auto-fix Action which commits as
+ *      `docguard-bot` — the memory file is the human-readable record.
+ *
+ *   2. **Future suppression hook.** A future `fix --write` can check the
+ *      memory and skip fixes that were applied and then reverted — avoiding
+ *      ping-pong loops where the bot keeps re-applying a fix the user keeps
+ *      undoing. For v0.13 we just record; suppression is v0.14+.
+ *
+ * Format (JSON, gitignore-friendly):
+ *   {
+ *     "schemaVersion": "1",
+ *     "entries": [
+ *       {
+ *         "id": "<sha256 of type+file+before+after, first 12 chars>",
+ *         "type": "replace-version",
+ *         "file": "README.md",
+ *         "summary": "v0.11.2 → v0.12.0",
+ *         "appliedAt": "2026-05-26T01:35:00Z",
+ *         "appliedBy": "fix --write" | "sync --write" | "docguard-bot"
+ *       }
+ *     ]
+ *   }
+ *
+ * The file is intentionally small (no full before/after content) to stay
+ * checkable into git for teams that want the audit trail under version
+ * control. Capped at 500 entries (rolling).
+ *
+ * @req SC-M2-001 — loadFixMemory returns an empty array when no file exists
+ * @req SC-M2-002 — appendFixes creates .docguard/ if needed
+ * @req SC-M2-003 — appendFixes is idempotent (same fix logged twice → one entry)
+ * @req SC-M2-004 — fingerprint dedupes by type+file+summary (not timestamp)
+ * @req SC-M2-005 — entries are capped at MAX_ENTRIES (oldest dropped)
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { createHash } from 'node:crypto';
+
+const MEMORY_PATH = '.docguard/fixed.json';
+const SCHEMA_VERSION = '1';
+const MAX_ENTRIES = 500;
+
+/**
+ * Compute a stable fingerprint for a fix. Used for dedup — two fixes with
+ * the same type+file+summary are considered the same operation, even if
+ * applied at different times.
+ */
+export function fingerprintFix(fix) {
+  const key = `${fix.type || ''}|${fix.file || ''}|${fix.summary || ''}`;
+  return createHash('sha256').update(key).digest('hex').slice(0, 12);
+}
+
+/**
+ * Load the fix memory from disk. Returns { schemaVersion, entries } —
+ * always a valid shape, even if the file is missing or malformed.
+ */
+export function loadFixMemory(projectDir) {
+  const p = resolve(projectDir, MEMORY_PATH);
+  if (!existsSync(p)) {
+    return { schemaVersion: SCHEMA_VERSION, entries: [] };
+  }
+  try {
+    const data = JSON.parse(readFileSync(p, 'utf-8'));
+    if (!data || !Array.isArray(data.entries)) {
+      return { schemaVersion: SCHEMA_VERSION, entries: [] };
+    }
+    return { schemaVersion: data.schemaVersion || SCHEMA_VERSION, entries: data.entries };
+  } catch {
+    return { schemaVersion: SCHEMA_VERSION, entries: [] };
+  }
+}
+
+/**
+ * Append fixes to the memory file. Dedupes by fingerprint — re-applying the
+ * same fix updates the existing entry's appliedAt instead of adding a row.
+ *
+ * `fixes` is an array of { type, file, summary } objects. The function adds
+ * `id` + `appliedAt` + `appliedBy` automatically.
+ *
+ * Returns the updated memory object.
+ */
+export function appendFixes(projectDir, fixes, appliedBy = 'fix --write') {
+  if (!Array.isArray(fixes) || fixes.length === 0) {
+    return loadFixMemory(projectDir);
+  }
+  const mem = loadFixMemory(projectDir);
+  const now = new Date().toISOString();
+  const byId = new Map(mem.entries.map(e => [e.id, e]));
+
+  for (const f of fixes) {
+    const id = fingerprintFix(f);
+    const entry = {
+      id,
+      type: f.type || 'unknown',
+      file: f.file || '',
+      summary: f.summary || '',
+      appliedAt: now,
+      appliedBy,
+    };
+    byId.set(id, entry); // overwrites prior with same fingerprint → updates appliedAt
+  }
+
+  let entries = Array.from(byId.values());
+  // Sort newest-first so the cap drops the oldest.
+  entries.sort((a, b) => (b.appliedAt || '').localeCompare(a.appliedAt || ''));
+  if (entries.length > MAX_ENTRIES) entries = entries.slice(0, MAX_ENTRIES);
+
+  const next = { schemaVersion: SCHEMA_VERSION, entries };
+
+  const fullPath = resolve(projectDir, MEMORY_PATH);
+  const dir = dirname(fullPath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(fullPath, JSON.stringify(next, null, 2) + '\n', 'utf-8');
+
+  return next;
+}
+
+/**
+ * True if a candidate fix (by fingerprint) has been applied before.
+ * Currently informational — future versions may use this to suppress.
+ */
+export function isFixRecorded(projectDir, candidate) {
+  const id = fingerprintFix(candidate);
+  return loadFixMemory(projectDir).entries.some(e => e.id === id);
+}

package/cli/writers/mechanical.mjs

@@ -102,6 +102,12 @@ export function applyMechanicalFix(projectDir, fix, opts = {}) {
 
 /**
  * Apply a batch of fixes; returns a summary.
+ *
+ * M-2: When `opts.recordHistory` is true (default true when not in dry-run),
+ * each successfully applied fix is appended to `.docguard/fixed.json` so
+ * the project has a persistent audit trail. Pass `recordHistory: false` to
+ * disable (used by dry-run tests).
+ *
  * @returns {{ applied: object[], skipped: object[] }}
  */
 export function applyMechanicalFixes(projectDir, fixes, opts = {}) {
@@ -112,5 +118,21 @@ export function applyMechanicalFixes(projectDir, fixes, opts = {}) {
     if (r.applied) applied.push({ ...fix, detail: r.detail });
     else if (r.skipped) skipped.push({ ...fix, reason: r.skipped });
   }
+
+  if (applied.length > 0 && opts.recordHistory !== false) {
+    // Lazy-import to avoid the circular risk and keep mechanical.mjs's
+    // synchronous-only contract clean for callers that don't want history.
+    import('./fix-memory.mjs').then(({ appendFixes }) => {
+      const entries = applied.map(f => ({
+        type: f.type,
+        file: f.file || f.path || '',
+        summary: f.summary || f.detail || `${f.type} applied`,
+      }));
+      appendFixes(projectDir, entries, opts.appliedBy || 'fix --write');
+    }).catch(() => {
+      // Never let history-write break the fix flow — it's auxiliary.
+    });
+  }
+
   return { applied, skipped };
 }

package/commands/docguard.guard.md

@@ -1,5 +1,5 @@
 ---
-description: Run DocGuard guard validation — check project documentation against CDD standards with 21 validators
+description: Run DocGuard guard validation — check project documentation against CDD standards with 22 validators
 handoffs:
   - label: Fix All Issues
     agent: docguard.fix
@@ -23,7 +23,7 @@ Run the DocGuard CLI to validate all documentation against Canonical-Driven Deve
 npx docguard-cli guard
 ```
 
-2. **Parse the output**. Each of the 21 validators reports ✅ (pass), ⚠️ (warning), ❌ (fail), or ➖ (N/A — nothing to validate). **A ➖ N/A is NOT a pass**: it means the validator found nothing to check (e.g. no API-REFERENCE.md, no DB schema, no layer boundaries declared). Don't read N/A as "healthy" — read it as "not assessed".
+2. **Parse the output**. Each of the 22 validators reports ✅ (pass), ⚠️ (warning), ❌ (fail), or ➖ (N/A — nothing to validate). **A ➖ N/A is NOT a pass**: it means the validator found nothing to check (e.g. no API-REFERENCE.md, no DB schema, no layer boundaries declared). Don't read N/A as "healthy" — read it as "not assessed".
 
    | Validator | What It Checks |
    |-----------|---------------|

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 (21 validators)
+npx docguard-cli guard        # Pass/fail check (22 validators)
 npx docguard-cli score        # 0-100 maturity score
 ```
 

package/extensions/spec-kit-docguard/commands/guard.md

@@ -14,7 +14,7 @@ handoffs:
 
 # DocGuard Guard
 
-Validate your project against its canonical documentation. Runs 160+ automated checks across 21 validators.
+Validate your project against its canonical documentation. Runs 160+ automated checks across 22 validators.
 
 ## User Input
 

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

@@ -3,7 +3,7 @@ schema_version: "1.0"
 extension:
   id: "docguard"
   name: "DocGuard — CDD Enforcement"
-  version: "0.12.0"
+  version: "0.13.1"
   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.12.0
+  version: 0.13.1
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.12.0 -->
+<!-- docguard:version: 0.13.1 -->
 
 # 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.12.0
+  version: 0.13.1
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.12.0 -->
+<!-- docguard:version: 0.13.1 -->
 
 # DocGuard Guard Skill
 
@@ -139,7 +139,7 @@ For each finding, provide a **specific, actionable fix** — not "fix the issue"
 
 Based on the triage results:
 
-- **If all PASS**: "All 21 validators passed. Project is CDD-compliant. Ready to commit."
+- **If all PASS**: "All 22 validators passed. Project is CDD-compliant. Ready to commit."
 - **If only MEDIUM/LOW warnings**: "Non-blocking warnings found. Safe to commit, but consider running `/docguard.fix` for automated remediation."
 - **If HIGH or CRITICAL failures**: "Blocking issues found. Fix these before committing. Suggest running `/docguard.fix --doc [most impactful doc]` next."
 

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.12.0
+  version: 0.13.1
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.12.0 -->
+<!-- docguard:version: 0.13.1 -->
 
 # 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.12.0
+  version: 0.13.1
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.12.0 -->
+<!-- docguard:version: 0.13.1 -->
 
 # 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.12.0
+  version: 0.13.1
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
 

package/package.json

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

package/templates/commands/docguard.guard.md

@@ -1,5 +1,5 @@
 ---
-description: Run DocGuard guard validation — check all 21 validators and fix any issues
+description: Run DocGuard guard validation — check all 22 validators and fix any issues
 handoffs:
   - label: Fix Issues
     agent: docguard.fix
@@ -19,7 +19,7 @@ You are an AI agent enforcing Canonical-Driven Development (CDD) compliance usin
 npx docguard-cli guard
 ```
 
-Read the output. It shows pass (✅), warn (⚠️), or fail (❌) for each of the 21 validators:
+Read the output. It shows pass (✅), warn (⚠️), or fail (❌) for each of the 22 validators:
 
 | Priority | Validators |
 |----------|-----------|