@orangepro/orangepro-mcp 0.2.30 → 0.2.31

package/README.md

@@ -199,6 +199,50 @@ Static mapping works across many languages via tree-sitter. Dynamic proof is del
 
 ---
 
+## Highest-value local run
+
+Use the repository's own setup and test commands first, and keep unit and integration
+coverage in separate artifacts. Then run `opro start`; it performs analysis, ingests
+the artifacts, attempts targeted proof, generates report-visible drafts, and writes the
+final report. A separate `opro analyze` is unnecessary when `opro start` follows it.
+
+```bash
+# 1. Install/build exactly as the repository documents.
+# 2. Run the repository's unit and integration coverage commands separately.
+# 3. Record artifact provenance (example paths and commands):
+mkdir -p .orangepro
+# create .orangepro/coverage-suites.json using the schema below
+
+opro coverage .                    # optional preflight: discover/generate artifacts
+opro start . --proof-limit 5 --generate-limit 20
+```
+
+```json
+{
+  "artifacts": {
+    ".orangepro/coverage/unit.coverprofile": {
+      "suite": "unit",
+      "command": "make unit-test-coverage"
+    },
+    ".orangepro/coverage/integration.coverprofile": {
+      "suite": "integration",
+      "command": "make integration-test-coverage"
+    }
+  }
+}
+```
+
+Without this manifest, OrangePro conservatively infers clear `unit`/`integration` names
+and labels everything else `unclassified`; it never guesses that an aggregate profile is
+unit-only. The report shows unit, integration, their overlap, unclassified coverage, and
+the combined union separately. `--proof-limit` controls dynamic proof attempts (which
+may draft a test for proof); `--generate-limit` independently controls the additional
+report-visible risk-gap drafting lane. A generation run
+also records its terminal status and exact reason, so a compiler/import failure is not
+misreported as a generic dependency problem.
+
+---
+
 ## Privacy
 
 - **No stored source.** Reads code in-process. Never uploads to an OrangePro server.
@@ -224,7 +268,7 @@ opro rtm                      # traceability matrix
 opro export                   # metadata-only evidence pack
 opro mcp                      # run as MCP server (stdio)
 opro doctor                   # what evidence to add next
