praxis-sec 1.0.0

package/cli/commands/audit.js

@@ -0,0 +1,1180 @@
+/**
+ * Audit Command — Full Security Audit
+ * =====================================
+ *
+ * One command to run everything: secrets, agents, deps, score, and
+ * generate a comprehensive report with a prioritized remediation plan.
+ *
+ * USAGE:
+ *   npx praxis-sec audit [path]                 Full audit with HTML report
+ *   npx praxis-sec audit . --json               JSON output
+ *   npx praxis-sec audit . --html report.html   Custom report path
+ *   npx praxis-sec audit . --no-deps            Skip dependency audit
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { renderFindingsSARIF } from '../core/output/sarif.js';
+import chalk from 'chalk';
+import ora from 'ora';
+import fg from 'fast-glob';
+import { buildOrchestrator, buildOrchestratorAsync } from '../agents/index.js';
+import { LegalRiskAgent } from '../agents/legal-risk-agent.js';
+import { ScoringEngine } from '../agents/scoring-engine.js';
+import { PolicyEngine } from '../agents/policy-engine.js';
+import { HTMLReporter } from '../agents/html-reporter.js';
+import { SBOMGenerator } from '../agents/sbom-generator.js';
+import { autoDetectProvider } from '../providers/llm-provider.js';
+import { runDepsAudit } from './deps.js';
+import {
+  SECRET_PATTERNS,
+  SECURITY_PATTERNS,
+  SKIP_DIRS,
+  SKIP_EXTENSIONS,
+  SKIP_FILENAMES,
+  MAX_FILE_SIZE,
+  loadGitignorePatterns
+} from '../utils/patterns.js';
+import { isHighEntropyMatch, getConfidence } from '../utils/entropy.js';
+import { printBanner } from '../utils/output.js';
+import { CacheManager } from '../utils/cache-manager.js';
+import { filterBaseline } from './baseline.js';
+import { SecurityMemory } from '../utils/security-memory.js';
+import { ScanPlaybook } from '../utils/scan-playbook.js';
+import { generatePDF, generatePrintHTML, isChromeAvailable } from '../utils/pdf-generator.js';
+import { SecretsVerifier } from '../utils/secrets-verifier.js';
+import { applyInlineAnnotations } from './autofix.js';
+import { buildScanFingerprint } from '../utils/scan-fingerprint.js';
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+
+const ALL_PATTERNS = [...SECRET_PATTERNS, ...SECURITY_PATTERNS];
+
+const SEV_ORDER = ['critical', 'high', 'medium', 'low'];
+
+const CATEGORY_LABELS = {
+  secrets: 'Secrets',
+  injection: 'Code Vulnerabilities',
+  deps: 'Dependencies',
+  auth: 'Auth & Access Control',
+  config: 'Configuration',
+  'supply-chain': 'Supply Chain',
+  api: 'API Security',
+  llm: 'AI/LLM Security',
+  legal: 'Legal Risk',
+};
+
+const EFFORT_MAP = {
+  secrets: 'low',
+  config: 'low',
+  deps: 'medium',
+  injection: 'medium',
+  auth: 'medium',
+  'supply-chain': 'medium',
+  api: 'medium',
+  llm: 'high',
+  legal: 'low',
+};
+
+// =============================================================================
+// MAIN COMMAND
+// =============================================================================
+
+export async function auditCommand(targetPath = '.', options = {}) {
+  const absolutePath = path.resolve(targetPath);
+  const machineOutput = options.json || options.sarif || options.csv || options.md;
+
+  if (!fs.existsSync(absolutePath)) {
+    console.error(chalk.red(`  Path does not exist: ${absolutePath}`));
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!machineOutput) {
+    printBanner();
+  }
+
+  // ── Cache Layer ──────────────────────────────────────────────────────────
+  // --deep forces a fresh scan so taint analysis covers every finding,
+  // not just the ones from files changed since the last cached run.
+  const useCache = options.cache !== false && !options.deep;
+  const cache = new CacheManager(absolutePath);
+  let cacheData = useCache ? cache.load() : null;
+  let cacheDiff = null;
+  let allFiles = [];
+
+  // ── Phase 1: Secret Scan ──────────────────────────────────────────────────
+  const secretSpinner = machineOutput ? null : ora({ text: chalk.white('[Phase 1/4] Scanning for secrets...'), color: 'cyan' }).start();
+  let secretFindings = [];
+  let filesScanned = 0;
+
+  try {
+    allFiles = await findFiles(absolutePath);
+    filesScanned = allFiles.length;
+
+    // Determine which files need scanning (incremental if cache exists)
+    let filesToScan = allFiles;
+    let cachedSecretFindings = [];
+
+    if (cacheData) {
+      cacheDiff = cache.diff(allFiles);
+      filesToScan = cacheDiff.changedFiles;
+      // Reuse cached findings for unchanged files (secrets only)
+      cachedSecretFindings = cacheDiff.cachedFindings.filter(
+        f => f.category === 'secrets' || f.category === 'secret'
+      );
+    }
+
+    for (const file of filesToScan) {
+      const fileResults = scanFileForSecrets(file);
+      for (const f of fileResults) {
+        secretFindings.push({
+          file,
+          line: f.line,
+          column: f.column,
+          severity: f.severity,
+          category: f.category || 'secrets',
+          rule: f.patternName,
+          title: f.patternName.replace(/_/g, ' '),
+          description: f.description,
+          matched: f.matched,
+          confidence: f.confidence,
+          fix: file.match(/\.env(\..*)?$/)
+            ? `Ensure .env is in .gitignore and use a secrets manager for production`
+            : `Move to environment variable or secrets manager`,
+        });
+      }
+    }
+
+    // Downgrade .env findings if the file is gitignored (properly managed)
+    const gitignoreContent = (() => {
+      try { return fs.readFileSync(path.join(absolutePath, '.gitignore'), 'utf-8'); } catch { return ''; }
+    })();
+    const envIsGitignored = gitignoreContent.split('\n')
+      .map(l => l.trim())
+      .some(l => /^\.env(\s|$)/.test(l) || l === '*.env' || l === '.env*' || l === '.env.local' || l === '.env.production');
+
+    if (envIsGitignored) {
+      for (const f of secretFindings) {
+        if (f.file.match(/\.env(\..*)?$/) && !f.file.includes('node_modules')) {
+          f.severity = 'low';
+          f.confidence = 'low';
+          f.fix = 'Already gitignored — ensure secrets manager is used for production deploys';
+        }
+      }
+    }
+
+    // Downgrade secrets in test files (intentional test fixtures)
+    const TEST_PATH = /(?:__tests__|\.test\.|\.spec\.|\/test\/|\/tests\/|\/fixtures?\/)/i;
+    for (const f of secretFindings) {
+      if (TEST_PATH.test(f.file)) {
+        f.confidence = 'low';
+      }
+    }
+
+    // Merge with cached findings for unchanged files
+    secretFindings = [...secretFindings, ...cachedSecretFindings];
+
+    const cacheNote = cacheDiff && cacheDiff.changedFiles.length < allFiles.length
+      ? ` (${cacheDiff.changedFiles.length} changed, ${cacheDiff.unchangedCount} cached)`
+      : '';
+
+    if (secretSpinner) secretSpinner.succeed(
+      secretFindings.length === 0
+        ? chalk.green(`[Phase 1/4] Secrets: clean${cacheNote}`)
+        : chalk.red(`[Phase 1/4] Secrets: ${secretFindings.length} found${cacheNote}`)
+    );
+  } catch (err) {
+    if (secretSpinner) secretSpinner.fail(chalk.red(`[Phase 1/4] Secret scan failed: ${err.message}`));
+  }
+
+  // ── Phase 2: Agent Scan ───────────────────────────────────────────────────
+  const orchestrator = await buildOrchestratorAsync(absolutePath, { quiet: true });
+
+  // --hermes-only: filter to llm + supply-chain category agents only
+  if (options.hermesOnly && orchestrator.agents) {
+    const hermesCategories = new Set(['llm', 'supply-chain']);
+    orchestrator.agents = orchestrator.agents.filter(a =>
+      hermesCategories.has(a.category) || hermesCategories.has(a.constructor?.category)
+    );
+  }
+
+  const registeredAgentCount = orchestrator.agents?.length || 15;
+  const agentSpinner = machineOutput ? null : ora({ text: chalk.white(`[Phase 2/4] Running ${registeredAgentCount} security agents...`), color: 'cyan' }).start();
+  let agentFindings = [];
+  let recon = null;
+  let agentResults = [];
+
+  try {
+    // Suppress individual agent spinners by using quiet mode
+    // Pass changedFiles for incremental scanning if cache is valid
+    const orchestratorOpts = { quiet: true };
+    if (options.deep) orchestratorOpts.deep = true;
+    if (options.local) orchestratorOpts.local = true;
+    if (options.model) orchestratorOpts.model = options.model;
+    if (options.provider) orchestratorOpts.provider = options.provider;
+    if (options.baseUrl) orchestratorOpts.baseUrl = options.baseUrl;
+    if (options.budget) orchestratorOpts.budget = options.budget;
+    if (options.verbose) orchestratorOpts.verbose = true;
+    if (cacheDiff && cacheDiff.changedFiles.length < allFiles.length) {
+      orchestratorOpts.changedFiles = cacheDiff.changedFiles;
+    }
+    const results = await orchestrator.runAll(absolutePath, orchestratorOpts); // praxis-ignore — orchestrator result, not LLM output triggering actions
+    recon = results.recon;
+    agentFindings = results.findings;
+    agentResults = results.agentResults;
+
+    const totalAgentFindings = agentFindings.length;
+    const agentCount = agentResults.filter(a => a.success).length;
+    if (agentSpinner) agentSpinner.succeed(
+      totalAgentFindings === 0
+        ? chalk.green(`[Phase 2/4] ${agentCount} agents: clean`)
+        : chalk.yellow(`[Phase 2/4] ${agentCount} agents: ${totalAgentFindings} finding(s)`)
+    );
+  } catch (err) {
+    if (agentSpinner) agentSpinner.fail(chalk.red(`[Phase 2/4] Agent scan failed: ${err.message}`));
+  }
+
+  // ── Phase 3: Dependency Audit ─────────────────────────────────────────────
+  let depVulns = [];
+  if (options.deps !== false) {
+    const depSpinner = machineOutput ? null : ora({ text: chalk.white('[Phase 3/4] Auditing dependencies...'), color: 'cyan' }).start();
+    try {
+      const depResult = await runDepsAudit(absolutePath);
+      depVulns = depResult.vulns || [];
+      if (depSpinner) depSpinner.succeed(
+        depVulns.length === 0
+          ? chalk.green('[Phase 3/4] Dependencies: clean')
+          : chalk.red(`[Phase 3/4] Dependencies: ${depVulns.length} CVE(s)`)
+      );
+    } catch {
+      if (depSpinner) depSpinner.succeed(chalk.gray('[Phase 3/4] Dependencies: skipped (no manifest)'));
+    }
+  } else if (!machineOutput) {
+    console.log(chalk.gray('  [Phase 3/4] Dependencies: skipped (--no-deps)'));
+  }
+
+  // ── Phase 3b: Legal Risk Scan (opt-in) ───────────────────────────────────
+  let legalFindings = [];
+  if (options.includeLegal) {
+    const legalSpinner = machineOutput ? null : ora({ text: chalk.white('[Phase 3b] Legal risk scan…'), color: 'cyan' }).start();
+    try {
+      const legalAgent = new LegalRiskAgent();
+      legalFindings = await legalAgent.analyze({ rootPath: absolutePath, files: allFiles });
+      if (legalSpinner) legalSpinner.succeed(
+        legalFindings.length === 0
+          ? chalk.green('[Phase 3b] Legal: clean')
+          : chalk.yellow(`[Phase 3b] Legal: ${legalFindings.length} finding(s)`)
+      );
+    } catch {
+      if (legalSpinner) legalSpinner.succeed(chalk.gray('[Phase 3b] Legal: skipped'));
+    }
+  }
+
+  // ── Phase 4: Merge, Score, and Build Plan ─────────────────────────────────
+  const scoreSpinner = machineOutput ? null : ora({ text: chalk.white('[Phase 4/4] Computing security score...'), color: 'cyan' }).start();
+
+  // Merge secret findings + agent findings + legal findings, deduplicate
+  const allFindings = deduplicateFindings([...secretFindings, ...agentFindings, ...legalFindings]);
+
+  // Apply policy
+  const policy = PolicyEngine.load(absolutePath);
+  let filteredFindings = policy.applyPolicy(allFindings);
+
+  // Apply baseline filter (only show new findings)
+  if (options.baseline) {
+    const beforeCount = filteredFindings.length;
+    filteredFindings = filterBaseline(filteredFindings, absolutePath);
+    if (!machineOutput && beforeCount !== filteredFindings.length) {
+      console.log(chalk.gray(`  Baseline: ${beforeCount - filteredFindings.length} known finding(s) filtered, ${filteredFindings.length} new`));
+    }
+  }
+
+  // ── Scan Playbook — update with latest recon + findings ─────────────────
+  try {
+    const playbook = new ScanPlaybook(absolutePath);
+    const suppressedRules = new SecurityMemory(absolutePath).list().map(e => e.rule).filter(Boolean);
+    playbook.update(recon, { score: scoreResult.score, grade: scoreResult.grade?.letter || scoreResult.grade, totalFindings: filteredFindings.length }, filteredFindings, suppressedRules);
+  } catch { /* non-fatal */ }
+
+  // ── Security Memory Filter ──────────────────────────────────────────────
+  // Auto-learn false positives from deep analysis results, then suppress
+  // any finding that memory recognises from a previous scan.
+  const secMemory = new SecurityMemory(absolutePath);
+  if (options.deep) {
+    // After deep analysis ran, learn any new false positives
+    const newFPs = secMemory.learnFromAnalysis(filteredFindings);
+    if (newFPs > 0 && !machineOutput) {
+      console.log(chalk.gray(`  Memory: ${newFPs} new false positive(s) learned and will be suppressed in future scans`));
+    }
+  }
+  const { kept: memFiltered, suppressedCount: memSuppressed } = secMemory.filter(filteredFindings);
+  filteredFindings = memFiltered;
+  if (memSuppressed > 0 && !machineOutput) {
+    console.log(chalk.gray(`  Memory: ${memSuppressed} previously-confirmed false positive(s) suppressed`));
+  }
+
+  // Count suppressions (praxis-ignore comments)
+  const suppressions = countSuppressions(allFiles);
+
+  // Score
+  const scoringEngine = new ScoringEngine();
+  const scoreResult = scoringEngine.compute(filteredFindings, depVulns);
+  // Round score to 1 decimal place to avoid floating-point noise (e.g., 63.300000000000004)
+  scoreResult.score = Math.round(scoreResult.score * 10) / 10;
+  scoringEngine.saveToHistory(absolutePath, scoreResult, suppressions);
+
+  const gradeColor = scoreResult.score >= 75 ? chalk.green.bold : scoreResult.score >= 60 ? chalk.yellow.bold : chalk.red.bold;
+  if (scoreSpinner) scoreSpinner.succeed(
+    chalk.white('[Phase 4/4] Score: ') + gradeColor(`${scoreResult.score}/100 ${scoreResult.grade.letter}`)
+  );
+
+  // ── AI Classification (optional, with LLM cache) ───────────────────────
+  if (options.ai !== false && !options.noAi) {
+    const provider = autoDetectProvider(absolutePath, {
+      provider:   options.provider,
+      baseUrl:    options.baseUrl,
+      model:      options.model,
+      think:      options.think || false,
+    });
+    if (provider && filteredFindings.length > 0 && filteredFindings.length <= 50) {
+      const aiSpinner = machineOutput ? null : ora({ text: `Classifying with ${provider.name}...`, color: 'cyan' }).start();
+      try {
+        // Check LLM cache for existing classifications
+        const llmCache = cache.loadLLMClassifications();
+        const uncachedFindings = [];
+        let cachedCount = 0;
+
+        for (const finding of filteredFindings) {
+          const key = cache.getLLMCacheKey(finding);
+          const cached = llmCache[key];
+          if (cached) {
+            finding.aiClassification = cached.classification;
+            finding.aiReason = cached.reason;
+            finding.aiFix = cached.fix;
+            cachedCount++;
+          } else {
+            uncachedFindings.push(finding);
+          }
+        }
+
+        // Only send uncached findings to LLM
+        if (uncachedFindings.length > 0) {
+          const classifications = await provider.classify(uncachedFindings);
+          const newCacheEntries = {};
+          for (const cl of classifications) {
+            const finding = filteredFindings.find(f => `${f.file}:${f.line}` === cl.id);
+            if (finding) {
+              finding.aiClassification = cl.classification;
+              finding.aiReason = cl.reason;
+              finding.aiFix = cl.fix;
+              const key = cache.getLLMCacheKey(finding);
+              newCacheEntries[key] = {
+                classification: cl.classification,
+                reason: cl.reason,
+                fix: cl.fix,
+                cachedAt: new Date().toISOString(),
+              };
+            }
+          }
+          cache.saveLLMClassifications(newCacheEntries);
+        }
+
+        const cacheNote = cachedCount > 0 ? `, ${cachedCount} cached` : '';
+        if (aiSpinner) aiSpinner.succeed(chalk.green(`AI classification complete (${provider.name}${cacheNote})`));
+      } catch (err) {
+        if (aiSpinner) aiSpinner.fail(chalk.yellow(`AI classification failed: ${err.message}`));
+      }
+    }
+  }
+
+  // ── Secrets Verification (optional, --verify flag) ─────────────────────
+  if (options.verify) {
+    const verifySpinner = machineOutput ? null : ora({ text: 'Verifying leaked secrets against provider APIs...', color: 'cyan' }).start();
+    try {
+      const verifier = new SecretsVerifier();
+      const verifyResults = await verifier.verify(filteredFindings);
+      const activeCount = verifyResults.filter(r => r.result.active === true).length;
+      const inactiveCount = verifyResults.filter(r => r.result.active === false).length;
+      if (verifySpinner) {
+        verifySpinner.succeed(chalk.green(
+          `Secrets verified: ${activeCount} active, ${inactiveCount} inactive, ${verifyResults.length - activeCount - inactiveCount} unknown`
+        ));
+      }
+      // Show active secrets warning
+      if (activeCount > 0 && !machineOutput) {
+        console.log(chalk.red.bold('  ⚠ ACTIVE SECRETS DETECTED — rotate immediately:'));
+        for (const r of verifyResults.filter(r => r.result.active === true)) {
+          const rel = path.relative(absolutePath, r.finding.file).replace(/\\/g, '/');
+          console.log(chalk.red(`    ${r.result.provider}: ${rel}:${r.finding.line} — ${r.result.info}`));
+        }
+      }
+    } catch (err) {
+      if (verifySpinner) verifySpinner.fail(chalk.yellow(`Secrets verification failed: ${err.message}`));
+    }
+  }
+
+  // ── Save Cache ──────────────────────────────────────────────────────────
+  if (useCache) {
+    try {
+      // Merge agent findings back for cache (secret + agent findings from changed files)
+      // plus cached findings from unchanged files
+      const cachedAgentFindings = cacheData && cacheDiff
+        ? cacheDiff.cachedFindings.filter(f => f.category !== 'secrets' && f.category !== 'secret')
+        : [];
+      const allFindingsForCache = [...secretFindings, ...agentFindings, ...cachedAgentFindings];
+      cache.save(allFiles, deduplicateFindings(allFindingsForCache), recon, scoreResult);
+    } catch {
+      // Silent — caching should never break a scan
+    }
+  }
+
+  // ── Build Remediation Plan ────────────────────────────────────────────────
+  const remediationPlan = buildRemediationPlan(filteredFindings, depVulns, absolutePath);
+
+  // Skip all output and file generation for inner agentic re-scans
+  if (options._agenticInner) {
+    return { score: scoreResult.score, findings: filteredFindings };
+  }
+
+  // ── Output ────────────────────────────────────────────────────────────────
+  if (!machineOutput) console.log();
+
+  if (options.csv) {
+    outputCSV(filteredFindings, depVulns, scoreResult, absolutePath);
+  } else if (options.md) {
+    outputMarkdown(scoreResult, filteredFindings, depVulns, remediationPlan, absolutePath);
+  } else if (options.json) {
+    outputJSON(scoreResult, filteredFindings, depVulns, recon, agentResults, remediationPlan, suppressions, options.compare ? scoringEngine.loadHistory(absolutePath) : null, filesScanned);
+  } else if (options.sarif) {
+    outputSARIF(filteredFindings, absolutePath);
+  } else {
+    printReport(scoreResult, filteredFindings, depVulns, recon, remediationPlan, absolutePath, filesScanned);
+  }
+
+  // ── HTML Report — always on for human output, or when --html is explicit ──
+  const explicitHtml = typeof options.html === 'string' || options.html === true;
+  if (explicitHtml || (!options.json && !options.sarif && !options.csv && !options.md)) {
+    const htmlPath = typeof options.html === 'string' ? options.html : 'praxis-report.html';
+    const reporter = new HTMLReporter();
+    reporter.generateToFile(scoreResult, filteredFindings, recon, absolutePath, htmlPath, agentResults, filesScanned);
+
+    // If --html-dir or --suite specified, also generate granular multi-page report suite
+    if (options.htmlDir || options['html-dir'] || options.suite) {
+      const suiteDir = typeof (options.htmlDir || options['html-dir'] || options.suite) === 'string'
+        ? (options.htmlDir || options['html-dir'] || options.suite)
+        : 'report';
+      reporter.generateReportSuite(scoreResult, filteredFindings, depVulns, recon, remediationPlan, absolutePath, suiteDir, agentResults, filesScanned);
+    }
+
+    // Keep stdout pure JSON/SARIF when combined with machine output
+    const note = machineOutput ? console.error : console.log;
+    note();
+    note(chalk.cyan(`  Full report: ${chalk.white.bold(htmlPath)}`));
+    note(chalk.gray(`  Dashboard:   `) + chalk.cyan(''));
+
+    // PDF export
+    if (options.pdf) {
+      const pdfPath = typeof options.pdf === 'string' ? options.pdf : 'praxis-report.pdf';
+      const result = generatePDF(path.resolve(htmlPath), path.resolve(pdfPath));
+      if (result) {
+        note(chalk.cyan(`  PDF report:  ${chalk.white.bold(pdfPath)}`));
+      } else {
+        // Fallback: print-optimized HTML
+        const fallbackPath = pdfPath.replace(/\.pdf$/, '.print.html');
+        generatePrintHTML(path.resolve(htmlPath), path.resolve(fallbackPath));
+        note(chalk.yellow(`  Chrome not found — saved print-optimized HTML: ${fallbackPath}`));
+        note(chalk.gray('  Open in a browser and Print → Save as PDF'));
+      }
+    }
+  }
+
+  if (!machineOutput && !options.csv && !options.md) {
+    // ── Policy Violations ──────────────────────────────────────────────────
+    const violations = policy.evaluate(scoreResult, filteredFindings, {
+      agentResults,
+      depsRun: options.deps !== false,
+      secretsRun: true,
+      depVulns,
+    });
+    if (violations.length > 0) {
+      console.log();
+      console.log(chalk.red.bold('  Policy Violations:'));
+      for (const v of violations.slice(0, 5)) {
+        console.log(chalk.red(`    ✗ ${v.message}`));
+      }
+    }
+
+    // ── Trend ───────────────────────────────────────────────────────────────
+    const trend = scoringEngine.getTrend(absolutePath, scoreResult.score);
+    if (trend) {
+      const arrow = trend.diff > 0 ? chalk.green('↑') : trend.diff < 0 ? chalk.red('↓') : chalk.gray('→');
+      const roundedDiff = Math.round(trend.diff * 10) / 10;
+      const diffLabel = roundedDiff === 0 ? chalk.gray('no change') : chalk.white(`${roundedDiff > 0 ? '+' : ''}${roundedDiff}`);
+      console.log(chalk.gray(`  Trend: ${trend.previousScore} → ${trend.currentScore} ${arrow} (`) + diffLabel + chalk.gray(')'));
+    }
+
+    // ── Detailed Comparison ────────────────────────────────────────────────
+    if (options.compare) {
+      printComparison(scoringEngine, absolutePath, scoreResult);
+    }
+
+    console.log();
+    console.log(chalk.cyan('═'.repeat(60)));
+    console.log();
+  }
+
+  // ── Agentic Loop (--agentic) ────────────────────────────────────────────
+  // Scan → annotate fixes → re-scan cycle until score >= target or maxIter.
+  // NOTE: process.exit() is deferred until after the loop so all iterations
+  // can run. The inner re-scans use _agenticInner: true to skip process.exit.
+  if (options.agentic && !options._agenticInner) {
+    const maxIter = typeof options.agentic === 'number' ? options.agentic : 3;
+    const targetScore = options.agenticTarget ?? 75;
+    let iteration = 1;
+    let currentScore = scoreResult.score;
+    let currentFindings = filteredFindings;
+
+    if (!machineOutput) {
+      console.log();
+      console.log(chalk.cyan.bold(`  Agentic mode: scan→fix→verify loop (max ${maxIter} iterations, target score: ${targetScore})`));
+    }
+
+    while (currentScore < targetScore && iteration <= maxIter) {
+      if (!machineOutput) {
+        console.log(chalk.cyan(`\n  ─── Agentic iteration ${iteration}/${maxIter} (current score: ${currentScore}) ───`));
+      }
+
+      const actionable = currentFindings.filter(f => f.fix && f.severity !== 'low');
+      if (actionable.length === 0) {
+        if (!machineOutput) console.log(chalk.gray('  No auto-fixable findings — stopping agentic loop.'));
+        break;
+      }
+
+      // Delegate annotation to autofix module (handles comment style, idempotency, NEVER_EDIT list)
+      const fixCount = applyInlineAnnotations(actionable);
+      if (!machineOutput) {
+        console.log(chalk.yellow(`  Annotated ${fixCount} finding(s). Re-scanning...`));
+      }
+      if (fixCount === 0) break;
+
+      // Re-scan without recursing into the agentic loop or calling process.exit
+      const innerResult = await runAuditInner(targetPath, {
+        ...options,
+        agentic: false,
+        _agenticInner: true,
+        json: false,
+        sarif: false,
+        csv: false,
+        md: false,
+        html: false,
+        pdf: false,
+        quiet: true,
+      });
+
+      const prevScore = currentScore;
+      currentScore = innerResult?.score ?? currentScore;
+      currentFindings = innerResult?.findings ?? currentFindings;
+
+      if (!machineOutput) {
+        const diff = currentScore - prevScore;
+        const arrow = diff > 0 ? chalk.green(`↑ +${diff.toFixed(1)}`) : diff < 0 ? chalk.red(`↓ ${diff.toFixed(1)}`) : chalk.gray('→ 0');
+        console.log(chalk.cyan(`  Re-scan score: ${currentScore} ${arrow}`));
+      }
+
+      iteration++;
+    }
+
+    if (!machineOutput) {
+      if (currentScore >= targetScore) {
+        console.log(chalk.green.bold(`\n  Agentic loop complete — target score ${targetScore} reached (${currentScore}).`));
+      } else {
+        console.log(chalk.yellow(`\n  Agentic loop stopped after ${iteration - 1} iteration(s). Final score: ${currentScore}`));
+      }
+    }
+  }
+
+  // ── Exit code logic ─────────────────────────────────────────────────────
+  // Only gate the exit code when --fail-below is explicitly requested;
+  // a plain scan reports findings and exits 0 (CI gating belongs to `scan ci`).
+  // Use process.exitCode (natural event-loop drain) instead of process.exit()
+  // so in-flight libuv handles (plugin dynamic imports, etc.) close cleanly.
+  if (options.failBelow !== undefined) {
+    let threshold = 75;
+    if (options.failBelow === 'baseline') {
+      // Read baseline score from .praxis/hermes-baseline.json
+      const baselinePath = path.join(absolutePath, '.praxis', 'hermes-baseline.json');
+      try {
+        const baseline = JSON.parse(fs.readFileSync(baselinePath, 'utf-8'));
+        threshold = baseline.score || 0;
+        if (!machineOutput) {
+          console.log(chalk.gray(`  Baseline threshold: ${threshold}/100 (from ${baselinePath})`));
+        }
+      } catch {
+        if (!machineOutput) {
+          console.log(chalk.yellow(`  Warning: could not read baseline — using score 0 as threshold`));
+        }
+        threshold = 0;
+      }
+    } else {
+      const parsed = parseInt(options.failBelow, 10);
+      threshold = Number.isNaN(parsed) ? 75 : parsed;
+    }
+    process.exitCode = scoreResult.score >= threshold ? 0 : 1;
+  }
+}
+
+/**
+ * Run a lightweight inner audit that returns { score, findings } without
+ * calling process.exit(). Used exclusively by the --agentic loop.
+ */
+async function runAuditInner(targetPath, options) {
+  try {
+    return await auditCommand(targetPath, options);
+  } catch {
+    return null;
+  }
+}
+
+// =============================================================================
+// REMEDIATION PLAN BUILDER
+// =============================================================================
+
+function buildRemediationPlan(findings, depVulns, rootPath) {
+  const plan = [];
+  let priority = 1;
+
+  // Exclude low-confidence findings (test files, docs, comments) from remediation plan
+  const actionable = findings.filter(f => f.confidence !== 'low');
+
+  // Priority order: secrets first, then by severity
+  const secretFindings = actionable.filter(f => f.category === 'secrets' || f.category === 'secret');
+  const otherFindings = actionable.filter(f => f.category !== 'secrets' && f.category !== 'secret');
+
+  // Group and sort
+  for (const sev of SEV_ORDER) {
+    // Secrets at this severity — group .env findings by file
+    const sevSecrets = secretFindings.filter(s => s.severity === sev);
+    const envGroups = new Map();
+    const nonEnvSecrets = [];
+
+    for (const f of sevSecrets) {
+      const relFile = path.relative(rootPath, f.file).replace(/\\/g, '/');
+      if (f.file.match(/\.env(\..*)?$/)) {
+        if (!envGroups.has(relFile)) envGroups.set(relFile, []);
+        envGroups.get(relFile).push(f);
+      } else {
+        nonEnvSecrets.push(f);
+      }
+    }
+
+    // One plan item per .env file
+    for (const [relFile, envFindings] of envGroups) {
+      const names = envFindings.map(f => f.title || f.rule).join(', ');
+      plan.push({
+        priority: priority++,
+        severity: sev,
+        category: 'secrets',
+        categoryLabel: 'SECRETS',
+        title: `${envFindings.length} secret${envFindings.length > 1 ? 's' : ''} in ${relFile} (${names})`,
+        file: relFile,
+        action: envFindings[0].fix || 'Ensure .env is in .gitignore and use a secrets manager for production',
+        effort: 'low',
+      });
+    }
+
+    // Individual items for non-.env secrets
+    for (const f of nonEnvSecrets) {
+      plan.push({
+        priority: priority++,
+        severity: sev,
+        category: 'secrets',
+        categoryLabel: 'SECRETS',
+        title: f.title || f.rule,
+        file: `${path.relative(rootPath, f.file).replace(/\\/g, '/')}:${f.line}`,
+        action: f.aiFix || f.fix || f.description,
+        effort: 'low',
+      });
+    }
+
+    // Other findings at this severity
+    for (const f of otherFindings.filter(s => s.severity === sev)) {
+      plan.push({
+        priority: priority++,
+        severity: sev,
+        category: f.category,
+        categoryLabel: (CATEGORY_LABELS[f.category] || f.category).toUpperCase(),
+        title: f.title || f.rule,
+        file: `${path.relative(rootPath, f.file).replace(/\\/g, '/')}:${f.line}`,
+        action: f.aiFix || f.fix || f.description,
+        effort: EFFORT_MAP[f.category] || 'medium',
+      });
+    }
+
+    // Dep vulns at this severity
+    for (const d of depVulns.filter(v => v.severity === sev || (sev === 'medium' && v.severity === 'moderate'))) {
+      plan.push({
+        priority: priority++,
+        severity: sev,
+        category: 'deps',
+        categoryLabel: 'DEPENDENCIES',
+        title: `Vulnerable: ${d.package || d.id}`,
+        file: 'package.json',
+        action: d.description ? `${d.description.slice(0, 80)}` : 'Update to patched version',
+        effort: 'medium',
+      });
+    }
+  }
+
+  return plan;
+}
+
+// =============================================================================
+// CONSOLE OUTPUT
+// =============================================================================
+
+function printReport(scoreResult, findings, depVulns, recon, plan, rootPath, filesScanned) {
+  const GRADE_COLOR = { A: chalk.green.bold, B: chalk.cyan.bold, C: chalk.yellow.bold, D: chalk.red, F: chalk.red.bold };
+  const SEV_ICON = { critical: '🔴', high: '🟠', medium: '🟡', low: '🔵' };
+  const SEV_LABEL = { critical: 'CRITICAL — fix immediately', high: 'HIGH — fix before deploy', medium: 'MEDIUM — fix soon', low: 'LOW — review when possible' };
+
+  // ── Score ─────────────────────────────────────────────────────────────────
+  const gradeColor = GRADE_COLOR[scoreResult.grade.letter] || chalk.white;
+  const scoreColor = scoreResult.score >= 75 ? chalk.green.bold : scoreResult.score >= 60 ? chalk.yellow.bold : chalk.red.bold;
+
+  console.log(chalk.cyan('  ' + '═'.repeat(56)));
+  console.log(
+    chalk.white.bold('  Security Score: ') +
+    scoreColor(`${scoreResult.score}/100 `) +
+    gradeColor(scoreResult.grade.letter) +
+    chalk.gray(` — ${scoreResult.grade.label}`)
+  );
+  console.log(chalk.cyan('  ' + '═'.repeat(56)));
+  console.log();
+
+  // ── Category Breakdown ────────────────────────────────────────────────────
+  console.log(chalk.white.bold('  Category Breakdown'));
+  console.log(chalk.gray('  ' + '─'.repeat(56)));
+
+  for (const [key, cat] of Object.entries(scoreResult.categories)) {
+    const count = Object.values(cat.counts).reduce((a, b) => a + b, 0);
+    const icon = count === 0 ? chalk.green('✔') : chalk.red('✘');
+    const status = count === 0 ? chalk.green('clean') : chalk.red(`${count} issue(s)`);
+    const deduction = cat.deduction > 0 ? chalk.red(`-${Math.round(cat.deduction * 10) / 10} pts`) : chalk.gray('+0');
+    console.log(`  ${icon}  ${chalk.white(cat.label.padEnd(22))} ${status.padEnd(25)} ${deduction}`);
+  }
+
+  // Deps row — only print if not already included in scoreResult.categories
+  const hasDepsCategory = Object.values(scoreResult.categories).some(c => c.label?.toLowerCase().includes('depend'));
+  if (!hasDepsCategory) {
+    const depIcon = depVulns.length === 0 ? chalk.green('✔') : chalk.red('✘');
+    const depStatus = depVulns.length === 0 ? chalk.green('clean') : chalk.red(`${depVulns.length} CVE(s)`);
+    console.log(`  ${depIcon}  ${chalk.white('Dependencies'.padEnd(22))} ${depStatus}`);
+  }
+
+  console.log(chalk.gray(`\n  Files scanned: ${filesScanned} | Findings: ${findings.length} | CVEs: ${depVulns.length}`));
+
+  // ── Remediation Plan ──────────────────────────────────────────────────────
+  if (plan.length > 0) {
+    console.log();
+    console.log(chalk.cyan('  ' + '═'.repeat(56)));
+    console.log(chalk.cyan.bold('  Remediation Plan'));
+    console.log(chalk.cyan('  ' + '═'.repeat(56)));
+
+    let currentSev = null;
+    let shown = 0;
+    const maxItems = 30;
+
+    for (const item of plan) {
+      if (shown >= maxItems) {
+        console.log(chalk.gray(`\n  ... and ${plan.length - maxItems} more items in the full report`));
+        break;
+      }
+
+      if (item.severity !== currentSev) {
+        currentSev = item.severity;
+        console.log();
+        console.log(chalk.white.bold(`  ${SEV_ICON[currentSev] || '⚪'} ${SEV_LABEL[currentSev] || currentSev.toUpperCase()}`));
+        console.log(chalk.gray('  ' + '─'.repeat(56)));
+      }
+
+      console.log(
+        chalk.white(`  ${String(item.priority).padStart(2)}.`) +
+        chalk.gray(` [${item.categoryLabel}] `) +
+        chalk.white(item.title)
+      );
+      console.log(
+        chalk.gray(`      ${item.file}`) +
+        chalk.gray(' → ') +
+        chalk.green((item.action || '').slice(0, 70))
+      );
+      shown++;
+    }
+  } else {
+    console.log();
+    console.log(chalk.green.bold('  All clear — safe to ship!'));
+  }
+
+  // ── Attack Surface ────────────────────────────────────────────────────────
+  if (recon) {
+    console.log();
+    console.log(chalk.gray('  Attack Surface:'));
+    if (recon.frameworks?.length) console.log(chalk.gray(`    Frameworks:  ${recon.frameworks.join(', ')}`));
+    if (recon.databases?.length) console.log(chalk.gray(`    Databases:   ${recon.databases.join(', ')}`));
+    if (recon.authPatterns?.length) console.log(chalk.gray(`    Auth:        ${recon.authPatterns.join(', ')}`));
+    if (recon.apiRoutes?.length) console.log(chalk.gray(`    API Routes:  ${recon.apiRoutes.length} discovered`));
+  }
+}
+
+// =============================================================================
+// JSON OUTPUT
+// =============================================================================
+
+function outputJSON(scoreResult, findings, depVulns, recon, agentResults, remediationPlan, suppressions, history, filesScanned = null) {
+  const output = {
+    score: scoreResult.score,
+    grade: scoreResult.grade.letter,
+    gradeLabel: scoreResult.grade.label,
+    totalFindings: findings.length,
+    totalDepVulns: depVulns.length,
+    categories: Object.fromEntries(
+      Object.entries(scoreResult.categories).map(([k, v]) => [k, {
+        label: v.label,
+        findingCount: Object.values(v.counts).reduce((a, b) => a + b, 0),
+        deduction: v.deduction,
+        counts: v.counts,
+      }])
+    ),
+    findings: findings.map(f => {
+      const normFile = String(f.file || '')
+        .replace(/\\/g, '/')
+        .replace(/^[a-zA-Z]:\/+/, '')
+        .replace(/^.*\/Praxis\/showcase-target\//, 'showcase-target/')
+        .replace(/^.*\/Praxis\//, '');
+      return {
+        file: normFile, line: f.line, severity: f.severity, category: f.category,
+        rule: f.rule, title: f.title, description: f.description, fix: f.fix,
+        cwe: f.cwe, owasp: f.owasp,
+        ...(f.eaa ? { eaa: f.eaa } : {}),
+        ...(f.confidence ? { confidence: f.confidence } : {}),
+        ...(f.standards ? { standards: f.standards } : {}),
+        ...(f.deepAnalysis ? { deepAnalysis: f.deepAnalysis } : {}),
+        ...(f.aiClassification ? {
+          aiClassification: f.aiClassification,
+          ...(f.aiReason ? { aiReason: f.aiReason } : {}),
+          ...(f.aiFix ? { aiFix: f.aiFix } : {}),
+        } : {}),
+      };
+    }),
+    depVulns: depVulns.map(d => ({
+      severity: d.severity, package: d.package || d.id, description: d.description,
+    })),
+    remediationPlan,
+    recon,
+    agents: agentResults,
+    // Provenance: which tool, runtime and vendored data produced these numbers (P-IMP-053).
+    fingerprint: buildScanFingerprint({ filesScanned }),
+  };
+  if (scoreResult.compliance) output.compliance = scoreResult.compliance;
+  if (scoreResult.standardsSummary) output.standardsSummary = scoreResult.standardsSummary;
+  if (scoreResult.agenticSummary) output.agenticSummary = scoreResult.agenticSummary;
+  if (suppressions) output.suppressions = suppressions;
+  if (history && history.length >= 2) {
+    const prev = history[history.length - 2];
+    output.comparison = {
+      previousScore: prev.score,
+      previousGrade: prev.grade,
+      previousDate: prev.timestamp,
+      diff: scoreResult.score - prev.score,
+      categoryComparison: Object.fromEntries(
+        Object.entries(scoreResult.categories).map(([k, v]) => {
+          const prevCat = prev.categoryScores?.[k];
+          return [k, {
+            label: v.label,
+            current: -v.deduction,
+            previous: prevCat ? -prevCat.deduction : 0,
+            delta: prevCat ? prevCat.deduction - v.deduction : 0,
+          }];
+        })
+      ),
+    };
+  }
+  console.log(JSON.stringify(output, null, 2));
+}
+
+// =============================================================================
+// SARIF OUTPUT
+// =============================================================================
+
+/**
+ * SARIF for GitHub Code Scanning.
+ *
+ * Delegates to the shared serializer in `cli/core/output/sarif.js` (P-IMP-062). This was
+ * a private copy, hardcoding a driver version of `4.0.0` while the package was at a
+ * different number entirely, and it carried no `security-severity` — so the default
+ * `praxis scan` lost severity fidelity in Code Scanning.
+ */
+function outputSARIF(findings, rootPath) {
+  console.log(renderFindingsSARIF(findings, { rootPath }));
+}
+
+// =============================================================================
+// FILE SCANNING (inline from scan.js to avoid circular deps)
+// =============================================================================
+
+// Walk up from `start` looking for `name`. Returns the absolute path or null.
+// Bounded to 8 ancestors to avoid runaway loops on weird filesystems.
+function findUpwards(start, name) {
+  let dir = path.resolve(start);
+  for (let i = 0; i < 8; i++) {
+    const candidate = path.join(dir, name);
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+  return null;
+}
+
+async function findFiles(rootPath) {
+  const globIgnore = Array.from(SKIP_DIRS).map(dir => `**/${dir}/**`);
+
+  // Respect .gitignore patterns
+  const gitignoreGlobs = loadGitignorePatterns(rootPath);
+  globIgnore.push(...gitignoreGlobs);
+
+  // Load .praxisignore — walk up to the project root so subdirectory scans
+  // still honor the repo-level ignore file.
+  const ignorePath = findUpwards(rootPath, '.praxisignore');
+  if (ignorePath) {
+    try {
+      const patterns = fs.readFileSync(ignorePath, 'utf-8')
+        .split('\n').map(l => l.trim()).filter(l => l && !l.startsWith('#'));
+      for (const p of patterns) {
+        if (p.endsWith('/')) { globIgnore.push(`**/${p}**`); }
+        else { globIgnore.push(`**/${p}`); globIgnore.push(p); }
+      }
+    } catch { /* skip */ }
+  }
+
+  const files = await fg('**/*', {
+    cwd: rootPath, absolute: true, onlyFiles: true, ignore: globIgnore, dot: true
+  });
+
+  return files.filter(file => {
+    const ext = path.extname(file).toLowerCase();
+    if (SKIP_EXTENSIONS.has(ext)) return false;
+    if (SKIP_FILENAMES.has(path.basename(file))) return false;
+    if (path.basename(file).endsWith('.min.js') || path.basename(file).endsWith('.min.css')) return false;
+    try { if (fs.statSync(file).size > MAX_FILE_SIZE) return false; } catch { return false; }
+    return true;
+  });
+}
+
+function scanFileForSecrets(filePath) {
+  const findings = [];
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const lines = content.split('\n');
+    for (let lineNum = 0; lineNum < lines.length; lineNum++) {
+      const line = lines[lineNum];
+      if (/praxis-ignore/i.test(line)) continue;
+      for (const pattern of SECRET_PATTERNS) {
+        pattern.pattern.lastIndex = 0;
+        let match;
+        while ((match = pattern.pattern.exec(line)) !== null) {
+          if (pattern.requiresEntropyCheck && !isHighEntropyMatch(match[0])) continue;
+          findings.push({
+            line: lineNum + 1, column: match.index + 1, matched: match[0],
+            patternName: pattern.name, severity: pattern.severity,
+            confidence: getConfidence(pattern, match[0]),
+            description: pattern.description, category: pattern.category || 'secret'
+          });
+        }
+      }
+    }
+  } catch { /* skip */ }
+
+  const seen = new Set();
+  return findings.filter(f => {
+    const key = `${f.line}:${f.matched}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function deduplicateFindings(findings) {
+  const seen = new Set();
+  return findings.filter(f => {
+    const key = `${f.file}:${f.line}:${f.rule}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+// =============================================================================
+// SUPPRESSION COUNTING
+// =============================================================================
+
+function countSuppressions(files) {
+  const suppressions = {};
+  let total = 0;
+  for (const file of files) {
+    try {
+      const content = fs.readFileSync(file, 'utf-8');
+      const lines = content.split('\n');
+      for (const line of lines) {
+        if (/praxis-ignore/i.test(line)) {
+          total++;
+          // Try to extract rule name from comment: praxis-ignore RULE_NAME
+          const match = line.match(/praxis-ignore\s+(\w+)/i);
+          const rule = match ? match[1] : '_unspecified';
+          suppressions[rule] = (suppressions[rule] || 0) + 1;
+        }
+      }
+    } catch { /* skip */ }
+  }
+  return total > 0 ? { total, rules: suppressions } : null;
+}
+
+// =============================================================================
+// CSV OUTPUT
+// =============================================================================
+
+function outputCSV(findings, depVulns, scoreResult, rootPath) {
+  const escape = (s) => {
+    if (!s) return '';
+    const str = String(s).replace(/"/g, '""');
+    return str.includes(',') || str.includes('"') || str.includes('\n') ? `"${str}"` : str;
+  };
+
+  console.log('severity,category,rule,file,line,title,description,fix');
+  for (const f of findings) {
+    const relFile = path.relative(rootPath, f.file).replace(/\\/g, '/');
+    console.log([
+      escape(f.severity), escape(f.category), escape(f.rule),
+      escape(relFile), f.line || '', escape(f.title),
+      escape(f.description), escape(f.fix),
+    ].join(','));
+  }
+  for (const d of depVulns) {
+    console.log([
+      escape(d.severity), 'deps', escape(d.id || d.package),
+      'package.json', '', escape(`Vulnerable: ${d.package || d.id}`),
+      escape(d.description), escape('Update to patched version'),
+    ].join(','));
+  }
+}
+
+// =============================================================================
+// MARKDOWN OUTPUT
+// =============================================================================
+
+function outputMarkdown(scoreResult, findings, depVulns, remediationPlan, rootPath) {
+  const lines = [];
+  lines.push('# Praxis Security Report');
+  lines.push('');
+  lines.push(`**Score: ${scoreResult.score}/100 (${scoreResult.grade.letter})** — ${scoreResult.grade.label}`);
+  lines.push('');
+  lines.push(`> Generated: ${new Date().toISOString()}`);
+  lines.push('');
+
+  // Category breakdown
+  lines.push('## Category Breakdown');
+  lines.push('');
+  lines.push('| Category | Issues | Deduction |');
+  lines.push('|----------|--------|-----------|');
+  for (const [, cat] of Object.entries(scoreResult.categories)) {
+    const count = Object.values(cat.counts).reduce((a, b) => a + b, 0);
+    lines.push(`| ${cat.label} | ${count} | -${cat.deduction} |`);
+  }
+  lines.push('');
+
+  // Findings by severity
+  for (const sev of SEV_ORDER) {
+    const sevFindings = findings.filter(f => f.severity === sev);
+    if (sevFindings.length === 0) continue;
+
+    lines.push(`## ${sev.charAt(0).toUpperCase() + sev.slice(1)} (${sevFindings.length})`);
+    lines.push('');
+    lines.push('| File | Rule | Description | Fix |');
+    lines.push('|------|------|-------------|-----|');
+    for (const f of sevFindings) {
+      const relFile = path.relative(rootPath, f.file).replace(/\\/g, '/');
+      lines.push(`| ${relFile}:${f.line} | ${f.rule} | ${(f.description || '').slice(0, 80)} | ${(f.fix || '').slice(0, 60)} |`);
+    }
+    lines.push('');
+  }
+
+  // Dep vulns
+  if (depVulns.length > 0) {
+    lines.push('## Dependency Vulnerabilities');
+    lines.push('');
+    lines.push('| Severity | Package | Description |');
+    lines.push('|----------|---------|-------------|');
+    for (const d of depVulns) {
+      lines.push(`| ${d.severity} | ${d.package || d.id} | ${(d.description || '').slice(0, 80)} |`);
+    }
+    lines.push('');
+  }
+
+  console.log(lines.join('\n'));
+}
+
+// =============================================================================
+// COMPARISON OUTPUT
+// =============================================================================
+
+function printComparison(scoringEngine, rootPath, scoreResult) {
+  const history = scoringEngine.loadHistory(rootPath);
+  if (history.length < 2) {
+    console.log(chalk.gray('\n  No previous scan to compare against.'));
+    return;
+  }
+
+  const prev = history[history.length - 2];
+  console.log();
+  console.log(chalk.cyan.bold('  Detailed Comparison'));
+  console.log(chalk.gray('  ' + '─'.repeat(56)));
+  console.log(chalk.gray(`  Previous scan: ${new Date(prev.timestamp).toLocaleString()}`));
+  console.log();
+  console.log(chalk.white('  Category'.padEnd(26)) + chalk.white('Previous'.padEnd(12)) + chalk.white('Current'.padEnd(12)) + chalk.white('Delta'));
+  console.log(chalk.gray('  ' + '─'.repeat(56)));
+
+  for (const [key, cat] of Object.entries(scoreResult.categories)) {
+    const prevCat = prev.categoryScores?.[key];
+    const prevDed = prevCat ? prevCat.deduction : 0;
+    const curDed = cat.deduction;
+    const delta = prevDed - curDed;
+
+    let deltaStr;
+    if (delta > 0) deltaStr = chalk.green(`+${delta} improved`);
+    else if (delta < 0) deltaStr = chalk.red(`${delta} regressed`);
+    else deltaStr = chalk.gray('→ unchanged');
+
+    console.log(
+      `  ${chalk.white(cat.label.padEnd(24))}` +
+      `${chalk.gray(String(-prevDed).padEnd(12))}` +
+      `${chalk.gray(String(-curDed).padEnd(12))}` +
+      deltaStr
+    );
+  }
+
+  const overallDiff = scoreResult.score - prev.score;
+  let overallDelta;
+  if (overallDiff > 0) overallDelta = chalk.green(`+${overallDiff} improved`);
+  else if (overallDiff < 0) overallDelta = chalk.red(`${overallDiff} regressed`);
+  else overallDelta = chalk.gray('→ unchanged');
+
+  console.log(chalk.gray('  ' + '─'.repeat(56)));
+  console.log(
+    `  ${chalk.white.bold('Overall'.padEnd(24))}` +
+    `${chalk.gray(`${prev.score}/100 ${prev.grade}`.padEnd(12))}` +
+    `${chalk.gray(`${scoreResult.score}/100 ${scoreResult.grade.letter}`.padEnd(12))}` +
+    overallDelta
+  );
+}