docguard-cli 0.5.2 → 0.7.0

package/cli/commands/guard.mjs

@@ -52,7 +52,7 @@ export function runGuardInternal(projectDir, config) {
 
   for (const { key, name, fn } of validatorMap) {
     if (validators[key] === false) {
-      results.push({ name, key, status: 'skipped', errors: [], warnings: [], passed: 0, total: 0 });
+      results.push({ name, key, status: 'skipped', quality: null, errors: [], warnings: [], passed: 0, total: 0 });
       continue;
     }
 
@@ -61,9 +61,22 @@ export function runGuardInternal(projectDir, config) {
       const hasErrors = result.errors.length > 0;
       const hasWarnings = result.warnings.length > 0;
       const status = hasErrors ? 'fail' : hasWarnings ? 'warn' : 'pass';
-      results.push({ ...result, name, key, status });
+
+      // Quality label: HIGH/MEDIUM/LOW (inspired by CJE quality stratification, Lopez et al. TRACE 2026)
+      let quality;
+      if (hasErrors) {
+        quality = 'LOW';
+      } else if (hasWarnings) {
+        quality = 'MEDIUM';
+      } else {
+        // Pass — check coverage ratio for HIGH vs MEDIUM
+        const ratio = result.total > 0 ? result.passed / result.total : 1;
+        quality = ratio >= 0.9 ? 'HIGH' : 'MEDIUM';
+      }
+
+      results.push({ ...result, name, key, status, quality });
     } catch (err) {
-      results.push({ name, key, status: 'fail', errors: [err.message], warnings: [], passed: 0, total: 1 });
+      results.push({ name, key, status: 'fail', quality: 'LOW', errors: [err.message], warnings: [], passed: 0, total: 1 });
     }
   }
 
@@ -114,12 +127,16 @@ export function runGuard(projectDir, config, flags) {
       continue;
     }
 
+    // Quality label badge
+    const qColor = v.quality === 'HIGH' ? c.green : v.quality === 'MEDIUM' ? c.yellow : c.red;
+    const qBadge = `${qColor}[${v.quality}]${c.reset}`;
+
     if (v.status === 'pass') {
-      console.log(`  ${c.green}✅ ${v.name}${c.reset}${c.dim}      ${v.passed}/${v.total} checks passed${c.reset}`);
+      console.log(`  ${c.green}✅ ${v.name}${c.reset} ${qBadge}${c.dim}  ${v.passed}/${v.total} checks passed${c.reset}`);
     } else if (v.status === 'fail') {
-      console.log(`  ${c.red}❌ ${v.name}${c.reset}${c.dim}      ${v.passed}/${v.total} checks passed${c.reset}`);
+      console.log(`  ${c.red}❌ ${v.name}${c.reset} ${qBadge}${c.dim}  ${v.passed}/${v.total} checks passed${c.reset}`);
     } else {
-      console.log(`  ${c.yellow}⚠️  ${v.name}${c.reset}${c.dim}      ${v.passed}/${v.total} checks passed${c.reset}`);
+      console.log(`  ${c.yellow}⚠️  ${v.name}${c.reset} ${qBadge}${c.dim}  ${v.passed}/${v.total} checks passed${c.reset}`);
     }
 
     if (flags.verbose || v.status === 'fail') {

package/cli/commands/publish.mjs

@@ -0,0 +1,246 @@
+/**
+ * DocGuard Publish Command
+ * Scaffolds documentation publishing config for external doc platforms.
+ * Currently supports: Mintlify
+ * 
+ * Usage: docguard publish --platform mintlify [--dir .]
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { resolve, basename } from 'node:path';
+import { c } from '../docguard.mjs';
+
+const SUPPORTED_PLATFORMS = ['mintlify'];
+
+export function runPublish(projectDir, config, flags) {
+  const platform = flags.platform || 'mintlify';
+
+  if (!SUPPORTED_PLATFORMS.includes(platform)) {
+    console.error(`${c.red}✗ Unsupported platform: ${platform}${c.reset}`);
+    console.log(`  Supported: ${SUPPORTED_PLATFORMS.join(', ')}`);
+    process.exit(1);
+  }
+
+  console.log(`${c.bold}📚 DocGuard Publish — ${platform}${c.reset}`);
+  console.log(`${c.dim}   Scaffolding ${platform} docs from canonical documentation...${c.reset}\n`);
+
+  switch (platform) {
+    case 'mintlify':
+      scaffoldMintlify(projectDir, config, flags);
+      break;
+  }
+}
+
+function scaffoldMintlify(dir, config, flags) {
+  const docsDir = resolve(dir, 'docs');
+
+  // Check for existing Mintlify setup
+  if (existsSync(resolve(dir, 'docs.json')) && !flags.force) {
+    console.log(`  ${c.yellow}⚠️  docs.json already exists.${c.reset} Use --force to overwrite.`);
+    return;
+  }
+
+  // Create docs directory
+  if (!existsSync(docsDir)) {
+    mkdirSync(docsDir, { recursive: true });
+  }
+
+  let created = 0;
+
+  // ── 1. Generate docs.json (Mintlify v2 config) ──
+  const docsJson = {
+    "$schema": "https://mintlify.com/docs.json",
+    name: config.projectName || basename(dir),
+    logo: {
+      dark: "/logo/dark.svg",
+      light: "/logo/light.svg",
+    },
+    favicon: "/favicon.svg",
+    colors: {
+      primary: "#0D9373",
+      light: "#07C983",
+      dark: "#0D9373",
+    },
+    topbarLinks: [
+      {
+        name: "GitHub",
+        url: `https://github.com/${config.repository || 'your-org/your-repo'}`,
+      },
+    ],
+    topbarCtaButton: {
+      name: "Get Started",
+      url: "/quickstart",
+    },
+    tabs: [
+      {
+        name: "Architecture",
+        url: "architecture",
+      },
+      {
+        name: "API Reference",
+        url: "api-reference",
+      },
+    ],
+    navigation: buildMintlifyNavigation(dir),
+    footerSocials: {
+      github: `https://github.com/${config.repository || 'your-org/your-repo'}`,
+    },
+  };
+
+  writeFileSync(resolve(dir, 'docs.json'), JSON.stringify(docsJson, null, 2), 'utf-8');
+  console.log(`  ${c.green}✅ docs.json${c.reset} (Mintlify v2 config)`);
+  created++;
+
+  // ── 2. Generate introduction.mdx ──
+  const readmePath = resolve(dir, 'README.md');
+  let readmeContent = '';
+  if (existsSync(readmePath)) {
+    readmeContent = readFileSync(readmePath, 'utf-8');
+    // Extract first paragraph for description
+    const firstPara = readmeContent.split('\n\n').slice(1, 3).join('\n\n');
+    readmeContent = firstPara;
+  }
+
+  const introContent = `---
+title: Introduction
+description: "${config.projectName} documentation"
+---
+
+# ${config.projectName}
+
+${readmeContent || `Welcome to the ${config.projectName} documentation.`}
+
+## Quick Links
+
+<CardGroup cols={2}>
+  <Card title="Quick Start" icon="rocket" href="/quickstart">
+    Get up and running in 5 minutes
+  </Card>
+  <Card title="Architecture" icon="building" href="/architecture">
+    Understand the system design
+  </Card>
+  <Card title="API Reference" icon="code" href="/api-reference">
+    Explore the API endpoints
+  </Card>
+  <Card title="Data Model" icon="database" href="/data-model">
+    Learn about the data structure
+  </Card>
+</CardGroup>
+`;
+
+  writeFileSync(resolve(docsDir, 'introduction.mdx'), introContent, 'utf-8');
+  console.log(`  ${c.green}✅ docs/introduction.mdx${c.reset}`);
+  created++;
+
+  // ── 3. Generate quickstart.mdx ──
+  const quickstartContent = `---
+title: Quick Start
+description: "Get started with ${config.projectName}"
+---
+
+# Quick Start
+
+## Prerequisites
+
+- Node.js 18+
+- npm or pnpm
+
+## Installation
+
+\`\`\`bash
+npm install
+\`\`\`
+
+## Setup
+
+\`\`\`bash
+cp .env.example .env.local
+# Fill in environment variables
+npm run dev
+\`\`\`
+
+## Verify
+
+\`\`\`bash
+npx docguard-cli guard    # Check documentation compliance
+npx docguard-cli score    # View CDD maturity score
+\`\`\`
+`;
+
+  writeFileSync(resolve(docsDir, 'quickstart.mdx'), quickstartContent, 'utf-8');
+  console.log(`  ${c.green}✅ docs/quickstart.mdx${c.reset}`);
+  created++;
+
+  // ── 4. Map canonical docs to Mintlify pages ──
+  const canonicalDir = resolve(dir, 'docs-canonical');
+  const mappings = [
+    { source: 'ARCHITECTURE.md', target: 'architecture.mdx', title: 'Architecture' },
+    { source: 'API-REFERENCE.md', target: 'api-reference.mdx', title: 'API Reference' },
+    { source: 'DATA-MODEL.md', target: 'data-model.mdx', title: 'Data Model' },
+    { source: 'SECURITY.md', target: 'security.mdx', title: 'Security' },
+    { source: 'ENVIRONMENT.md', target: 'environment.mdx', title: 'Environment' },
+    { source: 'TEST-SPEC.md', target: 'test-spec.mdx', title: 'Test Specification' },
+  ];
+
+  for (const mapping of mappings) {
+    const sourcePath = resolve(canonicalDir, mapping.source);
+    if (existsSync(sourcePath)) {
+      let content = readFileSync(sourcePath, 'utf-8');
+
+      // Add Mintlify frontmatter
+      const frontmatter = `---\ntitle: "${mapping.title}"\ndescription: "${config.projectName} ${mapping.title.toLowerCase()}"\n---\n\n`;
+
+      // Remove docguard metadata comments
+      content = content.replace(/<!--\s*docguard:\w+\s+[^>]+\s*-->\n?/g, '');
+      content = content.replace(/> \*\*Auto-generated by DocGuard\.\*\*[^\n]*\n?/g, '');
+
+      writeFileSync(resolve(docsDir, mapping.target), frontmatter + content, 'utf-8');
+      console.log(`  ${c.green}✅ docs/${mapping.target}${c.reset} ← ${mapping.source}`);
+      created++;
+    }
+  }
+
+  // ── Summary ──
+  console.log(`\n${c.bold}  ─────────────────────────────────────────${c.reset}`);
+  console.log(`  ${c.green}Created: ${created} files${c.reset}`);
+  console.log(`\n  ${c.bold}Next steps:${c.reset}`);
+  console.log(`  ${c.cyan}1.${c.reset} Install Mintlify: ${c.dim}npm install -g mintlify${c.reset}`);
+  console.log(`  ${c.cyan}2.${c.reset} Preview locally: ${c.dim}mintlify dev${c.reset}`);
+  console.log(`  ${c.cyan}3.${c.reset} Push to GitHub → auto-deploys on Mintlify${c.reset}`);
+  console.log(`  ${c.dim}\n  Mintlify is free for open-source projects.${c.reset}`);
+  console.log(`  ${c.dim}  Docs: https://mintlify.com/docs${c.reset}\n`);
+}
+
+function buildMintlifyNavigation(dir) {
+  const nav = [
+    {
+      group: "Getting Started",
+      pages: ["introduction", "quickstart"],
+    },
+  ];
+
+  // Add architecture group if docs exist
+  const canonicalDir = resolve(dir, 'docs-canonical');
+  const architecturePages = [];
+  if (existsSync(resolve(canonicalDir, 'ARCHITECTURE.md'))) architecturePages.push("architecture");
+  if (existsSync(resolve(canonicalDir, 'DATA-MODEL.md'))) architecturePages.push("data-model");
+  if (existsSync(resolve(canonicalDir, 'SECURITY.md'))) architecturePages.push("security");
+  if (architecturePages.length > 0) {
+    nav.push({ group: "Architecture", pages: architecturePages });
+  }
+
+  // Add operations group
+  const opsPages = [];
+  if (existsSync(resolve(canonicalDir, 'ENVIRONMENT.md'))) opsPages.push("environment");
+  if (existsSync(resolve(canonicalDir, 'TEST-SPEC.md'))) opsPages.push("test-spec");
+  if (opsPages.length > 0) {
+    nav.push({ group: "Operations", pages: opsPages });
+  }
+
+  // Add API reference
+  if (existsSync(resolve(canonicalDir, 'API-REFERENCE.md'))) {
+    nav.push({ group: "API Reference", pages: ["api-reference"] });
+  }
+
+  return nav;
+}

package/cli/commands/score.mjs

@@ -99,6 +99,37 @@ export function runScore(projectDir, config, flags) {
     console.log(`  Tax-to-value ratio:  ${taxColor}${c.bold}${tax.level}${c.reset}`);
     console.log(`  ${c.dim}${tax.recommendation}${c.reset}\n`);
   }
+
+  // ── Multi-Signal Breakdown (--signals flag) ──
+  // Inspired by CJE multi-signal composite scoring (Lopez et al., TRACE, IEEE TMLCN 2026)
+  if (flags.signals) {
+    console.log(`  ${c.bold}📡 Multi-Signal Quality Breakdown${c.reset}`);
+    console.log(`  ${c.dim}─────────────────────────────────${c.reset}`);
+
+    const signals = [
+      { name: 'Structure',     score: scores.structure,    weight: WEIGHTS.structure,    description: 'Required files exist' },
+      { name: 'Doc Quality',   score: scores.docQuality,   weight: WEIGHTS.docQuality,   description: 'Docs have required sections + content' },
+      { name: 'Testing',       score: scores.testing,      weight: WEIGHTS.testing,      description: 'Test spec alignment' },
+      { name: 'Security',      score: scores.security,     weight: WEIGHTS.security,     description: 'No hardcoded secrets, .gitignore' },
+      { name: 'Environment',   score: scores.environment,  weight: WEIGHTS.environment,  description: 'Env docs, .env.example' },
+      { name: 'Drift',         score: scores.drift,        weight: WEIGHTS.drift,        description: 'Drift tracking discipline' },
+      { name: 'Changelog',     score: scores.changelog,    weight: WEIGHTS.changelog,    description: 'Changelog maintenance' },
+      { name: 'Architecture',  score: scores.architecture, weight: WEIGHTS.architecture, description: 'Layer boundary compliance' },
+    ];
+
+    for (const sig of signals) {
+      const weighted = Math.round((sig.score / 100) * sig.weight);
+      const quality = sig.score >= 90 ? 'HIGH' : sig.score >= 50 ? 'MEDIUM' : 'LOW';
+      const qColor = quality === 'HIGH' ? c.green : quality === 'MEDIUM' ? c.yellow : c.red;
+      const bar = renderBar(sig.score);
+
+      console.log(`  ${bar} ${qColor}[${quality}]${c.reset} ${sig.name.padEnd(14)} ${sig.score}% → ${c.bold}${weighted}/${sig.weight}${c.reset} pts  ${c.dim}${sig.description}${c.reset}`);
+    }
+
+    console.log(`\n  ${c.dim}Composite: Σ(signal_score × weight) = ${totalScore}/100${c.reset}`);
+    console.log(`  ${c.dim}Quality labels: HIGH (≥90%), MEDIUM (50-89%), LOW (<50%)${c.reset}`);
+    console.log(`  ${c.dim}Methodology: CJE multi-signal composite (Lopez et al., TRACE, IEEE TMLCN 2026)${c.reset}\n`);
+  }
 }
 
 /**

package/cli/commands/trace.mjs

@@ -0,0 +1,311 @@
+/**
+ * Trace Command — Generate a requirements traceability matrix
+ * Maps canonical docs ↔ source code ↔ tests → produces a traceability report.
+ *
+ * Inspired by requirements traceability in Lopez et al., AITPG (IEEE TSE 2026)
+ * and ISO/IEC/IEEE 29119 traceability requirements.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { resolve, join, extname, basename, relative } from 'node:path';
+import { c } from '../docguard.mjs';
+
+const IGNORE_DIRS = new Set([
+  'node_modules', '.git', '.next', 'dist', 'build', 'coverage',
+  '.cache', '__pycache__', '.venv', 'vendor', '.turbo', '.vercel',
+  '.amplify-hosting', '.serverless',
+]);
+
+const CODE_EXTENSIONS = new Set([
+  '.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx',
+  '.py', '.java', '.go', '.rs', '.rb', '.php', '.cs',
+]);
+
+const TEST_PATTERNS = [
+  /\.test\.[jt]sx?$/,
+  /\.spec\.[jt]sx?$/,
+  /test_.*\.py$/,
+  /_test\.go$/,
+  /Test\.java$/,
+];
+
+/**
+ * Mapping of canonical documents to the code/config artifacts they trace to.
+ * Each entry defines what source patterns prove coverage of that canonical doc.
+ */
+const TRACE_MAP = {
+  'ARCHITECTURE.md': {
+    standard: 'arc42 / C4 Model',
+    sourcePatterns: [
+      { label: 'Entry points', glob: /^(index|main|app|server)\.[jt]sx?$/ },
+      { label: 'Config files', glob: /^(package\.json|tsconfig.*|next\.config|vite\.config)/ },
+      { label: 'Route handlers', glob: /(routes?|api|pages|app)\// },
+    ],
+  },
+  'DATA-MODEL.md': {
+    standard: 'C4 Component / ER (Chen)',
+    sourcePatterns: [
+      { label: 'Schema definitions', glob: /(schema|model|entity|migration|prisma)/i },
+      { label: 'Type definitions', glob: /types?\.[jt]sx?$/ },
+      { label: 'Database configs', glob: /(drizzle|knex|sequelize|typeorm)/i },
+    ],
+  },
+  'TEST-SPEC.md': {
+    standard: 'ISO/IEC/IEEE 29119-3',
+    sourcePatterns: [
+      { label: 'Test files', glob: /\.(test|spec)\.[jt]sx?$/ },
+      { label: 'Test config', glob: /(jest|vitest|playwright|cypress)\.config/ },
+      { label: 'E2E tests', glob: /(e2e|integration)\// },
+    ],
+  },
+  'SECURITY.md': {
+    standard: 'OWASP ASVS v4.0',
+    sourcePatterns: [
+      { label: 'Auth modules', glob: /(auth|login|session|jwt|oauth|middleware)/i },
+      { label: 'Secret configs', glob: /\.(env|env\.example|env\.local)$/ },
+      { label: 'Gitignore', glob: /^\.gitignore$/ },
+    ],
+  },
+  'ENVIRONMENT.md': {
+    standard: '12-Factor App',
+    sourcePatterns: [
+      { label: 'Env files', glob: /\.env/ },
+      { label: 'Docker configs', glob: /(Dockerfile|docker-compose|\.dockerignore)/ },
+      { label: 'CI/CD configs', glob: /\.(github|gitlab-ci|circleci)/ },
+    ],
+  },
+  'API-REFERENCE.md': {
+    standard: 'OpenAPI 3.1',
+    sourcePatterns: [
+      { label: 'Route handlers', glob: /(routes?|controllers?|handlers?)\// },
+      { label: 'OpenAPI spec', glob: /(openapi|swagger)\.(json|ya?ml)/ },
+      { label: 'API middleware', glob: /middleware\// },
+    ],
+  },
+};
+
+export function runTrace(projectDir, config, flags) {
+  console.log(`${c.bold}🔗 DocGuard Trace — ${config.projectName}${c.reset}`);
+  console.log(`${c.dim}   Directory: ${projectDir}${c.reset}`);
+  console.log(`${c.dim}   Generating requirements traceability matrix...${c.reset}\n`);
+
+  // ── 1. Inventory canonical docs ──
+  const docsDir = resolve(projectDir, 'docs-canonical');
+  const canonicalDocs = [];
+  if (existsSync(docsDir)) {
+    for (const f of readdirSync(docsDir)) {
+      if (f.endsWith('.md')) canonicalDocs.push(f);
+    }
+  }
+
+  // ── 2. Scan project files ──
+  const projectFiles = [];
+  scanDir(projectDir, projectDir, projectFiles);
+
+  // ── 3. Build traceability matrix ──
+  const matrix = [];
+
+  for (const [docName, traceInfo] of Object.entries(TRACE_MAP)) {
+    const docPath = resolve(docsDir, docName);
+    const docExists = existsSync(docPath);
+    let lastModified = null;
+    let docSize = 0;
+
+    if (docExists) {
+      const stat = statSync(docPath);
+      lastModified = stat.mtime.toISOString().split('T')[0];
+      docSize = stat.size;
+    }
+
+    // Find matching source files for each pattern
+    const traces = [];
+    for (const pattern of traceInfo.sourcePatterns) {
+      const matches = projectFiles.filter(f => pattern.glob.test(f));
+      traces.push({
+        label: pattern.label,
+        matchCount: matches.length,
+        files: matches.slice(0, 5), // Cap at 5 for display
+        hasMore: matches.length > 5,
+      });
+    }
+
+    // Find test coverage (files that test code related to this doc)
+    const relatedTests = findRelatedTests(projectFiles, traceInfo.sourcePatterns);
+
+    // Calculate coverage signal
+    const totalSources = traces.reduce((sum, t) => sum + t.matchCount, 0);
+    const coverageSignal = !docExists ? 'MISSING'
+      : totalSources === 0 ? 'UNLINKED'
+      : relatedTests.length > 0 ? 'TRACED'
+      : 'PARTIAL';
+
+    matrix.push({
+      document: docName,
+      standard: traceInfo.standard,
+      exists: docExists,
+      lastModified,
+      docSize,
+      traces,
+      relatedTests,
+      totalSources,
+      coverageSignal,
+    });
+  }
+
+  // ── 4. Output ──
+  if (flags.format === 'json') {
+    outputJSON(config.projectName, matrix);
+  } else {
+    outputText(config.projectName, matrix, canonicalDocs);
+  }
+}
+
+function outputJSON(projectName, matrix) {
+  const result = {
+    project: projectName,
+    traceability: matrix.map(m => ({
+      document: m.document,
+      standard: m.standard,
+      exists: m.exists,
+      lastModified: m.lastModified,
+      coverageSignal: m.coverageSignal,
+      sources: m.totalSources,
+      tests: m.relatedTests.length,
+      traces: m.traces,
+    })),
+    summary: {
+      total: matrix.length,
+      traced: matrix.filter(m => m.coverageSignal === 'TRACED').length,
+      partial: matrix.filter(m => m.coverageSignal === 'PARTIAL').length,
+      unlinked: matrix.filter(m => m.coverageSignal === 'UNLINKED').length,
+      missing: matrix.filter(m => m.coverageSignal === 'MISSING').length,
+    },
+    timestamp: new Date().toISOString(),
+  };
+  console.log(JSON.stringify(result, null, 2));
+}
+
+function outputText(projectName, matrix, canonicalDocs) {
+  // Header table
+  console.log(`  ${c.bold}Traceability Matrix${c.reset}\n`);
+  console.log(`  ${c.dim}${'Document'.padEnd(22)} ${'Standard'.padEnd(28)} ${'Status'.padEnd(10)} ${'Sources'.padEnd(9)} ${'Tests'.padEnd(7)} ${'Last Modified'}${c.reset}`);
+  console.log(`  ${c.dim}${'─'.repeat(22)} ${'─'.repeat(28)} ${'─'.repeat(10)} ${'─'.repeat(9)} ${'─'.repeat(7)} ${'─'.repeat(14)}${c.reset}`);
+
+  for (const entry of matrix) {
+    const statusColor = entry.coverageSignal === 'TRACED' ? c.green
+      : entry.coverageSignal === 'PARTIAL' ? c.yellow
+      : entry.coverageSignal === 'UNLINKED' ? c.yellow
+      : c.red;
+    const statusIcon = entry.coverageSignal === 'TRACED' ? '✅'
+      : entry.coverageSignal === 'PARTIAL' ? '⚠️ '
+      : entry.coverageSignal === 'UNLINKED' ? '🔗'
+      : '❌';
+
+    console.log(`  ${statusIcon} ${entry.document.padEnd(19)} ${c.dim}${entry.standard.padEnd(28)}${c.reset} ${statusColor}${entry.coverageSignal.padEnd(10)}${c.reset} ${String(entry.totalSources).padEnd(9)} ${String(entry.relatedTests.length).padEnd(7)} ${entry.lastModified || c.dim + 'n/a' + c.reset}`);
+  }
+
+  // Detailed traces (verbose)
+  console.log(`\n  ${c.bold}Detailed Traces${c.reset}\n`);
+
+  for (const entry of matrix) {
+    if (!entry.exists) {
+      console.log(`  ${c.red}❌ ${entry.document}${c.reset} — ${c.dim}Document not found. Run \`docguard generate\` to create.${c.reset}`);
+      continue;
+    }
+
+    console.log(`  ${c.bold}📄 ${entry.document}${c.reset} ${c.dim}(${entry.standard})${c.reset}`);
+
+    for (const trace of entry.traces) {
+      const icon = trace.matchCount > 0 ? `${c.green}✓${c.reset}` : `${c.dim}○${c.reset}`;
+      console.log(`     ${icon} ${trace.label}: ${trace.matchCount} file(s)`);
+      if (trace.matchCount > 0 && trace.files.length > 0) {
+        for (const f of trace.files) {
+          console.log(`       ${c.dim}→ ${f}${c.reset}`);
+        }
+        if (trace.hasMore) {
+          console.log(`       ${c.dim}  ... and ${trace.matchCount - 5} more${c.reset}`);
+        }
+      }
+    }
+
+    if (entry.relatedTests.length > 0) {
+      console.log(`     ${c.green}✓${c.reset} Test coverage: ${entry.relatedTests.length} test file(s)`);
+      for (const t of entry.relatedTests.slice(0, 3)) {
+        console.log(`       ${c.dim}→ ${t}${c.reset}`);
+      }
+      if (entry.relatedTests.length > 3) {
+        console.log(`       ${c.dim}  ... and ${entry.relatedTests.length - 3} more${c.reset}`);
+      }
+    } else {
+      console.log(`     ${c.yellow}○${c.reset} ${c.dim}No related test files found${c.reset}`);
+    }
+    console.log('');
+  }
+
+  // Summary
+  const traced = matrix.filter(m => m.coverageSignal === 'TRACED').length;
+  const partial = matrix.filter(m => m.coverageSignal === 'PARTIAL').length;
+  const unlinked = matrix.filter(m => m.coverageSignal === 'UNLINKED').length;
+  const missing = matrix.filter(m => m.coverageSignal === 'MISSING').length;
+
+  console.log(`  ${c.bold}─────────────────────────────────────${c.reset}`);
+  console.log(`  ${c.green}Traced: ${traced}${c.reset}  ${c.yellow}Partial: ${partial}${c.reset}  ${c.yellow}Unlinked: ${unlinked}${c.reset}  ${c.red}Missing: ${missing}${c.reset}`);
+  console.log(`  ${c.dim}Total: ${matrix.length} canonical documents evaluated${c.reset}`);
+
+  if (missing > 0 || unlinked > 0) {
+    console.log(`\n  ${c.dim}Run ${c.cyan}docguard generate${c.dim} to create missing docs.${c.reset}`);
+    console.log(`  ${c.dim}Run ${c.cyan}docguard diagnose${c.dim} to fix coverage gaps.${c.reset}`);
+  }
+
+  console.log(`\n  ${c.dim}Traceability methodology: ISO/IEC/IEEE 29119 (Lopez et al., AITPG, IEEE TSE 2026)${c.reset}\n`);
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function scanDir(rootDir, dir, files) {
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch { return; }
+
+  for (const entry of entries) {
+    if (IGNORE_DIRS.has(entry)) continue;
+    if (entry.startsWith('.') && entry !== '.env' && entry !== '.env.example'
+        && entry !== '.gitignore' && !entry.startsWith('.github')) continue;
+
+    const full = join(dir, entry);
+    let stat;
+    try { stat = statSync(full); } catch { continue; }
+
+    if (stat.isDirectory()) {
+      scanDir(rootDir, full, files);
+    } else {
+      files.push(relative(rootDir, full));
+    }
+  }
+}
+
+function findRelatedTests(projectFiles, sourcePatterns) {
+  // Find test files that might cover the source patterns
+  const testFiles = projectFiles.filter(f => TEST_PATTERNS.some(p => p.test(f)));
+
+  // Match tests to source patterns by directory/name proximity
+  const relatedTests = new Set();
+
+  for (const pattern of sourcePatterns) {
+    const sourceFiles = projectFiles.filter(f => pattern.glob.test(f));
+    for (const src of sourceFiles) {
+      const srcBase = basename(src).replace(/\.[^.]+$/, '');
+      const srcDir = src.split('/')[0];
+
+      for (const test of testFiles) {
+        // Match by name similarity or directory proximity
+        if (test.includes(srcBase) || test.includes(srcDir)) {
+          relatedTests.add(test);
+        }
+      }
+    }
+  }
+
+  return [...relatedTests];
+}