-opro coverage                 # ingest runtime coverage
+opro coverage                 # discover/generate artifacts; analyze or start ingests them
 ```
 
 Add `--json` to any read command for machine output. Run `opro help` for the full reference.

package/dist/local/analyze/coverage.js

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import path from "node:path";
+const COVERAGE_SUITE_MANIFEST = ".orangepro/coverage-suites.json";
 const GO_COVERAGE_CANDIDATES = new Set([
     "coverage.out",
     "cover.out",
@@ -47,6 +48,48 @@ function symbolLanguage(n) {
         return "java";
     return "other";
 }
+function normalizedArtifactPath(value) {
+    const normalized = value.replace(/\\/g, "/").replace(/^\.\//, "");
+    if (!normalized || path.posix.isAbsolute(normalized) || normalized.split("/").includes(".."))
+        return null;
+    return normalized;
+}
+function coverageSuiteManifest(root) {
+    const out = new Map();
+    try {
+        const raw = JSON.parse(readFileSync(path.join(root, COVERAGE_SUITE_MANIFEST), "utf8"));
+        for (const [artifactPath, value] of Object.entries(raw.artifacts ?? {})) {
+            const rel = normalizedArtifactPath(artifactPath);
+            if (!rel || !value || typeof value !== "object")
+                continue;
+            const suite = value.suite;
+            if (suite !== "unit" && suite !== "integration")
+                continue;
+            const command = value.command;
+            out.set(rel, { suite, ...(typeof command === "string" && command.trim() ? { command: command.trim() } : {}) });
+        }
+    }
+    catch {
+        // Missing or malformed provenance is fail-visible as unclassified coverage.
+    }
+    return out;
+}
+function inferredCoverageSuite(rel) {
+    const normalized = `/${rel.toLowerCase().replace(/[^a-z0-9/._-]+/g, "-")}/`;
+    if (/(?:^|[/_.-])(integration|e2e|end-to-end)(?:[/_.-]|$)/.test(normalized))
+        return "integration";
+    if (/(?:^|[/_.-])unit(?:[/_.-]|$)/.test(normalized))
+        return "unit";
+    return null;
+}
+export function coverageSuiteForArtifact(root, rel) {
+    const normalized = normalizedArtifactPath(rel) ?? rel.replace(/\\/g, "/");
+    const declared = coverageSuiteManifest(root).get(normalized);
+    if (declared)
+        return { suite: declared.suite, suite_source: "manifest", ...(declared.command ? { command: declared.command } : {}) };
+    const inferred = inferredCoverageSuite(normalized);
+    return inferred ? { suite: inferred, suite_source: "inferred" } : { suite: "unclassified", suite_source: "unclassified" };
+}
 function artifactCandidates(root, files) {
     const out = new Map();
     const add = (candidate) => {
@@ -79,7 +122,11 @@ function artifactCandidates(root, files) {
     catch {
         /* no generated coverage dir */
     }
-    return [...out.values()].sort((a, b) => a.path.localeCompare(b.path));
+    return [...out.values()]
+        .map((candidate) => {
+        return { ...candidate, ...coverageSuiteForArtifact(root, candidate.path) };
+    })
+        .sort((a, b) => a.path.localeCompare(b.path));
 }
 function discoverNestedCoverageArtifacts(root) {
     const out = [];
@@ -109,7 +156,7 @@ function discoverNestedCoverageArtifacts(root) {
         }
     };
     visit("");
-    return out;
+    return out.map((candidate) => ({ ...candidate, ...coverageSuiteForArtifact(root, candidate.path) }));
 }
 function goModuleForDir(dir, goModulesByDir) {
     for (;;) {
@@ -424,13 +471,14 @@ function parseJacocoXml(root, rel, codeFiles) {
     };
 }
 function parseCoverageArtifact(root, candidate, goModulesByDir, codeFiles) {
-    if (candidate.format === "go-coverprofile")
-        return parseGoCoverprofile(root, candidate.path, goModulesByDir, codeFiles);
-    if (candidate.format === "lcov")
-        return parseLcov(root, candidate.path, codeFiles);
-    if (candidate.format === "coverage-py")
-        return parseCoveragePyXml(root, candidate.path, codeFiles);
-    return parseJacocoXml(root, candidate.path, codeFiles);
+    const parsed = candidate.format === "go-coverprofile"
+        ? parseGoCoverprofile(root, candidate.path, goModulesByDir, codeFiles)
+        : candidate.format === "lcov"
+            ? parseLcov(root, candidate.path, codeFiles)
+            : candidate.format === "coverage-py"
+                ? parseCoveragePyXml(root, candidate.path, codeFiles)
+                : parseJacocoXml(root, candidate.path, codeFiles);
+    return { ...parsed, ranges: parsed.ranges.map((range) => ({ ...range, suite: candidate.suite })) };
 }
 function overlaps(aStart, aEnd, bStart, bEnd) {
     return aStart <= bEnd && bStart <= aEnd;
@@ -451,7 +499,14 @@ export function applyRuntimeCoverage(root, files, nodes, goModulesByDir) {
             skippedArtifacts.push(skipped);
         if (ranges.length === 0)
             continue;
-        const stat = artifactStats.get(artifact.path) ?? { files: new Set(), covered_ranges: 0, format: artifact.format };
+        const stat = artifactStats.get(artifact.path) ?? {
+            files: new Set(),
+            covered_ranges: 0,
+            format: artifact.format,
+            suite: artifact.suite,
+            suite_source: artifact.suite_source,
+            ...(artifact.command ? { command: artifact.command } : {})
+        };
         for (const range of ranges) {
             const list = rangesByFile.get(range.file);
             if (list)
@@ -467,6 +522,9 @@ export function applyRuntimeCoverage(root, files, nodes, goModulesByDir) {
         return undefined;
     const byLanguage = {};
     const coveredSymbols = new Set();
+    const unitSymbols = new Set();
+    const integrationSymbols = new Set();
+    const unclassifiedSymbols = new Set();
     let totalEligible = 0;
     let symbolsWithSpans = 0;
     const ingestedLanguages = new Set([...artifactStats.values()].map((s) => languageForFormat(s.format)));
@@ -491,12 +549,20 @@ export function applyRuntimeCoverage(root, files, nodes, goModulesByDir) {
         if (overlapping.length === 0)
             continue;
         const formats = [...new Set(overlapping.map((r) => r.format))].sort();
+        const suites = [...new Set(overlapping.map((r) => r.suite ?? "unclassified"))].sort();
         coveredSymbols.add(n.external_id);
+        if (suites.includes("unit"))
+            unitSymbols.add(n.external_id);
+        if (suites.includes("integration"))
+            integrationSymbols.add(n.external_id);
+        if (suites.includes("unclassified"))
+            unclassifiedSymbols.add(n.external_id);
         bucket.covered++;
         n.properties = {
             ...n.properties,
             runtime_covered: true,
-            runtime_coverage_formats: formats
+            runtime_coverage_formats: formats,
+            runtime_coverage_suites: suites
         };
     }
     for (const bucket of Object.values(byLanguage))
@@ -505,6 +571,9 @@ export function applyRuntimeCoverage(root, files, nodes, goModulesByDir) {
         artifacts: [...artifactStats.entries()].map(([path, s]) => ({
             path,
             format: s.format,
+            suite: s.suite,
+            suite_source: s.suite_source,
+            ...(s.command ? { command: s.command } : {}),
             files: s.files.size,
             covered_ranges: s.covered_ranges
         })),
@@ -513,6 +582,18 @@ export function applyRuntimeCoverage(root, files, nodes, goModulesByDir) {
         symbols_with_spans: symbolsWithSpans,
         covered_symbols: coveredSymbols.size,
         covered_pct: pct(coveredSymbols.size, totalEligible),
-        by_language: byLanguage
+        by_language: byLanguage,
+        by_suite: {
+            unit: unitSymbols.size,
+            integration: integrationSymbols.size,
+            overlap: [...unitSymbols].filter((id) => integrationSymbols.has(id)).length,
+            unclassified: unclassifiedSymbols.size,
+            union: coveredSymbols.size,
+            unit_pct: pct(unitSymbols.size, totalEligible),
+            integration_pct: pct(integrationSymbols.size, totalEligible),
+            overlap_pct: pct([...unitSymbols].filter((id) => integrationSymbols.has(id)).length, totalEligible),
+            unclassified_pct: pct(unclassifiedSymbols.size, totalEligible),
+            union_pct: pct(coveredSymbols.size, totalEligible)
+        }
     };
 }

package/dist/local/analyze/coverageArtifacts.js

@@ -2,6 +2,7 @@ import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync } from "node:fs";
 import path from "node:path";
 import { reportProgress } from "../util/progress.js";
+import { coverageSuiteForArtifact } from "./coverage.js";
 const DEFAULT_TIMEOUT_MS = 120_000;
 const DEFAULT_BUDGET_MS = 600_000;
 const GENERATED_COVERAGE_DIR = ".orangepro/coverage";
@@ -129,6 +130,10 @@ export function prepareRuntimeCoverage(root, opts = {}) {
             warnings.push("No local coverage generators found, so OrangePro did not generate runtime coverage.");
     }
     const artifacts = detectCoverageArtifacts(absRoot);
+    const unclassified = artifacts.filter((artifact) => artifact.ingestible && artifact.suite === "unclassified");
+    if (unclassified.length > 0) {
+        warnings.push(`${unclassified.length} ingestible coverage artifact(s) have no unit/integration provenance. Add ${COVERAGE_SUITE_MANIFEST_HELP} so OrangePro reports the suites separately.`);
+    }
     const suggested_commands = suggestCoverageCommands(absRoot);
     return {
         root: absRoot,
@@ -139,10 +144,12 @@ export function prepareRuntimeCoverage(root, opts = {}) {
         warnings
     };
 }
+const COVERAGE_SUITE_MANIFEST_HELP = ".orangepro/coverage-suites.json with an artifacts map, for example {\"coverage/unit.coverprofile\":{\"suite\":\"unit\",\"command\":\"make unit-test-coverage\"}}";
 export function detectCoverageArtifacts(root) {
     const absRoot = path.resolve(root);
     const out = new Map();
-    const add = (info) => {
+    const add = (raw) => {
+        const info = { ...raw, ...coverageSuiteForArtifact(absRoot, raw.path) };
         const abs = path.join(absRoot, info.path);
         if (!existsSync(abs))
             return;

package/dist/local/autoProve.js

@@ -18,7 +18,7 @@ import { generateTests, readDeclaredDeps, unresolvedLocalImports } from "./gener
 import { GENERATED_DIR, runHintsFor } from "./generate/runHints.js";
 import { rankRiskGaps } from "./score/risk.js";
 import { resolveProviderConfig } from "./localConfig.js";
-import { buildProvider } from "./generate/providers.js";
+import { buildProvider, DeterministicProvider } from "./generate/providers.js";
 import { resolveContained } from "./reprove/paths.js";
 import { buildRtm } from "./rtm.js";
 import { loadLedger } from "./ledger.js";
@@ -834,10 +834,12 @@ export async function autoProve(root, opts, deps) {
             attempts: ex.attempts
         };
     }
-    // Key gate applies ONLY to the generation lane. No provider key ⇒ generation is skipped
-    // (no files, no fake proof) with explicit guidance; the existing-tests lane still counts.
-    const providerConfig = resolveProviderConfig(deps.env, { provider: opts.provider, model: opts.model });
-    if (!providerConfig) {
+    // Provider gate applies ONLY to the generation lane. Explicit deterministic mode is a
+    // valid offline provider; otherwise a real provider key/config is required.
+    const deterministic = opts.provider === "deterministic"
+        || /^(1|true|yes)$/i.test(String(deps.env.ORANGEPRO_ALLOW_DETERMINISTIC ?? ""));
+    const providerConfig = deterministic ? null : resolveProviderConfig(deps.env, { provider: opts.provider, model: opts.model });
+    if (!providerConfig && !deterministic) {
         const status = ex.proven > 0 ? "proven-run" : ex.attempted > 0 ? "ran-no-proof" : "skipped-no-key";
         return {
             ran: ex.attempted > 0,
@@ -851,7 +853,7 @@ export async function autoProve(root, opts, deps) {
             attempts: ex.attempts
         };
     }
-    const provider = buildProvider(providerConfig);
+    const provider = deterministic ? new DeterministicProvider() : buildProvider(providerConfig);
     const generate = deps.generate ?? generateTests;
     const reader = fileReaderFor(sourceRoot);
     // Generation gets only the budget the existing-tests lane left unspent, so existing +

package/dist/local/cli.js

@@ -78,7 +78,7 @@ const HELP = `opro — OrangePro (local-first, BYOK, metadata-only artifacts)
 
 Usage:
   opro                                       # one-command start: analyze, optional AI links + flows, report, RTM, agent handoff
