docguard-cli 0.31.0 → 0.32.0

package/README.md

@@ -62,7 +62,7 @@ DocGuard enforces **Canonical-Driven Development (CDD)** — a methodology where
 
 DocGuard is an official [GitHub Spec Kit](https://github.com/github/spec-kit) community extension. It validates the artifacts that Spec Kit creates, ensuring your specs stay high-quality throughout the development lifecycle.
 
-📖 **[Philosophy](PHILOSOPHY.md)** · 📋 **[CDD Standard](STANDARD.md)** · ⚖️ **[Comparisons](COMPARISONS.md)** · 🗺️ **[Roadmap](ROADMAP.md)**
+📖 **[Philosophy](PHILOSOPHY.md)** · 📋 **[CDD Standard](STANDARD.md)** · ⚖️ **[Comparisons](COMPARISONS.md)** · 🔬 **[Validation](VALIDATION.md)** · 🗺️ **[Roadmap](ROADMAP.md)**
 
 ### Architecture
 
@@ -274,7 +274,7 @@ DocGuard ships **18 commands** (the "Daily 5" + 13 situational tools, including
 | `verify --semantic` | Extract documented numbers/limits/enums (retention days, rate limits, GSI/role counts, status enums) as a task list for an agent to check against code — the semantic-drift class regex/AST can't see |
 | `verify --instructions` | Audit AGENTS.md/CLAUDE.md themselves for drift: duplicate rules, never-vs-always contradictions, stale file pointers, unknown commands — plus clustered rule pairs as agent judgment tasks |
 | `feedback` | Report likely false positives back to DocGuard — local-first record + a 1-click prefilled, redacted GitHub issue (zero typing) |
-| `mcp` | MCP server over stdio — exposes guard/score/explain/verify/diagnose as native tools for Claude, Cursor, and any MCP client. Setup: `claude mcp add docguard -- npx docguard-cli mcp` |
+| `mcp` | MCP server — exposes guard/score/explain/verify/diagnose as native tools for Claude, Cursor, and any MCP client. Stdio: `claude mcp add docguard -- npx docguard-cli mcp`. Team-shared HTTP: `docguard mcp --transport http --port 8585` (loopback by default; non-loopback binds require `--api-key`) |
 | `memory` | Per-domain accuracy headline (endpoints / entities / env / tech) |
 | `memory --diff` | Drill into which specific claims don't match code |
 | `memory --pack` | Write `.docguard/context-pack.md` — compact, code-truth-stamped session-start context for AI agents |
@@ -325,6 +325,9 @@ Run them solo (`docguard init --with hooks`) or stacked (`docguard init --with a
 | `--apply` | Actually run the migration | upgrade |
 | `--pr` | Open a PR with the migration | upgrade |
 | `--reverse <file>` | Reverse traceability (code → docs) | trace |
+| `--no-indirect` | Skip the reverse-import-graph analysis (docs about modules that import a changed file) | impact, diff --since |
+| `--prs` | Open-PR doc-conflict analysis — two PRs impacting the same canonical doc = merge-order risk (needs the `gh` CLI) | impact |
+| `--transport http` `--port` `--host` `--api-key` `--path` | Serve MCP over Streamable HTTP instead of stdio (team-shared server; loopback-only unless an api-key is set) | mcp |
 | `--history` | Show fix audit log | fix |
 
 ### Example Output
@@ -383,7 +386,7 @@ DocGuard runs **27 automated validators** on every `guard` check. Every one is *
 | 17 | **TODO-Tracking** | Untracked TODOs/FIXMEs and skipped tests (skips test files by default) | ✅ On |
 | 18 | **Schema-Sync** | Database models documented in DATA-MODEL.md | ✅ On |
 | 19 | **Spec-Kit** | Spec quality validation (FR-IDs, mandatory sections, phased tasks) | ✅ On |
-| 20 | **Cross-Reference** | Internal markdown links + anchors resolve (with "did you mean?" hints) | ✅ On |
+| 20 | **Cross-Reference** | Internal markdown links + anchors resolve (with "did you mean?" hints); Obsidian wikilinks validated when the repo uses them as file links (`.obsidian` present or a target resolves) | ✅ On |
 | 21 | **Generated-Staleness** | `source=code` sections match scanner output; `status: draft` doc age | ✅ On |
 | 22 | **Canonical-Sync** | DocGuard's own README count claims match code-truth (DocGuard repo only — N/A elsewhere) | ✅ On |
 | 23 | **Metrics-Consistency** | Hardcoded numbers match actual counts | ✅ On |
@@ -450,6 +453,19 @@ DocGuard works with **every major AI coding agent**. All canonical docs are plai
 | Google Gemini CLI | ✅ | `docguard agents --agent gemini` |
 | Kiro (AWS) | ✅ | — |
 
+### Always-on nudge hook (Claude Code)
+
+```bash
+docguard hooks --claude            # install   (remove: docguard hooks --claude --remove)
+```
+
+Registers a `PostToolUse` hook in the project's `.claude/settings.json`. After the
+agent edits a canonical doc it is nudged to run `docguard guard --changed-only`;
+after it edits a code file the docs reference, it is nudged toward `docguard impact`.
+Merge-safe (only DocGuard's own entry is ever added/removed), throttled to one nudge
+per file per 30 minutes, and the hook runtime can never break a session (errors are
+silent by contract). Explicit opt-in — `init` never installs it for you.
+
 ---
 
 ## ⚡ Slash Commands

package/cli/commands/hooks.mjs

@@ -3,7 +3,7 @@
  * Creates git hooks that run guard/score before commits.
  */
 
-import { existsSync, writeFileSync, mkdirSync, chmodSync, readFileSync, unlinkSync } from 'node:fs';
+import { existsSync, writeFileSync, mkdirSync, chmodSync, readFileSync, unlinkSync, readdirSync } from 'node:fs';
 
 // v0.16-P3: managed-block markers. Letting users extend the hook with their
 // own commands (data-file guards, lint checks, etc.) without us clobbering
@@ -54,7 +54,7 @@ function spliceManagedBlock(existing, newBody) {
   const bodyNoShebang = newBody.replace(/^#!.*\n/, '');
   return `${before}${BEGIN_MARKER}\n${bodyNoShebang.replace(/\n+$/, '')}\n${END_MARKER}${after}`;
 }
-import { resolve } from 'node:path';
+import { resolve, relative, basename } from 'node:path';
 import { c } from '../shared.mjs';
 import { getHooksDir } from '../shared-git.mjs';
 
@@ -217,6 +217,15 @@ export function runHooks(projectDir, config, flags) {
   console.log(`${c.bold}🪝 DocGuard Hooks — ${config.projectName}${c.reset}`);
   console.log(`${c.dim}   Directory: ${projectDir}${c.reset}\n`);
 
+  // ── Claude Code agent nudge: `docguard hooks --claude` ──
+  // Separate path from git hooks: it edits .claude/settings.json, needs no
+  // git repo, and is explicitly opt-in (writing agent config unasked is a
+  // trust break — same class as the ensureSkills READ_ONLY_COMMANDS rule).
+  if (flags.claude) {
+    installClaudeNudge(projectDir, { remove: !!flags.remove });
+    return;
+  }
+
   // Resolve the real hooks dir via git — NOT `<projectDir>/.git/hooks`, which
   // is wrong inside a linked worktree (where `.git` is a file, not a dir) and
   // ignores a custom core.hooksPath.
@@ -337,3 +346,159 @@ export function runHooks(projectDir, config, flags) {
 
   console.log('');
 }
+
+// ── Claude Code agent nudge ─────────────────────────────────────────────────
+//
+// `docguard hooks --claude` registers a PostToolUse hook in the PROJECT's
+// .claude/settings.json. After the agent edits a canonical doc (or a code
+// file the docs reference), the hook nudges it toward the right DocGuard
+// command — the graphify "query-first hook" distribution pattern, pointed at
+// doc integrity instead of graph queries.
+//
+// Trust rules:
+//   - Explicit opt-in only (never installed by ensureSkills/init).
+//   - Merge-safe: parses the existing settings.json and adds/removes ONLY the
+//     entry whose command contains the NUDGE_HOOK_COMMAND marker. A file that
+//     doesn't parse is never touched.
+//   - The runtime (`docguard nudge-hook`) is throttled and can never break an
+//     agent session: any internal error exits 0 with no output.
+
+const NUDGE_HOOK_COMMAND = 'docguard nudge-hook';
+const NUDGE_THROTTLE_MS = 30 * 60 * 1000; // one nudge per file per 30 min
+const NUDGE_STATE_PATH = '.docguard/nudge-state.json';
+const NUDGE_CODE_EXT = /\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|rb|php|cs|swift)$/;
+const NUDGE_AGENT_FILES = new Set(['AGENTS.md', 'CLAUDE.md', 'GEMINI.md']);
+
+function isOurNudgeGroup(group) {
+  return Array.isArray(group?.hooks) &&
+    group.hooks.some(h => typeof h?.command === 'string' && h.command.includes(NUDGE_HOOK_COMMAND));
+}
+
+export function installClaudeNudge(projectDir, { remove = false } = {}) {
+  const settingsDir = resolve(projectDir, '.claude');
+  const settingsPath = resolve(settingsDir, 'settings.json');
+
+  let settings = {};
+  if (existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+    } catch {
+      console.log(`  ${c.red}❌ .claude/settings.json exists but is not valid JSON — refusing to touch it.${c.reset}`);
+      console.log(`  ${c.dim}Fix the file, then re-run docguard hooks --claude.${c.reset}\n`);
+      process.exitCode = 1;
+      return;
+    }
+  }
+
+  const groups = Array.isArray(settings.hooks?.PostToolUse) ? settings.hooks.PostToolUse : [];
+  const present = groups.some(isOurNudgeGroup);
+
+  if (remove) {
+    if (!present) {
+      console.log(`  ${c.dim}⏭️  No DocGuard nudge hook found in .claude/settings.json — nothing to remove.${c.reset}\n`);
+      return;
+    }
+    settings.hooks.PostToolUse = groups.filter(g => !isOurNudgeGroup(g));
+    if (settings.hooks.PostToolUse.length === 0) delete settings.hooks.PostToolUse;
+    if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+    console.log(`  ${c.yellow}🗑️  Removed the DocGuard nudge hook from .claude/settings.json${c.reset} ${c.dim}(everything else preserved)${c.reset}\n`);
+    return;
+  }
+
+  if (present) {
+    console.log(`  ${c.green}✅ DocGuard nudge hook already installed${c.reset} ${c.dim}(.claude/settings.json — idempotent)${c.reset}\n`);
+    return;
+  }
+
+  if (!settings.hooks) settings.hooks = {};
+  if (!Array.isArray(settings.hooks.PostToolUse)) settings.hooks.PostToolUse = [];
+  settings.hooks.PostToolUse.push({
+    matcher: 'Edit|Write|MultiEdit',
+    hooks: [{ type: 'command', command: NUDGE_HOOK_COMMAND }],
+  });
+
+  if (!existsSync(settingsDir)) mkdirSync(settingsDir, { recursive: true });
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+  console.log(`  ${c.green}✅ Installed the DocGuard nudge hook${c.reset} → .claude/settings.json (PostToolUse)`);
+  console.log(`  ${c.dim}After an agent edits a canonical doc (or code the docs reference), it is${c.reset}`);
+  console.log(`  ${c.dim}nudged toward docguard guard --changed-only / docguard impact.${c.reset}`);
+  console.log(`  ${c.dim}Throttled: one nudge per file per 30 minutes. Remove: docguard hooks --claude --remove${c.reset}\n`);
+}
+
+/**
+ * Runtime for the PostToolUse hook (`docguard nudge-hook`). Reads the Claude
+ * Code hook payload from stdin, classifies the edited file, and emits a
+ * `{"decision":"block","reason":…}` nudge on stdout when — and only when —
+ * DocGuard has something specific to say. stdout is the machine channel:
+ * nothing else may be printed. Errors NEVER propagate (exit 0, silent) — a
+ * broken nudge must not degrade the agent session.
+ */
+export function runNudgeHook(projectDir) {
+  try {
+    const payload = JSON.parse(readFileSync(0, 'utf-8'));
+    const toolInput = payload.tool_input || payload.toolInput || {};
+    const filePath = toolInput.file_path || toolInput.filePath;
+    if (!filePath) return;
+
+    const rel = relative(projectDir, resolve(projectDir, filePath)).replace(/\\/g, '/');
+    if (!rel || rel.startsWith('..')) return;
+
+    let reason = null;
+    const base = basename(rel);
+    const isCanonicalDoc =
+      (rel.startsWith('docs-canonical/') && rel.endsWith('.md')) ||
+      (NUDGE_AGENT_FILES.has(base) && !rel.includes('/'));
+
+    if (isCanonicalDoc) {
+      reason = `DocGuard: you edited ${rel} — a canonical/agent doc that gates this repo. ` +
+        `Before finishing, run \`docguard guard --changed-only\` to confirm links, anchors, and count claims still hold.`;
+    } else if (NUDGE_CODE_EXT.test(rel)) {
+      const referencingDocs = docsReferencingFile(projectDir, base);
+      if (referencingDocs.length > 0) {
+        reason = `DocGuard: ${referencingDocs.slice(0, 3).join(', ')} reference${referencingDocs.length === 1 ? 's' : ''} ` +
+          `\`${base}\` — after your edits, run \`docguard impact\` to see which doc sections to re-read or update.`;
+      }
+    }
+    if (!reason) return;
+
+    // Throttle per file — iterative edits must not spam the agent.
+    const statePath = resolve(projectDir, NUDGE_STATE_PATH);
+    let state = {};
+    try { state = JSON.parse(readFileSync(statePath, 'utf-8')); } catch { /* first run */ }
+    const now = Date.now();
+    if (state[rel] && now - state[rel] < NUDGE_THROTTLE_MS) return;
+    state[rel] = now;
+    try {
+      mkdirSync(resolve(projectDir, '.docguard'), { recursive: true });
+      writeFileSync(statePath, JSON.stringify(state, null, 2) + '\n', 'utf-8');
+    } catch { /* state is best-effort; still nudge */ }
+
+    process.stdout.write(JSON.stringify({ decision: 'block', reason }) + '\n');
+  } catch {
+    // Silent by contract.
+  }
+}
+
+/** Which canonical/agent docs mention this basename? Cheap line scan. */
+function docsReferencingFile(projectDir, base) {
+  const docs = [];
+  const check = (name, full) => {
+    try {
+      if (readFileSync(full, 'utf-8').includes(base)) docs.push(name);
+    } catch { /* unreadable */ }
+  };
+  const dir = resolve(projectDir, 'docs-canonical');
+  if (existsSync(dir)) {
+    try {
+      for (const f of readdirSync(dir)) {
+        if (f.endsWith('.md')) check(f, resolve(dir, f));
+      }
+    } catch { /* unreadable dir */ }
+  }
+  for (const a of NUDGE_AGENT_FILES) {
+    const p = resolve(projectDir, a);
+    if (existsSync(p)) check(a, p);
+  }
+  return docs;
+}

