@orangepro/orangepro-mcp 0.2.4 → 0.2.5

package/README.md

@@ -23,7 +23,7 @@ The command writes:
 
 ```
 .orangepro/
-├── behavior-coverage.html   ← open this: interactive gap report
+├── behavior-coverage.html   ← open this: system map, risks, flows, behaviors
 ├── graph.json               ← deterministic evidence graph
 ├── COVERAGE_REPORT.md       ← coverage and gap summary
 ├── rtm.md                   ← requirements traceability matrix
@@ -32,6 +32,8 @@ The command writes:
 orangepro_generated/         ← contained generated tests; existing source files are untouched
 ```
 
+The report opens on a **system map** of your repo — entry lanes (GraphQL/HTTP/Jobs) flowing into the services they reach, sized by traffic, colored by evidence tier, risk-ringed — identical on every run. Each rerun shows a **delta banner**: what changed since last run, or "No changes — identical graph, identical ranking." Every one of the ~N behaviors gets a plain-English description; every top risk gets a deterministic context line and a state-aware next step.
+
 Run `opro export` when you want a machine-readable evidence pack.
 <img width="895" height="960" alt="Screenshot 2026-07-08 at 1 18 01 AM" src="https://github.com/user-attachments/assets/73b8a812-2eab-43a1-8aed-4289545e630b" />
 
@@ -181,11 +183,13 @@ Each generated test includes:
 - **Run hints** — where to write it, how to run it
 - **Scenario bucket + technique** — what failure mode it targets and how
 
+If the environment can't run tests yet (dependencies not installed, runner unconfigured), rejected drafts are kept as **Manual tests** — scenario, Given/When/Then steps, synthetic test data, and expected outcome in plain English, with the exact blocker named. Install dependencies and re-run `opro start` to turn them into runnable tests. Runnable tests always replace Manual tests for the same behavior; the two are never mixed.
+
 ---
 
 ## Test categories
 
-Generation is evidence-gated. A category is produced only when the graph has supporting evidence — never padded with generic filler. These are the public local generation buckets. The broader concern taxonomy used by planning prompts is not a public coverage taxonomy and does not change report tiers.
+Generation is evidence-gated. A category is produced only when the graph has supporting evidence — never padded with generic filler. These are the local generation buckets. The report additionally shows each risk's **applicable testing categories** (contract, boundary limits, integration flow, state lifecycle, failure recovery, …), derived deterministically from graph facts — covered categories from real attached tests render normally; the rest render locked, meaning "warranted here, generated on the platform," never "hidden tests exist." Neither taxonomy changes evidence tiers.
 
 | Category | What it targets |
 |----------|-----------------|
@@ -206,7 +210,8 @@ Every behavior gets exactly one tier. Nothing is labeled "tested" on faith.
 |------|---------------|------------------|
 | **Dynamically Proven** | A real test kills a targeted mutant of this behavior | `opro prove` after writing/running a test |
 | **Runtime-covered** | Coverage tool executed this code | `opro start --generate-coverage` |
-| **Statically Linked** | Import/name/structural match links a test to this code | Automatic during analysis |
+| **Statically Linked** | A test **imports and calls** this code — a hard structural link | Automatic during analysis |
+| **Unconfirmed Candidate** | A lexically similar test file exists, but nothing links it — a lead, **not evidence** | Automatic; upgrade it by writing the linking test |
 | **No Signal** | Nothing tests this behavior yet | — |
 
 > **"Dynamically Proven 0" is normal on first run.** Static analysis always runs. Dynamic proof requires running tests against targeted mutations. That's the trust model — nothing is Dynamically Proven until a real test kills a real mutant.
