docguard-cli 0.27.0 → 0.29.0

package/cli/commands/guard.mjs

@@ -7,13 +7,17 @@
  *   runGuardInternal() → returns data, no side effects (for diagnose, ci)
  */
 
-import { c, resolveSeverity } from '../shared.mjs';
+import { c, resolveSeverity, loadIgnorePatterns, resolveDocDirs } from '../shared.mjs';
+import { walkFiles } from '../shared-ignore.mjs';
+import { mkFinding, resultFromFindings } from '../findings.mjs';
 import { loadValidatorSuppressions } from '../validator-markers.mjs';
 import { detectAgentMode, isSpecKitInitialized } from '../ensure-skills.mjs';
 import { checkUpgradeStatus } from './upgrade.mjs';
 import { changedFilesSince, isGitRepo } from '../shared-git.mjs';
+import { extractSemanticClaims } from '../scanners/semantic-claims.mjs';
+import { toSarif } from '../writers/sarif.mjs';
 import { readFileSync, writeFileSync, existsSync } from 'node:fs';
-import { resolve as resolvePath } from 'node:path';
+import { resolve as resolvePath, relative as relativePath } from 'node:path';
 import { fileURLToPath as fp } from 'node:url';
 import { dirname as dn } from 'node:path';
 
@@ -201,6 +205,64 @@ function renderableItems(v) {
   ];
 }
 
