docguard-cli 0.30.1 → 0.32.0

package/cli/shared-ir.mjs

@@ -0,0 +1,81 @@
+/**
+ * Shared IR primitives — zero-dependency TF-IDF + cosine similarity.
+ *
+ * Backs IR-based traceability link recovery (feat 5): when a requirement has no
+ * exact `@req <ID>` annotation, rank candidate test/code artifacts by textual
+ * similarity (Vector Space Model, the canonical IR traceability technique —
+ * "basic linear algebra, no external services"). A requirement with NO
+ * candidate above threshold is a strong "unimplemented / untested" signal.
+ *
+ * Pure functions over token arrays; the caller tokenizes (we reuse the
+ * identifier-aware tokenizer from shared-diff so `getUserById` in code matches
+ * "get user by id" in a requirement).
+ */
+
+/** term → count for one document's tokens. */
+export function termFreq(tokens) {
+  const tf = new Map();
+  for (const t of tokens) tf.set(t, (tf.get(t) || 0) + 1);
+  return tf;
+}
+
+/**
+ * Inverse document frequency across a corpus of token arrays.
+ * idf(t) = ln(N / (1 + df(t))) + 1  — smoothed so a term in every doc still
+ * carries a small positive weight (avoids all-zero vectors on tiny corpora).
+ */
+export function buildIdf(corpusTokenArrays) {
+  const N = corpusTokenArrays.length || 1;
+  const df = new Map();
+  for (const tokens of corpusTokenArrays) {
+    for (const t of new Set(tokens)) df.set(t, (df.get(t) || 0) + 1);
+  }
+  const idf = new Map();
+  for (const [t, d] of df) idf.set(t, Math.log(N / (1 + d)) + 1);
+  return idf;
+}
+
+/** TF-IDF vector (Map term→weight) for a document, given a prebuilt idf. */
+export function tfidfVector(tokens, idf) {
+  const tf = termFreq(tokens);
+  const vec = new Map();
+  const len = tokens.length || 1;
+  for (const [t, count] of tf) {
+    const w = idf.get(t);
+    if (w === undefined) continue; // term not in corpus idf → skip
+    vec.set(t, (count / len) * w); // normalized TF × IDF
+  }
+  return vec;
+}
+
+/** Cosine similarity of two sparse Map vectors. 0 when either is empty. */
+export function cosineSimilarity(a, b) {
+  if (a.size === 0 || b.size === 0) return 0;
+  // iterate the smaller for the dot product
+  const [small, large] = a.size <= b.size ? [a, b] : [b, a];
+  let dot = 0;
+  for (const [t, w] of small) {
+    const w2 = large.get(t);
+    if (w2 !== undefined) dot += w * w2;
+  }
+  if (dot === 0) return 0;
+  let na = 0; for (const w of a.values()) na += w * w;
+  let nb = 0; for (const w of b.values()) nb += w * w;
+  const denom = Math.sqrt(na) * Math.sqrt(nb);
+  return denom === 0 ? 0 : dot / denom;
+}
+
+/**
+ * Rank candidate documents against a query by cosine similarity.
+ * @param queryTokens tokens of the requirement text
+ * @param candidates  [{ id, tokens }]
+ * @returns [{ id, score }] sorted desc, scores in [0,1]
+ */
+export function rankBySimilarity(queryTokens, candidates) {
+  const corpus = [queryTokens, ...candidates.map(c => c.tokens)];
+  const idf = buildIdf(corpus);
+  const qv = tfidfVector(queryTokens, idf);
+  return candidates
+    .map(c => ({ id: c.id, score: cosineSimilarity(qv, tfidfVector(c.tokens, idf)) }))
+    .sort((x, y) => y.score - x.score);
+}

package/cli/validators/api-doc-smells.mjs

