docguard-cli 0.11.2 → 0.13.0

package/cli/validators/cross-reference.mjs

@@ -0,0 +1,289 @@
+/**
+ * Cross-Reference Validator — S-8 / K-7
+ *
+ * Scans canonical docs for cross-references between docs and verifies they
+ * resolve. Catches stale links when a section is renamed or removed.
+ *
+ * Reference forms supported (in rough order of frequency):
+ *   - Markdown relative links:        [text](./OTHER.md)
+ *                                     [text](./OTHER.md#anchor)
+ *                                     [text](#anchor-in-same-doc)
+ *   - Bare anchor refs:               see §3.2 ARCHITECTURE.md
+ *                                     (Section 3.2 in DATA-MODEL.md)
+ *   - Bracketed section refs:         [Section X.Y]
+ *                                     [ARCHITECTURE.md § Components]
+ *
+ * For each ref we extract: target_file (optional), anchor (optional). Then
+ * we check:
+ *   1. target_file exists (relative to projectDir or canonical doc dir)
+ *   2. anchor resolves to a heading or an explicit `<a name="...">` in that file
+ *
+ * Zero NPM dependencies. Pure Node.js built-ins.
+ *
+ * @req SC-K7-001 — broken markdown links between canonical docs are reported
+ * @req SC-K7-002 — broken intra-doc anchors are reported
+ * @req SC-K7-003 — external URLs (http/https) are NOT checked (those are not our problem)
+ * @req SC-K7-004 — code-fenced examples don't trigger false positives
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { resolve, join, dirname, basename } from 'node:path';
+
+/**
+ * Slugify a heading the way GitHub's markdown anchors work.
+ * Mirrors GFM rules: lowercase, strip non-word chars, hyphens for spaces.
+ * Good-enough for the 95% case; not bit-perfect.
+ */
+export function slugifyHeading(text) {
+  return text
+    // Remove leading "## " (markdown header marker) WITHOUT trimming the
+    // leading whitespace that may follow it — that whitespace is the
+    // position where an emoji used to live and GitHub's anchor builder
+    // converts it to a leading dash. Example: `## ⚡ Quick Start` →
+    // anchor `#-quick-start` (with leading dash). Stripping it here
+    // would cause false-positive "broken anchor" warnings on any TOC
+    // generated by GitHub itself.
+    .replace(/^#+\s+/, '')
+    .toLowerCase()
+    // Strip emoji + decorative pictographs (they leave a position which
+    // becomes a dash after whitespace-collapse below).
+    .replace(/[\u{1F300}-\u{1FAFF}\u{2600}-\u{27BF}\u{FE0F}]/gu, '')
+    // Strip GFM-deleted punctuation
+    .replace(/[.,;:!?'"`()[\]{}<>|\\/]/g, '')
+    // Convert whitespace runs to single dashes
+    .replace(/\s+/g, '-')
+    // Drop any remaining non-word/non-dash chars
+    .replace(/[^a-z0-9-]/g, '');
+    // NB: we do NOT collapse adjacent dashes and we do NOT strip leading/
+    // trailing dashes — GitHub's GFM keeps them. `& Academic` (with `&`
+    // removed) leaves two adjacent spaces which become `--`. README TOCs
+    // generated by GitHub itself rely on this exact behavior.
+}
+
+/**
+ * Extract all headings from a markdown file. Returns an array of
+ * { level, text, anchor } where anchor is the GFM-style slug.
+ *
+ * Skips headings inside ``` fenced code blocks to avoid false positives
+ * from example code.
+ */
+export function extractHeadings(content) {
+  const lines = content.split('\n');
+  const headings = [];
+  let inCodeFence = false;
+  for (const line of lines) {
+    if (line.startsWith('```')) {
+      inCodeFence = !inCodeFence;
+      continue;
+    }
+    if (inCodeFence) continue;
+    const m = line.match(/^(#{1,6})\s+(.+?)\s*$/);
+    if (m) {
+      const text = m[2];
+      headings.push({ level: m[1].length, text, anchor: slugifyHeading(text) });
+    }
+  }
+  return headings;
+}
+
+/**
+ * Extract all candidate cross-references from a markdown file.
+ *
+ * Returns an array of { source, file, anchor, raw } where:
+ *   - source = path of the document containing the reference (for reporting)
+ *   - file   = target file path, RELATIVE to the source file's directory.
+ *              null if the link is intra-doc (just `#anchor`).
+ *   - anchor = anchor part without `#`. null if no anchor.
+ *   - raw    = the original text matched (for error messages)
+ *
+ * Skips:
+ *   - External http(s) URLs (not our problem)
+ *   - mailto: links
+ *   - Code-fenced blocks
+ *   - Inline `code` with backticks
+ */
+export function extractRefs(content, sourcePath) {
+  const refs = [];
+  const lines = content.split('\n');
+  let inCodeFence = false;
+
+  // [text](target)  where target is one of:
+  //   ./RELATIVE.md
+  //   ../OTHER.md#anchor
+  //   #intra-doc-anchor
+  // We DON'T match http(s) targets here.
+  const markdownLinkRe = /\[([^\]]+)\]\(((?!https?:|mailto:)[^)]+)\)/g;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.startsWith('```')) {
+      inCodeFence = !inCodeFence;
+      continue;
+    }
+    if (inCodeFence) continue;
+
+    // Strip inline `code` so we don't match links inside it
+    const stripped = line.replace(/`[^`]+`/g, '');
+
+    let m;
+    markdownLinkRe.lastIndex = 0;
+    while ((m = markdownLinkRe.exec(stripped)) !== null) {
+      const target = m[2].trim();
+      // Drop any title text: [foo](bar "title") → bar
+      const cleanTarget = target.split(/\s+/)[0];
+      const hashIdx = cleanTarget.indexOf('#');
+      let file, anchor;
+      if (hashIdx === 0) {
+        // Intra-doc anchor only
+        file = null;
+        anchor = cleanTarget.slice(1);
+      } else if (hashIdx > 0) {
+        file = cleanTarget.slice(0, hashIdx);
+        anchor = cleanTarget.slice(hashIdx + 1);
+      } else {
+        file = cleanTarget;
+        anchor = null;
+      }
+      refs.push({ source: sourcePath, file, anchor, raw: m[0], line: i + 1 });
+    }
+  }
+
+  return refs;
+}
+
+/**
+ * Resolve a target file path relative to a source markdown file.
+ * Returns the absolute path or null if the file doesn't exist.
+ */
+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;
+  return null;
+}
+
+/**
+ * Collect canonical markdown docs to scan. Same selection logic as other
+ * validators — `docs-canonical/`, root tracking files, and AGENTS.md.
+ */
+function collectCanonicalDocs(projectDir) {
+  const docs = [];
+  const cdir = resolve(projectDir, 'docs-canonical');
+  if (existsSync(cdir)) {
+    try {
+      for (const f of readdirSync(cdir)) {
+        if (f.endsWith('.md')) {
+          const p = join(cdir, f);
+          if (statSync(p).isFile()) docs.push(p);
+        }
+      }
+    } catch {}
+  }
+  // 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);
+  }
+  return docs;
+}
+
+/**
+ * Validator entrypoint — matches the standard signature returning
+ * { errors, warnings, passed, total }.
+ */
+export function validateCrossReferences(projectDir, _config = {}) {
+  const errors = [];
+  const warnings = [];
+  let passed = 0;
+  let total = 0;
+
+  const docs = collectCanonicalDocs(projectDir);
+  if (docs.length === 0) {
+    return { errors, warnings, passed, total, applicable: false };
+  }
+
+  // Build a map of doc path → anchor set for fast lookups during ref resolution.
+  const anchorIndex = new Map();
+  for (const d of docs) {
+    try {
+      const content = readFileSync(d, 'utf-8');
+      const headings = extractHeadings(content);
+      anchorIndex.set(d, new Set(headings.map(h => h.anchor)));
+    } catch {
+      anchorIndex.set(d, new Set());
+    }
+  }
+
+  // Walk every doc and validate each ref.
+  for (const docPath of docs) {
+    let content;
+    try { content = readFileSync(docPath, 'utf-8'); } catch { continue; }
+    const refs = extractRefs(content, docPath);
+    const docName = basename(docPath);
+
+    for (const ref of refs) {
+      total++;
+
+      // Resolve the target file (if any)
+      let targetPath = null;
+      if (ref.file) {
+        // Skip non-markdown files — we only validate doc cross-refs, not
+        // links to images / code / config files. Those have their own truth.
+        if (!ref.file.toLowerCase().endsWith('.md')) {
+          passed++;
+          continue;
+        }
+        targetPath = resolveTarget(docPath, ref.file, projectDir);
+        if (!targetPath) {
+          warnings.push(
+            `${docName}:${ref.line} — broken link: target file "${ref.file}" not found`
+          );
+          continue;
+        }
+      } else {
+        // Intra-doc anchor reference
+        targetPath = docPath;
+      }
+
+      // If there's an anchor, verify it resolves in the target doc.
+      // URL-decode the anchor first — some editors percent-encode chars
+      // like `️` (variation selector) in TOC links that wouldn't
+      // appear in the actual GitHub-rendered anchor. Decoding makes
+      // `#%EF%B8%8F-cicd-integration` compare against `#-cicd-integration`.
+      if (ref.anchor) {
+        let decodedAnchor;
+        try {
+          decodedAnchor = decodeURIComponent(ref.anchor);
+        } catch {
+          decodedAnchor = ref.anchor;
+        }
+        // After decode, re-apply the slug pipeline so we compare like-for-like.
+        const normalizedAnchor = slugifyHeading(decodedAnchor);
+        const anchors = anchorIndex.get(targetPath);
+        const matches = anchors && (anchors.has(ref.anchor) || anchors.has(normalizedAnchor));
+        if (!matches) {
+          const where = targetPath === docPath ? 'same doc' : basename(targetPath);
+          warnings.push(
+            `${docName}:${ref.line} — broken anchor: "#${ref.anchor}" in ${where} doesn't match any heading`
+          );
+          continue;
+        }
+      }
+
+      passed++;
+    }
+  }
+
+  return { errors, warnings, passed, total };
+}

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