+// ── Doc coverage map (v0.29) ──────────────────────────────────────────────────
+// Field report #6, Gap 1: only allow-listed docs were ever validated, so a new
+// .md could drift forever while guard stayed green — the human had to REMEMBER to
+// enroll each doc, which is exactly the step that fails silently. We deliberately
+// do NOT deep-scan every doc for claims (that floods false positives — see the
+// wu-whatsappinbox scar in metrics-consistency). Instead we cheaply report what's
+// under a validation tier and what isn't, turning silent non-coverage into a
+// visible nudge. Pure visibility — never gates the build.
+//
+// DocGuard's OWN installed slash-command docs are tool-managed, not the project's
+// docs — counting them as "untracked drift" is noise the user can't act on.
+const DOCGUARD_OWN_DOC_RE = /(^|\/)commands\/docguard\.[a-z-]+\.md$/i;
+
+function collectMarkdown(projectDir) {
+  const out = [];
+  // Shared canonical walker (v0.29 consolidation) — same ignore set and dot-entry
+  // skipping as every other validator, instead of a private IGNORE_DIRS copy.
+  walkFiles(projectDir, (full) => {
+    if (full.toLowerCase().endsWith('.md')) {
+      out.push(relativePath(projectDir, full).replace(/\\/g, '/'));
+    }
+  });
+  return out;
+}
+
+/**
+ * Classify every discoverable Markdown file into a validation tier:
+ *   canonical    — in requiredFiles.canonical (structure + review-gated)
+ *   tracked      — under a doc home or root-level (claim/freshness checks reach it)
+ *   ignored      — matched by .docguardignore
+ *   unclassified — under NO tier; drift here is invisible (the Gap-1 trap)
+ */
+function computeDocCoverage(projectDir, config) {
+  const isIgnored = loadIgnorePatterns(projectDir);
+  const canonical = new Set(
+    ((config.requiredFiles && config.requiredFiles.canonical) || []).map(p => p.replace(/\\/g, '/'))
+  );
+  // Any path declared in documentTypes is a KNOWN doc (even if optional) — not
+  // "untracked." This keeps the warning specific to genuinely-unenrolled files.
+  const known = new Set(Object.keys(config.documentTypes || {}).map(p => p.replace(/\\/g, '/')));
+  // Same doc-home set the claim scanner uses — so "tracked" provably means
+  // "actually scanned," never a label the scanner ignores. With trailing slash
+  // for prefix matching.
+  const docHomePrefixes = resolveDocDirs(projectDir, config).map(d => d.replace(/\/?$/, '/'));
+  const all = collectMarkdown(projectDir);
+  let canonicalCount = 0, tracked = 0, ignored = 0;
+  const unclassified = [];
+  for (const rel of all) {
+    if (canonical.has(rel)) { canonicalCount++; continue; }
+    if (isIgnored(rel) || DOCGUARD_OWN_DOC_RE.test(rel)) { ignored++; continue; }
+    const inHome = docHomePrefixes.some(h => rel.startsWith(h));
+    const atRoot = !rel.includes('/');
+    if (inHome || atRoot || known.has(rel)) { tracked++; continue; }
+    unclassified.push(rel);
+  }
+  return { discovered: all.length, canonical: canonicalCount, tracked, ignored, unclassified };
+}
+
 export function runGuardInternal(projectDir, config) {
   const validators = config.validators || {};
   const results = [];
@@ -216,16 +278,28 @@ export function runGuardInternal(projectDir, config) {
     { key: 'security', name: 'Security', fn: () => validateSecurity(projectDir, config) },
     { key: 'architecture', name: 'Architecture', fn: () => validateArchitecture(projectDir, config) },
     { key: 'freshness', name: 'Freshness', fn: () => {
+      // v0.29: adapter now emits structured findings (FRS001–FRS005). The
+      // validator keeps its array-of-{status, code, doc, message} contract;
+      // messages are byte-identical (the sweep-needed nudge below regex-matches
+      // them), so counts/exit codes are unchanged.
       const freshnessResults = validateFreshness(projectDir, config);
-      const errors = [];
-      const warnings = [];
+      const findings = [];
       let passed = 0;
       for (const r of freshnessResults) {
-        if (r.status === 'pass') passed++;
-        else if (r.status === 'warn') warnings.push(r.message);
-        else if (r.status === 'fail') errors.push(r.message);
+        if (r.status === 'pass') { passed++; continue; }
+        if (r.status !== 'warn' && r.status !== 'fail') continue; // skip entries
+        findings.push(mkFinding({
+          code: r.code || null,
+          validator: 'freshness',
+          severity: r.status === 'fail' ? 'error' : 'warn',
+          message: r.message,
+          location: r.doc || null,
+          suggestion: r.code === 'FRS001'
+            ? { kind: 'fix', text: 'Commit the doc, or stamp it reviewed', pragma: '<!-- docguard:last-reviewed YYYY-MM-DD -->' }
+            : { kind: 'fix', text: 'Refresh the stale code-truth sections', command: 'docguard sync --write' },
+        }));
       }
-      return { errors, warnings, passed, total: passed + warnings.length + errors.length };
+      return resultFromFindings(findings, { passed, total: passed + findings.length });
     }},
     { key: 'traceability', name: 'Traceability', fn: () => validateTraceability(projectDir, config) },
     { key: 'docsDiff', name: 'Docs-Diff', fn: () => validateDocsDiff(projectDir, config) },
@@ -353,6 +427,19 @@ export function runGuardInternal(projectDir, config) {
   const nextStep =
     overallStatus === 'PASS' ? null : 'docguard diagnose';
 
+  // v0.29: coverage map + semantic-claim surfacing. Both are pure visibility —
+  // they never change errors/warnings/exit code. Skipped on the --changed-only
+  // lite path, which trades coverage for sub-2s speed and shouldn't pay for a
+  // repo-wide Markdown walk.
+  const lite = Array.isArray(config.changedFiles);
+  let coverage = null;
+  let semanticClaims = null;
+  if (!lite) {
+    try { coverage = computeDocCoverage(projectDir, config); } catch { coverage = null; }
+    try { semanticClaims = { count: extractSemanticClaims(projectDir, config).length }; }
+    catch { semanticClaims = null; }
+  }
+
   return {
     project: config.projectName,
     profile: config.profile || 'standard',
@@ -369,6 +456,8 @@ export function runGuardInternal(projectDir, config) {
     // things they've marked as high-severity.
     effectiveErrors,
     effectiveWarnings,
+    coverage,
+    semanticClaims,
     validators: results,
     // Unknown keys in `docguard:validator … n/a` markers — typo protection so
     // a mistyped key doesn't silently fail to suppress. Surfaced by runGuard.
@@ -460,14 +549,29 @@ export function runGuard(projectDir, config, flags) {
 
   const data = runGuardInternal(projectDir, config);
 
+  // ── SARIF output (2.1.0) ──
+  // Same flush discipline as the JSON branch below (bug-105): set exitCode and
+  // write+return so a piped consumer never gets a truncated payload.
+  if (flags.format === 'sarif') {
+    const sarif = toSarif(data, { projectDir });
+    process.exitCode = data.effectiveErrors > 0 ? 1 : data.effectiveWarnings > 0 ? 2 : 0;
+    process.stdout.write(JSON.stringify(sarif, null, 2) + '\n');
+    return;
+  }
+
   // ── JSON output ──
   if (flags.format === 'json') {
-    console.log(JSON.stringify(data, null, 2));
     // Use severity-aware effective counts for exit code; raw counts stay in the JSON
     // for display tools that want to show the full picture.
-    if (data.effectiveErrors > 0) process.exit(1);
-    if (data.effectiveWarnings > 0) process.exit(2);
-    process.exit(0);
+    const code = data.effectiveErrors > 0 ? 1 : data.effectiveWarnings > 0 ? 2 : 0;
+    // v0.28: set exitCode + return instead of process.exit(). A large JSON
+    // payload (>~8 KB) written to a PIPE flushes asynchronously; an immediate
+    // process.exit() truncates it mid-string, so a CI consumer parsing stdout
+    // gets "Unterminated string in JSON" on exactly the big reports that matter.
+    // Returning lets Node drain stdout and exit naturally with process.exitCode.
+    process.exitCode = code;
+    process.stdout.write(JSON.stringify(data, null, 2) + '\n');
+    return;
   }
 
   // ── Text output ──
@@ -586,6 +690,35 @@ export function runGuard(projectDir, config, flags) {
     console.log(`  ${c.dim}💡 Install ${c.cyan}/docguard.*${c.dim} commands for your agent: ${c.cyan}docguard init${c.reset}`);
   }
 
+  // ── Coverage + claim visibility (v0.29, field report #6) ──
+  // "Green" must mean "I checked these and they're clean," not "I checked the few
+  // files I was told about." Show what's under no tier (Gap 1) and that documented
+  // factual claims remain unverified vs code (Gap 2). Neither gates the build — but
+  // both must SHOW, or a green run misleads.
+  if (data.coverage) {
+    const cov = data.coverage;
+    const unclassN = cov.unclassified.length;
+    const tierLine = `${cov.canonical} canonical · ${cov.tracked} tracked · ${cov.ignored} ignored`
+      + (unclassN ? ` · ${c.yellow}${unclassN} outside any tier${c.reset}${c.dim}` : '');
+    console.log(`\n  ${c.dim}📑 Docs: ${tierLine} ${c.reset}${c.dim}(${cov.discovered} Markdown files)${c.reset}`);
+    if (unclassN > 0) {
+      // Calm by default — surface the COUNT every run (so non-coverage is never
+      // silent), but don't enumerate or cry "invisible drift": much of this is
+      // legitimately untracked (fixtures, templates, specs). The file list is one
+      // `--verbose` away. Loud-by-default here would just train users to ignore it.
+      console.log(`  ${c.dim}↪ ${unclassN} file(s) in no validation tier — add to requiredFiles.canonical, a docs/ home, or .docguardignore${flags.verbose ? ':' : ` (${skill('guard')} --verbose to list)`}${c.reset}`);
+      if (flags.verbose) {
+        for (const f of cov.unclassified.slice(0, 10)) console.log(`     ${c.dim}• ${f}${c.reset}`);
+        if (unclassN > 10) console.log(`     ${c.dim}... and ${unclassN - 10} more${c.reset}`);
+      }
+    }
+  }
+  if (data.semanticClaims && data.semanticClaims.count > 0) {
+    console.log(`\n  ${c.cyan}🔍 ${data.semanticClaims.count} documented claim(s) (counts/limits/enums) are unverified against code.${c.reset}`);
+    console.log(`     ${c.dim}A green guard means the structure is sound — NOT that these values still match the code.${c.reset}`);
+    console.log(`     ${c.dim}Confirm them: ${c.cyan}${skill('verify')} --semantic${c.reset}`);
+  }
+
   // Badge snippet
   const pct = data.total > 0 ? Math.round((data.passed / data.total) * 100) : 0;
   const bColor = pct >= 90 ? 'brightgreen' : pct >= 70 ? 'green' : pct >= 50 ? 'yellow' : 'red';
@@ -707,7 +840,8 @@ export function runGuard(projectDir, config, flags) {
   }
 
   // v0.5: severity-aware exit codes (see runGuardInternal for the rollup).
-  if (data.effectiveErrors > 0) process.exit(1);
-  if (data.effectiveWarnings > 0) process.exit(2);
-  process.exit(0);
+  // v0.28: exitCode + return (not process.exit) so the buffered text output
+  // flushes to a pipe before the process exits — same truncation fix as the
+  // JSON path above.
+  process.exitCode = data.effectiveErrors > 0 ? 1 : data.effectiveWarnings > 0 ? 2 : 0;
 }

package/cli/commands/init.mjs

@@ -78,6 +78,20 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const TEMPLATES_DIR = resolve(__dirname, '../../templates');
 
+/**
+ * v0.28 (field report #11): inject a `<!-- docguard:last-reviewed DATE -->`
+ * marker right after the first H1, so a canonical doc has a freshness signal the
+ * Freshness validator reads directly (not git mtime). No-op if one is present.
+ */
+function stampLastReviewed(content, date) {
+  const marker = `<!-- docguard:last-reviewed ${date} -->`;
+  const lines = content.split('\n');
+  const h1 = lines.findIndex(l => /^#\s/.test(l));
+  if (h1 === -1) return `${marker}\n\n${content}`;
+  lines.splice(h1 + 1, 0, '', marker);
+  return lines.join('\n');
+}
+
 // ── Readline helper ──────────────────────────────────────────────────────
 
 function askQuestion(prompt) {
@@ -263,7 +277,15 @@ export async function runInit(projectDir, config, flags) {
     if (existsSync(templatePath)) {
       const content = readFileSync(templatePath, 'utf-8');
       const today = new Date().toISOString().split('T')[0];
-      const processed = content.replace(/YYYY-MM-DD/g, today);
+      let processed = content.replace(/YYYY-MM-DD/g, today);
+      // v0.28 (field report #11): every canonical doc must ship with a freshness
+      // marker so the Freshness validator is marker-based (consistent across docs,
+      // and satisfiable in a pre-commit review loop) rather than silently falling
+      // back to git mtime. Templates now all carry one; this is the belt-and-
+      // suspenders guarantee for any future template that forgets.
+      if (mapping.dest.startsWith('docs-canonical/') && !/docguard:last-reviewed/.test(processed)) {
+        processed = stampLastReviewed(processed, today);
+      }
       writeFileSync(destPath, processed, 'utf-8');
       created.push(mapping.dest);
       console.log(`  ${c.green}✅${c.reset} Created: ${c.cyan}${mapping.dest}${c.reset}`);

package/cli/commands/llms.mjs

@@ -137,23 +137,85 @@ function getProjectDescription(projectDir) {
   return null;
 }
 
+// llms-full.txt (v0.29): the Mintlify-popularized companion form — full doc
+// bodies inlined, so an AI consumer gets everything in one fetch instead of
+// chasing the llms.txt link index. Any single doc is capped to keep one
+// runaway file from consuming the whole context window.
+const FULL_DOC_LINE_CAP = 400;
+
+/**
+ * Generate llms-full.txt content — llms.txt header + inlined doc bodies.
+ */
+export function generateLlmsFullTxt(projectDir, config) {
+  const lines = [];
+  const projectName = config.projectName || basename(projectDir);
+  const description = getProjectDescription(projectDir);
+
+  lines.push(`# ${projectName}`);
+  if (description) lines.push(`> ${description}`);
+  lines.push('');
+  lines.push('<!-- llms-full.txt — full-content form. The link-index form is llms.txt. -->');
+  lines.push('<!-- Generated by DocGuard (docguard llms --full). Regenerate after doc changes. -->');
+  lines.push('');
+
+  // Same doc discovery as the index form: canonical docs + present optional docs.
+  const docPaths = [];
+  const docsDir = resolve(projectDir, 'docs-canonical');
+  if (existsSync(docsDir)) {
+    try {
+      for (const entry of readdirSync(docsDir).filter(f => f.endsWith('.md')).sort()) {
+        docPaths.push({ path: `docs-canonical/${entry}`, desc: DOC_DESCRIPTIONS[entry] || null });
+      }
+    } catch { /* ignore */ }
+  }
+  for (const [file, desc] of Object.entries(OPTIONAL_DOCS)) {
+    if (existsSync(resolve(projectDir, file))) docPaths.push({ path: file, desc });
+  }
+
+  for (const { path, desc } of docPaths) {
+    let content;
+    try { content = readFileSync(resolve(projectDir, path), 'utf-8'); } catch { continue; }
+    lines.push('---');
+    lines.push('');
+    lines.push(`## ${path}`);
+    if (desc) lines.push(`> ${desc}`);
+    lines.push('');
+    const docLines = content.split('\n');
+    if (docLines.length > FULL_DOC_LINE_CAP) {
+      lines.push(...docLines.slice(0, FULL_DOC_LINE_CAP));
+      lines.push('');
+      lines.push(`<!-- truncated: ${docLines.length - FULL_DOC_LINE_CAP} more lines — read ${path} directly -->`);
+    } else {
+      lines.push(...docLines);
+    }
+    lines.push('');
+  }
+
+  lines.push('---');
+  lines.push(`Generated by DocGuard | [docguard-cli](https://www.npmjs.com/package/docguard-cli)`);
+  lines.push('');
+  return lines.join('\n');
+}
+
 /**
- * Public command — generate llms.txt file.
+ * Public command — generate llms.txt (or llms-full.txt with --full).
  */
 export function runLlms(projectDir, config, flags) {
-  const content = generateLlmsTxt(projectDir, config);
+  const full = !!flags.full;
+  const content = full ? generateLlmsFullTxt(projectDir, config) : generateLlmsTxt(projectDir, config);
 
   if (flags.stdout) {
     console.log(content);
     return;
   }
 
-  const outputPath = resolve(projectDir, 'llms.txt');
+  const fileName = full ? 'llms-full.txt' : 'llms.txt';
+  const outputPath = resolve(projectDir, fileName);
   writeFileSync(outputPath, content, 'utf-8');
 
-  console.log(`${c.bold}📄 DocGuard llms.txt Generator${c.reset}`);
+  console.log(`${c.bold}📄 DocGuard ${fileName} Generator${c.reset}`);
   console.log(`${c.green}✅ Generated ${outputPath}${c.reset}`);
-  console.log(`${c.dim}   Standard: llms.txt (Jeremy Howard, Answer.AI, 2024)${c.reset}`);
+  console.log(`${c.dim}   Standard: llms.txt (Jeremy Howard, Answer.AI, 2024)${full ? ' — full-content form' : ''}${c.reset}`);
   console.log(`${c.dim}   DocGuard keeps this in sync with your canonical docs.${c.reset}`);
   console.log('');
 }

package/cli/commands/mcp.mjs

@@ -0,0 +1,263 @@
+/**
+ * MCP Command — DocGuard as a Model Context Protocol server (stdio).
+ *
+ * `docguard mcp` exposes the read-only core (guard / score / explain /
+ * verify-claims / diagnose) as MCP tools any MCP client (Claude, Cursor,
+ * agent SDKs) can call over stdio. JSON-RPC 2.0, newline-delimited, per the
+ * MCP stdio transport (protocol revision 2024-11-05).
+ *
+ * Contract constraints:
+ *   - stdout IS the transport. Nothing else may be written there — the
+ *     dispatcher suppresses the banner for this command, and every diagnostic
+ *     goes to stderr.
+ *   - Tool failures are isolated: an exception inside a tool becomes an
+ *     `isError: true` tool RESULT (per MCP), never a JSON-RPC error and never
+ *     a server crash. Protocol-level problems (unparseable line, unknown
+ *     method, unknown tool) get the standard JSON-RPC error codes.
+ *   - Config is loaded PER tool call: the server is long-lived, .docguard.json
+ *     may change between calls, and the optional `projectDir` argument may
+ *     point each call at a different project.
+ *
+ * Zero npm dependencies — node:readline over process.stdin.
+ */
+
+import { createInterface } from 'node:readline';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runGuardInternal } from './guard.mjs';
+import { runScoreInternal } from './score.mjs';
+import { loadConfig } from '../config.mjs';
+import { CODES } from '../findings.mjs';
+import { extractSemanticClaims, buildSemanticVerifyTasks } from '../scanners/semantic-claims.mjs';
+
+const _PKG = JSON.parse(readFileSync(resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json'), 'utf-8'));
+
+// Oldest MCP revision this server implements; echoed back on initialize when
+// the client requests a version we recognize the shape of.
+const PROTOCOL_VERSION = '2024-11-05';
+
+// JSON-RPC 2.0 reserved error codes.
+const E_PARSE = -32700;
+const E_INVALID_REQUEST = -32600;
+const E_METHOD_NOT_FOUND = -32601;
+const E_INVALID_PARAMS = -32602;
+const E_INTERNAL = -32603;
+
+// Shared schema fragment: every project-scoped tool accepts an optional
+// projectDir and falls back to the server's working directory.
+const PROJECT_DIR_PROP = {
+  projectDir: {
+    type: 'string',
+    description: 'Path to the project to inspect (absolute, or relative to the server\'s working directory). Defaults to the working directory the server was started in.',
+  },
+};
+
+const TOOLS = [
+  {
+    name: 'docguard_guard',
+    description: 'Run every enabled DocGuard validator against the project\'s canonical docs. Returns the full guard JSON contract: status (PASS/WARN/FAIL), structured findings with stable codes and suggestions, nextStep, doc coverage map, semantic-claim count, and per-validator results.',
+    inputSchema: {
+      type: 'object',
+      properties: { ...PROJECT_DIR_PROP },
+    },
+  },
+  {
+    name: 'docguard_score',
+    description: 'Compute the project\'s CDD maturity score (0-100) with letter grade and per-category breakdown.',
+    inputSchema: {
+      type: 'object',
+      properties: { ...PROJECT_DIR_PROP },
+    },
+  },
+  {
+    name: 'docguard_explain',
+    description: 'Explain a stable DocGuard finding code (e.g. STR001, ENV003): what it means, which validator emits it, and the inline suppression to use if it\'s a confirmed false positive.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        code: {
+          type: 'string',
+          description: 'The finding code guard prints next to each finding, e.g. STR001 or ENV003. Case-insensitive.',
+        },
+      },
+      required: ['code'],
+    },
+  },
+  {
+    name: 'docguard_verify_claims',
+    description: 'Extract the semantic claims in the project\'s canonical docs — documented numbers, limits, and enums — as a verification task list. Deterministic discovery, LLM judgment — the caller verifies each claim against the code.',
+    inputSchema: {
+      type: 'object',
+      properties: { ...PROJECT_DIR_PROP },
+    },
+  },
+  {
+    name: 'docguard_diagnose',
+    description: 'Run guard and return only what needs fixing: failing/warning validators with their messages, structured findings, and suggested next actions — shaped for an agent to act on.',
+    inputSchema: {
+      type: 'object',
+      properties: { ...PROJECT_DIR_PROP },
+    },
+  },
+];
+
+/**
+ * Resolve a tool call's target project + config. loadConfig() process.exit(1)s
+ * on a malformed .docguard.json — fatal for a long-lived server — so the file
+ * is pre-parsed here and a broken config surfaces as an isError tool result.
+ */
+function resolveTarget(args, defaultDir) {
+  const dir = resolve(args && typeof args.projectDir === 'string' && args.projectDir.trim() !== '' ? args.projectDir : defaultDir);
+  if (!existsSync(dir)) throw new Error(`projectDir does not exist: ${dir}`);
+  const cfgPath = resolve(dir, '.docguard.json');
+  if (existsSync(cfgPath)) {
+    try { JSON.parse(readFileSync(cfgPath, 'utf-8')); }
+    catch (e) { throw new Error(`Cannot parse ${cfgPath}: ${e.message}`); }
+  }
+  return { dir, config: loadConfig(dir) };
+}
+
+const TOOL_HANDLERS = {
+  docguard_guard(args, defaultDir) {
+    const { dir, config } = resolveTarget(args, defaultDir);
+    return runGuardInternal(dir, config);
+  },
+
+  docguard_score(args, defaultDir) {
+    const { dir, config } = resolveTarget(args, defaultDir);
+    return runScoreInternal(dir, config);
+  },
+
+  docguard_explain(args) {
+    const code = String((args && args.code) || '').trim().toUpperCase();
+    if (!code) throw new Error('Missing required argument "code" (a stable finding code, e.g. STR001).');
+    const entry = CODES[code];
+    if (!entry) {
+      throw new Error(`Unknown finding code "${code}". Codes are the stable handles guard prints next to each finding (e.g. STR001, ENV003) — run docguard_guard and use a code from its findings.`);
+    }
+    return { code, title: entry.title, help: entry.help, suppress: entry.suppress, validator: entry.validator };
+  },
+
+  docguard_verify_claims(args, defaultDir) {
+    const { dir, config } = resolveTarget(args, defaultDir);
+    const claims = extractSemanticClaims(dir, config);
+    return {
+      claimCount: claims.length,
+      note: 'Deterministic discovery, LLM judgment — the caller verifies each claim against the code and reports any mismatch with both values.',
+      tasks: buildSemanticVerifyTasks(claims),
+    };
+  },
+
+  docguard_diagnose(args, defaultDir) {
+    const { dir, config } = resolveTarget(args, defaultDir);
+    const data = runGuardInternal(dir, config);
+    // Only what needs acting on: validators with errors/warnings, each carrying
+    // its structured findings (code + location + suggestion) when available.
+    const problems = (data.validators || [])
+      .filter((v) => (v.errors || []).length + (v.warnings || []).length > 0)
+      .map((v) => ({
+        validator: v.name,
+        key: v.key,
+        severity: v.severity || 'medium',
+        errors: v.errors || [],
+        warnings: v.warnings || [],
+        findings: (Array.isArray(v.findings) ? v.findings : []).map((f) => ({
+          code: f.code,
+          severity: f.severity,
+          message: f.message,
+          location: f.location,
+          suggestion: f.suggestion,
+        })),
+      }));
+    return {
+      status: data.status,
+      errors: data.errors,
+      warnings: data.warnings,
+      nextStep: data.nextStep,
+      problems,
+      hint: problems.length === 0
+        ? 'Nothing to fix — guard is clean.'
+        : 'Fix errors first, then warnings. Use docguard_explain with a finding code for the full remediation help.',
+    };
+  },
+};
+
+/**
+ * Serve MCP over stdio until stdin closes. The returned promise keeps the
+ * dispatcher's `await` (and thus the process) alive for the server's lifetime.
+ */
+export function runMcp(projectDir, _config, _flags) {
+  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`);
+
+  return new Promise((done) => {
+    const rl = createInterface({ input: process.stdin, terminal: false });
+    rl.on('line', (line) => {
+      const trimmed = line.trim();
+      if (!trimmed) return;
+      let msg;
+      try { msg = JSON.parse(trimmed); }
+      catch { replyError(null, E_PARSE, 'Parse error'); return; }
+      try { handleMessage(msg); }
+      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');
+      }
+    });
+    rl.on('close', () => done());
+  });
+}