docguard-cli 0.10.0 → 0.11.1

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, 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
@@ -207,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) {
@@ -215,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);

package/cli/commands/generate.mjs

@@ -11,6 +11,8 @@ import { c } from '../shared.mjs';
 import { detectDocTools } from '../scanners/doc-tools.mjs';
 import { scanRoutesDeep } from '../scanners/routes.mjs';
 import { scanSchemasDeep, generateERDiagram } from '../scanners/schemas.mjs';
+import { buildMemoryPlan } from '../scanners/memory-plan.mjs';
+import { upsertSection } from '../writers/sections.mjs';
 
 const IGNORE_DIRS = new Set([
   'node_modules', '.git', '.next', 'dist', 'build', 'coverage',
@@ -111,7 +113,96 @@ function appendStandardsCitation(content, docName) {
   return content.trimEnd() + '\n' + footer;
 }
 
+/**
+ * `docguard generate --plan` — AI-powered Generate.
+ * Builds the code-truth skeleton (marked sections) and emits the agent task
+ * manifest. `--format json` → machine manifest for an agent; text → summary.
+ * `--write` → scaffold the skeleton docs (code sections filled; prose sections
+ * inserted as agent-task placeholders), respecting human prose via markers.
+ */
+export function runGeneratePlan(projectDir, config, flags) {
+  const plan = buildMemoryPlan(projectDir, config);
+
+  if (flags.format === 'json') {
+    console.log(JSON.stringify({
+      project: config.projectName,
+      profile: {
+        languages: plan.profile.languages,
+        frameworks: plan.profile.frameworks,
+        polyglot: plan.profile.polyglot,
+        kind: plan.profile.kind,
+        ecosystems: plan.profile.ecosystems.map(e => ({ dir: e.dir, language: e.language, framework: e.framework, kind: e.kind })),
+      },
+      surface: {
+        endpoints: plan.surface.endpoints.length,
+        entities: plan.surface.entities.length,
+        screens: plan.surface.screens.length,
+        components: plan.surface.components.length,
+        envVars: plan.surface.envVars.length,
+      },
+      docs: plan.docs.map(d => ({
+        path: d.path,
+        sections: d.sections.map(s => s.source === 'code'
+          ? { id: s.id, source: 'code' }
+          : { id: s.id, source: 'human', task: s.task, grounding: s.grounding }),
+      })),
+      agentTasks: plan.agentTasks,
+      timestamp: new Date().toISOString(),
+    }, null, 2));
+    return;
+  }
+
+  // --write: scaffold the skeleton docs with code sections + agent-task placeholders.
+  if (flags.write) {
+    const docsDir = resolve(projectDir, 'docs-canonical');
+    if (!existsSync(docsDir)) mkdirSync(docsDir, { recursive: true });
+    let wrote = 0;
+    for (const doc of plan.docs) {
+      const full = resolve(projectDir, doc.path);
+      const title = basename(doc.path, '.md').replace(/-/g, ' ');
+      let content = existsSync(full)
+        ? readFileSync(full, 'utf-8')
+        : `# ${title}\n\n<!-- docguard:generated true -->\n`;
+      for (const sec of doc.sections) {
+        const body = sec.source === 'code'
+          ? sec.body
+          : `> **AI task:** ${sec.task}\n<!-- docguard:pending agent writes this section -->`;
+        content = upsertSection(content, sec.id, body, { source: sec.source }).content;
+      }
+      writeFileSync(full, content, 'utf-8');
+      wrote++;
+    }
+    console.log(`${c.bold}🔮 DocGuard Generate --plan --write — ${config.projectName}${c.reset}`);
+    console.log(`  ${c.green}✅ Scaffolded ${wrote} doc(s)${c.reset} with code-truth sections + ${plan.agentTasks.length} agent task(s).`);
+    console.log(`  ${c.dim}Now run your AI agent (/docguard.fix) to write the prose sections, then ${c.cyan}docguard guard${c.dim}.${c.reset}\n`);
+    return;
+  }
+
+  // Text summary.
+  console.log(`${c.bold}🔮 DocGuard Generate Plan — ${config.projectName}${c.reset}`);
+  console.log(`${c.dim}   ${plan.profile.polyglot ? 'Polyglot' : 'Single-language'}: ${plan.profile.languages.join(', ')} | frameworks: ${plan.profile.frameworks.join(', ') || '—'} | kind: ${plan.profile.kind}${c.reset}\n`);
+  console.log(`  ${c.bold}Code-truth surface:${c.reset} ${plan.surface.endpoints.length} endpoints · ${plan.surface.entities.length} entities · ${plan.surface.screens.length} screens · ${plan.surface.components.length} components · ${plan.surface.envVars.length} env vars\n`);
+  console.log(`  ${c.bold}Documents to build (${plan.docs.length}):${c.reset}`);
+  for (const d of plan.docs) {
+    const code = d.sections.filter(s => s.source === 'code').length;
+    const prose = d.sections.filter(s => s.source === 'human').length;
+    console.log(`    ${c.cyan}${d.path}${c.reset} ${c.dim}(${code} code section(s), ${prose} agent task(s))${c.reset}`);
+  }
+  console.log(`\n  ${c.bold}🤖 Agent tasks (${plan.agentTasks.length}):${c.reset} ${c.dim}prose the AI must write, grounded in scanned facts.${c.reset}`);
+  for (const t of plan.agentTasks) {
+    console.log(`    ${c.dim}• [${t.doc} → ${t.sectionId}] ${t.instruction}${c.reset}`);
+  }
+  console.log(`\n  ${c.dim}Scaffold the skeleton: ${c.cyan}docguard generate --plan --write${c.dim} · Machine manifest: ${c.cyan}--plan --format json${c.reset}\n`);
+}
+
 export function runGenerate(projectDir, config, flags) {
+  // --plan: emit the AI-powered "memory plan" — the agent task manifest. The CLI
+  // builds the code-truth skeleton (marked sections) + tells the agent exactly
+  // what prose to write per section. This is the language-aware Generate path.
+  if (flags.plan) {
+    return runGeneratePlan(projectDir, config, flags);
+  }
+
   console.log(`${c.bold}🔮 DocGuard Generate — ${config.projectName}${c.reset}`);
   console.log(`${c.dim}   Directory: ${projectDir}${c.reset}`);
   console.log(`${c.dim}   Scanning codebase to generate canonical documentation...${c.reset}\n`);

package/cli/commands/hooks.mjs

@@ -128,6 +128,40 @@ exit 0
   },
 };
 
+// Auto-fix variant of the pre-commit hook: apply deterministic fixes, re-stage,
+// then validate. Installed with: docguard hooks --type pre-commit --auto-fix
+const PRE_COMMIT_AUTOFIX = `#!/bin/sh
+# DocGuard pre-commit hook (auto-fix mode)
+# Applies deterministic (no-LLM) fixes, then validates.
+# Install: docguard hooks --type pre-commit --auto-fix
+# Remove: rm .git/hooks/pre-commit
+
+RUN="npx docguard-cli"
+if command -v docguard >/dev/null 2>&1; then RUN="docguard"; fi
+
+echo "🛡️  DocGuard: applying mechanical fixes…"
+# 1. Deterministically remove stale documented endpoints (safe, no AI).
+$RUN fix --write
+# 2. Re-stage anything DocGuard rewrote so the fix is part of THIS commit.
+git add docs-canonical/ 2>/dev/null
+
+# 3. Validate.
+$RUN guard
+EXIT_CODE=$?
+
+if [ $EXIT_CODE -eq 1 ]; then
+  echo ""
+  echo "❌ DocGuard guard FAILED — commit blocked."
+  echo "   Remaining issues need an AI agent (content rewrites, not mechanical):"
+  echo "   Run: $RUN diagnose   (emits ready-to-paste agent fix prompts)"
+  echo "   To skip: git commit --no-verify"
+  exit 1
+elif [ $EXIT_CODE -eq 2 ]; then
+  echo "⚠️  DocGuard guard found warnings — commit allowed"
+fi
+exit 0
+`;
+
 export function runHooks(projectDir, config, flags) {
   console.log(`${c.bold}🪝 DocGuard Hooks — ${config.projectName}${c.reset}`);
   console.log(`${c.dim}   Directory: ${projectDir}${c.reset}\n`);
@@ -208,9 +242,13 @@ export function runHooks(projectDir, config, flags) {
       continue;
     }
 
-    writeFileSync(hookPath, HOOKS[name].content, 'utf-8');
+    // pre-commit supports an auto-fix variant (applies mechanical fixes first).
+    const useAutofix = name === 'pre-commit' && flags.autoFix;
+    const content = useAutofix ? PRE_COMMIT_AUTOFIX : HOOKS[name].content;
+    writeFileSync(hookPath, content, 'utf-8');
     chmodSync(hookPath, 0o755); // Make executable
-    console.log(`  ${c.green}✅ ${name}${c.reset}: ${HOOKS[name].description}`);
+    const desc = useAutofix ? 'Apply mechanical fixes (fix --write) then guard' : HOOKS[name].description;
+    console.log(`  ${c.green}✅ ${name}${c.reset}: ${desc}`);
     installed++;
   }
 

package/cli/commands/score.mjs

@@ -26,12 +26,30 @@ export function runScore(projectDir, config, flags) {
 
   const { scores, totalScore, grade, details } = calcAllScores(projectDir, config);
 
+  // ── "Memory" framing: split signals into Completeness vs Accuracy ──
+  // Completeness = "is the memory whole?"  Accuracy = "does it match code?"
+  // No weight changes — just a derived view of the existing per-category scores.
+  const COMPLETENESS = new Set(['structure', 'docQuality']);
+  const memory = (() => {
+    let cW = 0, cP = 0, aW = 0, aP = 0;
+    for (const [cat, s] of Object.entries(scores)) {
+      const w = WEIGHTS[cat] || 0;
+      if (COMPLETENESS.has(cat)) { cW += w; cP += s * w; }
+      else { aW += w; aP += s * w; }
+    }
+    return {
+      completeness: cW ? Math.round(cP / cW) : 0,
+      accuracy: aW ? Math.round(aP / aW) : 0,
+    };
+  })();
+
   // ── Display Results ──
   if (flags.format === 'json') {
     const result = {
       project: config.projectName,
       score: totalScore,
       grade,
+      memory,
       categories: {},
     };
     for (const [cat, score] of Object.entries(scores)) {
@@ -39,6 +57,7 @@ export function runScore(projectDir, config, flags) {
         score,
         weight: WEIGHTS[cat],
         weighted: Math.round((score / 100) * WEIGHTS[cat]),
+        axis: COMPLETENESS.has(cat) ? 'completeness' : 'accuracy',
       };
     }
     console.log(JSON.stringify(result, null, 2));
@@ -60,6 +79,9 @@ export function runScore(projectDir, config, flags) {
 
   const gradeColor = totalScore >= 80 ? c.green : totalScore >= 60 ? c.yellow : c.red;
   console.log(`  ${gradeColor}${c.bold}CDD Maturity Score: ${totalScore}/100 (${grade})${c.reset}`);
+  // Memory framing: is the documentation memory COMPLETE and ACCURATE?
+  const memColor = (s) => s >= 80 ? c.green : s >= 60 ? c.yellow : c.red;
+  console.log(`  ${c.dim}Memory:${c.reset} ${memColor(memory.completeness)}Completeness ${memory.completeness}%${c.reset} ${c.dim}·${c.reset} ${memColor(memory.accuracy)}Accuracy ${memory.accuracy}%${c.reset}`);
 
   // Grade description
   const descriptions = {

package/cli/commands/sync.mjs

@@ -0,0 +1,123 @@
+/**
+ * Sync Command — keep the documentation memory ALWAYS UP TO DATE.
+ *
+ * Re-derives the code-truth surface (endpoints, entities, screens, tech-stack,
+ * env vars) and refreshes the matching `source=code` sections of existing
+ * canonical docs IN PLACE — mechanically, no LLM, idempotent. Human prose is
+ * never touched (it lives outside markers / in `source=human` sections).
+ *
+ * When a code section changes, the prose sections in that doc are flagged for
+ * agent review (e.g. "endpoints changed → re-read the API overview").
+ *
+ * Default is a DRY RUN (preview); `--write` applies. `--since <ref>` adds the
+ * git diff as context. Only edits docguard:generated docs unless `--force`.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { c } from '../shared.mjs';
+import { buildMemoryPlan } from '../scanners/memory-plan.mjs';
+import { getSection, replaceSection } from '../writers/sections.mjs';
+import { hasGeneratedMarker } from '../writers/api-reference.mjs';
+
+function gitChangedFiles(projectDir, since) {
+  const run = (args) => {
+    try {
+      return execFileSync('git', args, { cwd: projectDir, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] })
+        .split('\n').map(s => s.trim()).filter(Boolean);
+    } catch { return null; }
+  };
+  const committed = run(['diff', '--name-only', `${since}...HEAD`]);
+  if (committed === null) return null;
+  const working = run(['diff', '--name-only', since]) || [];
+  return [...new Set([...committed, ...working])];
+}
+
+export function runSync(projectDir, config, flags) {
+  const plan = buildMemoryPlan(projectDir, config);
+  const apply = !!flags.write;
+  const isJson = flags.format === 'json';
+  const changed = flags.since ? gitChangedFiles(projectDir, flags.since) : null;
+
+  const updates = [];   // { doc, section, status }
+  const reviews = [];   // { doc, section, reason }
+  const skipped = [];   // { doc, reason }
+
+  for (const doc of plan.docs) {
+    const full = resolve(projectDir, doc.path);
+    if (!existsSync(full)) {
+      skipped.push({ doc: doc.path, reason: 'not present — run `generate --plan --write` to create it' });
+      continue;
+    }
+    let content = readFileSync(full, 'utf-8');
+    if (!hasGeneratedMarker(content) && !flags.force) {
+      skipped.push({ doc: doc.path, reason: 'not marked docguard:generated (use --force to sync anyway)' });
+      continue;
+    }
+
+    let docChanged = false;
+    let codeSectionChanged = false;
+    for (const sec of doc.sections) {
+      if (sec.source !== 'code') continue;
+      const existing = getSection(content, sec.id);
+      if (!existing) continue; // sync refreshes sections that already exist
+      if (existing.body.trim() === String(sec.body).trim()) continue; // already current
+      codeSectionChanged = true;
+      updates.push({ doc: doc.path, section: sec.id, status: apply ? 'updated' : 'stale' });
+      if (apply) { content = replaceSection(content, sec.id, sec.body).content; docChanged = true; }
+    }
+
+    // If code changed, the prose around it may need an agent's eyes.
+    if (codeSectionChanged) {
+      for (const sec of doc.sections) {
+        if (sec.source === 'human') {
+          reviews.push({ doc: doc.path, section: sec.id, reason: 'a code section in this doc changed — review the prose' });
+        }
+      }
+    }
+
+    if (apply && docChanged) writeFileSync(full, content, 'utf-8');
+  }
+
+  if (isJson) {
+    console.log(JSON.stringify({
+      project: config.projectName,
+      since: flags.since || null,
+      changedFiles: changed,
+      applied: apply,
+      updates,
+      reviews,
+      skipped,
+      timestamp: new Date().toISOString(),
+    }, null, 2));
+    return;
+  }
+
+  console.log(`${c.bold}🔄 DocGuard Sync — ${config.projectName}${c.reset}`);
+  if (flags.since) {
+    const n = changed === null ? 'git unavailable' : `${changed.length} file(s) changed since ${flags.since}`;
+    console.log(`${c.dim}   ${n}${c.reset}`);
+  }
+  console.log(`${c.dim}   ${apply ? 'Applying' : 'Dry run (use --write to apply)'}${c.reset}\n`);
+
+  if (updates.length === 0) {
+    console.log(`  ${c.green}✅ Documentation memory is up to date — no code-truth sections drifted.${c.reset}\n`);
+  } else {
+    console.log(`  ${apply ? c.green : c.yellow}${apply ? '✅ Refreshed' : '⚠️  Stale'} ${updates.length} code-truth section(s):${c.reset}`);
+    for (const u of updates) console.log(`     ${apply ? c.green : c.yellow}${apply ? '↻' : '•'} ${u.doc} → ${u.section}${c.reset}`);
+    if (reviews.length > 0) {
+      console.log(`\n  ${c.bold}🤖 Prose to review (${reviews.length}) — code changed near these sections:${c.reset}`);
+      for (const r of reviews) console.log(`     ${c.dim}• ${r.doc} → ${r.section}${c.reset}`);
+      console.log(`  ${c.dim}Run your AI agent (/docguard.fix) to refresh the prose, then ${c.cyan}docguard guard${c.dim}.${c.reset}`);
+    }
+    if (!apply) console.log(`\n  ${c.dim}Apply mechanical refreshes: ${c.cyan}docguard sync --write${c.reset}`);
+    console.log('');
+  }
+
+  if (skipped.length > 0 && flags.verbose) {
+    console.log(`  ${c.dim}Skipped:${c.reset}`);
+    for (const s of skipped) console.log(`     ${c.dim}- ${s.doc}: ${s.reason}${c.reset}`);
+    console.log('');
+  }
+}

package/cli/docguard.mjs

@@ -35,6 +35,7 @@ import { runCI } from './commands/ci.mjs';
 import { runFix } from './commands/fix.mjs';
 import { runWatch } from './commands/watch.mjs';
 import { runDiagnose } from './commands/diagnose.mjs';
+import { runSync } from './commands/sync.mjs';
 import { runPublish } from './commands/publish.mjs';
 import { runTrace } from './commands/trace.mjs';
 import { runLlms } from './commands/llms.mjs';
@@ -236,6 +237,10 @@ ${c.bold}Enforcement:${c.reset}
   ${c.green}guard${c.reset}      Validate project against canonical docs (51+ checks)
   ${c.green}diagnose${c.reset}   AI orchestrator — guard → fix in one command
 
+${c.bold}Memory (build & maintain docs):${c.reset}
+  ${c.green}generate --plan${c.reset}  AI-powered: scan any project, emit agent task manifest + skeleton
+  ${c.green}sync${c.reset}       Refresh code-truth doc sections to match current code (always up to date)
+
 ${c.bold}Analysis:${c.reset}
   ${c.green}score${c.reset}      CDD maturity score (0-100)
   ${c.green}trace${c.reset}      Requirements traceability matrix
@@ -267,6 +272,13 @@ ${c.bold}Options:${c.reset}
   --threshold <n> Minimum score for CI pass (used with ci command)
   --fail-on-warning  Fail CI on warnings (used with ci command)
   --auto          Auto-fix what's possible (used with fix command)
+  --write         Apply deterministic fixes in place (fix command): removes
+                  documented endpoints the OpenAPI spec confirms are gone.
+                  Only edits docguard:generated docs unless --force.
+  --plan          AI-powered Generate (generate command): scan any project
+                  (JS/Python/Rust/Go/Java/…), emit the agent task manifest +
+                  code-truth skeleton. Add --write to scaffold, --format json
+                  for the machine-readable manifest.
   --doc <name>    Generate AI prompt for specific doc (architecture, security, etc.)
   --profile <p>   Compliance profile: starter, standard, enterprise (init command)
   --tax           Show estimated documentation maintenance cost (with score)
@@ -346,6 +358,13 @@ async function main() {
       flags.failOnWarning = true;
     } else if (args[i] === '--auto') {
       flags.auto = true;
+    } else if (args[i] === '--write') {
+      flags.write = true;
+    } else if (args[i] === '--plan') {
+      flags.plan = true;
+    } else if (args[i] === '--since' && args[i + 1]) {
+      flags.since = args[i + 1];
+      i++;
     } else if (args[i] === '--doc' && args[i + 1]) {
       flags.doc = args[i + 1];
       i++;
@@ -443,6 +462,9 @@ async function main() {
     case 'watch':
       runWatch(projectDir, config, flags);
       break;
+    case 'sync':
+      runSync(projectDir, config, flags);
+      break;
     case 'publish':
     case 'pub':
       runPublish(projectDir, config, flags);

package/cli/scanners/cdk.mjs

@@ -0,0 +1,10 @@
+/**
+ * CDK Detector — Re-export shim.
+ *
+ * The CDK-specific detector has been generalized into a multi-tool IaC
+ * detector at cli/scanners/iac.mjs covering CDK, Terraform, Pulumi, SAM,
+ * and Serverless Framework. This module re-exports the CDK-only API for
+ * backward compatibility. New code should import from iac.mjs directly.
+ */
+
+export { detectCDK, hasInfrastructureHeading } from './iac.mjs';