@deksden-com/dd-flow-cli 0.9.0-beta.74 → 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,18 +306,16 @@ 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, launch at most the qualified capacity at once. If more independent reviewer Works remain, wait for the current wave to settle, then start the unchanged queued Works in the next wave. A reviewer launch rejected before it starts is not review evidence: do not create a replacement; wait for a running wave to settle and start that same queued Work. Each reviewer must be a genuinely fresh harness child Session. The lifecycle adapter binds that observed Session; 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; do not let finished disposable workers occupy slots before the next wave.";
+        : "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.";
     return ["<stage_identity>", `- RUN: ${input.run.id}`, `- Work: ${input.workId}`, "- Stage: plan-review", `- Mode: ${input.effective}`, "</stage_identity>", "", "<trusted_runtime_context>", "These facts were collected by dd-flow. Trust them; do not repeat CLI, Git, compatibility, permission or schema discovery.", `- Project root: ${input.projectRoot}`, `- Stage workspace: ${input.root}`, `- PLAN revision: ${revision}`, `- PLAN report checksum: ${input.planChecksum}`, `- Generated CODE batch checksum: ${input.batchChecksum}`, "</trusted_runtime_context>", "", workspaceContract, "", "<review_groups>", ...input.groups.map((group) => `- ${group.key}: ${group.aspect_ids.join(", ")}`), "</review_groups>", "", "<execution_commands>", `Dispatch fresh reviewers: ${dispatchCommand(context, input.run.id, input.projectRoot)}`, `If dispatch reports qualified_capacity_required, stop. The external harness controller qualifies the selected profile outside this RUN and records the resulting integer with ${capacityRecordCommand(context, input.run.id, input.projectRoot, "<qualified-native-child-count>")}. PLAN-REVIEW never launches a capacity probe.`, reviewerLaunch, "Review the execution environment of every selected check as part of its proof: a reset/fixture process, service process and client process must share the intended data and configuration world. A runtime entrypoint that can break that invariant must be explicit in one Work's task and verification and ordered before its consumer. planned_write_areas may advertise likely overlap, but do not treat them as ownership; required_read alone is not a delivery plan.", "If the final decision needs user input with no reasonable default, run this exact one-command heredoc, replacing only its placeholder body. The heredoc is the permitted stdin form; do not use cat, a pipe, a temporary file or a second shell command:", "```sh", input.pauseCommandTemplate, "```", "Ask the returned user_message, stop, then resume this same PLAN-REVIEW Work. Do not write decision.json or finish first.", `When all reviewer results are complete and every user question is resolved, classify every material finding, fix accepted findings in this same PLAN-REVIEW Work, then write ${decision} and finish: ${finishCommand(context, input.run.id, input.projectRoot, decision)}`, "Reviewer findings use local FIND-NNN ids. dd-flow exposes each finding to this coordinator as WRK-.../FIND-NNN; use that canonical finding_ref in the decision.", "A completed reviewer result with needs_changes or blocked is evidence, not the stage outcome. Classify its material findings and apply accepted fixes in this one review pass; do not start a second review automatically. Only a missing, malformed or unfinished reviewer result blocks the stage. For an accepted correction, increment PLAN revision and update only plan.json and the relevant aspect map. Do not edit or list code-work-batch.json: the CLI validates final PLAN and regenerates it. If no material correction is needed, set correction.status=not_required. The CLI checks mechanical handoff coherence; it does not prove semantic correctness.", "```json", JSON.stringify({ schema_id: "dd-flow/plan-review-decision@3", outcome: "accepted | failed | cancelled", summary: "Concise evidence-backed final decision.", finding_decisions: [{ finding_ref: "WRK-001-review/FIND-001", decision: "accepted_fix | rejected | deferred_as_DEF | requires_user | duplicate", reason: "Why." }], correction: { status: "not_required | applied", previous_plan_revision: revision, changed_paths: [], summary: "No material correction was needed, or summarize the applied correction." } }, null, 2), "```", "</execution_commands>", "", "<stage_instructions>", template, "</stage_instructions>", ""].join("\n");
 }
 function reviewGroups(home, workspaceRoot) {
@@ -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"); }