docguard-cli 0.8.0 → 0.9.0

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,23 +223,33 @@ $ npx docguard-cli guard
 
 ---
 
-## 9 Validators
+## 19 Validators
 
 | # | Validator | What It Checks | Default |
 |---|-----------|---------------|---------| 
 | 1 | **Structure** | Required CDD files exist | ✅ On |
 | 2 | **Doc Sections** | Canonical docs have required sections | ✅ On |
-| 3 | **Docs-Sync** | Routes/services referenced in docs | ✅ On |
+| 3 | **Docs-Sync** | Routes/services referenced in docs + OpenAPI cross-check | ✅ On |
 | 4 | **Drift** | `// DRIFT:` comments logged in DRIFT-LOG.md | ✅ On |
 | 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 + V-Model requirement IDs | ✅ 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 | **Doc-Quality** | Writing quality (readability, passive voice, atomicity) | ✅ On |
+| 17 | **TODO-Tracking** | Untracked TODOs/FIXMEs and skipped tests | ✅ On |
+| 18 | **Schema-Sync** | Database models documented in DATA-MODEL.md | ✅ On |
+| 19 | **Spec-Kit** | GitHub Spec Kit artifact detection and CDD mapping | ✅ On |
 
 ---
 
-## 16 Templates
+## 18 Templates
 
 Every template includes professional metadata: `docguard:version`, `docguard:status`, badges, and revision history.
 
@@ -232,6 +263,7 @@ Every template includes professional metadata: `docguard:version`, `docguard:sta
 | DEPLOYMENT.md | Canonical | Infrastructure, CI/CD, DNS |
 | ADR.md | Canonical | Architecture Decision Records |
 | ROADMAP.md | Canonical | Project phases, feature tracking |
+| REQUIREMENTS.md | Canonical | Requirement IDs, V-Model traceability |
 | KNOWN-GOTCHAS.md | Implementation | Symptom/gotcha/fix entries |
 | TROUBLESHOOTING.md | Implementation | Error diagnosis guides |
 | RUNBOOKS.md | Implementation | Operational procedures |
@@ -240,6 +272,7 @@ Every template includes professional metadata: `docguard:version`, `docguard:sta
 | AGENTS.md | Agent | AI agent behavior rules |
 | CHANGELOG.md | Tracking | Change log |
 | DRIFT-LOG.md | Tracking | Deviation tracking |
+| llms.txt | Generated | AI-friendly project summary (llmstxt.org) |
 
 ---
 
@@ -252,7 +285,8 @@ your-project/
 │   ├── DATA-MODEL.md            # Database schemas, entity relationships
 │   ├── SECURITY.md              # Auth, permissions, secrets
 │   ├── TEST-SPEC.md             # Required tests, coverage rules
-│   └── ENVIRONMENT.md           # Environment variables, setup
+│   ├── ENVIRONMENT.md           # Environment variables, setup
+│   └── REQUIREMENTS.md          # Requirement IDs, V-Model traceability
 │
 ├── docs-implementation/         # Current state (optional)
 │   ├── KNOWN-GOTCHAS.md         # Lessons learned
@@ -263,6 +297,7 @@ your-project/
 ├── AGENTS.md                    # AI agent behavior rules
 ├── CHANGELOG.md                 # Change tracking
 ├── DRIFT-LOG.md                 # Documented deviations
