@kevinrabun/judges 3.38.0 → 3.41.0

package/dist/cli.js

@@ -42,6 +42,8 @@ import { generateGitLabCi, generateAzurePipelines, generateBitbucketPipelines }
 import { getPreset, listPresets, composePresets } from "./presets.js";
 import { parseConfig } from "./config.js";
 import { applyPatches } from "./commands/fix.js";
+import { DiskCache } from "./disk-cache.js";
+import { contentHash } from "./cache.js";
 import { runFeedback } from "./commands/feedback.js";
 import { runBenchmark } from "./commands/benchmark.js";
 import { runRule } from "./commands/rule.js";
@@ -50,6 +52,8 @@ import { runConfig } from "./commands/config-share.js";
 import { runDoctor } from "./commands/doctor.js";
 import { runTriage } from "./commands/triage.js";
 import { formatComparisonReport, formatFullComparisonMatrix, TOOL_PROFILES } from "./comparison.js";
+import { runOverride, loadOverrideStore, applyOverrides } from "./commands/override.js";
+import { runNotify } from "./commands/notify.js";
 // ─── Language Detection from Extension ──────────────────────────────────────
 const EXT_TO_LANG = {
     ".ts": "typescript",
@@ -117,8 +121,12 @@ function parseCliArgs(argv) {
         include: [],
         maxFiles: undefined,
         changedOnly: false,
+        stagedOnly: false,
         explain: false,
         sample: false,
+        trace: false,
+        incremental: false,
+        noCache: false,
     };
     // First non-flag arg is the command
     let i = 2; // skip node + script
@@ -185,6 +193,9 @@ function parseCliArgs(argv) {
             case "--changed-only":
                 args.changedOnly = true;
                 break;
+            case "--staged-only":
+                args.stagedOnly = true;
+                break;
             case "--explain":
                 args.explain = true;
                 break;
@@ -202,6 +213,15 @@ function parseCliArgs(argv) {
             case "--sample":
                 args.sample = true;
                 break;
+            case "--trace":
+                args.trace = true;
+                break;
+            case "--incremental":
+                args.incremental = true;
+                break;
+            case "--no-cache":
+                args.noCache = true;
+                break;
             default:
                 // If it looks like a file path (not a flag), treat as --file
                 if (!arg.startsWith("-") && !args.file) {
@@ -223,6 +243,7 @@ USAGE:
   judges init                         Interactive project setup wizard
   judges fix <file> [--apply]         Preview / apply auto-fixes
                                      --rule <id>  --severity <level>  --lines <start>-<end>
+  judges fix-pr <path>               Create a PR with auto-fix patches (like Dependabot)
   judges watch <path>                 Watch files and re-evaluate on save
   judges lsp                          Start LSP server for editor integration
   judges trend [file]                 Show findings trend from snapshots
@@ -244,6 +265,14 @@ USAGE:
   judges compare                      Compare judges vs other tools
   judges review                       Post inline review comments on a GitHub PR
   judges app serve                    Start GitHub App webhook server (zero-config PR reviews)
+  judges notify                       Send results to Slack, Teams, or webhook endpoints
+  judges quality-gate                 Evaluate composite quality gate policies
+  judges auto-calibrate               Auto-tune thresholds from feedback history
+  judges dep-audit                    Correlate dependency vulnerabilities with code findings
+  judges monorepo                     Discover and evaluate monorepo packages
+  judges config-migrate               Migrate .judgesrc to current schema
+  judges deprecated                   List deprecated rules with migration guidance
+  judges dedup-report                 Cross-run finding deduplication report
   judges tune                         Analyze project and suggest optimal config
   judges list                         List all available judges
   judges version                      Show version information
@@ -273,6 +302,7 @@ EVAL OPTIONS:
   --fix                      Auto-fix findings after evaluation (applies patches in-place)
   --changed-only             Only evaluate files changed since last commit (uses git diff)
   --explain                  Enrich findings with OWASP/CWE learning context
+  --trace                    Show detailed decision trace for every finding
   --help, -h                 Show this help
 
 FIX OPTIONS:
@@ -526,6 +556,23 @@ function getGitChangedFiles(cwd) {
         return [];
     }
 }
+function getStagedFiles(cwd) {
+    try {
+        const resolvedCwd = resolve(cwd);
+        const output = execSync("git diff --cached --name-only --diff-filter=ACM", {
+            cwd: resolvedCwd,
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
+        }).trim();
+        return output
+            .split("\n")
+            .filter(Boolean)
+            .map((f) => resolve(resolvedCwd, f));
+    }
+    catch {
+        return [];
+    }
+}
 // ─── Format Output ──────────────────────────────────────────────────────────
 function formatTribunalOutput(verdict, format, filePath) {
     switch (format) {
@@ -613,10 +660,33 @@ function formatTextOutput(verdict) {
         lines.push("  " + "─".repeat(60));
         for (const f of critical.slice(0, 20)) {
             const fixTag = f.patch ? " 🔧" : "";
-            lines.push(`  [${f.severity.toUpperCase().padEnd(8)}] ${f.ruleId}: ${f.title}${fixTag}`);
+            const confTag = f.confidence !== undefined ? ` (${Math.round(f.confidence * 100)}% confidence)` : "";
+            lines.push(`  [${f.severity.toUpperCase().padEnd(8)}] ${f.ruleId}: ${f.title}${fixTag}${confTag}`);
             if (f.lineNumbers && f.lineNumbers.length > 0) {
                 lines.push(`             Line ${f.lineNumbers[0]}: ${f.description.slice(0, 100)}`);
             }
+            if (f.provenance) {
+                lines.push(`             Evidence: ${f.provenance}`);
+            }
+            if (f.evidenceBasis) {
+                lines.push(`             Basis: ${f.evidenceBasis}`);
+            }
+            if (f.evidenceChain && f.evidenceChain.steps.length > 0) {
+                lines.push(`             Impact: ${f.evidenceChain.impactStatement}`);
+                for (const step of f.evidenceChain.steps.slice(0, 3)) {
+                    const loc = step.line ? ` (L${step.line})` : "";
+                    lines.push(`               → [${step.source}]${loc} ${step.observation}`);
+                }
+            }
+            if (f.cweIds && f.cweIds.length > 0) {
+                lines.push(`             CWE: ${f.cweIds.join(", ")}`);
+            }
+            if (f.owaspLlmTop10) {
+                lines.push(`             OWASP LLM: ${f.owaspLlmTop10}`);
+            }
+            if (f.learnMoreUrl) {
+                lines.push(`             📖 Learn more: ${f.learnMoreUrl}`);
+            }
         }
         if (critical.length > 20) {
             lines.push(`  ... and ${critical.length - 20} more critical/high findings`);
@@ -650,13 +720,23 @@ function formatSingleJudgeTextOutput(evaluation) {
     lines.push(`  Findings : ${evaluation.findings.length}`);
     lines.push("");
     for (const f of evaluation.findings) {
-        lines.push(`  [${f.severity.toUpperCase().padEnd(8)}] ${f.ruleId}: ${f.title}`);
+        const confTag = f.confidence !== undefined ? ` (${Math.round(f.confidence * 100)}%)` : "";
+        lines.push(`  [${f.severity.toUpperCase().padEnd(8)}] ${f.ruleId}: ${f.title}${confTag}`);
         if (f.lineNumbers && f.lineNumbers.length > 0) {
             lines.push(`             Line ${f.lineNumbers[0]}: ${f.description.slice(0, 120)}`);
         }
+        if (f.provenance) {
+            lines.push(`             Evidence: ${f.provenance}`);
+        }
+        if (f.evidenceChain && f.evidenceChain.steps.length > 0) {
+            lines.push(`             Impact: ${f.evidenceChain.impactStatement}`);
+        }
         if (f.suggestedFix) {
             lines.push(`             Fix: ${f.suggestedFix.slice(0, 120)}`);
         }
+        if (f.learnMoreUrl) {
+            lines.push(`             📖 ${f.learnMoreUrl}`);
+        }
     }
     lines.push("");
     return lines.join("\n");
@@ -720,6 +800,12 @@ export async function runCli(argv) {
         runFix(argv);
         return; // runFix calls process.exit internally
     }
+    // ─── Fix-PR Command ──────────────────────────────────────────────────
+    if (args.command === "fix-pr") {
+        const { runFixPr } = await import("./commands/fix-pr.js");
+        await runFixPr(argv);
+        return;
+    }
     // ─── Watch Command ────────────────────────────────────────────────────
     if (args.command === "watch") {
         const { runWatch } = await import("./commands/watch.js");
@@ -782,11 +868,66 @@ export async function runCli(argv) {
         runFeedback(argv);
         return;
     }
+    // ─── Override Command ─────────────────────────────────────────────────
+    if (args.command === "override") {
+        runOverride(argv);
+        return;
+    }
+    // ─── Feedback-Rules Command ───────────────────────────────────────────
+    if (args.command === "feedback-rules") {
+        const { runFeedbackRules } = await import("./commands/feedback-rules.js");
+        runFeedbackRules(argv);
+        return;
+    }
+    // ─── Governance Command ───────────────────────────────────────────────
+    if (args.command === "governance") {
+        const { runGovernance } = await import("./commands/governance.js");
+        runGovernance(argv);
+        return;
+    }
+    // ─── Parity Command ──────────────────────────────────────────────────
+    if (args.command === "parity") {
+        const { runParity } = await import("./commands/parity.js");
+        runParity(argv);
+        return;
+    }
+    // ─── Compliance-Report Command ────────────────────────────────────────
+    if (args.command === "compliance-report") {
+        const { buildComplianceReport, formatComplianceReportText } = await import("./commands/compliance-report.js");
+        const target = args.file || ".";
+        const code = args.file ? (await import("fs")).readFileSync(args.file, "utf-8") : "";
+        let findings = [];
+        if (code) {
+            const lang = detectLanguage(args.file) || "typescript";
+            const result = evaluateWithTribunal(code, lang);
+            findings = result.findings;
+        }
+        const framework = argv.find((a, i) => argv[i - 1] === "--framework") || undefined;
+        const report = buildComplianceReport(target, findings, framework);
+        if (argv.includes("--json")) {
+            console.log(JSON.stringify(report, null, 2));
+        }
+        else {
+            console.log(formatComplianceReportText(report));
+        }
+        return;
+    }
     // ─── Triage Command ───────────────────────────────────────────────────
     if (args.command === "triage") {
         runTriage(argv);
         return;
     }
+    // ─── Quality-Gate Command ─────────────────────────────────────────────
+    if (args.command === "quality-gate") {
+        const { runQualityGate } = await import("./commands/quality-gate.js");
+        runQualityGate(argv);
+        return;
+    }
+    // ─── Notify Command ─────────────────────────────────────────────────
+    if (args.command === "notify") {
+        await runNotify(argv);
+        return;
+    }
     // ─── Benchmark Command ────────────────────────────────────────────────
     if (args.command === "benchmark") {
         runBenchmark(argv);
@@ -819,6 +960,42 @@ export async function runCli(argv) {
         runAppCommand(argv.slice(3));
         return;
     }
+    // ─── Auto-Calibrate Command ────────────────────────────────────────
+    if (args.command === "auto-calibrate") {
+        const { runAutoCalibrate } = await import("./commands/auto-calibrate.js");
+        runAutoCalibrate(argv);
+        return;
+    }
+    // ─── Dep-Audit Command ─────────────────────────────────────────────
+    if (args.command === "dep-audit") {
+        const { runDepAuditCommand } = await import("./commands/dep-audit.js");
+        runDepAuditCommand(argv);
+        return;
+    }
+    // ─── Monorepo Command ─────────────────────────────────────────────
+    if (args.command === "monorepo") {
+        const { runMonorepoCommand } = await import("./commands/monorepo.js");
+        runMonorepoCommand(argv);
+        return;
+    }
+    // ─── Config-Migrate Command ───────────────────────────────────────
+    if (args.command === "config-migrate") {
+        const { runConfigMigrate } = await import("./commands/config-migrate.js");
+        runConfigMigrate(argv);
+        return;
+    }
+    // ─── Deprecated Rules Command ─────────────────────────────────────
+    if (args.command === "deprecated") {
+        const { runDeprecatedCommand } = await import("./commands/deprecated.js");
+        runDeprecatedCommand(argv);
+        return;
+    }
+    // ─── Dedup Report Command ─────────────────────────────────────────
+    if (args.command === "dedup-report") {
+        const { runDedupReport } = await import("./commands/dedup-report.js");
+        runDedupReport(argv);
+        return;
+    }
     // ─── Tune Command ─────────────────────────────────────────────────
     if (args.command === "tune") {
         const { runTune } = await import("./commands/tune.js");
@@ -837,6 +1014,12 @@ export async function runCli(argv) {
         await runCommunityPatterns(argv);
         process.exit(0);
     }
+    // ─── Calibration Share Command ───────────────────────────────────────
+    if (args.command === "calibration-share") {
+        const { runCalibrationShare } = await import("./commands/calibration-share.js");
+        runCalibrationShare(argv);
+        process.exit(0);
+    }
     // ─── Compare Command ─────────────────────────────────────────────────
     if (args.command === "compare") {
         const toolName = argv[3];
@@ -856,9 +1039,11 @@ export async function runCli(argv) {
     }
     // ─── Trend Command ───────────────────────────────────────────────────
     if (args.command === "trend") {
-        const { loadSnapshotStore, computeTrend, formatTrendReport, formatTrendReportHtml } = await import("./commands/snapshot.js");
-        const snapshotFile = argv.find((a, i) => i >= 3 && !a.startsWith("-")) || ".judges-snapshots.json";
+        const { loadSnapshotStore, computeTrend, formatTrendReport, formatTrendReportHtml, detectRegressions, formatRegressionAlerts, } = await import("./commands/snapshot.js");
+        const snapshotFile = argv.find((a, i) => i >= 3 && !a.startsWith("-") && !["html", "json", "text"].includes(a)) ||
+            ".judges-snapshots.json";
         const formatArg = argv.includes("--format") ? argv[argv.indexOf("--format") + 1] : "text";
+        const outputArg = argv.includes("--output") ? argv[argv.indexOf("--output") + 1] : undefined;
         const store = loadSnapshotStore(snapshotFile);
         if (store.snapshots.length === 0) {
             console.log("No snapshot data found. Run evaluations with --snapshot to collect trend data.");
@@ -866,14 +1051,30 @@ export async function runCli(argv) {
         }
         else {
             const report = computeTrend(store);
+            let output;
             if (formatArg === "html") {
-                console.log(formatTrendReportHtml(report));
+                output = formatTrendReportHtml(report);
             }
             else if (formatArg === "json") {
-                console.log(JSON.stringify(report, null, 2));
+                output = JSON.stringify(report, null, 2);
+            }
+            else {
+                output = formatTrendReport(report);
+            }
+            if (outputArg) {
+                writeFileSync(outputArg, output, "utf-8");
+                console.log(`  ✅ Trend report written to ${outputArg}`);
             }
             else {
-                console.log(formatTrendReport(report));
+                console.log(output);
+            }
+            // Regression alerts
+            const regressions = detectRegressions(store);
+            if (regressions.length > 0) {
+                console.log(formatRegressionAlerts(regressions));
+                if (args.failOnFindings && regressions.some((r) => r.severity === "error")) {
+                    process.exit(1);
+                }
             }
         }
         process.exit(0);
@@ -884,6 +1085,54 @@ export async function runCli(argv) {
         runScaffoldPlugin(argv);
         process.exit(0);
     }
+    // ─── Plugin Search Command ───────────────────────────────────────────
+    if (args.command === "plugin") {
+        const { runPluginSearch } = await import("./commands/plugin-search.js");
+        runPluginSearch(argv);
+        process.exit(0);
+    }
+    // ─── Trust Ramp Command ──────────────────────────────────────────────
+    if (args.command === "trust-ramp") {
+        const { runTrustRamp } = await import("./commands/trust-ramp.js");
+        runTrustRamp(argv);
+        process.exit(0);
+    }
+    // ─── Metrics Command ────────────────────────────────────────────────
+    if (args.command === "metrics") {
+        const { runMetrics } = await import("./commands/metrics.js");
+        runMetrics(argv);
+        process.exit(0);
+    }
+    // ─── Metrics Dashboard Command ────────────────────────────────────────
+    if (args.command === "metrics-dashboard") {
+        const { runMetricsDashboard } = await import("./commands/metrics-dashboard.js");
+        runMetricsDashboard(argv);
+        process.exit(0);
+    }
+    // ─── Help Command ────────────────────────────────────────────────────
+    if (args.command === "help") {
+        const { runHelp } = await import("./commands/help.js");
+        runHelp(argv);
+        process.exit(0);
+    }
+    // ─── Onboard Command ─────────────────────────────────────────────────
+    if (args.command === "onboard") {
+        const { runOnboard } = await import("./commands/onboard.js");
+        await runOnboard(argv);
+        process.exit(0);
+    }
+    // ─── Org Metrics Command ──────────────────────────────────────────────
+    if (args.command === "org-metrics") {
+        const { runOrgMetrics } = await import("./commands/org-metrics.js");
+        runOrgMetrics(argv);
+        process.exit(0);
+    }
+    // ─── Plugins Command ──────────────────────────────────────────────────
+    if (args.command === "plugins") {
+        const { runPlugins } = await import("./commands/plugins.js");
+        runPlugins(argv);
+        process.exit(0);
+    }
     // ─── List Command ────────────────────────────────────────────────────
     if (args.command === "list") {
         listJudges();
@@ -920,6 +1169,12 @@ export async function runCli(argv) {
                 const changedSet = new Set(changedFiles.map((f) => resolve(f)));
                 files = files.filter((f) => changedSet.has(resolve(f)));
             }
+            // ── --staged-only: scope to git-staged files ──
+            if (args.stagedOnly) {
+                const stagedFiles = getStagedFiles(target);
+                const stagedSet = new Set(stagedFiles.map((f) => resolve(f)));
+                files = files.filter((f) => stagedSet.has(resolve(f)));
+            }
             if (files.length === 0) {
                 console.error(`No supported source files found in: ${target}${args.changedOnly ? " (changed-only)" : ""}`);
                 process.exit(1);
@@ -933,6 +1188,9 @@ export async function runCli(argv) {
             let failCount = 0;
             let totalFixed = 0;
             let totalFixable = 0;
+            let cacheHits = 0;
+            // Incremental evaluation: use disk cache to skip unchanged files
+            const diskCache = args.noCache ? undefined : new DiskCache();
             for (let idx = 0; idx < files.length; idx++) {
                 const filePath = files[idx];
                 const relPath = relative(resolve("."), filePath);
@@ -941,7 +1199,21 @@ export async function runCli(argv) {
                 }
                 const fileCode = readFileSync(filePath, "utf-8");
                 const fileLang = args.language || detectLanguage(filePath) || "typescript";
-                const verdict = evaluateWithTribunal(fileCode, fileLang, undefined, evalOptions);
+                // Check disk cache for incremental mode (always when cache available)
+                const hash = contentHash(fileCode, fileLang);
+                let verdict;
+                if (diskCache) {
+                    verdict = diskCache.get(hash);
+                }
+                if (verdict) {
+                    cacheHits++;
+                }
+                else {
+                    verdict = evaluateWithTribunal(fileCode, fileLang, undefined, evalOptions);
+                    if (diskCache) {
+                        diskCache.set(hash, verdict, relPath);
+                    }
+                }
                 // Apply baseline suppression
                 if (loadedBaseline) {
                     for (const evaluation of verdict.evaluations) {
@@ -949,6 +1221,18 @@ export async function runCli(argv) {
                     }
                     verdict.findings = verdict.findings.filter((f) => !isBaselined(f, loadedBaseline, fileCode, relPath));
                 }
+                // Apply override suppressions for multi-file mode
+                {
+                    const overrideStore = loadOverrideStore();
+                    if (overrideStore.overrides.length > 0) {
+                        for (const evaluation of verdict.evaluations) {
+                            const result = applyOverrides(evaluation.findings, overrideStore, relPath);
+                            evaluation.findings = result.active;
+                        }
+                        const topResult = applyOverrides(verdict.findings, overrideStore, relPath);
+                        verdict.findings = topResult.active;
+                    }
+                }
                 const fileFindings = verdict.evaluations.reduce((s, e) => s + e.findings.length, 0);
                 const fileFixable = verdict.evaluations.reduce((s, e) => s + e.findings.filter((f) => f.patch).length, 0);
                 totalFindings += fileFindings;
@@ -996,6 +1280,9 @@ export async function runCli(argv) {
             if (args.fix && totalFixed > 0) {
                 console.log(`  Fixed    : ${totalFixed} patch(es) applied`);
             }
+            if (cacheHits > 0) {
+                console.log(`  Cached   : ${cacheHits} file(s) unchanged (skipped re-evaluation)`);
+            }
             console.log(`  Time     : ${elapsed}ms`);
             console.log("");
             if (args.failOnFindings && failCount > 0)
@@ -1069,6 +1356,27 @@ export async function runCli(argv) {
             if (args.verbose) {
                 console.log(`  ⏱  Evaluated in ${elapsed}ms`);
             }
+            // Trace output — show pipeline decision trace
+            if (args.trace) {
+                const { buildEvaluationTrace, formatTraceText } = await import("./commands/trace.js");
+                const wrappedForTrace = {
+                    overallVerdict: evaluation.verdict,
+                    overallScore: evaluation.score,
+                    summary: evaluation.summary,
+                    evaluations: [evaluation],
+                    findings: evaluation.findings,
+                    criticalCount: evaluation.findings.filter((f) => f.severity === "critical").length,
+                    highCount: evaluation.findings.filter((f) => f.severity === "high").length,
+                    timestamp: new Date().toISOString(),
+                };
+                const trace = buildEvaluationTrace(wrappedForTrace, resolvedPath || args.file, language);
+                if (args.format === "json") {
+                    console.log(JSON.stringify(trace, null, 2));
+                }
+                else {
+                    console.log(formatTraceText(trace));
+                }
+            }
             // Exit code — fail-on-findings or min-score
             if (args.failOnFindings && evaluation.verdict === "fail")
                 process.exit(1);
@@ -1117,6 +1425,22 @@ export async function runCli(argv) {
                 }
                 verdict.findings = filterBySeverity(verdict.findings, evalConfig.minSeverity);
             }
+            // Apply override suppressions
+            {
+                const overrideStore = loadOverrideStore();
+                if (overrideStore.overrides.length > 0) {
+                    const fileSrc = resolvedPath || args.file;
+                    for (const evaluation of verdict.evaluations) {
+                        const result = applyOverrides(evaluation.findings, overrideStore, fileSrc);
+                        evaluation.findings = result.active;
+                    }
+                    const topResult = applyOverrides(verdict.findings, overrideStore, fileSrc);
+                    verdict.findings = topResult.active;
+                    if (topResult.overridden.length > 0 && !args.quiet) {
+                        console.log(`  ℹ️  ${topResult.overridden.length} finding(s) suppressed by overrides`);
+                    }
+                }
+            }
             // Enrich with learning context when --explain is set
             if (args.explain) {
                 for (const evaluation of verdict.evaluations) {
@@ -1149,6 +1473,17 @@ export async function runCli(argv) {
                 console.log(`  ⏱  Evaluated in ${elapsed}ms`);
                 console.log(`  📊 ${verdict.evaluations.length} judges, ${verdict.findings.length} total findings`);
             }
+            // Trace output — show pipeline decision trace
+            if (args.trace) {
+                const { buildEvaluationTrace, formatTraceText } = await import("./commands/trace.js");
+                const trace = buildEvaluationTrace(verdict, resolvedPath || args.file, language);
+                if (args.format === "json") {
+                    console.log(JSON.stringify(trace, null, 2));
+                }
+                else {
+                    console.log(formatTraceText(trace));
+                }
+            }
             // Exit code — fail-on-findings or min-score
             if (args.failOnFindings && verdict.overallVerdict === "fail")
                 process.exit(1);
@@ -1380,18 +1715,37 @@ function enrichWithExplanations(findings) {
     return findings.map((f) => {
         const prefix = f.ruleId.replace(/-\d+$/, "");
         const ctx = RULE_PREFIX_CONTEXT[prefix];
-        if (!ctx)
-            return f;
         const parts = [f.description];
-        if (ctx.owasp)
-            parts.push(`\n📚 OWASP: ${ctx.owasp}`);
-        if (ctx.cwe)
-            parts.push(`CWE: ${ctx.cwe}`);
-        parts.push(`💡 ${ctx.learn}`);
+        // Layer 2: evidence-based explanation
+        if (f.confidence !== undefined) {
+            parts.push(`\n🎯 Confidence: ${Math.round(f.confidence * 100)}%`);
+        }
+        if (f.provenance) {
+            parts.push(`🔍 Detection: ${f.provenance}`);
+        }
+        if (f.evidenceBasis) {
+            parts.push(`📊 Evidence: ${f.evidenceBasis}`);
+        }
+        if (f.evidenceChain && f.evidenceChain.steps.length > 0) {
+            parts.push(`\n⚡ Why this matters: ${f.evidenceChain.impactStatement}`);
+            parts.push("   Evidence chain:");
+            for (const step of f.evidenceChain.steps.slice(0, 5)) {
+                const loc = step.line ? ` (L${step.line})` : "";
+                parts.push(`   → [${step.source}]${loc} ${step.observation}`);
+            }
+        }
+        // Layer 1: OWASP/CWE reference context
+        if (ctx) {
+            if (ctx.owasp)
+                parts.push(`\n📚 OWASP: ${ctx.owasp}`);
+            if (ctx.cwe)
+                parts.push(`CWE: ${ctx.cwe}`);
+            parts.push(`💡 ${ctx.learn}`);
+        }
         return {
             ...f,
             description: parts.join("  "),
-            reference: f.reference || [ctx.owasp, ctx.cwe].filter(Boolean).join(" / ") || f.reference,
+            reference: f.reference || (ctx ? [ctx.owasp, ctx.cwe].filter(Boolean).join(" / ") : undefined) || f.reference,
         };
     });
 }