@deksden-com/dd-flow-cli 0.9.0-beta.75 → 0.9.0-beta.79

package/dist/services/vnext-merge.js

@@ -10,16 +10,17 @@ import { resolveProjectRoot } from "../storage/paths.js";
 import { requireProjectByRoot } from "./projects.js";
 import { nextMergeRequestId } from "./ids.js";
 import { readProjectConfig } from "./config.js";
-import { appendFlowRunTimelineEvent, attachFlowRunStage, completeFlowRun, completeFlowRunStage, gitFacts, prepareVnextMergeSourceRepairAttempt } from "./runs.js";
+import { appendFlowRunTimelineEvent, attachFlowRunStage, completeFlowRun, completeFlowRunStage, gitFacts, prepareFlowRunStageAttachment, prepareVnextMergeSourceRepairAttempt } from "./runs.js";
 import { flowCommand, stagePauseCommandTemplate } from "./stage-pause.js";
-import { validateSchema } from "./schema-validation.js";
 import { writeStageReport } from "./stage-report-renderer.js";
 import { bindStageCoordinatorWork, createChildWork, failWork, finishFanInWork, finishWork, refreshRunWorkProjection, startStageCoordinatorWork } from "./work-registry.js";
 import { addVnextCodeRepair } from "./vnext-code.js";
 import { checkReceiptEvidenceValid, checkReceipts, effectiveCheckDeclarations, readCodeCheckProfile, runCodeChecks, validateFailedCheckRetry, workspaceChangedPaths, workspaceFingerprint } from "./code-checks.js";
-import { applyExternalStageContext } from "./stage-context.js";
-import { ensureLaneWorkspace, heartbeatLaneLock, releaseLaneLock, waitAcquireLaneLock } from "./lanes.js";
+import { applyExternalStageContext, prepareExternalStageContext } from "./stage-context.js";
+import { ensureLaneWorkspace, prepareLaneWorkspace, heartbeatLaneLock, releaseLaneLock, waitAcquireLaneLock } from "./lanes.js";
 import { assertRunMutationAllowed } from "./run-recovery.js";
+import { assertStageStartHookEvent } from "./hooks.js";
+import { prepareJsonSchema, prepareOutputFile } from "../cli/input-preparation.js";
 const stage = "merge";
 const stageDir = vnextStageDirectory(stage);
 export function isVnextMergeRun(context, input) {
@@ -108,20 +109,43 @@ export function prepareVnextMergeRequest(context, input) {
         return requestView(context, requireRequest(context, requestId));
     });
 }
