@orangepro/orangepro-mcp 0.1.0

package/dist/local/rtm.js

@@ -0,0 +1,413 @@
+import { denominatorBehaviors } from "./graph/factories.js";
+import { languageOf } from "./analyze/classify.js";
+import { targetFingerprint } from "./ledger.js";
+const STATUS_ORDER = {
+    "No integration signal": 0,
+    "Associated signal": 1,
+    "Generated-unverifiable": 2,
+    "Runtime-covered": 3,
+    "Proven": 4,
+    "Reproven (this run)": 5
+};
+const GENERIC_TEST_CATEGORIES = [
+    "happy-path",
+    "validation",
+    "auth-permission",
+    "state-transition",
+    "error-handling",
+    "boundary",
+    "idempotency-concurrency"
+];
+const ASSOCIATED_IMPORT_PROPAGATION_LIMIT = 25;
+export function buildRtm(graph, ledger, opts = {}) {
+    const targetSet = opts.targetIds ? new Set(opts.targetIds) : null;
+    const fileSet = opts.changedFiles ? new Set(opts.changedFiles) : null;
+    const statusSet = normalizeStatusFilter(opts.statuses);
+    const ledgerBySymbol = selectLedgerBySymbol(ledger, graph);
+    const indexes = buildRtmIndexes(graph);
+    const baseRows = denominatorBehaviors(graph)
+        .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));
+    const rows = opts.limit && opts.limit > 0 ? filteredRows.slice(0, opts.limit) : filteredRows;
+    return { summary: summarizeRows(baseRows), rows, ...(opts.scope ? { scope: opts.scope } : {}) };
+}
+function inScope(node, targetSet, fileSet) {
+    if (!targetSet && !fileSet)
+        return true;
+    if (targetSet?.has(node.external_id))
+        return true;
+    const file = nodeFileRef(node);
+    return file !== "" && fileSet?.has(file) === true;
+}
+export function renderRtmMarkdown(result) {
+    const s = result.summary;
+    const lines = [
+        "# OrangePro Traceability Matrix",
+        "",
+        "Deterministic local report. Public Proven is derived only from dynamic targeted-proof ledger records; static graph links and LLM output never set Proven.",
+        "",
+        "| Metric | Value |",
+        "|---|---:|",
+        `| Total denominator behaviors | ${s.total} |`,
+        `| Dynamically Proven | ${s.proven} |`,
+        `| Runtime-covered | ${s.runtime_covered} |`,
+        `| Associated signal | ${s.associated} |`,
+        `| No integration signal | ${s.no_link} |`,
+        `| Reproven this run | ${s.reproven_this_run} |`,
+        `| Generated unverifiable | ${s.generated_unverifiable} |`,
+        `| Dynamic Proven source | ${s.coverage_confirmed} / ${s.coverage_total} (${s.coverage_pct}%) |`,
+        `| Current graph kept rate | ${s.kept_rate}% (${s.reproven_this_run}/${s.attempted}) |`,
+        ""
+    ];
+    if (result.scope?.guidance) {
+        lines.push(`> ${escapeMarkdown(result.scope.guidance)}`, "");
+    }
+    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.`, "");
+    }
+    if (result.rows.length === 0) {
+        lines.push("No RTM rows matched this scope. Run `opro analyze .` first, widen filters, or use `opro gaps` for baseline opportunities.", "");
+        return lines.join("\n");
+    }
+    lines.push("| Behavior | Code Symbol | Area | Language | Test Signal | Status | Suggested Next Test | Ledger Outcome |");
+    lines.push("|---|---|---|---|---|---|---|---|");
+    for (const row of result.rows) {
+        lines.push([
+            row.behavior,
+            row.code_symbol || row.behavior_id,
+            row.area,
+            row.language,
+            row.test_signal,
+            row.status,
+            row.suggested_next_test,
+            row.ledger_outcome
+        ]
+            .map((cell) => escapeMarkdown(cell))
+            .join(" | ")
+            .replace(/^/, "| ")
+            .replace(/$/, " |"));
+    }
+    lines.push("");
+    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 rows = result.rows.map((row) => [
+        row.behavior,
+        row.behavior_id,
+        row.kind,
+        row.code_symbol,
+        row.file,
+        row.area,
+        row.language,
+        row.evidence_tier,
+        row.test_signal,
+        row.status,
+        row.suggested_next_test,
+        row.ledger_outcome,
+        row.ledger_run_id
+    ]);
+    return [header, ...rows].map((row) => row.map(csvCell).join(",")).join("\n") + "\n";
+}
+function toRtmRow(indexes, node, selected) {
+    const ledgerRecord = selected?.record;
+    const file = nodeFileRef(node);
+    // `proven` was already gated on isDynamicProofRecord AND a current-fingerprint
+    // match in selectLedgerBySymbol; a record that only passes isDynamicProofRecord
+    // (stale/absent fingerprint) arrives here with proven === false → not Proven.
+    const dynamicProof = selected?.proven === true;
+    const evidence = evidenceTierFor(indexes, node, file, dynamicProof);
+    const status = statusFor(evidence, ledgerRecord, dynamicProof);
+    const testSignal = dynamicProof ? dynamicProofSignalFor(ledgerRecord) : evidence === "runtime" ? runtimeSignalFor(node) : testSignalFor(indexes, node.external_id, file);
+    return {
+        behavior: node.title || node.external_id,
+        behavior_id: node.external_id,
+        kind: node.kind,
+        code_symbol: node.kind === "CodeSymbol" ? node.external_id : "",
+        file,
+        area: codeAreaOf(file),
+        language: node.kind === "CodeSymbol" ? languageLabel(languageOf(file)) : "Requirement",
+        evidence_tier: evidence,
+        test_signal: testSignal,
+        status,
+        suggested_next_test: suggestedNextTest(node, file, status),
+        ledger_outcome: ledgerRecord ? `${ledgerRecord.status}${ledgerRecord.closed ? " closed" : ""}` : "",
+        ledger_run_id: ledgerRecord?.run_id ?? ""
+    };
+}
+function evidenceTierFor(indexes, node, file, dynamicProof) {
+    if (dynamicProof)
+        return "proven";
+    if (node.kind === "CodeSymbol" && node.properties.runtime_covered === true)
+        return "runtime";
+    if (hasAssociatedSignal(indexes, node.external_id, file))
+        return "associated";
+    return "none";
+}
+function statusFor(evidence, ledgerRecord, dynamicProof) {
+    if (evidence === "proven")
+        return dynamicProof && ledgerRecord?.status === "reproven" && ledgerRecord.closed ? "Reproven (this run)" : "Proven";
+    if (evidence === "runtime")
+        return "Runtime-covered";
+    if (ledgerRecord?.status === "generated_unverifiable")
+        return "Generated-unverifiable";
+    if (evidence === "associated")
+        return "Associated signal";
+    return "No integration signal";
+}
+function summarizeRows(rows) {
+    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;
+    return {
+        total: rows.length,
+        proven,
+        runtime_covered: rows.filter((row) => row.evidence_tier === "runtime").length,
+        associated: rows.filter((row) => row.evidence_tier === "associated").length,
+        no_link: rows.filter((row) => row.evidence_tier === "none").length,
+        reproven_this_run: reproven,
+        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_total: rows.length,
+        coverage_pct: rows.length > 0 ? Number(((proven / rows.length) * 100).toFixed(1)) : 0
+    };
+}
+/**
+ * Best-ever-proven, fingerprint-scoped ledger selection (replaces pure
+ * latest-timestamp-wins). Per symbol:
+ *   1. Pick the NEWEST record that is a valid dynamic proof (`isDynamicProofRecord`)
+ *      AND whose `target_fingerprint` equals the target's current fingerprint → Proven.
+ *   2. Otherwise fall back to the latest overall record for status/diagnostics,
+ *      but NOT Proven (this is the trust-conservative branch — a stale/absent
+ *      fingerprint never counts as Proven).
+ * A later flaky/failed prove can no longer demote a genuine proof of the same
+ * unchanged code; a proof only lapses when the code (its file hash) changes.
+ */
+function selectLedgerBySymbol(ledger, graph) {
+    const bySymbol = new Map();
+    ledger.records.forEach((record, index) => {
+        const list = bySymbol.get(record.target_symbol);
+        if (list)
+            list.push({ record, index });
+        else
+            bySymbol.set(record.target_symbol, [{ record, index }]);
+    });
+    const newest = (entries) => entries.reduce((best, e) => (compareLedgerRecords(e.record, e.index, best.record, best.index) > 0 ? e : best));
+    const out = new Map();
+    for (const [symbol, entries] of bySymbol) {
+        const currentFingerprint = targetFingerprint(graph, symbol);
+        const matches = currentFingerprint
+            ? entries.filter((e) => isDynamicProofRecord(e.record) && e.record.target_fingerprint === currentFingerprint)
+            : [];
+        if (matches.length > 0) {
+            out.set(symbol, { record: newest(matches).record, proven: true });
+        }
+        else {
+            out.set(symbol, { record: newest(entries).record, proven: false });
+        }
+    }
+    return out;
+}
+function compareLedgerRecords(a, aIndex, b, bIndex) {
+    const aTs = Date.parse(a.ts);
+    const bTs = Date.parse(b.ts);
+    const safeATs = Number.isFinite(aTs) ? aTs : 0;
+    const safeBTs = Number.isFinite(bTs) ? bTs : 0;
+    return safeATs - safeBTs || aIndex - bIndex;
+}
+function buildRtmIndexes(graph) {
+    const nodeById = new Map(graph.nodes.map((n) => [n.external_id, n]));
+    const staticSignalsById = new Map();
+    const associatedSignalsById = new Map();
+    const associatedSignalsByFile = new Map();
+    const add = (map, key, value) => {
+        const set = map.get(key);
+        if (set)
+            set.add(value);
+        else
+            map.set(key, new Set([value]));
+    };
+    const importTargetsByFile = new Map();
+    const addFileAssociation = (file, value) => {
+        add(associatedSignalsByFile, file, value);
+        const imports = importTargetsByFile.get(file) ?? [];
+        if (imports.length > ASSOCIATED_IMPORT_PROPAGATION_LIMIT)
+            return;
+        for (const importedFile of imports)
+            add(associatedSignalsByFile, importedFile, value);
+    };
+    for (const e of graph.edges) {
+        if (e.evidence_strength !== "hard")
+            continue;
+        if (e.relationship_type === "IMPORTS" && isFileSignalKey(e.from_external_id) && isFileSignalKey(e.to_external_id)) {
+            importTargetsByFile.set(e.from_external_id, [...(importTargetsByFile.get(e.from_external_id) ?? []), e.to_external_id]);
+        }
+        if (e.relationship_type !== "COVERS" && e.relationship_type !== "TESTED_BY")
+            continue;
+        const from = nodeById.get(e.from_external_id);
+        const to = nodeById.get(e.to_external_id);
+        if (from?.kind === "TestCase" && to)
+            add(staticSignalsById, e.to_external_id, e.from_external_id);
+        if (to?.kind === "TestCase" && from)
+            add(staticSignalsById, e.from_external_id, e.to_external_id);
+    }
+    for (const e of graph.candidate_edges) {
+        if (e.review_status === "ai_suggested")
+            continue;
+        if (e.relationship_type !== "MAY_RELATE_TO" && e.relationship_type !== "MAY_BE_TESTED_BY" && e.relationship_type !== "MAY_COVER")
+            continue;
+        add(associatedSignalsById, e.from_external_id, e.to_external_id);
+        add(associatedSignalsById, e.to_external_id, e.from_external_id);
+        for (const [key, value] of [[e.from_external_id, e.to_external_id], [e.to_external_id, e.from_external_id]]) {
+            if (isFileSignalKey(key))
+                addFileAssociation(key, value);
+        }
+    }
+    const freeze = (map) => new Map([...map.entries()].map(([key, values]) => [key, [...values].sort()]));
+    return {
+        staticSignalsById: freeze(staticSignalsById),
+        associatedSignalsById: freeze(associatedSignalsById),
+        associatedSignalsByFile: freeze(associatedSignalsByFile)
+    };
+}
+function isFileSignalKey(id) {
+    return !id.startsWith("sym:") && !id.startsWith("test:") && !id.startsWith("flow:");
+}
+function hasAssociatedSignal(indexes, externalId, file) {
+    return indexes.staticSignalsById.has(externalId) || indexes.associatedSignalsById.has(externalId) || (file !== "" && indexes.associatedSignalsByFile.has(file));
+}
+function testSignalFor(indexes, externalId, file) {
+    const staticSignals = indexes.staticSignalsById.get(externalId) ?? [];
+    if (staticSignals.length > 0)
+        return `static candidate: ${staticSignals.slice(0, 3).join("; ")}`;
+    const associated = [...(indexes.associatedSignalsById.get(externalId) ?? []), ...(file ? indexes.associatedSignalsByFile.get(file) ?? [] : [])]
+        .filter((id) => id !== externalId && id !== file)
+        .sort();
+    if (associated.length > 0)
+        return associated.slice(0, 3).join("; ");
+    return "";
+}
+function isDynamicProofRecord(record) {
+    const proof = record?.dynamic_proof;
+    return (record?.status === "reproven" &&
+        record.closed === true &&
+        proof?.proof_kind === "dynamic_targeted" &&
+        proof.baseline_green === true &&
+        proof.mutant_failed_assertion === true &&
+        proof.target_not_mocked === true);
+}
+function dynamicProofSignalFor(record) {
+    const proof = record?.dynamic_proof;
+    const parts = ["dynamic targeted proof"];
+    if (proof?.runner)
+        parts.push(proof.runner);
+    if (proof?.sentinel)
+        parts.push(`sentinel:${proof.sentinel}`);
+    if (record?.run_id)
+        parts.push(record.run_id);
+    return parts.join(" · ");
+}
+function suggestedNextTest(node, file, status) {
+    if (status === "Proven" || status === "Reproven (this run)" || status === "Runtime-covered")
+        return "";
+    const haystack = `${node.title ?? ""} ${node.external_id} ${file}`.toLowerCase();
+    const category = haystack.match(/auth|permission|role|rbac|login|session|token/) ? "auth-permission" :
+        haystack.match(/valid|parse|schema|sanitize|input|required/) ? "validation" :
+            haystack.match(/create|update|delete|remove|archive|status|enable|disable|transition/) ? "state-transition" :
+                haystack.match(/error|fail|recover|retry|exception/) ? "error-handling" :
+                    haystack.match(/limit|range|empty|max|min|overflow|boundary/) ? "boundary" :
+                        haystack.match(/concurrent|lock|race|idempot|duplicate/) ? "idempotency-concurrency" :
+                            GENERIC_TEST_CATEGORIES[0];
+    return `Add a ${category} test that asserts this behavior.`;
+}
+function normalizeStatusFilter(statuses) {
+    if (!statuses || statuses.length === 0)
+        return null;
+    const out = new Set();
+    for (const raw of statuses) {
+        const s = raw.trim().toLowerCase().replace(/_/g, "-");
+        if (s === "proven")
+            out.add("Proven");
+        else if (s === "runtime" || s === "runtime-covered" || s === "runtimecovered")
+            out.add("Runtime-covered");
+        else if (s === "associated")
+            out.add("Associated signal");
+        else if (s === "no-link" || s === "nolink" || s === "none")
+            out.add("No integration signal");
+        else if (s === "reproven" || s === "reproven-this-run")
+            out.add("Reproven (this run)");
+        else if (s === "generated-unverifiable" || s === "unverifiable")
+            out.add("Generated-unverifiable");
+    }
+    return out.size > 0 ? out : null;
+}
+function runtimeSignalFor(node) {
+    const formats = Array.isArray(node.properties.runtime_coverage_formats)
+        ? node.properties.runtime_coverage_formats.filter((f) => typeof f === "string")
+        : [];
+    return formats.length > 0 ? `runtime coverage (${formats.sort().join(", ")})` : "runtime coverage";
+}
+function nodeFileRef(n) {
+    if (typeof n.properties.file === "string")
+        return n.properties.file;
+    if (typeof n.provenance?.source_ref === "string")
+        return n.provenance.source_ref;
+    return n.external_id.startsWith("sym:") ? n.external_id.replace(/^sym:/, "").split("#")[0] : "";
+}
+function cleanPathParts(sourceRefOrPath) {
+    if (!sourceRefOrPath)
+        return [];
+    return sourceRefOrPath.replace(/^[./]+/, "").split(/[#?]/)[0].split(/[\\/]/).filter(Boolean);
+}
+function parentDir(parts) {
+    return parts.length > 1 ? parts[parts.length - 2] : parts[0] || "core";
+}
+function codeAreaOf(sourceRefOrPath) {
+    const parts = cleanPathParts(sourceRefOrPath);
+    if (parts.length === 0)
+        return "core";
+    const language = languageOf(sourceRefOrPath ?? "");
+    if (language === "go") {
+        if (parts[0] === "server" && parts[1] === "channels" && parts[2])
+            return `server/${parts[2]}`;
+        return parts.length > 2 ? parts.slice(0, 2).join("/") : parentDir(parts);
+    }
+    if (language === "typescript" || language === "javascript") {
+        if (parts[0] === "webapp" && parts[1] === "channels" && parts[2] === "src" && parts[3])
+            return `webapp/${parts[3]}`;
+        return parts.length > 2 ? parts.slice(0, 2).join("/") : parentDir(parts);
+    }
+    return parts.length > 2 ? parts.slice(0, 2).join("/") : parentDir(parts);
+}
+function languageLabel(language) {
+    const labels = {
+        typescript: "TypeScript/JavaScript",
+        javascript: "TypeScript/JavaScript",
+        python: "Python",
+        go: "Go",
+        java: "Java",
+        ruby: "Ruby",
+        kotlin: "Kotlin",
+        rust: "Rust",
+        php: "PHP",
+        csharp: "C#",
+        swift: "Swift",
+        c: "C",
+        cpp: "C++"
+    };
+    return labels[language] ?? (language || "Unknown");
+}
+function escapeMarkdown(value) {
+    return value.replace(/\|/g, "\\|").replace(/[\r\n\t]/g, " ");
+}
+function csvCell(value) {
+    const normalized = value.replace(/\r/g, " ");
+    const safe = /^[=+\-@\t]/.test(normalized) ? `'${normalized}` : normalized;
+    if (!/[",\n]/.test(safe))
+        return safe;
+    return `"${safe.replace(/"/g, '""')}"`;
+}

package/dist/local/score/coverage.js

@@ -0,0 +1,99 @@
+import { denominatorComposition, isDenominatorEligible } from "../graph/factories.js";
+/**
+ * Phase 5.1 — static assertion-candidate coverage over the DENOMINATOR
+ * behaviors (CodeSymbols + Requirements), split by the test layer that links
+ * each one.
+ *
+ * Carry-over #3: the graph.html headline counted only UserFlows (test-inferred),
+ * so it read ~0% on real repos even when the confirmer proved many CodeSymbols.
+ * This computes the metric over `denominatorBehaviors` instead.
+ *
+ * A behavior has a static candidate iff it has a hard TESTED_BY/COVERS edge.
+ * Public Proven is stricter and comes only from a dynamic targeted-proof ledger
+ * record. This module remains as a diagnostic/static-association helper.
+ */
+// Most-informative structural layer first. A behavior confirmed by both a unit
+// and an e2e test is reported as `unit` (the structural confirmation); an
+// e2e-only-confirmed behavior buckets as `e2e`.
+const LAYER_PRECEDENCE = ["unit", "component", "integration", "api", "e2e", "manual", "unknown"];
+const emptyByLayer = () => ({
+    unit: 0,
+    component: 0,
+    integration: 0,
+    api: 0,
+    e2e: 0,
+    manual: 0,
+    unknown: 0
+});
+const layerOf = (n) => {
+    const l = n && typeof n.properties.test_layer === "string" ? n.properties.test_layer : "";
+    return LAYER_PRECEDENCE.includes(l) ? l : "unknown";
+};
+export function confirmedCoverageByLayer(graph) {
+    const byId = new Map();
+    for (const n of graph.nodes)
+        byId.set(n.external_id, n);
+    // behavior external_id -> the layers of the tests that confirm it (hard edges only).
+    const confirmingLayers = new Map();
+    const record = (behaviorId, testNode) => {
+        let set = confirmingLayers.get(behaviorId);
+        if (!set) {
+            set = new Set();
+            confirmingLayers.set(behaviorId, set);
+        }
+        set.add(layerOf(testNode));
+    };
+    for (const e of graph.edges) {
+        if (e.relationship_type !== "TESTED_BY" && e.relationship_type !== "COVERS")
+            continue;
+        // Only HARD edges count as static assertion candidates. A weaker/reviewed
+        // edge must not inflate the diagnostic metric.
+        if (e.evidence_strength !== "hard")
+            continue;
+        const from = byId.get(e.from_external_id);
+        const to = byId.get(e.to_external_id);
+        // The test endpoint is the TestCase; the other endpoint is the behavior.
+        if (from?.kind === "TestCase")
+            record(e.to_external_id, from);
+        else if (to?.kind === "TestCase")
+            record(e.from_external_id, to);
+    }
+    const behaviors = graph.nodes.filter(isDenominatorEligible);
+    const by_layer = emptyByLayer();
+    let confirmed = 0;
+    for (const b of behaviors) {
+        const layers = confirmingLayers.get(b.external_id);
+        if (!layers)
+            continue; // no hard edge -> not confirmed
+        confirmed++;
+        const primary = LAYER_PRECEDENCE.find((l) => layers.has(l)) ?? "unknown";
+        by_layer[primary]++;
+    }
+    const total_behaviors = behaviors.length;
+    return {
+        total_behaviors,
+        confirmed,
+        confirmed_pct: total_behaviors > 0 ? round1((confirmed / total_behaviors) * 100) : 0,
+        by_layer,
+        unknown_count: by_layer.unknown,
+        unknown_pct: confirmed > 0 ? round1((by_layer.unknown / confirmed) * 100) : 0
+    };
+}
+function round1(n) {
+    return Math.round(n * 10) / 10;
+}
+/**
+ * The static-candidate metric AND the denominator composition as ONE atomic pair.
+ *
+ * It ALWAYS recomputes both from the graph's nodes/edges and never trusts the persisted
+ * `analysis.confirmed_by_layer`/`denominator`: a persisted value can be stale (an old
+ * graph, or one edited out of band) in ways a cheap consistency check can't catch (e.g.
+ * the total agrees but `confirmed` was computed before a downgrade). Recomputing is O(n)
+ * and diagnostics are not a hot path, so the trade buys a hard guarantee — every
+ * static diagnostic reports the SAME numbers, consistent with the actual graph, with
+ * `coverage.total_behaviors === denominator.total` by construction. The persisted
+ * `analysis` fields remain in graph.json for the JSON contract; only rendering recomputes.
+ */
+export function resolveCoverage(graph) {
+    return { coverage: confirmedCoverageByLayer(graph), denominator: denominatorComposition(graph) };
+}

package/dist/local/score/doctor.js

@@ -0,0 +1,67 @@
+import { nodesByKind } from "../graph/factories.js";
+/**
+ * Recommend the smallest next source that would most improve generated-test
+ * quality. Recommendations are ranked by expected impact; the ranking heuristic
+ * itself is internal, only the human-facing actions are returned.
+ */
+export function doctorGraph(graph, score) {
+    const b = score.breakdown;
+    const candidates = [];
+    if (b.acceptance_criteria < 0.6) {
+        candidates.push({
+            priority: 0,
+            action: "Add acceptance criteria or a small requirements template (CSV/Markdown).",
+            why: "The graph has code/test context but weak business intent, so tests cannot assert expected outcomes.",
+            expected_score_impact: "+10 to +20",
+            gain: (0.6 - b.acceptance_criteria) * 20
+        });
+    }
+    if (b.interface_mapping < 0.5) {
+        candidates.push({
+            priority: 0,
+            action: "Add an OpenAPI spec or route/screen docs.",
+            why: "Endpoint/screen mapping makes API and UI tests target real interfaces instead of guesses.",
+            expected_score_impact: "+5 to +12",
+            gain: (0.5 - b.interface_mapping) * 15
+        });
+    }
+    if (b.known_regressions < 0.3) {
+        candidates.push({
+            priority: 0,
+            action: "List known bugs or past incidents (even a short Markdown list).",
+            why: "Known regressions let generation produce durable regression tests, not just happy-path checks.",
+            expected_score_impact: "+4 to +10",
+            gain: (0.3 - b.known_regressions) * 10
+        });
+    }
+    if (b.validation_evidence < 0.5) {
+        candidates.push({
+            priority: 0,
+            action: "Reference existing test names/links or manual QA steps.",
+            why: "Validation evidence ties behaviors to real checks and improves coverage confidence.",
+            expected_score_impact: "+4 to +10",
+            gain: (0.5 - b.validation_evidence) * 12
+        });
+    }
+    if (nodesByKind(graph, "Requirement").length === 0) {
+        candidates.push({
+            priority: 0,
+            action: "Add a few explicit requirements with descriptions and actors.",
+            why: "Explicit requirement anchors raise specificity well beyond code-only inference.",
+            expected_score_impact: "+8 to +18",
+            gain: 16
+        });
+    }
+    candidates.sort((a, c) => c.gain - a.gain);
+    const recommendations = candidates.slice(0, 4).map((rec, i) => ({
+        priority: i + 1,
+        action: rec.action,
+        why: rec.why,
+        expected_score_impact: rec.expected_score_impact
+    }));
+    return {
+        status: score.band,
+        recommendations,
+        can_continue_without_recommendations: score.overall >= 40
+    };
+}