-  opro start [path] [--base <ref>] [--no-ai] [--no-ai-flows] [--generate-coverage] [--prompt-version v5] [--json]
+  opro start [path] [--base <ref>] [--no-ai] [--no-ai-flows] [--generate-coverage] [--proof-limit 5] [--generate-limit 20] [--prompt-version v5] [--json]
   opro roast [path] [--limit 5] [--json]     # keyless: find passing tests whose targeted mutant still survives
   opro init
   opro setup                                 # interactive: choose a default model provider + model (saved locally)
@@ -199,6 +199,8 @@ async function main() {
                     aiAll: asBool(flags["ai-all"], false),
                     aiFlows: !asBool(flags["no-ai-flows"], false),
                     autoLimit: numericFlag(flags["auto-limit"]),
+                    proofLimit: numericFlag(flags["proof-limit"]),
+                    generateLimit: numericFlag(flags["generate-limit"]),
                     noAuto: asBool(flags["no-auto"], false),
                     promptVersion: flags["prompt-version"] === "v5" ? "v5" : undefined,
                     provider: typeof flags.provider === "string" ? flags.provider : undefined,
@@ -225,6 +227,10 @@ async function main() {
                     out("  Proof next:            no behavior is dynamically proven yet; run from a coding agent with a model key and follow the generated-test proof handoff.");
                 }
                 const ap = res.auto_prove;
+                const gen = res.generation;
+                out(`  Test generation:       ${gen.status} — ${gen.runnable}/${gen.generated} runnable, ${Math.max(0, gen.drafts - gen.runnable)} blocked draft(s)`);
+                if (gen.reason)
+                    out(`    generation reason:   ${gen.reason}`);
                 if (ap.status === "skipped-no-key") {
                     out(`  Dynamic proof:         skipped — ${ap.reason ?? "no provider key"}`);
                 }
@@ -527,7 +533,9 @@ async function main() {
                 if (res.artifacts.length) {
                     out("  found:");
                     for (const a of res.artifacts) {
-                        out(`    ${a.path} (${a.language}, ${a.format}${a.ingestible ? ", ingestible now" : ", detected only"})`);
+                        out(`    ${a.path} (${a.language}, ${a.format}, suite=${a.suite} [${a.suite_source}]${a.ingestible ? ", ingestible now" : ", detected only"})`);
+                        if (a.command)
+                            out(`      command: ${a.command}`);
                     }
                 }
                 else {

package/dist/local/cliArgs.js

@@ -13,6 +13,8 @@
 export const VALUE_FLAGS = new Set([
     "agent-pass",
     "auto-limit",
+    "proof-limit",
+    "generate-limit",
     "base",
     "client",
     "coverage-timeout-ms",

package/dist/local/generate/draftGuidance.js

@@ -0,0 +1,30 @@
+/** Classify only high-confidence generator/validator diagnostics. Ambiguous
+ * failures stay unknown rather than being mislabeled as a repo setup problem. */
+export function classifyGeneratedDraftBlocker(reason) {
+    const text = reason ?? "";
+    if (/timed?\s*out|timeout|ETIMEDOUT|signal:\s*killed/i.test(text))
+        return "validation_timeout";
+    if (/(?:^|\b)(?:go|gofmt|python3|pytest|mvn|gradle|node|npm|vitest|jest|mocha)(?:\b[^.\n]*)?(?:not found|ENOENT|not installed)/i.test(text) ||
+        /(?:test runner|toolchain).*(?:missing|not found|not installed)/i.test(text))
+        return "toolchain_or_runner";
+    if (/no required module provides package|cannot find module|module not found|unresolved import|imports module-path package/i.test(text)) {
+        return "unresolved_import";
+    }
+    if (/syntax check failed|undefined:|unknown field|redeclared in this block|expected (?:declaration|operand|'[^']+'|"[^"]+"|[^ ]+),? found|literal not terminated|cannot assign/i.test(text))
+        return "generated_code";
+    return "unknown";
+}
+export function generatedDraftRemediation(reason) {
+    switch (classifyGeneratedDraftBlocker(reason)) {
+        case "generated_code":
+            return "Regenerate or repair the draft using symbols and APIs that exist in this package; installing dependencies will not fix this compiler error.";
+        case "unresolved_import":
+            return "Verify that the generated import path exists and is already declared by this repo; install dependencies only when the repo expects that import, then regenerate.";
+        case "toolchain_or_runner":
+            return "Install or configure the named toolchain/test runner, then re-run `opro start`.";
+        case "validation_timeout":
+            return "Warm the dependency cache or raise the relevant OrangePro validation timeout, then re-run `opro start`.";
+        default:
+            return "Review the named blocker, repair or regenerate the draft as needed, then re-run `opro start`; do not assume dependencies are missing.";
+    }
+}

package/dist/local/generate/generator.js

@@ -19,6 +19,7 @@ import { languageOf } from "../analyze/classify.js";
 import { buildGroundedUserPrompt, buildRawUserPrompt, buildSystemPrompt, PROMPT_VERSION } from "./prompt.js";
 import { buildBatchGenerationSystemPromptV5, buildBatchGenerationUserPromptV5, buildPlanningRepairSystemPromptV5, buildPlanningRepairUserPromptV5, buildPlanningSystemPromptV5, buildPlanningUserPromptV5, hasRepairableScenarioStructure, parseBatchGeneratedTests, parsePlannedScenariosStrict, scenarioTiesBackToRaw, PROMPT_VERSION_V5 } from "./promptV5.js";
 import { BUCKET_LABEL, deriveBucketSignals, selectLocalBuckets } from "./buckets.js";
+import { generatedDraftRemediation } from "./draftGuidance.js";
 const MAX_LIMIT = 5;
 const DEFAULT_LIMIT = 3;
 const MAX_RELATED_FILES = 4;
@@ -30,6 +31,7 @@ const STATIC_CHECK_TIMEOUT_MS = 3000;
 // before the target package is compiled. Keep the check authoritative instead
 // of downgrading valid generated tests while dependencies are still downloading.
 const GO_COMPILE_CHECK_TIMEOUT_MS = 120000;
+const V5_GENERATION_MAX_TOKENS = 4000;
 /** A source ref that names a test file (used to place a generated test next to it). */
 const TEST_REF_RE = /(\.(test|spec)\.[cm]?[jt]sx?$)|((^|\/)test\.[cm]?[jt]sx?$)|(_test\.[a-z]+$)|(_spec\.[a-z]+$)|((^|\/)test_[^/]+\.[a-z]+$)/i;
 function areaOf(relPath) {
@@ -2382,7 +2384,8 @@ export async function generateTests(graph, opts, provider, fileReader, clock = s
                 reportProgress(`Generating "${gc.ctx.behavior_title}" [v5 batch: ${selected.length}]…`);
                 completions.push(await provider.complete({
                     system: buildBatchGenerationSystemPromptV5(),
-                    user: buildBatchGenerationUserPromptV5({ ...gc.ctx, scenarios: selected })
+                    user: buildBatchGenerationUserPromptV5({ ...gc.ctx, scenarios: selected }),
+                    maxTokens: V5_GENERATION_MAX_TOKENS
                 }));
             }
             catch (e) {
@@ -2392,7 +2395,8 @@ export async function generateTests(graph, opts, provider, fileReader, clock = s
                     try {
                         completions.push(await provider.complete({
                             system: buildBatchGenerationSystemPromptV5(),
-                            user: buildBatchGenerationUserPromptV5({ ...gc.ctx, scenarios: [scenario] })
+                            user: buildBatchGenerationUserPromptV5({ ...gc.ctx, scenarios: [scenario] }),
+                            maxTokens: V5_GENERATION_MAX_TOKENS
                         }));
                     }
                     catch (singleErr) {
@@ -2541,7 +2545,7 @@ export async function generateTests(graph, opts, provider, fileReader, clock = s
                         "",
                         // 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\`."
+                        `Fix: ${generatedDraftRemediation(reason)}`
                     ].join("\n"), gc.ctx.source_excerpts, "//").body;
                     generated.push({
                         id: `${run_id}-t${generated.length + 1}`,

package/dist/local/generate/providers.js

@@ -108,16 +108,17 @@ export class OpenAICompatibleProvider {
                 const data = (await postJson(this.fetchImpl, `${this.cfg.baseUrl}/chat/completions`, { Authorization: `Bearer ${this.cfg.apiKey ?? ""}` }, body, providerTimeoutMs(this.cfg.model)));
                 const choice = data.choices?.[0];
                 const content = choice?.message?.content ?? "";
-                // Reasoning starvation: the model spent the ENTIRE completion budget on
-                // hidden reasoning and returned no visible content (finish_reason
-                // "length"). Long grounded prompts trigger this on gpt-5/o-series at the
-                // 4000-token seed. Retry ONCE with 4x the budget; if it still comes back
-                // empty, return "" and let the caller refuse to emit an empty test.
-                if (!content.trim() && choice?.finish_reason === "length" && !tried.has("starved")) {
-                    tried.add("starved");
+                // A length stop means the completion is truncated even when it contains
+                // visible text. Returning that prefix turns cut-off source into a fake
+                // compiler/setup problem. Retry once with more room, then fail closed.
+                if (choice?.finish_reason === "length" && !tried.has("length-retry")) {
+                    tried.add("length-retry");
                     maxTokens = maxTokens * 4;
                     continue;
                 }
+                if (choice?.finish_reason === "length") {
+                    throw new Error("Model output was truncated at the token limit after one retry; no generated code was accepted.");
+                }
                 return content;
             }
             catch (e) {
@@ -176,14 +177,26 @@ export class AnthropicProvider {
         return this.cfg.model;
     }
     async complete(req) {
-        const data = (await postJson(this.fetchImpl, `${this.cfg.baseUrl}/messages`, { "x-api-key": this.cfg.apiKey ?? "", "anthropic-version": "2023-06-01" }, {
-            model: this.cfg.model,
-            max_tokens: req.maxTokens ?? 900,
-            temperature: req.temperature ?? 0.2,
-            system: req.system,
-            messages: [{ role: "user", content: req.user }]
-        }));
-        return (data.content ?? []).map((c) => c.text ?? "").join("");
+        let maxTokens = req.maxTokens ?? 900;
+        let retriedLength = false;
+        for (;;) {
+            const data = (await postJson(this.fetchImpl, `${this.cfg.baseUrl}/messages`, { "x-api-key": this.cfg.apiKey ?? "", "anthropic-version": "2023-06-01" }, {
+                model: this.cfg.model,
+                max_tokens: maxTokens,
+                temperature: req.temperature ?? 0.2,
+                system: req.system,
+                messages: [{ role: "user", content: req.user }]
+            }, providerTimeoutMs(this.cfg.model)));
+            if (data.stop_reason === "max_tokens" && !retriedLength) {
+                retriedLength = true;
+                maxTokens *= 4;
+                continue;
+            }
+            if (data.stop_reason === "max_tokens") {
+                throw new Error("Model output was truncated at the token limit after one retry; no generated code was accepted.");
+            }
+            return (data.content ?? []).map((c) => c.text ?? "").join("");
+        }
     }
 }
 /**

package/dist/local/operations.js

@@ -21,6 +21,7 @@ import { doctorGraph } from "./score/doctor.js";
 import { findGaps } from "./gaps/gaps.js";
 import { rankRiskGaps } from "./score/risk.js";
 import { generateTests } from "./generate/generator.js";
+import { classifyGeneratedDraftBlocker } from "./generate/draftGuidance.js";
 import { autoProve, NO_KEY_MESSAGE, isEligibleProvableTarget } from "./autoProve.js";
 import { AGENT_RUN_WORKFLOW, GROUNDING_CONTRACT, runnableRunHintsFor } from "./generate/runHints.js";
 import { buildProvider, DeterministicProvider } from "./generate/providers.js";
@@ -1514,10 +1515,13 @@ export async function opStart(root, opts = {}, deps = defaultDeps()) {
     const warnings = [...analyze.warnings];
     reportProgress("start: deterministic graph is ready", { current: 4, total: 8 });
     const staticSnapshot = writeStartStaticSnapshot(root, opts.baseRef, warnings);
-    const providerConfigured = deps.aiProvider !== undefined || resolveProviderConfig(providerEnv, providerOpts) !== null;
+    const aiProviderConfigured = deps.aiProvider !== undefined || resolveProviderConfig(providerEnv, providerOpts) !== null;
+    const resolvedGenerationProvider = deps.aiProvider ?? resolveGenerationProvider(providerEnv, providerOpts);
+    const generationProviderConfigured = resolvedGenerationProvider !== null;
+    const deterministicGeneration = resolvedGenerationProvider?.providerName === "deterministic";
     let aiLinks = { status: "skipped", reason: "AI candidate links disabled for this run." };
     if (opts.ai !== false) {
-        if (!providerConfigured) {
+        if (!aiProviderConfigured) {
             reportProgress("ai: skipped — no local provider key/base URL found", { current: 5, total: 8 });
             aiLinks = {
                 status: "skipped",
@@ -1542,7 +1546,7 @@ export async function opStart(root, opts = {}, deps = defaultDeps()) {
     }
     let aiFlows = { status: "skipped", reason: "AI candidate flows disabled for this run." };
     if (opts.ai !== false && opts.aiFlows !== false) {
-        if (!providerConfigured) {
+        if (!aiProviderConfigured) {
             aiFlows = {
                 status: "skipped",
                 reason: "No model provider configured; set OPENAI_API_KEY, ANTHROPIC_API_KEY, or OLLAMA_BASE_URL to auto-apply AI candidate flows."
@@ -1574,7 +1578,7 @@ export async function opStart(root, opts = {}, deps = defaultDeps()) {
     let autoProveResult;
     try {
         autoProveResult = await autoProve(root, {
-            autoLimit: opts.autoLimit,
+            autoLimit: opts.proofLimit ?? opts.autoLimit,
             noAuto: opts.noAuto,
             provider: providerOpts.provider,
             model: providerOpts.model,
@@ -1599,40 +1603,115 @@ export async function opStart(root, opts = {}, deps = defaultDeps()) {
         };
         warnings.push(`auto-prove skipped: ${reason}`);
     }
-    if (!opts.noAuto && providerConfigured && opts.ai !== false) {
+    const generationLimit = Math.max(0, Math.min(50, Math.floor(opts.generateLimit ?? START_GENERATE_RISK_LIMIT)));
+    let generationResult = {
+        status: "disabled",
+        requested: generationLimit,
+        generated: 0,
+        runnable: 0,
+        drafts: 0,
+        blockers: {},
+        reason: opts.noAuto
+            ? "Test generation was disabled by --no-auto."
+            : opts.ai === false
+                ? "Test generation was disabled by --no-ai."
+                : generationLimit === 0
+                    ? "Test generation budget is 0 (--generate-limit 0)."
+                    : undefined
+    };
+    if (!opts.noAuto && opts.ai !== false && generationLimit > 0 && !generationProviderConfigured) {
+        generationResult = {
+            ...generationResult,
+            status: "no_provider",
+            reason: NO_PROVIDER_MESSAGE
+        };
+        warnings.push(`generate: ${NO_PROVIDER_MESSAGE}`);
+    }
+    else if (!opts.noAuto && generationProviderConfigured && opts.ai !== false && generationLimit > 0) {
         try {
             const graphForGeneration = loadGraph(workspacePaths(root).graphPath);
             const generatedTargets = new Set((graphForGeneration.generated_tests ?? []).map((t) => t.target_symbol_external_id).filter((id) => Boolean(id)));
             const targetIds = rankRiskGaps(graphForGeneration, {
                 repoRoot: root,
-                limit: START_GENERATE_RISK_LIMIT,
+                limit: generationLimit,
                 provenIds: provenSymbolIds(graphForGeneration, loadLedger(root))
             })
                 .map((gap) => gap.id)
                 .filter((id) => !generatedTargets.has(id));
-            if (targetIds.length) {
+            if (!targetIds.length) {
+                generationResult = {
+                    ...generationResult,
+                    status: "no_targets",
+                    reason: "No eligible ungenerated risk targets were found."
+                };
+            }
+            else {
                 reportProgress(`generate: drafting tests for top ${targetIds.length} risk target(s)`, { current: 6, total: 8 });
-                let accepted = 0;
+                const generatedDrafts = [];
                 for (let i = 0; i < targetIds.length; i += START_GENERATE_BATCH_LIMIT) {
                     const batch = targetIds.slice(i, i + START_GENERATE_BATCH_LIMIT);
                     const generated = await opGenerate(root, {
                         ...providerOpts,
                         target_ids: batch,
                         limit: batch.length,
-                        prompt_version: opts.promptVersion ?? "v5"
+                        // The offline deterministic stand-in emits the established v2 scaffold; v5 is
+                        // a two-phase model planning protocol and must not be selected implicitly for it.
+                        prompt_version: opts.promptVersion ?? (deterministicGeneration ? "v2" : "v5")
                     }, providerDeps);
-                    accepted += generated.generated_tests.filter((t) => t.runnable !== false).length;
+                    generatedDrafts.push(...generated.generated_tests);
                     warnings.push(...generated.warnings.map((w) => `generate: ${w}`));
                 }
-                if (accepted === 0)
-                    warnings.push("generate: provider returned no accepted tests for the top risk targets.");
+                const blockers = {};
+                for (const draft of generatedDrafts.filter((test) => test.runnable === false)) {
+                    const blocker = classifyGeneratedDraftBlocker(draft.unresolved_reason);
+                    blockers[blocker] = (blockers[blocker] ?? 0) + 1;
+                }
+                const runnable = generatedDrafts.filter((test) => test.runnable !== false).length;
+                generationResult = {
+                    status: generatedDrafts.length === 0
+                        ? "no_results"
+                        : generatedDrafts.some((test) => test.runnable === false)
+                            ? "completed_with_blockers"
+                            : "completed",
+                    requested: targetIds.length,
+                    generated: generatedDrafts.length,
+                    runnable,
+                    drafts: generatedDrafts.length - runnable,
+                    blockers,
+                    ...(generatedDrafts.length === 0
+                        ? { reason: "The provider returned no generated-test drafts for the selected risk targets." }
+                        : {})
+                };
+                if (generatedDrafts.length === 0)
+                    warnings.push(`generate: ${generationResult.reason}`);
             }
         }
         catch (err) {
-            const reason = err instanceof Error ? err.message : String(err);
+            const reason = redactSecrets(err instanceof Error ? err.message : String(err));
+            generationResult = {
+                ...generationResult,
+                status: "failed",
+                reason
+            };
             warnings.push(`generate skipped: ${reason}`);
         }
     }
+    try {
+        const graphWithGeneration = loadGraph(workspacePaths(root).graphPath);
+        if (!graphWithGeneration.analysis)
+            throw new Error("analysis metadata is missing after analyze");
+        saveGraph(workspacePaths(root).graphPath, {
+            ...graphWithGeneration,
+            updated_at: deps.clock(),
+            analysis: {
+                ...graphWithGeneration.analysis,
+                start_generation: generationResult
+            }
+        });
+    }
+    catch (error) {
+        warnings.push(`generation outcome not persisted: ${error instanceof Error ? error.message : String(error)}`);
+    }
     // G1: persist the distilled, already-redacted attempt classifications so
     // `opro doctor --proof` and standalone report regens can explain blockers
     // after this process exits. Sidecar only — never read by the oracle, RTM,
@@ -1767,6 +1846,7 @@ export async function opStart(root, opts = {}, deps = defaultDeps()) {
         changed,
         gaps,
         auto_prove: autoProveResult,
+        generation: generationResult,
         next_actions: nextActions,
         agent_workflow: AGENT_RUN_WORKFLOW,
         grounding_contract: GROUNDING_CONTRACT,

package/dist/local/pack/coverageReport.js

@@ -74,12 +74,22 @@ export function renderCoverageReport(graph, ledger = emptyLedger()) {
             lines.push(`| ${language} | ${row.covered} / ${row.eligible} | ${row.covered_pct}% | ${row.symbols_with_spans} |`);
         }
         lines.push("");
+        lines.push("Coverage by test suite (inclusive counts; unit + integration must not be added because overlap is reported separately):");
+        lines.push("");
+        lines.push("| suite | covered symbols | eligible % |");
+        lines.push("| --- | ---: | ---: |");
+        lines.push(`| unit | ${runtime.by_suite.unit} | ${runtime.by_suite.unit_pct}% |`);
+        lines.push(`| integration | ${runtime.by_suite.integration} | ${runtime.by_suite.integration_pct}% |`);
+        lines.push(`| unit + integration overlap | ${runtime.by_suite.overlap} | ${runtime.by_suite.overlap_pct}% |`);
+        lines.push(`| unclassified | ${runtime.by_suite.unclassified} | ${runtime.by_suite.unclassified_pct}% |`);
+        lines.push(`| combined union | ${runtime.by_suite.union} | ${runtime.by_suite.union_pct}% |`);
+        lines.push("");
         lines.push("Artifacts:");
         lines.push("");
-        lines.push("| artifact | format | files | covered ranges |");
-        lines.push("| --- | --- | ---: | ---: |");
+        lines.push("| artifact | suite | provenance | command | format | files | covered ranges |");
+        lines.push("| --- | --- | --- | --- | --- | ---: | ---: |");
         for (const artifact of runtime.artifacts) {
-            lines.push(`| ${escapeMd(artifact.path)} | ${artifact.format} | ${artifact.files} | ${artifact.covered_ranges} |`);
+            lines.push(`| ${escapeMd(artifact.path)} | ${artifact.suite} | ${artifact.suite_source} | ${escapeMd(artifact.command ?? "-")} | ${artifact.format} | ${artifact.files} | ${artifact.covered_ranges} |`);
         }
         lines.push("");
         if (runtime.skipped_artifacts?.length) {

package/dist/local/viz/behaviorReportData.js

@@ -4,6 +4,7 @@ import { buildRtm } from "../rtm.js";
 import { inspectRiskInputHealth, isEntryPoint, rankRiskGaps } from "../score/risk.js";
 import { ORANGEPRO_VERSION } from "../version.js";
 import { PROOF_BLOCKER_GUIDE } from "../proofDoctor.js";
+import { classifyGeneratedDraftBlocker } from "../generate/draftGuidance.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",
@@ -229,6 +230,7 @@ function scanBlock(graph, rows) {
     const integration = tests.filter((n) => n.properties.test_layer === "integration" || n.properties.test_layer === "api" || n.properties.test_layer === "e2e").length;
     const unit = tests.filter((n) => n.properties.test_layer === "unit" || n.properties.test_layer === "component").length;
     const denominator = graph.analysis?.denominator;
+    const runtime = graph.analysis?.runtime_coverage;
     const excludedCount = (denominator?.excluded_boilerplate ?? 0) +
         (denominator?.excluded_infra ?? 0) +
         (denominator?.excluded_generated ?? 0) +
@@ -236,7 +238,22 @@ function scanBlock(graph, rows) {
     return {
         services: [...services.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, 50),
         serviceTotal: services.size,
-        tests: { total: tests.length, integration, unit },
+        tests: { total: tests.length, integration, unit, unclassified: Math.max(0, tests.length - integration - unit) },
+        runtimeCoverage: runtime
+            ? {
+                eligible: runtime.total_eligible_symbols,
+                unit: runtime.by_suite?.unit ?? 0,
+                integration: runtime.by_suite?.integration ?? 0,
+                overlap: runtime.by_suite?.overlap ?? 0,
+                unclassified: runtime.by_suite?.unclassified ?? runtime.covered_symbols,
+                union: runtime.by_suite?.union ?? runtime.covered_symbols,
+                unitPct: runtime.by_suite?.unit_pct ?? 0,
+                integrationPct: runtime.by_suite?.integration_pct ?? 0,
+                overlapPct: runtime.by_suite?.overlap_pct ?? 0,
+                unclassifiedPct: runtime.by_suite?.unclassified_pct ?? runtime.covered_pct,
+                unionPct: runtime.by_suite?.union_pct ?? runtime.covered_pct
+            }
+            : null,
         excluded: {
             count: excludedCount > 0 ? String(excludedCount) : "0",
             text: "non-behavior symbols were excluded from the behavior count — generated code, framework internals, test-inferred flows, and infrastructure plumbing."
@@ -415,7 +432,8 @@ function riskGeneratedTests(graph, gap, riskIds, isFirstRowForFile) {
             .filter(Boolean)
             .join(" · "),
         code: t.body,
-        runnable: t.runnable !== false
+        runnable: t.runnable !== false,
+        ...(t.runnable === false ? { blocker: classifyGeneratedDraftBlocker(t.unresolved_reason) } : {})
     }));
 }
 /** Incoming refs are method-attributed and can be fractional when a file-level
@@ -758,7 +776,23 @@ function riskTodo(risk, verb, path, generatedTests) {
         return "Run the generated test below in your repo; follow its prove handoff so a mutation failure can mint Dynamically Proven.";
     }
     if (generatedTests.length) {
-        return "Install this repo's dependencies / set up the test runner, then re-run `opro start` to turn the English intents below into runnable tests.";
+        const blockers = new Set(generatedTests.map((t) => t.blocker ?? "unknown"));
+        if (blockers.size === 1) {
+            const blocker = [...blockers][0];
+            if (blocker === "generated_code") {
+                return "OrangePro withheld the generated code because compile validation found invalid or invented generated code. Review the blocker below, then regenerate or repair the draft; installing dependencies is not the fix.";
+            }
+            if (blocker === "unresolved_import") {
+                return "OrangePro withheld the generated code because an import path did not resolve. Verify that the import exists and is declared by this repo; install dependencies only when the repo expects it, then regenerate.";
+            }
+            if (blocker === "toolchain_or_runner") {
+                return "OrangePro could not validate the generated test because the named toolchain or test runner is unavailable. Install/configure it, then re-run `opro start`.";
+            }
+            if (blocker === "validation_timeout") {
+                return "OrangePro's generated-test validation timed out. Warm the dependency cache or raise the named validation timeout, then re-run `opro start`.";
+            }
+        }
+        return "OrangePro withheld generated code for the reasons shown below. Review each blocker, then repair or regenerate the drafts; do not assume repository dependencies are missing.";
     }
     const call = verb !== "BEHAVIOR"
         ? `issues ${verb} ${path}`
@@ -908,6 +942,9 @@ export function buildBehaviorReportData(graph, ledger, opts = {}) {
             }
         },
         generatedTotal: graph.generated_tests?.length ?? 0,
+        generatedRunnableTotal: (graph.generated_tests ?? []).filter((t) => t.runnable !== false).length,
+        generatedDraftTotal: (graph.generated_tests ?? []).filter((t) => t.runnable === false).length,
+        generationOutcome: graph.analysis?.start_generation ?? null,
         shownCount: risks.reduce((acc, r) => acc + r.generatedTests.length, 0)
     };
 }

package/dist/local/viz/behaviorReportHtml.js

@@ -366,9 +366,26 @@ body[data-mode="expert"] .simple-only{display:none!important}
       <div class="split2">
         <div><div class="v vb" id="test-int">—</div><div class="k">Integration</div></div>
         <div><div class="v vp" id="test-unit">—</div><div class="k">Unit</div></div>
+        <div><div class="v" id="test-unknown">—</div><div class="k">Unclassified</div></div>
       </div>
     </div>
   </div>
+  <div class="card" id="runtime-suite-card" hidden style="margin-top:16px">
+    <p class="card-lbl">Runtime coverage by suite — inclusive symbol counts; unit + integration overlap is shown separately and must not be added.</p>
+    <div class="split2">
+      <div><div class="v vp" id="runtime-unit">—</div><div class="k">Unit</div></div>
+      <div><div class="v vb" id="runtime-integration">—</div><div class="k">Integration</div></div>
+      <div><div class="v" id="runtime-overlap">—</div><div class="k">Both</div></div>
+      <div><div class="v" id="runtime-unclassified">—</div><div class="k">Unclassified</div></div>
+      <div><div class="v vg" id="runtime-union">—</div><div class="k">Combined union</div></div>
+    </div>
+  </div>
+  <div class="card" id="generation-outcome-card" hidden style="margin-top:16px">
+    <p class="card-lbl">Latest automated test-generation run</p>
+    <div class="v" id="generation-outcome-status">—</div>
+    <p class="card-sub" id="generation-outcome-counts"></p>
+    <p class="card-sub" id="generation-outcome-reason"></p>
+  </div>
 </section>
 
 <!-- TAB 2: BEHAVIORS — bridge from "methods" to "behaviors" -->
@@ -697,6 +714,23 @@ D.scan.services.forEach(([nm,ct])=>$("#svc-list").append(el("div","svc",\`<span
 $("#test-total").textContent=D.scan.tests.total;
 $("#test-int").textContent=D.scan.tests.integration;
 $("#test-unit").textContent=D.scan.tests.unit;
+$("#test-unknown").textContent=D.scan.tests.unclassified;
+if(D.scan.runtimeCoverage){
+  const R=D.scan.runtimeCoverage;
+  $("#runtime-suite-card").hidden=false;
+  $("#runtime-unit").textContent=\`\${R.unit} (\${R.unitPct}%)\`;
+  $("#runtime-integration").textContent=\`\${R.integration} (\${R.integrationPct}%)\`;
+  $("#runtime-overlap").textContent=\`\${R.overlap} (\${R.overlapPct}%)\`;
+  $("#runtime-unclassified").textContent=\`\${R.unclassified} (\${R.unclassifiedPct}%)\`;
+  $("#runtime-union").textContent=\`\${R.union} (\${R.unionPct}%)\`;
+}
+if(D.generationOutcome){
+  const G=D.generationOutcome;
+  $("#generation-outcome-card").hidden=false;
+  $("#generation-outcome-status").textContent=String(G.status||"unknown").replaceAll("_"," ");
+  $("#generation-outcome-counts").textContent=G.generated+" draft(s): "+G.runnable+" runnable, "+Math.max(0,G.drafts-G.runnable)+" blocked; "+G.requested+" target(s) requested.";
+  $("#generation-outcome-reason").textContent=G.reason||"Generation completed; inspect each draft for its terminal validation result.";
+}
 
 // behaviors
 function humanizeSig(sig){
@@ -883,6 +917,10 @@ const riskTopBanner=el("div","platform-top-banner",
    <a class="platform-footer-btn" href="https://orangepro.ai/get-started" target="_blank">Unlock Full Analysis &rarr;</a>\`);
 riskList.before(riskTopBanner);
 const generatedRiskCount=D.risks.filter(r=>r.generatedTests&&r.generatedTests.length).length;
+const generatedOutputCopy=[
+  D.generatedRunnableTotal?\`\${D.generatedRunnableTotal} runnable generated test\${D.generatedRunnableTotal===1?"":"s"}\`:'',
+  D.generatedDraftTotal?\`\${D.generatedDraftTotal} grounded draft\${D.generatedDraftTotal===1?"":"s"} with code withheld\`:'',
+].filter(Boolean).join(' and ');
 let activeRiskFilter=generatedRiskCount?"generated":"all";
 function riskMatchesFilter(r){
   const hasGenerated=Boolean(r.generatedTests&&r.generatedTests.length);
@@ -893,7 +931,7 @@ function riskMatchesFilter(r){
 function renderRiskFilters(){
   const options=[
     ["all","All",D.risks.length],
-    ["generated","Flows with tests",generatedRiskCount],
+    ["generated","Flows with generated output",generatedRiskCount],
     ["missing","No generated tests",D.risks.filter(r=>!(r.generatedTests&&r.generatedTests.length)).length]
   ];
   riskTools.innerHTML=options.map(([key,label,count])=>\`<button class="risk-filter" type="button" data-risk-filter="\${key}" aria-pressed="\${key===activeRiskFilter}">\${label} <span class="gc">\${count}</span></button>\`).join("");
@@ -922,7 +960,7 @@ function riskCardHtml(r){
     // per-test chips whenever the generator produced unit tests.
     const allIntent=r.generatedTests.every(t=>t.runnable===false);
     const kinds=[...new Set(r.generatedTests.map(t=>t.concern).filter(Boolean))];
-    const kindLbl=allIntent?" (Manual tests — env setup needed)":kinds.length===1?" ("+kinds[0].replace(/_/g," ")+")":kinds.length>1?" (mixed)":"";
+    const kindLbl=allIntent?" (Generated drafts — code withheld)":kinds.length===1?" ("+kinds[0].replace(/_/g," ")+")":kinds.length>1?" (mixed)":"";
     testsHtml=\`<div class="gen-tests"><div class="gen-tests-lbl">Generated tests\${esc(kindLbl)}</div>\`;
     r.generatedTests.forEach(t=>{
       const cBadge=t.concern?\`<span class="badge b-info" style="margin-left:6px;font-size:9px">\${esc(t.concern.replace('_',' '))}</span>\`:'';
@@ -946,12 +984,12 @@ function renderRisks(){
     const remainingRiskFlows=Math.max(0,D.risks.length-generatedRiskCount);
     riskList.append(el("div","paywall",
       hiddenGeneratedFlows
-        ? \`<div class="paywall-num">\${hiddenGeneratedFlows} more flows with tests</div>
-           <div class="paywall-txt">OrangePro accepted \${D.generatedTotal} runnable generated test\${D.generatedTotal===1?"":"s"} across \${generatedRiskCount} high-risk flow\${generatedRiskCount===1?"":"s"}. Use the “Flows with tests” filter to review them first.</div>
+        ? \`<div class="paywall-num">\${hiddenGeneratedFlows} more flows with generated output</div>
+           <div class="paywall-txt">OrangePro produced \${generatedOutputCopy} across \${generatedRiskCount} high-risk flow\${generatedRiskCount===1?"":"s"}. Use the “Flows with generated output” filter to review them first.</div>
            <a class="paywall-btn" href="https://orangepro.ai/get-started" target="_blank">View all on OrangePro Platform &rarr;</a>\`
         : remainingRiskFlows
           ? \`<div class="paywall-num">\${remainingRiskFlows} high-risk flows left</div>
-             <div class="paywall-txt">The local MCP accepted \${D.generatedTotal} runnable generated test\${D.generatedTotal===1?"":"s"} across \${generatedRiskCount} high-risk flow\${generatedRiskCount===1?"":"s"}. Generate the remaining high-risk flow tests on OrangePro Platform.</div>
+             <div class="paywall-txt">The local MCP produced \${generatedOutputCopy} across \${generatedRiskCount} high-risk flow\${generatedRiskCount===1?"":"s"}. Generate the remaining high-risk flow tests on OrangePro Platform.</div>
              <a class="paywall-btn" href="https://orangepro.ai/get-started" target="_blank">Generate remaining tests on Platform &rarr;</a>\`
           : \`<div class="paywall-num">All generated tests are shown</div>
              <div class="paywall-txt">OrangePro generated tests for every high-risk flow in this report, and every generated test is visible here.</div>\`));

package/docs/local-proof-kit.md

@@ -264,6 +264,14 @@ local kit ingests Go coverprofiles, JS/TS `lcov.info`, Python coverage.py XML, a
 XML. These artifacts show executed lines inside symbols; they are not assertion-level proof and
 never promote Associated signal or No integration signal rows to Proven.
 
+For the highest-signal report in a repository with its own build/test workflow, bootstrap the
+repository first, run its native coverage target, optionally use `opro coverage .` to confirm the
+artifact is detected, and then run `opro start .`. The `coverage` command is discovery/generation
+only; `analyze` and `start` ingest detected artifacts while rebuilding the graph. Running
+`opro analyze .` immediately before `opro start .` is redundant. `opro start . --generate-coverage`
+is a convenience for conventional repositories; prefer the repository's native coverage command
+when it needs custom build tags, generated assets, services, or test-runner flags.
+
 ## Readiness score
 
 A 0–100 **readiness** signal (not a proof of lift), in bands: `thin` (0–39),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orangepro/orangepro-mcp",
-  "version": "0.2.30",
+  "version": "0.2.31",
   "private": false,
   "description": "OrangePro (`opro`) — a local-first, BYOK CLI + MCP server that builds an evidence graph from a local checkout, ingests runtime coverage, and generates grounded tests. Metadata-only exports; no source upload; generated tests stay local.",
   "license": "MIT",