docguard-cli 0.9.11 → 0.11.0

package/cli/commands/diff.mjs

@@ -6,6 +6,10 @@
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, extname, basename } from 'node:path';
 import { c } from '../shared.mjs';
+import { collectPackageJsons, detectDocker, grepEnvUsage, resolveSourceRoots } from '../shared-source.mjs';
+import { parseApiReferenceDoc, compareEndpoints } from '../scanners/api-doc.mjs';
+import { resolveApiSurface } from '../validators/api-surface.mjs';
+import { collectCodeTests } from '../validators/docs-diff.mjs';
 
 const IGNORE_DIRS = new Set([
   'node_modules', '.git', '.next', 'dist', 'build',
@@ -30,10 +34,10 @@ export function runDiff(projectDir, config, flags) {
   // 2. Entities documented vs models in code
   results.push(diffEntities(projectDir, config));
 
-  // 3. Env vars documented vs .env.example
+  // 3. Env vars documented vs .env.example + source usage
   results.push(diffEnvVars(projectDir, config));
 
-  // 4. Tech stack documented vs package.json
+  // 4. Tech stack documented vs package.json(s)
   results.push(diffTechStack(projectDir, config));
 
   // 5. Tests documented vs tests that exist
@@ -91,59 +95,39 @@ export function runDiff(projectDir, config, flags) {
 
 // ── Diff Functions ─────────────────────────────────────────────────────────
 
-function diffRoutes(dir) {
+function diffRoutes(dir, config = {}) {
+  // Documented surface: prefer the dedicated API reference, fall back to ARCHITECTURE.md.
+  const apiRefPath = resolve(dir, 'docs-canonical/API-REFERENCE.md');
   const archPath = resolve(dir, 'docs-canonical/ARCHITECTURE.md');
-  if (!existsSync(archPath)) return null;
+  const docPath = existsSync(apiRefPath) ? apiRefPath : (existsSync(archPath) ? archPath : null);
+  if (!docPath) return null;
 
-  const content = readFileSync(archPath, 'utf-8');
+  const documented = parseApiReferenceDoc(readFileSync(docPath, 'utf-8'));
 
-  // Extract route-like patterns from ARCHITECTURE.md
-  const docRoutes = new Set();
-  const routeRegex = /(?:\/api\/\S+|(?:GET|POST|PUT|DELETE|PATCH)\s+(\/\S+))/gi;
-  let match;
-  while ((match = routeRegex.exec(content)) !== null) {
-    const route = match[1] || match[0];
-    // Skip markdown table syntax and non-route content
-    if (route.startsWith('|') || route.startsWith('(') || route.length < 3) continue;
-    docRoutes.add(route);
-  }
+  // Actual surface: OpenAPI spec (sourceRoot-aware) → monorepo code scan.
+  const surface = resolveApiSurface(dir, config);
+  if (surface.confidence === 'none' && documented.length === 0) return null;
 
-  // Also check for paths in tables
-  const pathRegex = /`(\/api\/[^`]+)`/g;
-  while ((match = pathRegex.exec(content)) !== null) {
-    docRoutes.add(match[1]);
-  }
-
-  // Find route files in code
-  const codeRoutes = new Set();
-  const routeDirs = ['src/routes', 'src/app/api', 'routes', 'api'];
-  for (const rd of routeDirs) {
-    const routeDir = resolve(dir, rd);
-    if (!existsSync(routeDir)) continue;
-
-    const files = getFilesRecursive(routeDir);
-    for (const f of files) {
-      const rel = f.replace(dir + '/', '');
-      codeRoutes.add(rel);
-    }
-  }
+  const { documentedButAbsent, presentButUndocumented, matched } =
+    compareEndpoints(documented, surface.endpoints);
 
+  const fmt = (e) => `${e.method} ${e.path}`;
   return {
     title: 'API Routes',
     icon: '🛣️',
-    onlyInDocs: [...docRoutes].filter(r => ![...codeRoutes].some(cr => cr.includes(r.replace(/\//g, '/')))),
-    onlyInCode: [...codeRoutes].filter(cr => {
-      const name = basename(cr, extname(cr));
-      return ![...docRoutes].some(dr => dr.includes(name));
-    }),
-    matched: [...codeRoutes].filter(cr => {
-      const name = basename(cr, extname(cr));
-      return [...docRoutes].some(dr => dr.includes(name));
-    }),
+    onlyInDocs: documentedButAbsent.map(fmt),
+    onlyInCode: presentButUndocumented.map(fmt),
+    matched: matched.map(fmt),
   };
 }
 
-function diffEntities(dir) {
+// Non-entity filenames commonly found in model/schema dirs (infra, not entities).
+const CODE_ENTITY_NOISE = new Set([
+  'index', 'types', 'type', 'schema', 'schemas', 'registry', 'paths', 'openapi',
+  'models', 'model', 'utils', 'helpers', 'constants', 'config', 'common', 'base',
+]);
+
+function diffEntities(dir, config = {}) {
   const dataModelPath = resolve(dir, 'docs-canonical/DATA-MODEL.md');
   if (!existsSync(dataModelPath)) return null;
 
@@ -165,82 +149,57 @@ function diffEntities(dir) {
     'Testing', 'Deployment', 'Monitoring', 'Operations', 'Security',
   ]);
 
-  const headerRegex = /^### (\S+)/gm;
+  // Extract entity names ONLY from "### EntityName" headings. The previous
+  // table-cell extractor produced garbage tokens (table, index, foreign, string…);
+  // headings are the only reliable entity source in a DATA-MODEL doc.
+  const headerRegex = /^#{3,4}\s+(.+)$/gm;
   let match;
   while ((match = headerRegex.exec(content)) !== null) {
-    const name = match[1].replace(/[`*]/g, '');
-    // Skip template placeholders (<!-- ... -->) and noise words
-    if (name.startsWith('<!--') || name.length <= 2 || HEADER_NOISE.has(name) || HEADER_NOISE.has(name.toLowerCase())) {
-      continue;
-    }
-    // Skip hyphenated words (e.g., 'Trade-offs', 'Set-up') — these are section titles, not entities
-    if (name.includes('-')) continue;
+    const name = match[1].replace(/[`*]/g, '').trim();
+    if (name.startsWith('<!--') || name.length <= 2) continue;
+    if (HEADER_NOISE.has(name) || HEADER_NOISE.has(name.toLowerCase())) continue;
+    // Entity headings are a single PascalCase/snake_case identifier — not a phrase.
+    if (!/^[A-Za-z][A-Za-z0-9_]*$/.test(name)) continue;
     docEntities.add(name.toLowerCase());
   }
 
-  // Also check tables for entity references
-  const tableRegex = /\|\s*(?:`)?(\w+)(?:`)?\s*\|/g;
-  // Filter out common table headers, template placeholders, and markdown noise
-  const TABLE_NOISE = new Set([
-    'entity', 'field', 'type', 'from', 'to', 'table', 'index', 'storage',
-    'required', 'default', 'constraints', 'description', 'name', 'value',
-    'status', 'version', 'category', 'technology', 'license', 'purpose',
-    'cascade', 'relationship', 'notes', 'date', 'author', 'changes',
-    'metadata', 'tbd', 'fields', 'todo', 'example', 'primary', 'key',
-    'none', 'see', 'detected', 'yes', 'no', 'all', 'the', 'for', 'not',
-    'add', 'database', 'orm', 'source', 'unit', 'test', 'integration',
-    'metric', 'target', 'current', 'journey', 'file', 'score', 'weight',
-    'weighted', 'method', 'provider', 'token', 'expiry', 'role',
-    'permissions', 'secret', 'rotation', 'access', 'variable', 'tool',
-    'command', 'run', 'component', 'responsibility', 'location', 'tests',
-    // Data types — common in table schemas, not entity names
-    'string', 'boolean', 'number', 'integer', 'float', 'double', 'decimal',
-    'array', 'object', 'null', 'undefined', 'enum', 'varchar', 'text',
-    'timestamp', 'uuid', 'bigint', 'serial', 'json', 'jsonb', 'blob',
-    'char', 'date', 'time', 'datetime', 'binary', 'bit', 'money',
-    // Common table headers and template words
-    'true', 'false', 'header', 'checks', 'project', 'count', 'grade',
-    'breakdown', 'issuecount', 'autofixable', 'projectname', 'projecttype',
-    // Common doc section words (not entity names)
-    'trade', 'offs', 'tradeoffs', 'setup', 'overview', 'summary',
-    'details', 'configuration', 'reference', 'pattern', 'patterns',
-    'strategy', 'approach', 'impact', 'benefit', 'risk', 'concern',
-    'action', 'result', 'outcome', 'inverted', 'composite', 'secondary',
-  ]);
-  while ((match = tableRegex.exec(content)) !== null) {
-    const name = match[1];
-    // Skip short names (<=3 chars) and noise words
-    if (name.length > 3 && !TABLE_NOISE.has(name.toLowerCase())) {
-      docEntities.add(name.toLowerCase());
-    }
-  }
-
-  // Find model/entity files in code
+  // Find model/entity files in code — monorepo-aware (honors config.sourceRoot/workspaces).
   const codeEntities = new Set();
-  const modelDirs = ['src/models', 'models', 'src/entities', 'entities', 'src/schema', 'schema', 'prisma'];
-  for (const md of modelDirs) {
-    const modelDir = resolve(dir, md);
-    if (!existsSync(modelDir)) continue;
-
-    const files = getFilesRecursive(modelDir);
-    for (const f of files) {
-      const name = basename(f, extname(f)).toLowerCase();
-      if (name !== 'index') {
+  const modelSubdirs = ['models', 'entities', 'schema', 'schemas', 'prisma'];
+  const roots = resolveSourceRoots(dir, config);
+  for (const root of roots) {
+    for (const sub of modelSubdirs) {
+      const modelDir = join(root, sub);
+      if (!existsSync(modelDir)) continue;
+      const files = getFilesRecursive(modelDir);
+      for (const f of files) {
+        const name = basename(f, extname(f)).toLowerCase();
+        // Skip non-entity infrastructure/aggregation filenames.
+        if (CODE_ENTITY_NOISE.has(name)) continue;
         codeEntities.add(name);
       }
     }
   }
 
+  // No code-side entity source (e.g. DynamoDB single-table design with no model
+  // files) → cannot reliably diff. Skip rather than flag every documented entity.
+  if (codeEntities.size === 0) return null;
+
+  // Exact (normalized) matching — no fuzzy bidirectional substring includes().
+  const norm = (s) => s.replace(/[_-]/g, '').replace(/s$/, '');
+  const codeNorm = new Set([...codeEntities].map(norm));
+  const docNorm = new Map([...docEntities].map(d => [norm(d), d]));
+
   return {
     title: 'Data Entities',
     icon: '🗃️',
-    onlyInDocs: [...docEntities].filter(d => ![...codeEntities].some(ce => ce.includes(d) || d.includes(ce))),
-    onlyInCode: [...codeEntities].filter(ce => ![...docEntities].some(d => d.includes(ce) || ce.includes(d))),
-    matched: [...codeEntities].filter(ce => [...docEntities].some(d => d.includes(ce) || ce.includes(d))),
+    onlyInDocs: [...docEntities].filter(d => !codeNorm.has(norm(d))),
+    onlyInCode: [...codeEntities].filter(ce => !docNorm.has(norm(ce))),
+    matched: [...codeEntities].filter(ce => docNorm.has(norm(ce))),
   };
 }
 
-function diffEnvVars(dir) {
+function diffEnvVars(dir, config = {}) {
   const envDocPath = resolve(dir, 'docs-canonical/ENVIRONMENT.md');
   if (!existsSync(envDocPath)) return null;
 
@@ -254,16 +213,20 @@ function diffEnvVars(dir) {
     docVars.add(match[1]);
   }
 
-  // Read .env.example
+  // Code-side truth = .env.example/.env.template entries UNION process.env /
+  // import.meta.env usage across the (monorepo-aware) source roots.
   const codeVars = new Set();
-  const envExamplePath = resolve(dir, '.env.example');
-  if (existsSync(envExamplePath)) {
-    const envContent = readFileSync(envExamplePath, 'utf-8');
-    const envRegex = /^([A-Z][A-Z0-9_]+)\s*=/gm;
-    while ((match = envRegex.exec(envContent)) !== null) {
-      codeVars.add(match[1]);
+  for (const envFile of ['.env.example', '.env.template']) {
+    const envExamplePath = resolve(dir, envFile);
+    if (existsSync(envExamplePath)) {
+      const envContent = readFileSync(envExamplePath, 'utf-8');
+      const envRegex = /^([A-Z][A-Z0-9_]+)\s*=/gm;
+      while ((match = envRegex.exec(envContent)) !== null) {
+        codeVars.add(match[1]);
+      }
     }
   }
+  for (const name of grepEnvUsage(dir, config)) codeVars.add(name);
 
   if (docVars.size === 0 && codeVars.size === 0) return null;
 
@@ -276,13 +239,15 @@ function diffEnvVars(dir) {
   };
 }
 
-function diffTechStack(dir) {
+function diffTechStack(dir, config = {}) {
   const archPath = resolve(dir, 'docs-canonical/ARCHITECTURE.md');
-  const pkgPath = resolve(dir, 'package.json');
-  if (!existsSync(archPath) || !existsSync(pkgPath)) return null;
+  if (!existsSync(archPath)) return null;
+
+  // Monorepo-aware: merge dependencies across root + source-root + workspace packages.
+  const pkgs = collectPackageJsons(dir, config);
+  if (pkgs.length === 0) return null;
 
   const archContent = readFileSync(archPath, 'utf-8');
-  const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
 
   // Extract tech from ARCHITECTURE.md
   const docTech = new Set();
@@ -296,9 +261,12 @@ function diffTechStack(dir) {
     }
   }
 
-  // Extract from package.json
+  // Extract from merged package.json dependencies
   const codeTech = new Set();
-  const allDeps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+  const allDeps = {};
+  for (const { pkg } of pkgs) {
+    Object.assign(allDeps, pkg.dependencies || {}, pkg.devDependencies || {});
+  }
   const depMap = {
     'react': 'React', 'next': 'Next.js', 'vue': 'Vue', 'express': 'Express',
     'fastify': 'Fastify', 'hono': 'Hono', 'prisma': 'Prisma', '@prisma/client': 'Prisma',
@@ -311,6 +279,9 @@ function diffTechStack(dir) {
     if (allDeps[dep]) codeTech.add(tech);
   }
 
+  // Docker via Dockerfile/compose (not an npm dependency).
+  if (detectDocker(dir, config)) codeTech.add('Docker');
+
   if (docTech.size === 0 && codeTech.size === 0) return null;
 
   return {
@@ -322,42 +293,44 @@ function diffTechStack(dir) {
   };
 }
 
-function diffTests(dir) {
+function diffTests(dir, config = {}) {
   const testSpecPath = resolve(dir, 'docs-canonical/TEST-SPEC.md');
   if (!existsSync(testSpecPath)) return null;
 
-  const content = readFileSync(testSpecPath, 'utf-8');
-
-  // Extract test file references from TEST-SPEC.md
+  // Strip fenced code blocks (shell commands inside ``` ``` were mis-parsed as
+  // test files), then extract whitespace-free test tokens (literals or globs).
+  const content = readFileSync(testSpecPath, 'utf-8').replace(/```[\s\S]*?```/g, '');
   const docTests = new Set();
-  const testFileRegex = /`([^`]*\.(?:test|spec)\.[^`]+)`/g;
+  const testFileRegex = /`([^`\s]*\.(?:test|spec)\.[a-zA-Z0-9]+)`/g;
   let match;
   while ((match = testFileRegex.exec(content)) !== null) {
     docTests.add(match[1]);
   }
 
-  // Find actual test files
-  const codeTests = new Set();
-  const testDirs = ['tests', 'test', '__tests__', 'spec', 'e2e'];
-  for (const td of testDirs) {
-    const testDir = resolve(dir, td);
-    if (!existsSync(testDir)) continue;
-
-    const files = getFilesRecursive(testDir);
-    for (const f of files) {
-      const rel = f.replace(dir + '/', '');
-      codeTests.add(rel);
-    }
-  }
+  // Find actual test files (monorepo-aware: configured patterns + recursive
+  // co-located/nested scan under each source root + root-level test dirs).
+  const codeTests = collectCodeTests(dir, config);
 
   if (docTests.size === 0 && codeTests.size === 0) return null;
 
+  // Glob-aware matching (documented entries are often patterns or basenames).
+  const codeArr = [...codeTests];
+  const docArr = [...docTests];
+  const matches = (docEntry, codeRel) => {
+    const entry = String(docEntry).trim();
+    const hasSlash = entry.includes('/');
+    const target = hasSlash ? entry : basename(entry);
+    const subject = hasSlash ? codeRel : basename(codeRel);
+    const rx = new RegExp('^' + target.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*+/g, '.*') + '$');
+    return rx.test(subject);
+  };
+
   return {
     title: 'Test Files',
     icon: '🧪',
-    onlyInDocs: [...docTests].filter(t => !codeTests.has(t)),
-    onlyInCode: [...codeTests].filter(t => !docTests.has(t)),
-    matched: [...docTests].filter(t => codeTests.has(t)),
+    onlyInDocs: docArr.filter(d => !codeArr.some(c => matches(d, c))),
+    onlyInCode: codeArr.filter(c => !docArr.some(d => matches(d, c))),
+    matched: docArr.filter(d => codeArr.some(c => matches(d, c))),
   };
 }
 

package/cli/commands/fix.mjs

@@ -13,11 +13,66 @@
  *   --auto          Create skeleton files (NOT content) via init
  */
 
-import { existsSync, readFileSync, mkdirSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { resolve, basename, dirname } from 'node:path';
-import { execSync } from 'node:child_process';
+import { execSync, execFileSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { c } from '../shared.mjs';
+import { computeApiSurfaceDrift } from '../validators/api-surface.mjs';
+import { removeEndpoints, hasGeneratedMarker } from '../writers/api-reference.mjs';
+import { applyMechanicalFixes } from '../writers/mechanical.mjs';
+import { runGuardInternal } from './guard.mjs';
+
+const API_DOC = 'docs-canonical/API-REFERENCE.md';
+
+/**
+ * Apply DETERMINISTIC, no-LLM API-surface fixes: remove endpoints documented in
+ * API-REFERENCE.md that the OpenAPI spec confirms no longer exist. Removes the
+ * summary-table row and the detail block. Never rewrites prose.
+ *
+ * Safety: only edits a doc carrying the `<!-- docguard:generated true -->`
+ * marker, unless `force` is set. Idempotent.
+ *
+ * @returns {{ applied: boolean, removed: Array<{method,path}>, skipped?: string }}
+ */
+export function applyApiSurfaceWrites(projectDir, config, { force = false } = {}) {
+  const drift = computeApiSurfaceDrift(projectDir, config);
+  // Only spec-confirmed absences are safe to delete deterministically.
+  const removable = drift.confidence === 'spec' ? drift.documentedButAbsent : [];
+  if (removable.length === 0) return { applied: false, removed: [] };
+
+  const apiDocPath = resolve(projectDir, API_DOC);
+  if (!existsSync(apiDocPath)) return { applied: false, removed: [] };
+
+  const content = readFileSync(apiDocPath, 'utf-8');
+  if (!hasGeneratedMarker(content) && !force) {
+    return {
+      applied: false,
+      removed: [],
+      skipped: `${API_DOC} is not marked '<!-- docguard:generated true -->'. ` +
+        `Re-run with --force to edit it, or fix it via an AI agent (/docguard.fix --doc api-reference).`,
+    };
+  }
+
+  const { content: newContent, removed } = removeEndpoints(content, removable);
+  if (removed.length === 0 || newContent === content) {
+    return { applied: false, removed: [] }; // idempotent no-op
+  }
+
+  writeFileSync(apiDocPath, newContent, 'utf-8');
+  // Map removed keys back to {method,path} for reporting.
+  const removedEndpoints = removable.filter(e => removed.includes(`${e.method.toUpperCase()} ${normalizeForKey(e.path)}`));
+  return { applied: true, removed: removedEndpoints.length ? removedEndpoints : removable };
+}
+
+// Local mirror of api-doc normalizePath for matching removed keys (avoids an
+// extra import cycle); only used for display reconciliation.
+function normalizeForKey(p) {
+  let s = String(p).trim().replace(/^[|`'"\s]+/, '').replace(/[|`'"\s]+$/, '').split(/[?#]/)[0];
+  s = s.replace(/\{[^}/]+\}/g, '{}').replace(/:[^/]+/g, '{}');
+  if (s.length > 1) s = s.replace(/\/+$/, '');
+  return s;
+}
 
 // ── Document Quality Definitions ───────────────────────────────────────────
 // What each doc SHOULD contain, and what to look for in the codebase
@@ -144,6 +199,39 @@ WRITE THE DOCUMENT:
 IMPORTANT: Reference REAL test files. If there are no tests yet, document what SHOULD be tested.`,
   },
 
+  'docs-canonical/API-REFERENCE.md': {
+    label: 'API Reference',
+    purpose: 'Document every HTTP endpoint so the docs match the real API surface (no phantom or missing routes)',
+    qualitySignals: [
+      'Every documented endpoint exists in the OpenAPI spec or route definitions',
+      'No endpoints that were removed from code are still documented',
+      'Every real endpoint in code is documented',
+      'Method + path + auth + request/response shapes are accurate',
+      'No TODO or example placeholders',
+    ],
+    aiResearchInstructions: `
+RESEARCH STEPS:
+1. Find the authoritative API surface FIRST:
+   - Look for an OpenAPI/Swagger spec (openapi.yaml/json, swagger.yaml) under the project root,
+     the source-root package (e.g. backend/), and docs/ — this is the source of truth.
+   - If no spec, scan route definitions: Express \`app.get/post/...\`, Next.js app/api route.ts,
+     Fastify/Hono \`.get/.post\`, FastAPI/Django decorators — under the configured sourceRoot.
+2. Build the real list of {METHOD, path} endpoints from that surface.
+3. Read the CURRENT docs-canonical/API-REFERENCE.md and extract its documented endpoints.
+4. Diff the two lists:
+   - DOCUMENTED-BUT-ABSENT: in the doc but NOT in code → these are stale, DELETE them.
+   - PRESENT-BUT-UNDOCUMENTED: in code but NOT in the doc → ADD them.
+
+WRITE THE DOCUMENT:
+- Remove every endpoint that no longer exists in code (e.g. a deleted integration's routes).
+- Add every real endpoint that is missing, with method, path, auth requirement, and request/response.
+- Keep the existing table/heading format the doc already uses.
+- After editing, also update CHANGELOG.md ([Unreleased]) and DRIFT-LOG.md to record the removal/addition.
+
+IMPORTANT: The OpenAPI spec / route code is the source of truth — the doc must conform to it, not vice versa.
+Do NOT invent endpoints. Use REAL method+path values.`,
+  },
+
   'docs-canonical/ENVIRONMENT.md': {
     label: 'Environment',
     purpose: 'Document setup steps, dependencies, and environment variables',
@@ -174,6 +262,57 @@ IMPORTANT: A new contributor should be able to follow this doc and have the proj
   },
 };
 
+// ── Deterministic --write mode ───────────────────────────────────────────────
+
+/**
+ * Collect every structured mechanical fix surfaced by the validators and apply
+ * them deterministically (no LLM). Covers: remove-endpoint (API-Surface),
+ * replace-count (Metrics-Consistency), replace-version (Metadata-Sync),
+ * insert-changelog-unreleased (Changelog).
+ * @returns {{ applied: object[], skipped: object[], total: number }}
+ */
+export function applyAllMechanicalFixes(projectDir, config, { force = false } = {}) {
+  const guardData = runGuardInternal(projectDir, config);
+  const fixes = [];
+  for (const v of guardData.validators) {
+    if (Array.isArray(v.fixes)) fixes.push(...v.fixes);
+  }
+  const { applied, skipped } = applyMechanicalFixes(projectDir, fixes, { force });
+  return { applied, skipped, total: fixes.length };
+}
+
+function runWriteMode(projectDir, config, flags) {
+  const isJson = flags.format === 'json';
+  const { applied, skipped, total } = applyAllMechanicalFixes(projectDir, config, { force: flags.force });
+
+  if (isJson) {
+    console.log(JSON.stringify({
+      status: applied.length ? 'applied' : (total ? 'skipped' : 'clean'),
+      applied,
+      skipped,
+    }, null, 2));
+    return;
+  }
+
+  console.log(`${c.bold}🔧 DocGuard Fix --write — ${config.projectName}${c.reset}\n`);
+  if (total === 0) {
+    console.log(`  ${c.green}✅ No mechanical fixes needed — the docs match the code.${c.reset}\n`);
+    return;
+  }
+  if (applied.length === 0) {
+    console.log(`  ${c.dim}Nothing applied (idempotent or gated).${c.reset}`);
+    for (const s of skipped) console.log(`     ${c.yellow}⚠ ${s.type}: ${s.reason}${c.reset}`);
+    console.log('');
+    return;
+  }
+  console.log(`  ${c.green}✅ Applied ${applied.length} deterministic fix(es):${c.reset}`);
+  for (const a of applied) console.log(`     ${c.green}✔ ${a.detail}${c.reset}`);
+  if (skipped.length) {
+    for (const s of skipped) console.log(`     ${c.yellow}⚠ ${s.type}: ${s.reason}${c.reset}`);
+  }
+  console.log(`\n  ${c.dim}Verify with ${c.cyan}docguard guard${c.dim}, then commit. Prose rewrites still need an AI agent (${c.cyan}/docguard.fix${c.dim}).${c.reset}\n`);
+}
+
 // ── Main Entry ─────────────────────────────────────────────────────────────
 
 export function runFix(projectDir, config, flags) {
@@ -182,6 +321,12 @@ export function runFix(projectDir, config, flags) {
   const autoFix = flags.auto || false;
   const specificDoc = flags.doc || null;
 
+  // --write: deterministically APPLY mechanical fixes (no LLM). Currently:
+  // remove API-REFERENCE.md endpoints the OpenAPI spec confirms no longer exist.
+  if (flags.write) {
+    return runWriteMode(projectDir, config, flags);
+  }
+
   // If --doc flag is provided, generate a deep prompt for that specific document
   if (specificDoc) {
     return generateDocPrompt(projectDir, config, specificDoc);
@@ -414,12 +559,15 @@ function generateDocPrompt(projectDir, config, docName) {
     'testspec': 'docs-canonical/TEST-SPEC.md',
     'environment': 'docs-canonical/ENVIRONMENT.md',
     'env': 'docs-canonical/ENVIRONMENT.md',
+    'api-reference': 'docs-canonical/API-REFERENCE.md',
+    'api': 'docs-canonical/API-REFERENCE.md',
+    'apireference': 'docs-canonical/API-REFERENCE.md',
   };
 
   const filePath = mapping[normalized];
   if (!filePath) {
     console.error(`${c.red}Unknown document: ${docName}${c.reset}`);
-    console.log(`${c.dim}Available: architecture, data-model, security, test-spec, environment${c.reset}`);
+    console.log(`${c.dim}Available: architecture, data-model, security, test-spec, environment, api-reference${c.reset}`);
     process.exit(1);
   }
 
@@ -473,7 +621,7 @@ function autoFixIssues(projectDir, config, issues) {
 
   try {
     const cliPath = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'docguard.mjs');
-    execSync(`node ${cliPath} init --dir "${projectDir}"`, {
+    execFileSync(process.execPath, [cliPath, 'init', '--dir', projectDir], {
       encoding: 'utf-8',
       stdio: 'pipe',
     });