docguard-cli 0.7.2 → 0.8.0

package/cli/commands/agents.mjs

@@ -5,7 +5,7 @@
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { resolve, dirname } from 'node:path';
-import { c } from '../docguard.mjs';
+import { c } from '../shared.mjs';
 
 const AGENT_TARGETS = {
   cursor: {

package/cli/commands/badge.mjs

@@ -3,7 +3,7 @@
  * Outputs badge markdown or JSON for README, CI, and dashboards.
  */
 
-import { c } from '../docguard.mjs';
+import { c } from '../shared.mjs';
 import { runScoreInternal } from './score.mjs';
 
 export function runBadge(projectDir, config, flags) {

package/cli/commands/ci.mjs

@@ -8,7 +8,7 @@
  *   2 = Guard warnings only
  */
 
-import { c } from '../docguard.mjs';
+import { c } from '../shared.mjs';
 import { runGuardInternal } from './guard.mjs';
 import { runScoreInternal } from './score.mjs';
 

package/cli/commands/diagnose.mjs

@@ -13,7 +13,7 @@
  *   --format prompt  Full AI-ready prompt (all issues combined)
  */
 
-import { c } from '../docguard.mjs';
+import { c } from '../shared.mjs';
 import { runGuardInternal } from './guard.mjs';
 import { runScoreInternal } from './score.mjs';
 import { existsSync, readFileSync, mkdirSync } from 'node:fs';

package/cli/commands/diff.mjs

@@ -5,7 +5,7 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, extname, basename } from 'node:path';
-import { c } from '../docguard.mjs';
+import { c } from '../shared.mjs';
 
 const IGNORE_DIRS = new Set([
   'node_modules', '.git', '.next', 'dist', 'build',
@@ -99,10 +99,13 @@ function diffRoutes(dir) {
 
   // Extract route-like patterns from ARCHITECTURE.md
   const docRoutes = new Set();
-  const routeRegex = /(?:\/api\/\S+|GET|POST|PUT|DELETE|PATCH)\s+(\S+)/gi;
+  const routeRegex = /(?:\/api\/\S+|(?:GET|POST|PUT|DELETE|PATCH)\s+(\/\S+))/gi;
   let match;
   while ((match = routeRegex.exec(content)) !== null) {
-    docRoutes.add(match[1] || match[0]);
+    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);
   }
 
   // Also check for paths in tables
@@ -183,6 +186,14 @@ function diffEntities(dir) {
     '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',
   ]);
   while ((match = tableRegex.exec(content)) !== null) {
     const name = match[1];

package/cli/commands/fix.mjs

@@ -16,7 +16,7 @@
 import { existsSync, readFileSync, mkdirSync } from 'node:fs';
 import { resolve, basename } from 'node:path';
 import { execSync } from 'node:child_process';
-import { c } from '../docguard.mjs';
+import { c } from '../shared.mjs';
 
 // ── Document Quality Definitions ───────────────────────────────────────────
 // What each doc SHOULD contain, and what to look for in the codebase

package/cli/commands/generate.mjs

@@ -7,7 +7,7 @@
 
 import { existsSync, readFileSync, writeFileSync, readdirSync, statSync, mkdirSync } from 'node:fs';
 import { resolve, join, extname, basename, relative, dirname } from 'node:path';
-import { c } from '../docguard.mjs';
+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';

package/cli/commands/guard.mjs

@@ -7,7 +7,7 @@
  *   runGuardInternal() → returns data, no side effects (for diagnose, ci)
  */
 
-import { c } from '../docguard.mjs';
+import { c } from '../shared.mjs';
 import { validateStructure, validateDocSections } from '../validators/structure.mjs';
 import { validateDrift } from '../validators/drift.mjs';
 import { validateChangelog } from '../validators/changelog.mjs';
@@ -18,6 +18,7 @@ import { validateDocsSync } from '../validators/docs-sync.mjs';
 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';
 
 /**
  * Internal guard — returns structured data, no console output, no process.exit.
@@ -50,6 +51,7 @@ export function runGuardInternal(projectDir, config) {
       return { errors, warnings, passed, total: passed + warnings.length + errors.length };
     }},
     { key: 'traceability', name: 'Traceability', fn: () => validateTraceability(projectDir, config) },
+    { key: 'docsDiff', name: 'Docs-Diff', fn: () => validateDocsDiff(projectDir, config) },
   ];
 
   for (const { key, name, fn } of validatorMap) {
@@ -169,6 +171,12 @@ export function runGuard(projectDir, config, flags) {
     console.log(`  ${c.dim}Run ${c.cyan}docguard diagnose${c.dim} to get AI fix prompts.${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';
+  const badgeUrl = `https://img.shields.io/badge/CDD_Guard-${data.passed}%2F${data.total}_passed-${bColor}`;
+  console.log(`\n  ${c.dim}📎 Badge: ![CDD Guard](${badgeUrl})${c.reset}`);
+
   console.log('');
 
   if (data.errors > 0) process.exit(1);

package/cli/commands/hooks.mjs

@@ -5,7 +5,7 @@
 
 import { existsSync, writeFileSync, mkdirSync, chmodSync, readFileSync, unlinkSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { c } from '../docguard.mjs';
+import { c } from '../shared.mjs';
 
 const HOOKS = {
   'pre-commit': {

package/cli/commands/init.mjs

@@ -1,11 +1,13 @@
 /**
  * Init Command — Initialize CDD documentation from templates
+ * Interactive setup: asks which docs the user needs + suggests hooks.
  */
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from 'node:fs';
-import { resolve, dirname, join } from 'node:path';
+import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { c, PROFILES } from '../docguard.mjs';
+import { createInterface } from 'node:readline';
+import { c, PROFILES } from '../shared.mjs';
 
 function detectProjectType(dir) {
   const pkgPath = resolve(dir, 'package.json');
@@ -29,7 +31,21 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const TEMPLATES_DIR = resolve(__dirname, '../../templates');
 
-export function runInit(projectDir, config, flags) {
+// ── Readline helper ──────────────────────────────────────────────────────
+
+function askQuestion(prompt) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(res => {
+    rl.question(prompt, answer => {
+      rl.close();
+      res(answer);
+    });
+  });
+}
+
+// ── Init Command ─────────────────────────────────────────────────────────
+
+export async function runInit(projectDir, config, flags) {
   const profileName = flags.profile || 'standard';
   const profile = PROFILES[profileName];
 
@@ -43,29 +59,63 @@ export function runInit(projectDir, config, flags) {
   console.log(`${c.dim}   Directory: ${projectDir}${c.reset}`);
   console.log(`${c.dim}   Profile:   ${profileName} — ${profile.description}${c.reset}\n`);
 
+  // Detect project type
+  const detectedType = detectProjectType(projectDir);
+  console.log(`  ${c.dim}Auto-detected project type: ${c.cyan}${detectedType}${c.reset}\n`);
+
+  // ── Doc catalog ────────────────────────────────────────────────────────
+  const allDocs = [
+    { key: 'ARCHITECTURE', file: 'docs-canonical/ARCHITECTURE.md', template: 'ARCHITECTURE.md.template', desc: 'System architecture, tech stack, layer boundaries', defaultYes: true },
+    { key: 'DATA-MODEL', file: 'docs-canonical/DATA-MODEL.md', template: 'DATA-MODEL.md.template', desc: 'Database schemas, entities, relationships', defaultYes: ['webapp', 'api'].includes(detectedType) },
+    { key: 'SECURITY', file: 'docs-canonical/SECURITY.md', template: 'SECURITY.md.template', desc: 'Auth, secrets, security controls', defaultYes: ['webapp', 'api'].includes(detectedType) },
+    { key: 'TEST-SPEC', file: 'docs-canonical/TEST-SPEC.md', template: 'TEST-SPEC.md.template', desc: 'Test strategy, coverage requirements', defaultYes: true },
+    { key: 'ENVIRONMENT', file: 'docs-canonical/ENVIRONMENT.md', template: 'ENVIRONMENT.md.template', desc: 'Environment variables, deployment config', defaultYes: ['webapp', 'api'].includes(detectedType) },
+  ];
+
+  let selectedDocs;
+
+  if (flags.skipPrompts || flags.force) {
+    // Non-interactive — use profile defaults
+    const profileCanonical = profile.requiredFiles?.canonical || allDocs.map(d => d.file);
+    selectedDocs = allDocs.filter(d => profileCanonical.includes(d.file));
+    console.log(`  ${c.dim}Non-interactive mode — using ${profileName} profile defaults${c.reset}\n`);
+  } else {
+    // Interactive — ask about each doc
+    console.log(`  ${c.bold}Which canonical docs does your project need?${c.reset}`);
+    console.log(`  ${c.dim}(press Enter for default, type y or n)${c.reset}\n`);
+
+    selectedDocs = [];
+    for (const doc of allDocs) {
+      const defaultLabel = doc.defaultYes ? 'Y/n' : 'y/N';
+      const answer = await askQuestion(`    ${doc.key} — ${doc.desc} [${defaultLabel}]: `);
+      const trimmed = answer.trim().toLowerCase();
+
+      const include = doc.defaultYes
+        ? (trimmed === '' || trimmed === 'y' || trimmed === 'yes')
+        : (trimmed === 'y' || trimmed === 'yes');
+
+      if (include) {
+        selectedDocs.push(doc);
+      }
+    }
+    console.log('');
+  }
+
+  // ── Create selected doc files ──────────────────────────────────────────
   const created = [];
   const skipped = [];
 
-  // Map template files to their destinations
-  const allMappings = [
-    { template: 'ARCHITECTURE.md.template', dest: 'docs-canonical/ARCHITECTURE.md' },
-    { template: 'DATA-MODEL.md.template', dest: 'docs-canonical/DATA-MODEL.md' },
-    { template: 'SECURITY.md.template', dest: 'docs-canonical/SECURITY.md' },
-    { template: 'TEST-SPEC.md.template', dest: 'docs-canonical/TEST-SPEC.md' },
-    { template: 'ENVIRONMENT.md.template', dest: 'docs-canonical/ENVIRONMENT.md' },
+  // Always create tracking files
+  const alwaysCreate = [
     { template: 'AGENTS.md.template', dest: 'AGENTS.md' },
     { template: 'CHANGELOG.md.template', dest: 'CHANGELOG.md' },
     { template: 'DRIFT-LOG.md.template', dest: 'DRIFT-LOG.md' },
   ];
 
-  // Filter based on profile — starter only gets required files
-  const profileRequiredFiles = profile.requiredFiles
-    ? new Set([...profile.requiredFiles.canonical, profile.requiredFiles.changelog, profile.requiredFiles.driftLog, ...profile.requiredFiles.agentFile])
-    : null;
-
-  const fileMappings = profileRequiredFiles
-    ? allMappings.filter(m => profileRequiredFiles.has(m.dest))
-    : allMappings;
+  const fileMappings = [
+    ...selectedDocs.map(d => ({ template: d.template, dest: d.file })),
+    ...alwaysCreate,
+  ];
 
   for (const mapping of fileMappings) {
     const destPath = resolve(projectDir, mapping.dest);
@@ -77,35 +127,26 @@ export function runInit(projectDir, config, flags) {
       continue;
     }
 
-    // Ensure directory exists
     const destDir = dirname(destPath);
     if (!existsSync(destDir)) {
       mkdirSync(destDir, { recursive: true });
     }
 
-    // Read template and write
     if (existsSync(templatePath)) {
       const content = readFileSync(templatePath, 'utf-8');
-      // Replace template date placeholder with today's date
       const today = new Date().toISOString().split('T')[0];
       const processed = content.replace(/YYYY-MM-DD/g, today);
       writeFileSync(destPath, processed, 'utf-8');
       created.push(mapping.dest);
       console.log(`  ${c.green}✅${c.reset} Created: ${c.cyan}${mapping.dest}${c.reset}`);
     } else {
-      console.log(
-        `  ${c.red}❌${c.reset} Template not found: ${mapping.template}`
-      );
+      console.log(`  ${c.red}❌${c.reset} Template not found: ${mapping.template}`);
     }
   }
 
-  // Create .docguard.json if it doesn't exist — auto-detect project type
+  // ── Create .docguard.json ──────────────────────────────────────────────
   const configPath = resolve(projectDir, '.docguard.json');
   if (!existsSync(configPath)) {
-    // Detect project type from package.json
-    const detectedType = detectProjectType(projectDir);
-
-    // Get appropriate defaults for this project type
     const typeDefaults = {
       cli:     { needsEnvVars: false, needsEnvExample: false, needsE2E: false, needsDatabase: false },
       library: { needsEnvVars: false, needsEnvExample: false, needsE2E: false, needsDatabase: false },
@@ -122,6 +163,9 @@ export function runInit(projectDir, config, flags) {
       profile: profileName,
       projectType: detectedType,
       projectTypeConfig: ptc,
+      requiredFiles: {
+        canonical: selectedDocs.map(d => d.file),
+      },
       validators: profile.validators || {
         structure: true,
         docsSync: true,
@@ -137,18 +181,17 @@ export function runInit(projectDir, config, flags) {
 
     writeFileSync(configPath, JSON.stringify(defaultConfig, null, 2) + '\n', 'utf-8');
     created.push('.docguard.json');
-    console.log(`  ${c.green}✅${c.reset} Created: ${c.cyan}.docguard.json${c.reset} ${c.dim}(auto-detected: ${detectedType})${c.reset}`);
+    console.log(`  ${c.green}✅${c.reset} Created: ${c.cyan}.docguard.json${c.reset} ${c.dim}(${selectedDocs.length} docs selected, type: ${detectedType})${c.reset}`);
   } else {
     skipped.push('.docguard.json');
     console.log(`  ${c.yellow}⏭️${c.reset}  .docguard.json ${c.dim}(already exists)${c.reset}`);
   }
 
-  // Install slash commands for AI agents — detect which agents are in use
+  // ── Slash commands for AI agents ───────────────────────────────────────
   const commandsSourceDir = resolve(TEMPLATES_DIR, 'commands');
   if (existsSync(commandsSourceDir)) {
     const commandFiles = readdirSync(commandsSourceDir).filter(f => f.endsWith('.md'));
 
-    // Detect which AI agent directories exist in the project
     const agentDirs = [
       { name: 'GitHub Copilot', path: '.github/commands' },
       { name: 'Cursor', path: '.cursor/rules' },
@@ -157,12 +200,10 @@ export function runInit(projectDir, config, flags) {
       { name: 'Antigravity', path: '.agents/workflows' },
     ];
 
-    // Find which agent dirs already exist in the project
     const detected = agentDirs.filter(a =>
-      existsSync(resolve(projectDir, a.path.split('/')[0])) // check parent dir exists
+      existsSync(resolve(projectDir, a.path.split('/')[0]))
     );
 
-    // If none detected, default to .github/commands (most universal)
     const targets = detected.length > 0
       ? detected
       : [{ name: 'GitHub (default)', path: '.github/commands' }];
@@ -203,47 +244,44 @@ export function runInit(projectDir, config, flags) {
     }
   }
 
-  // Summary
+  // ── Summary ────────────────────────────────────────────────────────────
   console.log(`\n${c.bold}  ─────────────────────────────────────${c.reset}`);
   console.log(`  ${c.green}Created:${c.reset} ${created.length} files`);
   if (skipped.length > 0) {
     console.log(`  ${c.yellow}Skipped:${c.reset} ${skipped.length} files (already exist)`);
   }
 
-  if (flags.skipPrompts) {
-    // Simple instructions, no AI prompts
-    console.log(`\n  ${c.bold}Next steps:${c.reset}`);
-    console.log(`  ${c.dim}Run${c.reset} ${c.cyan}docguard diagnose${c.reset} ${c.dim}to get AI prompts for filling docs.${c.reset}`);
-    console.log(`  ${c.dim}Then verify:${c.reset} ${c.cyan}docguard guard${c.reset}\n`);
-  } else {
-    // Auto-populate: output AI research prompts for each created canonical doc
-    const createdDocs = created.filter(f => f.startsWith('docs-canonical/'));
-
-    if (createdDocs.length > 0) {
-      console.log(`\n  ${c.bold}🤖 AI Auto-Populate${c.reset}`);
-      console.log(`  ${c.dim}The files above are skeleton templates. Your AI agent should fill them.${c.reset}`);
-      console.log(`  ${c.dim}Run this single command to get a full remediation plan:${c.reset}\n`);
-      console.log(`  ${c.cyan}${c.bold}docguard diagnose${c.reset}\n`);
-      console.log(`  ${c.dim}Or generate prompts for individual docs:${c.reset}`);
-
-      const docNameMap = {
-        'docs-canonical/ARCHITECTURE.md': 'architecture',
-        'docs-canonical/DATA-MODEL.md': 'data-model',
-        'docs-canonical/SECURITY.md': 'security',
-        'docs-canonical/TEST-SPEC.md': 'test-spec',
-        'docs-canonical/ENVIRONMENT.md': 'environment',
-      };
-
-      for (const doc of createdDocs) {
-        const target = docNameMap[doc];
-        if (target) {
-          console.log(`  ${c.cyan}docguard fix --doc ${target}${c.reset}`);
-        }
+  // ── Hooks suggestion ──────────────────────────────────────────────────
+  console.log(`\n  ${c.bold}💡 Automation:${c.reset}`);
+  console.log(`  ${c.dim}Auto-guard on commit:${c.reset}  ${c.cyan}docguard hooks --type pre-commit${c.reset}`);
+  console.log(`  ${c.dim}Auto-guard on push:${c.reset}   ${c.cyan}docguard hooks --type pre-push${c.reset}`);
+
+  // ── Next steps ─────────────────────────────────────────────────────────
+  const createdDocs = created.filter(f => f.startsWith('docs-canonical/'));
+
+  if (createdDocs.length > 0) {
+    console.log(`\n  ${c.bold}🤖 AI Auto-Populate${c.reset}`);
+    console.log(`  ${c.dim}The files above are skeleton templates. Your AI agent should fill them.${c.reset}`);
+    console.log(`  ${c.dim}Run this single command to get a full remediation plan:${c.reset}\n`);
+    console.log(`  ${c.cyan}${c.bold}docguard diagnose${c.reset}\n`);
+    console.log(`  ${c.dim}Or generate prompts for individual docs:${c.reset}`);
+
+    const docNameMap = {
+      'docs-canonical/ARCHITECTURE.md': 'architecture',
+      'docs-canonical/DATA-MODEL.md': 'data-model',
+      'docs-canonical/SECURITY.md': 'security',
+      'docs-canonical/TEST-SPEC.md': 'test-spec',
+      'docs-canonical/ENVIRONMENT.md': 'environment',
+    };
+
+    for (const doc of createdDocs) {
+      const target = docNameMap[doc];
+      if (target) {
+        console.log(`  ${c.cyan}docguard fix --doc ${target}${c.reset}`);
       }
-      console.log(`\n  ${c.dim}Then verify:${c.reset} ${c.cyan}docguard guard${c.reset}\n`);
-    } else {
-      console.log(`\n  ${c.dim}Run${c.reset} ${c.cyan}docguard diagnose${c.reset} ${c.dim}to check for issues.${c.reset}\n`);
     }
+    console.log(`\n  ${c.dim}Then verify:${c.reset} ${c.cyan}docguard guard${c.reset}\n`);
+  } else {
+    console.log(`\n  ${c.dim}Run${c.reset} ${c.cyan}docguard diagnose${c.reset} ${c.dim}to check for issues.${c.reset}\n`);
   }
 }
-

package/cli/commands/publish.mjs

@@ -8,7 +8,7 @@
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { resolve, basename } from 'node:path';
-import { c } from '../docguard.mjs';
+import { c } from '../shared.mjs';
 
 const SUPPORTED_PLATFORMS = ['mintlify'];
 

package/cli/commands/score.mjs

@@ -6,7 +6,7 @@
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, extname } from 'node:path';
 import { execSync } from 'node:child_process';
-import { c } from '../docguard.mjs';
+import { c } from '../shared.mjs';
 
 const WEIGHTS = {
   structure: 25,     // Required files exist
@@ -23,7 +23,7 @@ export function runScore(projectDir, config, flags) {
   console.log(`${c.bold}📊 DocGuard Score — ${config.projectName}${c.reset}`);
   console.log(`${c.dim}   Directory: ${projectDir}${c.reset}\n`);
 
-  const { scores, totalScore, grade } = calcAllScores(projectDir, config);
+  const { scores, totalScore, grade, details } = calcAllScores(projectDir, config);
 
   // ── Display Results ──
   if (flags.format === 'json') {
@@ -80,7 +80,7 @@ export function runScore(projectDir, config, flags) {
   if (weakest.length > 0) {
     console.log(`  ${c.bold}Top improvements:${c.reset}`);
     for (const [cat, score] of weakest) {
-      const suggestion = getSuggestion(cat, score);
+      const suggestion = getSuggestion(cat, score, details);
       console.log(`  ${c.yellow}→ ${cat}${c.reset}: ${suggestion}`);
     }
     console.log('');
@@ -130,6 +130,11 @@ export function runScore(projectDir, config, flags) {
     console.log(`  ${c.dim}Quality labels: HIGH (≥90%), MEDIUM (50-89%), LOW (<50%)${c.reset}`);
     console.log(`  ${c.dim}Methodology: CJE multi-signal composite (Lopez et al., TRACE, IEEE TMLCN 2026)${c.reset}\n`);
   }
+
+  // Badge snippet
+  const bColor = totalScore >= 90 ? 'brightgreen' : totalScore >= 80 ? 'green' : totalScore >= 70 ? 'yellowgreen' : totalScore >= 60 ? 'yellow' : totalScore >= 50 ? 'orange' : 'red';
+  const badgeUrl = `https://img.shields.io/badge/CDD_Score-${totalScore}%2F100_(${grade})-${bColor}`;
+  console.log(`  ${c.dim}📎 Badge: ![CDD Score](${badgeUrl})${c.reset}\n`);
 }
 
 /**
@@ -143,8 +148,12 @@ export function runScoreInternal(projectDir, config) {
 
 function calcAllScores(projectDir, config) {
   const scores = {};
+  const details = {}; // Per-category failure details for actionable suggestions
+
   scores.structure = calcStructureScore(projectDir, config);
-  scores.docQuality = calcDocQualityScore(projectDir, config);
+  const dqResult = calcDocQualityScore(projectDir, config);
+  scores.docQuality = dqResult.score;
+  details.docQuality = dqResult.failures;
   scores.testing = calcTestingScore(projectDir, config);
   scores.security = calcSecurityScore(projectDir, config);
   scores.environment = calcEnvironmentScore(projectDir, config);
@@ -158,7 +167,7 @@ function calcAllScores(projectDir, config) {
   }
   totalScore = Math.round(totalScore);
 
-  return { scores, totalScore, grade: getGrade(totalScore) };
+  return { scores, totalScore, grade: getGrade(totalScore), details };
 }
 
 // ── Scoring Functions ──────────────────────────────────────────────────────
@@ -196,32 +205,42 @@ function calcDocQualityScore(dir, config) {
 
   let found = 0;
   let total = 0;
+  const failures = []; // Track specific failures for actionable suggestions
 
   for (const [file, sections] of Object.entries(checks)) {
     const fullPath = resolve(dir, file);
-    if (!existsSync(fullPath)) continue;
+    if (!existsSync(fullPath)) {
+      failures.push({ file, issue: 'file missing' });
+      continue;
+    }
 
     const content = readFileSync(fullPath, 'utf-8');
+    const docName = file.replace('docs-canonical/', '').replace('.md', '').toLowerCase();
 
     for (const section of sections) {
       total++;
-      if (content.includes(section)) found++;
+      if (content.includes(section)) {
+        found++;
+      } else {
+        failures.push({ file, issue: `missing section: ${section}`, fixCmd: `docguard fix --doc ${docName}` });
+      }
     }
 
-    // Bonus: check if doc has docguard metadata
-    total++;
-    if (content.includes('docguard:version')) found++;
-
-    // Bonus: check if doc has more than just template placeholders
+    // Check if doc has more than just template placeholders
     total++;
     const lines = content.split('\n').filter(l => l.trim() && !l.startsWith('#') && !l.startsWith('|') && !l.startsWith('>') && !l.startsWith('<!--'));
-    if (lines.length > 5) found++;
+    if (lines.length > 5) {
+      found++;
+    } else {
+      failures.push({ file, issue: `thin content (${lines.length} lines — need >5)`, fixCmd: `docguard fix --doc ${docName}` });
+    }
   }
 
-  return total === 0 ? 0 : Math.round((found / total) * 100);
+  const score = total === 0 ? 0 : Math.round((found / total) * 100);
+  return { score, failures };
 }
 
-function calcTestingScore(dir) {
+function calcTestingScore(dir, config) {
   let score = 0;
 
   // Check test directory exists
@@ -232,10 +251,28 @@ function calcTestingScore(dir) {
   // Check test spec exists
   if (existsSync(resolve(dir, 'docs-canonical/TEST-SPEC.md'))) score += 30;
 
-  // Check for test config files
+  // Check for test config files OR built-in test runner
   const testConfigs = ['jest.config.js', 'jest.config.ts', 'vitest.config.ts', 'vitest.config.js', 'pytest.ini', 'setup.cfg', '.mocharc.yml'];
   const hasTestConfig = testConfigs.some(f => existsSync(resolve(dir, f)));
-  if (hasTestConfig) score += 15;
+
+  if (hasTestConfig) {
+    score += 15;
+  } else {
+    // Check if using node:test (no config needed) — look in package.json scripts
+    const ptc = config.projectTypeConfig || {};
+    const pkgPath = resolve(dir, 'package.json');
+    if (ptc.testFramework === 'node:test') {
+      score += 15; // Config says node:test — no config file needed
+    } else if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+        const testScript = pkg.scripts?.test || '';
+        if (testScript.includes('node --test') || testScript.includes('node:test')) {
+          score += 15; // Using built-in test runner
+        }
+      } catch { /* skip */ }
+    }
+  }
 
   // Check for CI test step
   const ciFiles = ['.github/workflows/ci.yml', '.github/workflows/test.yml'];
@@ -245,8 +282,9 @@ function calcTestingScore(dir) {
   return Math.min(100, score);
 }
 
-function calcSecurityScore(dir) {
+function calcSecurityScore(dir, config) {
   let score = 0;
+  const ptc = config.projectTypeConfig || {};
 
   // SECURITY.md exists
   if (existsSync(resolve(dir, 'docs-canonical/SECURITY.md'))) score += 30;
@@ -262,17 +300,28 @@ function calcSecurityScore(dir) {
   // No .env file committed (check if .env exists but .gitignore covers it)
   if (!existsSync(resolve(dir, '.env')) || existsSync(gitignorePath)) score += 15;
 
-  // .env.example exists (safe template)
-  if (existsSync(resolve(dir, '.env.example'))) score += 15;
+  // .env.example exists (safe template) — only check if project needs env vars
+  if (ptc.needsEnvExample === false) {
+    score += 15; // Full marks — project doesn't need env vars
+  } else if (existsSync(resolve(dir, '.env.example'))) {
+    score += 15;
+  }
 
   return Math.min(100, score);
 }
 
-function calcEnvironmentScore(dir) {
+function calcEnvironmentScore(dir, config) {
   let score = 0;
+  const ptc = config.projectTypeConfig || {};
 
   if (existsSync(resolve(dir, 'docs-canonical/ENVIRONMENT.md'))) score += 40;
-  if (existsSync(resolve(dir, '.env.example'))) score += 30;
+
+  // .env.example — only check if project needs env vars
+  if (ptc.needsEnvExample === false) {
+    score += 30; // Full marks — project doesn't need env vars
+  } else if (existsSync(resolve(dir, '.env.example'))) {
+    score += 30;
+  }
 
   // Check for setup documentation
   const readmePath = resolve(dir, 'README.md');
@@ -352,16 +401,31 @@ function getGrade(score) {
   return 'F';
 }
 
-function getSuggestion(category, score) {
+function getSuggestion(category, score, details) {
+  // Dynamic, specific suggestions based on actual failures
+  if (category === 'docQuality' && details?.docQuality?.length > 0) {
+    const failures = details.docQuality;
+    // Group by doc
+    const byDoc = {};
+    for (const f of failures) {
+      const doc = f.file.replace('docs-canonical/', '');
+      if (!byDoc[doc]) byDoc[doc] = [];
+      byDoc[doc].push(f.issue);
+    }
+    const parts = Object.entries(byDoc).map(([doc, issues]) => `${doc}: ${issues.join(', ')}`);
+    const fixCmd = failures.find(f => f.fixCmd)?.fixCmd || 'docguard fix';
+    return `${parts.join(' | ')} → Run \`${fixCmd}\``;
+  }
+
   const suggestions = {
     structure: 'Run `docguard init` to create missing documentation',
-    docQuality: 'Fill in template sections — replace placeholders with real content',
+    docQuality: 'Run `docguard fix` to get AI prompts for each doc that needs content',
     testing: 'Add tests/ directory and configure TEST-SPEC.md',
-    security: 'Create SECURITY.md and add .env to .gitignore',
-    environment: 'Document env variables and create .env.example',
+    security: 'Create SECURITY.md and add .env to .gitignore → Run `docguard fix --doc security`',
+    environment: 'Document env variables and create .env.example → Run `docguard fix --doc environment`',
     drift: 'Create DRIFT-LOG.md and log any code deviations',
     changelog: 'Maintain CHANGELOG.md with [Unreleased] section',
-    architecture: 'Add layer boundaries and Mermaid diagrams to ARCHITECTURE.md',
+    architecture: 'Add layer boundaries and Mermaid diagrams → Run `docguard fix --doc architecture`',
   };
   return suggestions[category] || 'Review and improve this area';
 }

package/cli/commands/trace.mjs

@@ -8,7 +8,7 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, extname, basename, relative } from 'node:path';
-import { c } from '../docguard.mjs';
+import { c } from '../shared.mjs';
 
 const IGNORE_DIRS = new Set([
   'node_modules', '.git', '.next', 'dist', 'build', 'coverage',

package/cli/commands/watch.mjs

@@ -9,7 +9,7 @@
 
 import { watch as fsWatch, existsSync, readdirSync, statSync } from 'node:fs';
 import { resolve, relative, extname } from 'node:path';
-import { c } from '../docguard.mjs';
+import { c } from '../shared.mjs';
 import { runGuardInternal } from './guard.mjs';
 
 const DEBOUNCE_MS = 500;

package/cli/docguard.mjs

@@ -22,7 +22,7 @@ import { fileURLToPath } from 'node:url';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG = JSON.parse(readFileSync(resolve(__dirname, '..', 'package.json'), 'utf-8'));
 const VERSION = PKG.version;
-import { runAudit } from './commands/audit.mjs';
+// audit is now an alias for guard (old audit.mjs deleted — guard does everything it did + more)
 import { runInit } from './commands/init.mjs';
 import { runGuard } from './commands/guard.mjs';
 import { runScore } from './commands/score.mjs';
@@ -38,66 +38,9 @@ import { runDiagnose } from './commands/diagnose.mjs';
 import { runPublish } from './commands/publish.mjs';
 import { runTrace } from './commands/trace.mjs';
 
-// ── Colors (ANSI escape codes, zero deps) ──────────────────────────────────
-export const c = {
-  reset: '\x1b[0m',
-  bold: '\x1b[1m',
-  dim: '\x1b[2m',
-  red: '\x1b[31m',
-  green: '\x1b[32m',
-  yellow: '\x1b[33m',
-  blue: '\x1b[34m',
-  cyan: '\x1b[36m',
-  white: '\x1b[37m',
-  bgRed: '\x1b[41m',
-  bgGreen: '\x1b[42m',
-  bgYellow: '\x1b[43m',
-};
-// ── Compliance Profiles ───────────────────────────────────────────────────
-// Profiles layer between defaults and user config — they're preset bundles
-// that adjust what docs are required and which validators run.
-const PROFILES = {
-  starter: {
-    description: 'Minimal CDD — just architecture + changelog. For side projects and prototypes.',
-    requiredFiles: {
-      canonical: [
-        'docs-canonical/ARCHITECTURE.md',
-      ],
-      agentFile: ['AGENTS.md', 'CLAUDE.md'],
-      changelog: 'CHANGELOG.md',
-      driftLog: 'DRIFT-LOG.md',
-    },
-    validators: {
-      structure: true,
-      docsSync: true,
-      drift: false,
-      changelog: true,
-      architecture: false,
-      testSpec: false,
-      security: false,
-      environment: false,
-      freshness: false,
-    },
-  },
-  standard: {
-    description: 'Full CDD — all 5 canonical docs. For team projects.',
-    // Uses the defaults — no overrides needed
-  },
-  enterprise: {
-    description: 'Strict CDD — all docs, all validators, freshness enforced. For regulated/enterprise projects.',
-    validators: {
-      structure: true,
-      docsSync: true,
-      drift: true,
-      changelog: true,
-      architecture: true,
-      testSpec: true,
-      security: true,
-      environment: true,
-      freshness: true,
-    },
-  },
-};
+// ── Shared constants (imported to break circular dependencies) ──────────
+import { c, PROFILES } from './shared.mjs';
+export { c, PROFILES };
 
 // ── Config Loading ─────────────────────────────────────────────────────────
 export function loadConfig(projectDir) {
@@ -195,8 +138,7 @@ export function loadConfig(projectDir) {
   return defaults;
 }
 
-// Export profiles for use by other commands (init --profile)
-export { PROFILES };
+// PROFILES is exported from shared.mjs (re-exported at line 43)
 
 /**
  * Auto-detect project type from package.json and file structure.
@@ -273,22 +215,31 @@ function printHelp() {
   console.log(`${c.bold}Usage:${c.reset}
   docguard <command> [options]
 
-${c.bold}Commands:${c.reset}
-  ${c.green}audit${c.reset}      Scan project, report what CDD docs exist or are missing
-  ${c.green}init${c.reset}       Initialize CDD documentation from templates
-  ${c.green}guard${c.reset}      Validate project against its canonical documentation
-  ${c.green}score${c.reset}      Calculate CDD maturity score (0-100)
-  ${c.green}diagnose${c.reset}   AI orchestrator — chains guard→fix in one command
-  ${c.green}diff${c.reset}       Show gaps between canonical docs and code
-  ${c.green}agents${c.reset}     Generate agent-specific config files from AGENTS.md
+${c.bold}Getting Started:${c.reset}
+  ${c.green}init${c.reset}       Initialize CDD docs (interactive setup)
   ${c.green}generate${c.reset}   Reverse-engineer canonical docs from existing code
-  ${c.green}hooks${c.reset}      Install git hooks (pre-commit, pre-push, commit-msg)
+
+${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}Analysis:${c.reset}
+  ${c.green}score${c.reset}      CDD maturity score (0-100)
+  ${c.green}trace${c.reset}      Requirements traceability matrix
+  ${c.green}diff${c.reset}       Show gaps between docs and code (detailed view)
+
+${c.bold}CI/CD & Automation:${c.reset}
+  ${c.green}ci${c.reset}         Pipeline gate (guard + score, exit codes)
+  ${c.green}hooks${c.reset}      Install/manage git hooks
+  ${c.green}watch${c.reset}      Watch for changes, re-run guard
+
+${c.bold}Utilities:${c.reset}
+  ${c.green}fix${c.reset}        Generate AI fix instructions for specific docs
+  ${c.green}agents${c.reset}     Generate agent config files (AGENTS.md, CLAUDE.md)
   ${c.green}badge${c.reset}      Generate CDD score badges for README
-  ${c.green}ci${c.reset}         Single command for CI/CD pipelines (guard + score)
-  ${c.green}fix${c.reset}        Find issues and generate AI fix instructions
-  ${c.green}watch${c.reset}      Watch for file changes and re-run guard automatically
-  ${c.green}publish${c.reset}    Scaffold external docs (Mintlify, Docusaurus)
-  ${c.green}trace${c.reset}      Generate requirements traceability matrix
+
+${c.bold}Experimental:${c.reset}
+  ${c.dim}publish${c.reset}    Scaffold external doc sites (Mintlify)
 
 ${c.bold}Options:${c.reset}
   --dir <path>    Project directory (default: current directory)
@@ -305,7 +256,6 @@ ${c.bold}Options:${c.reset}
   --auto          Auto-fix what's possible (used with fix command)
   --doc <name>    Generate AI prompt for specific doc (architecture, security, etc.)
   --profile <p>   Compliance profile: starter, standard, enterprise (init command)
-  --platform <p>  Doc platform: mintlify (publish command)
   --tax           Show estimated documentation maintenance cost (with score)
   --help          Show this help message
   --version       Show version
@@ -319,12 +269,12 @@ ${c.bold}Examples:${c.reset}
   ${c.dim}# AI auto-diagnose and fix${c.reset}
   docguard diagnose
 
-  ${c.dim}# Quick start for a side project${c.reset}
-  docguard init --profile starter
-
-  ${c.dim}# Full CDD init (default)${c.reset}
+  ${c.dim}# Interactive setup (asks which docs you need)${c.reset}
   docguard init
 
+  ${c.dim}# Quick start for a side project${c.reset}
+  docguard init --profile starter --skip-prompts
+
   ${c.dim}# See documentation tax estimate${c.reset}
   docguard score --tax
 
@@ -339,7 +289,7 @@ ${c.bold}Learn more:${c.reset}
 }
 
 // ── Main ───────────────────────────────────────────────────────────────────
-function main() {
+async function main() {
   const args = process.argv.slice(2);
   const command = args[0];
 
@@ -425,10 +375,11 @@ function main() {
 
   switch (command) {
     case 'audit':
-      runAudit(projectDir, config, flags);
+      // audit is an alias for guard — guard does everything the old audit did + 50 more checks
+      runGuard(projectDir, config, flags);
       break;
     case 'init':
-      runInit(projectDir, config, flags);
+      await runInit(projectDir, config, flags);
       break;
     case 'guard':
       runGuard(projectDir, config, flags);

package/cli/shared.mjs

@@ -0,0 +1,65 @@
+/**
+ * Shared constants for DocGuard CLI — colors, profiles, version.
+ * Extracted from docguard.mjs to break circular dependencies.
+ * All commands import from here instead of docguard.mjs.
+ */
+
+// ── Colors (ANSI escape codes, zero deps) ──────────────────────────────────
+export const c = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  cyan: '\x1b[36m',
+  white: '\x1b[37m',
+  bgRed: '\x1b[41m',
+  bgGreen: '\x1b[42m',
+  bgYellow: '\x1b[43m',
+};
+
+// ── Compliance Profiles ───────────────────────────────────────────────────
+export const PROFILES = {
+  starter: {
+    description: 'Minimal CDD — just architecture + changelog. For side projects and prototypes.',
+    requiredFiles: {
+      canonical: [
+        'docs-canonical/ARCHITECTURE.md',
+      ],
+      agentFile: ['AGENTS.md', 'CLAUDE.md'],
+      changelog: 'CHANGELOG.md',
+      driftLog: 'DRIFT-LOG.md',
+    },
+    validators: {
+      structure: true,
+      docsSync: true,
+      drift: false,
+      changelog: true,
+      architecture: false,
+      testSpec: false,
+      security: false,
+      environment: false,
+      freshness: false,
+    },
+  },
+  standard: {
+    description: 'Full CDD — all 5 canonical docs. For team projects.',
+    // Uses the defaults — no overrides needed
+  },
+  enterprise: {
+    description: 'Strict CDD — all docs, all validators, freshness enforced. For regulated/enterprise projects.',
+    validators: {
+      structure: true,
+      docsSync: true,
+      drift: true,
+      changelog: true,
+      architecture: true,
+      testSpec: true,
+      security: true,
+      environment: true,
+      freshness: true,
+    },
+  },
+};

package/cli/validators/docs-diff.mjs

@@ -0,0 +1,185 @@
+/**
+ * Docs-Diff Validator — Checks alignment between canonical docs and code.
+ *
+ * Runs as part of `docguard guard` on every invocation.
+ * Detects undocumented code artifacts and documented items not found in code.
+ * Returns warnings (not errors) since drift is a soft signal.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { resolve, join, extname, basename } from 'node:path';
+
+const IGNORE_DIRS = new Set([
+  'node_modules', '.git', '.next', 'dist', 'build',
+  'coverage', '.cache', '__pycache__', '.venv', 'vendor',
+  'docs-canonical', 'docs-implementation', 'templates',
+]);
+
+const CODE_EXTENSIONS = new Set([
+  '.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx',
+  '.py', '.java', '.go', '.rs', '.rb', '.php',
+]);
+
+/**
+ * Validate doc-code alignment — compares canonical docs vs source code.
+ * @returns {{ errors: string[], warnings: string[], passed: number, total: number }}
+ */
+export function validateDocsDiff(projectDir, config) {
+  const warnings = [];
+  let passed = 0;
+  let total = 0;
+
+  const checks = [
+    diffTechStack(projectDir),
+    diffEnvVars(projectDir),
+    diffTests(projectDir),
+  ];
+
+  for (const result of checks) {
+    if (!result) continue;
+
+    total++;
+    const undocumented = result.onlyInCode.length;
+    const stale = result.onlyInDocs.length;
+
+    if (undocumented === 0 && stale === 0) {
+      passed++;
+    } else {
+      const parts = [];
+      if (undocumented > 0) parts.push(`${undocumented} in code but not documented`);
+      if (stale > 0) parts.push(`${stale} documented but not found in code`);
+      warnings.push(`${result.title} drift: ${parts.join(', ')}`);
+    }
+  }
+
+  return { errors: [], warnings, passed, total };
+}
+
+// ── Diff Functions (lightweight versions for validator) ──────────────────
+
+function diffTechStack(dir) {
+  const archPath = resolve(dir, 'docs-canonical/ARCHITECTURE.md');
+  const pkgPath = resolve(dir, 'package.json');
+  if (!existsSync(archPath) || !existsSync(pkgPath)) return null;
+
+  const archContent = readFileSync(archPath, 'utf-8');
+  let pkg;
+  try { pkg = JSON.parse(readFileSync(pkgPath, 'utf-8')); } catch { return null; }
+
+  const docTech = new Set();
+  const techPatterns = ['React', 'Next.js', 'Vue', 'Angular', 'Svelte', 'Express', 'Fastify', 'Hono',
+    'PostgreSQL', 'MySQL', 'MongoDB', 'DynamoDB', 'Redis', 'Prisma', 'Drizzle',
+    'TypeScript', 'Tailwind', 'Docker', 'Terraform'];
+
+  for (const tech of techPatterns) {
+    if (archContent.toLowerCase().includes(tech.toLowerCase())) {
+      docTech.add(tech);
+    }
+  }
+
+  const codeTech = new Set();
+  const 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',
+    'drizzle-orm': 'Drizzle', 'typescript': 'TypeScript', 'tailwindcss': 'Tailwind',
+    'redis': 'Redis', 'ioredis': 'Redis', 'pg': 'PostgreSQL', 'mysql2': 'MySQL',
+    'mongoose': 'MongoDB', '@aws-sdk/client-dynamodb': 'DynamoDB',
+  };
+
+  for (const [dep, tech] of Object.entries(depMap)) {
+    if (allDeps[dep]) codeTech.add(tech);
+  }
+
+  if (docTech.size === 0 && codeTech.size === 0) return null;
+
+  return {
+    title: 'Tech Stack',
+    onlyInDocs: [...docTech].filter(t => !codeTech.has(t)),
+    onlyInCode: [...codeTech].filter(t => !docTech.has(t)),
+  };
+}
+
+function diffEnvVars(dir) {
+  const envDocPath = resolve(dir, 'docs-canonical/ENVIRONMENT.md');
+  if (!existsSync(envDocPath)) return null;
+
+  const content = readFileSync(envDocPath, 'utf-8');
+  const docVars = new Set();
+  const varRegex = /`([A-Z][A-Z0-9_]{2,})`/g;
+  let match;
+  while ((match = varRegex.exec(content)) !== null) {
+    docVars.add(match[1]);
+  }
+
+  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]);
+    }
+  }
+
+  if (docVars.size === 0 && codeVars.size === 0) return null;
+
+  return {
+    title: 'Environment Variables',
+    onlyInDocs: [...docVars].filter(v => !codeVars.has(v)),
+    onlyInCode: [...codeVars].filter(v => !docVars.has(v)),
+  };
+}
+
+function diffTests(dir) {
+  const testSpecPath = resolve(dir, 'docs-canonical/TEST-SPEC.md');
+  if (!existsSync(testSpecPath)) return null;
+
+  const content = readFileSync(testSpecPath, 'utf-8');
+  const docTests = new Set();
+  const testFileRegex = /`([^`]*\.(test|spec)\.[^`]+)`/g;
+  let match;
+  while ((match = testFileRegex.exec(content)) !== null) {
+    docTests.add(match[1]);
+  }
+
+  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) {
+      codeTests.add(f.replace(dir + '/', ''));
+    }
+  }
+
+  if (docTests.size === 0 && codeTests.size === 0) return null;
+
+  return {
+    title: 'Test Files',
+    onlyInDocs: [...docTests].filter(t => !codeTests.has(t)),
+    onlyInCode: [...codeTests].filter(t => !docTests.has(t)),
+  };
+}
+
+function getFilesRecursive(dir) {
+  const results = [];
+  if (!existsSync(dir)) return results;
+  let entries;
+  try { entries = readdirSync(dir); } catch { return results; }
+
+  for (const entry of entries) {
+    if (IGNORE_DIRS.has(entry) || entry.startsWith('.')) continue;
+    const fullPath = join(dir, entry);
+    try {
+      const stat = statSync(fullPath);
+      if (stat.isDirectory()) {
+        results.push(...getFilesRecursive(fullPath));
+      } else if (stat.isFile() && CODE_EXTENSIONS.has(extname(fullPath))) {
+        results.push(fullPath);
+      }
+    } catch { /* skip */ }
+  }
+  return results;
+}

package/cli/validators/test-spec.mjs

@@ -37,6 +37,7 @@ export function validateTestSpec(projectDir, config) {
       if (cells.length < 3) continue;
 
       const sourceFile = cells[0];
+      const testFile = cells[1];
       const status = cells[cells.length - 1]; // Last column is always status
 
       // Skip template/example rows and italic placeholder rows
@@ -56,6 +57,38 @@ export function validateTestSpec(projectDir, config) {
         results.total++;
         results.passed++;
       }
+
+      // ── File existence checks ───────────────────────────────────────
+      // Verify source file still exists (catch stale map entries)
+      const cleanSource = sourceFile.replace(/`/g, '').trim();
+      if (cleanSource && cleanSource !== '—' && cleanSource !== 'Source File') {
+        const sourcePath = resolve(projectDir, cleanSource);
+        if (!existsSync(sourcePath)) {
+          results.total++;
+          results.warnings.push(
+            `Source-to-Test Map: source file \`${cleanSource}\` not found on disk — stale entry?`
+          );
+        } else {
+          results.total++;
+          results.passed++;
+        }
+      }
+
+      // Verify test file exists (catch wrong/stale test references)
+      const cleanTest = testFile ? testFile.replace(/`/g, '').trim() : '';
+      if (cleanTest && cleanTest !== '—' && cleanTest !== 'Test File' &&
+          cleanTest !== 'Unit Test' && !cleanTest.includes('N/A')) {
+        const testPath = resolve(projectDir, cleanTest);
+        if (!existsSync(testPath)) {
+          results.total++;
+          results.warnings.push(
+            `Source-to-Test Map: test file \`${cleanTest}\` not found — referenced by ${cleanSource}`
+          );
+        } else {
+          results.total++;
+          results.passed++;
+        }
+      }
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docguard-cli",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation.",
   "type": "module",
   "bin": {

package/templates/TEST-SPEC.md.template

@@ -53,3 +53,16 @@
 |--------|---------------|------|
 | Health | <!-- e.g. /health returns 200 --> | |
 | Auth | <!-- e.g. Login flow completes --> | |
+
+## Recommended Test Patterns
+
+<!-- DocGuard validates that files listed in the Source-to-Test Map exist on disk.
+     Keep the map up to date — stale entries will trigger warnings. -->
+
+| Pattern | Description | Priority |
+|---------|-------------|----------|
+| Config-awareness | Test behavior changes per `.docguard.json` / env config | ⚠️ High |
+| Individual functions | Test each module/function directly, not just via CLI | ⚠️ High |
+| Edge cases | Empty inputs, missing files, invalid config | ✅ Medium |
+| Error paths | Verify graceful failure, not just happy path | ✅ Medium |
+| Regression guards | Pin specific bug fixes with dedicated tests | ✅ Medium |

package/cli/commands/audit.mjs

@@ -1,92 +0,0 @@
-/**
- * Audit Command — Scan project, report what CDD docs exist or are missing
- * Now uses the full documentTypes config to show ALL docs with categories.
- */
-
-import { existsSync } from 'node:fs';
-import { resolve } from 'node:path';
-import { c } from '../docguard.mjs';
-
-export function runAudit(projectDir, config, flags) {
-  console.log(`${c.bold}📋 DocGuard Audit — ${config.projectName}${c.reset}`);
-  console.log(`${c.dim}   Directory: ${projectDir}${c.reset}\n`);
-
-  const results = { found: 0, missing: 0, optional: 0, total: 0, details: [] };
-
-  // Use documentTypes from config (all 16 doc types with required/optional)
-  const docTypes = config.documentTypes || {};
-
-  // Group by category
-  const categories = {};
-  for (const [filePath, meta] of Object.entries(docTypes)) {
-    const cat = meta.category || 'other';
-    if (!categories[cat]) categories[cat] = [];
-    categories[cat].push({ filePath, ...meta });
-  }
-
-  // Category display names and order
-  const categoryLabels = {
-    canonical: '📘 Canonical Documentation (Design Intent)',
-    implementation: '📗 Implementation Documentation (Current State)',
-    agent: '🤖 Agent Instructions',
-    tracking: '📑 Change Tracking',
-  };
-
-  const categoryOrder = ['canonical', 'implementation', 'agent', 'tracking'];
-
-  for (const cat of categoryOrder) {
-    const docs = categories[cat];
-    if (!docs || docs.length === 0) continue;
-
-    console.log(`${c.bold}  ${categoryLabels[cat] || cat}${c.reset}`);
-
-    for (const doc of docs) {
-      const fullPath = resolve(projectDir, doc.filePath);
-      const exists = existsSync(fullPath);
-
-      if (exists) {
-        results.found++;
-        results.total++;
-        results.details.push({ file: doc.filePath, status: 'found', required: doc.required });
-        console.log(`    ${c.green}✅${c.reset} ${doc.filePath} ${c.dim}— ${doc.description}${c.reset}`);
-      } else if (doc.required) {
-        results.missing++;
-        results.total++;
-        results.details.push({ file: doc.filePath, status: 'missing', required: true });
-        console.log(`    ${c.red}❌${c.reset} ${doc.filePath} ${c.dim}— ${doc.description}${c.reset} ${c.red}(required)${c.reset}`);
-      } else {
-        results.optional++;
-        results.details.push({ file: doc.filePath, status: 'optional', required: false });
-        if (flags.verbose) {
-          console.log(`    ${c.dim}○  ${doc.filePath} — ${doc.description} (optional)${c.reset}`);
-        }
-      }
-    }
-    console.log('');
-  }
-
-  // Score (only required files)
-  const requiredTotal = results.found + results.missing;
-  const pct = requiredTotal === 0 ? 100 : Math.round((results.found / requiredTotal) * 100);
-  const scoreColor = pct >= 80 ? c.green : pct >= 50 ? c.yellow : c.red;
-
-  console.log(`${c.bold}  ─────────────────────────────────────${c.reset}`);
-  console.log(`  ${c.bold}Required:${c.reset} ${scoreColor}${results.found - (results.found - requiredTotal + results.missing)}/${requiredTotal} files (${pct}%)${c.reset}`);
-
-  // Show optional count
-  if (!flags.verbose && results.optional > 0) {
-    console.log(`  ${c.dim}Optional: ${results.optional} not present (use --verbose to see all)${c.reset}`);
-  }
-
-  if (results.missing > 0) {
-    console.log(`\n  ${c.yellow}💡 Run ${c.cyan}docguard init${c.yellow} to create missing docs from templates.${c.reset}`);
-    console.log(`  ${c.yellow}💡 Run ${c.cyan}docguard generate${c.yellow} to auto-fill docs from your codebase.${c.reset}`);
-  } else {
-    console.log(`\n  ${c.green}🎉 All required CDD documentation present!${c.reset}`);
-    console.log(`  ${c.dim}Run ${c.cyan}docguard guard${c.dim} to validate content alignment.${c.reset}`);
-    console.log(`  ${c.dim}Run ${c.cyan}docguard score${c.dim} to check your CDD maturity.${c.reset}`);
-  }
-
-  console.log('');
-  return results;
-}