-export async function startVnextMerge(context, input) {
+export function prepareVnextMergeStart(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const project = requireProjectByRoot(context, projectRoot);
     const run = requireRun(context, project.id, input.runId);
     const home = requireHome(run);
     const request = requestForRun(context, project.id, run.id);
     const generation = assertRunMutationAllowed(context, project.id, run.id);
+    const common = { projectRoot, project, run, request, generation };
     if (request.status === "completed")
+        return { ...common, terminal: true };
+    if (!["queued", "dispatching", "active", "action_required"].includes(request.status))
+        throw new AppError("merge_request_state_invalid", "MERGE request cannot be started in its current state", 1, { status: request.status, merge_request_id: request.merge_request_id });
+    const root = path.join(home, stageDir), workRoot = path.join(root, "works", request.executor_work_id);
+    const resultPath = path.join(workRoot, "result.json"), promptPath = path.join(workRoot, "prompt.md");
+    const work = context.db.get("SELECT status, project_id, run_id FROM works WHERE work_id = ?", [request.executor_work_id]);
+    if (!work || work.project_id !== project.id || work.run_id !== run.id || !["created", "running"].includes(work.status))
+        throw new AppError("runtime_artifact_invalid", "MERGE executor Work is missing or not startable", 1, { work_id: request.executor_work_id });
+    const index = JSON.parse(run.index_json);
+    if (!index.stage_runs?.some(entry => entry.stage === stage))
+        prepareFlowRunStageAttachment(context, { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@2" });
+    prepareLaneWorkspace(context, { projectRoot, lane: "merge", workspacePath: request.target_workspace, branch: request.target_branch });
+    const checks = effectiveMergeChecks(run, request), settings = executionSettings(run);
+    const existingPrompt = ["active", "action_required"].includes(request.status) && fs.existsSync(promptPath) ? fs.readFileSync(promptPath, "utf8") : null;
+    if (existingPrompt === null || input.externalContext)
+        prepareOutputFile(promptPath);
+    if (input.externalContext)
+        prepareExternalStageContext({ stageRoot: root, loaded: input.externalContext });
+    return { ...common, terminal: false, root, workRoot, resultPath, promptPath, checks, settings, existingPrompt };
+}
+export async function startVnextMerge(context, input, prepared = prepareVnextMergeStart(context, input)) {
+    const { projectRoot, project, run, request, generation } = prepared;
+    if (prepared.terminal)
         return requestView(context, request);
-    const root = path.join(home, stageDir);
-    const workRoot = path.join(root, "works", request.executor_work_id);
+    const { root, workRoot, resultPath, promptPath, checks, settings, existingPrompt } = prepared;
+    assertRunMutationAllowed(context, project.id, run.id, generation);
+    assertStageStartHookEvent(context, { projectId: project.id, eventKey: input.hookEventId, runId: run.id, stage, projectRoot, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
     fs.mkdirSync(workRoot, { recursive: true });
-    const resultPath = path.join(workRoot, "result.json");
-    const promptPath = path.join(workRoot, "prompt.md");
     ensureLaneWorkspace(context, { projectRoot, lane: "merge", workspacePath: request.target_workspace, branch: request.target_branch });
     const lane = await waitAcquireLaneLock(context, { projectRoot, lane: "merge", workerId: request.executor_work_id, workspacePath: request.target_workspace, timeoutSeconds: 3600, pollIntervalSeconds: 15, ttlSeconds: 7200, reason: `MERGE ${request.merge_request_id}`, ...(input.progress ? { progress: input.progress } : {}) });
     if (!lane.acquired)
@@ -133,12 +157,12 @@ export async function startVnextMerge(context, input) {
             const binding = pendingWork?.status === "created"
                 ? startStageCoordinatorWork(context, { workId: request.executor_work_id, hookEventId: input.hookEventId, stage, projectRoot, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) })
                 : bindStageCoordinatorWork(context, { workId: request.executor_work_id, hookEventId: input.hookEventId, stage, promptPath, resultPath, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
-            const prompt = fs.existsSync(promptPath) ? fs.readFileSync(promptPath, "utf8") : mergePrompt(context, { run, request, resultPath, projectRoot });
-            if (!fs.existsSync(promptPath))
+            const prompt = existingPrompt ?? mergePrompt(context, { run, request, resultPath, projectRoot }, checks, settings);
+            if (existingPrompt === null)
                 fs.writeFileSync(promptPath, prompt);
             const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
             ensureMergeStageAttached(context, run, projectRoot);
-            return startPacket(context, run, request, binding, promptPath, resultPath, prompt, projectRoot, externalContext);
+            return startPacket(context, run, request, binding, promptPath, resultPath, prompt, projectRoot, checks, externalContext);
         }
         const current = requireRequest(context, request.merge_request_id);
         const targetHead = gitValue(current.target_workspace, ["rev-parse", current.target_branch], true);
@@ -152,13 +176,13 @@ export async function startVnextMerge(context, input) {
         if (claimed.changes !== 1 && requireRequest(context, current.merge_request_id).status !== "active")
             throw new AppError("merge_claim_conflict", "MERGE request could not acquire the integration lane", 1, { merge_request_id: current.merge_request_id });
         const started = startStageCoordinatorWork(context, { workId: current.executor_work_id, hookEventId: input.hookEventId, stage, projectRoot, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
-        const prompt = mergePrompt(context, { run, request: requireRequest(context, current.merge_request_id), resultPath, projectRoot });
+        const prompt = mergePrompt(context, { run, request: requireRequest(context, current.merge_request_id), resultPath, projectRoot }, checks, settings);
         fs.writeFileSync(promptPath, prompt);
         const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
         context.db.run("UPDATE work_sessions SET prompt_path = ?, result_path = ?, updated_at = ? WHERE work_id = ? AND status = 'running'", [promptPath, resultPath, context.now(), current.executor_work_id]);
         attachFlowRunStage(context, { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@2" });
         appendFlowRunTimelineEvent(context, project.id, run.id, { type: "merge_started", merge_request_id: current.merge_request_id, work_id: current.executor_work_id, target_head: targetHead });
-        return startPacket(context, run, current, started, promptPath, resultPath, prompt, projectRoot, externalContext);
+        return startPacket(context, run, current, started, promptPath, resultPath, prompt, projectRoot, checks, externalContext);
     }
     catch (error) {
         const latest = requireRequest(context, request.merge_request_id);
@@ -172,8 +196,8 @@ export async function startVnextMerge(context, input) {
         throw error;
     }
 }
-function startPacket(context, run, request, binding, promptPath, resultPath, prompt, projectRoot, externalContext) {
-    return { ok: true, run_id: run.id, stage, merge_request_id: request.merge_request_id, work_id: request.executor_work_id, session_binding: binding.session_binding ?? binding, prompt_path: promptPath, result_path: resultPath, worker_prompt_markdown: prompt, ...(externalContext ? { external_context: externalContext } : {}), queue: queueStatus(context, request), effective_checks: effectiveMergeChecks(run, request), next: { apply_command: applyCommand(context, request, projectRoot), finish_command: finishCommand(context, run.id, request, projectRoot) } };
+function startPacket(context, run, request, binding, promptPath, resultPath, prompt, projectRoot, checks, externalContext) {
+    return { ok: true, run_id: run.id, stage, merge_request_id: request.merge_request_id, work_id: request.executor_work_id, session_binding: binding.session_binding ?? binding, prompt_path: promptPath, result_path: resultPath, worker_prompt_markdown: prompt, ...(externalContext ? { external_context: externalContext } : {}), queue: queueStatus(context, request), effective_checks: checks, next: { apply_command: applyCommand(context, request, projectRoot), finish_command: finishCommand(context, run.id, request, projectRoot) } };
 }
 export function applyVnextMerge(context, input) {
     const existing = requireRequest(context, input.requestId);
@@ -207,7 +231,7 @@ export function applyVnextMerge(context, input) {
     context.db.run("UPDATE merge_requests SET checkpoint = 'apply_recorded', result_json = ?, updated_at = ? WHERE merge_request_id = ?", [JSON.stringify({ apply_receipt: receiptFile }), context.now(), request.merge_request_id]);
     return { ok: true, ...receipt };
 }
-export async function finishVnextMerge(context, input) {
+export function prepareVnextMergeFinish(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const project = requireProjectByRoot(context, projectRoot);
     const run = requireRun(context, project.id, input.runId);
@@ -215,24 +239,35 @@ export async function finishVnextMerge(context, input) {
     const generation = assertRunMutationAllowed(context, project.id, run.id);
     if (existing.project_id !== project.id || existing.run_id !== run.id || existing.executor_work_id !== input.workId)
         throw new AppError("merge_request_mismatch", "MRG/Work/RUN/project identity does not match", 2);
-    if (existing.status === "completed") {
-        recoverCompletedMergeRun(context, run, projectRoot, existing);
-        releaseMergeLane(context, projectRoot, existing, `MERGE ${existing.merge_request_id} completion recovered`);
-        return { ok: true, resumed: true, run_id: run.id, stage, outcome: "completed", merge_request_id: existing.merge_request_id, work_id: existing.executor_work_id, integration_commit: existing.integration_commit, report_path: path.join(requireHome(run), stageDir, "stage-report.json"), next_action: "merge_completed" };
-    }
-    let request = requireOwnedActiveRequest(context, input);
-    heartbeatLaneLock(context, { projectRoot, lane: "merge", workerId: request.executor_work_id, workspacePath: request.target_workspace, ttlSeconds: 7200 });
+    if (existing.status === "completed")
+        return { projectRoot, project, run, existing, generation, terminal: true };
+    const request = requireOwnedActiveRequest(context, input);
     if (request.run_id !== run.id)
         throw new AppError("merge_request_mismatch", "MRG does not belong to RUN", 2);
     if (request.checkpoint === "baseline_locked" || !fs.existsSync(applyReceiptPath(context, request)))
         throw new AppError("merge_apply_required", "Run the exact merge apply command before MERGE finish", 2, { merge_request_id: request.merge_request_id, checkpoint: request.checkpoint });
-    if (unmerged(request.target_workspace).length)
-        throw new AppError("merge_conflicts_unresolved", "Resolve every unmerged path before finishing MERGE", 2, { paths: unmerged(request.target_workspace) });
+    const conflicts = unmerged(request.target_workspace);
+    if (conflicts.length)
+        throw new AppError("merge_conflicts_unresolved", "Resolve every unmerged path before finishing MERGE", 2, { paths: conflicts });
     const resultPath = path.join(requireHome(run), stageDir, "works", request.executor_work_id, "result.json");
-    validateSchema({ schemaName: "merge-result", file: resultPath, projectRoot: request.target_workspace, ddFlowHome: context.ddFlowHome, runId: run.id, runRoot: requireHome(run) });
-    const semantic = JSON.parse(fs.readFileSync(resultPath, "utf8"));
-    if (semantic.outcome !== "completed")
+    const result = prepareJsonSchema(resultPath, "MERGE result", { schemaName: "merge-result", projectRoot: request.target_workspace, ddFlowHome: context.ddFlowHome, runId: run.id, runRoot: requireHome(run) });
+    if (result.value.outcome !== "completed")
         throw new AppError("merge_semantic_blocked", "A blocked semantic result cannot complete MERGE", 2, { result_path: resultPath });
+    const gate = readFrozenMergeGate(path.join(requireHome(run), stageDir, "merge-gate.json"), request.merge_request_id);
+    if (input.retryCheckId)
+        validateFailedCheckRetry(context, { projectId: project.id, runId: run.id, receiptId: input.retryCheckId, declarations: gate.checks, reason: input.retryReason });
+    return { projectRoot, project, run, existing, generation, terminal: false, request, resultPath, result, gate };
+}
+export async function finishVnextMerge(context, input, prepared = prepareVnextMergeFinish(context, input)) {
+    const { projectRoot, project, run, existing, generation } = prepared;
+    if (prepared.terminal) {
+        recoverCompletedMergeRun(context, run, projectRoot, existing);
+        releaseMergeLane(context, projectRoot, existing, `MERGE ${existing.merge_request_id} completion recovered`);
+        return { ok: true, resumed: true, run_id: run.id, stage, outcome: "completed", merge_request_id: existing.merge_request_id, work_id: existing.executor_work_id, integration_commit: existing.integration_commit, report_path: path.join(requireHome(run), stageDir, "stage-report.json"), next_action: "merge_completed" };
+    }
+    let request = prepared.request;
+    heartbeatLaneLock(context, { projectRoot, lane: "merge", workerId: request.executor_work_id, workspacePath: request.target_workspace, ttlSeconds: 7200 });
+    const semantic = prepared.result.value;
     if (request.checkpoint === "apply_recorded") {
         input.progress?.("bootstrapping integrated target");
         await runBootstrap(context, run, request.target_workspace, request.merge_request_id, input.progress);
@@ -240,11 +275,9 @@ export async function finishVnextMerge(context, input) {
         context.db.run("UPDATE merge_requests SET checkpoint = 'bootstrap_ready', updated_at = ? WHERE merge_request_id = ?", [context.now(), request.merge_request_id]);
         request = requireRequest(context, request.merge_request_id);
     }
-    const gate = readFrozenMergeGate(path.join(requireHome(run), stageDir, "merge-gate.json"), request.merge_request_id), checks = gate.checks;
-    if (input.retryCheckId) {
-        validateFailedCheckRetry(context, { projectId: project.id, runId: run.id, receiptId: input.retryCheckId, declarations: checks, reason: input.retryReason });
+    const gate = prepared.gate, checks = gate.checks;
+    if (input.retryCheckId)
         appendFlowRunTimelineEvent(context, project.id, run.id, { type: "check_retry_requested", check_receipt_id: input.retryCheckId, stage, reason: input.retryReason ?? "operator retry" });
-    }
     const acceptancePath = path.join(requireHome(run), stageDir, "merge-gate-acceptance.json");
     const recovered = readMergeGateAcceptance(context, acceptancePath, request, gate);
     const resumingGate = ["checks_passed", "integration_committed", "delivered"].includes(request.checkpoint);
@@ -285,7 +318,7 @@ export async function finishVnextMerge(context, input) {
     context.db.run("UPDATE merge_requests SET checkpoint = 'delivered', updated_at = ? WHERE merge_request_id = ?", [context.now(), request.merge_request_id]);
     request = requireRequest(context, request.merge_request_id);
     performConfiguredCleanup(run, request);
-    const acceptedResult = fs.readFileSync(resultPath, "utf8");
+    const acceptedResult = prepared.result.text;
     const executor = context.db.get("SELECT status, result FROM works WHERE work_id = ?", [request.executor_work_id]);
     if (!executor)
         return recovery(context, request, "merge_executor_missing", { work_id: request.executor_work_id });
@@ -396,7 +429,7 @@ export async function repairVnextMerge(context, input) {
     appendFlowRunTimelineEvent(context, project.id, request.run_id, { type: "merge_source_repair_created", merge_request_id: request.merge_request_id, repair_work_id: repair.repair_work_id, cycle: prepared.cycle, failed_receipt_ids: failed });
     return { ok: true, run_id: request.run_id, merge_request_id: request.merge_request_id, status: "superseded", source_repair: repair, next: { kind: "start_stage", stage: "code", command: managedLifecycleCommand(context, `${flowCommand(context)} stage start ${request.run_id} --stage code --project-root ${JSON.stringify(projectRoot)} --json --progress-jsonl`) } };
 }
-function mergePrompt(context, input) { const pause = managedLifecycleCommand(context, `${flowCommand(context)} stage pause ${input.run.id} --stage merge --work ${input.request.executor_work_id} --project-root ${JSON.stringify(input.projectRoot)} --question-stdin --json`); const repair = `${flowCommand(context)} merge repair ${input.request.merge_request_id} --project-root ${JSON.stringify(input.projectRoot)} --json`; return ["<stage_identity>", `- RUN: ${input.run.id}`, `- MERGE request: ${input.request.merge_request_id}`, `- Work: ${input.request.executor_work_id}`, "- stage: merge", "</stage_identity>", "", "<trusted_runtime_context>", `- integration workspace: ${input.request.target_workspace}`, `- source workspace: ${input.request.source_workspace}`, `- frozen source commit: ${input.request.source_commit}`, `- target branch: ${input.request.target_branch}`, `- execution target baseline: ${input.request.execution_target_head}`, `- queue route: ${input.request.execution_route}`, `- delivery: ${JSON.stringify(executionSettings(input.run).merge_delivery)}`, `- cleanup: ${JSON.stringify(executionSettings(input.run).merge_cleanup)}`, "These facts and the acquired project integration lane were established by dd-flow. Do not repeat discovery and do not run git merge/rebase/squash yourself.", "</trusted_runtime_context>", "", "<effective_merge_gate>", ...effectiveMergeChecks(input.run, input.request).map((check) => `- ${check.canonical_ref ?? check.id}: ${check.command} — ${check.purpose}`), "</effective_merge_gate>", "", "<execution_contract>", `1. Run this exact standalone command first: ${applyCommand(context, input.request, input.projectRoot)}`, "2. If it reports conflicts, resolve only the actual unmerged paths in the integration workspace. Do not repeat merge apply and do not edit product code, tests, documentation or configuration merely to make a gate pass.", `3. Write the compact semantic result to ${input.resultPath}:`, "```json", JSON.stringify({ schema_id: "dd-flow/merge-result@1", outcome: "completed", summary: "What was integrated.", conflict_resolution: "How material conflicts were resolved, or empty when none.", verification_summary: "Why the integrated result is ready for deterministic checks.", residual_risks: [] }, null, 2), "```", `4. Finish with this exact standalone command and wait for all progress: ${finishCommand(context, input.run.id, input.request, input.projectRoot)}`, `If a gate fails, read its receipt and logs and determine the cause. For a product defect use ${repair}; it restores the target baseline and opens CODE → independent CODE-REVIEW → replacement MRG. For an environment failure restore the declared environment in this MERGE and use the returned finish command with --retry-check <receipt-id> --reason "<what was restored>". The CLI reruns the real gate and retains the old receipt. Never edit product code in the integration target to make a gate pass.`, "If a material conflict has no reasonable answer in accepted evidence, pause this same Work with the exact heredoc below, ask the returned user_message, then use the exact resume command returned by CLI:", "```sh", stagePauseCommandTemplate(pause), "```", "</execution_contract>", ""].join("\n"); }
+function mergePrompt(context, input, checks, settings) { const pause = managedLifecycleCommand(context, `${flowCommand(context)} stage pause ${input.run.id} --stage merge --work ${input.request.executor_work_id} --project-root ${JSON.stringify(input.projectRoot)} --question-stdin --json`); const repair = `${flowCommand(context)} merge repair ${input.request.merge_request_id} --project-root ${JSON.stringify(input.projectRoot)} --json`; return ["<stage_identity>", `- RUN: ${input.run.id}`, `- MERGE request: ${input.request.merge_request_id}`, `- Work: ${input.request.executor_work_id}`, "- stage: merge", "</stage_identity>", "", "<trusted_runtime_context>", `- integration workspace: ${input.request.target_workspace}`, `- source workspace: ${input.request.source_workspace}`, `- frozen source commit: ${input.request.source_commit}`, `- target branch: ${input.request.target_branch}`, `- execution target baseline: ${input.request.execution_target_head}`, `- queue route: ${input.request.execution_route}`, `- delivery: ${JSON.stringify(settings.merge_delivery)}`, `- cleanup: ${JSON.stringify(settings.merge_cleanup)}`, "These facts and the acquired project integration lane were established by dd-flow. Do not repeat discovery and do not run git merge/rebase/squash yourself.", "</trusted_runtime_context>", "", "<effective_merge_gate>", ...checks.map((check) => `- ${check.canonical_ref ?? check.id}: ${check.command} — ${check.purpose}`), "</effective_merge_gate>", "", "<execution_contract>", `1. Run this exact standalone command first: ${applyCommand(context, input.request, input.projectRoot)}`, "2. If it reports conflicts, resolve only the actual unmerged paths in the integration workspace. Do not repeat merge apply and do not edit product code, tests, documentation or configuration merely to make a gate pass.", `3. Write the compact semantic result to ${input.resultPath}:`, "```json", JSON.stringify({ schema_id: "dd-flow/merge-result@1", outcome: "completed", summary: "What was integrated.", conflict_resolution: "How material conflicts were resolved, or empty when none.", verification_summary: "Why the integrated result is ready for deterministic checks.", residual_risks: [] }, null, 2), "```", `4. Finish with this exact standalone command and wait for all progress: ${finishCommand(context, input.run.id, input.request, input.projectRoot)}`, `If a gate fails, read its receipt and logs and determine the cause. For a product defect use ${repair}; it restores the target baseline and opens CODE → independent CODE-REVIEW → replacement MRG. For an environment failure restore the declared environment in this MERGE and use the returned finish command with --retry-check <receipt-id> --reason "<what was restored>". The CLI reruns the real gate and retains the old receipt. Never edit product code in the integration target to make a gate pass.`, "If a material conflict has no reasonable answer in accepted evidence, pause this same Work with the exact heredoc below, ask the returned user_message, then use the exact resume command returned by CLI:", "```sh", stagePauseCommandTemplate(pause), "```", "</execution_contract>", ""].join("\n"); }
 function mergeReport(context, run, request, semantic, receipts) { const now = context.now(); const cleanup = cleanupReceiptPath(run); return { schema_id: "dd-flow/stage-report@2", run_id: run.id, stage, generated_at: now, verdict: "done", summary: semantic.summary, semantic: { result: semantic.summary, acceptance: ["source_commit_frozen", "integration_commit_created", "merge_gate_passed", "delivery_confirmed"], changed_files: [], checks: receipts.map((item) => item.command), evidence: [applyReceiptPath(context, request), ...receipts.map((item) => item.receipt_path), ...(fs.existsSync(cleanup) ? [cleanup] : [])], next_action: "merge_completed", merge: { merge_request_id: request.merge_request_id, work_id: request.executor_work_id, protocols: JSON.parse(request.protocol_ids_json), source_commit: request.source_commit, execution_target_head: request.execution_target_head, accepted_tree: request.accepted_tree, integration_commit: request.integration_commit, route: request.execution_route, delivery: executionSettings(run).merge_delivery, cleanup: executionSettings(run).merge_cleanup, verification_summary: semantic.verification_summary, residual_risks: semantic.residual_risks } }, mechanical: { started_at: request.lock_acquired_at, finished_at: now, git: gitFacts(request.target_workspace), queue: queueStatus(context, request) }, artifacts: { json: "stage-report.json", markdown: "stage-report.md", html: "stage-report.html" }, validation: { status: "passed" } }; }
 function effectiveMergeChecks(run, request) { return readFrozenMergeGate(path.join(requireHome(run), stageDir, "merge-gate.json"), request.merge_request_id).checks; }
 function planChecks(workspace, protocols) { return protocols.flatMap((protocol) => { const file = path.join(workspace, ".memory-bank", "protocol", protocol, "plan.json"); if (!fs.existsSync(file))

package/dist/services/vnext-plan-review.js

@@ -1,13 +1,13 @@
 import { managedLifecycleCommand } from "./lifecycle-invocations.js";
 import crypto from "node:crypto";
-import { withStageSettlement } from "./runs.js";
+import { withStageSettlement, prepareFlowRunStageAttachment } from "./runs.js";
 import fs from "node:fs";
 import path from "node:path";
 import { AppError } from "../shared/errors.js";
 import { resolveProjectRoot } from "../storage/paths.js";
 import { requireProjectByRoot } from "./projects.js";
 import { advanceFlowRun, appendFlowRunTimelineEvent, attachFlowRunStage, completeFlowRun, completeFlowRunStage, getFlowRunVariables, gitFacts, setRuntimeRunVariable } from "./runs.js";
-import { addWorkBatch, bindStageCoordinatorWork, ensureWorkRegistry, refreshRunWorkProjection, workStartCommand } from "./work-registry.js";
+import { addWorkBatch, prepareWorkBatch, bindStageCoordinatorWork, ensureWorkRegistry, refreshRunWorkProjection, workStartCommand } from "./work-registry.js";
 import { validateSchema } from "./schema-validation.js";
 import { flowCommand, stagePauseCommand, stagePauseCommandTemplate } from "./stage-pause.js";
 import { assertStageStartHookEvent } from "./hooks.js";
@@ -17,7 +17,8 @@ import { nextWorkId } from "./ids.js";
 import { vnextStageDirectory } from "../domain/stage-catalog.js";
 import { writeStageReport } from "./stage-report-renderer.js";
 import { assertPortableArtifactRef } from "./portable-refs.js";
-import { applyExternalStageContext } from "./stage-context.js";
+import { applyExternalStageContext, prepareExternalStageContext } from "./stage-context.js";
+import { prepareJsonSchema, prepareOutputFile } from "../cli/input-preparation.js";
 import { getStageFanoutCapacity, readFanoutDescriptor, subagentCapacityKey, writeFanoutDescriptor } from "./vnext-fanout.js";
 const stage = "plan-review";
 const stageDir = vnextStageDirectory(stage);
@@ -26,54 +27,95 @@ export function isVnextPlanReviewRun(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     return Boolean(context.db.get("SELECT id FROM runs WHERE project_id = ? AND id = ? AND flow_kind = 'vnext_protocolize'", [project.id, input.runId]));
 }
-export function startVnextPlanReview(context, input) {
-    ensureWorkRegistry(context);
+export function prepareVnextPlanReviewStart(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const project = requireProjectByRoot(context, projectRoot);
     const run = requireRun(context, projectRoot, input.runId);
     const home = requireHome(run);
-    assertStageStartHookEvent(context, { projectId: project.id, eventKey: input.hookEventId, runId: run.id, stage, projectRoot, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
-    const workspaceRoute = requireVnextWorkspaceRoute({ projectRoot, runId: run.id, runHome: home, workspaceRoot: run.workspace_root, stage: "plan-review" });
     const planRoot = path.join(home, "03-plan");
     const root = path.join(home, stageDir);
     const batch = path.join(planRoot, "code-work-batch.json");
+    const common = { projectRoot, project, run, home, planRoot, root, batch };
+    const priorStage = readIndex(run).stage_runs?.find((entry) => entry.stage === stage);
+    if (priorStage?.status === "done") {
+        const report = readJson(path.join(root, "stage-report.json"));
+        const outcome = report.semantic?.plan_review?.outcome;
+        if (outcome === "off" || outcome === "accepted")
+            return { ...common, state: "terminal", report, outcome };
+        throw new AppError("invalid_work_state", "PLAN-REVIEW is already terminal; corrections are applied in the same review Work and are not re-reviewed automatically", 2, { run_id: run.id, outcome });
+    }
+    const workspaceRoute = requireVnextWorkspaceRoute({ projectRoot, runId: run.id, runHome: home, workspaceRoot: run.workspace_root, stage: "plan-review" });
     if (!fs.existsSync(path.join(planRoot, "stage-report.json")) || !fs.existsSync(batch))
-        throw new AppError("not_found", "PLAN-REVIEW requires the accepted PLAN report and proposed CODE batch", 1);
+        throw new AppError("runtime_artifact_missing", "PLAN-REVIEW requires the accepted PLAN report and proposed CODE batch", 1);
     const requested = requestedMode(run);
     const protocolIds = protocolIdsForReview(home);
     assertReviewWorkspace(run.workspace_root, protocolIds);
     const groups = reviewGroups(home, run.workspace_root);
     const effective = resolveMode(requested, groups, home, run.workspace_root);
     const existing = context.db.get("SELECT work_id, status FROM works WHERE project_id = ? AND run_id = ? AND task = ? ORDER BY created_at DESC LIMIT 1", [project.id, run.id, reviewTask]);
+    const batchChecksum = checksum(batch), planChecksum = planSetChecksum(home, run.workspace_root);
+    if (input.externalContext)
+        prepareExternalStageContext({ stageRoot: root, loaded: input.externalContext });
+    prepareOutputFile(path.join(root, "stage-prompt.md"));
+    const active = { ...common, requested, protocolIds, groups, effective, workspaceRoute, batchChecksum, planChecksum };
     if (existing?.status === "running") {
-        const promptPath = path.join(root, "stage-prompt.md");
-        const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
-        return { ...preparedExisting(context, { projectRoot, projectId: project.id, run, root, workId: existing.work_id, hookEventId: input.hookEventId, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}), requested, effective, groups, batchChecksum: checksum(batch), planChecksum: planSetChecksum(home, run.workspace_root) }), ...(externalContext ? { external_context: externalContext } : {}) };
-    }
-    const priorStage = readIndex(run).stage_runs?.find((entry) => entry.stage === stage);
-    if (priorStage?.status === "done") {
-        const report = readJson(path.join(root, "stage-report.json"));
-        const outcome = report.semantic?.plan_review?.outcome;
-        if (outcome === "off" || outcome === "accepted")
-            return { ok: true, run_id: run.id, stage, outcome: outcome === "off" ? "review_off" : "accepted", ...(report.semantic?.code ? { code: report.semantic.code } : {}), next: { kind: "start_stage", stage: "code", command: codeCommand(context, run.id, projectRoot) }, idempotent: true };
-        throw new AppError("invalid_work_state", "PLAN-REVIEW is already terminal; corrections are applied in the same review Work and are not re-reviewed automatically", 2, { run_id: run.id, outcome });
+        const orchestration = readFanoutDescriptor(root);
+        if (!orchestration)
+            prepareOutputFile(path.join(root, "fanout.json"));
+        return { ...active, state: "resumed", workId: existing.work_id, prompt: fs.readFileSync(path.join(root, "stage-prompt.md"), "utf8"), orchestration };
     }
-    fs.mkdirSync(root, { recursive: true });
-    const now = context.now();
-    const batchChecksum = checksum(batch);
-    const planChecksum = planSetChecksum(home, run.workspace_root);
+    prepareFlowRunStageAttachment(context, { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/plan-review-decision@3" });
+    const rootWork = rootWorkId(context, project.id, run.id);
     if (effective === "off") {
         const failures = validateVnextPlanArtifacts(context, { projectRoot, workspaceRoot: run.workspace_root, runId: run.id, home, protocols: protocolIds });
         if (failures.length)
-            throw new AppError("validation", "PLAN artifacts have validation errors", 2, { errors: failures });
-        const rootWork = rootWorkId(context, project.id, run.id);
+            throw new AppError("runtime_artifact_invalid", "Accepted PLAN artifacts have validation errors", 1, { errors: failures });
+        // This is retained runtime data, not a newly supplied --file argument.
+        const codeBatch = readJson(batch);
+        let codeItems;
+        try {
+            codeItems = prepareWorkBatch(context, { parentWorkId: rootWork, value: codeBatch });
+        }
+        catch (error) {
+            if (error instanceof AppError && error.exitCode === 2)
+                throw new AppError("runtime_artifact_invalid", "Accepted CODE batch cannot be registered", 1, { file: batch, cause_code: error.code });
+            throw error;
+        }
+        for (const name of ["stage-report.json", "stage-report.md", "stage-report.html"])
+            prepareOutputFile(path.join(root, name));
+        return { ...active, state: "off", rootWork, codeItems };
+    }
+    const template = read(path.join(projectRoot, ".memory-bank", "dd-flow", "vnext", "plan-review.md"));
+    const revision = currentPlanRevision(home, run.workspace_root);
+    const capacity = getStageFanoutCapacity(context, { projectRoot, runId: run.id, stage });
+    for (const name of ["work-context.json", "fanout.json"])
+        prepareOutputFile(path.join(root, name));
+    return { ...active, state: "fresh", rootWork, template, revision, capacity };
+}
+export function startVnextPlanReview(context, input, prepared = prepareVnextPlanReviewStart(context, input)) {
+    const { projectRoot, project, run, home, root, planRoot } = prepared;
+    assertStageStartHookEvent(context, { projectId: project.id, eventKey: input.hookEventId, runId: run.id, stage, projectRoot, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
+    if (prepared.state === "terminal") {
+        const { report, outcome } = prepared;
+        return { ok: true, run_id: run.id, stage, outcome: outcome === "off" ? "review_off" : "accepted", ...(report.semantic?.code ? { code: report.semantic.code } : {}), next: { kind: "start_stage", stage: "code", command: codeCommand(context, run.id, projectRoot) }, idempotent: true };
+    }
+    const { requested, effective, groups, batchChecksum, planChecksum, workspaceRoute } = prepared;
+    if (prepared.state === "resumed") {
+        const promptPath = path.join(root, "stage-prompt.md");
+        const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
+        return { ...preparedExisting(context, { projectRoot, projectId: project.id, run, root, workId: prepared.workId, hookEventId: input.hookEventId, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}), requested, effective, groups, batchChecksum, planChecksum, orchestration: prepared.orchestration }), ...(externalContext ? { external_context: externalContext } : {}) };
+    }
+    ensureWorkRegistry(context);
+    fs.mkdirSync(root, { recursive: true });
+    const now = context.now(), rootWork = prepared.rootWork;
+    if (prepared.state === "off") {
         const promptPath = path.join(root, "stage-prompt.md");
         fs.writeFileSync(promptPath, "PLAN-REVIEW is disabled by the frozen RUN configuration.\n");
         const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
         bindStageCoordinatorWork(context, { workId: rootWork, hookEventId: input.hookEventId, stage, promptPath, resultPath: path.join(root, "stage-report.json"), ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
         attachFlowRunStage(context, { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/plan-review-decision@3" });
         return withStageSettlement(context, () => {
-            const registered = registerCode(context, project.id, run.id, batch);
+            const registered = addWorkBatch(context, { parentWorkId: rootWork, prepared: prepared.codeItems });
             const report = reportFor(context, { run, mode: effective, requested, outcome: "off", groups: [], batchChecksum, planChecksum, code: registered, now, projectRoot, flow: flowCommand(context) });
             writeReport(root, report);
             completeFlowRunStage(context, { projectRoot, runId: run.id, stage, status: "done", data: "stage-report.json", dataSchemaId: "dd-flow/stage-report@1", report: "stage-report.md", stageReport: "stage-report.html" });
@@ -82,11 +124,10 @@ export function startVnextPlanReview(context, input) {
             return { ok: true, run_id: run.id, stage, outcome: "review_off", ...(externalContext ? { external_context: externalContext } : {}), plan_review: { requested_mode: requested, effective_mode: effective, policy_source: policySource(run), reason: "No applicable independent review group." }, next: { kind: "start_stage", stage: "code", command: codeCommand(context, run.id, projectRoot) } };
         });
     }
-    const rootWork = rootWorkId(context, project.id, run.id);
     const workId = nextWorkId(context, project.id, "plan-review");
     context.db.run("INSERT INTO works (work_id, project_id, run_id, parent_work_id, task, launch_policy, result_schema, depends_on_json, status, result, started_at, created_at, updated_at, completed_at) VALUES (?, ?, ?, ?, ?, 'reuse_allowed', NULL, '[]', 'running', NULL, ?, ?, ?, NULL)", [workId, project.id, run.id, rootWork, reviewTask, now, now, now]);
     const pauseCommand = stagePauseCommand(context, { runId: run.id, stage, workId, projectRoot });
-    const prompt = orchestratorPrompt(context, { projectRoot, run, home, root, workId, requested, effective, groups, batchChecksum, planChecksum, workspaceRoute, pauseCommand, pauseCommandTemplate: stagePauseCommandTemplate(pauseCommand) });
+    const prompt = orchestratorPrompt(context, { projectRoot, run, home, root, workId, requested, effective, groups, batchChecksum, planChecksum, workspaceRoute, pauseCommand, pauseCommandTemplate: stagePauseCommandTemplate(pauseCommand), template: prepared.template, revision: prepared.revision, capacity: prepared.capacity });
     const promptPath = path.join(root, "stage-prompt.md");
     fs.writeFileSync(promptPath, prompt);
     const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
@@ -104,7 +145,7 @@ export function startVnextPlanReview(context, input) {
     const workSessionId = String(binding.work_session_id);
     const sessionId = String(binding.session_id);
     const orchestration = writeFanoutDescriptor(root, { stage, parent_work_id: workId, dispatch: "plan-review", capacity_required: true });
-    writeJson(path.join(root, "work-context.json"), { schema_id: "dd-flow/plan-review-context@1", read_only_input: { parent_work_id: workId }, system: { run_id: run.id, work_id: workId, stage, requested_mode: requested, effective_mode: effective, plan_revision: currentPlanRevision(home, run.workspace_root), plan_checksum: planChecksum, batch_checksum: batchChecksum }, groups, workspace: { project_root: projectRoot, workspace_root: run.workspace_root, stage_root: root, plan_root: planRoot } });
+    writeJson(path.join(root, "work-context.json"), { schema_id: "dd-flow/plan-review-context@1", read_only_input: { parent_work_id: workId }, system: { run_id: run.id, work_id: workId, stage, requested_mode: requested, effective_mode: effective, plan_revision: prepared.revision, plan_checksum: planChecksum, batch_checksum: batchChecksum }, groups, workspace: { project_root: projectRoot, workspace_root: run.workspace_root, stage_root: root, plan_root: planRoot } });
     refreshRunWorkProjection(context, project.id, run.id);
     appendFlowRunTimelineEvent(context, project.id, run.id, { type: "work_session_started", stage, work_id: workId, id: workSessionId, session_id: sessionId });
     return { ok: true, run_id: run.id, stage, outcome: "review_required", work_id: workId, id: workSessionId, prompt_path: promptPath, worker_prompt_markdown: fs.readFileSync(promptPath, "utf8"), ...(externalContext ? { external_context: externalContext } : {}), orchestration, plan_review: { requested_mode: requested, effective_mode: effective, policy_source: policySource(run), groups }, next: { dispatch_command: dispatchCommand(context, run.id, projectRoot), finish_command: finishCommand(context, run.id, projectRoot, path.join(root, "decision.json")) } };
@@ -187,7 +228,8 @@ function finishPlanReviewOwned(context, input) {
     if (!parent || parent.status !== "running")
         throw new AppError("invalid_work_state", "PLAN-REVIEW has no running parent Work", 2);
     const decisionPath = path.resolve(input.decisionFile ?? path.join(root, "decision.json"));
-    const decision = readDecision(context, projectRoot, run.id, home, decisionPath);
+    const decision = input.decision ?? readDecision(context, projectRoot, run.id, home, decisionPath);
+    validateSchema({ schemaName: "plan-review-decision", file: decisionPath, data: decision, projectRoot, runId: run.id, runRoot: home, ddFlowHome: context.ddFlowHome });
     const children = context.db.all("SELECT work_id, task, status, result, created_at FROM works WHERE project_id = ? AND run_id = ? AND parent_work_id = ?", [project.id, run.id, parent.work_id]);
     const contextFile = readJson(path.join(root, "work-context.json"));
     const groups = contextFile.groups ?? [];
@@ -200,7 +242,7 @@ function finishPlanReviewOwned(context, input) {
         throw new AppError("stage_pause_required", "A user or decision blocker must pause the current PLAN-REVIEW Work with `dd-flow stage pause`; do not finish the stage as blocked", 2, { run_id: run.id, stage, work_id: parent.work_id });
     }
     if (["failed", "cancelled"].includes(decision.outcome)) {
-        return withStageSettlement(context, () => { preserveDecisionReceipt(root, decisionPath); return finishTerminalReview(context, { projectRoot, projectId: project.id, run, root, planRoot, batch, parentWorkId: parent.work_id, children, contextFile, decision }); });
+        return withStageSettlement(context, () => { preserveDecisionReceipt(root, decision, input.decisionText); return finishTerminalReview(context, { projectRoot, projectId: project.id, run, root, planRoot, batch, parentWorkId: parent.work_id, children, contextFile, decision }); });
     }
     if (children.some((child) => child.status === "created" || child.status === "running"))
         throw new AppError("worker_jobs_incomplete", "PLAN-REVIEW finish requires all reviewer Works to settle", 1, { works: children.map((child) => ({ work_id: child.work_id, status: child.status })) });
@@ -247,7 +289,7 @@ function finishPlanReviewOwned(context, input) {
     const finalBatchChecksum = prepared.batchChecksum;
     return withStageSettlement(context, () => {
         prepared.publish();
-        preserveDecisionReceipt(root, decisionPath);
+        preserveDecisionReceipt(root, decision, input.decisionText);
         const registered = registerCode(context, project.id, run.id, batch);
         const now = context.now();
         settleReviewParent(context, { projectRoot, projectId: project.id, runId: run.id, parentWorkId: parent.work_id, status: "completed", result: decision.summary, reason: "plan_review_completed", resultPath: path.join(root, "stage-report.json") });
@@ -264,15 +306,13 @@ function finishPlanReviewOwned(context, input) {
 function preparedExisting(context, input) {
     const promptPath = path.join(input.root, "stage-prompt.md");
     const binding = bindStageCoordinatorWork(context, { workId: input.workId, hookEventId: input.hookEventId, stage, promptPath, resultPath: path.join(input.root, "stage-report.json"), ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
-    const orchestration = readFanoutDescriptor(input.root) ?? writeFanoutDescriptor(input.root, { stage, parent_work_id: input.workId, dispatch: "plan-review", capacity_required: true });
+    const orchestration = input.orchestration ?? writeFanoutDescriptor(input.root, { stage, parent_work_id: input.workId, dispatch: "plan-review", capacity_required: true });
     return { ok: true, resumed: true, run_id: input.run.id, stage, outcome: "review_required", work_id: input.workId, id: binding.work_session_id, prompt_path: promptPath, worker_prompt_markdown: fs.readFileSync(promptPath, "utf8"), orchestration, plan_review: { requested_mode: input.requested, effective_mode: input.effective, policy_source: policySource(input.run), groups: input.groups }, next: { dispatch_command: dispatchCommand(context, input.run.id, input.projectRoot), finish_command: finishCommand(context, input.run.id, input.projectRoot, path.join(input.root, "decision.json")) } };
 }
 function orchestratorPrompt(context, input) {
-    const template = read(path.join(input.projectRoot, ".memory-bank", "dd-flow", "vnext", "plan-review.md"));
+    const { template, revision, capacity } = input;
     const decision = path.join(input.root, "decision.json");
-    const revision = currentPlanRevision(input.home, input.run.workspace_root);
     const workspaceContract = ["<workspace_contract>", `- route: ${input.workspaceRoute.route}`, `- feature branch: ${input.workspaceRoute.feature_branch ?? "not applicable"}`, `- base commit: ${input.workspaceRoute.base_ref ?? "not applicable"}`, `- read/write workspace: ${input.run.workspace_root}`, "The CLI verified this frozen route. All plan and correction writes belong in the named workspace; project root remains only the stable lifecycle identity. Do not create, switch, merge or delete branches/worktrees.", "</workspace_contract>"].join("\n");
-    const capacity = getStageFanoutCapacity(context, { projectRoot: input.projectRoot, runId: input.run.id, stage });
     const reviewerLaunch = capacity.source === "external_policy"
         ? `After dispatch, return at the Work-graph boundary. The shared runtime launches the queued reviewer Works as separate external Sessions, at most ${capacity.available_slots} in parallel under the RUN's frozen profiles. Do not launch native children, create provider roots, run a capacity probe, or record this external limit as native capacity. Reviewers are read-only leaf workers. Continue the semantic decision only after their Work receipts settle; do not substitute a missing result or relaunch a settled reviewer.`
         : "After dispatch, stop at the Work-graph boundary. The shared controller supplies the selected adapter's native tool, exact parameters, child task, and wait contract; do not choose a provider tool from this stage prompt or substitute a shell command. It launches at most the qualified capacity at once and starts unchanged queued Works only after the current wave settles. A launch rejected before it starts is not review evidence: do not create a replacement. Each reviewer must be a genuinely fresh harness child Session; the lifecycle adapter binds that observed Session, so do not bind or supply a Session ID manually. Reviewers are read-only and must not create children. As soon as a reviewer result is accepted, release that reviewer Session when the harness permits.";
@@ -393,10 +433,13 @@ catch {
 function rootWorkId(context, projectId, runId) { const root = context.db.get("SELECT work_id FROM works WHERE project_id = ? AND run_id = ? AND parent_work_id IS NULL ORDER BY created_at LIMIT 1", [projectId, runId]); if (!root)
     throw new AppError("runtime_missing", "vNext RUN has no root Work", 1); return root.work_id; }
 function registerCode(context, projectId, runId, batch) { return addWorkBatch(context, { parentWorkId: rootWorkId(context, projectId, runId), file: batch }); }
-function readDecision(context, projectRoot, runId, runRoot, file) { const data = readJson(file); validateSchema({ schemaName: "plan-review-decision", file, data, projectRoot, runId, runRoot, ddFlowHome: context.ddFlowHome }); return data; }
-function preserveDecisionReceipt(root, source) {
+function readDecision(context, projectRoot, runId, runRoot, file) { return prepareJsonSchema(file, "PLAN-REVIEW decision", { schemaName: "plan-review-decision", projectRoot, runId, runRoot, ddFlowHome: context.ddFlowHome }).value; }
+function preserveDecisionReceipt(root, decision, preparedText) {
     const receipt = path.join(root, "decision.receipt.json");
-    const bytes = fs.readFileSync(source);
+    // The CLI has already parsed and validated this decision during prepare.
+    // Persist that immutable value rather than re-opening a caller-controlled
+    // filename after lifecycle admission.
+    const bytes = Buffer.from(preparedText ?? `${JSON.stringify(decision, null, 2)}\n`);
     if (fs.existsSync(receipt)) {
         if (!bytes.equals(fs.readFileSync(receipt)))
             throw new AppError("decision_receipt_conflict", "The immutable PLAN-REVIEW decision receipt already contains a different payload", 2, { receipt });
@@ -516,12 +559,12 @@ function requireRun(context, projectRoot, runId) { const project = requireProjec
 function requireHome(run) { if (!run.run_root)
     throw new AppError("runtime_missing", "RUN artifact root is unavailable", 1); return run.run_root; }
 function read(file) { if (!fs.existsSync(file))
-    throw new AppError("not_found", "Required vNext prompt is missing", 1, { file }); return fs.readFileSync(file, "utf8"); }
+    throw new AppError("runtime_artifact_missing", "Required vNext prompt is missing", 1, { file }); return fs.readFileSync(file, "utf8"); }
 function readJson(file) { try {
     return JSON.parse(fs.readFileSync(file, "utf8"));
 }
 catch {
-    throw new AppError("validation", "Expected valid JSON artifact", 2, { file });
+    throw new AppError("runtime_artifact_invalid", "Expected valid retained JSON artifact", 1, { file });
 } }
 function writeJson(file, value) { const temporary = `${file}.${crypto.randomUUID()}.tmp`; fs.writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`); fs.renameSync(temporary, file); }
 function checksum(file) { return crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex"); }