docguard-cli 0.30.1 → 0.32.0

package/cli/commands/verify.mjs

@@ -22,10 +22,50 @@
  *   docguard verify [--semantic | --instructions] [--format json]
  */
 
+import { basename } from 'node:path';
 import { c } from '../shared.mjs';
 import { detectAgentMode } from '../ensure-skills.mjs';
 import { extractSemanticClaims, buildSemanticVerifyTasks } from '../scanners/semantic-claims.mjs';
 import { auditInstructions } from '../scanners/instruction-audit.mjs';
+import { isGitRepo, getDiffText } from '../shared-git.mjs';
+import { parseUnifiedDiff, activityLabeledDiff } from '../shared-diff.mjs';
+
+const CHANGE_CODE_EXT = /\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|rb|php|cs|swift|scala|dart)$/;
+
+/**
+ * Structured change context for staged agent tasks (feat 6). When `--since` is
+ * given, decompose the code diff into activity-labeled spans (ordered
+ * replace/delete/add) — the CARL-CCI representation shown to beat raw-text
+ * diffs (arXiv 2512.19883). The agent judging a claim then sees WHAT changed,
+ * not just the claim. Returns null when there's no ref / git / diff.
+ *
+ * Bounded: caps files and per-activity lines so the JSON stays agent-sized.
+ */
+function buildChangeContext(projectDir, since, { maxFiles = 40, maxLines = 6 } = {}) {
+  if (!since || !isGitRepo(projectDir)) return null;
+  const files = parseUnifiedDiff(getDiffText(projectDir, since))
+    .filter(f => f.newPath && CHANGE_CODE_EXT.test(f.newPath) && f.status !== 'deleted');
+  if (files.length === 0) return null;
+  const clip = (arr) => arr.slice(0, maxLines).map(s => s.length > 200 ? s.slice(0, 200) + '…' : s);
+  const activities = files.slice(0, maxFiles).map(f => ({
+    file: f.newPath,
+    activities: activityLabeledDiff(f).map(a => ({
+      type: a.type,
+      ...(a.del ? { del: clip(a.del) } : {}),
+      ...(a.add ? { add: clip(a.add) } : {}),
+    })),
+  }));
+  return { since, changedFiles: files.map(f => f.newPath), activities };
+}
+
+// Best-effort: is this semantic-verify task about code that just changed?
+function taskTouchesChange(task, changedSet, changedBasenames) {
+  const cite = task.citedCode || '';
+  if (!cite) return false;
+  if (changedSet.has(cite)) return true;
+  const b = basename(cite);
+  return changedBasenames.has(b) || [...changedSet].some(p => cite.includes(p) || p.includes(cite));
+}
 
 export function runVerify(projectDir, config, flags) {
   if (flags.instructions) {
@@ -37,13 +77,27 @@ export function runVerify(projectDir, config, flags) {
   const claims = extractSemanticClaims(projectDir, config);
   const tasks = buildSemanticVerifyTasks(claims);
 
+  // Change-aware staging (feat 6): if --since given, attach the structured diff
+  // and flag which claims are about just-changed code (verify those first).
+  const changeContext = buildChangeContext(projectDir, flags.since);
+  if (changeContext) {
+    const changedSet = new Set(changeContext.changedFiles);
+    const changedBasenames = new Set(changeContext.changedFiles.map(f => basename(f)));
+    for (const t of tasks) t.aboutChangedCode = taskTouchesChange(t, changedSet, changedBasenames);
+    // Prioritize changed-code claims first.
+    tasks.sort((a, b) => (b.aboutChangedCode ? 1 : 0) - (a.aboutChangedCode ? 1 : 0));
+  }
+
   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.',
+      howToVerify: changeContext
+        ? 'Claims flagged aboutChangedCode are about code that changed since the ref — verify those FIRST using changeContext.activities (the ordered replace/delete/add spans show exactly what changed). For each task, read the cited code, compare to the documented value, report mismatches with both values.'
+        : '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.',
+      ...(changeContext ? { changeContext } : {}),
       tasks,
     }, null, 2));
     return;
@@ -66,6 +120,10 @@ export function runVerify(projectDir, config, flags) {
   }
 
   console.log(`  ${c.yellow}${tasks.length} claim(s) to verify against the code:${c.reset}\n`);