+├── llms.txt                     # AI-friendly project summary
 └── .docguard.json              # DocGuard configuration
 ```
 

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,13 @@ 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';
+import { validateDocQuality } from '../validators/doc-quality.mjs';
+import { validateTodoTracking } from '../validators/todo-tracking.mjs';
+import { validateSchemaSync } from '../validators/schema-sync.mjs';
+import { validateSpecKitIntegration } from '../scanners/speckit.mjs';
 
 /**
  * Internal guard — returns structured data, no console output, no process.exit.
@@ -52,6 +59,13 @@ 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) },
+    { key: 'docQuality', name: 'Doc-Quality', fn: () => validateDocQuality(projectDir, config) },
+    { key: 'todoTracking', name: 'TODO-Tracking', fn: () => validateTodoTracking(projectDir, config) },
+    { key: 'schemaSync', name: 'Schema-Sync', fn: () => validateSchemaSync(projectDir, config) },
+    { key: 'specKit', name: 'Spec-Kit', fn: () => validateSpecKitIntegration(projectDir, config) },
+    // Metrics-Consistency runs post-loop (needs guard results)
   ];
 
   for (const { key, name, fn } of validatorMap) {
@@ -84,6 +98,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/commands/llms.mjs

@@ -0,0 +1,159 @@
+/**
+ * llms Command — Generate llms.txt from canonical documentation
+ *
+ * llms.txt is a proposed standard (Jeremy Howard, Answer.AI, 2024) for providing
+ * AI-friendly content summaries at a project root. This command generates it
+ * from existing canonical docs.
+ *
+ * Usage:
+ *   docguard llms                 — Generate/regenerate llms.txt
+ *   docguard llms --stdout        — Print to stdout instead of file
+ *
+ * Integration:
+ *   - `docguard init` includes llms.txt in standard template
+ *   - `docguard generate` auto-regenerates llms.txt
+ *   - `docguard guard` validates llms.txt exists and is current
+ */
+
+import { existsSync, readFileSync, writeFileSync, readdirSync } from 'node:fs';
+import { resolve, join, basename } from 'node:path';
+import { c } from '../shared.mjs';
+
+// ──── Doc descriptions for llms.txt ────
+const DOC_DESCRIPTIONS = {
+  'ARCHITECTURE.md': 'System architecture, component boundaries, and tech stack',
+  'DATA-MODEL.md': 'Database schemas, entity relationships, and data flow',
+  'SECURITY.md': 'Authentication, authorization, secrets management, and security policies',
+  'TEST-SPEC.md': 'Test coverage requirements, testing strategy, and quality rules',
+  'ENVIRONMENT.md': 'Setup instructions, environment variables, and prerequisites',
+  'API-REFERENCE.md': 'API endpoints, request/response formats, and integration docs',
+  'DEPLOYMENT.md': 'Deployment procedures, CI/CD pipelines, and infrastructure',
+  'MONITORING.md': 'Observability, logging, alerting, and health checks',
+  'PERFORMANCE.md': 'Performance requirements, benchmarks, and optimization',
+  'ACCESSIBILITY.md': 'WCAG compliance, accessibility standards, and testing',
+};
+
+const OPTIONAL_DOCS = {
+  'DRIFT-LOG.md': 'Known deviations from canonical documentation',
+  'CHANGELOG.md': 'Version history and release notes',
+  'ROADMAP.md': 'Planned features and development roadmap',
+  'REQUIREMENTS.md': 'Tracked requirements with traceability IDs',
+  'AGENTS.md': 'AI agent behavior rules and workflow instructions',
+  'CURRENT-STATE.md': 'Current implementation status and known issues',
+};
+
+/**
+ * Generate llms.txt content from project docs.
+ */
+export function generateLlmsTxt(projectDir, config) {
+  const lines = [];
+
+  // ── Header ──
+  const projectName = config.projectName || basename(projectDir);
+  const description = getProjectDescription(projectDir);
+
+  lines.push(`# ${projectName}`);
+  if (description) {
+    lines.push(`> ${description}`);
+  }
+  lines.push('');
+
+  // ── Canonical Docs ──
+  const docsDir = resolve(projectDir, 'docs-canonical');
+  const existingDocs = [];
+
+  if (existsSync(docsDir)) {
+    try {
+      const entries = readdirSync(docsDir).filter(f => f.endsWith('.md')).sort();
+      for (const entry of entries) {
+        const desc = DOC_DESCRIPTIONS[entry] || `${entry.replace('.md', '')} documentation`;
+        existingDocs.push({ path: `docs-canonical/${entry}`, name: entry, desc });
+      }
+    } catch { /* ignore */ }
+  }
+
+  if (existingDocs.length > 0) {
+    lines.push('## Docs');
+    lines.push('');
+    for (const doc of existingDocs) {
+      lines.push(`- [${doc.name.replace('.md', '')}](${doc.path}): ${doc.desc}`);
+    }
+    lines.push('');
+  }
+
+  // ── Optional Docs ──
+  const optionalFound = [];
+  for (const [file, desc] of Object.entries(OPTIONAL_DOCS)) {
+    if (existsSync(resolve(projectDir, file))) {
+      optionalFound.push({ path: file, name: file, desc });
+    }
+  }
+
+  if (optionalFound.length > 0) {
+    lines.push('## Optional');
+    lines.push('');
+    for (const doc of optionalFound) {
+      lines.push(`- [${doc.name.replace('.md', '')}](${doc.path}): ${doc.desc}`);
+    }
+    lines.push('');
+  }
+
+  // ── Footer ──
+  lines.push('---');
+  lines.push(`Generated by DocGuard v${config.version || 'unknown'} | [docguard-cli](https://www.npmjs.com/package/docguard-cli)`);
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+/**
+ * Get project description from package.json or ARCHITECTURE.md.
+ */
+function getProjectDescription(projectDir) {
+  // Try package.json first
+  const pkgPath = resolve(projectDir, 'package.json');
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+      if (pkg.description) return pkg.description;
+    } catch { /* ignore */ }
+  }
+
+  // Try ARCHITECTURE.md first line after the header
+  const archPath = resolve(projectDir, 'docs-canonical', 'ARCHITECTURE.md');
+  if (existsSync(archPath)) {
+    try {
+      const content = readFileSync(archPath, 'utf-8');
+      const lines = content.split('\n');
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed && !trimmed.startsWith('#') && !trimmed.startsWith('|') && !trimmed.startsWith('-')) {
+          return trimmed.substring(0, 200);
+        }
+      }
+    } catch { /* ignore */ }
+  }
+
+  return null;
+}
+
+/**
+ * Public command — generate llms.txt file.
+ */
+export function runLlms(projectDir, config, flags) {
+  const content = generateLlmsTxt(projectDir, config);
+
+  if (flags.stdout) {
+    console.log(content);
+    return;
+  }
+
+  const outputPath = resolve(projectDir, 'llms.txt');
+  writeFileSync(outputPath, content, 'utf-8');
+
+  console.log(`${c.bold}📄 DocGuard llms.txt Generator${c.reset}`);
+  console.log(`${c.green}✅ Generated ${outputPath}${c.reset}`);
+  console.log(`${c.dim}   Standard: llms.txt (Jeremy Howard, Answer.AI, 2024)${c.reset}`);
+  console.log(`${c.dim}   DocGuard keeps this in sync with your canonical docs.${c.reset}`);
+  console.log('');
+}

