docguard-cli 0.30.1 → 0.32.0

package/cli/commands/impact.mjs

@@ -15,17 +15,38 @@
  * JSON mode emits a structured `{ changedFiles, affectedDocs }` payload
  * for CI integrations and PR-comment bots.
  *
+ * v0.31.0 — blast radius (feat 1):
+ *   - Agent-instruction files (AGENTS.md/CLAUDE.md/GEMINI.md) are indexed
+ *     alongside canonical docs, so a changed code file they reference is
+ *     surfaced too (agent instructions drift when the code they describe moves).
+ *   - Doc→doc graph: when a DOC changes, the docs that reference it — INCLUDING
+ *     agent-instruction files — are flagged as suspect ("blast radius"). This is
+ *     the unclaimed slice: a change in ARCHITECTURE.md marks the AGENTS.md that
+ *     points at it for review.
+ *
  * @req SC-S11-001 — impact reports per-file → doc mappings
  * @req SC-S11-002 — files with no doc references are listed as "no impact"
  * @req SC-S11-003 — --format json emits parseable structured output
  * @req SC-S11-004 — non-code files (.md, .json, etc.) are skipped from impact analysis
+ * @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.
@@ -33,10 +54,32 @@ import { changedFilesSince, isGitRepo } from '../shared-git.mjs';
  */
 const CODE_EXTENSIONS = /\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|rb|php|cs|swift)$/;
 
+// Root agent-instruction files — documentation that names code and other docs.
+const AGENT_FILES = ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md'];
+
 function escapeRegex(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
+/**
+ * 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) || wikiRe.test(l))) dependents.push(docName);
+  }
+  return dependents;
+}
+
 /**
  * Find canonical doc references for a single file. Reuses the same three
  * match strategies as trace --reverse for consistency: direct path,
@@ -63,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';
 
@@ -81,9 +252,11 @@ export function runImpact(projectDir, _config, flags) {
   // impact" in the same sense; they ARE the docs (or config).
   const codeChanged = changed.filter(f => CODE_EXTENSIONS.test(f));
 
-  // Index canonical docs once
+  // Index canonical docs once, PLUS root agent-instruction files (they name
+  // code and other docs, so they belong in both code→doc and doc→doc analysis).
   const docsDir = resolve(projectDir, 'docs-canonical');
   const docsIndex = new Map(); // docName → lines[]
+  const agentDocs = new Set(); // which indexed docs are agent-instruction files
   if (existsSync(docsDir)) {
     try {
       for (const f of readdirSync(docsDir)) {
@@ -95,6 +268,17 @@ export function runImpact(projectDir, _config, flags) {
       }
     } catch { /* skip if dir unreadable */ }
   }
