@orangepro/orangepro-mcp 0.1.0

package/dist/local/operations.js

@@ -0,0 +1,1749 @@
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { LOCAL_GRAPH_SCHEMA_VERSION } from "./graph/ontology.js";
+import { systemClock } from "./util/time.js";
+import { redactSecrets } from "./util/redact.js";
+import { isPathIgnored, loadIgnore, walkFiles } from "./util/walk.js";
+import { WORKSPACE_DIR, deriveWorkspaceName, graphExists, initWorkspace, loadConfig, saveConfig, loadGraph, saveGraph, workspaceInitialized, workspacePaths } from "./workspace.js";
+import { loadProviderEnv, resolveProviderConfig } from "./localConfig.js";
+import { behaviorNodes, denominatorComposition } from "./graph/factories.js";
+import { summarizeTestEvidence } from "./graph/citations.js";
+import { analyzeRepo } from "./analyze/analyzer.js";
+import { ParseCache } from "./analyze/parseCache.js";
+import { ResolverCache } from "./resolve/resolverCache.js";
+import { manifestKindOf, roleOf } from "./analyze/classify.js";
+import { enrichFromContent } from "./enrich/index.js";
+import { scoreGraph } from "./score/score.js";
+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 { 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";
+import { buildOracle, scoreArm, armMetrics } from "./generate/compareScore.js";
+import { judgeComparison, buildJudgeContext } from "./generate/compareJudge.js";
+import { renderCompareReportMarkdown, renderArmTestsFile, renderArmTestsJson, testsFileExt, testsArtifactName, compareTestsFramework } from "./generate/compareReport.js";
+import { buildPack } from "./pack/exporter.js";
+import { packToMarkdown } from "./pack/summary.js";
+import { validatePack } from "./pack/validate.js";
+import { buildManifest, readGitInfo } from "./freshness/manifest.js";
+import { computeFreshness } from "./freshness/status.js";
+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 { renderBehaviorReport } from "./viz/behaviorReportHtml.js";
+import { renderCoverageReport } from "./pack/coverageReport.js";
+import { confirmedCoverageByLayer } from "./score/coverage.js";
+import { prepareRuntimeCoverage } from "./analyze/coverageArtifacts.js";
+import { appendLedgerRecord, canReproveLanguage, loadLedger, ledgerStats, proofEdgesFor, reproveTarget, resolveTargetSymbol, targetFingerprint, targetLanguage } from "./ledger.js";
+import { buildRtm, renderRtmCsv, renderRtmMarkdown } from "./rtm.js";
+import { tryScopedReprove } from "./reprove/scoped.js";
+import { resolveContained, toWorkspaceRel } from "./reprove/paths.js";
+import { hashBuffer } from "./util/hash.js";
+import { applyAiLinks, generateAiLinks, summarizeAiLinks } from "./aiGraph/links.js";
+import { applyAiFlows, generateAiFlows, isValidStoredCandidateFlowMeta, revalidateCandidateFlowMeta } from "./flows/llmFlowDiscovery.js";
+import { summarizeCorpusScope } from "./corpusScope.js";
+import { reportProgress } from "./util/progress.js";
+function defaultDeps() {
+    return { clock: systemClock, env: process.env };
+}
+function dynamicProofSpikePath() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    return resolve(here, "..", "..", "scripts", "spikes", "dynamic-proof-spike.mjs");
+}
+function defaultDynamicProofRunner(args, opts = {}) {
+    const script = dynamicProofSpikePath();
+    if (!existsSync(script)) {
+        throw new Error(`Dynamic proof spike runner not found at ${script}. Run this command from an OrangePro source checkout with scripts/spikes available.`);
+    }
+    const child = spawnSync(process.execPath, [script, ...args], {
+        cwd: opts.cwd,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"]
+    });
+    if (child.error)
+        throw child.error;
+    return {
+        stdout: child.stdout ?? "",
+        stderr: child.stderr ?? "",
+        exitCode: child.status ?? 1
+    };
+}
+function parseDynamicProofJson(stdout, stderr) {
+    try {
+        return JSON.parse(stdout);
+    }
+    catch (err) {
+        const detail = redactSecrets((stderr || stdout).slice(0, 2000));
+        throw new Error(`Dynamic proof runner did not return JSON.${detail ? ` stderr/stdout: ${detail}` : ""}`);
+    }
+}
+function dynamicProofSucceeded(oracle) {
+    return (oracle.status === "proven" &&
+        oracle.proven === true &&
+        oracle.baseline?.exitCode === 0 &&
+        oracle.baseline?.timedOut !== true &&
+        oracle.mutant?.exitCode !== 0 &&
+        oracle.mutant?.assertionFailure === true &&
+        oracle.mutant?.timedOut !== true);
+}
+function symbolTargetParts(symExtId) {
+    const match = /^sym:(.+)#([^#]+)$/.exec(symExtId);
+    if (!match) {
+        throw new Error(`Cannot derive dynamic proof target from symbol id: ${symExtId}`);
+    }
+    const [, file, symbolName] = match;
+    const method = symbolName.split(".").filter(Boolean).pop();
+    if (!file || !method) {
+        throw new Error(`Cannot derive dynamic proof target from symbol id: ${symExtId}`);
+    }
+    return { file, method };
+}
+function assertProofTargetMatchesSymbol(opts, symbolTarget) {
+    if (opts.target_path !== undefined && opts.target_path !== "") {
+        const provided = opts.target_path.split(/[\\/]+/).join("/");
+        if (provided !== symbolTarget.file) {
+            throw new Error(`prove target mismatch: --target-file ${provided} does not match resolved symbol file ${symbolTarget.file}. Dynamic proof certificates must mutate the credited symbol.`);
+        }
+    }
+    if (opts.method !== undefined && opts.method !== "" && opts.method !== symbolTarget.method) {
+        throw new Error(`prove target mismatch: --method ${opts.method} does not match resolved symbol member ${symbolTarget.method}. Dynamic proof certificates must mutate the credited symbol.`);
+    }
+}
+function assertProofSourceMatchesGraph(sourceRoot, graph) {
+    const graphRoot = resolve(graph.workspace.root);
+    if (sourceRoot !== graphRoot) {
+        throw new Error(`prove source mismatch: --source ${sourceRoot} does not match the analyzed graph root ${graphRoot}. Run OrangePro analyze/prove against the same checkout before minting public Proven.`);
+    }
+}
+/**
+ * Refuse to prove against a target file that changed since analyze: the cert's
+ * target_fingerprint is derived from the analyzed graph manifest hash, so proving
+ * against different current bytes would credit a proof of the CURRENT source to a
+ * STALE graph revision and RTM would show Proven for code the graph never indexed.
+ * No manifest entry → the fingerprint is undefined and RTM never counts it.
+ */
+function assertTargetFileFresh(sourceRoot, targetRel, graph) {
+    const analyzedHash = graph.manifest.files[targetRel]?.hash;
+    if (analyzedHash === undefined)
+        return;
+    const targetAbs = resolveContained(sourceRoot, targetRel);
+    if (existsSync(targetAbs) && hashBuffer(readFileSync(targetAbs)) !== analyzedHash) {
+        throw new Error(`prove: target file ${targetRel} changed since analyze; rerun \`opro analyze\` before proving so the proof binds to the current code.`);
+    }
+}
+/** Parse a positive-int env override; undefined falls back to the analyzer default. */
+function positiveIntEnv(raw) {
+    if (!raw)
+        return undefined;
+    const n = Number.parseInt(raw, 10);
+    return Number.isFinite(n) && n > 0 ? n : undefined;
+}
+/** Read the configurable inferred-flow cap (ORANGEPRO_MAX_FLOWS) from the env. */
+function maxFlowsFromEnv(env) {
+    return positiveIntEnv(env.ORANGEPRO_MAX_FLOWS);
+}
+/** Read the configurable file-scan cap (ORANGEPRO_MAX_FILES) from the env. */
+function maxFilesFromEnv(env) {
+    return positiveIntEnv(env.ORANGEPRO_MAX_FILES);
+}
+/** Read the configurable symbol-extraction cap (ORANGEPRO_MAX_SYMBOLS) from the env. */
+function maxSymbolsFromEnv(env) {
+    return positiveIntEnv(env.ORANGEPRO_MAX_SYMBOLS);
+}
+/** Read the configurable per-file-scan wall-clock budget (ORANGEPRO_MAX_ANALYZE_MS) from the env. */
+function maxAnalyzeMsFromEnv(env) {
+    return positiveIntEnv(env.ORANGEPRO_MAX_ANALYZE_MS);
+}
+/** Path of the persistent parse cache (next to the workspace graph). */
+function parseCachePath(graphPath) {
+    return join(dirname(graphPath), "parse-cache.json");
+}
+/** Load the persistent parse cache; a missing/garbage/old-version file starts empty (never trusted). */
+function loadParseCache(graphPath) {
+    try {
+        const raw = readFileSync(parseCachePath(graphPath), "utf8");
+        return new ParseCache(JSON.parse(raw));
+    }
+    catch {
+        return new ParseCache(null);
+    }
+}
+/** Path of the persistent resolver cache (next to the workspace graph). */
+function resolverCachePath(graphPath) {
+    return join(dirname(graphPath), "resolver-cache.json");
+}
+/** Load the persistent resolver cache; a missing/garbage file starts empty (the gate re-validates). */
+function loadResolverCache(graphPath) {
+    try {
+        const raw = readFileSync(resolverCachePath(graphPath), "utf8");
+        return new ResolverCache(JSON.parse(raw));
+    }
+    catch {
+        return new ResolverCache(null);
+    }
+}
+// ── helpers ──────────────────────────────────────────────────────────
+/** Write atomically (temp + rename) so a concurrent poller never reads a half file. */
+function writeFileAtomic(path, data) {
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, data, "utf8");
+    renameSync(tmp, path);
+}
+function gitRunner(root) {
+    return (args) => {
+        try {
+            return execFileSync("git", args, { cwd: root, stdio: ["ignore", "pipe", "ignore"] }).toString();
+        }
+        catch {
+            return null;
+        }
+    };
+}
+/** Injection-safe `gh` runner (array args, never a shell string); null on failure. */
+function ghRunner(root) {
+    return (args) => {
+        try {
+            return execFileSync("gh", args, { cwd: root, stdio: ["ignore", "pipe", "ignore"] }).toString();
+        }
+        catch {
+            return null;
+        }
+    };
+}
+function fileReaderFor(root) {
+    const absRoot = resolve(root);
+    return (relPath) => {
+        const abs = resolve(absRoot, relPath);
+        // Guard against traversal AND sibling-prefix escapes (e.g. /root vs /root-evil).
+        if (abs !== absRoot && !abs.startsWith(absRoot + sep))
+            return null;
+        try {
+            return readFileSync(abs, "utf8");
+        }
+        catch {
+            return null;
+        }
+    };
+}
+/** Lightweight content-hash scan (no node building) for freshness checks. */
+function scanFileEntries(root) {
+    const ignore = loadIgnore(root);
+    const files = walkFiles(root, ignore);
+    const entries = {};
+    for (const f of files) {
+        entries[f.relPath] = { hash: f.hash, size: f.size, kind: manifestKindOf(f.relPath) };
+    }
+    return entries;
+}
+function dedupeNodesByExternalId(nodes) {
+    const seen = new Map();
+    for (const n of nodes) {
+        const prev = seen.get(n.external_id);
+        if (!prev || n.confidence > prev.confidence)
+            seen.set(n.external_id, n);
+    }
+    return [...seen.values()];
+}
+function dedupeById(items) {
+    const seen = new Map();
+    for (const it of items)
+        if (!seen.has(it.id))
+            seen.set(it.id, it);
+    return [...seen.values()];
+}
+/** Drop edges whose endpoints are not present — enforces "no dangling edges". */
+function pruneDanglingEdges(nodes, edges) {
+    const ids = new Set(nodes.map((n) => n.external_id));
+    return edges.filter((e) => ids.has(e.from_external_id) && ids.has(e.to_external_id));
+}
+/** Discover optional enricher inputs (templates/docs) without LLM. */
+function collectEnricherFragments(root, extraPaths, includeMarkdown) {
+    const fragments = [];
+    const reader = fileReaderFor(root);
+    const seen = new Set();
+    const tryFile = (relPath) => {
+        if (seen.has(relPath))
+            return;
+        seen.add(relPath);
+        const content = reader(relPath);
+        if (!content)
+            return;
+        const frag = enrichFromContent(relPath, content);
+        if (frag)
+            fragments.push(frag);
+    };
+    for (const p of extraPaths)
+        tryFile(p);
+    const ignore = loadIgnore(root);
+    for (const f of walkFiles(root, ignore)) {
+        const lower = f.relPath.toLowerCase();
+        if (lower.endsWith(".csv"))
+            tryFile(f.relPath);
+        else if (includeMarkdown &&
+            /\.(md|mdx|markdown)$/.test(lower) &&
+            /(requirement|template|acceptance|stories|prd|spec|intake)/.test(lower)) {
+            tryFile(f.relPath);
+        }
+    }
+    return fragments.filter(Boolean);
+}
+function buildGraphFromFragments(workspaceRoot, scanRoot, analyzeFragment, enrichFragments, now) {
+    const paths = workspacePaths(workspaceRoot);
+    const config = loadConfig(paths);
+    const repoSource = analyzeFragment.sources[0];
+    const nodes = dedupeNodesByExternalId([
+        ...analyzeFragment.nodes,
+        ...enrichFragments.flatMap((f) => f.nodes)
+    ]);
+    const edges = dedupeById([...analyzeFragment.edges, ...enrichFragments.flatMap((f) => f.edges)]);
+    const candidate_edges = dedupeById([
+        ...analyzeFragment.candidate_edges,
+        ...enrichFragments.flatMap((f) => f.candidate_edges)
+    ]);
+    const sources = [...analyzeFragment.sources, ...enrichFragments.flatMap((f) => f.sources)];
+    const manifest = buildManifest(analyzeFragment.file_entries, readGitInfo(gitRunner(scanRoot)), now);
+    const prunedEdges = pruneDanglingEdges(nodes, edges);
+    return {
+        schema_version: LOCAL_GRAPH_SCHEMA_VERSION,
+        workspace: {
+            name: config.workspace_name || deriveWorkspaceName(scanRoot),
+            root: resolve(scanRoot),
+            root_hash: repoSource?.content_hash ?? "sha256:",
+            source_upload_policy: "metadata_only"
+        },
+        created_at: now,
+        updated_at: now,
+        sources,
+        nodes,
+        edges: prunedEdges,
+        candidate_edges: pruneDanglingEdges(nodes, candidate_edges),
+        generation_runs: [],
+        generated_tests: [],
+        manifest,
+        // Composition AND confirmed-by-layer are computed over the MERGED node set
+        // (analyzer + enrichers) and the pruned edges, so template/markdown
+        // requirements land in the denominator and the confirmed metric agrees with it.
+        analysis: {
+            ...analyzeFragment.analysis,
+            denominator: denominatorComposition({ nodes }),
+            confirmed_by_layer: confirmedCoverageByLayer({ nodes, edges: prunedEdges })
+        }
+    };
+}
+// ── operations ───────────────────────────────────────────────────────
+export function opInit(root, deps = defaultDeps()) {
+    const { paths } = initWorkspace(root, deps.clock());
+    return { graph_path: paths.graphPath, config_path: paths.configPath };
+}
+/**
+ * Carry an applied AI candidate-flow lane across a re-analysis. The stored lane
+ * is untrusted input: a missing/corrupt old graph or a malformed/invariant-
+ * violating lane is dropped (never throws), and re-validation touches ONLY
+ * analysis.candidate_flows — never edges, tiers, or the denominator.
+ */
+function preserveCandidateFlows(graphPath, graph) {
+    let previous;
+    try {
+        if (existsSync(graphPath))
+            previous = loadGraph(graphPath).analysis?.candidate_flows;
+    }
+    catch {
+        return graph;
+    }
+    if (!previous || !isValidStoredCandidateFlowMeta(previous))
+        return graph;
+    try {
+        return {
+            ...graph,
+            analysis: { ...graph.analysis, candidate_flows: revalidateCandidateFlowMeta(previous, graph) }
+        };
+    }
+    catch {
+        return graph;
+    }
+}
+export function opAnalyze(root, opts = {}, deps = defaultDeps()) {
+    const now = deps.clock();
+    const paths = workspacePaths(root);
+    const scanRoot = opts.source ? resolve(opts.source) : resolve(root);
+    // Fail loudly on a typo'd path instead of silently producing an empty graph.
+    if (!existsSync(scanRoot)) {
+        throw new Error(`Path not found: ${scanRoot}. Pass an existing directory to analyze (e.g. \`opro analyze .\`).`);
+    }
+    if (!statSync(scanRoot).isDirectory()) {
+        throw new Error(`Not a directory: ${scanRoot}. Pass a directory to analyze (e.g. \`opro analyze .\`).`);
+    }
+    if (!opts.suppressProgress)
+        reportProgress(`analyze: source ${scanRoot}`, { current: 1, total: 4 });
+    const runtimeCoveragePrepare = opts.generateCoverage
+        ? (!opts.suppressProgress && reportProgress("coverage: generating local runtime coverage before graph build", { current: 2, total: 4 }),
+            prepareRuntimeCoverage(scanRoot, { generate: true, timeoutMs: opts.coverageTimeoutMs, runner: deps.coverageRunner }))
+        : undefined;
+    if (!workspaceInitialized(root))
+        initWorkspace(root, now);
+    if (!opts.suppressProgress) {
+        reportProgress("analyze: parsing source and building deterministic graph", {
+            current: opts.generateCoverage ? 3 : 2,
+            total: opts.generateCoverage ? 4 : 3
+        });
+    }
+    const parseCache = loadParseCache(paths.graphPath);
+    const resolverCache = loadResolverCache(paths.graphPath);
+    const analyzeFragment = analyzeRepo(scanRoot, {
+        readContent: true,
+        maxInferredFlows: maxFlowsFromEnv(deps.env),
+        maxFiles: maxFilesFromEnv(deps.env),
+        maxSymbols: maxSymbolsFromEnv(deps.env),
+        maxAnalyzeMs: maxAnalyzeMsFromEnv(deps.env),
+        parseCache,
+        resolverCache
+    });
+    // Persist the (pruned-to-this-run) parse cache so the next analyze reuses unchanged files.
+    // Best-effort: a cache write failure must never fail analyze.
+    try {
+        writeFileAtomic(parseCachePath(paths.graphPath), JSON.stringify(parseCache.toData()));
+    }
+    catch {
+        /* ignore */
+    }
+    try {
+        writeFileAtomic(resolverCachePath(paths.graphPath), JSON.stringify(resolverCache.toData()));
+    }
+    catch {
+        /* ignore */
+    }
+    const extraPaths = (opts.paths ?? []).filter((p) => existsSync(resolve(scanRoot, p)) && /\.(csv|md|mdx|markdown|txt)$/i.test(p));
+    const enrichFragments = collectEnricherFragments(scanRoot, extraPaths, opts.includeMarkdown ?? true);
+    const builtGraph = buildGraphFromFragments(root, scanRoot, analyzeFragment, enrichFragments, now);
+    // Applied AI candidate flows must SURVIVE re-analysis, but the stored lane is
+    // untrusted (any process can rewrite graph.json) — preserve+re-validate it
+    // without ever letting a malformed lane fail analyze.
+    const graph = preserveCandidateFlows(paths.graphPath, builtGraph);
+    if (!opts.suppressProgress) {
+        reportProgress("analyze: writing graph.json", { current: opts.generateCoverage ? 4 : 3, total: opts.generateCoverage ? 4 : 3 });
+    }
+    saveGraph(paths.graphPath, graph);
+    const coverageWarnings = runtimeCoveragePrepare?.generated
+        .filter((g) => !g.ok)
+        .map((g) => `coverage generation failed for ${g.language} module ${g.module_dir}: ${g.reason ?? "unknown failure"}`) ?? [];
+    const coverageSuccess = runtimeCoveragePrepare?.generated
+        .filter((g) => g.ok && g.artifact_path)
+        .map((g) => `coverage artifact generated for ${g.language} module ${g.module_dir}: ${g.artifact_path}`) ?? [];
+    const warnings = [...coverageSuccess, ...coverageWarnings, ...(runtimeCoveragePrepare?.warnings ?? []), ...analyzeFragment.warnings, ...enrichFragments.flatMap((f) => f.warnings)];
+    return {
+        graph_path: paths.graphPath,
+        sources_count: graph.sources.length,
+        entities_count: graph.nodes.length,
+        relationships_count: graph.edges.length,
+        candidate_relationships_count: graph.candidate_edges.length,
+        behavior_anchors_count: behaviorNodes(graph).length,
+        analysis: graph.analysis ?? analyzeFragment.analysis,
+        ...(runtimeCoveragePrepare ? { runtime_coverage_prepare: runtimeCoveragePrepare } : {}),
+        ai_linked: summarizeAiLinks(graph),
+        warnings
+    };
+}
+export function opRuntimeCoverage(root, opts = {}) {
+    const scanRoot = opts.source ? resolve(opts.source) : resolve(root);
+    if (!existsSync(scanRoot)) {
+        throw new Error(`Path not found: ${scanRoot}. Pass an existing directory to coverage (e.g. \`opro coverage .\`).`);
+    }
+    if (!statSync(scanRoot).isDirectory()) {
+        throw new Error(`Not a directory: ${scanRoot}. Pass a directory to coverage (e.g. \`opro coverage .\`).`);
+    }
+    return prepareRuntimeCoverage(scanRoot, { generate: opts.generate, timeoutMs: opts.timeoutMs });
+}
+/** Persist the default provider/model chosen via `opro setup`. Keys are never stored. */
+export function opSetModelDefault(root, sel, deps = defaultDeps()) {
+    if (!workspaceInitialized(root))
+        initWorkspace(root, deps.clock());
+    const paths = workspacePaths(root);
+    saveConfig(paths, { ...loadConfig(paths), model_default: sel });
+}
+/** Read the saved default provider/model, if `opro setup` was run. */
+export function getModelDefault(root) {
+    if (!workspaceInitialized(root))
+        return null;
+    return loadConfig(workspacePaths(root)).model_default ?? null;
+}
+function startProviderOverride(root, opts) {
+    if (opts.provider || opts.model)
+        return { provider: opts.provider, model: opts.model };
+    const saved = getModelDefault(root);
+    return saved ? { provider: saved.provider, model: saved.model } : {};
+}
+/**
+ * Resolve the behaviors a diff touches, so `generate --base <ref>` targets only the
+ * changed code (PR-scoped generation) instead of the global top gap. Never throws or
+ * fabricates: returns structured guidance when there is no usable diff (not a git
+ * repo / missing base ref / no changes), or when the diff touches no tracked behavior.
+ */
+export function resolveDiffTargets(root, baseRef) {
+    const ch = opChanged(root, baseRef);
+    if (ch.status !== "ok") {
+        return { status: ch.status, base_ref: ch.base_ref, target_ids: [], guidance: ch.guidance };
+    }
+    return {
+        status: "ok",
+        base_ref: ch.base_ref,
+        target_ids: ch.affected_behaviors,
+        guidance: ch.affected_behaviors.length
+            ? undefined
+            : `The diff vs ${ch.base_ref} touched no tracked behaviors. Generate without --base, or add requirements/tests for the changed area.`
+    };
+}
+/**
+ * One-command PR support for `generate --pr <n>`: check out the PR via `gh` and
+ * resolve its base branch so the diff is scoped to the PR's changes. Side-effecting
+ * (switches the working tree via `gh pr checkout` + `git fetch`) and CLI-only.
+ *
+ * The mutation is gated: it refuses on a dirty working tree (`dirty_tree`) and
+ * does NOTHING unless `opts.confirmed` is true — without confirmation it returns
+ * `needs_confirmation` and performs no `gh`/`git` write. The non-mutating default
+ * is `--base <ref>` (read-only `git diff`); `--pr` is the opt-in escape hatch.
+ *
+ * Never throws; returns structured guidance for every refusal. Runners are
+ * injectable for tests.
+ */
+export function resolvePrCheckout(root, prNumber, opts = {}) {
+    const gh = opts.gh ?? ghRunner(root);
+    const git = opts.git ?? gitRunner(root);
+    if (!Number.isInteger(prNumber) || prNumber <= 0) {
+        return { status: "invalid_pr", pr: prNumber, guidance: "Pass a positive PR number, e.g. `opro generate --pr 123`." };
+    }
+    if (gh(["--version"]) === null) {
+        return {
+            status: "gh_missing",
+            pr: prNumber,
+            guidance: "GitHub CLI `gh` was not found. Install it (https://cli.github.com) and run `gh auth login`, or check out the PR yourself and pass --base <ref>."
+        };
+    }
+    // Refuse on a dirty working tree BEFORE any mutation: `gh pr checkout` would
+    // either fail or strand uncommitted work. A null porcelain result means git
+    // could not report status (not a repo / git error); the checkout below will
+    // surface that as checkout_failed rather than us guessing "dirty".
+    const porcelain = git(["status", "--porcelain"]);
+    if (porcelain !== null && porcelain.trim() !== "") {
+        return {
+            status: "dirty_tree",
+            pr: prNumber,
+            guidance: `Working tree has uncommitted changes — \`opro generate --pr ${prNumber}\` would run \`gh pr checkout\` and switch branches, ` +
+                "risking your work. Commit/stash first, or check out the PR yourself and use the non-mutating `--base <ref>`."
+        };
+    }
+    // No mutation without explicit confirmation. Non-TTY / --json / MCP callers
+    // never auto-confirm, so they get this and stop; a TTY user confirms (or
+    // passes --yes/--force) before we touch the working tree.
+    if (!opts.confirmed) {
+        return {
+            status: "needs_confirmation",
+            pr: prNumber,
+            guidance: `\`--pr ${prNumber}\` mutates your working tree: it runs \`gh pr checkout ${prNumber}\` (switches branch) and \`git fetch\`. ` +
+                "Re-run with --yes (or --force) to confirm, or use the non-mutating default `--base <ref>` to diff without checking out."
+        };
+    }
+    if (gh(["pr", "checkout", String(prNumber)]) === null) {
+        return {
+            status: "checkout_failed",
+            pr: prNumber,
+            guidance: `Could not check out PR #${prNumber}. Confirm gh is authenticated (gh auth status), this is the correct GitHub repo, ` +
+                `the working tree is clean, and #${prNumber} is an open PR.`
+        };
+    }
+    // Resolve the PR's base branch and make it locally diffable.
+    const baseName = gh(["pr", "view", String(prNumber), "--json", "baseRefName", "-q", ".baseRefName"])?.trim();
+    let base_ref;
+    if (baseName) {
+        git(["fetch", "origin", baseName]); // best-effort; the base may already be local
+        const remoteRef = `origin/${baseName}`;
+        if (git(["rev-parse", "--verify", "--quiet", `${remoteRef}^{commit}`]) !== null)
+            base_ref = remoteRef;
+        else if (git(["rev-parse", "--verify", "--quiet", `${baseName}^{commit}`]) !== null)
+            base_ref = baseName;
+        else
+            base_ref = remoteRef; // resolveDiffContext will surface a missing-ref guidance if unresolved
+    }
+    return { status: "ok", pr: prNumber, base_ref };
+}
+export function opStatus(root, deps = defaultDeps()) {
+    const paths = workspacePaths(root);
+    const initialized = workspaceInitialized(root);
+    if (!initialized || !graphExists(root)) {
+        return {
+            workspace_initialized: initialized,
+            graph_path: paths.graphPath,
+            last_analyzed_at: null,
+            local_only: true,
+            sources: {},
+            quality_score: null,
+            can_generate_tests: false,
+            freshness: "missing",
+            changed_files: 0,
+            analysis: null,
+            privacy: { graph_storage: "local", upload_enabled: false, source_snippets_in_pack: false }
+        };
+    }
+    const graph = loadGraph(paths.graphPath);
+    const current = scanFileEntries(graph.workspace.root);
+    const fresh = computeFreshness(graph, current);
+    const score = scoreGraph(graph);
+    const sources = {};
+    for (const s of graph.sources)
+        sources[s.source_system] = (sources[s.source_system] ?? 0) + 1;
+    return {
+        workspace_initialized: true,
+        graph_path: paths.graphPath,
+        last_analyzed_at: graph.updated_at,
+        local_only: true,
+        sources,
+        quality_score: score.overall,
+        can_generate_tests: score.overall >= 1 && graph.nodes.length > 0,
+        freshness: fresh.state,
+        changed_files: fresh.changed_files.length,
+        analysis: graph.analysis ?? null,
+        privacy: { graph_storage: "local", upload_enabled: false, source_snippets_in_pack: false }
+    };
+}
+export function opScore(root) {
+    return scoreGraph(loadGraph(workspacePaths(root).graphPath));
+}
+export function opDoctor(root) {
+    const graph = loadGraph(workspacePaths(root).graphPath);
+    return doctorGraph(graph, scoreGraph(graph));
+}
+export function opGaps(root, opts = {}) {
+    const graph = loadGraph(workspacePaths(root).graphPath);
+    const gaps = findGaps(graph, opts);
+    const topRiskGaps = rankRiskGaps(graph, { limit: opts.limit ?? 10, repoRoot: root }).map((gap) => ({
+        external_id: gap.id,
+        title: gap.title,
+        file: gap.file,
+        risk_score: gap.risk_score,
+        incoming_refs: gap.incoming_refs,
+        git_churn: gap.git_churn,
+        entry_point: gap.entry_point,
+        reasons: gap.reasons,
+        probability: gap.probability,
+        impact: gap.impact,
+        detection_difficulty: gap.detection_difficulty,
+        fan_out: gap.fan_out,
+        route_weight: gap.route_weight,
+        data_sensitivity: gap.data_sensitivity,
+        flow_position: gap.flow_position,
+        complexity_proxy: gap.complexity_proxy,
+        is_new_code: gap.is_new_code,
+        integration_signal: gap.integration_signal
+    }));
+    return {
+        ...gaps,
+        top_risk_gaps: topRiskGaps,
+        risk_model: {
+            formula: "OrangePro Risk Score = Probability(1-10) × Impact(1-10) × DetectionDifficulty(1|5|10); P = normalize(git_churn*0.35 + fan_out*0.30 + new_code*15 + complexity*0.20); I = normalize(fan_in*0.30 + route_weight*0.30 + flow_position*0.20 + data_sensitivity*0.20); D = {proven:1, associated:5, none:10}",
+            note: "Risk ranking is prioritization only. It does not change Proven, Runtime-covered, Associated signal, No integration signal, or coverage percentages."
+        }
+    };
+}
+export function opRecordRun(root, opts, deps = defaultDeps()) {
+    const paths = workspacePaths(root);
+    const preGraph = loadGraph(paths.graphPath);
+    const targetInput = opts.target_symbol ?? opts.target_id;
+    const target = targetInput ? resolveTargetSymbol(preGraph, targetInput) : null;
+    if (!target) {
+        throw new Error("record requires --target-symbol sym:<file>#<Symbol>, or a target id that resolves to exactly one CodeSymbol.");
+    }
+    const language = targetLanguage(target);
+    const preEdges = proofEdgesFor(preGraph, target);
+    const sourceRoot = resolve(opts.source ?? root);
+    const testRel = opts.test_path ? toWorkspaceRel(sourceRoot, resolveContained(sourceRoot, opts.test_path)) : undefined;
+    let status = "unproven";
+    let closed = false;
+    let newEdges = [];
+    let reason = "";
+    let reproveMode;
+    let reproveReason;
+    if (!canReproveLanguage(language)) {
+        status = "generated_unverifiable";
+        reason = `OrangePro cannot dynamically verify ${language} targets yet; recorded separately from kept-rate.`;
+    }
+    else if (preEdges.length > 0) {
+        status = "unproven";
+        reason = "Target already had a static hard edge before this run; record_run is static diagnostics only and public Proven requires orangepro_prove.";
+    }
+    else {
+        const scoped = tryScopedReprove({
+            root: opts.source ?? root,
+            graph: preGraph,
+            targetSymbol: target,
+            preEdges,
+            testPath: opts.test_path,
+            now: deps.clock()
+        });
+        let reproved;
+        if (scoped && scoped.newEdges.length > 0) {
+            saveGraph(paths.graphPath, scoped.graph);
+            reproved = { closed: true, newEdges: scoped.newEdges };
+            reproveMode = "scoped";
+            reproveReason = scoped.reason;
+        }
+        else {
+            (deps.analyze ?? opAnalyze)(root, { source: opts.source ?? root }, deps);
+            const postGraph = loadGraph(paths.graphPath);
+            reproved = reproveTarget(preEdges, postGraph, target);
+            reproveMode = "full";
+            reproveReason = opts.test_path
+                ? "Scoped confirmer did not produce a hard edge; full re-analysis decided the outcome."
+                : "No explicit test path was provided; full re-analysis decided the outcome.";
+        }
+        newEdges = testRel ? reproved.newEdges.filter((edge) => edge.startsWith(`test:${testRel}->`)) : reproved.newEdges;
+        const staticAssociated = newEdges.length > 0;
+        closed = false;
+        status = "unproven";
+        if (testRel && reproved.closed && newEdges.length === 0) {
+            reproveReason = `A hard COVERS edge for the target exists, but none came from the provided test (${testRel}); not credited to this attempt.`;
+        }
+        reason = staticAssociated
+            ? reproveMode === "scoped"
+                ? "Static COVERS edge found by scoped deterministic confirmation; public Proven still requires a dynamic targeted-proof certificate."
+                : "Static COVERS edge found after re-analysis; public Proven still requires a dynamic targeted-proof certificate."
+            : opts.vacuous
+                ? "No new hard edge; attempt marked vacuous."
+                : "No new hard COVERS edge found after re-analysis.";
+    }
+    return appendLedgerRecord(root, {
+        run_id: opts.run_id,
+        target_id: opts.target_id,
+        target_symbol: target,
+        pre_edges: preEdges,
+        new_edges: newEdges,
+        closed,
+        vacuous: opts.vacuous === true,
+        agent_pass: opts.agent_pass,
+        evidence_ids: opts.evidence_ids ?? [],
+        provider: opts.provider,
+        model: opts.model,
+        prompt_version: opts.prompt_version,
+        language,
+        status,
+        reprove_mode: reproveMode,
+        reprove_reason: reproveReason,
+        reason,
+        ts: deps.clock()
+    });
+}
+export function opDynamicProof(root, opts, deps = defaultDeps()) {
+    const paths = workspacePaths(root);
+    const graph = loadGraph(paths.graphPath);
+    const targetInput = opts.target_symbol ?? opts.target_id;
+    const target = targetInput ? resolveTargetSymbol(graph, targetInput) : null;
+    if (!target) {
+        throw new Error("prove requires --target-symbol sym:<file>#<Symbol>, or a target id that resolves to exactly one CodeSymbol.");
+    }
+    const language = targetLanguage(target);
+    if (language !== "typescript") {
+        throw new Error(`prove currently supports JavaScript/TypeScript targets only; found ${language}.`);
+    }
+    if (!opts.test_path)
+        throw new Error("prove requires --test <path>.");
+    if (opts.replacement === undefined)
+        throw new Error("prove requires --replacement <sentinel>.");
+    const sourceRoot = resolve(opts.source ?? root);
+    assertProofSourceMatchesGraph(sourceRoot, graph);
+    const symbolTarget = symbolTargetParts(target);
+    const providedTargetRel = opts.target_path ? toWorkspaceRel(sourceRoot, resolveContained(sourceRoot, opts.target_path)) : undefined;
+    assertProofTargetMatchesSymbol({ ...opts, target_path: providedTargetRel }, symbolTarget);
+    const testRel = toWorkspaceRel(sourceRoot, resolveContained(sourceRoot, opts.test_path));
+    const targetRel = symbolTarget.file;
+    const method = symbolTarget.method;
+    assertTargetFileFresh(sourceRoot, targetRel, graph);
+    const replacementMode = opts.replacement_mode ?? "return-json";
+    const runner = opts.runner ?? "auto";
+    if (replacementMode !== "return-json" && replacementMode !== "promise-json") {
+        throw new Error("prove --replacement-mode must be one of: return-json, promise-json.");
+    }
+    if (runner !== "auto" && runner !== "vitest" && runner !== "jest" && runner !== "mocha") {
+        throw new Error("prove --runner must be one of: auto, vitest, jest, mocha.");
+    }
+    const args = [
+        "--root",
+        sourceRoot,
+        "--test",
+        testRel,
+        "--target",
+        targetRel,
+        "--method",
+        method,
+        "--replacement",
+        opts.replacement,
+        "--replacement-mode",
+        replacementMode,
+        "--runner",
+        runner,
+        "--json"
+    ];
+    if (opts.timeout_ms !== undefined)
+        args.push("--timeout-ms", String(opts.timeout_ms));
+    if (opts.link_node_modules)
+        args.push("--link-node-modules");
+    if (opts.vitest_config)
+        args.push("--vitest-config", toWorkspaceRel(sourceRoot, resolveContained(sourceRoot, opts.vitest_config)));
+    if (opts.jest_config)
+        args.push("--jest-config", toWorkspaceRel(sourceRoot, resolveContained(sourceRoot, opts.jest_config)));
+    for (const entry of opts.test_env ?? [])
+        args.push("--test-env", entry);
+    const run = (deps.dynamicProofRunner ?? defaultDynamicProofRunner)(args, { cwd: sourceRoot });
+    const oracle = parseDynamicProofJson(run.stdout, run.stderr);
+    const closed = dynamicProofSucceeded(oracle);
+    const baselineGreen = oracle.baseline?.exitCode === 0 && oracle.baseline?.timedOut !== true;
+    const mutantFailedAssertion = oracle.mutant?.assertionFailure === true && oracle.mutant?.timedOut !== true;
+    const dynamicProof = {
+        proof_kind: "dynamic_targeted",
+        baseline_green: baselineGreen,
+        mutant_failed_assertion: mutantFailedAssertion,
+        // Derived from the targeted mutation kill: if the credited subject is mocked/replaced,
+        // mutating its real body cannot cause the same test to fail at an assertion.
+        target_not_mocked: closed,
+        sentinel: oracle.replacementMode ?? replacementMode,
+        runner: oracle.runner ?? runner,
+        test_path: oracle.test ?? testRel,
+        mutant_status: oracle.status
+    };
+    const result = appendLedgerRecord(root, {
+        run_id: opts.run_id,
+        target_id: opts.target_id,
+        target_symbol: target,
+        pre_edges: proofEdgesFor(graph, target),
+        new_edges: [],
+        closed,
+        evidence_ids: [],
+        language,
+        dynamic_proof: dynamicProof,
+        target_fingerprint: targetFingerprint(graph, target),
+        status: closed ? "reproven" : "unproven",
+        reason: oracle.reason ?? (closed ? "Dynamic targeted proof closed." : "Dynamic targeted proof did not close."),
+        ts: deps.clock()
+    });
+    return {
+        ...result,
+        oracle: {
+            status: oracle.status,
+            proven: oracle.proven,
+            reason: oracle.reason,
+            runner: oracle.runner,
+            replacementMode: oracle.replacementMode,
+            test: oracle.test,
+            target: oracle.target,
+            method: oracle.method,
+            baseline: oracle.baseline
+                ? {
+                    exitCode: oracle.baseline.exitCode,
+                    timedOut: oracle.baseline.timedOut,
+                    // Surface the oracle's already-redacted, single-line baseline failure summary so
+                    // autoProve can classify WHY a baseline was red (R-1). Transient return-only field:
+                    // it is NOT written to the ledger cert (the record carries only the dynamic_proof
+                    // certificate), so raw stderr never lands in the ledger or the report.
+                    failureSummary: oracle.baseline.failureSummary ?? null
+                }
+                : undefined,
+            mutant: oracle.mutant
+                ? { exitCode: oracle.mutant.exitCode, timedOut: oracle.mutant.timedOut, assertionFailure: oracle.mutant.assertionFailure }
+                : undefined,
+            medianProofMs: oracle.medianProofMs
+        }
+    };
+}
+const SETUP_DEFAULT_TIMEOUT_MS = 30_000;
+/** Validate a prove-loop setup command shape (ported from the spike cost-runner). */
+function validateSetupCommand(command, index) {
+    if (!command || typeof command !== "object") {
+        throw new Error(`prove-loop setup command ${index} must be an object`);
+    }
+    if (typeof command.command !== "string" || command.command.trim() === "") {
+        throw new Error(`prove-loop setup command ${index} missing command`);
+    }
+    if (command.args !== undefined && (!Array.isArray(command.args) || command.args.some((a) => typeof a !== "string"))) {
+        throw new Error(`prove-loop setup command ${index} has invalid args`);
+    }
+    if (command.timeout_ms !== undefined && (!Number.isInteger(command.timeout_ms) || command.timeout_ms <= 0)) {
+        throw new Error(`prove-loop setup command ${index} has invalid timeout_ms (must be a positive integer)`);
+    }
+    return { command: command.command, args: command.args ?? [], timeout_ms: command.timeout_ms };
+}
+/**
+ * Run setup_commands in the source checkout before the oracle makes its isolated
+ * baseline/mutant copies. Trusted-local prep only (same posture as test_env). The
+ * first non-zero exit or timeout stops the run; the reason redacts secret-looking output.
+ */
+function runProveLoopSetup(sourceRoot, commands, defaultTimeoutMs) {
+    for (const command of commands) {
+        const timeoutMs = command.timeout_ms ?? defaultTimeoutMs ?? SETUP_DEFAULT_TIMEOUT_MS;
+        const result = spawnSync(command.command, command.args, {
+            cwd: sourceRoot,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: timeoutMs,
+            // A successful `npm ci` / `npm run build` (the main use case) easily exceeds the
+            // 1 MiB default, which would SIGTERM the child and be misread as a failure.
+            maxBuffer: 64 * 1024 * 1024
+        });
+        const label = redactSecrets([command.command, ...command.args].join(" "));
+        if (result.error) {
+            // Spawn-level failure (status is null): ENOENT (bad command), ENOBUFS (output
+            // over maxBuffer), ETIMEDOUT, etc. Surface the real code so it is not fabricated
+            // as "(exit 1)".
+            const err = result.error;
+            const code = err.code ?? "spawn error";
+            const detail = redactSecrets(err.message ?? "").split("\n", 1)[0] ?? "";
+            return { ok: false, reason: `setup command failed: ${label} (${code}${detail ? `: ${detail}` : ""})` };
+        }
+        const exitCode = result.status ?? 1;
+        if (exitCode !== 0) {
+            const detail = redactSecrets((result.stderr || result.stdout || "").trim().split("\n", 1)[0] ?? "");
+            return { ok: false, reason: `setup command failed: ${label} (exit ${exitCode})${detail ? `: ${detail}` : ""}` };
+        }
+    }
+    return { ok: true };
+}
+/**
+ * Product wrapper around opDynamicProof: run trusted-local setup in the source
+ * checkout, then call the UNCHANGED oracle, then best-effort refresh the report.
+ * Setup lives entirely here so the proof primitive stays a small single-shot.
+ * A setup failure returns `unrunnable` WITHOUT touching the ledger (setup-didn't-run
+ * is an environmental non-event); the oracle is not called and no cert is minted.
+ */
+export function opProveLoop(root, opts, deps = defaultDeps()) {
+    // Resolve the credited symbol up front and apply the SAME TS-only guard opDynamicProof
+    // enforces — both BEFORE running setup — so a bad/non-TS target fails fast like `opro
+    // prove` and never runs setup or mints a divergent record the primitive would reject.
+    const graph = loadGraph(workspacePaths(root).graphPath);
+    const targetInput = opts.target_symbol ?? opts.target_id;
+    const target = targetInput ? resolveTargetSymbol(graph, targetInput) : null;
+    if (!target) {
+        throw new Error("prove requires --target-symbol sym:<file>#<Symbol>, or a target id that resolves to exactly one CodeSymbol.");
+    }
+    const language = targetLanguage(target);
+    if (language !== "typescript") {
+        throw new Error(`prove currently supports JavaScript/TypeScript targets only; found ${language}.`);
+    }
+    const setupCommands = (opts.setup_commands ?? []).map((command, index) => validateSetupCommand(command, index));
+    const sourceRoot = resolve(opts.source ?? root);
+    const setup = runProveLoopSetup(sourceRoot, setupCommands, opts.setup_timeout_ms);
+    if (!setup.ok) {
+        // Setup did not run: an environmental non-event, not a proof attempt of record.
+        // Append NOTHING — a setup flake (e.g. `npm ci` network blip) must never write a
+        // newer ledger record that, via RTM latest-wins, clobbers a prior closed cert for
+        // this symbol. The oracle is NOT called.
+        return { status: "unrunnable", reason: setup.reason };
+    }
+    // Setup passed (or none) → call opDynamicProof VERBATIM. It copies the now-prepared
+    // source, derives the mutation target from the credited symbol, mints the cert.
+    const proof = opDynamicProof(root, {
+        target_symbol: opts.target_symbol,
+        target_id: opts.target_id,
+        source: opts.source,
+        test_path: opts.test_path,
+        target_path: opts.target_path,
+        method: opts.method,
+        replacement: opts.replacement,
+        replacement_mode: opts.replacement_mode,
+        runner: opts.runner,
+        timeout_ms: opts.timeout_ms,
+        link_node_modules: opts.link_node_modules,
+        vitest_config: opts.vitest_config,
+        jest_config: opts.jest_config,
+        test_env: opts.test_env,
+        run_id: opts.run_id
+    }, deps);
+    // Best-effort report refresh (exactly like ai-flows --apply): a render failure
+    // must never fail a completed proof — the ledger/cert is already written.
+    let behaviorCoveragePath;
+    try {
+        behaviorCoveragePath = opBehaviorCoverageHtml(root, `${WORKSPACE_DIR}/behavior-coverage.html`).behavior_coverage_path;
+    }
+    catch {
+        // ponytail: swallow — refresh is advisory; DynamicProofResult carries no warnings channel.
+    }
+    return { ...proof, ...(behaviorCoveragePath ? { behavior_coverage_path: behaviorCoveragePath } : {}) };
+}
+export function opStats(root) {
+    return ledgerStats(root);
+}
+export function opRtm(root, opts = {}) {
+    const graph = loadGraph(workspacePaths(root).graphPath);
+    let targetIds;
+    let changedFiles;
+    let scope;
+    if (opts.baseRef) {
+        const diff = opChanged(root, opts.baseRef);
+        targetIds = diff.affected_behaviors;
+        changedFiles = diff.status === "ok" ? diff.changed_files : [];
+        scope = {
+            base_ref: diff.base_ref,
+            status: diff.status,
+            ...(diff.guidance ? { guidance: diff.guidance } : {}),
+            target_ids: diff.affected_behaviors,
+            changed_files: changedFiles
+        };
+    }
+    const format = opts.format ?? "md";
+    const result = buildRtm(graph, loadLedger(root), { targetIds, changedFiles, statuses: opts.statuses, limit: opts.limit, scope });
+    const ext = format === "json" ? "json" : format === "csv" ? "csv" : "md";
+    const absRoot = resolve(root);
+    // --out resolves like the sibling commands (export/graph-html/coverage-report):
+    // relative to the workspace root, absolute paths honored as-is, no confinement.
+    const rtmPath = opts.outputPath ? resolve(absRoot, opts.outputPath) : join(workspacePaths(root).dir, `rtm.${ext}`);
+    mkdirSync(dirname(rtmPath), { recursive: true });
+    const content = format === "json" ? JSON.stringify(result, null, 2) + "\n" : format === "csv" ? renderRtmCsv(result) : renderRtmMarkdown(result);
+    writeFileAtomic(rtmPath, content);
+    return { ...result, rtm_path: rtmPath, format };
+}
+export async function opAiLinks(root, opts = {}, deps = defaultDeps()) {
+    const paths = workspacePaths(root);
+    const graph = loadGraph(paths.graphPath);
+    if (opts.apply) {
+        const { result, graph: next } = applyAiLinks(root, graph);
+        saveGraph(paths.graphPath, { ...next, updated_at: deps.clock() });
+        return result;
+    }
+    const providerEnv = loadProviderEnv([root], deps.env);
+    const cfg = opts.provider === "deterministic" ? null : resolveProviderConfig(providerEnv, opts);
+    const provider = deps.aiProvider ?? (cfg ? buildProvider(cfg) : null);
+    if (!provider) {
+        throw new Error("No model provider configured. Set OPENAI_API_KEY, ANTHROPIC_API_KEY, or OLLAMA_BASE_URL before running ai-links.");
+    }
+    return generateAiLinks(root, graph, provider, {
+        all: opts.all,
+        symbolsPerBehavior: opts.symbolsPerBehavior ?? positiveIntEnv(providerEnv.ORANGEPRO_AI_LINK_SYMBOLS_PER_BEHAVIOR),
+        maxPromptTokens: opts.maxPromptTokens ?? positiveIntEnv(providerEnv.ORANGEPRO_AI_LINK_MAX_PROMPT_TOKENS),
+        maxBehaviors: opts.maxBehaviors ?? positiveIntEnv(providerEnv.ORANGEPRO_AI_LINK_MAX_BEHAVIORS),
+        progressRange: opts.progressRange
+    }, deps.clock);
+}
+/**
+ * LLM candidate flow discovery (Slice 4). Mirrors opAiLinks: BYOK provider,
+ * two-phase generate (stage artifact) / apply (store analysis.candidate_flows).
+ * Explicit opt-in only — NEVER auto-run by opStart. Candidate flows are a
+ * "verify these" worklist, never evidence.
+ */
+export async function opAiFlows(root, opts = {}, deps = defaultDeps()) {
+    const paths = workspacePaths(root);
+    const graph = loadGraph(paths.graphPath);
+    if (opts.apply) {
+        const { result, graph: next } = applyAiFlows(root, graph);
+        saveGraph(paths.graphPath, { ...next, updated_at: deps.clock() });
+        // Re-render the behavior report so applied candidate flows are visible.
+        // Best-effort: a render failure must never fail apply (graph is saved).
+        const warnings = [...result.warnings];
+        let behaviorCoveragePath;
+        try {
+            behaviorCoveragePath = opBehaviorCoverageHtml(root, `${WORKSPACE_DIR}/behavior-coverage.html`).behavior_coverage_path;
+        }
+        catch (error) {
+            warnings.push(`behavior coverage view not written: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return { ...result, warnings, ...(behaviorCoveragePath ? { behavior_coverage_path: behaviorCoveragePath } : {}) };
+    }
+    const providerEnv = loadProviderEnv([root], deps.env);
+    const cfg = opts.provider === "deterministic" ? null : resolveProviderConfig(providerEnv, opts);
+    const provider = deps.aiProvider ?? (cfg ? buildProvider(cfg) : null);
+    if (!provider) {
+        throw new Error("No model provider configured. Set OPENAI_API_KEY, ANTHROPIC_API_KEY, or OLLAMA_BASE_URL before running ai-flows.");
+    }
+    return generateAiFlows(root, graph, provider, deps.clock);
+}
+/**
+ * Dependency-manager lockfiles / installed-dep dirs — a diff of ONLY these maps to no behaviors.
+ * Language-agnostic (monorepos exist in every ecosystem), not JS-only: JS/TS, Rust, Go, Python,
+ * Ruby, PHP, Gradle.
+ */
+const INSTALL_ARTIFACT_BASENAMES = new Set([
+    "package-lock.json", "pnpm-lock.yaml", "yarn.lock", "bun.lock", "bun.lockb", // JS/TS
+    "cargo.lock", // Rust
+    "go.sum", // Go
+    "poetry.lock", "pipfile.lock", // Python
+    "gemfile.lock", // Ruby
+    "composer.lock", // PHP
+    "gradle.lockfile" // Gradle
+]);
+export function isInstallArtifact(rel) {
+    const p = rel.split(/[\\/]+/).join("/");
+    // installed-dep dirs
+    if (/(?:^|\/)(?:node_modules|vendor\/bundle|\.venv)(?:\/|$)/.test(p))
+        return true;
+    return INSTALL_ARTIFACT_BASENAMES.has((p.split("/").pop() ?? "").toLowerCase());
+}
+/**
+ * Auto-prove scope for `opStart`. Explicit `--base` (PR/diff mode) stays scoped to the diff verbatim.
+ * DEFAULT `opro start` must NOT let an install-artifact-only diff (e.g. a `package-lock.json` bump)
+ * scope auto-prove to zero behaviors and skip the keyless existing-tests-first lane: ignore install
+ * artifacts, and scope to the diff ONLY when it maps to >=1 eligible provable CodeSymbol target —
+ * otherwise return undefined so autoProve runs the GLOBAL top-5 existing-tests-first pass.
+ */
+export function autoProveChangedScope(graph, changed, baseRef) {
+    if (changed.status !== "ok")
+        return undefined;
+    if (baseRef)
+        return changed.changed_files; // explicit PR/diff mode: unchanged, stay scoped
+    const meaningful = changed.changed_files.filter((f) => !isInstallArtifact(f));
+    if (meaningful.length === 0)
+        return undefined; // only install artifacts → global top-5
+    const changedSet = new Set(meaningful);
+    const hasEligibleTarget = graph.nodes.some((n) => {
+        if (n.kind !== "CodeSymbol" || !isEligibleProvableTarget(n))
+            return false;
+        const ref = n.provenance?.source_ref;
+        const file = typeof n.properties.file === "string" ? n.properties.file : undefined;
+        return (ref != null && changedSet.has(ref)) || changedSet.has(n.external_id) || (file != null && changedSet.has(file));
+    });
+    return hasEligibleTarget ? meaningful : undefined; // no eligible provable target in scope → global top-5
+}
+export async function opStart(root, opts = {}, deps = defaultDeps()) {
+    const providerOpts = startProviderOverride(root, opts);
+    const scanRoot = opts.source ? resolve(opts.source) : resolve(root);
+    const providerEnv = loadProviderEnv([root, scanRoot], deps.env);
+    const providerDeps = { ...deps, env: providerEnv };
+    const scope = summarizeCorpusScope(scanRoot);
+    reportProgress(`start: preflight found ${scope.files.toLocaleString()} source/doc file(s)`, { current: 1, total: 8 });
+    reportProgress("start: running deterministic analysis", { current: 2, total: 8 });
+    const analyze = (deps.analyze ?? opAnalyze)(root, {
+        source: opts.source ?? root,
+        includeMarkdown: opts.includeMarkdown,
+        generateCoverage: opts.generateCoverage,
+        coverageTimeoutMs: opts.coverageTimeoutMs,
+        suppressProgress: true
+    }, deps);
+    const warnings = [...analyze.warnings];
+    reportProgress("start: deterministic graph is ready", { current: 4, total: 8 });
+    const providerConfigured = deps.aiProvider !== undefined || resolveProviderConfig(providerEnv, providerOpts) !== null;
+    let aiLinks = { status: "skipped", reason: "AI candidate links disabled for this run." };
+    if (opts.ai !== false) {
+        if (!providerConfigured) {
+            reportProgress("ai: skipped — no local provider key/base URL found", { current: 5, total: 8 });
+            aiLinks = {
+                status: "skipped",
+                reason: "No model provider configured; set OPENAI_API_KEY, ANTHROPIC_API_KEY, or OLLAMA_BASE_URL to auto-apply weak AI grounding."
+            };
+        }
+        else {
+            try {
+                reportProgress("ai: generating weak candidate links from the coverage-aware graph", { current: 5, total: 8 });
+                const generated = await opAiLinks(root, { ...providerOpts, all: opts.aiAll, progressRange: { start: 63, end: 75 } }, providerDeps);
+                reportProgress("ai: applying weak candidate links", { current: 6, total: 8 });
+                const applied = await opAiLinks(root, { apply: true }, providerDeps);
+                aiLinks = { status: "applied", generate: generated, apply: applied };
+                warnings.push(...generated.warnings, ...applied.warnings);
+            }
+            catch (error) {
+                const reason = error instanceof Error ? error.message : String(error);
+                aiLinks = { status: "failed", reason };
+                warnings.push(`AI candidate links skipped: ${reason}`);
+            }
+        }
+    }
+    let aiFlows = { status: "skipped", reason: "AI candidate flows disabled for this run." };
+    if (opts.ai !== false && opts.aiFlows !== false) {
+        if (!providerConfigured) {
+            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."
+            };
+        }
+        else {
+            try {
+                reportProgress("ai-flows: generating candidate behavior-flow worklist", { current: 6, total: 8 });
+                const generated = await opAiFlows(root, providerOpts, providerDeps);
+                reportProgress("ai-flows: applying candidate behavior-flow worklist", { current: 6, total: 8 });
+                const applied = await opAiFlows(root, { apply: true }, providerDeps);
+                aiFlows = { status: "applied", generate: generated, apply: applied };
+                warnings.push(...generated.warnings, ...applied.warnings);
+            }
+            catch (error) {
+                const reason = error instanceof Error ? error.message : String(error);
+                aiFlows = { status: "failed", reason };
+                warnings.push(`AI candidate flows skipped: ${reason}`);
+            }
+        }
+    }
+    // PR scope is computed once here so auto-prove can scope to the diff and the later
+    // summary can reuse it.
+    const changed = opChanged(root, opts.baseRef);
+    // Auto-prove (PR 1): key-gated generate→prove for the top provable TS/JS targets.
+    // Runs BEFORE the report/RTM writes below so they reflect any freshly-minted Proven.
+    // Proof is minted only by opProveLoop's UNCHANGED oracle; no key ⇒ no files, no proof.
+    reportProgress("auto-prove: driving generate → prove on the top provable targets", { current: 6, total: 8 });
+    let autoProveResult;
+    try {
+        autoProveResult = await autoProve(root, {
+            autoLimit: opts.autoLimit,
+            noAuto: opts.noAuto,
+            provider: providerOpts.provider,
+            model: providerOpts.model,
+            changedFiles: autoProveChangedScope(loadGraph(workspacePaths(root).graphPath), changed, opts.baseRef)
+        }, { ...providerDeps, proveLoop: opProveLoop });
+        for (const skip of autoProveResult.skipped)
+            warnings.push(`auto-prove skipped ${skip.target_symbol ?? skip.title}: ${skip.reason}`);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        autoProveResult = {
+            ran: false,
+            status: "no-targets",
+            reason: `auto-prove failed but deterministic artifacts are ready: ${reason}`,
+            attempted: 0,
+            proven: 0,
+            needs_setup: [],
+            skipped: [],
+            generated_files: [],
+            attempts: []
+        };
+        warnings.push(`auto-prove skipped: ${reason}`);
+    }
+    let coverageReport;
+    try {
+        reportProgress("artifacts: writing coverage report", { current: 6, total: 8 });
+        coverageReport = opCoverageReport(root, `${WORKSPACE_DIR}/COVERAGE_REPORT.md`).coverage_report_path;
+    }
+    catch (error) {
+        warnings.push(`coverage report not written: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    let coverageHtml;
+    try {
+        reportProgress("artifacts: writing behavior coverage view", { current: 7, total: 8 });
+        // Forward THIS-RUN dynamic-proof outcome so the report can name the dominant setup/runnability
+        // block reason when 0 behaviors closed (metadata only; mints nothing, changes no tier count).
+        const dynForReport = {
+            attempted: autoProveResult.attempted,
+            proven: autoProveResult.proven,
+            needsSetup: autoProveResult.needs_setup.map((a) => ({ category: a.category, reason: a.reason }))
+        };
+        coverageHtml = opBehaviorCoverageHtml(root, `${WORKSPACE_DIR}/behavior-coverage.html`, dynForReport).behavior_coverage_path;
+    }
+    catch (error) {
+        warnings.push(`behavior coverage view not written: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    reportProgress("artifacts: writing RTM", { current: 8, total: 8 });
+    const rtm = opRtm(root, { format: "md", baseRef: opts.baseRef, limit: START_RTM_LIMIT });
+    const finalGraph = loadGraph(workspacePaths(root).graphPath);
+    const aiLinked = summarizeAiLinks(finalGraph);
+    const finalAnalyze = {
+        ...analyze,
+        analysis: finalGraph.analysis ?? analyze.analysis,
+        candidate_relationships_count: finalGraph.candidate_edges.length,
+        ai_linked: aiLinked
+    };
+    reportProgress("artifacts: selecting gap targets", { current: 8, total: 8 });
+    const gaps = opGaps(root, { limit: 10 });
+    const nextActions = [];
+    if (coverageHtml)
+        nextActions.push(`Open ${coverageHtml} for the behavior report (codebase, behaviors, composed flows, priority risks).`);
+    // Auto-prove summary: "auto-proved M of N attempted" + needs_setup/skipped reasons + files.
+    if (autoProveResult.status === "skipped-no-key") {
+        nextActions.push(autoProveResult.reason ?? NO_KEY_MESSAGE);
+    }
+    else if (autoProveResult.status === "disabled") {
+        nextActions.push("Dynamic proof was not attempted (--no-auto); run without it to auto-mint Dynamically Proven from generated tests. Static mapping and Associated signals are unaffected.");
+    }
+    else if (autoProveResult.ran) {
+        nextActions.push(`Dynamic proof: attempted the top ${autoProveResult.attempted} target(s); ${autoProveResult.proven} dynamically proven. Static breadth (behaviors, flows, Associated signals) is mapped regardless.`);
+        if (autoProveResult.proven === 0) {
+            const dom = dominantBlockReason(autoProveResult.needs_setup);
+            if (dom)
+                nextActions.push(`Dynamic proof closed 0: blocked because ${dom.label} (${dom.count}/${dom.total}). This is a sandbox setup gap, not a static-test failure; Static Associated signals are still shown.`);
+        }
+        for (const file of autoProveResult.generated_files)
+            nextActions.push(`Auto-prove wrote generated test: ${file}`);
+        for (const attempt of autoProveResult.needs_setup)
+            nextActions.push(`Auto-prove needs setup for ${attempt.target_symbol} (${attempt.test_path}): ${attempt.reason ?? "baseline/setup did not run"}.`);
+        // Fix 2: the existing-tests lane ran without a key but minted 0 Proven (all survived) —
+        // still surface the add-a-key guidance, since a key would unlock the generation lane.
+        // (`reason` carries NO_KEY_MESSAGE only on the no-key path; skipped-no-key is handled above.)
+        if (autoProveResult.proven === 0 && autoProveResult.reason === NO_KEY_MESSAGE)
+            nextActions.push(autoProveResult.reason);
+    }
+    if (rtm.summary.total > 0 && rtm.summary.proven === 0) {
+        nextActions.push("Dynamically Proven is 0 because no dynamic proof has closed yet; this is expected after analyze-only. In a coding agent, generate a test for the top gap and follow the returned prove_run/prove_loop handoff to mint Dynamically Proven through the dynamic oracle.");
+    }
+    nextActions.push(rtm.rows.length < rtm.summary.total
+        ? `Share ${rtm.rtm_path} as the capped deterministic traceability matrix (${rtm.rows.length}/${rtm.summary.total} rows).`
+        : `Share ${rtm.rtm_path} as the deterministic traceability matrix.`);
+    if (rtm.rows.length < rtm.summary.total)
+        nextActions.push("For full machine-readable RTM, run `opro rtm --format json --out .orangepro/rtm-full.json`; avoid opening full Markdown on very large repos.");
+    if (changed.status === "ok" && changed.affected_behaviors.length > 0) {
+        nextActions.push(`In your coding agent, call orangepro_generate_tests with base_ref=${changed.base_ref}; write runnable tests, then follow each returned handoff: use prove_run when present for public Proven, otherwise record_run for static diagnostics.`);
+    }
+    else if (gaps.gaps.length > 0) {
+        nextActions.push(`In your coding agent, call orangepro_generate_tests for ${gaps.gaps[0].external_id}; write runnable tests, then follow each returned handoff: use prove_run when present for public Proven, otherwise record_run for static diagnostics.`);
+    }
+    else {
+        nextActions.push("No deterministic gap target was found; inspect the RTM and graph before generating tests.");
+    }
+    if (aiLinks.status === "skipped")
+        nextActions.push(aiLinks.reason ?? "AI grounding was skipped.");
+    if (aiLinks.status === "failed")
+        nextActions.push(`AI grounding failed but deterministic artifacts are ready: ${aiLinks.reason}`);
+    if (aiFlows.status === "applied")
+        nextActions.push("Review the AI-suggested flows section in the behavior report; these are candidate chains to verify, not evidence.");
+    if (aiFlows.status === "failed")
+        nextActions.push(`AI candidate flows failed but deterministic artifacts are ready: ${aiFlows.reason}`);
+    return {
+        scope,
+        analyze: finalAnalyze,
+        ai_links: aiLinks,
+        ai_flows: aiFlows,
+        ai_linked: aiLinked,
+        behavior_coverage_path: coverageHtml,
+        coverage_report_path: coverageReport,
+        rtm,
+        changed,
+        gaps,
+        auto_prove: autoProveResult,
+        next_actions: nextActions,
+        agent_workflow: AGENT_RUN_WORKFLOW,
+        grounding_contract: GROUNDING_CONTRACT,
+        warnings
+    };
+}
+const NO_PROVIDER_MESSAGE = 'No model provider configured. Set OPENAI_API_KEY (or OLLAMA_BASE_URL / ANTHROPIC_API_KEY) in your shell environment or a .env.provider.local file to generate with your own model, or pass provider="deterministic" (or set ORANGEPRO_ALLOW_DETERMINISTIC=1) to use the offline deterministic stand-in. No tests were generated.';
+const START_RTM_LIMIT = 500;
+const EMPTY_EVIDENCE_SUMMARY = {
+    tests: 0,
+    tests_with_proof: 0,
+    tests_without_validated_evidence: 0,
+    invalid_citations: 0
+};
+/**
+ * Resolve the generation provider per the BYOK contract. Returns null when no
+ * provider/key is configured and the deterministic stand-in was not opted into,
+ * so callers can surface NO_PROVIDER_MESSAGE instead of silently degrading.
+ */
+function resolveGenerationProvider(env, opts) {
+    if (opts.provider === "deterministic")
+        return new DeterministicProvider();
+    const cfg = resolveProviderConfig(env, { provider: opts.provider, model: opts.model });
+    if (cfg)
+        return buildProvider(cfg);
+    if (/^(1|true|yes)$/i.test(String(env.ORANGEPRO_ALLOW_DETERMINISTIC ?? "")))
+        return new DeterministicProvider();
+    return null;
+}
+export async function opGenerate(root, opts = {}, deps = defaultDeps()) {
+    const paths = workspacePaths(root);
+    const graph = loadGraph(paths.graphPath);
+    // BYOK contract: real customer generation uses their own key/local model.
+    // Load provider credentials from the workspace's .env.provider.local/.env.local/.env
+    // (never persisted) the same way ai-links/ai-flows/start do, so `opro generate`
+    // picks up a key file without exporting it into the shell. The offline
+    // deterministic stand-in is opt-in only; otherwise return setup guidance
+    // instead of silently degrading.
+    const providerEnv = loadProviderEnv([root], deps.env);
+    const provider = resolveGenerationProvider(providerEnv, opts);
+    if (!provider) {
+        return {
+            run_id: null,
+            model_provider: "none",
+            model_name: "none",
+            generated_tests: [],
+            evidence: [],
+            evidence_summary: EMPTY_EVIDENCE_SUMMARY,
+            missing_evidence: [],
+            warnings: [NO_PROVIDER_MESSAGE],
+            wrote_repo_files: false
+        };
+    }
+    const reader = fileReaderFor(graph.workspace.root);
+    const result = await generateTests(graph, { target_ids: opts.target_ids, framework: opts.framework, limit: opts.limit, input_mode: opts.input_mode, prompt_version: opts.prompt_version }, provider, reader, deps.clock);
+    if (result.run && result.generated_tests.length) {
+        const next = {
+            ...graph,
+            generation_runs: [...graph.generation_runs, result.run],
+            generated_tests: [...graph.generated_tests, ...result.generated_tests],
+            updated_at: deps.clock()
+        };
+        saveGraph(paths.graphPath, next);
+    }
+    // Validate each test's grounding citations against the graph the tests cite.
+    // This is the keyless grounding contract: provenance must be verifiable, and a
+    // test that cites nothing resolvable is surfaced loudly, not returned as success.
+    const { per_test, summary } = summarizeTestEvidence(graph, result.generated_tests);
+    const warnings = [...result.warnings];
+    if (summary.tests_without_validated_evidence > 0) {
+        warnings.push(`${summary.tests_without_validated_evidence} generated test(s) cite no evidence that resolves to the local graph — provenance unverified.`);
+    }
+    return {
+        run_id: result.run?.run_id ?? null,
+        model_provider: provider.providerName,
+        model_name: provider.modelName,
+        generated_tests: result.generated_tests,
+        evidence: per_test,
+        evidence_summary: summary,
+        missing_evidence: result.missing_evidence,
+        warnings,
+        wrote_repo_files: false
+    };
+}
+/**
+ * Run BOTH arms — prompt-only baseline vs Local KG (graph-grounded) — with the
+ * SAME model and the SAME (kit default) system prompt via the single-call path, so
+ * both arms emit runnable framework code (the only difference is KG injection).
+ * Score them across four dimensions and return the side-by-side comparison.
+ * Non-persisting testing view: it does not write generation runs into the graph.
+ */
+export async function opCompare(root, opts = {}, deps = defaultDeps()) {
+    const graph = loadGraph(workspacePaths(root).graphPath);
+    const provider = resolveGenerationProvider(deps.env, opts);
+    const ZERO = { completeness: 0, context_awareness: 0, accuracy: 0, domain_specificity: 0 };
+    const ZERO_METRICS = {
+        tests: 0,
+        concrete_assertions_avg: 0,
+        traceability_refs: 0,
+        weak_evidence_disclosed: 0,
+        smoke_only: 0
+    };
+    const emptyArm = () => ({ generated_tests: [], missing_evidence: [], warnings: [], run_hints: [] });
+    if (!provider) {
+        return {
+            model_provider: "none",
+            model_name: "none",
+            system_prompt_source: "kit_default",
+            scoring_method: "heuristic",
+            baseline: emptyArm(),
+            grounded: emptyArm(),
+            scores: { baseline: ZERO, grounded: ZERO },
+            matrix: { baseline: ZERO_METRICS, grounded: ZERO_METRICS },
+            warnings: [NO_PROVIDER_MESSAGE],
+            wrote_repo_files: false
+        };
+    }
+    const reader = fileReaderFor(graph.workspace.root);
+    // Both arms use the SAME single-call generation with the SAME (kit) system
+    // prompt; the ONLY difference is whether Local KG evidence is injected
+    // (graph_grounded) vs not (raw_prompt). Both arms emit RUNNABLE framework code,
+    // so a tester can run AND compare the actual scripts side by side.
+    const shared = { target_ids: opts.target_ids, framework: opts.framework, limit: opts.limit };
+    const baseline = await generateTests(graph, { ...shared, input_mode: "raw_prompt" }, provider, reader, deps.clock);
+    const grounded = await generateTests(graph, { ...shared, input_mode: "graph_grounded", prompt_version: opts.prompt_version }, provider, reader, deps.clock);
+    // Score holistically — the arms produce different test cases, so never per-test.
+    // Use the LLM judge when a real model is configured; fall back to the deterministic
+    // heuristic offline so the comparison still runs with no key.
+    const oracle = buildOracle(graph);
+    const haveTests = baseline.generated_tests.length > 0 || grounded.generated_tests.length > 0;
+    const judged = provider.providerName !== "deterministic" && haveTests
+        ? await judgeComparison(provider, buildJudgeContext(graph, grounded.generated_tests), baseline.generated_tests.map((t) => t.body).join("\n\n"), grounded.generated_tests.map((t) => t.body).join("\n\n"))
+        : null;
+    let scores;
+    let scoring_method;
+    let rationale;
+    if (judged) {
+        scores = { baseline: judged.baseline, grounded: judged.grounded };
+        scoring_method = "llm_judge";
+        rationale = judged.rationale;
+    }
+    else {
+        scores = {
+            baseline: scoreArm(baseline.generated_tests, oracle),
+            grounded: scoreArm(grounded.generated_tests, oracle)
+        };
+        scoring_method = "heuristic";
+    }
+    const matrix = {
+        baseline: armMetrics(baseline.generated_tests, oracle),
+        grounded: armMetrics(grounded.generated_tests, oracle)
+    };
+    return {
+        model_provider: provider.providerName,
+        model_name: provider.modelName,
+        system_prompt_source: "kit_default",
+        scoring_method,
+        ...(rationale ? { rationale } : {}),
+        baseline: {
+            generated_tests: baseline.generated_tests,
+            missing_evidence: baseline.missing_evidence,
+            warnings: baseline.warnings,
+            run_hints: runnableRunHintsFor(baseline.generated_tests, graph.workspace.root)
+        },
+        grounded: {
+            generated_tests: grounded.generated_tests,
+            missing_evidence: grounded.missing_evidence,
+            warnings: grounded.warnings,
+            run_hints: runnableRunHintsFor(grounded.generated_tests, graph.workspace.root)
+        },
+        scores,
+        matrix,
+        // Both arms share the same target-selection warnings (e.g. "no behavior
+        // anchors"), so dedupe instead of emitting each one twice.
+        warnings: [...new Set([...baseline.warnings, ...grounded.warnings])],
+        wrote_repo_files: false
+    };
+}
+/**
+ * Write a fresh A/B comparison report (Markdown + JSON) into the workspace's
+ * .orangepro/ dir. Overwritten on every run. Local testing artifact only — not the
+ * evidence pack, never uploaded.
+ */
+export function writeCompareReport(root, cmp, deps = defaultDeps()) {
+    const dir = dirname(workspacePaths(root).graphPath);
+    const now = deps.clock();
+    // Per-arm extensions: an arm whose bodies carry JSX gets .tsx (JSX in .ts is a TS error).
+    const fw = compareTestsFramework(cmp);
+    const groundedExt = testsFileExt(fw, cmp.grounded.generated_tests.map((t) => t.body));
+    const baselineExt = testsFileExt(fw, cmp.baseline.generated_tests.map((t) => t.body));
+    const names = {
+        localKgTests: testsArtifactName("compare-tests.local-kg", groundedExt),
+        baselineTests: testsArtifactName("compare-tests.baseline", baselineExt),
+        localKgJson: "compare-tests.local-kg.json",
+        baselineJson: "compare-tests.baseline.json"
+    };
+    const report_path = join(dir, "compare-report.md");
+    const report_json_path = join(dir, "compare-report.json");
+    const local_kg_tests_path = join(dir, names.localKgTests);
+    const baseline_tests_path = join(dir, names.baselineTests);
+    const local_kg_json_path = join(dir, names.localKgJson);
+    const baseline_json_path = join(dir, names.baselineJson);
+    // Per-arm test files are the durable artifacts (run + compare each arm); the
+    // Markdown report is a slim pointer + scores. Atomic writes so a background
+    // poller reading these never sees a half-written file.
+    writeFileAtomic(local_kg_tests_path, renderArmTestsFile(cmp, "grounded", now));
+    writeFileAtomic(baseline_tests_path, renderArmTestsFile(cmp, "baseline", now));
+    writeFileAtomic(local_kg_json_path, renderArmTestsJson(cmp, "grounded", now));
+    writeFileAtomic(baseline_json_path, renderArmTestsJson(cmp, "baseline", now));
+    writeFileAtomic(report_path, renderCompareReportMarkdown(cmp, now, names));
+    writeFileAtomic(report_json_path, JSON.stringify(cmp, null, 2));
+    return {
+        report_path,
+        report_json_path,
+        local_kg_tests_path,
+        baseline_tests_path,
+        local_kg_json_path,
+        baseline_json_path
+    };
+}
+export function opExplain(root, testId) {
+    return explainTest(loadGraph(workspacePaths(root).graphPath), testId);
+}
+export function opExport(root, outputPath, opts = {}, deps = defaultDeps()) {
+    const graph = loadGraph(workspacePaths(root).graphPath);
+    const score = scoreGraph(graph);
+    const pack = buildPack(graph, score, { include_generated_bodies: opts.include_generated_bodies ?? false }, deps.clock);
+    const validation = validatePack(pack);
+    const packPath = resolve(root, outputPath);
+    writeFileSync(packPath, JSON.stringify(pack, null, 2) + "\n", "utf8");
+    const summaryPath = packPath.replace(/\.json$/i, "") + ".md";
+    writeFileSync(summaryPath, packToMarkdown(pack, graph.analysis), "utf8");
+    const result = { pack_path: packPath, summary_path: summaryPath, validation };
+    if (opts.graph_html) {
+        const htmlPath = packPath.replace(/\.json$/i, "") + ".html";
+        writeFileSync(htmlPath, renderVizHtml(buildVizPayload(graph, score, loadLedger(root))), "utf8");
+        result.graph_html_path = htmlPath;
+    }
+    return result;
+}
+/** Write the self-contained offline evidence-graph explorer (metadata only). */
+export function opGraphHtml(root, outputPath = "orangepro-graph.html") {
+    const graph = loadGraph(workspacePaths(root).graphPath);
+    const html = renderVizHtml(buildVizPayload(graph, scoreGraph(graph), loadLedger(root)));
+    const htmlPath = resolve(root, outputPath);
+    writeFileSync(htmlPath, html, "utf8");
+    return { graph_html_path: htmlPath };
+}
+/** Write the self-contained offline behavior-coverage view (deterministic, metadata only). */
+export function opBehaviorCoverageHtml(root, outputPath = "orangepro-behavior-coverage.html", dynamicProof) {
+    const graph = loadGraph(workspacePaths(root).graphPath);
+    const html = renderBehaviorReport(buildBehaviorReportData(graph, loadLedger(root), { repoRoot: root, dynamicProof }));
+    const htmlPath = resolve(root, outputPath);
+    writeFileSync(htmlPath, html, "utf8");
+    return { behavior_coverage_path: htmlPath };
+}
+/** Phase 5.2 — write the human-readable COVERAGE_REPORT.md (3-file contract). */
+export function opCoverageReport(root, outputPath = "COVERAGE_REPORT.md") {
+    const graph = loadGraph(workspacePaths(root).graphPath);
+    const reportPath = resolve(root, outputPath);
+    writeFileSync(reportPath, renderCoverageReport(graph, loadLedger(root)), "utf8");
+    return { coverage_report_path: reportPath };
+}
+export function opUpdate(root, opts = {}, deps = defaultDeps()) {
+    const paths = workspacePaths(root);
+    if (!graphExists(root)) {
+        opAnalyze(root, {}, deps);
+        return { status: "rebuilt", changed_files: 0, updated_entities: 0, stale_generated_tests: 0, warnings: ["No graph existed; performed full analyze."] };
+    }
+    const old = loadGraph(paths.graphPath);
+    const scanRoot = old.workspace.root;
+    const current = scanFileEntries(scanRoot);
+    const fresh = computeFreshness(old, current);
+    if (opts.force_full_rebuild) {
+        const summary = opAnalyze(root, { source: scanRoot }, deps);
+        return { status: "rebuilt", changed_files: fresh.changed_files.length, updated_entities: summary.entities_count, stale_generated_tests: 0, warnings: summary.warnings };
+    }
+    if (fresh.changed_files.length === 0) {
+        return { status: "fresh", changed_files: 0, updated_entities: 0, stale_generated_tests: 0, warnings: [] };
+    }
+    const next = incrementalMerge(scanRoot, old, fresh.changed_files, deps.clock(), maxFlowsFromEnv(deps.env), maxFilesFromEnv(deps.env), maxSymbolsFromEnv(deps.env));
+    saveGraph(paths.graphPath, next.graph);
+    return {
+        status: "updated",
+        changed_files: fresh.changed_files.length,
+        updated_entities: next.updated_entities,
+        stale_generated_tests: next.stale_generated_tests,
+        warnings: next.warnings
+    };
+}
+function incrementalMerge(root, old, changedFiles, now, maxInferredFlows, maxFiles, maxSymbols) {
+    const changed = new Set(changedFiles);
+    // maxSymbols MUST match the analyze run: a lower cap here would drop live
+    // exports beyond it from the fresh scan and mark them stale, silently
+    // shrinking the denominator on every `opro update`.
+    const freshFragment = analyzeRepo(root, { readContent: true, maxInferredFlows, maxFiles, maxSymbols });
+    const enrichFragments = collectEnricherFragments(root, [], true);
+    const repoScopeId = freshFragment.sources[0]?.source_scope_id;
+    // Preserve enricher/manual nodes (non-analyzer); fully refresh analyzer nodes from fresh scan.
+    const preservedNodes = old.nodes.filter((n) => n.provenance.source_scope_id !== repoScopeId);
+    const freshExt = new Set(freshFragment.nodes.map((n) => n.external_id));
+    const removedAnalyzer = old.nodes
+        .filter((n) => n.provenance.source_scope_id === repoScopeId && !freshExt.has(n.external_id))
+        .map((n) => ({ ...n, stale: true }));
+    const nodes = dedupeNodesByExternalId([
+        ...freshFragment.nodes,
+        ...enrichFragments.flatMap((f) => f.nodes),
+        ...preservedNodes,
+        ...removedAnalyzer
+    ]);
+    const preservedEdges = old.edges.filter((e) => e.provenance.source_scope_id !== repoScopeId);
+    const edges = dedupeById([...freshFragment.edges, ...enrichFragments.flatMap((f) => f.edges), ...preservedEdges]);
+    const candidate_edges = dedupeById([
+        ...freshFragment.candidate_edges,
+        ...enrichFragments.flatMap((f) => f.candidate_edges),
+        ...old.candidate_edges.filter((e) => e.provenance?.source_scope_id !== repoScopeId)
+    ]);
+    // Mark generated tests stale when their grounding touches a changed file.
+    let staleCount = 0;
+    const generated_tests = old.generated_tests.map((t) => {
+        const touches = [...t.grounding.entity_ids, ...t.grounding.source_refs].some((ref) => changed.has(ref));
+        if (touches && !t.stale) {
+            staleCount++;
+            return { ...t, stale: true };
+        }
+        return t;
+    });
+    const manifest = buildManifest(freshFragment.file_entries, readGitInfo(gitRunner(root)), now);
+    const updatedEntities = freshFragment.nodes.filter((n) => {
+        const ref = n.provenance.source_ref;
+        return (ref && changed.has(ref)) || changed.has(n.external_id) || (typeof n.properties.file === "string" && changed.has(n.properties.file));
+    }).length;
+    const prunedEdges = pruneDanglingEdges(nodes, edges);
+    const graph = {
+        ...old,
+        updated_at: now,
+        sources: [...freshFragment.sources, ...enrichFragments.flatMap((f) => f.sources)],
+        nodes,
+        edges: prunedEdges,
+        candidate_edges: pruneDanglingEdges(nodes, candidate_edges),
+        generated_tests,
+        manifest,
+        analysis: {
+            ...freshFragment.analysis,
+            denominator: denominatorComposition({ nodes }),
+            confirmed_by_layer: confirmedCoverageByLayer({ nodes, edges: prunedEdges })
+        }
+    };
+    return { graph, updated_entities: updatedEntities, stale_generated_tests: staleCount, warnings: freshFragment.warnings };
+}
+const NO_DIFF_GUIDANCE = "No changed files found. Run this on a feature branch, pass base_ref, or use the test-gaps tool for baseline opportunities (CLI: opro gaps; MCP: orangepro_find_test_gaps).";
+const NO_CODE_CHANGES_GUIDANCE = "The diff vs the base ref only touched docs (.md/.txt/etc) — there is no code change to generate tests for. Generate without --base for baseline coverage, or use the test-gaps tool (CLI: opro gaps; MCP: orangepro_find_test_gaps).";
+/**
+ * Diff/PR tool-mode contract. Every tool that needs a real change set resolves
+ * its diff context here. It NEVER throws and NEVER fabricates impact: when the
+ * workspace is not a git repo, the base ref is missing, or there is no diff, it
+ * returns a structured guidance status instead. Baseline tools must NOT call it.
+ *
+ * `base_ref` defaults to `main`. The diff runs from `git merge-base <base> HEAD`
+ * to the working tree: the branch's own commits AND uncommitted edits, never
+ * upstream churn on the base (falls back to the base tip when no merge-base
+ * exists). Read-only: no repo writes, no source upload.
+ */
+export function resolveDiffContext(graph, baseRefInput) {
+    const scanRoot = graph.workspace.root;
+    const git = gitRunner(scanRoot);
+    const explicitBase = (baseRefInput && baseRefInput.trim()) || "";
+    let base_ref = explicitBase || "main";
+    const insideWorkTree = git(["rev-parse", "--is-inside-work-tree"]);
+    if (!insideWorkTree || insideWorkTree.trim() !== "true") {
+        return {
+            status: "not_a_git_repo",
+            base_ref,
+            changed_files: [],
+            guidance: "Workspace is not a git repository, so there is no diff to analyze. Use the test-gaps tool for baseline opportunities on the current checkout (CLI: opro gaps; MCP: orangepro_find_test_gaps)."
+        };
+    }
+    // No explicit base (e.g. bare diff / `--changed`): autodetect the default branch
+    // so it works on master-default repos too, not just "main".
+    if (!explicitBase) {
+        for (const cand of ["main", "master"]) {
+            if (git(["rev-parse", "--verify", "--quiet", `${cand}^{commit}`])) {
+                base_ref = cand;
+                break;
+            }
+        }
+    }
+    // Peel to a commit (^{commit}) so branches, tags, remotes, and shas all validate
+    // uniformly (and annotated tags resolve to their commit). Injection-safe: git
+    // args are passed as an array to execFileSync, never a shell string.
+    const verified = git(["rev-parse", "--verify", "--quiet", `${base_ref}^{commit}`]);
+    if (!verified) {
+        return {
+            status: "missing_base_ref",
+            base_ref,
+            changed_files: [],
+            guidance: `Base ref '${base_ref}' was not found locally. Pass an existing local ref — a branch (try "master" if this repo does not use "main"), a tag, a commit sha, or a fetched remote like "origin/main" — or use the test-gaps tool for baseline opportunities (CLI: opro gaps; MCP: orangepro_find_test_gaps).`
+        };
+    }
+    // Diff from the MERGE-BASE of base and HEAD to the working tree: the branch's
+    // own changes (plus uncommitted edits), never upstream churn. Diffing the base
+    // TIP directly counted every file changed ON the base since the branch point as
+    // "changed" — on an active repo that flooded --pr targeting with upstream-
+    // modified test files (Mattermost dogfood: 513 files / 243 tests reported for a
+    // PR whose real diff was 5). Falls back to the base tip when merge-base is
+    // unavailable (shallow clone, unrelated histories) — degraded, never fabricated.
+    const mergeBase = git(["merge-base", base_ref, "HEAD"])?.trim();
+    const diff = git(["diff", "--name-only", mergeBase || base_ref]) ?? "";
+    const rules = loadIgnore(scanRoot);
+    const allChanged = diff
+        .split(/\r?\n/)
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .filter((f) => !isPathIgnored(f, rules));
+    if (allChanged.length === 0) {
+        return { status: "no_diff", base_ref, changed_files: [], guidance: NO_DIFF_GUIDANCE };
+    }
+    // PR-scoped generation targets REAL code changes only: a docs-only diff
+    // (README/.md/.txt/etc) has nothing to test. Drop role 'doc'; keep
+    // code/test/config/other so the change set (and the area mapping) is not
+    // inflated by documentation edits.
+    const changed_files = allChanged.filter((f) => roleOf(f) !== "doc");
+    if (changed_files.length === 0) {
+        return { status: "no_code_changes", base_ref, changed_files: [], guidance: NO_CODE_CHANGES_GUIDANCE };
+    }
+    return { status: "ok", base_ref, changed_files };
+}
+export function opChanged(root, baseRef) {
+    const graph = loadGraph(workspacePaths(root).graphPath);
+    const ctx = resolveDiffContext(graph, baseRef);
+    if (ctx.status !== "ok") {
+        return {
+            status: ctx.status,
+            base_ref: ctx.base_ref,
+            changed_files: [],
+            affected_behaviors: [],
+            link_kinds: {},
+            affected_tests: [],
+            recommended_actions: [],
+            guidance: ctx.guidance
+        };
+    }
+    return changedImpact(graph, ctx.changed_files, ctx.base_ref);
+}
+export { redactSecrets };