package/cli/commands/score.mjs

@@ -131,6 +131,30 @@ export function runScore(projectDir, config, flags) {
     console.log(`  ${c.dim}Methodology: CJE multi-signal composite (Lopez et al., TRACE, IEEE TMLCN 2026)${c.reset}\n`);
   }
 
+  // ── ALCOA+ Compliance Scoring ──
+  // Maps existing validators to the 9 ALCOA+ attributes (FDA data integrity framework)
+  // Always shown — gives enterprise positioning value
+  const alcoa = computeAlcoaCompliance(projectDir, config, scores);
+
+  console.log(`  ${c.bold}🏛️  ALCOA+ Compliance${c.reset} ${c.dim}(FDA Data Integrity Framework)${c.reset}`);
+  console.log(`  ${c.dim}─────────────────────────────────${c.reset}`);
+
+  for (const attr of alcoa.attributes) {
+    const icon = attr.met ? `${c.green}✅` : `${c.yellow}⚠️`;
+    const status = attr.met ? `${c.green}${attr.evidence}` : `${c.yellow}${attr.gap}`;
+    console.log(`  ${icon} ${attr.name.padEnd(16)}${c.reset} — ${status}${c.reset}`);
+    if (!attr.met && attr.fix) {
+      console.log(`  ${c.dim}     Fix: ${attr.fix}${c.reset}`);
+    }
+  }
+
+  const alcoaColor = alcoa.score >= 78 ? c.green : alcoa.score >= 56 ? c.yellow : c.red;
+  console.log(`\n  ${alcoaColor}${c.bold}ALCOA+ Score: ${alcoa.score}% (${alcoa.met}/${alcoa.total} attributes)${c.reset}`);
+  if (alcoa.met < alcoa.total) {
+    console.log(`  ${c.dim}${alcoa.total - alcoa.met} action(s) needed for full compliance${c.reset}`);
+  }
+  console.log('');
+
   // 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}`;
