docguard-cli 0.8.2 → 0.9.1

package/README.md

@@ -223,13 +223,13 @@ $ npx docguard-cli guard
 
 ---
 
-## 14 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 |
@@ -237,16 +237,19 @@ $ npx docguard-cli guard
 | 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 |
+| 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 | **Docs-Sync** | Source files have matching doc entries | ✅ 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.
 
@@ -260,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 |
@@ -268,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) |
 
 ---
 
@@ -280,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
@@ -291,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/guard.mjs

@@ -22,6 +22,10 @@ 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.
@@ -57,6 +61,10 @@ export function runGuardInternal(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)
   ];
 

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
@@ -243,38 +405,77 @@ function calcDocQualityScore(dir, config) {
 function calcTestingScore(dir, config) {
   let score = 0;
 
-  // Check test directory exists
+  // ── Check 1: Test files exist (40 pts) ──
+  // Check top-level test directories
   const testDirs = ['tests', 'test', '__tests__', 'spec', 'e2e'];
-  const hasTestDir = testDirs.some(d => existsSync(resolve(dir, d)));
-  if (hasTestDir) score += 40;
+  const hasTopLevelTestDir = testDirs.some(d => existsSync(resolve(dir, d)));
+
+  // Check co-located tests: src/**/__tests__/ and src/**/*.test.* / src/**/*.spec.*
+  let hasColocatedTests = false;
+  if (!hasTopLevelTestDir) {
+    hasColocatedTests = findColocatedTests(dir);
+  }
 
-  // Check test spec exists
+  // Check vitest/jest config for custom test patterns
+  let hasConfigTests = false;
+  if (!hasTopLevelTestDir && !hasColocatedTests) {
+    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');
+          const includeMatch = cfgContent.match(/include\s*:\s*\[([^\]]+)\]/);
+          if (includeMatch) {
+            const patterns = includeMatch[1].match(/['"]([^'"]+)['"]/g);
+            if (patterns) {
+              for (const p of patterns) {
+                const pattern = p.replace(/['"]|\s/g, '');
+                const rootDir = pattern.split('/')[0];
+                if (rootDir && rootDir !== '**' && rootDir !== '*') {
+                  const fullDir = resolve(dir, rootDir);
+                  if (existsSync(fullDir)) {
+                    hasConfigTests = true;
+                    break;
+                  }
+                }
+              }
+            }
+          }
+        } catch { /* config parse may fail */ }
+        break;
+      }
+    }
+  }
+
+  if (hasTopLevelTestDir || hasColocatedTests || hasConfigTests) score += 40;
+
+  // ── Check 2: TEST-SPEC.md exists (30 pts) ──
   if (existsSync(resolve(dir, 'docs-canonical/TEST-SPEC.md'))) score += 30;
 
-  // 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)));
+  // ── Check 3: Test config or built-in runner (15 pts) ──
+  const testConfigs2 = ['jest.config.js', 'jest.config.ts', 'vitest.config.ts', 'vitest.config.js', 'pytest.ini', 'setup.cfg', '.mocharc.yml'];
+  const hasTestConfig = testConfigs2.some(f => existsSync(resolve(dir, f)));
 
   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
+      score += 15;
     } 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
+          score += 15;
         }
       } catch { /* skip */ }
     }
   }
 
-  // Check for CI test step
+  // ── Check 4: CI test step (15 pts) ──
   const ciFiles = ['.github/workflows/ci.yml', '.github/workflows/test.yml'];
   const hasCITest = ciFiles.some(f => existsSync(resolve(dir, f)));
   if (hasCITest) score += 15;
@@ -282,6 +483,53 @@ function calcTestingScore(dir, config) {
   return Math.min(100, score);
 }
 
+/**
+ * Scan common source directories for co-located test files.
+ * Checks: __tests__/ dirs, *.test.*, *.spec.* anywhere in src/, app/, lib/, packages/
+ * Also checks root-level for *.test.* files.
+ */
+function findColocatedTests(dir) {
+  // Scan these common source roots for co-located tests
+  const sourceRoots = ['src', 'app', 'lib', 'packages', 'modules'];
+  const ignoreSet = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'coverage', '.cache']);
+
+  for (const root of sourceRoots) {
+    const rootDir = resolve(dir, root);
+    if (!existsSync(rootDir)) continue;
+    if (walkForTests(rootDir, ignoreSet)) return true;
+  }
+
+  // Also check root-level for *.test.* files (some projects put tests at root)
+  try {
+    const rootEntries = readdirSync(dir);
+    for (const entry of rootEntries) {
+      if (/\.(test|spec)\.[^.]+$/.test(entry)) return true;
+    }
+  } catch { /* ignore */ }
+
+  return false;
+}
+
+/** Recursively walk a dir looking for test files. Returns true as soon as one is found. */
+function walkForTests(d, ignoreSet) {
+  let entries;
+  try { entries = readdirSync(d); } catch { return false; }
+  for (const entry of entries) {
+    if (ignoreSet.has(entry) || entry.startsWith('.')) continue;
+    const full = join(d, entry);
+    try {
+      const s = statSync(full);
+      if (s.isDirectory()) {
+        if (entry === '__tests__' || entry === '__test__') return true;
+        if (walkForTests(full, ignoreSet)) return true;
+      } else {
+        if (/\.(test|spec)\.[^.]+$/.test(entry)) return true;
+      }
+    } catch { continue; }
+  }
+  return false;
+}
+
 function calcSecurityScore(dir, config) {
   let score = 0;
   const ptc = config.projectTypeConfig || {};

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.`);