@@ -0,0 +1,143 @@
+/**
+ * API-Doc-Smells validator (APS001 Bloated, APS002 Lazy) — v0.31.0.
+ *
+ * Research: the API-documentation-smell taxonomy (Bloated, Excess Structural
+ * Info, Tangled, Fragmented, Lazy) with a 1,000-unit benchmark. The two smells
+ * with strong DETERMINISTIC detectors are Bloated (F1 0.90) and Lazy (F1 0.95),
+ * keyed on documentation length relative to the surface documented — no ML.
+ * The three semantic smells need BERT and are deliberately left to staged agent
+ * judgment (verify --semantic), matching DocGuard's split.
+ *
+ * We apply the length signals per "API documentation unit" = a markdown section
+ * whose HEADING is a code signature (an HTTP endpoint `GET /path`, a function
+ * `foo(...)`, or a backticked symbol). Prose-only sections are ignored — that's
+ * doc-quality.mjs's job (passive voice, readability); this is API-surface-specific.
+ *
+ *   Lazy   — a documented endpoint/method with (almost) no explanation: ≤ N
+ *            prose words of body. "Documented in name only."
+ *   Bloated— a single unit that is grossly over-documented: ≥ M words.
+ *
+ * All findings confidence:'low' / soft — a nudge to right-size the doc.
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { mkFinding, resultFromFindings } from '../findings.mjs';
+
+const HEADING = /^(#{1,6})\s+(.*)$/;
+// A heading that documents an API/code unit — NOT a prose section heading.
+// Precision (corpus-tuned): markdown headings routinely read "Some Words
+// (parenthetical note)", which naively looks like a call. A real signature has
+// NO space before `(` AND a code-shaped identifier (camelCase / snake_case /
+// dotted). This kills FPs like "Remediation Log (2026-03-17)", "Unit Tests
+// (vitest)", "4.1 Enrollment (Base Record)".
+const HTTP_SIG = /^`?\s*(GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS)\s+\/?`?\S/i;
+const FUNC_SIG = /(?:^|[\s`.])([A-Za-z_][A-Za-z0-9_]*)\((?:\)|[^)]*\))/; // identifier(...) no space
+const CODEY = /[a-z][A-Z]|_|\./;                     // camel/snake/dotted → code-shaped
+const BACKTICK_SIG = /^`[^`\s][^`]*`\s*$/;           // heading is exactly a `symbol`
+function isSignatureHeading(text) {
+  const t = text.trim();
+  if (HTTP_SIG.test(t)) return true;
+  if (BACKTICK_SIG.test(t)) return true;
+  const fm = t.match(FUNC_SIG);
+  if (fm && (CODEY.test(fm[1]) || /\(\s*\)/.test(t))) return true; // codey name OR empty-arg call foo()
+  return false;
+}
+
+// Prose words in a body, EXCLUDING fenced code blocks (a big code sample isn't
+// "explanation", so a unit with only code counts as Lazy).
+function proseWordCount(bodyLines) {
+  let inFence = false;
+  let words = 0;
+  for (const line of bodyLines) {
+    if (/^\s*```/.test(line)) { inFence = !inFence; continue; }
+    if (inFence) continue;
+    const m = line.trim().match(/[A-Za-z0-9][A-Za-z0-9'-]*/g);
+    if (m) words += m.length;
+  }
+  return words;
+}
+function totalWordCount(bodyLines) {
+  let words = 0;
+  for (const line of bodyLines) {
+    const m = line.match(/[A-Za-z0-9][A-Za-z0-9'-]*/g);
+    if (m) words += m.length;
+  }
+  return words;
+}
+
+// Split markdown into signature-headed units: { heading, level, line, body[] }.
+function extractUnits(content) {
+  const lines = content.split('\n');
+  const units = [];
+  let cur = null;
+  for (let i = 0; i < lines.length; i++) {
+    const hm = lines[i].match(HEADING);
+    if (hm) {
+      // close current unit at the next heading of same-or-higher level
+      if (cur && hm[1].length <= cur.level) { units.push(cur); cur = null; }
+      if (!cur && isSignatureHeading(hm[2])) {
+        cur = { heading: hm[2].trim(), level: hm[1].length, line: i + 1, body: [] };
+        continue;
+      }
+      if (cur) { cur.body.push(lines[i]); }
+      continue;
+    }
+    if (cur) cur.body.push(lines[i]);
+  }
+  if (cur) units.push(cur);
+  return units;
+}
+
+export function validateApiDocSmells(projectDir, config = {}) {
+  const cfg = config.apiDocSmells || {};
+  const lazyMax = Number.isInteger(cfg.lazyMaxWords) ? cfg.lazyMaxWords : 6;
+  const bloatedMin = Number.isInteger(cfg.bloatedMinWords) ? cfg.bloatedMinWords : 300;
+
+  const docsDir = resolve(projectDir, 'docs-canonical');
+  if (!existsSync(docsDir)) {
+    return resultFromFindings([], { passed: 0, total: 0, applicable: false });
+  }
+  let docFiles = [];
+  try { docFiles = readdirSync(docsDir).filter(f => f.endsWith('.md')); } catch { /* skip */ }
+
+  const findings = [];
+  let unitCount = 0;
+  for (const f of docFiles) {
+    let content;
+    try { content = readFileSync(resolve(docsDir, f), 'utf-8'); } catch { continue; }
+    const units = extractUnits(content);
+    for (const u of units) {
+      unitCount++;
+      const prose = proseWordCount(u.body);
+      const total = totalWordCount(u.body);
+      if (prose <= lazyMax) {
+        findings.push(mkFinding({
+          code: 'APS002',
+          validator: 'api-doc-smells',
+          severity: 'warn',
+          confidence: 'low',
+          message: `${f}: "${u.heading.slice(0, 60)}" is documented in name only (${prose} words of explanation) — Lazy API doc.`,
+          location: { file: f, line: u.line },
+          suggestion: { summary: `Describe what "${u.heading.slice(0, 40)}" does, its params, return, and errors — not just its signature.` },
+        }));
+      } else if (total >= bloatedMin) {
+        findings.push(mkFinding({
+          code: 'APS001',
+          validator: 'api-doc-smells',
+          severity: 'warn',
+          confidence: 'low',
+          message: `${f}: "${u.heading.slice(0, 60)}" is ${total} words for one unit — Bloated API doc; trim to the essential contract.`,
+          location: { file: f, line: u.line },
+          suggestion: { summary: `Split or trim "${u.heading.slice(0, 40)}" — move examples/edge-cases elsewhere and keep the core contract.` },
+        }));
+      }
+    }
+  }
+
+  return resultFromFindings(findings, {
+    passed: unitCount - findings.length,
+    total: unitCount,
+    applicable: unitCount > 0,
+  });
+}

package/cli/validators/architecture.mjs

@@ -143,7 +143,14 @@ function validateConfigLayers(projectDir, config, layers, acc) {
 
 // ── Import Graph Builder ────────────────────────────────────────────────────
 
-function buildImportGraph(projectDir, config) {
+/**
+ * Build the project's JS/TS import graph. Exported for reuse by `impact`
+ * (indirect code→doc analysis walks this graph's reverse edges) — one graph
+ * builder, not two.
+ *
+ * @returns {{files: string[], edges: {from,to,dynamic}[], fileMap: Map<string,string[]>}}
+ */
+export function buildImportGraph(projectDir, config) {
   const graph = { files: [], edges: [], fileMap: new Map() };
 
   const allFiles = getFilesRecursive(projectDir, config, projectDir);

package/cli/validators/cross-reference.mjs

@@ -8,6 +8,13 @@
  *   - Markdown relative links:        [text](./OTHER.md)
  *                                     [text](./OTHER.md#anchor)
  *                                     [text](#anchor-in-same-doc)
+ *                                     [text](<path with spaces.md>)
+ *   - Obsidian wikilinks:             [[OTHER]]  [[OTHER#Heading]]  [[OTHER|alias]]
+ *     Validated only when the repo shows wikilinks-are-files evidence
+ *     (`.obsidian/` exists, or at least one wikilink target resolves) — some
+ *     repos use [[name]] as a non-file convention (template placeholders,
+ *     memory links) and must not be flagged. Image embeds `![[x.png]]` are
+ *     never treated as doc links.
  *   - Bare anchor refs:               see §3.2 ARCHITECTURE.md
  *                                     (Section 3.2 in DATA-MODEL.md)
  *   - Bracketed section refs:         [Section X.Y]
@@ -29,6 +36,8 @@
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, dirname, basename, relative } from 'node:path';
 import { mkFinding, resultFromFindings } from '../findings.mjs';
+import { resolveDocDirs } from '../shared.mjs';
+import { walkFiles } from '../shared-ignore.mjs';
 
 /**
  * Slugify a heading the way GitHub's markdown anchors work.
@@ -112,8 +121,13 @@ export function extractRefs(content, sourcePath) {
   //   ./RELATIVE.md
   //   ../OTHER.md#anchor
   //   #intra-doc-anchor
+  //   <path with spaces.md>   (CommonMark angle-bracket form)
   // We DON'T match http(s) targets here.
   const markdownLinkRe = /\[([^\]]+)\]\(((?!https?:|mailto:)[^)]+)\)/g;
+  // [[Target]] / [[Target#Heading]] / [[Target|alias]]. The (?<!!) guard
+  // excludes Obsidian image embeds ![[img.png]] — an embed is content, not a
+  // doc cross-reference.
+  const wikiLinkRe = /(?<!!)\[\[([^\]|#\n]+)(?:#([^\]|\n]*))?(?:\|[^\]\n]*)?\]\]/g;
 
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
@@ -130,8 +144,14 @@ export function extractRefs(content, sourcePath) {
     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];
+      let cleanTarget;
+      if (target.startsWith('<') && target.includes('>')) {
+        // Angle-bracket form: the target is everything inside <…>, spaces allowed.
+        cleanTarget = target.slice(1, target.indexOf('>'));
+      } else {
+        // Drop any title text: [foo](bar "title") → bar
+        cleanTarget = target.split(/\s+/)[0];
+      }
       const hashIdx = cleanTarget.indexOf('#');
       let file, anchor;
       if (hashIdx === 0) {
@@ -145,13 +165,55 @@ export function extractRefs(content, sourcePath) {
         file = cleanTarget;
         anchor = null;
       }
+      // `./repo.md?x=1#setup` targets repo.md — the query never names a file.
+      if (file) file = file.split('?')[0];
       refs.push({ source: sourcePath, file, anchor, raw: m[0], line: i + 1 });
     }
+
+    wikiLinkRe.lastIndex = 0;
+    while ((m = wikiLinkRe.exec(stripped)) !== null) {
+      const target = m[1].trim();
+      if (!target) continue;
+      const anchor = m[2] !== undefined ? m[2].trim() : null;
+      refs.push({ source: sourcePath, file: target, anchor: anchor || null, raw: m[0], line: i + 1, wiki: true });
+    }
   }
 
   return refs;
 }
 
+/**
+ * Basename-stem → path index of every markdown file in the project's doc
+ * homes plus the already-collected canonical docs. Obsidian resolves
+ * wikilinks vault-wide by basename; this is the named-doc-dirs equivalent
+ * (never an arbitrary-subdir walk).
+ */
+function buildWikiIndex(projectDir, config, docs) {
+  const idx = new Map();
+  const add = (p) => {
+    const stem = basename(p).replace(/\.mdx?$/i, '').toLowerCase();
+    if (!idx.has(stem)) idx.set(stem, p);
+  };
+  for (const d of docs) add(d);
+  for (const d of resolveDocDirs(projectDir, config)) {
+    const abs = resolve(projectDir, d);
+    if (!existsSync(abs)) continue;
+    walkFiles(abs, (full) => { if (/\.mdx?$/i.test(full)) add(full); });
+  }
+  return idx;
+}
+
+/** Resolve a wikilink target: sibling path, project root, then vault index. */
+function resolveWikiTarget(sourcePath, target, projectDir, wikiIndex) {
+  const withExt = /\.mdx?$/i.test(target) ? target : `${target}.md`;
+  for (const base of [dirname(sourcePath), projectDir]) {
+    const p = resolve(base, withExt);
+    if (existsSync(p)) return p;
+  }
+  const stem = basename(withExt).replace(/\.mdx?$/i, '').toLowerCase();
+  return wikiIndex.get(stem) || null;
+}
+
 /**
  * Resolve a target file path relative to a source markdown file.
  * Returns the absolute path or null if the file doesn't exist.
@@ -297,9 +359,10 @@ function collectCanonicalDocs(projectDir) {
  * errors/warnings arrays from the same findings, so counts, exit codes, and
  * existing tests are unaffected; guard just renders richer output.
  */
-export function validateCrossReferences(projectDir, _config = {}) {
+export function validateCrossReferences(projectDir, config = {}) {
   const findings = [];
   const fixes = [];
+  const wikiRefs = []; // validated in a second pass — evidence gate needs the full set
   let passed = 0;
   let total = 0;
 
@@ -328,6 +391,10 @@ export function validateCrossReferences(projectDir, _config = {}) {
     const docName = basename(docPath);
 
     for (const ref of refs) {
+      if (ref.wiki) {
+        wikiRefs.push({ ...ref, docPath, docName });
+        continue;
+      }
       total++;
 
       // Resolve the target file (if any)
@@ -411,6 +478,60 @@ export function validateCrossReferences(projectDir, _config = {}) {
     }
   }
 
+  // ── Wikilink pass — only when the repo demonstrably uses [[x]] as FILE
+  // links: `.obsidian/` exists, or at least one wikilink target resolves.
+  // Repos using [[name]] as a non-file convention are skipped silently.
+  if (wikiRefs.length > 0) {
+    const wikiIndex = buildWikiIndex(projectDir, config, docs);
+    const resolved = wikiRefs.map(r => ({
+      r,
+      path: resolveWikiTarget(r.docPath, r.file, projectDir, wikiIndex),
+    }));
+    const evidence = existsSync(resolve(projectDir, '.obsidian')) || resolved.some(x => x.path);
+    if (evidence) {
+      for (const { r, path } of resolved) {
+        total++;
+        if (!path) {
+          findings.push(mkFinding({
+            code: 'XRF001',
+            validator: 'crossReference',
+            severity: 'warn',
+            message: `${r.docName}:${r.line} — broken wikilink: target "[[${r.file}]]" not found`,
+            location: `${relative(projectDir, r.docPath)}:${r.line}`,
+            suggestion: { kind: 'fix', text: 'Fix the wikilink target (or remove the dead link)' },
+          }));
+          continue;
+        }
+        if (r.anchor) {
+          let anchors = anchorIndex.get(path);
+          if (!anchors) {
+            try {
+              anchors = new Set(extractHeadings(readFileSync(path, 'utf-8')).map(h => h.anchor));
+            } catch { anchors = new Set(); }
+            anchorIndex.set(path, anchors);
+          }
+          // Obsidian anchors are heading TEXT ([[Doc#Quick Start]]); compare
+          // through the same slug pipeline as inline links.
+          const normalized = slugifyHeading(r.anchor);
+          if (!anchors.has(normalized) && !anchors.has(r.anchor)) {
+            const suggestion = suggestAnchor(normalized, anchors);
+            const hint = suggestion ? ` (did you mean #${suggestion}?)` : '';
+            findings.push(mkFinding({
+              code: 'XRF002',
+              validator: 'crossReference',
+              severity: 'warn',
+              message: `${r.docName}:${r.line} — broken anchor: "[[${r.file}#${r.anchor}]]" doesn't match any heading in ${basename(path)}${hint}`,
+              location: `${relative(projectDir, r.docPath)}:${r.line}`,
+              suggestion: { kind: 'review', text: 'Update the wikilink heading to match a real heading in the target doc' },
+            }));
+            continue;
+          }
+        }
+        passed++;
+      }
+    }
+  }
+
   return { ...resultFromFindings(findings, { passed, total }), fixes };
 }
 

package/cli/validators/diff-suspicion.mjs

@@ -0,0 +1,178 @@
+/**
+ * Diff-Overlap Suspicion validator (DSP) — v0.31.0.
+ *
+ * Research basis: the outdated-comment work (arXiv 2010.01625) found that a
+ * purely deterministic rule — "flag the prose as suspect if its tokens overlap
+ * a Delete/ReplaceOld span of the code change" — hits F1 74.7, beating every
+ * post-hoc neural model. We apply it to DOCS instead of comments.
+ *
+ * Precision-first pairing (two independent signals must BOTH hold):
+ *   1. the doc REFERENCES the changed code file (path / basename / `module`),
+ *   2. the doc's wording OVERLAPS tokens that were REMOVED from that file.
+ * Requiring both is what keeps this from firing on every doc that happens to
+ * share a common word with a diff. All findings are confidence:'low' (soft /
+ * reportable) — this is a "review this" signal, never a hard failure.
+ *
+ * Change-driven: reads `config.changedSinceRef` (set by `guard --changed-only`)
+ * or falls back to HEAD~1. Returns applicable:false when there's no git history
+ * or no code change carries removed tokens, so it stays silent off-CI.
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { resolve, basename } from 'node:path';
+import { isGitRepo, getDiffText } from '../shared-git.mjs';
+import { parseUnifiedDiff, removedTokens, tokenize, tokenOverlap } from '../shared-diff.mjs';
+import { mkFinding, resultFromFindings } from '../findings.mjs';
+
+const CODE_EXTENSIONS = /\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|rb|php|cs|swift|scala|dart)$/;
+
+// Generic framework / language noise that overlaps between ANY React/TS doc and
+// ANY diff — empirically the residual false-positive source (v0.31.0 corpus:
+// "SECURITY.md ↔ page.tsx: page,set,use,state,active"). We require the shared
+// tokens to contain DOMAIN identifiers, so these are stripped before counting.
+const GENERIC_TOKENS = new Set([
+  'page', 'components', 'component', 'shared', 'nav', 'state', 'use', 'set',
+  'active', 'tab', 'react', 'props', 'prop', 'string', 'type', 'types', 'value',
+  'values', 'data', 'status', 'config', 'client', 'none', 'all', 'com', 'https',
+  'http', 'url', 'text', 'download', 'request', 'response', 'error', 'index',
+  'item', 'items', 'list', 'name', 'key', 'map', 'log', 'update', 'updated',
+  'version', 'content', 'document', 'description', 'service', 'services',
+  'object', 'array', 'number', 'boolean', 'async', 'await', 'promise', 'void',
+  'render', 'component', 'element', 'style', 'styles', 'class', 'div', 'span',
+  'button', 'input', 'form', 'label', 'title', 'header', 'footer', 'main',
+  // presentational / CSS — styling churn is not API-contract drift
+  'font', 'color', 'colors', 'tracking', 'surface', 'auto', 'full', 'next',
+  'body', 'sans', 'blue', 'accent', 'size', 'spacing', 'margin', 'padding',
+  'width', 'height', 'flex', 'grid', 'bold', 'bg', 'rounded',
+  // HTTP / REST / handler plumbing — generic across any API route (globalshares
+  // corpus: a route-inventory doc + heavy rewrites flooded findings with these)
+  'code', 'json', 'err', 'error', 'message', 'auth', 'get', 'put', 'post',
+  'patch', 'delete', 'req', 'res', 'route', 'routes', 'handler', 'endpoint',
+  'method', 'headers', 'query', 'params', 'param', 'cron', 'process', 'api',
+  'path', 'lib', 'util', 'utils', 'helper', 'helpers', 'admin', 'roles', 'role',
+  'user', 'users', 'email', 'price', 'json', 'fetch', 'axios', 'send', 'call',
+]);
+
+function escapeRegex(s) { return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
+
+// Index canonical docs + root agent-instruction files → Map<name, {lines, tokens}>.
+function indexDocs(projectDir) {
+  const docs = new Map();
+  const add = (name, full) => {
+    try {
+      const content = readFileSync(full, 'utf-8');
+      docs.set(name, { lines: content.split('\n'), tokens: tokenize(content) });
+    } catch { /* skip unreadable */ }
+  };
+  const docsDir = resolve(projectDir, 'docs-canonical');
+  if (existsSync(docsDir)) {
+    try {
+      for (const f of readdirSync(docsDir)) {
+        if (f.endsWith('.md')) add(f, resolve(docsDir, f));
+      }
+    } catch { /* skip */ }
+  }
+  // Agent-instruction files are documentation too — they routinely name code.
+  for (const agent of ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md']) {
+    const p = resolve(projectDir, agent);
+    if (existsSync(p)) add(agent, p);
+  }
+  return docs;
+}
+
+// Does the doc reference this file? We deliberately accept ONLY `path` (the
+// doc wrote the real file path) and `module` (the doc backticked the module
+// stem) references. We DROP bare `basename` matches: empirical corpus testing
+// (v0.31.0) showed basename refs pair an architecture doc that lists every
+// `page.tsx` with framework-noise tokens (page/components/state/use/nav),
+// producing false positives. path/module refs are intentional and high-signal.
+function referenceKind(docLines, file) {
+  const normalized = file.replace(/^\.\//, '');
+  const base = basename(normalized);
+  const stem = base.replace(/\.[^.]+$/, '');
+  const stemRe = new RegExp(`\`${escapeRegex(stem)}\``);
+  for (const line of docLines) {
+    if (line.includes(normalized)) return 'path';
+    if (stemRe.test(line)) return 'module';
+  }
+  return null;
+}
+
+export function validateDiffSuspicion(projectDir, config = {}) {
+  const cfg = config.diffSuspicion || {};
+  const minOverlap = Number.isInteger(cfg.minOverlap) ? cfg.minOverlap : 2;
+  const ref = cfg.since || config.changedSinceRef || 'HEAD~1';
+
+  if (!isGitRepo(projectDir)) {
+    return resultFromFindings([], { passed: 0, total: 0, applicable: false });
+  }
+
+  const diffText = getDiffText(projectDir, ref);
+  const changedFiles = parseUnifiedDiff(diffText).filter(
+    f => f.newPath && CODE_EXTENSIONS.test(f.newPath) && f.status !== 'deleted'
+  );
+  // Precompute removed-token sets; drop files whose change removed nothing.
+  const changed = changedFiles
+    .map(f => ({ path: f.newPath, removed: removedTokens(f) }))
+    .filter(f => f.removed.size > 0);
+
+  if (changed.length === 0) {
+    return resultFromFindings([], { passed: 0, total: 0, applicable: false });
+  }
+
+  const docs = indexDocs(projectDir);
+  if (docs.size === 0) {
+    return resultFromFindings([], { passed: 0, total: 0, applicable: false });
+  }
+
+  const maxPerDoc = Number.isInteger(cfg.maxPerDoc) ? cfg.maxPerDoc : 5;
+  const findings = [];
+  let pairsChecked = 0;
+  for (const [docName, doc] of docs) {
+    // Collect this doc's suspect pairs, strongest overlap first, so a doc that
+    // inventories many changed files (e.g. an API-route reference) is capped
+    // with an elision note rather than flooding — the same discipline SPK008 uses.
+    const hits = [];
+    for (const cf of changed) {
+      const kind = referenceKind(doc.lines, cf.path);
+      if (!kind) continue; // signal 1: doc must reference the changed file (path|module)
+      pairsChecked++;
+      const { shared: rawShared } = tokenOverlap(doc.tokens, cf.removed);
+      // signal 2: doc must share DOMAIN (non-generic) removed tokens
+      const shared = rawShared.filter(t => !GENERIC_TOKENS.has(t));
+      if (shared.length < minOverlap) continue;
+      hits.push({ path: cf.path, kind, shared });
+    }
+    hits.sort((a, b) => b.shared.length - a.shared.length);
+    for (const h of hits.slice(0, maxPerDoc)) {
+      findings.push(mkFinding({
+        code: 'DSP001',
+        validator: 'diff-suspicion',
+        severity: 'warn',
+        confidence: 'low',
+        message: `${docName} describes ${h.path} (${h.kind} ref), which just had ${h.shared.slice(0, 5).join(', ')}${h.shared.length > 5 ? '…' : ''} removed/changed (${ref}..HEAD) — verify the doc still matches.`,
+        location: { file: docName },
+        suggestion: {
+          summary: `Re-read ${docName} against the current ${h.path}; the removed symbols (${h.shared.slice(0, 8).join(', ')}) may now be wrong.`,
+        },
+      }));
+    }
+    if (hits.length > maxPerDoc) {
+      findings.push(mkFinding({
+        code: 'DSP001',
+        validator: 'diff-suspicion',
+        severity: 'warn',
+        confidence: 'low',
+        message: `${docName} references ${hits.length - maxPerDoc} more changed file(s) with removed domain symbols (${ref}..HEAD) — a broad change; review ${docName} as a whole.`,
+        location: { file: docName },
+        suggestion: { summary: `${docName} looks broadly affected by this change set — review it end-to-end rather than line by line.` },
+      }));
+    }
+  }
+
+  return resultFromFindings(findings, {
+    passed: pairsChecked - findings.length,
+    total: pairsChecked,
+    applicable: true,
+  });
+}