docguard-cli 0.31.0 → 0.32.0

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());
+  });
+}

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

@@ -614,6 +614,12 @@ export const CODES = {
     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',

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/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 };
 }