docguard-cli 0.8.0 → 0.8.2

package/README.md

@@ -81,6 +81,27 @@ diagnose  →  AI reads prompts  →  AI fixes docs  →  guard verifies
 
 ---
 
+## Usage
+
+```bash
+# Initialize CDD docs for your project
+npx docguard-cli init
+
+# Reverse-engineer docs from existing code
+npx docguard-cli generate
+
+# Validate project — use as CI gate
+npx docguard-cli guard
+
+# Get AI-actionable fix prompts
+npx docguard-cli diagnose
+
+# Check CDD maturity score
+npx docguard-cli score
+```
+
+---
+
 ## 13 Commands
 
 ### 🔮 Generate — Reverse-engineer docs from code
@@ -202,7 +223,7 @@ $ npx docguard-cli guard
 
 ---
 
-## 9 Validators
+## 14 Validators
 
 | # | Validator | What It Checks | Default |
 |---|-----------|---------------|---------| 
@@ -213,8 +234,15 @@ $ npx docguard-cli guard
 | 5 | **Changelog** | CHANGELOG.md has [Unreleased] section | ✅ On |
 | 6 | **Test-Spec** | Tests exist per TEST-SPEC.md rules | ✅ On |
 | 7 | **Environment** | Env vars documented, .env.example exists | ✅ On |
-| 8 | **Security** | No hardcoded secrets in source code | ❌ Off |
-| 9 | **Architecture** | Imports follow layer boundaries | ❌ Off |
+| 8 | **Security** | No hardcoded secrets in source code | ✅ On |
+| 9 | **Architecture** | Imports follow layer boundaries | ✅ On |
+| 10 | **Freshness** | Docs not stale relative to code changes | ✅ On |
+| 11 | **Traceability** | Canonical docs linked to source code | ✅ On |
+| 12 | **Docs-Diff** | Code artifacts match documented entities | ✅ On |
+| 13 | **Metadata-Sync** | Version refs consistent across docs | ✅ On |
+| 14 | **Docs-Coverage** | Code features referenced in documentation | ✅ On |
+| 15 | **Metrics-Consistency** | Hardcoded numbers match actual counts | ✅ On |
+| 16 | **Docs-Sync** | Source files have matching doc entries | ✅ On |
 
 ---
 

package/cli/commands/diagnose.mjs