@@ -9,6 +9,7 @@
 import { existsSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, extname } from 'node:path';
 import { execSync, execFileSync } from 'node:child_process';
+import { getLastCommitDate } from '../shared-git.mjs';
 
 const IGNORE_DIRS = new Set([
   'node_modules', '.git', '.next', 'dist', 'build',
@@ -21,16 +22,10 @@ const IGNORE_DIRS = new Set([
  * Returns null if the file isn't tracked or git isn't available.
  */
 function getLastGitDate(filePath, dir) {
-  try {
-    const result = execFileSync(
-      'git',
-      ['log', '-1', '--format=%aI', '--', filePath],
-      { cwd: dir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }
-    ).trim();
-    return result ? new Date(result) : null;
-  } catch {
-    return null;
-  }
+  // Delegate to shared-git so rename history (--follow) is preserved.
+  // Without --follow, a `git mv` resets the file's "last commit date" and
+  // the Freshness counter silently misses drift introduced by the rename.
+  return getLastCommitDate(dir, filePath);
 }
 
 /**

package/cli/validators/generated-staleness.mjs

@@ -0,0 +1,97 @@
+/**
+ * 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 } from 'node:fs';
+import { resolve, basename } from 'node:path';
+
+import { buildMemoryPlan } from '../scanners/memory-plan.mjs';
+import { getSection } from '../writers/sections.mjs';
+
+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;
+
+  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; }
+
+    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.`
+      );
+    }
+  }
+
+  if (!anySourceCodeSection) {
+    return { ...result, applicable: false };
+  }
+
+  return result;
+}

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

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

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

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

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