package/cli/commands/impact.mjs

@@ -30,13 +30,23 @@
  * @req SC-S11-004 — non-code files (.md, .json, etc.) are skipped from impact analysis
  * @req SC-S11-007 — agent-instruction files participate in impact analysis
  * @req SC-S11-008 — a changed doc flags the docs that reference it (blast radius)
+ *
+ * Indirect impact (import-graph BFS):
+ *   A changed file with no doc references can still invalidate docs about the
+ *   modules that IMPORT it (change shared-git.mjs → the doc describing
+ *   `impact` is suspect). We walk the reverse import graph up to 2 hops —
+ *   beyond that, hub modules connect everything and the signal drowns.
+ *   JS/TS only (the graph builder's scope); `--no-indirect` disables.
+ * @req SC-S11-009 — docs referencing an importer of a changed file are flagged as indirect
  */
 
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { resolve, basename } from 'node:path';
+import { execFileSync } from 'node:child_process';
 
 import { c } from '../shared.mjs';
 import { changedFilesSince, isGitRepo } from '../shared-git.mjs';
+import { buildImportGraph } from '../validators/architecture.mjs';
 
 /**
  * File extensions we consider "code" for the purposes of impact analysis.
@@ -52,16 +62,20 @@ function escapeRegex(s) {
 }
 
 /**
- * Doc→doc references: which indexed docs reference `changedDocPath` (by its
- * basename — the form used in prose "see ARCHITECTURE.md" and markdown links
- * `](ARCHITECTURE.md)`). Skips self. This is the blast-radius edge set.
+ * Doc→doc references: which indexed docs reference `changedDocPath` — by its
+ * basename (the form used in prose "see ARCHITECTURE.md" and markdown links
+ * `](ARCHITECTURE.md)`) or by an extension-less Obsidian wikilink
+ * (`[[ARCHITECTURE]]`, `[[ARCHITECTURE#Heading]]`, `[[ARCHITECTURE|alias]]`).
+ * Skips self. This is the blast-radius edge set.
  */
 function docsReferencing(changedDocPath, index) {
   const cbase = basename(changedDocPath);
+  const stem = cbase.replace(/\.md$/i, '');
+  const wikiRe = new RegExp(`\\[\\[${escapeRegex(stem)}(?:[#|\\]])`);
   const dependents = [];
   for (const [docName, lines] of index) {
     if (docName === cbase || docName === changedDocPath) continue; // not self
-    if (lines.some(l => l.includes(cbase))) dependents.push(docName);
+    if (lines.some(l => l.includes(cbase) || wikiRe.test(l))) dependents.push(docName);
   }
   return dependents;
 }
@@ -92,7 +106,135 @@ function findReferences(file, docs) {
   return refs;
 }
 
-export function runImpact(projectDir, _config, flags) {
+/**
+ * Ancestors of `file` in the reverse import graph, capped at `maxHops`.
+ * Returns Map<ancestorPath, {hops, via}> where `via` is the first hop on the
+ * path back toward the changed file (for explainable output).
+ */
+function reverseImportAncestors(file, reverseEdges, maxHops = 2) {
+  const seen = new Map(); // ancestor → hops from the changed file
+  let frontier = [file];
+  for (let hop = 1; hop <= maxHops && frontier.length > 0; hop++) {
+    const next = [];
+    for (const cur of frontier) {
+      for (const importer of reverseEdges.get(cur) || []) {
+        if (importer === file || seen.has(importer)) continue;
+        seen.set(importer, hop);
+        next.push(importer);
+      }
+    }
+    frontier = next;
+  }
+  return seen;
+}
+
+// ── PR doc-conflict analysis (`impact --prs`) ───────────────────────────────
+//
+// Two open PRs whose changed files impact the SAME canonical doc are a
+// merge-order risk: whichever lands second must re-verify (and often re-edit)
+// a doc the first one already changed the ground truth for. The graph-
+// community version of this idea ships in graphify's `prs --conflicts`; this
+// is the doc-integrity equivalent, computed from DocGuard's own code→doc
+// reference index. Pure function — the `gh` plumbing stays at the edge.
+
+/**
+ * @param {Array<{number:number,title:string,files:string[]}>} prs
+ * @param {Map<string,string[]>} docsIndex  docName → lines[]
+ * @returns {{prImpacts: Array, conflicts: Array}}
+ */
+export function computeDocConflicts(prs, docsIndex) {
+  const prImpacts = prs.map(pr => {
+    const docs = new Set();
+    for (const f of pr.files) {
+      if (!CODE_EXTENSIONS.test(f)) {
+        // A PR that edits a canonical doc directly impacts that doc too.
+        if (f.endsWith('.md') && docsIndex.has(basename(f))) docs.add(basename(f));
+        continue;
+      }
+      for (const r of findReferences(f, docsIndex)) docs.add(r.doc);
+    }
+    return { number: pr.number, title: pr.title, docs: [...docs].sort() };
+  });
+
+  const conflicts = [];
+  for (let i = 0; i < prImpacts.length; i++) {
+    for (let j = i + 1; j < prImpacts.length; j++) {
+      const shared = prImpacts[i].docs.filter(d => prImpacts[j].docs.includes(d));
+      if (shared.length > 0) {
+        conflicts.push({ prs: [prImpacts[i].number, prImpacts[j].number], docs: shared });
+      }
+    }
+  }
+  return { prImpacts, conflicts };
+}
+
+const MAX_PRS = 20; // keep the per-PR file fetches bounded
+
+/** Fetch open PRs + their changed files via the gh CLI. Throws with a human message. */
+function fetchOpenPrs(projectDir) {
+  const gh = (args) => execFileSync('gh', args, {
+    cwd: projectDir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'],
+  });
+  let list;
+  try {
+    list = JSON.parse(gh(['pr', 'list', '--state', 'open', '--json', 'number,title', '--limit', String(MAX_PRS)]));
+  } catch (err) {
+    const msg = String(err?.message || err);
+    if (/ENOENT/.test(msg)) throw new Error('the GitHub CLI (gh) is not installed — install it or run impact without --prs');
+    throw new Error(`gh pr list failed — is this repo on GitHub and gh authenticated? (${msg.split('\n')[0]})`);
+  }
+  return list.map(pr => {
+    let files = [];
+    try {
+      files = JSON.parse(gh(['pr', 'view', String(pr.number), '--json', 'files']))
+        .files.map(f => f.path);
+    } catch { /* PR vanished mid-scan — treat as no files */ }
+    return { number: pr.number, title: pr.title, files };
+  });
+}
+
+function runPrConflicts(projectDir, flags, docsIndex) {
+  const isJson = flags.format === 'json';
+  let prs;
+  try {
+    prs = fetchOpenPrs(projectDir);
+  } catch (err) {
+    if (isJson) {
+      console.log(JSON.stringify({ error: err.message, prs: [], conflicts: [] }, null, 2));
+    } else {
+      console.log(`  ${c.yellow}⚠ ${err.message}${c.reset}`);
+    }
+    return;
+  }
+
+  const { prImpacts, conflicts } = computeDocConflicts(prs, docsIndex);
+
+  if (isJson) {
+    console.log(JSON.stringify({ prs: prImpacts, conflicts, timestamp: new Date().toISOString() }, null, 2));
+    return;
+  }
+
+  console.log(`${c.bold}📊 DocGuard Impact — open-PR doc conflicts${c.reset}\n`);
+  if (prImpacts.length === 0) {
+    console.log(`  ${c.green}✅ No open PRs.${c.reset}`);
+    return;
+  }
+  for (const pr of prImpacts) {
+    const docsNote = pr.docs.length > 0 ? pr.docs.join(', ') : `${c.dim}no canonical-doc impact${c.reset}`;
+    console.log(`  ${c.cyan}#${pr.number}${c.reset} ${pr.title.slice(0, 60)} ${c.dim}→${c.reset} ${docsNote}`);
+  }
+  if (conflicts.length === 0) {
+    console.log(`\n  ${c.green}✅ No two open PRs impact the same canonical doc.${c.reset}`);
+    return;
+  }
+  console.log(`\n  ${c.yellow}⚠ ${conflicts.length} doc-conflict pair(s) — merge order matters:${c.reset}`);
+  for (const cf of conflicts) {
+    console.log(`  ${c.yellow}#${cf.prs[0]} × #${cf.prs[1]}${c.reset} both impact ${c.cyan}${cf.docs.join(', ')}${c.reset}`);
+  }
+  console.log(`  ${c.dim}Whichever lands second should re-run docguard impact before updating the shared doc(s).${c.reset}`);
+}
+
+export function runImpact(projectDir, config, flags) {
   const isJson = flags.format === 'json';
   const since = flags.since || 'HEAD~1';
 
@@ -132,6 +274,12 @@ export function runImpact(projectDir, _config, flags) {
     try { docsIndex.set(a, readFileSync(p, 'utf-8').split('\n')); agentDocs.add(a); } catch { /* skip */ }
   }
 
+  // `impact --prs`: cross-PR doc-conflict analysis instead of a --since diff.
+  if (flags.prs) {
+    runPrConflicts(projectDir, flags, docsIndex);
+    return;
+  }
+
   // Compute per-file references
   const fileImpact = []; // { file, references: [{doc, line, kind}] }
   for (const f of codeChanged) {
@@ -152,6 +300,51 @@ export function runImpact(projectDir, _config, flags) {
     isAgentFile: agentDocs.has(doc),
   }));
 
+  // ── Indirect impact: docs about the IMPORTERS of a changed file ──
+  // Reverse-import BFS (2 hops max). A doc already directly affected by the
+  // same changed file is not repeated here — direct wins.
+  const indirectDocs = [];
+  if (flags.indirect !== false && codeChanged.length > 0) {
+    const graph = buildImportGraph(projectDir, config || {});
+    if (graph.edges.length > 0) {
+      const reverseEdges = new Map(); // to → [from…]
+      const outDegree = new Map();    // from → number of imports
+      for (const e of graph.edges) {
+        if (!reverseEdges.has(e.to)) reverseEdges.set(e.to, []);
+        reverseEdges.get(e.to).push(e.from);
+        outDegree.set(e.from, (outDegree.get(e.from) || 0) + 1);
+      }
+      // Hub suppression (dogfooded): an orchestrator that imports many modules
+      // (a CLI dispatcher, a barrel index) would flag its docs on EVERY
+      // dependency change — recurring noise, not signal. Its doc-relevant
+      // surface rarely shifts when one of 30 imports does.
+      const HUB_OUT_DEGREE = 15;
+      const isHub = (f) => (outDegree.get(f) || 0) > HUB_OUT_DEGREE;
+      const changedSet = new Set(codeChanged.map(f => f.replace(/^\.\//, '')));
+      const indirectMap = new Map(); // doc → chains[]
+      for (const f of codeChanged) {
+        const norm = f.replace(/^\.\//, '');
+        const directDocs = new Set(
+          (fileImpact.find(fi => fi.file === f)?.references || []).map(r => r.doc));
+        for (const [ancestor, hops] of reverseImportAncestors(norm, reverseEdges)) {
+          if (changedSet.has(ancestor)) continue; // changed files have their own direct row
+          if (isHub(ancestor)) continue;          // hub modules: noise, not signal
+          for (const r of findReferences(ancestor, docsIndex)) {
+            if (directDocs.has(r.doc)) continue;
+            if (!indirectMap.has(r.doc)) indirectMap.set(r.doc, []);
+            const chains = indirectMap.get(r.doc);
+            if (!chains.some(ch => ch.changed === norm && ch.via === ancestor)) {
+              chains.push({ changed: norm, via: ancestor, hops });
+            }
+          }
+        }
+      }
+      for (const [doc, chains] of indirectMap) {
+        indirectDocs.push({ doc, isAgentFile: agentDocs.has(doc), chains });
+      }
+    }
+  }
+
   // ── Doc→doc blast radius: a changed DOC flags the docs that reference it ──
   // (including agent-instruction files that point at it). Only meaningful edges
   // are emitted (changed doc with ≥1 dependent).
@@ -180,6 +373,7 @@ export function runImpact(projectDir, _config, flags) {
       changedDocs,
       ignoredFiles: changed.filter(f => !CODE_EXTENSIONS.test(f) && !f.endsWith('.md')),
       affectedDocs,
+      indirectDocs,
       blastRadius,
       timestamp: new Date().toISOString(),
     }, null, 2));
@@ -237,6 +431,20 @@ export function runImpact(projectDir, _config, flags) {
     }
   }
 
+  // Indirect impact — docs about modules that import a changed file.
+  if (indirectDocs.length > 0) {
+    console.log(`\n  ${c.bold}↺ Indirect impact${c.reset} ${c.dim}(docs about modules that import the changed files)${c.reset}`);
+    for (const { doc, isAgentFile, chains } of indirectDocs.slice(0, 8)) {
+      const tag = isAgentFile ? ` ${c.yellow}[agent-instruction]${c.reset}` : '';
+      console.log(`  ${c.cyan}${doc}${c.reset}${tag}`);
+      for (const ch of chains.slice(0, 3)) {
+        console.log(`     ${c.dim}↳ describes${c.reset} ${ch.via}${c.dim}, which imports${c.reset} ${ch.changed} ${c.dim}(${ch.hops} hop${ch.hops > 1 ? 's' : ''})${c.reset}`);
+      }
+      if (chains.length > 3) console.log(`     ${c.dim}... ${chains.length - 3} more chain(s)${c.reset}`);
+    }
+    if (indirectDocs.length > 8) console.log(`  ${c.dim}... ${indirectDocs.length - 8} more doc(s)${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) {