@@ -284,6 +289,8 @@ OrangePro separates **analysis** (what your code does) from **proof** (whether t
 | **Generate** | Grounded tests for top gaps, per-behavior | Yes (BYOK) |
 | **Prove** | Mutation-kill oracle confirms test actually breaks if behavior changes | No |
 
+Reruns are cache-accelerated: unchanged files skip re-parsing, BYOK stages don't re-spend tokens on unchanged inputs, and proof certificates persist in a local ledger until the certified file changes. Upgrading the tool auto-invalidates caches.
+
 ---
 
 ## Privacy

package/dist/local/analyze/behaviorContracts.js

@@ -6,8 +6,15 @@ const HTTP_METHODS = new Set(["get", "post", "put", "delete", "patch", "options"
 // - computed router methods/paths are ignored.
 // That is intentional while Endpoint nodes are informational only and excluded
 // from the coverage denominator.
-const NEST_METHOD_DECORATOR = /@(Get|Post|Put|Delete|Patch|Options|Head|All)\s*\(\s*(?:(["'`])([^"'`]*)\2)?\s*\)(?:\s|\/\*[\s\S]*?\*\/|\/\/[^\n]*\n)*?(?:public\s+|private\s+|protected\s+|async\s+)*([A-Za-z_$][A-Za-z0-9_$]*)\s*\(/g;
-const NEST_CONTROLLER_DECORATOR = /@Controller\s*\(\s*(?:(["'`])([^"'`]*)\1)?\s*\)\s*(?:export\s+)?class\s+([A-Za-z_$][A-Za-z0-9_$]*)/g;
+// Tolerates intermediate decorators (@UseGuards, @UseFilters, @HttpCode, …)
+// between the route decorator and the method name — decorator-stacked NestJS
+// controllers (Twenty: every route) previously produced ZERO endpoint contracts.
+const NEST_METHOD_DECORATOR = /@(Get|Post|Put|Delete|Patch|Options|Head|All)\s*\(\s*(?:(["'`])([^"'`]*)\2|\[\s*(["'`])([^"'`]*)\4\s*\])?\s*\)(?:\s|@[A-Za-z_$][A-Za-z0-9_$]*(?:\s*\((?:[^()]|\([^()]*\))*\))?|\/\*[\s\S]*?\*\/|\/\/[^\n]*\n)*?(?:public\s+|private\s+|protected\s+|async\s+)*([A-Za-z_$][A-Za-z0-9_$]*)\s*\(/g;
+const CLASS_DECLARATION = /(?:export\s+)?(?:abstract\s+)?class\s+([A-Za-z_$][A-Za-z0-9_$]*)/g;
+const NEST_GQL_METHOD_DECORATOR = /@(Query|Mutation|Subscription|ResolveField)\s*\((?:[^()]|\([^()]*\))*\)(?:\s|@[A-Za-z_$][A-Za-z0-9_$]*(?:\s*\((?:[^()]|\([^()]*\))*\))?|\/\*[\s\S]*?\*\/|\/\/[^\n]*\n)*?(?:public\s+|private\s+|protected\s+|async\s+)*([A-Za-z_$][A-Za-z0-9_$]*)\s*\(/g;
+const NEST_PROCESSOR_DECORATOR = /@Processor\s*\(\s*(?:(["'`])([^"'`]*)\1|[A-Za-z_$][A-Za-z0-9_$.]*)?\s*\)(?:\s|@[A-Za-z_$][A-Za-z0-9_$]*(?:\s*\((?:[^()]|\([^()]*\))*\))?|\/\*[\s\S]*?\*\/|\/\/[^\n]*\n)*?(?:export\s+)?class\s+([A-Za-z_$][A-Za-z0-9_$]*)/g;
+const NEST_PROCESS_METHOD_DECORATOR = /@Process\s*\((?:[^()]|\([^()]*\))*\)(?:\s|@[A-Za-z_$][A-Za-z0-9_$]*(?:\s*\((?:[^()]|\([^()]*\))*\))?|\/\*[\s\S]*?\*\/|\/\/[^\n]*\n)*?(?:public\s+|private\s+|protected\s+|async\s+)*([A-Za-z_$][A-Za-z0-9_$]*)\s*\(/g;
+const NEST_CONTROLLER_DECORATOR = /@Controller\s*\(\s*(?:(["'`])([^"'`]*)\1)?\s*\)(?:\s|@[A-Za-z_$][A-Za-z0-9_$]*(?:\s*\((?:[^()]|\([^()]*\))*\))?|\/\*[\s\S]*?\*\/|\/\/[^\n]*\n)*?(?:export\s+)?class\s+([A-Za-z_$][A-Za-z0-9_$]*)/g;
 const EXPRESS_ROUTER_CALL = /\b(?:router|app)\s*\.\s*(get|post|put|delete|patch|options|head|all)\s*\(\s*(["'`])([^"'`]*)\2\s*,\s*([A-Za-z_$][A-Za-z0-9_$]*(?:\.[A-Za-z_$][A-Za-z0-9_$]*)?|\([^)]*\)\s*=>|async\s+\([^)]*\)\s*=>|function\s+[A-Za-z_$][A-Za-z0-9_$]*)/gi;
 const EXPRESS_ROUTE_CHAIN = /\b(?:router|app)\s*\.\s*route\s*\(\s*(["'`])([^"'`]*)\1\s*\)((?:\s*\.\s*(?:get|post|put|delete|patch|options|head|all)\s*\([^)]*\))+)/gi;
 const CHAINED_METHOD_CALL = /\.\s*(get|post|put|delete|patch|options|head|all)\s*\(\s*([A-Za-z_$][A-Za-z0-9_$]*(?:\.[A-Za-z_$][A-Za-z0-9_$]*)?|\([^)]*\)\s*=>|async\s+\([^)]*\)\s*=>|function\s+[A-Za-z_$][A-Za-z0-9_$]*)/gi;
@@ -17,6 +24,8 @@ export function extractBehaviorContracts(content, file) {
     return dedupeContracts([
         ...extractFileRouteContracts(content, file),
         ...extractNestContracts(content, file),
+        ...extractNestGraphqlContracts(content, file),
+        ...extractNestProcessorContracts(content, file),
         ...extractRouterContracts(content, file, EXPRESS_ROUTER_CALL, "express"),
         ...extractExpressRouteChains(content, file),
         ...extractRouterContracts(content, file, FASTIFY_CALL, "fastify")
@@ -52,8 +61,8 @@ function extractNestContracts(content, file) {
         const index = match.index ?? 0;
         const controller = nearestController(controllers, index);
         const method = httpMethod(match[1]);
-        const routePath = joinRoutePaths(controller?.path ?? "", match[3] ?? "");
-        const handler = match[4];
+        const routePath = joinRoutePaths(controller?.path ?? "", match[3] ?? match[5] ?? "");
+        const handler = match[6];
         contracts.push(makeContract({
             file,
             framework: "nestjs",
@@ -65,6 +74,70 @@ function extractNestContracts(content, file) {
     }
     return contracts;
 }
+function extractNestGraphqlContracts(content, file) {
+    // GraphQL resolvers are first-class user-triggerable entry points. In
+    // NestJS-heavy monorepos (Twenty: 415 @Query/@Mutation methods vs 139 HTTP
+    // routes) skipping them left almost every user behavior without an Endpoint
+    // anchor, so static flows rooted at internal orphan methods instead.
+    if (!/@(Query|Mutation|Subscription)\s*\(/.test(content))
+        return [];
+    const resolvers = [...content.matchAll(CLASS_DECLARATION)].map((match) => ({
+        index: match.index ?? 0,
+        path: "",
+        name: match[1]
+    }));
+    if (resolvers.length === 0)
+        return [];
+    const contracts = [];
+    for (const match of content.matchAll(NEST_GQL_METHOD_DECORATOR)) {
+        const resolver = nearestController(resolvers, match.index ?? 0);
+        if (!resolver)
+            continue;
+        const opKind = match[1].toUpperCase();
+        if (opKind === "RESOLVEFIELD")
+            continue; // field resolvers are not user-triggerable operations
+        const handler = match[2];
+        contracts.push(makeContract({
+            file,
+            framework: "nestjs",
+            kind: "graphql_operation",
+            method: opKind,
+            path: `graphql:${handler}`,
+            handler,
+            controller: resolver.name
+        }));
+    }
+    return contracts;
+}
+function extractNestProcessorContracts(content, file) {
+    // Background jobs and crons are behaviors (June 27 definition: user- or
+    // system-triggerable, cross-layer, observable outcome). Anchoring them lets
+    // the flow walker show queue-driven chains instead of orphan roots.
+    const processors = [...content.matchAll(NEST_PROCESSOR_DECORATOR)].map((match) => ({
+        index: match.index ?? 0,
+        path: normalizeRoutePath(match[2] ?? ""),
+        name: match[3]
+    }));
+    if (processors.length === 0)
+        return [];
+    const contracts = [];
+    for (const match of content.matchAll(NEST_PROCESS_METHOD_DECORATOR)) {
+        const processor = nearestController(processors, match.index ?? 0);
+        if (!processor)
+            continue;
+        const handler = match[1];
+        contracts.push(makeContract({
+            file,
+            framework: "nestjs",
+            kind: "queue_processor",
+            method: "JOB",
+            path: `queue:${processor.path || processor.name}`,
+            handler,
+            controller: processor.name
+        }));
+    }
+    return contracts;
+}
 function nearestController(controllers, index) {
     let current;
     for (const controller of controllers) {
@@ -111,7 +184,7 @@ function makeContract(input) {
     return {
         id: `endpoint:${slugify(`${input.method}-${input.path}-${input.file}-${input.handler ?? ""}`)}`,
         title,
-        kind: "http_endpoint",
+        kind: input.kind ?? "http_endpoint",
         framework: input.framework,
         method: input.method,
         path: input.path,

package/dist/local/analyze/parseCache.js

@@ -1,3 +1,4 @@
+import { createRequire } from "node:module";
 /**
  * Phase 5.4.2 — persistent PARSE cache.
  *
@@ -55,6 +56,19 @@
 // v16: symbol extraction now carries source line spans for runtime coverage
 // report ingestion; warm v15 entries lack the ranges and cannot be mapped.
 export const PARSER_VERSION = 17; // 17: Go method symbols receiver-qualified (Recv.M + member_of)
+/** Tool package version, folded into the cache guard so UPGRADES auto-invalidate
+ *  the cache — bumping PARSER_VERSION by hand is a discipline; this is a lock.
+ *  (The stale-cache incident: upgraded binary served old per-file results.) */
+export const TOOL_VERSION = (() => {
+    try {
+        // dist/local/analyze/ → ../../../package.json
+        const req = createRequire(import.meta.url);
+        return String(req("../../../package.json").version ?? "0");
+    }
+    catch {
+        return "0";
+    }
+})();
 const SYMBOL_KINDS = new Set(["function", "class", "const", "method"]);
 /** Strict structural validation — persisted data is untrusted FOR SHAPE; reject anything off-shape. */
 function validSymbols(v) {
@@ -100,7 +114,7 @@ export class ParseCache {
     constructor(data) {
         this.entries = new Map();
         // A version mismatch (or no data) starts empty — never trust a stale schema.
-        if (!data || data.version !== PARSER_VERSION || !data.entries || typeof data.entries !== "object")
+        if (!data || data.version !== PARSER_VERSION || data.tool !== TOOL_VERSION || !data.entries || typeof data.entries !== "object")
             return;
         for (const [key, raw] of Object.entries(data.entries)) {
             if (!raw || typeof raw !== "object")
@@ -159,6 +173,6 @@ export class ParseCache {
             if (e)
                 entries[key] = e;
         }
-        return { version: PARSER_VERSION, entries };
+        return { version: PARSER_VERSION, tool: TOOL_VERSION, entries };
     }
 }

package/dist/local/cli.js

@@ -278,7 +278,10 @@ async function main() {
                 out("  - opro agent --client claude-code");
                 out("  - opro agent --client cursor");
                 out("  - opro agent --client opencode");
-                for (const w of res.warnings)
+                // opStart aggregates warnings from ai-flows generate AND apply — the same
+                // message (e.g. the prompt entry cap) can legitimately arrive twice.
+                // Dedupe at print time; JSON output keeps the raw array.
+                for (const w of [...new Set(res.warnings)])
                     out(`  warning: ${w}`);
             }
             return 0;
@@ -468,7 +471,7 @@ async function main() {
                     }
                     if (coverageReport)
                         out(`  coverage report:         ${coverageReport}`);
-                    for (const w of [...res.warnings, ...aiFlowWarnings, ...htmlWarnings])
+                    for (const w of [...new Set([...res.warnings, ...aiFlowWarnings, ...htmlWarnings])])
                         out(`  warning: ${w}`);
                     const sugg = res.analysis.exclude_suggestions ?? [];
                     if (sugg.length) {
@@ -579,7 +582,8 @@ async function main() {
                         out(`     next: ${b.next_step}`);
                     }
                     for (const nk of res.non_killing) {
-                        out(`  mutant survived: ${nk.target_symbol}${nk.test_path ? ` (test: ${nk.test_path})` : ""}`);
+                        const nkLabel = nk.mutant_status === "associated_non_assertion_failure" ? "mutant failed (non-assertion)" : "mutant survived";
+                        out(`  ${nkLabel}: ${nk.target_symbol}${nk.test_path ? ` (test: ${nk.test_path})` : ""}`);
                         out(`     ${nk.note}`);
                     }
                 }

package/dist/local/enrich/markdown.js

@@ -4,6 +4,14 @@ import { slugify } from "../util/ids.js";
 import { redactSecrets } from "../util/redact.js";
 const DETECTOR = "markdown_docs";
 const MAX_REQUIREMENTS = 60;
+/**
+ * Repo-governance and template markdown must never mint Requirement nodes.
+ * Hint words like "should"/"must" are ubiquitous in CONTRIBUTING files and
+ * PR/issue templates — on Hono, ".github/PULL_REQUEST_TEMPLATE.md" produced
+ * REQ-md-the-author-should-do-the-following-if-applicable and surfaced as the
+ * report's top suggested next action. Product docs (README, docs/) still count.
+ */
+const GOVERNANCE_MD_RE = /(^|\/)\.github\/|(^|\/)(CONTRIBUTING|CODE_OF_CONDUCT|PULL_REQUEST_TEMPLATE|ISSUE_TEMPLATE|SECURITY|SUPPORT|CHANGELOG|LICENSE|GOVERNANCE|MAINTAINERS|CODEOWNERS|AUTHORS)[^\/]*$|(^|\/)\.changeset\/|\/templates?\/|(^|\/)(AGENTS|CLAUDE|GEMINI|COPILOT)\.md$|(^|\/)\.cursor(rules)?\//i;
 /** Words that suggest a heading describes a requirement/feature behavior. */
 const REQUIREMENT_HINTS = [
     "requirement",
@@ -53,6 +61,9 @@ function parseBullet(line) {
  * Bounded to ~60 requirements; all captured text is secret-redacted.
  */
 export function enrichFromMarkdown(relPath, content) {
+    if (GOVERNANCE_MD_RE.test(relPath)) {
+        return { nodes: [], edges: [], candidate_edges: [], sources: [], warnings: [] };
+    }
     const nodes = [];
     const edges = [];
     const warnings = [];

package/dist/local/flows/flowWalker.js

@@ -3,7 +3,7 @@ import { LOCAL_GRAPH_SCHEMA_VERSION } from "../graph/ontology.js";
 import { rankRiskGaps } from "../score/risk.js";
 import { stableId } from "../util/ids.js";
 const DEFAULT_MAX_DEPTH = 8;
-const DEFAULT_MAX_FLOWS_PER_ENTRY = 20;
+const DEFAULT_MAX_FLOWS_PER_ENTRY = 5;
 const DEFAULT_GLOBAL_CAP = 500;
 const HIGH_ROUTE_RE = /payment|refund|checkout|cart|order|auth|login|token|customer|user|tax|fulfillment|ship/i;
 const MUTATION_METHOD_RE = /^(POST|PUT|PATCH|DELETE)\b/i;
@@ -103,11 +103,16 @@ export function rankEntries(graph, entries, adjacency) {
         gap.id,
         gap.risk_score
     ]));
-    return [...entries].sort((a, b) => {
-        const aScore = Math.max(riskScores.get(a.start) ?? 0, fallbackScore(a, adjacency));
-        const bScore = Math.max(riskScores.get(b.start) ?? 0, fallbackScore(b, adjacency));
-        return bScore - aScore || a.kind.localeCompare(b.kind) || a.external_id.localeCompare(b.external_id) || a.start.localeCompare(b.start);
-    });
+    // Endpoint-anchored flows first. An Endpoint entry IS the definition of a
+    // user-triggerable behavior (June 27 agreement); orphan call-graph roots are
+    // useful but must never crowd endpoints out of the global cap — on Twenty,
+    // saturated risk ties let ~25 internal orphan methods consume all 500 flow
+    // slots while every HTTP/GraphQL entry point went unrendered.
+    const score = (e) => Math.max(riskScores.get(e.start) ?? 0, fallbackScore(e, adjacency));
+    const byScore = (a, b) => score(b) - score(a) || a.external_id.localeCompare(b.external_id) || a.start.localeCompare(b.start);
+    const endpoints = entries.filter((e) => e.kind === "Endpoint").sort(byScore);
+    const behaviors = entries.filter((e) => e.kind !== "Endpoint").sort(byScore);
+    return [...endpoints, ...behaviors];
 }
 function prunePrefixSubsumed(flows) {
     const sorted = [...flows].sort((a, b) => b.path.length - a.path.length || a.id.localeCompare(b.id));

package/dist/local/generate/generator.js

@@ -552,7 +552,7 @@ export function gatherContext(graph, behavior, framework, fileReader) {
         acceptance_criteria: acceptance,
         workflow_steps: workflow,
         framework,
-        test_layer: inferLayer(behavior, framework),
+        test_layer: inferLayer(behavior, framework, graph),
         code_context: dedupe(codeContext),
         source_excerpts: excerpts,
         weak_context: dedupe(weakContext),
@@ -602,7 +602,7 @@ function flowChainFor(graph, behavior) {
         };
     });
 }
-function inferLayer(behavior, framework) {
+function inferLayer(behavior, framework, graph) {
     const fw = framework.toLowerCase();
     if (fw.includes("playwright") || fw.includes("cypress"))
         return "e2e";
@@ -613,6 +613,21 @@ function inferLayer(behavior, framework) {
     const hint = String(behavior.properties.test_layer ?? "");
     if (hint)
         return hint;
+    // Graph-aware default (hop-count methodology): a behavior that an endpoint
+    // implements, or that participates in a multi-step call chain, is an
+    // INTEGRATION target — the code→flows→behaviors journey is the product;
+    // "unit" is only for genuinely 0-hop leaf functions. The old blanket
+    // "unit" default stamped every vitest/jest repo unit-first.
+    if (graph) {
+        const id = behavior.external_id;
+        const isEntryHandler = graph.edges.some((e) => e.relationship_type === "IMPLEMENTED_IN" && e.to_external_id === id);
+        if (isEntryHandler)
+            return "integration";
+        const inChain = graph.edges.some((e) => e.relationship_type === "CALLS" && (e.from_external_id === id || e.to_external_id === id)) ||
+            (graph.analysis?.flows?.flows ?? []).some((f) => f.entry_point.external_id === id || f.hops.some((h) => h.from === id || h.to === id));
+        if (inChain)
+            return "integration";
+    }
     return "unit";
 }
 function tooThin(ctx) {
@@ -2366,13 +2381,49 @@ export async function generateTests(graph, opts, provider, fileReader, clock = s
                 const runnable = isRunnable(body, framework, import_provenance, importErrors) && !compileIssue;
                 if (!runnable) {
                     const reason = unresolved_reason ?? compileIssue ?? runnableFailureReason(body, framework, import_provenance, importErrors, declaredDeps);
-                    warnings.push(`Dropped non-runnable v5 generated test for "${gc.ctx.behavior_title}" / "${scenario.title}": ${reason}`);
+                    warnings.push(`Non-runnable v5 generated test for "${gc.ctx.behavior_title}" / "${scenario.title}" kept as an English intent (no run command): ${reason}`);
                     missing.push({
                         external_id: behavior.external_id,
                         title: gc.ctx.behavior_title,
                         reason,
                         needed: ["a compiling generated test with a real assertion and resolvable subject import"]
                     });
+                    // Preserve the grounded INTENT in English, never the rejected code.
+                    // The scenario fields were authored by a model that saw source
+                    // excerpts — scrub the composed body with the same guard as code.
+                    // The scenario plan (title / assertion targets / rationale) is the
+                    // reviewable half of the draft; withholding the body entirely also
+                    // removes any residual source-echo risk. runnable:false + the reason
+                    // keep this honestly a draft — it ships with no run command and can
+                    // never enter the proof-ready set.
+                    const manualBody = sanitizeGeneratedBody([
+                        `Scenario: ${scenario.title}`,
+                        ...(scenario.steps && scenario.steps.length
+                            ? ["Steps:", ...scenario.steps.map((st, n) => `  ${n + 1}. ${st}`)]
+                            : []),
+                        ...(scenario.test_data ? [`Test data: ${scenario.test_data}`] : []),
+                        ...(scenario.assertion_targets.length ? [`Expected: ${scenario.assertion_targets.join("; ")}`] : []),
+                        ...(scenario.rationale ? [`Why this test: ${scenario.rationale}`] : []),
+                        "",
+                        // Concise blocker: first clause only — the full remedy is one line.
+                        `Blocked by: ${reason.split(" — ")[0]}`,
+                        "Fix: install this repo's dependencies / configure the test runner, then re-run \`opro start\`."
+                    ].join("\n"), gc.ctx.source_excerpts, "//").body;
+                    generated.push({
+                        id: `${run_id}-t${generated.length + 1}`,
+                        run_id,
+                        title: `${gc.ctx.behavior_title} — ${scenario.title}`,
+                        test_type: gc.ctx.test_layer,
+                        framework_hint: framework,
+                        body: manualBody,
+                        bucket: bucketForV5Scenario(scenario),
+                        prompt_version: PROMPT_VERSION_V5,
+                        grounding: { entity_ids: gc.entityIds, source_refs: [], weak_relationships_used: [] },
+                        weak_evidence_used: false,
+                        target_symbol_external_id: behavior.external_id,
+                        runnable: false,
+                        unresolved_reason: reason
+                    });
                     continue;
                 }
                 generated.push({

package/dist/local/generate/promptV5.js

@@ -75,7 +75,7 @@ export function buildPlanningSystemPromptV5() {
         "- Return a raw JSON array only. No prose, no markdown fences, no heading, no explanation.",
         "- If no missing scenario is justified, return [] exactly.",
         "- The first character of your response must be [ and the last character must be ].",
-        '[{"id":1,"title":"...","concern":"...","technique":"...","rationale":"...","assertion_targets":["..."],"complexity":"basic|intermediate|advanced","risk_rank":1}]'
+        '[{"id":1,"title":"...","concern":"...","technique":"...","rationale":"...","assertion_targets":["..."],"steps":["Given ...","When ...","Then ..."],"test_data":"concrete example input values (synthetic, showing the edge case)","complexity":"basic|intermediate|advanced","risk_rank":1}]'
     ].join("\n");
 }
 export function buildPlanningUserPromptV5(ctx) {
@@ -303,6 +303,15 @@ function validatePlannedScenario(v) {
     const riskRank = toFinite(v.risk_rank);
     if (riskRank === null)
         return { ok: false, reason: "non-finite risk_rank" };
+    // Optional human-readable fields (tolerant: absent/malformed → omitted, never a rejection).
+    const steps = Array.isArray(v.steps)
+        ? v.steps.filter((x) => typeof x === "string" && x.trim().length > 0).slice(0, 6).map((x) => x.slice(0, 240))
+        : undefined;
+    const test_data = typeof v.test_data === "string" && v.test_data.trim()
+        ? v.test_data.slice(0, 400)
+        : v.test_data && typeof v.test_data === "object"
+            ? JSON.stringify(v.test_data).slice(0, 400)
+            : undefined;
     return {
         ok: true,
         value: {
@@ -312,6 +321,8 @@ function validatePlannedScenario(v) {
             technique: technique,
             rationale: typeof v.rationale === "string" ? v.rationale : "",
             assertion_targets: targets,
+            ...(steps && steps.length ? { steps } : {}),
+            ...(test_data ? { test_data } : {}),
             complexity,
             risk_rank: riskRank
         }

package/dist/local/operations.js

@@ -35,7 +35,7 @@ import { changedImpact } from "./freshness/changed.js";
 import { explainTest } from "./explain/explain.js";
 import { buildVizPayload } from "./viz/payload.js";
 import { renderVizHtml } from "./viz/html.js";
-import { buildBehaviorReportData, dominantBlockReason } from "./viz/behaviorReportData.js";
+import { buildBehaviorReportData, computeReportDelta, reportBaselineOf, dominantBlockReason } from "./viz/behaviorReportData.js";
 import { renderBehaviorReport } from "./viz/behaviorReportHtml.js";
 import { renderCoverageReport } from "./pack/coverageReport.js";
 import { confirmedCoverageByLayer } from "./score/coverage.js";
@@ -804,8 +804,9 @@ export function opDoctor(root) {
  */
 export function opProofDoctor(root) {
     const graph = loadGraph(workspacePaths(root).graphPath);
-    const rtm = buildRtm(graph, loadLedger(root));
-    return buildProofDoctor(graph, rtm, loadProofAttempts(root));
+    const ledger = loadLedger(root);
+    const rtm = buildRtm(graph, ledger);
+    return buildProofDoctor(graph, rtm, loadProofAttempts(root), {}, ledger);
 }
 export function opGaps(root, opts = {}) {
     const graph = loadGraph(workspacePaths(root).graphPath);
@@ -1609,7 +1610,7 @@ export async function opStart(root, opts = {}, deps = defaultDeps()) {
                         limit: batch.length,
                         prompt_version: opts.promptVersion ?? "v5"
                     }, providerDeps);
-                    accepted += generated.generated_tests.length;
+                    accepted += generated.generated_tests.filter((t) => t.runnable !== false).length;
                     warnings.push(...generated.warnings.map((w) => `generate: ${w}`));
                 }
                 if (accepted === 0)
@@ -2000,9 +2001,28 @@ export function opBehaviorCoverageHtml(root, outputPath = "orangepro-behavior-co
     // proof-attempts sidecar ONLY when it anchors to the current graph+commit
     // (stale evidence is dropped — fail closed; display copy only, no tier math).
     const dyn = dynamicProof ?? sidecarDynamicProof(root, graph);
-    const html = renderBehaviorReport(buildBehaviorReportData(graph, loadLedger(root), { repoRoot: root, dynamicProof: dyn }));
+    const data = buildBehaviorReportData(graph, loadLedger(root), { repoRoot: root, dynamicProof: dyn });
+    // Delta-since-last-run: best-effort read of the previous snapshot; a missing
+    // or unreadable baseline means first run (banner hidden). Display-only —
+    // the delta never touches tiers, ranks, or counts.
+    const baselinePath = resolve(root, `${WORKSPACE_DIR}/report-baseline.json`);
+    try {
+        const prev = JSON.parse(readFileSync(baselinePath, "utf8"));
+        if (prev && prev.summary && Array.isArray(prev.riskPaths))
+            data.delta = computeReportDelta(prev, data);
+    }
+    catch {
+        data.delta = null;
+    }
+    const html = renderBehaviorReport(data);
     const htmlPath = resolve(root, outputPath);
     writeFileSync(htmlPath, html, "utf8");
+    try {
+        writeFileSync(baselinePath, JSON.stringify(reportBaselineOf(data, new Date().toISOString())), "utf8");
+    }
+    catch {
+        // baseline write is advisory
+    }
     return { behavior_coverage_path: htmlPath };
 }
 /** Fresh-only sidecar view for report regens; unreadable or stale ⇒ undefined. */

package/dist/local/proofDoctor.js

@@ -77,6 +77,16 @@ export const PROOF_BLOCKER_GUIDE = {
 /** 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.";
+/** Opposite failure mode: the mutant DID make the test fail, but via a runtime
+ *  crash rather than a trusted assertion. The test exercises the target; the
+ *  proof standard (assertion failure) was not met. Misreporting this as
+ *  "mutant survived" sends users to fix the wrong thing. */
+export const NON_ASSERTION_NOTE = "Not proven: the mutant made the test FAIL, but with a runtime error instead of a trusted assertion failure. " +
+    "The test does exercise the target; strengthen the assertion to check the target's returned value directly, or re-run — " +
+    "whether the crash or the assertion is hit first can vary between runs.";
+export function nonKillingNoteFor(mutantStatus) {
+    return mutantStatus === "associated_non_assertion_failure" ? NON_ASSERTION_NOTE : NON_KILLING_NOTE;
+}
 export function proofAttemptsPath(root) {
     return join(workspacePaths(root).dir, PROOF_ATTEMPTS_FILE);
 }
@@ -100,6 +110,7 @@ export function distillProofAttempts(auto, meta) {
             target_symbol: a.target_symbol,
             test_path: a.test_path || undefined,
             classification: a.classification,
+            mutant_status: a.mutant_status,
             category: a.category,
             reason: a.reason ? redactSecrets(a.reason) : undefined,
             deduped: a.deduped,
@@ -246,13 +257,26 @@ function groupBlockers(blocked, source) {
  * 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 = {}) {
+export function buildProofDoctor(graph, rtm, attempts, opts = {}, ledger) {
     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;
+    // Legacy-sidecar backfill: proof-attempts files written before mutant_status
+    // was persisted carry no outcome detail, which forced every non-close into
+    // the "mutant survived" diagnosis. The ledger next to it is ground truth —
+    // recover mutant_status from the latest ledger record per target so the
+    // doctor self-heals without requiring a fresh `opro start`.
+    const ledgerStatusByTarget = new Map();
+    for (const r of ledger?.records ?? []) {
+        const ms = r.dynamic_proof?.mutant_status;
+        if (!ms)
+            continue;
+        ledgerStatusByTarget.set(r.target_symbol, ms); // records are append-ordered; last wins
+    }
+    const mutantStatusFor = (a) => a.mutant_status ?? ledgerStatusByTarget.get(a.target_symbol);
     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");
@@ -268,7 +292,8 @@ export function buildProofDoctor(graph, rtm, attempts, opts = {}) {
         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 });
+        const ms = mutantStatusFor(a);
+        non_killing.push({ target_symbol: a.target_symbol, test_path: a.test_path, mutant_status: ms, note: nonKillingNoteFor(ms) });
     }
     let status;
     let headline;
@@ -291,7 +316,7 @@ export function buildProofDoctor(graph, rtm, attempts, opts = {}) {
     }
     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).`;
+        headline = `0 Dynamically Proven — ${non_killing.length} attempt(s) ran but did not close (see non_killing for the per-target outcome).`;
     }
     else {
         status = "no_data";