docguard-cli 0.9.11 → 0.11.0

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`);
@@ -311,6 +402,8 @@ function detectStack(dir) {
 
 // ── Project Scanner ────────────────────────────────────────────────────────
 
+
+
 function scanProject(dir) {
   const scan = {
     routes: [],
@@ -324,6 +417,30 @@ function scanProject(dir) {
     totalLines: 0,
   };
 
+  scanRoutes(dir, scan);
+  scanModels(dir, scan);
+  scanServices(dir, scan);
+  scanTests(dir, scan);
+  scanComponents(dir, scan);
+  scanMiddlewares(dir, scan);
+  scanEnvVars(dir, scan);
+
+  // Count files and lines
+  countFilesAndLines(dir, scan);
+
+  // ── Filter test files out of source lists ──
+  // Test files (*.test.*, *.spec.*, __tests__/) should NOT appear as source files
+  const isTestFile = (f) => f.includes('__tests__') || f.includes('__test__') || /\.(test|spec)\.[^.]+$/.test(f);
+  scan.routes = scan.routes.filter(f => !isTestFile(f));
+  scan.models = scan.models.filter(f => !isTestFile(f));
+  scan.services = scan.services.filter(f => !isTestFile(f));
+  scan.components = scan.components.filter(f => !isTestFile(f));
+  scan.middlewares = scan.middlewares.filter(f => !isTestFile(f));
+
+  return scan;
+}
+
+function scanRoutes(dir, scan) {
   // Find routes
   ['src/app/api', 'src/routes', 'routes', 'api', 'src/api'].forEach(routeDir => {
     const fullDir = resolve(dir, routeDir);
@@ -334,7 +451,10 @@ function scanProject(dir) {
       }
     }
   });
+}
 
+
+function scanModels(dir, scan) {
   // Find models/entities
   ['src/models', 'models', 'src/entities', 'entities', 'src/schema', 'schema', 'prisma'].forEach(modelDir => {
     const fullDir = resolve(dir, modelDir);
@@ -345,7 +465,10 @@ function scanProject(dir) {
       }
     }
   });
+}
 
+
+function scanServices(dir, scan) {
   // Find services
   ['src/services', 'services', 'src/lib', 'lib'].forEach(svcDir => {
     const fullDir = resolve(dir, svcDir);
@@ -356,7 +479,10 @@ function scanProject(dir) {
       }
     }
   });
+}
 
+
+function scanTests(dir, scan) {
   // Find tests — top-level test dirs
   ['tests', 'test', '__tests__', 'spec', 'e2e'].forEach(testDir => {
     const fullDir = resolve(dir, testDir);
@@ -416,7 +542,10 @@ function scanProject(dir) {
       break; // Use first found config
     }
   }
+}
 
+
+function scanComponents(dir, scan) {
   // Find components
   ['src/components', 'components', 'src/ui'].forEach(compDir => {
     const fullDir = resolve(dir, compDir);
@@ -427,7 +556,10 @@ function scanProject(dir) {
       }
     }
   });
+}
 
+
+function scanMiddlewares(dir, scan) {
   // Find middleware
   ['src/middleware', 'middleware', 'src/middlewares'].forEach(mwDir => {
     const fullDir = resolve(dir, mwDir);
@@ -438,7 +570,10 @@ function scanProject(dir) {
       }
     }
   });
+}
+
 
+function scanEnvVars(dir, scan) {
   // Parse .env.example for env vars
   const envExample = resolve(dir, '.env.example');
   if (existsSync(envExample)) {
@@ -451,20 +586,6 @@ function scanProject(dir) {
       }
     }
   }
-
-  // Count files and lines
-  countFilesAndLines(dir, scan);
-
-  // ── Filter test files out of source lists ──
-  // Test files (*.test.*, *.spec.*, __tests__/) should NOT appear as source files
-  const isTestFile = (f) => f.includes('__tests__') || f.includes('__test__') || /\.(test|spec)\.[^.]+$/.test(f);
-  scan.routes = scan.routes.filter(f => !isTestFile(f));
-  scan.models = scan.models.filter(f => !isTestFile(f));
-  scan.services = scan.services.filter(f => !isTestFile(f));
-  scan.components = scan.components.filter(f => !isTestFile(f));
-  scan.middlewares = scan.middlewares.filter(f => !isTestFile(f));
-
-  return scan;
 }
 
 function countFilesAndLines(dir, scan) {
@@ -535,7 +656,7 @@ function generateArchitecture(dir, config, stack, scan, flags, docTools) {
 ## 1. Introduction & Goals
 <!-- arc42: §1 — Introduction and Goals -->
 
-<!-- TODO: Describe what this system does, who it's for, and key quality goals -->
+<!-- TBD: Describe what this system does, who it's for, and key quality goals -->
 ${config.projectName} is a ${stack.framework || stack.language || 'software'} application.
 
 ### Quality Goals
@@ -611,8 +732,8 @@ See \\\`docs-canonical/DEPLOYMENT.md\\\` for details.
 | Environment | Infrastructure | URL |
 |-------------|---------------|-----|
 | Development | localhost | http://localhost:3000 |
-| Staging | ${stack.hosting || 'TBD'} | <!-- TODO --> |
-| Production | ${stack.hosting || 'TBD'} | <!-- TODO --> |
+| Staging | ${stack.hosting || 'TBD'} | <!-- TBD --> |
+| Production | ${stack.hosting || 'TBD'} | <!-- TBD --> |
 
 ## 8. Crosscutting Concepts
 <!-- arc42: §8 — Crosscutting Concepts -->
@@ -715,7 +836,7 @@ ${r.description ? `- **Description:** ${r.description}` : ''}
 
 | Parameter | In | Type | Required | Description |
 |-----------|-----|------|:--------:|-------------|
-| <!-- TODO --> | | | | |
+| <!-- TBD --> | | | | |
 
 | Status | Response |
 |--------|----------|
@@ -742,7 +863,7 @@ ${routeDetails}`;
 |----------|-------|
 | **Status** | ![Status](https://img.shields.io/badge/status-draft-yellow) |
 | **Base URL** | \`http://localhost:3000\` |
-| **Auth** | <!-- TODO: Describe auth mechanism --> |
+| **Auth** | <!-- TBD: Describe auth mechanism --> |
 | **Total Endpoints** | ${deepRoutes.length} |
 | **Source** | ${deepRoutes[0]?.source || 'code scan'} |
 
@@ -826,7 +947,7 @@ function generateDataModel(dir, config, stack, scan, flags, deepSchemas) {
 
 | Field | Type | Required | Default | Constraints | Description |
 |-------|------|----------|---------|-------------|-------------|
-| <!-- TODO: Fill in fields --> | | | | | |
+| <!-- TBD: Fill in fields --> | | | | | |
 `;
       }
       const fieldRows = e.fields.map(f =>
@@ -913,7 +1034,7 @@ ${erDiagram}
 
 | Table | Index Name | Fields | Type | Purpose |
 |-------|-----------|--------|------|---------|
-| <!-- TODO: Document indexes --> | | | | |
+| <!-- TBD: Document indexes --> | | | | |
 
 ---
 
@@ -1046,9 +1167,9 @@ function generateTestSpec(dir, config, stack, scan, flags) {
 
 | Metric | Target | Current |
 |--------|:------:|:-------:|
-| Line Coverage | 80% | <!-- TODO --> |
-| Branch Coverage | 70% | <!-- TODO --> |
-| Function Coverage | 80% | <!-- TODO --> |
+| Line Coverage | 80% | <!-- TBD --> |
+| Branch Coverage | 70% | <!-- TBD --> |
+| Function Coverage | 80% | <!-- TBD --> |
 
 ## Service-to-Test Map
 
@@ -1103,7 +1224,7 @@ function generateSecurity(dir, config, stack, scan, flags) {
 
 | Method | Provider | Token Type | Expiry |
 |--------|---------|-----------|--------|
-| ${stack.auth || '<!-- TODO -->'} | | | |
+| ${stack.auth || '<!-- TBD -->'} | | | |
 
 ## Authorization
 
@@ -1117,8 +1238,8 @@ function generateSecurity(dir, config, stack, scan, flags) {
 | Secret | Storage | Rotation | Access |
 |--------|---------|----------|--------|
 ${scan.envVars.filter(v => isSecretVar(v.name)).map(v =>
-  `| \`${v.name}\` | Environment Variable | <!-- TODO --> | Application |`
-).join('\n') || '| <!-- TODO --> | | | |'}
+  `| \`${v.name}\` | Environment Variable | <!-- TBD --> | Application |`
+).join('\n') || '| <!-- TBD --> | | | |'}
 
 ## Security Rules
 

package/cli/commands/guard.mjs

@@ -20,6 +20,7 @@ import { validateArchitecture } from '../validators/architecture.mjs';
 import { validateFreshness } from '../validators/freshness.mjs';
 import { validateTraceability } from '../validators/traceability.mjs';
 import { validateDocsDiff } from '../validators/docs-diff.mjs';
+import { validateApiSurface } from '../validators/api-surface.mjs';
 import { validateMetadataSync } from '../validators/metadata-sync.mjs';
 import { validateMetricsConsistency } from '../validators/metrics-consistency.mjs';
 import { validateDocsCoverage } from '../validators/docs-coverage.mjs';
@@ -32,6 +33,38 @@ import { validateSpecKitIntegration } from '../scanners/speckit.mjs';
  * Internal guard — returns structured data, no console output, no process.exit.
  * Used by diagnose, ci, and guard --format json.
  */
+/**
+ * Classify a validator result into a status + quality badge.
+ *
+ * Critically, a check that found NOTHING to validate (no errors, no warnings,
+ * total === 0) — or that explicitly reports `applicable === false` — is status
+ * 'na' (not applicable), NOT 'pass'. This prevents a validator from rendering a
+ * confident green ✅ when it actually checked nothing (the root cause of the
+ * "clean bill of health on out-of-sync docs" incident).
+ */
+export function classifyResult(result) {
+  const hasErrors = result.errors.length > 0;
+  const hasWarnings = result.warnings.length > 0;
+
+  if (!hasErrors && !hasWarnings && (result.applicable === false || result.total === 0)) {
+    return { status: 'na', quality: null };
+  }
+
+  const status = hasErrors ? 'fail' : hasWarnings ? 'warn' : 'pass';
+
+  // Quality label: HIGH/MEDIUM/LOW (inspired by CJE quality stratification, Lopez et al. TRACE 2026)
+  let quality;
+  if (hasErrors) {
+    quality = 'LOW';
+  } else if (hasWarnings) {
+    quality = 'MEDIUM';
+  } else {
+    const ratio = result.total > 0 ? result.passed / result.total : 1;
+    quality = ratio >= 0.9 ? 'HIGH' : 'MEDIUM';
+  }
+  return { status, quality };
+}
+
 export function runGuardInternal(projectDir, config) {
   const validators = config.validators || {};
   const results = [];
@@ -40,7 +73,7 @@ export function runGuardInternal(projectDir, config) {
     { key: 'structure', name: 'Structure', fn: () => validateStructure(projectDir, config) },
     { key: 'structure', name: 'Doc Sections', fn: () => validateDocSections(projectDir, config) },
     { key: 'docsSync', name: 'Docs-Sync', fn: () => validateDocsSync(projectDir, config) },
-    { key: 'drift', name: 'Drift', fn: () => validateDrift(projectDir, config) },
+    { key: 'drift', name: 'Drift-Comments', fn: () => validateDrift(projectDir, config) },
     { key: 'changelog', name: 'Changelog', fn: () => validateChangelog(projectDir, config) },
     { key: 'testSpec', name: 'Test-Spec', fn: () => validateTestSpec(projectDir, config) },
     { key: 'environment', name: 'Environment', fn: () => validateEnvironment(projectDir, config) },
@@ -60,6 +93,7 @@ export function runGuardInternal(projectDir, config) {
     }},
     { key: 'traceability', name: 'Traceability', fn: () => validateTraceability(projectDir, config) },
     { key: 'docsDiff', name: 'Docs-Diff', fn: () => validateDocsDiff(projectDir, config) },
+    { key: 'apiSurface', name: 'API-Surface', fn: () => validateApiSurface(projectDir, config) },
     { key: 'metadataSync', name: 'Metadata-Sync', fn: () => validateMetadataSync(projectDir, config) },
     { key: 'docsCoverage', name: 'Docs-Coverage', fn: () => validateDocsCoverage(projectDir, config) },
     { key: 'docQuality', name: 'Doc-Quality', fn: () => validateDocQuality(projectDir, config) },
@@ -77,23 +111,7 @@ export function runGuardInternal(projectDir, config) {
 
     try {
       const result = fn();
-      const hasErrors = result.errors.length > 0;
-      const hasWarnings = result.warnings.length > 0;
-      const status = hasErrors ? 'fail' : hasWarnings ? 'warn' : 'pass';
-
-      // Quality label: HIGH/MEDIUM/LOW (inspired by CJE quality stratification, Lopez et al. TRACE 2026)
-      let quality;
-      if (hasErrors) {
-        quality = 'LOW';
-      } else if (hasWarnings) {
-        quality = 'MEDIUM';
-      } else {
-        // Pass — check coverage ratio for HIGH vs MEDIUM
-        const ratio = result.total > 0 ? result.passed / result.total : 1;
-        quality = ratio >= 0.9 ? 'HIGH' : 'MEDIUM';
-      }
-
-      results.push({ ...result, name, key, status, quality });
+      results.push({ ...result, name, key, ...classifyResult(result) });
     } catch (err) {
       results.push({ name, key, status: 'fail', quality: 'LOW', errors: [err.message], warnings: [], passed: 0, total: 1 });
     }
@@ -103,12 +121,7 @@ export function runGuardInternal(projectDir, config) {
   if (validators.metricsConsistency !== false) {
     try {
       const result = validateMetricsConsistency(projectDir, config, results);
-      const hasErrors = result.errors.length > 0;
-      const hasWarnings = result.warnings.length > 0;
-      const status = hasErrors ? 'fail' : hasWarnings ? 'warn' : 'pass';
-      const ratio = result.total > 0 ? result.passed / result.total : 1;
-      const quality = hasErrors ? 'LOW' : hasWarnings ? 'MEDIUM' : ratio >= 0.9 ? 'HIGH' : 'MEDIUM';
-      results.push({ ...result, name: 'Metrics-Consistency', key: 'metricsConsistency', status, quality });
+      results.push({ ...result, name: 'Metrics-Consistency', key: 'metricsConsistency', ...classifyResult(result) });
     } catch (err) {
       results.push({ name: 'Metrics-Consistency', key: 'metricsConsistency', status: 'fail', quality: 'LOW', errors: [err.message], warnings: [], passed: 0, total: 1 });
     }
@@ -161,6 +174,14 @@ export function runGuard(projectDir, config, flags) {
       continue;
     }
 
+    // Not applicable — nothing to validate. Render neutrally (NOT a green pass)
+    // so the reader can tell "checked and clean" apart from "nothing checked".
+    if (v.status === 'na') {
+      const reason = v.note ? ` ${c.dim}(${v.note})${c.reset}` : ` ${c.dim}(nothing to validate)${c.reset}`;
+      console.log(`  ${c.dim}➖ ${v.name}${c.reset} ${c.dim}[N/A]${c.reset}${reason}`);
+      continue;
+    }
+
     // Quality label badge
     const qColor = v.quality === 'HIGH' ? c.green : v.quality === 'MEDIUM' ? c.yellow : c.red;
     const qBadge = `${qColor}[${v.quality}]${c.reset}`;

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