@orangepro/orangepro-mcp 0.1.0 → 0.2.1

package/dist/local/proofDoctor.js

@@ -0,0 +1,312 @@
+/**
+ * G1 — `opro doctor --proof`: explain WHY top targets are not Dynamically Proven.
+ *
+ * Read-only diagnostics over already-produced, already-redacted data:
+ *   - `.orangepro/proof-attempts.json` — a distilled sidecar of the last run's
+ *     auto-prove attempt classifications (written by opStart AFTER autoProve
+ *     returns; autoProve itself and the proof oracle are untouched).
+ *   - the graph + ledger via the CANONICAL judge (buildRtm) for proven counts —
+ *     this module never re-derives or re-scores proof.
+ *
+ * Trust invariants (load-bearing):
+ *   - Mints nothing, mutates no ledger, never writes on the doctor path.
+ *   - Reasons are the upstream single-line redacted summaries; re-redacted at
+ *     sidecar-write time as belt-and-braces. No raw stderr/stdout, ever.
+ *   - A survived mutant is a proven NEGATIVE ("not proven, possibly equivalent"),
+ *     never blamed on the user and never nudged toward weakening a test.
+ *   - Stale sidecar (graph re-analyzed / git moved since) ⇒ fail closed: reasons
+ *     are labeled stale and the headline says re-run, never presented as current.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { workspacePaths } from "./workspace.js";
+import { redactSecrets } from "./util/redact.js";
+import { targetLanguage } from "./ledger.js";
+import { readEnginesNode, satisfiesNodeRange } from "./proofRunnability.js";
+export const PROOF_ATTEMPTS_SCHEMA_VERSION = "orangepro.proof_attempts.v1";
+export const PROOF_ATTEMPTS_FILE = "proof-attempts.json";
+export const PROOF_DOCTOR_SCHEMA_VERSION = "orangepro.proof_doctor.v1";
+/** Languages with a shipped dynamic-proof profile. Everything else is honest "not yet". */
+const PROVABLE_LANGUAGES = new Set(["typescript", "javascript", "go", "java", "python"]);
+/**
+ * One label + one smallest-next-step per category. Copy discipline: honest
+ * pointers only — never nudge toward weakening a test, never call a test bad.
+ */
+export const PROOF_BLOCKER_GUIDE = {
+    module_not_found: {
+        label: "a module or dependency is missing in the proof sandbox",
+        next_step: "Install the package's dependencies (npm ci / go mod download / pip install) so imports resolve, then re-run `opro start`."
+    },
+    tsconfig_missing: {
+        label: "the package extends a monorepo tsconfig the sandbox cannot resolve",
+        next_step: "Run `opro start` from the monorepo root so parent tsconfigs are mirrored into the proof sandbox."
+    },
+    experimental_builtin: {
+        label: "the target needs an experimental Node builtin runtime flag",
+        next_step: "Re-run with the flag named in the attempt reason (e.g. NODE_OPTIONS=--experimental-sqlite) or a Node version where the builtin is stable."
+    },
+    engine_mismatch: {
+        label: "the runner Node is outside the package's declared engines range",
+        next_step: "Switch Node versions (e.g. `nvm use`) to satisfy engines.node, then re-run `opro start`."
+    },
+    db_or_external: {
+        label: "the test needs a database or external service the sandbox lacks",
+        next_step: "Provide the service locally (or a test double) via `orangepro_prove_loop` setup_commands, then re-run."
+    },
+    runner_missing: {
+        label: "no supported test runner is available for the target's package",
+        next_step: "Install the package's test framework (vitest / jest / mocha; go, mvn, pytest on PATH), then re-run `opro start`."
+    },
+    module_root_missing: {
+        label: "no module root (go.mod / pom.xml / build.gradle) was found under the analyzed path",
+        next_step: "Run `opro start` from the module root that owns this target (the directory containing go.mod / pom.xml)."
+    },
+    assertion_binding: {
+        label: "the proof could not bind exactly one test to the target (ambiguous test identity)",
+        next_step: "Give the covering test a unique title/name so the oracle can bind exactly one test to the mutant; ambiguity fails closed."
+    },
+    unsupported_language: {
+        label: "no dynamic-proof profile exists for this language yet",
+        next_step: "TS/JS, Go, Java and Python are dynamically provable today; other languages stay honestly in their static tiers."
+    },
+    setup_failed: {
+        label: "proof setup failed before the oracle could run",
+        next_step: "Read the attempt reason, fix the named setup step, then re-run `opro start`."
+    }
+};
+/** Wording is load-bearing: a survivor is a proven negative, never a user failure. */
+export const NON_KILLING_NOTE = "Not proven: the test still passed while the target was mutated (possibly an equivalent mutation). " +
+    "The mutant surviving is a proven negative about assertion strength — it is never counted as Dynamically Proven.";
+export function proofAttemptsPath(root) {
+    return join(workspacePaths(root).dir, PROOF_ATTEMPTS_FILE);
+}
+/**
+ * Distill an AutoProveResult into the persistable sidecar. Reasons arrive
+ * already redacted (autoProve/classifyBaselineFailure discipline); redactSecrets
+ * is applied again here so the WRITER enforces the no-secrets guarantee even if
+ * an upstream path regresses.
+ */
+export function distillProofAttempts(auto, meta) {
+    const manifest = meta.graph.manifest;
+    return {
+        schema_version: PROOF_ATTEMPTS_SCHEMA_VERSION,
+        generated_at: meta.generatedAt,
+        graph_generated_at: manifest?.generated_at ?? null,
+        git_commit: manifest?.git?.commit ?? null,
+        git_dirty: manifest?.git?.dirty ?? null,
+        attempted: auto.attempted,
+        proven: auto.proven,
+        attempts: auto.attempts.map((a) => ({
+            target_symbol: a.target_symbol,
+            test_path: a.test_path || undefined,
+            classification: a.classification,
+            category: a.category,
+            reason: a.reason ? redactSecrets(a.reason) : undefined,
+            deduped: a.deduped,
+            language: targetLanguage(a.target_symbol)
+        })),
+        skipped: auto.skipped.map((s) => ({
+            target_symbol: s.target_symbol,
+            title: s.title,
+            reason: redactSecrets(s.reason)
+        }))
+    };
+}
+export function writeProofAttempts(root, file) {
+    const path = proofAttemptsPath(root);
+    writeFileSync(path, JSON.stringify(file, null, 2) + "\n", "utf8");
+    return path;
+}
+/** True when the sidecar anchors to the CURRENT graph generation + commit. */
+export function proofAttemptsFresh(attempts, graph) {
+    const manifest = graph.manifest;
+    return (attempts.graph_generated_at === (manifest?.generated_at ?? null) &&
+        attempts.git_commit === (manifest?.git?.commit ?? null));
+}
+export function loadProofAttempts(root) {
+    const path = proofAttemptsPath(root);
+    if (!existsSync(path))
+        return null;
+    // Fail closed on ANY unreadable sidecar — malformed JSON, wrong schema, or a
+    // non-object shape. Unreadable evidence is no evidence; doctor must never crash.
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return null;
+    const file = parsed;
+    if (file.schema_version !== PROOF_ATTEMPTS_SCHEMA_VERSION)
+        return null;
+    if (!Array.isArray(file.attempts) || !Array.isArray(file.skipped))
+        return null;
+    return file;
+}
+/**
+ * Map one recorded attempt to a doctor blocker category. Uses the R-1 category
+ * when present; otherwise a CONSERVATIVE pattern match on the (redacted) reason.
+ * Anything unrecognized stays "setup_failed" — never guess a specific cause.
+ */
+export function blockerCategoryFor(attempt) {
+    const reason = attempt.reason ?? "";
+    if (/runner binary not found|unsupported or unknown test runner/i.test(reason))
+        return "runner_missing";
+    if (/no go\.mod found|no pom\.xml|no maven or gradle|build\.gradle/i.test(reason))
+        return "module_root_missing";
+    if (/ambiguous|appears more than once|uniquely passed|not uniquely/i.test(reason))
+        return "assertion_binding";
+    const cat = attempt.category;
+    if (cat && cat in PROOF_BLOCKER_GUIDE)
+        return cat;
+    return "setup_failed";
+}
+/**
+ * Cheap static preflight for targets with NO attempt record: names blockers
+ * WITHOUT running any test. Checks are deliberately few and certain:
+ * unsupported language, missing go/java module root, engines mismatch.
+ */
+function preflightBlockers(rtm, root, io, limit) {
+    const rows = rtm.rows.filter((r) => r.evidence_tier !== "proven" && r.code_symbol.startsWith("sym:")).slice(0, limit);
+    const found = [];
+    for (const row of rows) {
+        const lang = targetLanguage(row.code_symbol);
+        const fileRel = row.code_symbol.match(/^sym:(.+)#/)?.[1] ?? "";
+        if (!PROVABLE_LANGUAGES.has(lang)) {
+            found.push({ category: "unsupported_language", target: row.code_symbol });
+            continue;
+        }
+        if (lang === "go" || lang === "java") {
+            const markers = lang === "go" ? ["go.mod"] : ["pom.xml", "build.gradle", "build.gradle.kts"];
+            if (!nearestMarker(root, fileRel, markers, io)) {
+                found.push({ category: "module_root_missing", target: row.code_symbol });
+                continue;
+            }
+        }
+        if (lang === "typescript" || lang === "javascript") {
+            const range = readEnginesNode(root, fileRel);
+            if (range && satisfiesNodeRange(io.nodeVersion, range) === false) {
+                found.push({ category: "engine_mismatch", target: row.code_symbol });
+            }
+        }
+    }
+    return groupBlockers(found.map((f) => ({
+        target_symbol: f.target,
+        test_path: undefined,
+        category: f.category,
+        reason: undefined
+    })), "preflight");
+}
+/** Walk from the target file's dir UP to root (inclusive) looking for a marker file. */
+function nearestMarker(root, fileRel, markers, io) {
+    let dir = join(root, dirname(fileRel));
+    const stop = root;
+    for (;;) {
+        for (const m of markers)
+            if (io.exists(join(dir, m)))
+                return true;
+        if (dir === stop)
+            return false;
+        const parent = dirname(dir);
+        if (parent === dir || !parent.startsWith(stop))
+            return false;
+        dir = parent;
+    }
+}
+function groupBlockers(blocked, source) {
+    const groups = new Map();
+    for (const b of blocked) {
+        const category = source === "preflight" && b.category && b.category in PROOF_BLOCKER_GUIDE
+            ? b.category
+            : blockerCategoryFor(b);
+        const guide = PROOF_BLOCKER_GUIDE[category];
+        const existing = groups.get(category);
+        if (existing) {
+            existing.count += 1;
+            if (existing.targets.length < 5)
+                existing.targets.push(b.target_symbol);
+        }
+        else {
+            groups.set(category, {
+                category,
+                label: guide.label,
+                count: 1,
+                targets: [b.target_symbol],
+                representative: { target_symbol: b.target_symbol, test_path: b.test_path, reason: b.reason },
+                next_step: guide.next_step,
+                source
+            });
+        }
+    }
+    return [...groups.values()].sort((a, b) => b.count - a.count);
+}
+/**
+ * Pure assembly: graph + canonical RTM result + optional attempts sidecar →
+ * deduped blocker report. Never writes; never mints; never recomputes proof.
+ */
+export function buildProofDoctor(graph, rtm, attempts, opts = {}) {
+    const io = opts.io ?? { exists: existsSync, nodeVersion: process.version };
+    const proven = rtm.summary.proven;
+    const denominator = rtm.summary.total;
+    // Freshness: the sidecar must anchor to the CURRENT graph generation + commit.
+    const stale = Boolean(attempts && !proofAttemptsFresh(attempts, graph));
+    const currentAttempts = attempts && !stale ? attempts : null;
+    const blocked = (currentAttempts?.attempts ?? []).filter((a) => a.classification === "needs_setup");
+    const survivors = (currentAttempts?.attempts ?? []).filter((a) => a.classification === "non_killing");
+    let blockers = groupBlockers(blocked, "attempt");
+    if (blockers.length === 0 && !currentAttempts) {
+        blockers = preflightBlockers(rtm, graph.workspace?.root ?? "", io, opts.preflightLimit ?? 10);
+    }
+    // Dedupe identical (target, test) survivor pairs — repeat attempts add noise,
+    // not information. Attribution stays exact: one row per target+test pair.
+    const seenSurvivors = new Set();
+    const non_killing = [];
+    for (const a of survivors) {
+        const key = `${a.target_symbol}\u0000${a.test_path ?? ""}`;
+        if (seenSurvivors.has(key))
+            continue;
+        seenSurvivors.add(key);
+        non_killing.push({ target_symbol: a.target_symbol, test_path: a.test_path, note: NON_KILLING_NOTE });
+    }
+    let status;
+    let headline;
+    if (stale) {
+        status = "stale";
+        headline =
+            "Proof-attempt data is stale (the graph or commit changed since the last run) — re-run `opro start` for current blocker reasons.";
+    }
+    else if (proven > 0) {
+        status = "proven";
+        headline = `${proven} of ${denominator} behaviors are Dynamically Proven (RTM). Blockers below explain the rest.`;
+    }
+    else if (blockers.length > 0) {
+        const top = blockers[0];
+        status = "blocked";
+        headline =
+            top.count > 1
+                ? `0 Dynamically Proven — one root cause blocked ${top.count} target${top.count === 1 ? "" : "s"}: ${top.label}.`
+                : `0 Dynamically Proven — top blocker: ${top.label}.`;
+    }
+    else if (non_killing.length > 0) {
+        status = "blocked";
+        headline = `0 Dynamically Proven — ${non_killing.length} attempt(s) ran but the mutant survived (see non_killing).`;
+    }
+    else {
+        status = "no_data";
+        headline = "No proof-attempt data yet — run `opro start` to attempt dynamic proof and record blockers.";
+    }
+    return {
+        schema_version: PROOF_DOCTOR_SCHEMA_VERSION,
+        status,
+        proven,
+        denominator,
+        attempted: currentAttempts?.attempted ?? null,
+        stale,
+        headline,
+        blockers,
+        non_killing,
+        generated_at: attempts?.generated_at ?? null
+    };
+}

package/dist/local/rtm.js

@@ -29,9 +29,22 @@ export function buildRtm(graph, ledger, opts = {}) {
         .filter((node) => inScope(node, targetSet, fileSet))
         .map((node) => toRtmRow(indexes, node, ledgerBySymbol.get(node.external_id)))
         .sort((a, b) => STATUS_ORDER[a.status] - STATUS_ORDER[b.status] || a.area.localeCompare(b.area) || a.file.localeCompare(b.file) || a.behavior.localeCompare(b.behavior));
-    const filteredRows = baseRows.filter((row) => !statusSet || statusSet.has(row.status));
+    // Display-union: surface CodeSymbols with a CURRENT valid dynamic-proof cert that fall
+    // OUTSIDE the deterministic denominator (e.g. a Formatter SPI method below the
+    // entry-point-adjacent bar). `ledgerBySymbol.get(...).proven` is already gated by
+    // isDynamicProofRecord + fingerprint-match + closed, so a stale/invalid/unclosed cert
+    // is never `true` here. These rows are counted in `summary.proven` but NOT in the
+    // denominator math (total/coverage_total/coverage_pct) — the denominator stays stable.
+    const denominatorIds = new Set(baseRows.map((row) => row.behavior_id));
+    const unionRows = graph.nodes
+        .filter((node) => node.kind === "CodeSymbol" && !denominatorIds.has(node.external_id) && ledgerBySymbol.get(node.external_id)?.proven === true)
+        .filter((node) => inScope(node, targetSet, fileSet))
+        .map((node) => ({ ...toRtmRow(indexes, node, ledgerBySymbol.get(node.external_id)), off_denominator: true }))
+        .sort((a, b) => a.area.localeCompare(b.area) || a.file.localeCompare(b.file) || a.behavior.localeCompare(b.behavior));
+    const displayRows = [...baseRows, ...unionRows];
+    const filteredRows = displayRows.filter((row) => !statusSet || statusSet.has(row.status));
     const rows = opts.limit && opts.limit > 0 ? filteredRows.slice(0, opts.limit) : filteredRows;
-    return { summary: summarizeRows(baseRows), rows, ...(opts.scope ? { scope: opts.scope } : {}) };
+    return { summary: summarizeRows(baseRows, unionRows), rows, ...(opts.scope ? { scope: opts.scope } : {}) };
 }
 function inScope(node, targetSet, fileSet) {
     if (!targetSet && !fileSet)
@@ -43,6 +56,11 @@ function inScope(node, targetSet, fileSet) {
 }
 export function renderRtmMarkdown(result) {
     const s = result.summary;
+    // Off-denominator proven symbols (display-union): counted in `proven` but not in `total`.
+    const offDenominatorProven = result.rows.filter((row) => row.off_denominator === true && row.evidence_tier === "proven").length;
+    const provenValue = offDenominatorProven > 0
+        ? `${s.proven} (${s.proven - offDenominatorProven} in denominator + ${offDenominatorProven} off-denominator)`
+        : `${s.proven}`;
     const lines = [
         "# OrangePro Traceability Matrix",
         "",
@@ -51,7 +69,7 @@ export function renderRtmMarkdown(result) {
         "| Metric | Value |",
         "|---|---:|",
         `| Total denominator behaviors | ${s.total} |`,
-        `| Dynamically Proven | ${s.proven} |`,
+        `| Dynamically Proven | ${provenValue} |`,
         `| Runtime-covered | ${s.runtime_covered} |`,
         `| Associated signal | ${s.associated} |`,
         `| No integration signal | ${s.no_link} |`,
@@ -64,6 +82,9 @@ export function renderRtmMarkdown(result) {
     if (result.scope?.guidance) {
         lines.push(`> ${escapeMarkdown(result.scope.guidance)}`, "");
     }
+    if (offDenominatorProven > 0) {
+        lines.push(`> ${offDenominatorProven} dynamically-proven symbol(s) sit OUTSIDE the deterministic denominator (marked \`off-denominator\` below). They are counted in Dynamically Proven but NOT in the denominator or Dynamic Proven source ratio.`, "");
+    }
     if (result.rows.length < s.total) {
         lines.push(`> Showing ${result.rows.length} row(s) from ${s.total} scoped denominator row(s). This can reflect \`--limit\` and/or \`--status\` filters. Use \`opro rtm --format json --out .orangepro/rtm-full.json\` for a full machine-readable RTM.`, "");
     }
@@ -77,7 +98,7 @@ export function renderRtmMarkdown(result) {
         lines.push([
             row.behavior,
             row.code_symbol || row.behavior_id,
-            row.area,
+            row.off_denominator ? `${row.area} (off-denominator)` : row.area,
             row.language,
             row.test_signal,
             row.status,
@@ -93,7 +114,7 @@ export function renderRtmMarkdown(result) {
     return lines.join("\n");
 }
 export function renderRtmCsv(result) {
-    const header = ["behavior", "behavior_id", "kind", "code_symbol", "file", "area", "language", "evidence_tier", "test_signal", "status", "suggested_next_test", "ledger_outcome", "ledger_run_id"];
+    const header = ["behavior", "behavior_id", "kind", "code_symbol", "file", "area", "language", "evidence_tier", "test_signal", "status", "suggested_next_test", "ledger_outcome", "ledger_run_id", "off_denominator"];
     const rows = result.rows.map((row) => [
         row.behavior,
         row.behavior_id,
@@ -107,7 +128,8 @@ export function renderRtmCsv(result) {
         row.status,
         row.suggested_next_test,
         row.ledger_outcome,
-        row.ledger_run_id
+        row.ledger_run_id,
+        row.off_denominator ? "true" : "false"
     ]);
     return [header, ...rows].map((row) => row.map(csvCell).join(",")).join("\n") + "\n";
 }
@@ -157,10 +179,18 @@ function statusFor(evidence, ledgerRecord, dynamicProof) {
         return "Associated signal";
     return "No integration signal";
 }
-function summarizeRows(rows) {
+/**
+ * `rows` = the deterministic denominator rows (drives ALL denominator math). `unionRows`
+ * = off-denominator symbols with a current valid dynamic-proof cert; they add ONLY to
+ * `proven` (the honest "Dynamically Proven" headline), never to total/coverage_total/
+ * coverage_pct. Splitting the two keeps the denominator stable while the headline counts
+ * every genuinely-proven symbol.
+ */
+function summarizeRows(rows, unionRows = []) {
     const attempted = rows.filter((row) => row.ledger_outcome.startsWith("reproven") || row.ledger_outcome.startsWith("unproven")).length;
     const reproven = rows.filter((row) => row.status === "Reproven (this run)").length;
-    const proven = rows.filter((row) => row.evidence_tier === "proven").length;
+    const denominatorProven = rows.filter((row) => row.evidence_tier === "proven").length;
+    const proven = denominatorProven + unionRows.filter((row) => row.evidence_tier === "proven").length;
     return {
         total: rows.length,
         proven,
@@ -171,9 +201,9 @@ function summarizeRows(rows) {
         generated_unverifiable: rows.filter((row) => row.status === "Generated-unverifiable").length,
         attempted,
         kept_rate: attempted > 0 ? Number(((reproven / attempted) * 100).toFixed(2)) : 0,
-        coverage_confirmed: proven,
+        coverage_confirmed: denominatorProven,
         coverage_total: rows.length,
-        coverage_pct: rows.length > 0 ? Number(((proven / rows.length) * 100).toFixed(1)) : 0
+        coverage_pct: rows.length > 0 ? Number(((denominatorProven / rows.length) * 100).toFixed(1)) : 0
     };
 }
 /**

package/dist/local/viz/behaviorReportData.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { buildRtm } from "../rtm.js";
 import { rankRiskGaps } from "../score/risk.js";
+import { PROOF_BLOCKER_GUIDE } from "../proofDoctor.js";
 /** Short human phrase per R-1 needs_setup category, for the "blocked because: …" panel copy. */
 const BLOCK_CATEGORY_LABEL = {
     module_not_found: "a missing module or dependency in the sandbox",
@@ -30,7 +31,19 @@ export function dominantBlockReason(needsSetup) {
             topKey = k;
         }
     }
-    return { label: BLOCK_CATEGORY_LABEL[topKey] ?? "setup/runnability of the test in the sandbox", count: top, total: needsSetup.length };
+    return { label: BLOCK_CATEGORY_LABEL[topKey] ?? "setup/runnability of the test in the sandbox", count: top, total: needsSetup.length, category: topKey };
+}
+/**
+ * G1: category-specific smallest next step for the dominant blocker (display
+ * copy only; the guide lives in proofDoctor so doctor/CLI/report share one
+ * source). Unknown/uncategorized falls back to the generic handoff action.
+ */
+function nextStepFor(dom) {
+    if (!dom)
+        return null;
+    const key = dom.category === "runnability" ? "setup_failed" : dom.category;
+    const guide = PROOF_BLOCKER_GUIDE[key];
+    return guide ? `Next: ${guide.next_step}` : null;
 }
 function nodeFile(node) {
     if (!node)
@@ -158,7 +171,7 @@ function proofGuidance(ledger, summary, dyn) {
                 state: "attempted",
                 title: `0 Dynamically Proven — top ${dyn.attempted} attempted, all setup-blocked`,
                 body: `Dynamic proof attempted ${dyn.attempted} target${plural}; all were blocked by ${dom.label} (${dom.count}/${dom.total}). This is a sandbox setup gap, not a static-test failure — the Statically Linked signals are still shown.`,
-                action: HANDOFF_ACTION
+                action: nextStepFor(dom) ?? HANDOFF_ACTION
             };
         }
         const because = dom ? ` Blocked because: ${dom.label} (${dom.count}/${dom.total}).` : "";
@@ -166,7 +179,7 @@ function proofGuidance(ledger, summary, dyn) {
             state: "attempted",
             title: `0 Dynamically Proven — top ${dyn.attempted} attempted, 0 closed`,
             body: `OrangePro mapped this repo statically. Dynamic proof is a targeted verification pass: it runs existing or generated tests, mutates the exact behavior, and promotes only tests that fail at an assertion. This run attempted the top ${dyn.attempted} eligible behavior${plural} and closed 0.${because} Static test signals stay Statically Linked.`,
-            action: HANDOFF_ACTION
+            action: nextStepFor(dom) ?? HANDOFF_ACTION
         };
     }
     // Standalone report regen (no THIS-RUN data) → derive from the ledger only.
@@ -313,7 +326,53 @@ function candidateFlows(graph) {
         }))
     };
 }
-function riskRows(risks) {
+/** Tier sort rank: Proven first, then Test signal, Reachable, No signal. */
+function tierRank(b) {
+    if (b.tier === "proven")
+        return 0;
+    if (b.tier === "assoc")
+        return 1;
+    return b.reachable ? 2 : 3;
+}
+/**
+ * Link REAL generated tests (graph.generated_tests) to a risk row: exact
+ * target-symbol match first, then same-file. Metadata shown is honest and
+ * verbatim (title, test_type, framework hint, weak-evidence disclosure, body)
+ * — nothing is fabricated; no tests ⇒ the template hides the section.
+ */
+function riskGeneratedTests(graph, gap, riskIds, isFirstRowForFile) {
+    const all = graph.generated_tests ?? [];
+    const fileOf = (sym) => sym?.match(/^sym:(.+)#/)?.[1];
+    // Exact target wins. The same-file fallback (test targets an UNLISTED symbol
+    // in this file) attaches to exactly ONE deterministic row — the file's first
+    // (highest-ranked) risk row — and is labeled "same-file target" so a real
+    // generated test never reads as generated FOR a sibling behavior.
+    const linked = all.flatMap((t) => {
+        if (!t.target_symbol_external_id)
+            return [];
+        if (t.target_symbol_external_id === gap.id)
+            return [{ t, sameFile: false }];
+        if (riskIds.has(t.target_symbol_external_id))
+            return [];
+        if (!isFirstRowForFile)
+            return [];
+        return fileOf(t.target_symbol_external_id) === gap.file ? [{ t, sameFile: true }] : [];
+    });
+    return linked.slice(0, 2).map(({ t, sameFile }) => ({
+        name: t.title,
+        concern: t.test_type && t.test_type !== "unknown" ? t.test_type : undefined,
+        assertion: [sameFile ? "same-file target" : "", t.framework_hint, t.weak_evidence_used ? "weak evidence disclosed" : ""]
+            .filter(Boolean)
+            .join(" · "),
+        code: t.body
+    }));
+}
+function riskRows(risks, graph) {
+    const riskIds = new Set(risks.map((r) => r.id));
+    const firstRowForFile = new Map();
+    for (const r of risks)
+        if (!firstRowForFile.has(r.file))
+            firstRowForFile.set(r.file, r.id);
     return risks.map((risk, idx) => {
         const methodMatch = risk.title.match(/^(GET|POST|PUT|PATCH|DELETE)\s+(.+)$/i);
         const pathMatch = risk.file.match(/\/api\/(.+)$/);
@@ -326,6 +385,15 @@ function riskRows(risks) {
             tags.push(["Entry point", "entry"]);
         return {
             rank: idx + 1,
+            ...(() => {
+                const generatedTests = riskGeneratedTests(graph, risk, riskIds, firstRowForFile.get(risk.file) === risk.id);
+                return {
+                    generatedTests,
+                    // Honest category strip: only the concerns of REAL attached tests —
+                    // every pill renders as shown ("n of n"), none fabricated as locked.
+                    applicableCategories: [...new Set(generatedTests.map((t) => t.concern).filter((c) => Boolean(c)))]
+                };
+            })(),
             verb: methodMatch?.[1]?.toUpperCase() ?? (risk.entry_point ? "ENTRY" : "CODE"),
             path: methodMatch?.[2] ?? (pathMatch ? `/${pathMatch[1]}` : risk.file),
             desc: risk.reasons.join(" · "),
@@ -348,6 +416,7 @@ export function buildBehaviorReportData(graph, ledger, opts = {}) {
     const repoRoot = opts.repoRoot ?? graph.workspace.root;
     const riskGaps = rankRiskGaps(graph, { repoRoot, limit: opts.riskLimit ?? 20 });
     const lists = behaviorLists(rows, flowIds);
+    const risks = riskRows(riskGaps, graph);
     return {
         repo: path.basename(repoRoot || graph.workspace.name || "repo"),
         scanned: (graph.updated_at || graph.created_at || new Date(0).toISOString()).slice(0, 10),
@@ -358,10 +427,13 @@ export function buildBehaviorReportData(graph, ledger, opts = {}) {
         pipeline: pipeline(graph, ledger, summary),
         scan: scanBlock(graph, rows),
         behaviorGroups: lists.behaviorGroups,
-        behaviors: lists.behaviors,
+        // Proven first so the strongest evidence leads the grid (stable within tiers).
+        behaviors: [...lists.behaviors].sort((a, b) => tierRank(a) - tierRank(b)),
         flows: flows(graph, rows, riskGaps),
         candidateFlows: candidateFlows(graph),
-        risks: riskRows(riskGaps),
-        zeroProofExplainer: summary.proven === 0 ? { title: ZERO_PROOF_EXPLAINER.title, body: [...ZERO_PROOF_EXPLAINER.body] } : null
+        risks,
+        zeroProofExplainer: summary.proven === 0 ? { title: ZERO_PROOF_EXPLAINER.title, body: [...ZERO_PROOF_EXPLAINER.body] } : null,
+        generatedTotal: graph.generated_tests?.length ?? 0,
+        shownCount: risks.reduce((acc, r) => acc + r.generatedTests.length, 0)
     };
 }