@@ -146,6 +170,144 @@ export function runScoreInternal(projectDir, config) {
   return { score: totalScore, grade, categories: scores };
 }
 
+/**
+ * ALCOA+ Compliance Scoring
+ *
+ * Maps DocGuard's existing validators to the 9 ALCOA+ attributes
+ * (FDA 21 CFR Part 11 / EMA Annex 11 data integrity framework).
+ *
+ * ALCOA+ = Attributable, Legible, Contemporaneous, Original, Accurate
+ *        + Complete, Consistent, Enduring, Available
+ *
+ * Reference: WHO Technical Report Series, No. 996, 2016, Annex 5
+ */
+function computeAlcoaCompliance(projectDir, config, scores) {
+  const attributes = [];
+
+  // 1. Attributable — Can we trace who wrote/reviewed docs?
+  const hasGit = existsSync(resolve(projectDir, '.git'));
+  const docsDir = resolve(projectDir, 'docs-canonical');
+  let hasReviewedMeta = false;
+  if (existsSync(docsDir)) {
+    try {
+      const docs = readdirSync(docsDir).filter(f => f.endsWith('.md'));
+      for (const doc of docs) {
+        const content = readFileSync(join(docsDir, doc), 'utf-8');
+        if (content.includes('docguard:last-reviewed') || content.includes('last-reviewed')) {
+          hasReviewedMeta = true;
+          break;
+        }
+      }
+    } catch { /* ignore */ }
+  }
+  attributes.push({
+    name: 'Attributable',
+    met: hasGit,
+    evidence: hasGit ? `Git authorship found${hasReviewedMeta ? ', review metadata present' : ''}` : null,
+    gap: !hasGit ? 'No version control found' : null,
+    fix: !hasGit ? 'Initialize git repository: git init' : null,
+  });
+
+  // 2. Legible — Are docs readable and well-written?
+  const legible = scores.docQuality >= 60;
+  attributes.push({
+    name: 'Legible',
+    met: legible,
+    evidence: legible ? `Doc quality score: ${scores.docQuality}% (readable)` : null,
+    gap: !legible ? `Doc quality score: ${scores.docQuality}% (needs improvement)` : null,
+    fix: !legible ? 'Run docguard diagnose for specific readability improvements' : null,
+  });
+
+  // 3. Contemporaneous — Are docs kept current?
+  let freshnessMet = true;
+  if (existsSync(docsDir)) {
+    try {
+      const docs = readdirSync(docsDir).filter(f => f.endsWith('.md'));
+      for (const doc of docs) {
+        const stat_ = statSync(join(docsDir, doc));
+        const daysSinceModified = (Date.now() - stat_.mtimeMs) / (1000 * 60 * 60 * 24);
+        if (daysSinceModified > 30) {
+          freshnessMet = false;
+          break;
+        }
+      }
+    } catch { /* ignore */ }
+  }
+  attributes.push({
+    name: 'Contemporaneous',
+    met: freshnessMet,
+    evidence: freshnessMet ? 'All docs updated within 30 days' : null,
+    gap: !freshnessMet ? 'Some docs not updated in 30+ days' : null,
+    fix: !freshnessMet ? 'Review and update stale docs, add <!-- docguard:last-reviewed YYYY-MM-DD -->' : null,
+  });
+
+  // 4. Original — Are docs stored as originals (not copies)?
+  const hasCanonicalDir = existsSync(docsDir);
+  attributes.push({
+    name: 'Original',
+    met: hasCanonicalDir,
+    evidence: hasCanonicalDir ? 'Canonical docs present as markdown originals' : null,
+    gap: !hasCanonicalDir ? 'No docs-canonical/ directory found' : null,
+    fix: !hasCanonicalDir ? 'Run docguard init to create canonical documentation' : null,
+  });
+
+  // 5. Accurate — Do docs match the code?
+  const accurate = scores.drift >= 80 && scores.docQuality >= 50;
+  attributes.push({
+    name: 'Accurate',
+    met: accurate,
+    evidence: accurate ? `Drift: ${scores.drift}%, doc quality: ${scores.docQuality}%` : null,
+    gap: !accurate ? `Drift: ${scores.drift}%, doc quality: ${scores.docQuality}% — docs may be inaccurate` : null,
+    fix: !accurate ? 'Run docguard diagnose to find doc/code mismatches' : null,
+  });
+
+  // 6. Complete — Are all required docs present?
+  const complete = scores.structure >= 80;
+  attributes.push({
+    name: 'Complete',
+    met: complete,
+    evidence: complete ? `Structure score: ${scores.structure}% — required docs present` : null,
+    gap: !complete ? `Structure score: ${scores.structure}% — missing required docs` : null,
+    fix: !complete ? 'Run docguard init to create missing documentation' : null,
+  });
+
+  // 7. Consistent — Are versions, metadata, and references in sync?
+  const consistent = scores.changelog >= 50;
+  attributes.push({
+    name: 'Consistent',
+    met: consistent,
+    evidence: consistent ? `Changelog: ${scores.changelog}% — versions tracked` : null,
+    gap: !consistent ? `Changelog: ${scores.changelog}% — version inconsistencies` : null,
+    fix: !consistent ? 'Update CHANGELOG.md with [Unreleased] section and version headers' : null,
+  });
+
+  // 8. Enduring — Will docs survive infrastructure changes?
+  const enduring = hasGit;
+  attributes.push({
+    name: 'Enduring',
+    met: enduring,
+    evidence: enduring ? 'Git-backed repository with version history' : null,
+    gap: !enduring ? 'No version control — docs could be lost' : null,
+    fix: !enduring ? 'Initialize git repository: git init' : null,
+  });
+
+  // 9. Available — Can anyone access the docs?
+  const available = hasCanonicalDir;
+  attributes.push({
+    name: 'Available',
+    met: available,
+    evidence: available ? 'Docs in plain markdown — no vendor lock-in, universally accessible' : null,
+    gap: !available ? 'No docs directory found' : null,
+    fix: !available ? 'Run docguard init to create accessible documentation' : null,
+  });
+
+  const met = attributes.filter(a => a.met).length;
+  const total = attributes.length;
+  const score = Math.round((met / total) * 100);
+
+  return { attributes, met, total, score };
+}
+
 function calcAllScores(projectDir, config) {
   const scores = {};
   const details = {}; // Per-category failure details for actionable suggestions

package/cli/docguard.mjs

@@ -37,6 +37,7 @@ import { runWatch } from './commands/watch.mjs';
 import { runDiagnose } from './commands/diagnose.mjs';
 import { runPublish } from './commands/publish.mjs';
 import { runTrace } from './commands/trace.mjs';
+import { runLlms } from './commands/llms.mjs';
 
 // ── Shared constants (imported to break circular dependencies) ──────────
 import { c, PROFILES } from './shared.mjs';
@@ -354,6 +355,8 @@ async function main() {
       flags.signals = true;
     } else if (args[i] === '--debate') {
       flags.debate = true;
+    } else if (args[i] === '--stdout') {
+      flags.stdout = true;
     }
   }
 
@@ -427,6 +430,9 @@ async function main() {
     case 'traceability':
       runTrace(projectDir, config, flags);
       break;
+    case 'llms':
+      runLlms(projectDir, config, flags);
+      break;
     default:
       console.error(`${c.red}Unknown command: ${command}${c.reset}`);
       console.log(`Run ${c.cyan}docguard --help${c.reset} for usage.`);