+  if (changeContext) {
+    const nChanged = tasks.filter(t => t.aboutChangedCode).length;
+    console.log(`  ${c.cyan}⚡ ${nChanged} claim(s) are about code changed since ${flags.since}${c.reset} ${c.dim}— verify these first (structured diff in --format json).${c.reset}\n`);
+  }
   for (const [doc, ts] of byDoc) {
     console.log(`  ${c.bold}${doc}${c.reset}`);
     for (const t of ts) {
@@ -89,6 +147,9 @@ function runInstructionAudit(projectDir, config, flags) {
   const { rules, deterministic, tasks } = auditInstructions(projectDir, config);
   const { duplicates, negations, stalePointers, staleCommands } = deterministic;
   const findingCount = duplicates.length + negations.length + stalePointers.length + staleCommands.length;
+  // Structured change context helps the agent judge whether a rule about code
+  // has been invalidated by a recent change (feat 6).
+  const changeContext = buildChangeContext(projectDir, flags.since);
 
   if (isJson) {
     console.log(JSON.stringify({
@@ -100,6 +161,7 @@ function runInstructionAudit(projectDir, config, flags) {
       taskCount: tasks.length,
       // How to act on this: findings are proven; tasks need judgment.
       howToVerify: 'The findings are deterministic — fix them directly (delete the duplicate copy, resolve the negation in favour of one rule, repoint or remove stale paths/commands). For each task, read both rules in context and judge whether they contradict in practice; if so, report which should win, why, and which file to edit. DocGuard cannot judge the tasks — they require understanding intent.',
+      ...(changeContext ? { changeContext } : {}),
       tasks,
     }, null, 2));
     return;

package/cli/config.mjs

@@ -77,6 +77,13 @@ export function loadConfig(projectDir) {
       security: false,
       environment: true,
       freshness: true,
+      // v0.31.0 — all three default ON. Soft (confidence:low, never break CI),
+      // precise (zero false positives across the 6-repo corpus), and quiet when
+      // not applicable (no diff / no API-reference doc). api-doc-smells is
+      // low-yield but zero-FP, so on-by-default beats a self-counting split.
+      diffSuspicion: true,
+      referenceExistence: true,
+      apiDocSmells: true,
     },
   };
 

package/cli/docguard.mjs

@@ -29,7 +29,7 @@ import { runScore } from './commands/score.mjs';
 import { runDiff } from './commands/diff.mjs';
 import { runAgents } from './commands/agents.mjs';
 import { runGenerate } from './commands/generate.mjs';
-import { runHooks } from './commands/hooks.mjs';
+import { runHooks, runNudgeHook } from './commands/hooks.mjs';
 import { runBadge } from './commands/badge.mjs';
 import { runCI } from './commands/ci.mjs';
 import { runFix } from './commands/fix.mjs';
@@ -495,6 +495,32 @@ async function main() {
       i++;
     } else if (args[i] === '--no-fix') {
       flags.noFix = true;
+    } else if (args[i] === '--no-indirect') {
+      // impact: skip the reverse-import-graph (indirect code→doc) analysis.
+      flags.indirect = false;
+    } else if (args[i] === '--prs') {
+      // impact: open-PR doc-conflict analysis (needs the gh CLI).
+      flags.prs = true;
+    } else if (args[i] === '--claude') {
+      // hooks: install/remove the Claude Code agent nudge hook.
+      flags.claude = true;
+    } else if (args[i] === '--transport' && args[i + 1]) {
+      // mcp: stdio (default) or http (Streamable HTTP, team-shared server).
+      flags.transport = args[i + 1];
+      i++;
+    } else if (args[i] === '--port' && args[i + 1]) {
+      flags.port = args[i + 1];
+      i++;
+    } else if (args[i] === '--host' && args[i + 1]) {
+      flags.host = args[i + 1];
+      i++;
+    } else if (args[i] === '--api-key' && args[i + 1]) {
+      flags.apiKey = args[i + 1];
+      i++;
+    } else if (args[i] === '--path' && args[i + 1]) {
+      // mcp --transport http: HTTP mount path (default /mcp).
+      flags.path = args[i + 1];
+      i++;
     } else if (args[i] === '--signals') {
       flags.signals = true;
     } else if (args[i] === '--debate') {
@@ -545,7 +571,9 @@ async function main() {
   // `agent` emits a machine task graph (JSON by default) — it must be banner-
   // free and side-effect-free like the other read-only commands.
   // `mcp`: stdout IS the JSON-RPC transport — any banner byte corrupts the stream.
-  const headless = jsonMode || flags.write || flags.checkOnly || flags.changedOnly || flags.quiet || flags.plan || command === 'agent' || command === 'mcp';
+  // `nudge-hook`: stdout is the Claude Code hook feedback channel — any banner
+  // byte corrupts the JSON the hook runner parses.
+  const headless = jsonMode || flags.write || flags.checkOnly || flags.changedOnly || flags.quiet || flags.plan || command === 'agent' || command === 'mcp' || command === 'nudge-hook';
 
   if (!headless) printBanner();
 
@@ -572,6 +600,9 @@ async function main() {
     'verify',
     // mcp serves read-only tools over stdio — scaffolding writes are off-limits.
     'mcp',
+    // nudge-hook runs inside an agent's PostToolUse hook — it may write only
+    // its own .docguard/nudge-state.json throttle file, never scaffold skills.
+    'nudge-hook',
   ]);
 
   // Silent auto-check: install skills/commands if missing. Skip entirely in
@@ -624,7 +655,9 @@ async function main() {
     process.exit(1);
   }
 
-  if (DEPRECATED_COMMANDS[command] && !flags.quiet) {
+  // `hooks --claude` is a first-class new surface (agent nudge hook), not the
+  // deprecated git-hooks alias — no deprecation warning for it.
+  if (DEPRECATED_COMMANDS[command] && !flags.quiet && !(command === 'hooks' && flags.claude)) {
     const { since, replacement } = DEPRECATED_COMMANDS[command];
     console.error(`${c.yellow}⚠ Deprecated since v${since}:${c.reset} ${c.cyan}docguard ${command}${c.reset} → use ${c.cyan}${replacement}${c.reset}`);
     console.error(`${c.dim}  The old form still works in v0.20.x but will be removed in v1.0. See MIGRATION-v0.20.md.${c.reset}`);
@@ -671,8 +704,18 @@ async function main() {
       runAgent(projectDir, config, flags);
       break;
     case 'hooks':
+      if (flags.claude) {
+        // Agent nudge hook (.claude/settings.json) — direct path, no wizard.
+        runHooks(projectDir, config, flags);
+        break;
+      }
       await runInit(projectDir, config, { ...flags, with: ['hooks'], skipPrompts: true });
       break;
+    case 'nudge-hook':
+      // Runtime for the Claude Code PostToolUse hook. stdout is the machine
+      // channel (headless — see the jsonMode/banner gate above).
+      runNudgeHook(projectDir);
+      break;
     case 'badge':
       await runInit(projectDir, config, { ...flags, with: ['badge'], skipPrompts: true });
       break;

package/cli/findings.mjs

@@ -600,6 +600,38 @@ export const CODES = {
     help: 'Over 30% of sentences are conditional (if/unless/when…). Split conditionals into separate, unconditional requirements.',
     suppress: null,
   },
+
+  // ── v0.31.0 change-driven + IR detectors (all confidence:'low' / soft) ──
+  DSP001: {
+    validator: 'diff-suspicion',
+    title: 'Doc describes code that just changed',
+    help: 'A canonical doc (or agent-instruction file) references a code file AND shares wording with symbols removed/changed in that file since the compared revision. Deterministic diff-overlap rule (arXiv 2010.01625, F1 74.7). Low-confidence by design — re-read the doc against the current code; suppress the pairing if it is a false positive.',
+    suppress: null,
+  },
+  REF001: {
+    validator: 'reference-existence',
+    title: 'Doc references a code symbol that no longer exists',
+    help: 'A code-element reference in the doc matched source when the doc was last updated, but matches ZERO source instances at HEAD (two-revision check, arXiv 2212.01479). Excludes the two documented false-positive modes (removed-but-config-relevant flags, and symbols whose literal string was deleted while logic remains). Verify and update the reference.',
+    suppress: '<!-- docguard:ignore REF001 — still relevant, e.g. user-facing flag -->',
+  },
+  REF002: {
+    validator: 'reference-existence',
+    title: 'Code cites an ADR that has no document',
+    help: 'A code comment cites an Architecture Decision Record (e.g. ADR-012) that no ADR document defines — the citation is stale (renumbered, removed) or the ADR was never written. Numbers compare as integers, so ADR-0011 matches ADR-11. IETF RFC citations are deliberately not checked (external registry). Write the ADR, fix the number, or suppress on the citation line.',
+    suppress: '// docguard:ignore REF002 — your reason',
+  },
+  APS001: {
+    validator: 'api-doc-smells',
+    title: 'Bloated API documentation',
+    help: 'An API doc unit is excessively long / over-structured relative to the surface it documents (smell taxonomy, arXiv API-doc-smells; deterministic Bloated detector F1 0.90). Trim to the essential contract.',
+    suppress: '<!-- docguard:quality api-smell off — your reason -->',
+  },
+  APS002: {
+    validator: 'api-doc-smells',
+    title: 'Lazy API documentation',
+    help: 'An API doc unit is vague/generic or barely exceeds the signature it documents (deterministic Lazy detector F1 0.95). Document parameters, return, and errors concretely.',
+    suppress: '<!-- docguard:quality api-smell off — your reason -->',
+  },
 };
 
 /**

package/cli/scanners/agent-readability.mjs

@@ -14,6 +14,7 @@
 
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { resolve, dirname } from 'node:path';
+import { loadIgnorePatterns } from '../shared.mjs';
 
 /** chars/4 — the standard rough token estimate; consistency matters more than precision. */
 const estTokens = (s) => Math.ceil(s.length / 4);
@@ -31,9 +32,13 @@ function readIfExists(path) {
 function canonicalDocs(projectDir) {
   const dir = resolve(projectDir, 'docs-canonical');
   if (!existsSync(dir)) return [];
+  // Honor .docguardignore — an excluded doc (e.g. a historical audit) must
+  // not drag down the readability metrics either (same rule as the
+  // semantic-claim extractor, bug-212).
+  const isIgnored = loadIgnorePatterns(projectDir);
   try {
     return readdirSync(dir)
-      .filter(f => f.toLowerCase().endsWith('.md'))
+      .filter(f => f.toLowerCase().endsWith('.md') && !isIgnored(`docs-canonical/${f}`))
       .sort()
       .map(f => ({ name: `docs-canonical/${f}`, content: readIfExists(resolve(dir, f)) }))
       .filter(d => d.content !== null);

package/cli/scanners/semantic-claims.mjs

@@ -23,6 +23,7 @@
 
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { resolve, join } from 'node:path';
+import { loadIgnorePatterns } from '../shared.mjs';
 
 // Numbers are only claims when adjacent to a recognized unit.
 const NUMBER_PATTERNS = [
@@ -49,17 +50,24 @@ const MAX_CLAIMS = 80;
 
 /** Canonical docs + the root docs where limits/counts commonly live. */
 function claimSourceDocs(projectDir) {
+  // Honor .docguardignore: a doc the user explicitly excluded from validation
+  // (e.g. a historical audit full of point-in-time counts) must not feed the
+  // "unverified claims" pool either — it inflated the count and buried the
+  // claims that ARE actionable (bug-212).
+  const isIgnored = loadIgnorePatterns(projectDir);
   const docs = [];
   const canonical = resolve(projectDir, 'docs-canonical');
   if (existsSync(canonical)) {
     try {
       for (const f of readdirSync(canonical)) {
-        if (f.toLowerCase().endsWith('.md')) docs.push(`docs-canonical/${f}`);
+        if (f.toLowerCase().endsWith('.md') && !isIgnored(`docs-canonical/${f}`)) {
+          docs.push(`docs-canonical/${f}`);
+        }
       }
     } catch { /* ignore */ }
   }
   for (const root of ['README.md', 'AGENTS.md']) {
-    if (existsSync(resolve(projectDir, root))) docs.push(root);
+    if (existsSync(resolve(projectDir, root)) && !isIgnored(root)) docs.push(root);
   }
   return docs;
 }

package/cli/shared-diff.mjs

@@ -0,0 +1,209 @@
+/**
+ * Shared Unified-Diff Parser + Tokenizer — zero-dependency foundation for the
+ * change-driven detectors added in v0.31.0.
+ *
+ * ONE parser, consumed by four features so they never re-implement diff
+ * scraping (each previously would have grepped `git diff` output ad hoc):
+ *   - diff-overlap suspicion (validators/diff-suspicion.mjs): does a doc's
+ *     wording overlap tokens that were DELETED/REPLACED-OLD in the code diff?
+ *   - reference-existence (validators/reference-existence.mjs): which symbols
+ *     left the tree between two revisions.
+ *   - impact blast-radius (commands/impact.mjs): which docs cite changed code.
+ *   - structured-diff staging (commands/verify.mjs): hand agents an ordered
+ *     replace/delete/add representation (the CARL-CCI "activity-labeled diff"
+ *     shown to beat raw-text diffs — arXiv 2512.19883) instead of a raw patch.
+ *
+ * Pure Node built-ins. No git here — this operates on diff TEXT a caller
+ * already produced (see shared-git.getDiffSpans). That keeps it unit-testable
+ * without a repo and reusable on any unified-diff string.
+ */
+
+// ── Tokenizer ────────────────────────────────────────────────────────────────
+// Identifier-aware: keeps `getUserById`, `user_id`, `UserService` whole, then
+// also emits their sub-words so a doc saying "user id" still overlaps code
+// token `user_id`. Deterministic, lowercase, stopword-filtered.
+
+const STOPWORDS = new Set([
+  'the', 'a', 'an', 'and', 'or', 'but', 'if', 'then', 'else', 'for', 'of', 'to',
+  'in', 'on', 'at', 'by', 'as', 'is', 'are', 'was', 'were', 'be', 'been', 'this',
+  'that', 'these', 'those', 'it', 'its', 'with', 'from', 'not', 'no', 'we', 'you',
+  'return', 'returns', 'const', 'let', 'var', 'function', 'class', 'import',
+  'export', 'default', 'new', 'true', 'false', 'null', 'void', 'public', 'private',
+]);
+
+/**
+ * Split identifiers into sub-words: getUserById → [get,user,by,id];
+ * user_id → [user,id]; HTTPServer → [http,server].
+ */
+export function splitIdentifier(id) {
+  return String(id)
+    // camelCase / PascalCase / ACRONYMBoundary
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+    // snake_case, kebab-case, dot.paths
+    .replace(/[_\-.]+/g, ' ')
+    .toLowerCase()
+    .split(/\s+/)
+    .filter(Boolean);
+}
+
+/**
+ * Tokenize free text OR code into a lowercase word set. Keeps whole identifiers
+ * AND their sub-words. `min` drops tokens shorter than it (default 3) to cut
+ * noise; identifiers below `min` after splitting are still dropped.
+ *
+ * Returns an array (call-site decides Set vs list). Deduped, order-preserving.
+ */
+export function tokenize(text, { min = 3, keepStopwords = false } = {}) {
+  const out = [];
+  const seen = new Set();
+  const raw = String(text).match(/[A-Za-z_][A-Za-z0-9_.-]*/g) || [];
+  for (const word of raw) {
+    // the whole identifier (lowercased) …
+    const whole = word.toLowerCase();
+    for (const t of [whole, ...splitIdentifier(word)]) {
+      if (t.length < min) continue;
+      if (!keepStopwords && STOPWORDS.has(t)) continue;
+      if (seen.has(t)) continue;
+      seen.add(t);
+      out.push(t);
+    }
+  }
+  return out;
+}
+
+// ── Unified-diff parser ──────────────────────────────────────────────────────
+
+/**
+ * Parse a unified diff (git diff / diff -u) into structured file entries.
+ * Handles multi-file diffs, adds/deletes (/dev/null), renames, and the
+ * "" marker.
+ *
+ * Returns: [{ oldPath, newPath, status, hunks: [{ oldStart, newStart,
+ *   lines: [{ op: ' '|'-'|'+', text }] }] }]
+ * status ∈ 'modified' | 'added' | 'deleted' | 'renamed'.
+ */
+export function parseUnifiedDiff(diffText) {
+  const files = [];
+  if (!diffText) return files;
+  const lines = String(diffText).split('\n');
+  let cur = null;
+  let hunk = null;
+
+  const pushHunkHeader = (m) => {
+    hunk = { oldStart: parseInt(m[1], 10) || 0, newStart: parseInt(m[2], 10) || 0, lines: [] };
+    cur.hunks.push(hunk);
+  };
+
+  for (const line of lines) {
+    if (line.startsWith('diff --git')) {
+      // a/<old> b/<new> — quotes possible but rare; keep it simple.
+      const m = line.match(/^diff --git a\/(.+?) b\/(.+)$/);
+      cur = { oldPath: m ? m[1] : null, newPath: m ? m[2] : null, status: 'modified', hunks: [] };
+      files.push(cur);
+      hunk = null;
+      continue;
+    }
+    if (!cur) continue; // ignore any preamble before the first file
+    if (line.startsWith('rename from ')) { cur.status = 'renamed'; cur.oldPath = line.slice(12); continue; }
+    if (line.startsWith('rename to ')) { cur.status = 'renamed'; cur.newPath = line.slice(10); continue; }
+    if (line.startsWith('--- ')) {
+      const p = line.slice(4);
+      if (p === '/dev/null') cur.status = 'added';
+      else cur.oldPath = p.replace(/^a\//, '');
+      continue;
+    }
+    if (line.startsWith('+++ ')) {
+      const p = line.slice(4);
+      if (p === '/dev/null') cur.status = 'deleted';
+      else cur.newPath = p.replace(/^b\//, '');
+      continue;
+    }
+    const hm = line.match(/^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/);
+    if (hm) { pushHunkHeader(hm); continue; }
+    if (!hunk) continue;
+    if (line.startsWith('\\')) continue; // ""
+    const op = line[0];
+    if (op === ' ' || op === '+' || op === '-') {
+      hunk.lines.push({ op, text: line.slice(1) });
+    }
+  }
+  return files;
+}
+
+/**
+ * Decompose a file's hunks into an ORDERED activity list — the CARL-CCI
+ * "activity-labeled" representation. Consecutive removed/added runs are grouped:
+ *   run of '-' then '+'  → { type: 'replace', del: [...], add: [...] }
+ *   run of '-' only      → { type: 'delete', del: [...] }
+ *   run of '+' only      → { type: 'add', add: [...] }
+ * Context lines are the separators and are not emitted (they're not a change).
+ *
+ * This is what makes staged agent tasks legible: the agent sees "these lines
+ * were replaced by those", not a flat blob.
+ */
+export function activityLabeledDiff(fileDiff) {
+  const acts = [];
+  for (const h of fileDiff.hunks || []) {
+    let del = [];
+    let add = [];
+    const flush = () => {
+      if (del.length && add.length) acts.push({ type: 'replace', del, add });
+      else if (del.length) acts.push({ type: 'delete', del });
+      else if (add.length) acts.push({ type: 'add', add });
+      del = []; add = [];
+    };
+    for (const ln of h.lines) {
+      if (ln.op === '-') {
+        if (add.length) flush(); // an add run ended before this delete → boundary
+        del.push(ln.text);
+      } else if (ln.op === '+') {
+        add.push(ln.text);
+      } else {
+        flush(); // context terminates the current activity
+      }
+    }
+    flush();
+  }
+  return acts;
+}
+
+/**
+ * Tokens that LEFT the code in this file diff — union over every '-' line
+ * (both pure deletes and the "old" side of replaces). This is the
+ * `deleted ∪ replaceOld` span the outdated-comment research keys on: a doc
+ * that still talks about these tokens is a drift suspect.
+ */
+export function removedTokens(fileDiff, opts) {
+  const set = new Set();
+  for (const h of fileDiff.hunks || []) {
+    for (const ln of h.lines) {
+      if (ln.op === '-') for (const t of tokenize(ln.text, opts)) set.add(t);
+    }
+  }
+  return set;
+}
+
+/** Tokens that were ADDED ('+' lines) — the new-side span. */
+export function addedTokens(fileDiff, opts) {
+  const set = new Set();
+  for (const h of fileDiff.hunks || []) {
+    for (const ln of h.lines) {
+      if (ln.op === '+') for (const t of tokenize(ln.text, opts)) set.add(t);
+    }
+  }
+  return set;
+}
+
+/**
+ * Overlap score between a doc's tokens and a set of change tokens: the count
+ * and the shared tokens themselves (for explainable findings). Deterministic.
+ */
+export function tokenOverlap(docTokens, changeTokenSet) {
+  const shared = [];
+  const seen = new Set();
+  for (const t of docTokens) {
+    if (changeTokenSet.has(t) && !seen.has(t)) { seen.add(t); shared.push(t); }
+  }
+  return { count: shared.length, shared };
+}

package/cli/shared-git.mjs

@@ -148,6 +148,99 @@ export function changedFilesSince(dir, ref = 'HEAD~1') {
   }
 }
 
+/**
+ * Return the raw unified-diff TEXT between `ref` and HEAD, restricted to code
+ * files (docs are excluded — a doc changing is not a code change that could
+ * make OTHER docs stale). Consumed by shared-diff.parseUnifiedDiff.
+ *
+ * `-U0`? No — we want a few lines of context so the parser can group activities
+ * and callers can see surrounding tokens; default 3 is fine. Returns '' on
+ * error / no diff. Caps output at ~5MB so a giant refactor can't OOM the CLI.
+ */
+export function getDiffText(dir, ref = 'HEAD~1', pathspec = null) {
+  try {
+    const args = ['diff', '--no-color', '--no-ext-diff', ref, 'HEAD'];
+    if (pathspec && pathspec.length) args.push('--', ...pathspec);
+    const raw = execFileSync('git', args, {
+      cwd: dir, encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'ignore'],
+      maxBuffer: 1024 * 1024 * 5,
+    });
+    return raw || '';
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Read a file's contents AS OF a given revision (e.g. the commit where a doc
+ * was last touched), following the `<rev>:<path>` git addressing. Returns null
+ * when the path didn't exist at that rev, the rev is unknown, or git is
+ * unavailable — callers treat null as "no prior snapshot to compare".
+ *
+ * This is the backbone of the two-revision reference-existence check: read the
+ * source at the doc's last-updated commit vs HEAD and diff symbol presence.
+ */
+export function fileContentAtRev(dir, rev, filePath) {
+  try {
+    const raw = execFileSync(
+      'git',
+      ['show', `${rev}:${filePath}`],
+      { cwd: dir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'ignore'], maxBuffer: 1024 * 1024 * 10 }
+    );
+    return raw;
+  } catch {
+    return null;
+  }
+}
+
+// Default source globs for symbol-existence grep (any-language).
+export const CODE_GLOBS = [
+  '*.ts', '*.tsx', '*.js', '*.jsx', '*.mjs', '*.cjs', '*.py', '*.go', '*.rs',
+  '*.java', '*.kt', '*.rb', '*.php', '*.cs', '*.swift', '*.scala', '*.dart', '*.c', '*.cpp', '*.h',
+];
+
+/**
+ * True if `symbol` appears as a whole word in the source tree AS OF `rev`.
+ * Uses `git grep -w -F` (fixed string, word boundary) at the given revision —
+ * exactly the "whole-word, case-sensitive, exact string match" the two-revision
+ * outdated-reference method specifies (arXiv 2212.01479). Restricted to code
+ * globs so a symbol still named in prose/docs doesn't count as "present".
+ *
+ * Returns false when absent, the rev is unknown, or git is unavailable — the
+ * caller pairs two calls (doc's last-update rev vs HEAD) to detect present→gone.
+ */
+export function symbolExistsAtRev(dir, symbol, rev, pathspecs = CODE_GLOBS) {
+  try {
+    execFileSync(
+      'git',
+      ['grep', '-q', '-w', '-F', '-e', symbol, rev, '--', ...pathspecs],
+      { cwd: dir, stdio: ['pipe', 'ignore', 'ignore'] }
+    );
+    return true; // exit 0 → at least one match
+  } catch {
+    return false; // exit 1 → no match (or bad rev / no git)
+  }
+}
+
+/**
+ * Resolve the commit hash that last touched `filePath` (following renames), or
+ * null. Used to anchor "the revision when this doc was last updated" for the
+ * two-revision check without re-parsing getFileHistory at every call site.
+ */
+export function lastCommitHash(dir, filePath) {
+  try {
+    const raw = execFileSync(
+      'git',
+      ['log', '--follow', '-1', '--format=%H', '--', filePath],
+      { cwd: dir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'ignore'] }
+    ).trim();
+    return raw || null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Resolve the absolute path to this repo's git hooks directory.
  *