praxis-sec 1.2.1 → 1.2.4

package/cli/commands/audit.js

@@ -1,1228 +1,1272 @@
-/**
- * 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 '../core/glob.js';
-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';
-import { isGitUrl, cloneGitRepo, redactGitUrl } from '../core/git-clone.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 machineOutput = options.json || options.sarif || options.csv || options.md;
-  let gitClone = null;
-  let effectivePath = targetPath;
-
-  // ── Remote Git Repository Support ─────────────────────────────────────────
-  if (isGitUrl(targetPath)) {
-    if (!machineOutput) printBanner();
-    const gitSpinner = machineOutput ? null : ora({ text: chalk.cyan(`Cloning remote Git repository: ${redactGitUrl(targetPath)}...`), color: 'cyan' }).start();
-    try {
-      gitClone = cloneGitRepo(targetPath, {
-        branch: options.branch,
-        depth: options.depth,
-        gitToken: options.gitToken,
-        submodules: options.submodules,
-        gitHistory: options.gitHistory,
-      });
-      effectivePath = gitClone.tempDir;
-      if (gitSpinner) gitSpinner.succeed(chalk.green(`Cloned ${gitClone.repoName} (${gitClone.displayUrl}) to temporary workspace`));
-    } catch (err) {
-      if (gitSpinner) gitSpinner.fail(chalk.red(err.message));
-      else console.error(chalk.red(err.message));
-      process.exitCode = 1;
-      return;
-    }
-  }
-
-  try {
-    const absolutePath = path.resolve(effectivePath);
-
-    if (!fs.existsSync(absolutePath)) {
-      console.error(chalk.red(`  Path does not exist: ${absolutePath}`));
-      process.exitCode = 1;
-      return;
-    }
-
-    if (!machineOutput && !gitClone) {
-      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, trustPlugins: !gitClone && options.trustPlugins === 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;
-    // Deliberately NOT passing `changedFiles` to the orchestrator.
-    //
-    // BaseAgent.getFilesToScan() returns `context.changedFiles || context.files`,
-    // so passing it makes an agent scan only changed files — and on an unchanged
-    // tree that list is empty, so the agent reports nothing at all. The cache
-    // cannot cover for that: the restore below is filtered to
-    // `category === 'secrets'`, so agent findings for unchanged files were never
-    // coming back. A warm scan silently lost every finding from
-    // PromptInjectionProberAgent, VibeCodingAgent and ExceptionHandlerAgent —
-    // 9 findings on this tree, under-reporting on the second run of any project.
-    //
-    // 25 of 28 agents already ignore `changedFiles` and read `context.files`, so
-    // the hint only ever narrowed three of them while making them wrong. Phase 1
-    // (secrets) is where the cache actually pays for itself, and it still uses
-    // it. Passing an unsafe optimisation is worse than not optimising.
-    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`));
-    }
-  }
-
-  // ── 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);
-
-  // Score and filtered findings must exist before the best-effort playbook update.
-  try {
-    const playbook = new ScanPlaybook(absolutePath);
-    const suppressedRules = secMemory.list().map(entry => entry.rule).filter(Boolean);
-    playbook.update(recon, { score: scoreResult.score, grade: scoreResult.grade?.letter || scoreResult.grade, totalFindings: filteredFindings.length }, filteredFindings, suppressedRules);
-  } catch { /* non-fatal */ }
-
-  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;
-  }
-  } finally {
-    if (gitClone) {
-      if (!options.keepClone) {
-        gitClone.cleanup();
-      } else if (!machineOutput) {
-        console.log(chalk.gray(`\n  Cloned repository retained at: ${gitClone.tempDir}`));
-      }
-    }
-  }
-}
-
-/**
- * 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.
-    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`. 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
-  );
-}
+/**
+ * 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 { displayPath } from '../core/paths.js';
+import { validateDir } from '../core/fs.js';
+import fg from '../core/glob.js';
+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, isDocumentedSecretExample } 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';
+import { isGitUrl, cloneGitRepo, redactGitUrl } from '../core/git-clone.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 machineOutput = options.json || options.sarif || options.csv || options.md;
+  let gitClone = null;
+  let effectivePath = targetPath;
+
+  // ── Remote Git Repository Support ─────────────────────────────────────────
+  if (isGitUrl(targetPath)) {
+    if (!machineOutput) printBanner();
+    const gitSpinner = machineOutput ? null : ora({ text: chalk.cyan(`Cloning remote Git repository: ${redactGitUrl(targetPath)}...`), color: 'cyan' }).start();
+    try {
+      gitClone = cloneGitRepo(targetPath, {
+        branch: options.branch,
+        depth: options.depth,
+        gitToken: options.gitToken,
+        submodules: options.submodules,
+        gitHistory: options.gitHistory,
+      });
+      effectivePath = gitClone.tempDir;
+      if (gitSpinner) gitSpinner.succeed(chalk.green(`Cloned ${gitClone.repoName} (${gitClone.displayUrl}) to temporary workspace`));
+    } catch (err) {
+      if (gitSpinner) gitSpinner.fail(chalk.red(err.message));
+      else console.error(chalk.red(err.message));
+      process.exitCode = 1;
+      return;
+    }
+  }
+
+  try {
+    const absolutePath = validateDir(effectivePath, { exitOnMissing: false });
+
+    if (!absolutePath) {
+      console.error(chalk.red('  Full scans require an existing directory.'));
+      process.exitCode = 1;
+      return;
+    }
+
+    if (!machineOutput && !gitClone) {
+      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 = [];
+  const scanErrors = [];
+
+  // ── 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({
+          // Normalised here so secret findings are indistinguishable from agent
+          // findings by the time anything renders them.
+          file: displayPath(file, absolutePath),
+          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) {
+    scanErrors.push({ phase: 'secrets', message: err.message });
+    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, trustPlugins: !gitClone && options.trustPlugins === 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, timeout: options.timeout };
+    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;
+    // Deliberately NOT passing `changedFiles` to the orchestrator.
+    //
+    // BaseAgent.getFilesToScan() returns `context.changedFiles || context.files`,
+    // so passing it makes an agent scan only changed files — and on an unchanged
+    // tree that list is empty, so the agent reports nothing at all. The cache
+    // cannot cover for that: the restore below is filtered to
+    // `category === 'secrets'`, so agent findings for unchanged files were never
+    // coming back. A warm scan silently lost every finding from
+    // PromptInjectionProberAgent, VibeCodingAgent and ExceptionHandlerAgent —
+    // 9 findings on this tree, under-reporting on the second run of any project.
+    //
+    // 25 of 28 agents already ignore `changedFiles` and read `context.files`, so
+    // the hint only ever narrowed three of them while making them wrong. Phase 1
+    // (secrets) is where the cache actually pays for itself, and it still uses
+    // it. Passing an unsafe optimisation is worse than not optimising.
+    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;
+    for (const agent of agentResults.filter(agent => !agent.success)) {
+      scanErrors.push({ phase: 'agents', message: `${agent.agent}: ${agent.error || 'scan failed'}` });
+    }
+
+    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) {
+    scanErrors.push({ phase: 'agents', message: err.message });
+    if (agentSpinner) agentSpinner.fail(chalk.red(`[Phase 2/4] Agent scan failed: ${err.message}`));
+  }
+
+  // ── Phase 3: Dependency Audit ─────────────────────────────────────────────
+  let depVulns = [];
+  let dependencyAudit = options.deps === false ? 'skipped' : 'not-applicable';
+  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 || [];
+      dependencyAudit = depResult.error ? 'failed' : (depResult.pm ? 'complete' : 'not-applicable');
+      if (depResult.error) {
+        scanErrors.push({ phase: 'dependencies', message: depResult.error });
+        if (depSpinner) depSpinner.fail(chalk.red('[Phase 3/4] Dependency audit incomplete'));
+      } else 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 (err) {
+      dependencyAudit = 'failed';
+      scanErrors.push({ phase: 'dependencies', message: err.message });
+      if (depSpinner) depSpinner.fail(chalk.red('[Phase 3/4] Dependency audit incomplete'));
+    }
+  } 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 (err) {
+      scanErrors.push({ phase: 'legal', message: err.message });
+      if (legalSpinner) legalSpinner.fail(chalk.red('[Phase 3b] Legal scan incomplete'));
+    }
+  }
+
+  // ── 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`));
+    }
+  }
+
+  // ── 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);
+  const scanComplete = scanErrors.length === 0;
+  scoreResult.scanComplete = scanComplete;
+  scoreResult.scanErrors = scanErrors;
+  scoreResult.dependencyAudit = dependencyAudit;
+  if (!scanComplete) {
+    console.error('[praxis] Scan incomplete; the score reflects only available results.');
+    for (const error of scanErrors) console.error(`[praxis] ${error.phase}: ${error.message}`);
+  }
+  // Round score to 1 decimal place to avoid floating-point noise (e.g., 63.300000000000004)
+  scoreResult.score = Math.round(scoreResult.score * 10) / 10;
+  if (scanComplete) scoringEngine.saveToHistory(absolutePath, scoreResult, suppressions);
+
+  // Score and filtered findings must exist before the best-effort playbook update.
+  try {
+    if (scanComplete) {
+      const playbook = new ScanPlaybook(absolutePath);
+      const suppressedRules = secMemory.list().map(entry => entry.rule).filter(Boolean);
+      playbook.update(recon, { score: scoreResult.score, grade: scoreResult.grade?.letter || scoreResult.grade, totalFindings: filteredFindings.length }, filteredFindings, suppressedRules);
+    }
+  } catch { /* non-fatal */ }
+
+  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 && scanComplete) {
+    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, scanComplete, scanErrors, dependencyAudit };
+  }
+
+  // ── 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.
+  let verificationComplete = true;
+  if (options.agentic && !options._agenticInner && scanComplete) {
+    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, absolutePath);
+      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: true,
+        sarif: false,
+        csv: false,
+        md: false,
+        html: false,
+        pdf: false,
+        quiet: true,
+      });
+
+      const prevScore = currentScore;
+      if (innerResult?.scanComplete !== true) {
+        console.error('[praxis] Agentic loop stopped: verification scan incomplete.');
+        verificationComplete = false;
+        scoreResult.scanComplete = false;
+        scanErrors.push({ phase: 'verification', message: 'Agentic verification scan incomplete' });
+        process.exitCode = 1;
+        break;
+      }
+      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 (verificationComplete && 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}`));
+      }
+    }
+  }
+
+  // ── 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, absolutePath);
+  } 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();
+  }
+
+  // ── 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 (!scanComplete || !verificationComplete) process.exitCode = 1;
+  if (scanComplete && verificationComplete && 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;
+  }
+  } finally {
+    if (gitClone) {
+      if (!options.keepClone) {
+        gitClone.cleanup();
+      } else if (!machineOutput) {
+        console.log(chalk.gray(`\n  Cloned repository retained at: ${gitClone.tempDir}`));
+      }
+    }
+  }
+}
+
+/**
+ * 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 = displayPath(f.file, rootPath);
+      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: `${displayPath(f.file, rootPath)}:${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: `${displayPath(f.file, rootPath)}:${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, absolutePath = process.cwd()) {
+  const output = {
+    score: scoreResult.score,
+    scanComplete: scoreResult.scanComplete,
+    scanErrors: scoreResult.scanErrors,
+    dependencyAudit: scoreResult.dependencyAudit,
+    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 => {
+      return {
+        // Secret findings are built here rather than by an agent, so they never
+        // pass through the orchestrator's normalisation. Do it at the source —
+        // see cli/core/paths.js. This used to be the fourth copy of the same
+        // strippers, which is how an absolute path reached the JSON report with
+        // its drive letter removed and the username left behind.
+        file: displayPath(f.file, absolutePath),
+        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.
+    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`. 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 (isDocumentedSecretExample(pattern.name, match[0])) continue;
+
+          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 = displayPath(f.file, rootPath);
+    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 = displayPath(f.file, rootPath);
+      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
+  );
+}