@@ -17,7 +17,8 @@ import { c } from '../shared.mjs';
 import { runGuardInternal } from './guard.mjs';
 import { runScoreInternal } from './score.mjs';
 import { existsSync, readFileSync, mkdirSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { execSync } from 'node:child_process';
 
 // Map validator failures to the right fix --doc target
@@ -103,16 +104,16 @@ export function runDiagnose(projectDir, config, flags) {
   // ── Step 2: Collect issues ──
   let issues = collectIssues(guardData);
 
-  // ── Step 3: Auto-fix what we can (unless --no-fix) ──
-  const shouldAutoFix = !flags.noFix && flags.format !== 'json';
-  if (shouldAutoFix && issues.length > 0) {
+  // ── Step 3: Auto-fix (only with --auto flag) or suggest fixes ──
+  const shouldAutoFix = flags.auto && flags.format !== 'json';
+  if (issues.length > 0) {
     const autoFixable = issues.filter(i => i.autoFixable);
     const hasStructural = issues.some(i => i.validator === 'Structure');
 
-    if (hasStructural || autoFixable.length > 0) {
+    if (shouldAutoFix && (hasStructural || autoFixable.length > 0)) {
       // Run init to create missing files
       try {
-        const cliPath = resolve(import.meta.dirname, '..', 'docguard.mjs');
+        const cliPath = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'docguard.mjs');
         execSync(`node "${cliPath}" init --dir "${projectDir}"`, {
           encoding: 'utf-8',
           stdio: 'pipe',
@@ -121,7 +122,7 @@ export function runDiagnose(projectDir, config, flags) {
 
       // Run generate to fill in content
       try {
-        const cliPath = resolve(import.meta.dirname, '..', 'docguard.mjs');
+        const cliPath = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'docguard.mjs');
         execSync(`node "${cliPath}" generate --dir "${projectDir}" --force`, {
           encoding: 'utf-8',
           stdio: 'pipe',
@@ -138,6 +139,12 @@ export function runDiagnose(projectDir, config, flags) {
           console.log(`  ${c.green}⚡ Auto-fixed ${fixedCount} issue(s)${c.reset} (created/regenerated docs)\n`);
         }
       }
+    } else if (!shouldAutoFix && (hasStructural || autoFixable.length > 0) && (!flags.format || flags.format === 'text')) {
+      // Suggest-only mode: tell user what they can do
+      console.log(`  ${c.yellow}💡 ${autoFixable.length + (hasStructural ? 1 : 0)} issue(s) can be auto-fixed.${c.reset} Run with ${c.cyan}--auto${c.reset} to create/regenerate docs, or manually:`);
+      if (hasStructural) console.log(`     ${c.dim}docguard init --dir .${c.reset}`);
+      if (autoFixable.length > 0) console.log(`     ${c.dim}docguard generate --dir . --force${c.reset}`);
+      console.log('');
     }
   }
 
@@ -340,7 +347,7 @@ function outputPrompt(projectDir, guardData, scoreData, issues, flags) {
   lines.push('VALIDATION:');
   lines.push('After making all fixes, run: docguard guard');
   lines.push('Expected result: All checks pass (0 errors, 0 warnings)');
-  lines.push(`Target score: ≥${scoreData.score + 5}/100`);
+  lines.push(`Target score: ≥${Math.min(scoreData.score + 5, 100)}/100`);
 
   // Agent-aware: add explicit checklist for basic-tier agents
   if (agentTier === 'basic') {

package/cli/commands/fix.mjs

@@ -14,8 +14,9 @@
  */
 
 import { existsSync, readFileSync, mkdirSync } from 'node:fs';
-import { resolve, basename } from 'node:path';
+import { resolve, basename, dirname } from 'node:path';
 import { execSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
 import { c } from '../shared.mjs';
 
 // ── Document Quality Definitions ───────────────────────────────────────────
@@ -471,7 +472,7 @@ function autoFixIssues(projectDir, config, issues) {
   }
 
   try {
-    const cliPath = resolve(import.meta.dirname, '..', 'docguard.mjs');
+    const cliPath = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'docguard.mjs');
     execSync(`node ${cliPath} init --dir "${projectDir}"`, {
       encoding: 'utf-8',
       stdio: 'pipe',

package/cli/commands/generate.mjs

@@ -318,7 +318,7 @@ function scanProject(dir) {
     }
   });
 
-  // Find tests
+  // Find tests — top-level test dirs
   ['tests', 'test', '__tests__', 'spec', 'e2e'].forEach(testDir => {
     const fullDir = resolve(dir, testDir);
     if (existsSync(fullDir)) {
@@ -329,6 +329,55 @@ function scanProject(dir) {
     }
   });
 
+  // Find co-located tests: src/**/__tests__/ and src/**/*.test.* / src/**/*.spec.*
+  const srcDir = resolve(dir, 'src');
+  if (existsSync(srcDir)) {
+    walkDir(srcDir, (filePath) => {
+      const rel = relative(dir, filePath);
+      const isTestDir = rel.includes('__tests__') || rel.includes('__test__');
+      const isTestFile = /\.(test|spec)\.[^.]+$/.test(rel);
+      if ((isTestDir || isTestFile) && !scan.tests.includes(rel)) {
+        scan.tests.push(rel);
+      }
+    });
+  }
+
+  // Read vitest/jest config for custom test patterns
+  const testConfigs = ['vitest.config.ts', 'vitest.config.js', 'vitest.config.mts', 'jest.config.ts', 'jest.config.js'];
+  for (const cfgFile of testConfigs) {
+    const cfgPath = resolve(dir, cfgFile);
+    if (existsSync(cfgPath)) {
+      try {
+        const cfgContent = readFileSync(cfgPath, 'utf-8');
+        // Extract include patterns like: include: ['src/**/*.test.ts']
+        const includeMatch = cfgContent.match(/include\s*:\s*\[([^\]]+)\]/);
+        if (includeMatch) {
+          // Parse the test root from the pattern (e.g., 'src/**/*.test.ts' → 'src')
+          const patterns = includeMatch[1].match(/['"]([^'"]+)['"]/g);
+          if (patterns) {
+            for (const p of patterns) {
+              const pattern = p.replace(/['"]|\s/g, '');
+              // Extract root dir from glob (e.g., 'src/**/*.test.ts' → 'src')
+              const rootDir = pattern.split('/')[0];
+              if (rootDir && rootDir !== '**' && rootDir !== '*') {
+                const fullDir = resolve(dir, rootDir);
+                if (existsSync(fullDir)) {
+                  walkDir(fullDir, (filePath) => {
+                    const rel = relative(dir, filePath);
+                    if (/\.(test|spec)\.[^.]+$/.test(rel) && !scan.tests.includes(rel)) {
+                      scan.tests.push(rel);
+                    }
+                  });
+                }
+              }
+            }
+          }
+        }
+      } catch { /* config parse may fail */ }
+      break; // Use first found config
+    }
+  }
+
   // Find components
   ['src/components', 'components', 'src/ui'].forEach(compDir => {
     const fullDir = resolve(dir, compDir);
@@ -367,6 +416,15 @@ 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;
 }
 

package/cli/commands/guard.mjs

@@ -19,6 +19,9 @@ 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 { validateMetadataSync } from '../validators/metadata-sync.mjs';
+import { validateMetricsConsistency } from '../validators/metrics-consistency.mjs';
+import { validateDocsCoverage } from '../validators/docs-coverage.mjs';
 
 /**
  * Internal guard — returns structured data, no console output, no process.exit.
@@ -52,6 +55,9 @@ export function runGuardInternal(projectDir, config) {
     }},
     { key: 'traceability', name: 'Traceability', fn: () => validateTraceability(projectDir, config) },
     { key: 'docsDiff', name: 'Docs-Diff', fn: () => validateDocsDiff(projectDir, config) },
+    { key: 'metadataSync', name: 'Metadata-Sync', fn: () => validateMetadataSync(projectDir, config) },
+    { key: 'docsCoverage', name: 'Docs-Coverage', fn: () => validateDocsCoverage(projectDir, config) },
+    // Metrics-Consistency runs post-loop (needs guard results)
   ];
 
   for (const { key, name, fn } of validatorMap) {
@@ -84,6 +90,21 @@ export function runGuardInternal(projectDir, config) {
     }
   }
 
+  // ── Metrics-Consistency runs AFTER all other validators (needs their results) ──
+  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 });
+    } catch (err) {
+      results.push({ name: 'Metrics-Consistency', key: 'metricsConsistency', status: 'fail', quality: 'LOW', errors: [err.message], warnings: [], passed: 0, total: 1 });
+    }
+  }
+
   const activeResults = results.filter(r => r.status !== 'skipped');
   const totalErrors = activeResults.reduce((sum, r) => sum + r.errors.length, 0);
   const totalWarnings = activeResults.reduce((sum, r) => sum + r.warnings.length, 0);

package/cli/shared.mjs

@@ -63,3 +63,44 @@ export const PROFILES = {
     },
   },
 };
+
+// ── .docguardignore Support ───────────────────────────────────────────────
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve, relative } from 'node:path';
+
+/**
+ * Load ignore patterns from .docguardignore (like .gitignore).
+ * Returns a function that checks if a relative path should be ignored.
+ *
+ * Format: one pattern per line, # comments, blank lines skipped.
+ * Supports simple glob: * (any chars), ** (any path segments).
+ *
+ * @param {string} projectDir - Project root
+ * @returns {(relPath: string) => boolean} - Returns true if file should be ignored
+ */
+export function loadIgnorePatterns(projectDir) {
+  const ignorePath = resolve(projectDir, '.docguardignore');
+  if (!existsSync(ignorePath)) return () => false;
+
+  let content;
+  try { content = readFileSync(ignorePath, 'utf-8'); } catch { return () => false; }
+
+  const patterns = content
+    .split('\n')
+    .map(line => line.trim())
+    .filter(line => line && !line.startsWith('#'))
+    .map(pattern => {
+      // Convert glob to regex:
+      // ** → match any path segments
+      // * → match any chars except /
+      // . → literal dot
+      const escaped = pattern
+        .replace(/\./g, '\\.')
+        .replace(/\*\*/g, '§§')     // temp placeholder
+        .replace(/\*/g, '[^/]*')
+        .replace(/§§/g, '.*');
+      return new RegExp(`^${escaped}$|/${escaped}$|^${escaped}/|/${escaped}/`);
+    });
+
+  return (relPath) => patterns.some(regex => regex.test(relPath));
+}

package/cli/validators/docs-coverage.mjs

@@ -0,0 +1,387 @@
+/**
+ * Docs-Coverage Validator — Detects code features not referenced in docs.
+ *
+ * Generic validator for ANY project type. Scans the project for
+ * "documentable artifacts" and checks if at least one canonical doc
+ * or README references them.
+ *
+ * What it catches:
+ *  - Config/dotfiles at root not mentioned in docs
+ *  - Config filenames referenced in source code (resolve/readFile calls) but not documented
+ *  - package.json bin entries not documented
+ *  - Source directories not referenced in ARCHITECTURE.md
+ *  - README.md missing standard sections (inspired by Standard README spec)
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { resolve, join, relative, basename, extname } from 'node:path';
+
+const IGNORE_DIRS = new Set([
+  'node_modules', '.git', '.next', 'dist', 'build', 'coverage',
+  '.cache', '__pycache__', '.venv', 'vendor', '.turbo', '.vercel',
+]);
+
+// Dotfiles that are universally common and don't need documentation
+const COMMON_DOTFILES = new Set([
+  '.gitignore', '.gitattributes', '.git', '.DS_Store',
+  '.editorconfig', '.prettierrc', '.prettierignore',
+  '.eslintrc', '.eslintrc.js', '.eslintrc.json', '.eslintrc.cjs',
+  '.eslintignore', '.nvmrc', '.node-version', '.npmrc', '.npmignore',
+  '.env', '.env.local', '.env.development', '.env.production',
+  '.vscode', '.idea', '.github', '.husky',
+  '.babelrc', '.browserslistrc', '.stylelintrc',
+]);
+
+/**
+ * Validate that code artifacts are referenced in documentation.
+ * @param {string} projectDir - Project root directory
+ * @param {object} config - DocGuard config
+ * @returns {{ errors: string[], warnings: string[], passed: number, total: number }}
+ */
+export function validateDocsCoverage(projectDir, config) {
+  const warnings = [];
+  let passed = 0;
+  let total = 0;
+
+  // Collect all doc content for searching
+  const allDocContent = collectDocContent(projectDir);
+  if (!allDocContent) {
+    return { errors: [], warnings, passed: 0, total: 0 };
+  }
+
+  // ── Check 1: Project-specific config/dotfiles referenced in docs ──
+  const configChecks = checkConfigFiles(projectDir, allDocContent);
+  total += configChecks.total;
+  passed += configChecks.passed;
+  warnings.push(...configChecks.warnings);
+
+  // ── Check 2: package.json bin entries documented ──
+  const binChecks = checkPackageBins(projectDir, allDocContent);
+  total += binChecks.total;
+  passed += binChecks.passed;
+  warnings.push(...binChecks.warnings);
+
+  // ── Check 3: Source directory structure matches ARCHITECTURE.md ──
+  const dirChecks = checkSourceDirs(projectDir, allDocContent);
+  total += dirChecks.total;
+  passed += dirChecks.passed;
+  warnings.push(...dirChecks.warnings);
+
+  // ── Check 4: Config filenames referenced in source code but not documented ──
+  const codeConfigChecks = checkCodeReferencedConfigs(projectDir, allDocContent);
+  total += codeConfigChecks.total;
+  passed += codeConfigChecks.passed;
+  warnings.push(...codeConfigChecks.warnings);
+
+  // ── Check 5: README section completeness (Standard README spec) ──
+  const readmeChecks = checkReadmeSections(projectDir);
+  total += readmeChecks.total;
+  passed += readmeChecks.passed;
+  warnings.push(...readmeChecks.warnings);
+
+  return { errors: [], warnings, passed, total };
+}
+
+// ── Check Functions ─────────────────────────────────────────────────────────
+
+/**
+ * Check 1: Project-specific config/dotfiles are mentioned in docs.
+ * Skips universally common files (.gitignore, .eslintrc, etc.).
+ */
+function checkConfigFiles(projectDir, allDocContent) {
+  const warnings = [];
+  let passed = 0;
+  let total = 0;
+
+  let entries;
+  try { entries = readdirSync(projectDir); } catch { return { warnings, passed, total }; }
+
+  const lowerDocContent = allDocContent.toLowerCase();
+
+  for (const entry of entries) {
+    const isDotFile = entry.startsWith('.');
+    const isProjectConfig = entry.endsWith('.config.js') ||
+      entry.endsWith('.config.ts') ||
+      entry.endsWith('.config.mjs') ||
+      entry.endsWith('.config.cjs') ||
+      entry.endsWith('.json') && !['package.json', 'package-lock.json', 'tsconfig.json'].includes(entry);
+
+    if (!isDotFile && !isProjectConfig) continue;
+    if (COMMON_DOTFILES.has(entry)) continue;
+    if (entry === 'tsconfig.json' || entry === 'package-lock.json') continue;
+
+    total++;
+    if (lowerDocContent.includes(entry.toLowerCase())) {
+      passed++;
+    } else {
+      warnings.push(
+        `Config file "${entry}" exists but is not mentioned in any documentation. Document its purpose in ARCHITECTURE.md or README.md`
+      );
+    }
+  }
+
+  return { warnings, passed, total };
+}
+
+/**
+ * Check 2: package.json bin entries (CLI commands users run) are documented.
+ */
+function checkPackageBins(projectDir, allDocContent) {
+  const warnings = [];
+  let passed = 0;
+  let total = 0;
+
+  const pkgPath = resolve(projectDir, 'package.json');
+  if (!existsSync(pkgPath)) return { warnings, passed, total };
+
+  let pkg;
+  try { pkg = JSON.parse(readFileSync(pkgPath, 'utf-8')); } catch { return { warnings, passed, total }; }
+
+  const bins = typeof pkg.bin === 'string'
+    ? { [pkg.name]: pkg.bin }
+    : (pkg.bin || {});
+
+  const lowerDocContent = allDocContent.toLowerCase();
+
+  for (const [binName] of Object.entries(bins)) {
+    total++;
+    if (lowerDocContent.includes(binName.toLowerCase())) {
+      passed++;
+    } else {
+      warnings.push(
+        `package.json defines CLI command "${binName}" but it's not mentioned in any documentation`
+      );
+    }
+  }
+
+  return { warnings, passed, total };
+}
+
+/**
+ * Check 3: Source directories are referenced in ARCHITECTURE.md.
+ */
+function checkSourceDirs(projectDir, allDocContent) {
+  const warnings = [];
+  let passed = 0;
+  let total = 0;
+
+  const archPath = resolve(projectDir, 'docs-canonical/ARCHITECTURE.md');
+  if (!existsSync(archPath)) return { warnings, passed, total };
+
+  let archContent;
+  try { archContent = readFileSync(archPath, 'utf-8'); } catch { return { warnings, passed, total }; }
+
+  const lowerArchContent = archContent.toLowerCase();
+  const sourceRoots = ['src', 'lib', 'app', 'cli', 'server', 'api'];
+
+  for (const root of sourceRoots) {
+    const rootDir = resolve(projectDir, root);
+    if (!existsSync(rootDir)) continue;
+
+    let entries;
+    try { entries = readdirSync(rootDir); } catch { continue; }
+
+    for (const entry of entries) {
+      const fullPath = join(rootDir, entry);
+      try {
+        const stat = statSync(fullPath);
+        if (!stat.isDirectory()) continue;
+      } catch { continue; }
+
+      if (IGNORE_DIRS.has(entry) || entry.startsWith('.') || entry === '__tests__' || entry === '__test__') continue;
+
+      total++;
+      const searchName = entry.toLowerCase();
+      if (lowerArchContent.includes(searchName) || lowerArchContent.includes(root + '/' + entry)) {
+        passed++;
+      } else {
+        warnings.push(
+          `Source directory "${root}/${entry}/" is not referenced in ARCHITECTURE.md`
+        );
+      }
+    }
+  }
+
+  return { warnings, passed, total };
+}
+
+/**
+ * Check 4: Config files that code actually READS are documented.
+ *
+ * Scans source code for resolve(dir, '.configname') and existsSync('.configname')
+ * patterns — these are configs the project USES. Avoids matching config names
+ * sitting in arrays (scan patterns for detecting other projects' configs).
+ */
+function checkCodeReferencedConfigs(projectDir, allDocContent) {
+  const warnings = [];
+  let passed = 0;
+  let total = 0;
+
+  const lowerDocContent = allDocContent.toLowerCase();
+  const foundConfigs = new Set();
+
+  // Only match config filenames inside function calls that actually USE the file:
+  // resolve(dir, '.docguardignore'), existsSync('.env.example'), readFileSync('vitest.config.ts')
+  const usageRegex = /(?:resolve|join|existsSync|readFileSync|accessSync|writeFileSync)\s*\([^)]*['"`]([^'"`\n]{2,})['"`]/g;
+
+  const sourceRoots = ['src', 'lib', 'cli', 'bin', 'server', 'api', 'app'];
+
+  const scanFile = (filePath) => {
+    const ext = extname(filePath);
+    if (!['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx'].includes(ext)) return;
+    let content;
+    try { content = readFileSync(filePath, 'utf-8'); } catch { return; }
+
+    usageRegex.lastIndex = 0;
+    let match;
+    while ((match = usageRegex.exec(content)) !== null) {
+      const name = match[1];
+      // Must be a dotfile (.something) or *.config.* — not a path
+      if (name.includes('/') || name.startsWith('..')) continue;
+      const isDotConfig = name.startsWith('.') && name.length > 2;
+      const isNamedConfig = /^[\w-]+\.config\.\w+$/.test(name);
+      if (!isDotConfig && !isNamedConfig) continue;
+      // Skip bare extensions
+      if (/^\.[a-z]{1,4}$/i.test(name)) continue;
+      foundConfigs.add(name);
+    }
+  };
+
+  for (const root of sourceRoots) {
+    const rootDir = resolve(projectDir, root);
+    if (!existsSync(rootDir)) continue;
+    walkFiles(rootDir, scanFile);
+  }
+
+  for (const configName of foundConfigs) {
+    if (COMMON_DOTFILES.has(configName)) continue;
+    total++;
+    if (lowerDocContent.includes(configName.toLowerCase())) {
+      passed++;
+    } else {
+      warnings.push(
+        `Code references config file "${configName}" but no documentation mentions it. Add it to README.md or ARCHITECTURE.md`
+      );
+    }
+  }
+
+  return { warnings, passed, total };
+}
+
+/**
+ * Check 5: README section completeness.
+ * Inspired by Standard README (https://github.com/RichardLitt/standard-readme)
+ * and Make a README (https://www.makeareadme.com/).
+ */
+function checkReadmeSections(projectDir) {
+  const warnings = [];
+  let passed = 0;
+  let total = 0;
+
+  const readmePath = resolve(projectDir, 'README.md');
+  if (!existsSync(readmePath)) return { warnings, passed, total };
+
+  let content;
+  try { content = readFileSync(readmePath, 'utf-8'); } catch { return { warnings, passed, total }; }
+
+  const lowerContent = content.toLowerCase();
+
+  // Required sections — every well-documented project should have these
+  const requiredSections = [
+    { name: 'Installation', patterns: ['install', 'getting started', 'setup', 'quickstart', 'quick start'] },
+    { name: 'Usage', patterns: ['usage', 'how to use', 'examples', 'getting started'] },
+    { name: 'License', patterns: ['license', 'licence'] },
+  ];
+
+  // Recommended — count toward score but don't warn
+  const recommendedSections = [
+    { name: 'Contributing', patterns: ['contributing', 'contribution', 'how to contribute'] },
+    { name: 'Description', patterns: ['## what', '## about', '## description', '## overview'] },
+  ];
+
+  for (const section of requiredSections) {
+    total++;
+    if (section.patterns.some(p => lowerContent.includes(p))) {
+      passed++;
+    } else {
+      warnings.push(`README.md is missing a "${section.name}" section (Standard README spec)`);
+    }
+  }
+
+  for (const section of recommendedSections) {
+    total++;
+    if (section.patterns.some(p => lowerContent.includes(p))) {
+      passed++;
+    }
+  }
+
+  return { warnings, passed, total };
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * Collect all documentation content into a single searchable string.
+ */
+function collectDocContent(projectDir) {
+  const docPaths = [];
+
+  const rootDocs = ['README.md', 'AGENTS.md', 'CLAUDE.md', 'CONTRIBUTING.md', 'STANDARD.md'];
+  for (const doc of rootDocs) {
+    const p = resolve(projectDir, doc);
+    if (existsSync(p)) docPaths.push(p);
+  }
+
+  const canonDir = resolve(projectDir, 'docs-canonical');
+  if (existsSync(canonDir)) {
+    try {
+      for (const entry of readdirSync(canonDir)) {
+        if (entry.endsWith('.md')) docPaths.push(resolve(canonDir, entry));
+      }
+    } catch { /* skip */ }
+  }
+
+  const extDir = resolve(projectDir, 'extensions');
+  if (existsSync(extDir)) {
+    walkFiles(extDir, (f) => {
+      if (f.endsWith('.md') || f.endsWith('.yml') || f.endsWith('.yaml')) {
+        docPaths.push(f);
+      }
+    });
+  }
+
+  for (const docsDir of ['docs', 'docs-implementation']) {
+    const d = resolve(projectDir, docsDir);
+    if (existsSync(d)) {
+      walkFiles(d, (f) => {
+        if (f.endsWith('.md')) docPaths.push(f);
+      });
+    }
+  }
+
+  if (docPaths.length === 0) return null;
+  const parts = [];
+  for (const p of docPaths) {
+    try { parts.push(readFileSync(p, 'utf-8')); } catch { /* skip */ }
+  }
+  return parts.join('\n');
+}
+
+function walkFiles(dir, callback) {
+  if (!existsSync(dir)) return;
+  let entries;
+  try { entries = readdirSync(dir); } catch { return; }
+
+  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()) {
+        walkFiles(fullPath, callback);
+      } else if (stat.isFile()) {
+        callback(fullPath);
+      }
+    } catch { /* skip */ }
+  }
+}

package/cli/validators/metadata-sync.mjs

@@ -0,0 +1,179 @@
+/**
+ * Metadata Sync Validator — Detects stale version references across docs.
+ *
+ * Cross-checks package.json version against extension.yml and all .md files.
+ * Flags outdated version strings (e.g., README references v0.7.2 but package.json is 0.8.0).
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { resolve, join, relative, extname } from 'node:path';
+import { loadIgnorePatterns } from '../shared.mjs';
+
+const IGNORE_DIRS = new Set([
+  'node_modules', '.git', '.next', 'dist', 'build', 'coverage',
+  '.cache', '__pycache__', '.venv', 'vendor', '.turbo', '.vercel',
+]);
+
+/**
+ * Validate version/metadata consistency across project files.
+ * @param {string} projectDir - Project root directory
+ * @param {object} config - DocGuard config
+ * @returns {{ errors: string[], warnings: string[], passed: number, total: number }}
+ */
+export function validateMetadataSync(projectDir, config) {
+  const warnings = [];
+  let passed = 0;
+  let total = 0;
+
+  // ── Get source of truth: package.json version ──
+  const pkgPath = resolve(projectDir, 'package.json');
+  if (!existsSync(pkgPath)) {
+    return { errors: [], warnings, passed: 0, total: 0 };
+  }
+
+  let pkg;
+  try { pkg = JSON.parse(readFileSync(pkgPath, 'utf-8')); } catch { return { errors: [], warnings, passed: 0, total: 0 }; }
+  const currentVersion = pkg.version;
+  if (!currentVersion) return { errors: [], warnings, passed: 0, total: 0 };
+
+  // Parse into components for smart comparison
+  const vParts = currentVersion.split('.');
+  const major = parseInt(vParts[0], 10);
+  const minor = parseInt(vParts[1], 10);
+
+  // ── Check 1: extension.yml version sync ──
+  const extFiles = findExtensionYmls(projectDir);
+  for (const extFile of extFiles) {
+    total++;
+    const relPath = relative(projectDir, extFile);
+    try {
+      const content = readFileSync(extFile, 'utf-8');
+      const versionMatch = content.match(/version:\s*["']?(\d+\.\d+\.\d+)["']?/);
+      if (versionMatch) {
+        if (versionMatch[1] !== currentVersion) {
+          warnings.push(
+            `${relPath} has version "${versionMatch[1]}" but package.json is "${currentVersion}"`
+          );
+        } else {
+          passed++;
+        }
+      }
+    } catch { /* skip unreadable */ }
+  }
+
+  // ── Check 2: Version references in markdown files ──
+  const isIgnored = loadIgnorePatterns(projectDir);
+  const mdFiles = findMarkdownFiles(projectDir);
+  // Version patterns to find: v0.7.2, @0.7.2, /v0.7.2/, docguard-cli@0.7.2
+  const versionRegex = /(?:v|@|\/v?)(\d+\.\d+\.\d+)/g;
+
+  for (const mdFile of mdFiles) {
+    const relPath = relative(projectDir, mdFile);
+    // Skip CHANGELOG.md and DRIFT-LOG.md — these are historical by definition
+    const baseName = relPath.toLowerCase();
+    if (baseName.includes('changelog') || baseName.includes('drift-log')) continue;
+    // Skip files matched by .docguardignore
+    if (isIgnored(relPath)) continue;
+
+    let content;
+    try { content = readFileSync(mdFile, 'utf-8'); } catch { continue; }
+
+    // Only flag version references in actionable contexts:
+    // - URLs (download, install, archive links)
+    // - version: declarations (YAML-style)
+    // - npm install / npx commands
+    // - Badge URLs
+    // NOT in prose text like "In v0.2.0 we added..." or roadmap discussions
+    const actionablePatterns = [
+      // URLs with version: /v0.7.2/, /tags/v0.7.2, @0.7.2
+      /(?:archive|tags|releases|download)\/v?(\d+\.\d+\.\d+)/g,
+      // npm install/npx commands: docguard-cli@0.7.2
+      /@(\d+\.\d+\.\d+)/g,
+      // YAML-style: version: "0.7.2" or version: 0.7.2
+      /version:\s*["']?(\d+\.\d+\.\d+)["']?/g,
+    ];
+
+    for (const pattern of actionablePatterns) {
+      pattern.lastIndex = 0;
+      let match;
+      while ((match = pattern.exec(content)) !== null) {
+        const foundVersion = match[1];
+        const fParts = foundVersion.split('.');
+        const fMajor = parseInt(fParts[0], 10);
+        const fMinor = parseInt(fParts[1], 10);
+
+        // Only flag if same major but older minor (same package, stale ref)
+        if (fMajor === major && fMinor < minor && foundVersion !== currentVersion) {
+          total++;
+          warnings.push(
+            `${relPath} references "v${foundVersion}" in an actionable context (URL/install/declaration) but current version is "${currentVersion}"`
+          );
+        } else if (fMajor === major && fMinor === minor && foundVersion === currentVersion) {
+          total++;
+          passed++;
+        }
+      }
+    }
+  }
+
+  return { errors: [], warnings, passed, total };
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function findExtensionYmls(dir) {
+  const results = [];
+  const extDir = resolve(dir, 'extensions');
+  if (existsSync(extDir)) {
+    walkFiles(extDir, (f) => {
+      if (f.endsWith('extension.yml') || f.endsWith('extension.yaml')) {
+        results.push(f);
+      }
+    });
+  }
+  // Also check root
+  const rootExt = resolve(dir, 'extension.yml');
+  if (existsSync(rootExt)) results.push(rootExt);
+  return results;
+}
+
+function findMarkdownFiles(dir) {
+  const seen = new Set();
+  const mdFiles = [];
+  const searchDirs = [
+    dir,
+    resolve(dir, 'docs-canonical'),
+    resolve(dir, 'extensions'),
+  ];
+
+  for (const searchDir of searchDirs) {
+    if (!existsSync(searchDir)) continue;
+    walkFiles(searchDir, (f) => {
+      if (f.endsWith('.md') && !seen.has(f)) {
+        seen.add(f);
+        mdFiles.push(f);
+      }
+    });
+  }
+
+  return mdFiles;
+}
+
+function walkFiles(dir, callback) {
+  if (!existsSync(dir)) return;
+  let entries;
+  try { entries = readdirSync(dir); } catch { return; }
+
+  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()) {
+        walkFiles(fullPath, callback);
+      } else if (stat.isFile()) {
+        callback(fullPath);
+      }
+    } catch { /* skip */ }
+  }
+}

package/cli/validators/metrics-consistency.mjs

@@ -0,0 +1,166 @@
+/**
+ * Metrics Consistency Validator — Detects stale hardcoded numbers in docs.
+ *
+ * Scans all .md files for patterns like "N checks", "N validators", "N tests"
+ * and compares against actual values from guard results and package.json.
+ * Returns warnings for mismatches.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { resolve, join, relative } from 'node:path';
+import { loadIgnorePatterns } from '../shared.mjs';
+
+const IGNORE_DIRS = new Set([
+  'node_modules', '.git', '.next', 'dist', 'build', 'coverage',
+  '.cache', '__pycache__', '.venv', 'vendor', '.turbo', '.vercel',
+]);
+
+/**
+ * Validate metrics consistency across documentation.
+ * @param {string} projectDir - Project root directory
+ * @param {object} config - DocGuard config
+ * @param {object} [guardResults] - Results from runGuardInternal (optional)
+ * @returns {{ errors: string[], warnings: string[], passed: number, total: number }}
+ */
+export function validateMetricsConsistency(projectDir, config, guardResults) {
+  const warnings = [];
+  let passed = 0;
+  let total = 0;
+
+  // ── Collect actual metrics ──
+  const actuals = {};
+
+  // Guard check count (from guard results if available)
+  if (guardResults && Array.isArray(guardResults)) {
+    const totalChecks = guardResults.reduce((sum, r) => {
+      if (r.status === 'skipped') return sum;
+      return sum + (r.total || 0);
+    }, 0);
+    const validatorCount = guardResults.filter(r => r.status !== 'skipped').length;
+
+    actuals.checks = totalChecks;
+    actuals.validators = validatorCount;
+  }
+
+  // Test count — count test files on disk
+  const testFiles = findTestFiles(projectDir);
+  if (testFiles.length > 0) {
+    actuals.tests = testFiles.length;
+  }
+
+  // If no actuals to compare, skip
+  if (Object.keys(actuals).length === 0) {
+    return { errors: [], warnings, passed: 0, total: 0 };
+  }
+
+  // ── Scan markdown files for hardcoded numbers ──
+  const isIgnored = loadIgnorePatterns(projectDir);
+  const mdFiles = findMarkdownFiles(projectDir);
+  // Patterns must match standalone number references, not ratio-style "8/8 checks"
+  const patterns = [
+    { key: 'checks', regex: /(?<!\d\/)\b(\d{2,})\s+(?:automated\s+)?checks?\b/gi, label: 'checks' },
+    { key: 'validators', regex: /(?<!\d\/)\b(\d{2,})\s+validators?\b/gi, label: 'validators' },
+  ];
+
+  for (const mdFile of mdFiles) {
+    const relPath = relative(projectDir, mdFile);
+    // Skip changelog (historical numbers are fine by definition)
+    if (relPath.toLowerCase().includes('changelog')) continue;
+    // Skip files matched by .docguardignore
+    if (isIgnored(relPath)) continue;
+
+    let content;
+    try { content = readFileSync(mdFile, 'utf-8'); } catch { continue; }
+
+    for (const { key, regex, label } of patterns) {
+      if (actuals[key] === undefined) continue;
+
+      regex.lastIndex = 0;
+      let match;
+      while ((match = regex.exec(content)) !== null) {
+        total++;
+        const found = parseInt(match[1], 10);
+        if (found !== actuals[key] && found > 0) {
+          warnings.push(
+            `${relPath} says "${found} ${label}" but actual count is ${actuals[key]}. Update the doc or run \`docguard generate --force\``
+          );
+        } else {
+          passed++;
+        }
+      }
+    }
+  }
+
+  return { errors: [], warnings, passed, total };
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function findTestFiles(dir) {
+  const tests = [];
+  const testDirs = ['tests', 'test', '__tests__', 'spec', 'e2e'];
+
+  // Top-level test dirs
+  for (const td of testDirs) {
+    const fullDir = resolve(dir, td);
+    if (existsSync(fullDir)) {
+      walkFiles(fullDir, (f) => {
+        if (/\.(test|spec)\.[^.]+$/.test(f)) tests.push(f);
+      });
+    }
+  }
+
+  // Co-located tests in src/
+  const srcDir = resolve(dir, 'src');
+  if (existsSync(srcDir)) {
+    walkFiles(srcDir, (f) => {
+      if (/\.(test|spec)\.[^.]+$/.test(f) || f.includes('__tests__')) {
+        if (!tests.includes(f)) tests.push(f);
+      }
+    });
+  }
+
+  return tests;
+}
+
+function findMarkdownFiles(dir) {
+  const seen = new Set();
+  const mdFiles = [];
+  // Check root, docs-canonical, and extensions
+  const searchDirs = [
+    dir,
+    resolve(dir, 'docs-canonical'),
+    resolve(dir, 'extensions'),
+  ];
+
+  for (const searchDir of searchDirs) {
+    if (!existsSync(searchDir)) continue;
+    walkFiles(searchDir, (f) => {
+      if (f.endsWith('.md') && !seen.has(f)) {
+        seen.add(f);
+        mdFiles.push(f);
+      }
+    });
+  }
+
+  return mdFiles;
+}
+
+function walkFiles(dir, callback) {
+  if (!existsSync(dir)) return;
+  let entries;
+  try { entries = readdirSync(dir); } catch { return; }
+
+  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()) {
+        walkFiles(fullPath, callback);
+      } else if (stat.isFile()) {
+        callback(fullPath);
+      }
+    } catch { /* skip */ }
+  }
+}

package/package.json

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