+  for (const a of AGENT_FILES) {
+    const p = resolve(projectDir, a);
+    if (!existsSync(p)) continue;
+    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}] }
@@ -113,15 +297,84 @@ export function runImpact(projectDir, _config, flags) {
   const affectedDocs = Array.from(docMap.entries()).map(([doc, files]) => ({
     doc,
     files: Array.from(files),
+    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).
+  //
+  // A source must be an INDEXED canonical/agent doc — not any changed `.md`.
+  // Otherwise a CHANGELOG.md / README.md / .wolf/*.md change flags every doc
+  // that merely mentions it in passing (dogfooding false positives).
+  const indexBasenames = new Set(docsIndex.keys());
+  const changedDocs = changed.filter(f => f.endsWith('.md') && indexBasenames.has(basename(f)));
+  const blastRadius = [];
+  for (const cd of changedDocs) {
+    const dependents = docsReferencing(cd, docsIndex);
+    if (dependents.length > 0) {
+      blastRadius.push({
+        changedDoc: cd,
+        dependents: dependents.map(d => ({ doc: d, isAgentFile: agentDocs.has(d) })),
+      });
+    }
+  }
+
   // ── JSON output ──
   if (isJson) {
     console.log(JSON.stringify({
       since,
       changedFiles: codeChanged,
-      ignoredFiles: changed.filter(f => !CODE_EXTENSIONS.test(f)),
+      changedDocs,
+      ignoredFiles: changed.filter(f => !CODE_EXTENSIONS.test(f) && !f.endsWith('.md')),
       affectedDocs,
+      indirectDocs,
+      blastRadius,
       timestamp: new Date().toISOString(),
     }, null, 2));
     return;
@@ -134,8 +387,28 @@ export function runImpact(projectDir, _config, flags) {
     console.log(`  ${c.green}✅ No file changes since ${since}.${c.reset}`);
     return;
   }
+
+  // Doc→doc blast radius — shown whether or not code changed (a doc-only change
+  // can still ripple to the docs / agent files that reference it).
+  const printBlast = () => {
+    if (blastRadius.length === 0) return;
+    console.log(`\n  ${c.bold}🌐 Doc blast radius${c.reset} ${c.dim}(${changedDocs.length} doc(s) changed)${c.reset}`);
+    for (const { changedDoc, dependents } of blastRadius) {
+      console.log(`  ${c.cyan}${changedDoc}${c.reset} ${c.dim}changed → review ${dependents.length} dependent doc(s):${c.reset}`);
+      for (const dep of dependents.slice(0, 8)) {
+        const tag = dep.isAgentFile ? ` ${c.yellow}[agent-instruction]${c.reset}` : '';
+        console.log(`     ${c.dim}↳${c.reset} ${dep.doc}${tag}`);
+      }
+      if (dependents.length > 8) console.log(`     ${c.dim}... ${dependents.length - 8} more${c.reset}`);
+    }
+  };
+
   if (codeChanged.length === 0) {
-    console.log(`  ${c.dim}No code files changed (${changed.length} non-code files: ${changed.slice(0, 3).join(', ')}${changed.length > 3 ? '…' : ''}).${c.reset}`);
+    console.log(`  ${c.dim}No code files changed (${changedDocs.length} doc(s) + ${changed.length - changedDocs.length} other non-code file(s)).${c.reset}`);
+    if (blastRadius.length === 0 && changedDocs.length > 0) {
+      console.log(`  ${c.green}✅ No other docs reference the changed doc(s).${c.reset}`);
+    }
+    printBlast();
     return;
   }
 
@@ -146,16 +419,30 @@ export function runImpact(projectDir, _config, flags) {
     console.log(`  ${c.dim}This often means the changed code is undocumented. Consider:${c.reset}`);
     console.log(`  ${c.dim}  - Running ${c.cyan}docguard generate --plan${c.dim} to add doc skeletons${c.reset}`);
     console.log(`  ${c.dim}  - Reviewing whether the change belongs in an existing doc${c.reset}`);
-    return;
+  } else {
+    console.log(`  ${c.green}${affectedDocs.length}${c.reset} canonical doc(s) reference the changed files:\n`);
+    for (const { doc, files, isAgentFile } of affectedDocs) {
+      const tag = isAgentFile ? ` ${c.yellow}[agent-instruction]${c.reset}` : '';
+      console.log(`  ${c.cyan}${doc}${c.reset}${tag} ${c.dim}(${files.length} file${files.length > 1 ? 's' : ''})${c.reset}`);
+      for (const f of files.slice(0, 5)) {
+        console.log(`     ${c.dim}via${c.reset} ${f}`);
+      }
+      if (files.length > 5) console.log(`     ${c.dim}... ${files.length - 5} more${c.reset}`);
+    }
   }
 
-  console.log(`  ${c.green}${affectedDocs.length}${c.reset} canonical doc(s) reference the changed files:\n`);
-  for (const { doc, files } of affectedDocs) {
-    console.log(`  ${c.cyan}${doc}${c.reset} ${c.dim}(${files.length} file${files.length > 1 ? 's' : ''})${c.reset}`);
-    for (const f of files.slice(0, 5)) {
-      console.log(`     ${c.dim}via${c.reset} ${f}`);
+  // 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 (files.length > 5) console.log(`     ${c.dim}... ${files.length - 5} more${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
@@ -166,4 +453,6 @@ export function runImpact(projectDir, _config, flags) {
     if (orphaned.length > 5) console.log(`     ${c.dim}... ${orphaned.length - 5} more${c.reset}`);
     console.log(`  ${c.dim}These may be undocumented — review whether they belong in an existing doc.${c.reset}`);
   }
+
+  printBlast();
 }

package/cli/commands/mcp.mjs

@@ -204,62 +204,69 @@ const TOOL_HANDLERS = {
 };
 
 /**
- * Serve MCP over stdio until stdin closes. The returned promise keeps the
+ * Transport-agnostic JSON-RPC dispatch. Returns the response message for a
+ * request, or null for notifications (which get no response by spec). Both
+ * the stdio and HTTP transports route through this one dispatcher.
+ */
+function dispatchMessage(msg, projectDir) {
+  const result = (id, res) => ({ jsonrpc: '2.0', id, result: res });
+  const error = (id, code, message) => ({ jsonrpc: '2.0', id, error: { code, message } });
+
+  if (!msg || typeof msg !== 'object' || Array.isArray(msg) || msg.jsonrpc !== '2.0' || typeof msg.method !== 'string') {
+    return error(msg && msg.id !== undefined ? msg.id : null, E_INVALID_REQUEST, 'Invalid Request');
+  }
+  const { id, method, params } = msg;
+  const isNotification = id === undefined || id === null;
+
+  switch (method) {
+    case 'initialize':
+      return result(id, {
+        protocolVersion: typeof params?.protocolVersion === 'string' ? params.protocolVersion : PROTOCOL_VERSION,
+        capabilities: { tools: {} },
+        serverInfo: { name: 'docguard', version: _PKG.version },
+      });
+    case 'ping':
+      return result(id, {});
+    case 'tools/list':
+      return result(id, { tools: TOOLS });
+    case 'tools/call': {
+      const handler = TOOL_HANDLERS[params?.name];
+      if (!handler) return error(id, E_INVALID_PARAMS, `Unknown tool: ${params?.name}`);
+      // In-tool failures are tool RESULTS (isError), not protocol errors —
+      // one bad call must never take down the server or the session.
+      try {
+        const payload = handler(params?.arguments || {}, projectDir);
+        return result(id, { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] });
+      } catch (err) {
+        return result(id, { content: [{ type: 'text', text: String((err && err.message) || err) }], isError: true });
+      }
+    }
+    default:
+      // Notifications (initialized, cancelled, …) get no response by spec.
+      if (isNotification) return null;
+      return error(id, E_METHOD_NOT_FOUND, `Method not found: ${method}`);
+  }
+}
+
+/**
+ * Serve MCP until the transport closes. The returned promise keeps the
  * dispatcher's `await` (and thus the process) alive for the server's lifetime.
+ * Default transport is stdio; `--transport http` serves the same tools over
+ * the MCP Streamable HTTP transport so one shared process can serve a team.
  */
-export function runMcp(projectDir, _config, _flags) {
+export function runMcp(projectDir, _config, flags = {}) {
+  if (flags.transport === 'http') return runMcpHttp(projectDir, flags);
+  if (flags.transport && flags.transport !== 'stdio') {
+    process.stderr.write(`docguard mcp: unknown transport "${flags.transport}" (expected stdio or http)\n`);
+    process.exitCode = 1;
+    return;
+  }
+
   const send = (msg) => {
     // A vanished client (EPIPE) is a normal shutdown, not a crash.
     try { process.stdout.write(JSON.stringify(msg) + '\n'); }
     catch { /* client gone — the readline close handler ends the server */ }
   };
-  const reply = (id, result) => send({ jsonrpc: '2.0', id, result });
-  const replyError = (id, code, message) => send({ jsonrpc: '2.0', id, error: { code, message } });
-
-  const handleMessage = (msg) => {
-    if (!msg || typeof msg !== 'object' || Array.isArray(msg) || msg.jsonrpc !== '2.0' || typeof msg.method !== 'string') {
-      replyError(msg && msg.id !== undefined ? msg.id : null, E_INVALID_REQUEST, 'Invalid Request');
-      return;
-    }
-    const { id, method, params } = msg;
-    const isNotification = id === undefined || id === null;
-
-    switch (method) {
-      case 'initialize':
-        reply(id, {
-          protocolVersion: typeof params?.protocolVersion === 'string' ? params.protocolVersion : PROTOCOL_VERSION,
-          capabilities: { tools: {} },
-          serverInfo: { name: 'docguard', version: _PKG.version },
-        });
-        return;
-      case 'ping':
-        reply(id, {});
-        return;
-      case 'tools/list':
-        reply(id, { tools: TOOLS });
-        return;
-      case 'tools/call': {
-        const handler = TOOL_HANDLERS[params?.name];
-        if (!handler) {
-          replyError(id, E_INVALID_PARAMS, `Unknown tool: ${params?.name}`);
-          return;
-        }
-        // In-tool failures are tool RESULTS (isError), not protocol errors —
-        // one bad call must never take down the server or the session.
-        try {
-          const payload = handler(params?.arguments || {}, projectDir);
-          reply(id, { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] });
-        } catch (err) {
-          reply(id, { content: [{ type: 'text', text: String((err && err.message) || err) }], isError: true });
-        }
-        return;
-      }
-      default:
-        // Notifications (initialized, cancelled, …) get no response by spec.
-        if (isNotification) return;
-        replyError(id, E_METHOD_NOT_FOUND, `Method not found: ${method}`);
-    }
-  };
 
   process.stderr.write(`docguard mcp v${_PKG.version} — serving ${TOOLS.length} tools on stdio (project: ${projectDir})\n`);
 
@@ -270,14 +277,133 @@ export function runMcp(projectDir, _config, _flags) {
       if (!trimmed) return;
       let msg;
       try { msg = JSON.parse(trimmed); }
-      catch { replyError(null, E_PARSE, 'Parse error'); return; }
-      try { handleMessage(msg); }
-      catch (err) {
+      catch { send({ jsonrpc: '2.0', id: null, error: { code: E_PARSE, message: 'Parse error' } }); return; }
+      try {
+        const resp = dispatchMessage(msg, projectDir);
+        if (resp) send(resp);
+      } catch (err) {
         // Last-resort trap: a protocol-handler bug must not kill the server.
         process.stderr.write(`docguard mcp: internal error: ${err && err.stack || err}\n`);
-        if (msg && msg.id !== undefined && msg.id !== null) replyError(msg.id, E_INTERNAL, 'Internal error');
+        if (msg && msg.id !== undefined && msg.id !== null) {
+          send({ jsonrpc: '2.0', id: msg.id, error: { code: E_INTERNAL, message: 'Internal error' } });
+        }
       }
     });
     rl.on('close', () => done());
   });
 }
+
+// ── Streamable HTTP transport ───────────────────────────────────────────────
+//
+// Minimal spec-compliant subset, zero-dep (node:http):
+//   - POST <path>: JSON-RPC request/batch in, application/json out. A body of
+//     only notifications → 202 Accepted, empty.
+//   - GET <path>: 405 — this server does not offer a server-initiated SSE
+//     stream (clients that need one fall back to plain request/response).
+//   - DELETE <path>: 200 — the server is stateless; nothing to clean up.
+//   - `Mcp-Session-Id` is issued on initialize and accepted (not required)
+//     afterwards — stateless by design, like `--stateless` HTTP MCP servers.
+//
+// Security posture (Security → Production-readiness → Simplicity):
+//   - Default bind 127.0.0.1 (loopback-only).
+//   - Binding any non-loopback host REQUIRES --api-key / DOCGUARD_API_KEY —
+//     the server refuses to start otherwise, instead of warning and exposing
+//     read access to the whole network.
+//   - When an api-key is set, every request must carry it
+//     (`Authorization: Bearer <key>` or `X-API-Key: <key>`) → else 401.
+//   - Origin allow-list on loopback binds (DNS-rebinding guard per the MCP
+//     Streamable HTTP security notes): browser-originated cross-site requests
+//     are rejected; non-browser clients send no Origin and pass.
+
+const HTTP_BODY_CAP = 4 * 1024 * 1024; // 4 MiB — guard payloads are large but bounded
+
+function isLoopbackHost(host) {
+  return host === '127.0.0.1' || host === 'localhost' || host === '::1';
+}
+
+async function runMcpHttp(projectDir, flags) {
+  const { createServer } = await import('node:http');
+  const { randomUUID } = await import('node:crypto');
+
+  const host = flags.host || '127.0.0.1';
+  const port = Number.isFinite(Number(flags.port)) && Number(flags.port) >= 0 ? Number(flags.port) : 8585;
+  const mountPath = flags.path || '/mcp';
+  const apiKey = flags.apiKey || process.env.DOCGUARD_API_KEY || '';
+
+  if (!isLoopbackHost(host) && !apiKey) {
+    process.stderr.write(
+      `docguard mcp: refusing to bind ${host} without an API key.\n` +
+      `Exposing the server beyond localhost requires --api-key <key> (or DOCGUARD_API_KEY).\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const authorized = (req) => {
+    if (!apiKey) return true;
+    const auth = req.headers['authorization'] || '';
+    const xkey = req.headers['x-api-key'] || '';
+    return auth === `Bearer ${apiKey}` || xkey === apiKey;
+  };
+
+  const originAllowed = (req) => {
+    const origin = req.headers['origin'];
+    if (!origin) return true; // non-browser clients (MCP SDKs, curl) send none
+    try {
+      const o = new URL(origin);
+      return isLoopbackHost(o.hostname);
+    } catch { return false; }
+  };
+
+  const server = createServer((req, res) => {
+    const answer = (status, body, headers = {}) => {
+      res.writeHead(status, { 'content-type': 'application/json', ...headers });
+      res.end(body === undefined ? '' : JSON.stringify(body));
+    };
+
+    const url = (req.url || '').split('?')[0];
+    if (url !== mountPath) return answer(404, { error: 'not found' });
+    if (!originAllowed(req)) return answer(403, { error: 'origin not allowed' });
+    if (!authorized(req)) return answer(401, { error: 'unauthorized' }, { 'www-authenticate': 'Bearer' });
+
+    if (req.method === 'GET') return answer(405, { error: 'SSE stream not offered — POST JSON-RPC to this endpoint' }, { allow: 'POST, DELETE' });
+    if (req.method === 'DELETE') return answer(200, {}); // stateless — nothing to end
+    if (req.method !== 'POST') return answer(405, { error: 'method not allowed' }, { allow: 'POST, DELETE' });
+
+    let size = 0;
+    const chunks = [];
+    req.on('data', (c) => {
+      size += c.length;
+      if (size > HTTP_BODY_CAP) { answer(413, { error: 'payload too large' }); req.destroy(); return; }
+      chunks.push(c);
+    });
+    req.on('end', () => {
+      if (res.writableEnded) return;
+      let parsed;
+      try { parsed = JSON.parse(Buffer.concat(chunks).toString('utf-8')); }
+      catch { return answer(400, { jsonrpc: '2.0', id: null, error: { code: E_PARSE, message: 'Parse error' } }); }
+
+      try {
+        const messages = Array.isArray(parsed) ? parsed : [parsed];
+        const responses = messages.map((m) => dispatchMessage(m, projectDir)).filter(Boolean);
+        // New sessions get an id on initialize; we accept any/none afterwards.
+        const headers = messages.some((m) => m && m.method === 'initialize')
+          ? { 'mcp-session-id': randomUUID() } : {};
+        if (responses.length === 0) return answer(202, undefined, headers); // notifications only
+        return answer(200, Array.isArray(parsed) ? responses : responses[0], headers);
+      } catch (err) {
+        process.stderr.write(`docguard mcp: internal error: ${err && err.stack || err}\n`);
+        return answer(500, { jsonrpc: '2.0', id: null, error: { code: E_INTERNAL, message: 'Internal error' } });
+      }
+    });
+  });
+
+  return new Promise((done) => {
+    server.listen(port, host, () => {
+      const addr = server.address();
+      process.stderr.write(
+        `docguard mcp v${_PKG.version} — Streamable HTTP on http://${host}:${addr.port}${mountPath} ` +
+        `(project: ${projectDir}${apiKey ? ', api-key required' : ', loopback only'})\n`);
+    });
+    server.on('close', () => done());
+  });
+}