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

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

@@ -10,17 +10,18 @@ import { validateSchema } from "./schema-validation.js";
 import { flowCommand } from "./stage-pause.js";
 import { assertStageStartHookEvent } from "./hooks.js";
 import { requireVnextWorkspaceRoute } from "./vnext-workspace-policy.js";
-import { addVnextCodeRepair, resumeAcceptedCodeStage } from "./vnext-code.js";
+import { addVnextCodeRepair, prepareVnextCodeRepair, resumeAcceptedCodeStage } from "./vnext-code.js";
 import { finalCodeCheckDeclarations, runCodeChecks, validateFailedCheckRetry, workspaceChangedPaths } from "./code-checks.js";
-import { addWorkBatch, bindStageCoordinatorWork, finishStageCoordinatorWork, refreshRunWorkProjection } from "./work-registry.js";
-import { withStageSettlement } from "./runs.js";
+import { addWorkBatch, prepareWorkBatch, bindStageCoordinatorWork, finishStageCoordinatorWork, refreshRunWorkProjection } from "./work-registry.js";
+import { withStageSettlement, prepareFlowRunStageAttachment } from "./runs.js";
 import { vnextStageDirectory } from "../domain/stage-catalog.js";
 import { writeStageReport } from "./stage-report-renderer.js";
-import { applyExternalStageContext } from "./stage-context.js";
+import { applyExternalStageContext, prepareExternalStageContext } from "./stage-context.js";
 import { readFanoutDescriptor, writeFanoutDescriptor } from "./vnext-fanout.js";
 import { prepareVnextMergeRequest } from "./vnext-merge.js";
 import { validateVnextCodeHandoff } from "./vnext-plan.js";
 import { assertRunMutationAllowed } from "./run-recovery.js";
+import { prepareJsonFile, prepareOutputFile } from "../cli/input-preparation.js";
 const stage = "code-review";
 const stageDir = vnextStageDirectory(stage);
 const baselineAspects = ["goal_traceability", "coding_standards_design_review", "verification_evidence_review"];
@@ -28,34 +29,57 @@ export function isVnextCodeReviewRun(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 startVnextCodeReview(context, input) {
+export function prepareVnextCodeReviewStart(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const project = requireProjectByRoot(context, projectRoot);
     const run = requireRun(context, project.id, input.runId);
     const home = requireHome(run);
-    assertStageStartHookEvent(context, { projectId: project.id, eventKey: input.hookEventId, runId: run.id, stage, projectRoot, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
+    assertRunMutationAllowed(context, project.id, run.id);
     requireVnextWorkspaceRoute({ projectRoot, runId: run.id, runHome: home, workspaceRoot: run.workspace_root, stage });
     if (!fs.existsSync(path.join(home, "05-code", "stage-report.json")))
-        throw new AppError("not_found", "CODE-REVIEW requires an accepted CODE report", 1);
+        throw new AppError("runtime_artifact_missing", "CODE-REVIEW requires an accepted CODE report", 1);
     const root = path.join(home, stageDir);
-    fs.mkdirSync(root, { recursive: true });
     const rootWork = requireRootWork(context, project.id, run.id);
     const prior = stageStatus(run, stage);
     const existingPrompt = path.join(root, "stage-prompt.md");
-    if (prior && fs.existsSync(existingPrompt)) {
+    if (input.externalContext)
+        prepareExternalStageContext({ stageRoot: root, loaded: input.externalContext });
+    prepareOutputFile(existingPrompt);
+    const common = { projectRoot, project, run, home, root, rootWork, existingPrompt };
+    if (prior && fs.existsSync(existingPrompt))
+        return { ...common, resumed: true, prior, prompt: fs.readFileSync(existingPrompt, "utf8"), orchestration: readFanoutDescriptor(root) };
+    prepareFlowRunStageAttachment(context, { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@1" });
+    const mode = effectiveMode(home, run);
+    const cycle = reviewCycle(run);
+    const codeReportSha256 = sha256File(path.join(home, "05-code", "stage-report.json"));
+    const groups = mode.mode === "off" ? [] : reviewGroups(home);
+    const batch = { works: groups.map((group, index) => ({ key: `code-review-${index + 1}`, task: reviewerTask(home, group), launch_policy: "fresh_agent_required", result_schema: "dd-flow/code-review-result@1", payload: { kind: "code-review", review_cycle: cycle, group, read_only: true } })) };
+    const items = mode.mode === "off" ? [] : prepareWorkBatch(context, { parentWorkId: rootWork.work_id, value: batch });
+    const template = mode.mode === "off" ? "" : read(path.join(run.workspace_root, ".memory-bank", "dd-flow", "vnext", "code-review.md"));
+    const checks = mode.mode === "off" ? [] : acceptedCodeChecks(context, project.id, run.id).map(({ id, purpose }) => ({ id, purpose }));
+    for (const name of ["review-context.json", ...(mode.mode === "off" ? ["decision.json"] : ["review-work-batch.json", "fanout.json"])])
+        prepareOutputFile(path.join(root, name));
+    return { ...common, resumed: false, mode, cycle, codeReportSha256, groups, batch, items, template, checks };
+}
+export function startVnextCodeReview(context, input, prepared = prepareVnextCodeReviewStart(context, input)) {
+    const { projectRoot, project, run, root, rootWork, existingPrompt } = prepared;
+    assertRunMutationAllowed(context, project.id, run.id);
+    assertStageStartHookEvent(context, { projectId: project.id, eventKey: input.hookEventId, runId: run.id, stage, projectRoot, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
+    fs.mkdirSync(root, { recursive: true });
+    if (prepared.resumed) {
         const externalContext = applyExternalStageContext({ stageRoot: root, promptPath: existingPrompt, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
         const binding = bindStageCoordinatorWork(context, { workId: rootWork.work_id, hookEventId: input.hookEventId, stage, promptPath: existingPrompt, resultPath: path.join(root, "stage-report.json"), ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
         const prompt = fs.readFileSync(existingPrompt, "utf8");
-        const orchestration = readFanoutDescriptor(root);
-        return { ok: true, resumed: true, run_id: run.id, stage, stage_status: prior, id: binding.work_session_id, prompt_path: existingPrompt, worker_prompt_markdown: prompt, ...(externalContext ? { external_context: externalContext } : {}), ...(orchestration ? { orchestration } : {}), next: { finish_command: finishCommand(context, run.id, projectRoot, path.join(root, "decision.json")) } };
+        const orchestration = prepared.orchestration;
+        return { ok: true, resumed: true, run_id: run.id, stage, stage_status: prepared.prior, id: binding.work_session_id, prompt_path: existingPrompt, worker_prompt_markdown: prompt, ...(externalContext ? { external_context: externalContext } : {}), ...(orchestration ? { orchestration } : {}), next: { finish_command: finishCommand(context, run.id, projectRoot, path.join(root, "decision.json")) } };
     }
-    const mode = effectiveMode(home, run);
-    const cycle = reviewCycle(run);
+    const { mode, cycle, groups, batch, items, template, checks, codeReportSha256 } = prepared;
     freezeFlowRunReviewMode(context, { projectRoot, runId: run.id, review: "code", mode: mode.mode, source: mode.source, reason: mode.reason });
     const promptPath = path.join(root, "stage-prompt.md");
     const reviewContextPath = path.join(root, "review-context.json");
-    fs.writeFileSync(reviewContextPath, `${JSON.stringify({ schema_id: "dd-flow/code-review-context@1", cycle, mode: mode.mode, mode_source: mode.source, mode_reason: mode.reason, ...(mode.mode !== "off" ? { read_only_input: { parent_work_id: rootWork.work_id } } : {}), code_report_sha256: sha256File(path.join(home, "05-code", "stage-report.json")) }, null, 2)}\n`);
+    fs.writeFileSync(reviewContextPath, `${JSON.stringify({ schema_id: "dd-flow/code-review-context@1", cycle, mode: mode.mode, mode_source: mode.source, mode_reason: mode.reason, ...(mode.mode !== "off" ? { read_only_input: { parent_work_id: rootWork.work_id } } : {}), code_report_sha256: codeReportSha256 }, null, 2)}\n`);
     if (mode.mode === "off") {
+        fs.writeFileSync(path.join(root, "decision.json"), `${JSON.stringify(disabledReviewDecision(), null, 2)}\n`);
         const prompt = `<stage_identity>\n- RUN: ${run.id}\n- stage: code-review\n- mode: off\n</stage_identity>\n\nCODE-REVIEW is disabled by the frozen RUN configuration. Finish with: ${finishCommand(context, run.id, projectRoot, path.join(root, "decision.json"))}\n`;
         fs.writeFileSync(promptPath, prompt);
         const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
@@ -63,22 +87,23 @@ export function startVnextCodeReview(context, input) {
         attachFlowRunStage(context, { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@1" });
         return { ok: true, run_id: run.id, stage, mode: mode.mode, mode_source: mode.source, id: binding.work_session_id, prompt_path: promptPath, worker_prompt_markdown: fs.readFileSync(promptPath, "utf8"), ...(externalContext ? { external_context: externalContext } : {}), next: { finish_command: finishCommand(context, run.id, projectRoot, path.join(root, "decision.json")) } };
     }
-    const groups = reviewGroups(home);
-    const batch = { works: groups.map((group, index) => ({ key: `code-review-${index + 1}`, task: reviewerTask(home, group), launch_policy: "fresh_agent_required", result_schema: "dd-flow/code-review-result@1", payload: { kind: "code-review", review_cycle: cycle, group, read_only: true } })) };
     const batchFile = path.join(root, "review-work-batch.json");
     fs.writeFileSync(batchFile, `${JSON.stringify(batch, null, 2)}\n`);
-    const prompt = orchestratorPrompt(context, { projectRoot, run, root, rootWork, mode: mode.mode, groups });
+    const prompt = orchestratorPrompt(context, { projectRoot, run, root, rootWork, mode: mode.mode, groups, template, checks });
     fs.writeFileSync(promptPath, prompt);
     const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
     const binding = bindStageCoordinatorWork(context, { workId: rootWork.work_id, hookEventId: input.hookEventId, stage, promptPath, resultPath: path.join(root, "stage-report.json"), ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
-    const registered = addWorkBatch(context, { parentWorkId: rootWork.work_id, file: batchFile });
+    const registered = addWorkBatch(context, { parentWorkId: rootWork.work_id, value: batch, prepared: items });
     const orchestration = writeFanoutDescriptor(root, { stage, parent_work_id: rootWork.work_id, dispatch: "none", capacity_required: true });
     attachFlowRunStage(context, { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@1" });
     appendFlowRunTimelineEvent(context, project.id, run.id, { type: "code_review_started", work_id: rootWork.work_id, mode: mode.mode, mode_source: mode.source, groups, registered });
     return { ok: true, run_id: run.id, stage, mode: mode.mode, mode_source: mode.source, id: binding.work_session_id, prompt_path: promptPath, worker_prompt_markdown: fs.readFileSync(promptPath, "utf8"), ...(externalContext ? { external_context: externalContext } : {}), orchestration, review: { groups, works: registered }, next: { finish_command: finishCommand(context, run.id, projectRoot, path.join(root, "decision.json")) } };
 }
-/** Create a narrow CODE repair from accepted independent-review evidence. */
-export function addVnextCodeReviewRepair(context, input) {
+export function prepareVnextCodeReviewRepair(context, input) {
+    if (!Array.isArray(input.findingIds) || !input.findingIds.length || input.findingIds.some(id => typeof id !== "string" || !id.trim()))
+        throw new AppError("validation", "Repair requires nonempty finding IDs", 2);
+    if (!input.checkRefsByFinding || typeof input.checkRefsByFinding !== "object" || Array.isArray(input.checkRefsByFinding) || Object.entries(input.checkRefsByFinding).some(([id, refs]) => !input.findingIds.includes(id) || !Array.isArray(refs) || refs.some(ref => typeof ref !== "string" || !ref.trim())))
+        throw new AppError("validation", "Repair check references must map selected findings to check IDs", 2);
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const project = requireProjectByRoot(context, projectRoot);
     const run = requireRun(context, project.id, input.runId);
@@ -103,7 +128,7 @@ export function addVnextCodeReviewRepair(context, input) {
     if (unknown.length)
         throw new AppError("review_check_reference_unknown", "CODE-REVIEW finding cites a check absent from the accepted CODE handoff", 2, { check_refs: unknown });
     const reviewChecks = requestedCheckRefs.map((ref) => checks.get(ref));
-    return addVnextCodeRepair(context, {
+    const repairInput = {
         projectRoot,
         runId: run.id,
         reviewFindings: selected.map(({ finding_ref, finding }) => ({ finding_ref, priority: finding.priority, problem: finding.problem, impact: finding.impact, required_outcome: finding.required_outcome, evidence_refs: finding.evidence_refs, obligation_refs: finding.obligation_refs, decision_reason: input.decisionReasonsByFinding?.[finding_ref] ?? input.objective, check_refs: input.checkRefsByFinding[finding_ref] ?? [] })),
@@ -111,7 +136,11 @@ export function addVnextCodeReviewRepair(context, input) {
         originWorkIds: origins,
         objective: input.objective,
         reviewCycle: reviewCycle(run)
-    });
+    };
+    return { input: repairInput, value: prepareVnextCodeRepair(context, repairInput) };
+}
+export function addVnextCodeReviewRepair(context, input, prepared = prepareVnextCodeReviewRepair(context, input)) {
+    return addVnextCodeRepair(context, prepared.input, prepared.value);
 }
 export async function finishVnextCodeReview(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
@@ -140,10 +169,14 @@ export async function finishVnextCodeReview(context, input) {
     const coordinator = context.db.get("SELECT session_id, result_path FROM work_sessions WHERE work_id = ? AND status = 'running' ORDER BY created_at DESC LIMIT 1", [rootWork.work_id]);
     if (!coordinator || path.resolve(coordinator.result_path ?? "") !== path.resolve(reportPath))
         throw new AppError("code_review_session_binding_conflict", "CODE-REVIEW can finish only after its successful stage start bound the coordinator Session and report path", 1, { run_id: run.id, expected_result_path: reportPath, actual_result_path: coordinator?.result_path ?? null });
-    const decisionFile = input.decisionFile ?? path.join(root, "decision.json");
-    if (!fs.existsSync(decisionFile) && mode === "off")
-        fs.writeFileSync(decisionFile, `${JSON.stringify({ schema_id: "dd-flow/code-review-decision@3", summary: "CODE-REVIEW is disabled by RUN configuration.", findings: [] }, null, 2)}\n`);
-    const decision = readCodeReviewDecision(decisionFile, reviewContext.accepted_decision, Boolean(input.decisionFile));
+    const decisionFile = path.resolve(input.decisionFile ?? path.join(root, "decision.json"));
+    const disabledDecision = disabledReviewDecision();
+    // The implicit review-off decision is the one deliberate no-file path.  An
+    // explicitly supplied --decision-file is still caller input and must be
+    // readable before any lifecycle work can proceed.
+    const decision = mode === "off" && !input.decision && !input.decisionFile && !fs.existsSync(decisionFile)
+        ? disabledDecision
+        : readCodeReviewDecision(decisionFile, reviewContext.accepted_decision, Boolean(input.decisionFile), input.decision);
     validateSchema({ schemaName: "code-review-decision", file: decisionFile, data: decision, projectRoot: run.workspace_root, ddFlowHome: context.ddFlowHome, runId: run.id, runRoot: home });
     const cycle = reviewContext.cycle ?? "initial";
     const reviewers = reviewerWorks(context, project.id, run.id, cycle);
@@ -158,7 +191,8 @@ export async function finishVnextCodeReview(context, input) {
         const checkRefsByFinding = validateRepairChecks(context, { projectId: project.id, runId: run.id, decision: canonical.decision });
         let repairs = reviewRepairWorks(context, project.id, run.id, root, cycle);
         const frozenShaFile = path.join(root, ".decision-sha256");
-        if (!reviewContext.accepted_decision && fs.existsSync(frozenShaFile) && fs.readFileSync(frozenShaFile, "utf8").trim() !== sha256File(decisionFile))
+        const decisionHash = sha256Value(input.decisionText ?? JSON.stringify(decision));
+        if (!reviewContext.accepted_decision && fs.existsSync(frozenShaFile) && fs.readFileSync(frozenShaFile, "utf8").trim() !== decisionHash)
             throw new AppError("review_decision_changed", "The accepted CODE-REVIEW decision cannot change during repair", 2, { decision_file: decisionFile });
         const fixIds = canonical.fix_ids;
         if (fixIds.length && repairs.length === 0) {
@@ -168,7 +202,7 @@ export async function finishVnextCodeReview(context, input) {
             fs.writeFileSync(temporary, `${JSON.stringify({ ...reviewContext, accepted_decision: decision }, null, 2)}\n`);
             fs.renameSync(temporary, contextFile);
             const repair = addVnextCodeReviewRepair(context, { projectRoot, runId: run.id, findingIds: fixIds, checkRefsByFinding, decisionReasonsByFinding: Object.fromEntries(canonical.decision.findings.map((item) => [item.finding_ref, item.reason])), objective: `Resolve accepted CODE-REVIEW findings: ${fixIds.join(", ")}` });
-            return { ok: true, run_id: run.id, stage, outcome: "repair_required", repair, instruction: "Run the returned repair Work in one fresh child session. When it completes, invoke next.finish_command; this review cycle uses the decision already accepted by the runtime.", next: { finish_command: finishCommand(context, run.id, projectRoot, decisionFile) } };
+            return { ok: true, run_id: run.id, stage, outcome: "repair_required", repair, instruction: "The repair Work is already registered: do not invoke its start_command in this coordinator Session. End this Turn so the controller can launch it in a fresh child Session. When it completes, invoke next.finish_command; this review cycle uses the decision already accepted by the runtime.", next: { finish_command: finishCommand(context, run.id, projectRoot, decisionFile) } };
         }
         repairs = reviewRepairWorks(context, project.id, run.id, root, cycle);
         const incompleteRepairs = repairs.filter((work) => work.status !== "completed");
@@ -226,14 +260,29 @@ export async function finishVnextCodeReview(context, input) {
     });
     return { ok: true, run_id: run.id, stage, outcome, report_path: path.join(root, "stage-report.json"), next_action: nextAction, ...(mergeRequest ? { merge_request: mergeRequest, next: { kind: "start_stage", stage: "merge", command: managedLifecycleCommand(context, `${flowCommand(context)} stage start ${run.id} --stage merge --project-root ${JSON.stringify(projectRoot)} --json --progress-jsonl`) } } : {}) };
 }
-export function readCodeReviewDecision(file, accepted, explicit = false) {
+export function readCodeReviewDecision(file, accepted, explicit = false, prepared) {
     if (!accepted)
-        return readJson(file);
-    if (explicit && fs.existsSync(file) && JSON.stringify(readJson(file)) !== JSON.stringify(accepted)) {
+        return prepared ?? prepareJsonFile(file, "CODE-REVIEW decision").value;
+    if ((prepared !== undefined || (explicit && fs.existsSync(file))) && JSON.stringify(prepared ?? prepareJsonFile(file, "CODE-REVIEW decision").value) !== JSON.stringify(accepted)) {
         throw new AppError("review_decision_changed", "This review cycle already accepted a different decision", 2, { decision_file: file });
     }
     return accepted;
 }
+function disabledReviewDecision() {
+    return { schema_id: "dd-flow/code-review-decision@3", summary: "CODE-REVIEW is disabled by RUN configuration.", findings: [] };
+}
+/** Retained decisions remain authoritative after their caller file is gone. */
+export function prepareCodeReviewDecision(runRoot, file) {
+    const root = path.join(runRoot, "06-code-review");
+    const context = readJson(path.join(root, "review-context.json"));
+    const source = path.resolve(file ?? path.join(root, "decision.json"));
+    if (context.accepted_decision && !fs.existsSync(source))
+        return { value: context.accepted_decision };
+    if (context.mode === "off" && !file && !fs.existsSync(source))
+        return { value: disabledReviewDecision() };
+    const prepared = prepareJsonFile(source, "CODE-REVIEW decision");
+    return { value: readCodeReviewDecision(source, context.accepted_decision, Boolean(file), prepared.value), text: prepared.text };
+}
 export function reviewGroups(home) {
     const expected = new Set(baselineAspects);
     const declared = [];
@@ -277,7 +326,7 @@ export function assertCodeReviewCoverage(groups, reviewers) {
         throw new AppError("reviewer_coverage_invalid", "CODE-REVIEW requires every expected reviewer group", 2, { missing_groups: missing });
 }
 export function reviewerTask(home, group) { return `Read-only independent CODE review for ${group.key}. Assess every assigned aspect exactly once: ${group.aspect_ids.join(", ")}. Read the accepted PLAN, ${path.join(home, "05-code", "stage-report.json")}, and any files needed under the bounded CODE evidence root ${path.join(home, "05-code")}. Verify that universal and exclusive constraints (only, any, all, never, whole) and stated exceptions were not narrowed. For every changed mutation guarded by membership, ownership, authorization or parent lifecycle state, trace the decision to the write boundary: the predicate must remain in the write statement or the guard and write must share one explicit transaction with the needed lock. A separate earlier read is not proof of current authority or lifecycle state; report a material finding when this invariant is broken. Evidence closes a claim only when it exercises the named failure mechanism; a sequential negative test does not prove a concurrency race, and proof limits cannot waive an accepted obligation. Report only material, evidenced defects: a violated obligation or rule, direct evidence, impact, and minimum required outcome. Do not report taste, cosmetics, or untargeted refactoring. Use local finding ids FIND-001, FIND-002, and so on; dd-flow adds the Work-qualified canonical reference. Return dd-flow/code-review-result@1.`; }
-function orchestratorPrompt(context, input) { const template = read(path.join(input.run.workspace_root, ".memory-bank", "dd-flow", "vnext", "code-review.md")); const decision = path.join(input.root, "decision.json"); const checks = acceptedCodeChecks(context, input.run.project_id, input.run.id).map(({ id, purpose }) => ({ id, purpose })); return ["<stage_identity>", `- RUN: ${input.run.id}`, `- root Work: ${input.rootWork.work_id}`, `- stage: ${stage}`, `- mode: ${input.mode}`, "</stage_identity>", "", "<trusted_runtime_context>", `- project root: ${input.projectRoot}`, `- immutable write workspace: ${input.run.workspace_root}`, `- stage workspace: ${input.root}`, `- bounded CODE evidence root: ${path.join(input.run.run_root, "05-code")}`, "CODE is already semantically verified and all declared checks passed. Do not redo CODE verification; conduct independent quality review.", "</trusted_runtime_context>", "", "<review_groups>", ...input.groups.map((group) => `- ${group.key}: ${group.aspect_ids.join(", ")}`), "</review_groups>", "", "<execution_commands>", "Each reviewer Work must run in one fresh child session. The coordinator must never claim a reviewer Work itself. Start each ready Work with its exact start_command from the work graph; it receives the task and result schema. Reviewers are read-only and must not create subagents. Do not interrupt a quiet worker.", `Ready reviewer Works: ${flowCommand(context)} work ls --run ${input.run.id} --ready --project-root ${JSON.stringify(input.projectRoot)} --json`, `Finish only after every reviewer Work settles and you have written ${decision}: ${finishCommand(context, input.run.id, input.projectRoot, decision)}`, "Reviewer results use local FIND-NNN ids. Classify them by the canonical WRK-.../FIND-NNN finding_ref returned by dd-flow. Fix P0/P1. Fix bounded safe P2 by default; defer only a legitimate P2 with a named DEF. P3 is an observation or a reasoned rejection, not automatic repair/DEF. For every disposition fix, check_refs is mandatory: choose the one or more causal checks from the accepted list below that the repair must rerun. Do not guess a CHK id or copy every check. The first successful Finish freezes this decision and creates one repair Work when needed. Run it, then call the returned next.finish_command; do not reuse an earlier invocation-id. Review is not repeated.", "If the post-repair aggregate gate fails, do not stop after `code_review_gate_failed`: that rejected finish does not create a repair Work. In the same coordinator Turn, use the returned repair command with the failed receipt, a relevant completed origin Work ID, and a concise repair objective; then stop so the runner can dispatch the new repair. Do not edit invisibly in the root orchestrator.", `Accepted repair checks: ${JSON.stringify(checks)}`, "```json", JSON.stringify({ schema_id: "dd-flow/code-review-decision@3", summary: "Evidence-backed conclusion.", findings: [{ finding_ref: "WRK-001-review/FIND-001", disposition: "fix | defer | reject | duplicate", reason: "Why this classification is correct.", check_refs: ["CHK-CAUSAL-CHECK only when disposition is fix"], def_id: "DEF-0001 only for an allowed P2 deferral", duplicate_of: "canonical finding_ref only for duplicate" }] }, null, 2), "```", "</execution_commands>", "", "<stage_instructions>", template, "</stage_instructions>", ""].join("\n"); }
+function orchestratorPrompt(context, input) { const { template, checks } = input; const decision = path.join(input.root, "decision.json"); return ["<stage_identity>", `- RUN: ${input.run.id}`, `- root Work: ${input.rootWork.work_id}`, `- stage: ${stage}`, `- mode: ${input.mode}`, "</stage_identity>", "", "<trusted_runtime_context>", `- project root: ${input.projectRoot}`, `- immutable write workspace: ${input.run.workspace_root}`, `- stage workspace: ${input.root}`, `- bounded CODE evidence root: ${path.join(input.run.run_root, "05-code")}`, "CODE is already semantically verified and all declared checks passed. Do not redo CODE verification; conduct independent quality review.", "</trusted_runtime_context>", "", "<review_groups>", ...input.groups.map((group) => `- ${group.key}: ${group.aspect_ids.join(", ")}`), "</review_groups>", "", "<execution_commands>", "Do not choose a provider delegation tool from this stage prompt. At the Work-graph boundary, return immediately; the shared controller supplies the selected adapter's native tool, exact parameters, child task, and wait contract. Each reviewer Work must run in one fresh child session. The coordinator must never invoke a Work start_command itself: a child runs its exact start_command after native delegation. Reviewers are read-only and must not create subagents. Do not interrupt a quiet worker.", `Ready reviewer Works: ${flowCommand(context)} work ls --run ${input.run.id} --ready --project-root ${JSON.stringify(input.projectRoot)} --json`, `Write the decision to this exact absolute path, not a relative look-alike: ${decision}`, `Finish only after every reviewer Work settles and that exact file exists: ${finishCommand(context, input.run.id, input.projectRoot, decision)}`, "Reviewer results use local FIND-NNN ids. Classify them by the canonical WRK-.../FIND-NNN finding_ref returned by dd-flow. Fix P0/P1. Fix bounded safe P2 by default; defer only a legitimate P2 with a named DEF. P3 is an observation or a reasoned rejection, not automatic repair/DEF. For every disposition fix, check_refs is mandatory: choose the one or more causal checks from the accepted list below that the repair must rerun. Do not guess a CHK id or copy every check. The first successful Finish freezes this decision and creates one repair Work when needed. Do not invoke that Work's start_command from the coordinator Session: end this Turn so the controller can launch a fresh child, then call the returned next.finish_command after it completes. Internal invocation IDs are runtime-owned and must not be copied or reused. Review is not repeated.", "If the post-repair aggregate gate fails, do not stop after `code_review_gate_failed`: that rejected finish does not create a repair Work. In the same coordinator Turn, use the returned repair command with the failed receipt, a relevant completed origin Work ID, and a concise repair objective; then end the Turn so the runner can dispatch the new repair. The repair command creates Work only; do not invoke its start_command in the coordinator Session. Do not edit invisibly in the root orchestrator.", `Accepted repair checks: ${JSON.stringify(checks)}`, "```json", JSON.stringify({ schema_id: "dd-flow/code-review-decision@3", summary: "Evidence-backed conclusion.", findings: [{ finding_ref: "WRK-001-review/FIND-001", disposition: "fix | defer | reject | duplicate", reason: "Why this classification is correct.", check_refs: ["CHK-CAUSAL-CHECK only when disposition is fix"], def_id: "DEF-0001 only for an allowed P2 deferral", duplicate_of: "canonical finding_ref only for duplicate" }] }, null, 2), "```", "</execution_commands>", "", "<stage_instructions>", template, "</stage_instructions>", ""].join("\n"); }
 function canonicalReviewEvidence(decision, reviewers) {
     const known = new Set(canonicalCodeFindings(reviewers).map((item) => item.finding_ref));
     const items = new Map(decision.findings.map((item) => [item.finding_ref, item]));
@@ -405,6 +454,7 @@ function effectiveMode(home, run) { const index = JSON.parse(run.index_json); if
 function executionStopTarget(run) { return JSON.parse(run.index_json).execution_profile?.settings?.stop_target ?? "code_review_completed"; }
 function changedPaths(workspaceRoot) { return workspaceChangedPaths(workspaceRoot); }
 function sha256File(file) { return crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex"); }
+function sha256Value(value) { return crypto.createHash("sha256").update(value).digest("hex"); }
 function stageStatus(run, name) { try {
     return JSON.parse(run.index_json).stage_runs?.find((item) => item.stage === name)?.status ?? null;
 }

package/dist/services/vnext-code.js

@@ -1,5 +1,4 @@
 import { managedLifecycleCommand } from "./lifecycle-invocations.js";
-import crypto from "node:crypto";
 import { runWorkspaceBootstrap } from "./workspace-bootstrap.js";
 import fs from "node:fs";
 import path from "node:path";
@@ -7,20 +6,21 @@ import { AppError } from "../shared/errors.js";
 import { resolveProjectRoot } from "../storage/paths.js";
 import { aggregateCheckDeclarations, effectiveCheckDeclarations, finalCodeCheckDeclarations, runCodeChecks, validateFailedCheckRetry, workspaceChangedPaths } from "./code-checks.js";
 import { requireProjectByRoot } from "./projects.js";
-import { appendFlowRunTimelineEvent, advanceFlowRun, attachFlowRunStage, completeFlowRunStage, completeFlowRun, withStageSettlement, getFlowRunVariables, gitFacts } from "./runs.js";
+import { appendFlowRunTimelineEvent, advanceFlowRun, attachFlowRunStage, prepareFlowRunStageAttachment, completeFlowRunStage, completeFlowRun, withStageSettlement, getFlowRunVariables, gitFacts } from "./runs.js";
 import { validateSchema } from "./schema-validation.js";
 import { flowCommand } from "./stage-pause.js";
 import { validateVnextCodeHandoff } from "./vnext-plan.js";
 import { requireVnextWorkspaceRoute } from "./vnext-workspace-policy.js";
 import { readVnextSpecifyResult } from "./vnext-specify.js";
-import { addWorkBatch, bindStageCoordinatorWork, codeWorkGraph, finishStageCoordinatorWork, refreshRunWorkProjection, validateWorkBatchFile, workStartCommand } from "./work-registry.js";
+import { addWorkBatch, prepareWorkBatch, bindStageCoordinatorWork, codeWorkGraph, finishStageCoordinatorWork, refreshRunWorkProjection, validateWorkBatchFile, workStartCommand } from "./work-registry.js";
 import { vnextStageDirectory } from "../domain/stage-catalog.js";
 import { writeStageReport } from "./stage-report-renderer.js";
 import { prepareVnextMergeRequest } from "./vnext-merge.js";
 import { assertStageStartHookEvent } from "./hooks.js";
-import { applyExternalStageContext } from "./stage-context.js";
+import { applyExternalStageContext, prepareExternalStageContext } from "./stage-context.js";
 import { readFanoutDescriptor, writeFanoutDescriptor } from "./vnext-fanout.js";
 import { assertRunMutationAllowed } from "./run-recovery.js";
+import { prepareJsonSchema, prepareOutputFile } from "../cli/input-preparation.js";
 const stage = "code";
 const stageDir = vnextStageDirectory("code");
 /** A controller prepares slow, deterministic project tooling before it asks an
@@ -39,25 +39,28 @@ export async function prepareVnextCodeWorkspace(context, input) {
     fs.mkdirSync(root, { recursive: true });
     return ensureCodeWorkspaceReady(context, project.id, run, root, [], input.progress, { force: input.stage !== "code-review" });
 }
-export async function startVnextCode(context, input) {
+export function prepareVnextCodeStart(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const project = requireProjectByRoot(context, projectRoot);
     const run = requireRun(context, project.id, input.runId);
-    assertStageStartHookEvent(context, { projectId: project.id, eventKey: input.hookEventId, runId: run.id, stage, projectRoot, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
+    assertRunMutationAllowed(context, project.id, run.id);
     const home = requireHome(run);
     requireVnextWorkspaceRoute({ projectRoot, runId: input.runId, runHome: home, workspaceRoot: run.workspace_root, stage });
     const existingRoot = path.join(home, stageDir);
     const existingPrompt = path.join(existingRoot, "stage-prompt.md");
     const existingStage = stageStatus(run, stage);
     const sourceRepairAttempt = isMergeSourceRepairAttempt(run);
+    const rootWork = requireRootWork(context, project.id, input.runId);
+    if (input.externalContext)
+        prepareExternalStageContext({ stageRoot: existingRoot, loaded: input.externalContext });
+    prepareOutputFile(existingPrompt);
+    prepareOutputFile(path.join(existingRoot, "fanout.json"));
+    const common = { projectRoot, project, run, home, root: existingRoot, promptPath: existingPrompt, rootWork, sourceRepairAttempt };
     if (existingStage && fs.existsSync(existingPrompt)) {
-        const externalContext = applyExternalStageContext({ stageRoot: existingRoot, promptPath: existingPrompt, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
-        const prompt = fs.readFileSync(existingPrompt, "utf8");
-        const rootWork = requireRootWork(context, project.id, input.runId);
-        bindStageCoordinatorWork(context, { workId: rootWork.work_id, hookEventId: input.hookEventId, stage, promptPath: existingPrompt, resultPath: path.join(existingRoot, "stage-report.json"), ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
-        const orchestration = readFanoutDescriptor(existingRoot) ?? writeFanoutDescriptor(existingRoot, { stage, parent_work_id: rootWork.work_id, dispatch: "none", capacity_required: true });
-        return { ok: true, resumed: true, run_id: run.id, stage, stage_status: existingStage, prompt_path: existingPrompt, worker_prompt_markdown: prompt, ...(externalContext ? { external_context: externalContext } : {}), orchestration, graph: codeWorkGraph(context, project.id, run.id), next: { refresh_graph_command: `${flowCommand(context)} work ls --run ${run.id} --ready --project-root ${JSON.stringify(projectRoot)} --json`, finish_command: finishCommand(context, input.runId, projectRoot, path.join(existingRoot, "code-verification.json")) } };
+        return { ...common, resumed: true, existingStage, prompt: fs.readFileSync(existingPrompt, "utf8"), orchestration: readFanoutDescriptor(existingRoot) };
     }
+    if (!sourceRepairAttempt)
+        prepareFlowRunStageAttachment(context, { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@1" });
     const batch = path.join(home, "03-plan", "code-work-batch.json");
     const handoffFailures = validateVnextCodeHandoff(context, {
         projectRoot,
@@ -77,12 +80,25 @@ export async function startVnextCode(context, input) {
         runRoot: home
     });
     validateWorkBatchFile(batch);
-    const root = path.join(home, stageDir);
+    const template = fs.readFileSync(path.join(run.workspace_root, ".memory-bank", "dd-flow", "vnext", "code.md"), "utf8");
+    const variables = getFlowRunVariables(context, { projectRoot, runId: run.id });
+    return { ...common, resumed: false, template, capacity: variables.variables?.["runtime.subagent.available_slots"] };
+}
+export async function startVnextCode(context, input, prepared = prepareVnextCodeStart(context, input)) {
+    const { projectRoot, project, run, root, promptPath, rootWork, sourceRepairAttempt } = prepared;
+    assertRunMutationAllowed(context, project.id, run.id);
+    assertStageStartHookEvent(context, { projectId: project.id, eventKey: input.hookEventId, runId: run.id, stage, projectRoot, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
+    if (prepared.resumed) {
+        const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
+        bindStageCoordinatorWork(context, { workId: rootWork.work_id, hookEventId: input.hookEventId, stage, promptPath, resultPath: path.join(root, "stage-report.json"), ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
+        const orchestration = prepared.orchestration ?? writeFanoutDescriptor(root, { stage, parent_work_id: rootWork.work_id, dispatch: "none", capacity_required: true });
+        return { ok: true, resumed: true, run_id: run.id, stage, stage_status: prepared.existingStage, prompt_path: promptPath, worker_prompt_markdown: fs.readFileSync(promptPath, "utf8"), ...(externalContext ? { external_context: externalContext } : {}), orchestration, graph: codeWorkGraph(context, project.id, run.id), next: { refresh_graph_command: `${flowCommand(context)} work ls --run ${run.id} --ready --project-root ${JSON.stringify(projectRoot)} --json`, finish_command: finishCommand(context, input.runId, projectRoot, path.join(root, "code-verification.json")) } };
+    }
     fs.mkdirSync(root, { recursive: true });
     const readiness = await ensureCodeWorkspaceReady(context, project.id, run, root, [], input.progress);
-    const rootWork = requireRootWork(context, project.id, input.runId);
-    const promptPath = path.join(root, "stage-prompt.md");
-    const prompt = coordinatorPrompt(context, { projectRoot, run, root, rootWork, readiness });
+    // Graph rendering may issue managed child commands; it belongs to execution.
+    const graph = codeWorkGraph(context, project.id, run.id);
+    const prompt = coordinatorPrompt(context, { projectRoot, run, root, rootWork, readiness, template: prepared.template, capacity: prepared.capacity, graph });
     fs.writeFileSync(promptPath, prompt);
     const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
     const binding = bindStageCoordinatorWork(context, {
@@ -103,7 +119,6 @@ export async function startVnextCode(context, input) {
             dataSchemaId: "dd-flow/stage-report@1"
         });
     }
-    const graph = codeWorkGraph(context, project.id, input.runId);
     const orchestration = writeFanoutDescriptor(root, { stage, parent_work_id: rootWork.work_id, dispatch: "none", capacity_required: true });
     appendFlowRunTimelineEvent(context, project.id, input.runId, { type: "code_started", work_id: rootWork.work_id, graph });
     return {
@@ -159,7 +174,8 @@ export async function finishVnextCode(context, input) {
         throw new AppError("obligation_coverage_incomplete", "CODE graph does not cover every accepted obligation", 2, { missing });
     }
     // Reject a malformed semantic receipt before running the expensive gate.
-    const verification = verificationForFinish(context, { file: input.verificationFile, projectRoot: run.workspace_root, runId: run.id, runRoot: home });
+    const verification = input.verification ?? verificationForFinish(context, { file: input.verificationFile, projectRoot: run.workspace_root, runId: run.id, runRoot: home });
+    validateSchema({ schemaName: "code-verification", file: input.verificationFile, data: verification, projectRoot: run.workspace_root, ddFlowHome: context.ddFlowHome, runId: run.id, runRoot: home });
     if (verification.verdict === "blocked") {
         return { ok: true, run_id: run.id, stage, outcome: "blocked", verification, instruction: "CODE remains running. Resolve the stated external or user-input blocker in this same coordinator session, update code-verification.json, then invoke this same stage finish command again." };
     }
@@ -173,9 +189,10 @@ export async function finishVnextCode(context, input) {
             originWorkIds: works.filter((work) => work.status === "completed").map((work) => work.work_id),
             semanticUnresolved: verification.unresolved.length ? verification.unresolved : [verification.summary],
             verificationPath: input.verificationFile,
+            verification,
             objective: verification.summary
         });
-        return { ok: true, run_id: run.id, stage, outcome: "repair_required", verification, repair, instruction: "The semantic verification is not accepted. Run the returned repair Work, then update code-verification.json and invoke this same stage finish command again." };
+        return { ok: true, run_id: run.id, stage, outcome: "repair_required", verification, repair, instruction: "The semantic verification is not accepted. The repair Work is already registered: do not invoke its start_command in this coordinator Session. End this Turn so the controller can launch it in a fresh child Session. After that Work completes, update code-verification.json and invoke this same stage finish command again." };
     }
     const checks = finalCodeCheckDeclarations(run.workspace_root, works.flatMap((work) => packet(work)?.checks ?? []));
     if (input.retryCheckId) {
@@ -292,21 +309,41 @@ export async function finishVnextCode(context, input) {
         ...(next === "start_code_review" ? { next: { kind: "start_stage", stage: "code-review", command: managedLifecycleCommand(context, `${flowCommand(context)} stage start ${run.id} --stage code-review --project-root ${JSON.stringify(projectRoot)} --json`) } } : next === "start_merge" ? { merge_request: mergeRequest, next: { kind: "start_stage", stage: "merge", command: managedLifecycleCommand(context, `${flowCommand(context)} stage start ${run.id} --stage merge --project-root ${JSON.stringify(projectRoot)} --json --progress-jsonl`) } } : {})
     };
 }
-export function addVnextCodeRepair(context, input) {
+export function prepareVnextCodeRepair(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const project = requireProjectByRoot(context, projectRoot);
     const run = requireRun(context, project.id, input.runId);
     const home = requireHome(run);
-    if (!input.objective.trim())
-        throw new AppError("validation", "Repair objective must not be empty", 2);
     if (input.reviewCycle) {
         const previous = codeWorks(context, project.id, run.id).find((work) => packet(work)?.review_cycle === input.reviewCycle);
         if (previous)
-            return { ok: true, run_id: run.id, repair_work_id: previous.work_id, start_command: workStartCommand(context, previous), reused: true };
+            return { kind: "replay", project, run, previous };
     }
+    if (typeof input.objective !== "string" || !input.objective.trim())
+        throw new AppError("validation", "Repair objective must not be empty", 2);
+    if (input.semanticUnresolved !== undefined && (!Array.isArray(input.semanticUnresolved) || input.semanticUnresolved.some(value => typeof value !== "string" || !value.trim())))
+        throw new AppError("validation", "Semantic unresolved items must be nonempty strings", 2);
+    if (input.reviewFindings !== undefined && !Array.isArray(input.reviewFindings))
+        throw new AppError("validation", "Review findings must be an array", 2);
+    if (input.reviewChecks !== undefined && !Array.isArray(input.reviewChecks))
+        throw new AppError("validation", "Review checks must be an array", 2);
+    if (!Array.isArray(input.originWorkIds) || !input.originWorkIds.length || input.originWorkIds.some(id => typeof id !== "string" || !id.trim()))
+        throw new AppError("validation", "Repair requires at least one origin Work", 2);
     if (!input.checkReceiptId && !input.reviewFindings?.length && !input.semanticUnresolved?.length) {
         throw new AppError("validation", "Repair needs failed check evidence, a CODE-REVIEW finding, or an unresolved CODE verification", 2);
     }
+    if ([Boolean(input.checkReceiptId), Boolean(input.reviewFindings?.length), Boolean(input.semanticUnresolved?.length)].filter(Boolean).length !== 1)
+        throw new AppError("validation", "Repair requires exactly one evidence source", 2);
+    if (input.semanticUnresolved?.length) {
+        if (!input.verificationPath)
+            throw new AppError("usage", "Semantic repair requires a verification file", 2);
+        const verification = input.verification ?? readVerification(context, { file: input.verificationPath, projectRoot: run.workspace_root, runId: run.id, runRoot: home });
+        if (input.verification !== undefined)
+            validateSchema({ schemaName: "code-verification", file: input.verificationPath, data: verification, projectRoot: run.workspace_root, ddFlowHome: context.ddFlowHome, runId: run.id, runRoot: home });
+        const unresolved = verification.unresolved.length ? verification.unresolved : [verification.summary];
+        if (verification.verdict !== "needs_repair" || input.semanticUnresolved.some(value => !unresolved.includes(value)))
+            throw new AppError("validation", "Semantic repair must reference unresolved items from a needs_repair verification", 2);
+    }
     const receipt = input.checkReceiptId ? context.db.get("SELECT id, declaration_id, run_id, command, status, receipt_path, stdout_path, stderr_path FROM check_receipts WHERE project_id = ? AND id = ?", [
         project.id,
         input.checkReceiptId
@@ -387,23 +424,23 @@ export function addVnextCodeRepair(context, input) {
         result_schema: "dd-flow/code-work-result@3",
         ...(input.reviewCycle ? { review_cycle: input.reviewCycle } : {})
     };
-    const file = path.join(home, stageDir, `.repair-${crypto.randomUUID()}.json`);
-    fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.writeFileSync(file, `${JSON.stringify({ works: [repair] }, null, 2)}\n`);
-    let registered;
-    try {
-        registered = addWorkBatch(context, { parentWorkId: requireRootWork(context, project.id, run.id).work_id, file });
-    }
-    finally {
-        fs.rmSync(file, { force: true });
-    }
+    const parentWorkId = requireRootWork(context, project.id, run.id).work_id;
+    const items = prepareWorkBatch(context, { parentWorkId, value: { works: [repair] } });
+    return { kind: "create", project, run, input, parentWorkId, items, key, receipt };
+}
+export function addVnextCodeRepair(context, input, prepared = prepareVnextCodeRepair(context, input)) {
+    const { project, run } = prepared;
+    if (prepared.kind === "replay")
+        return { ok: true, run_id: run.id, repair_work_id: prepared.previous.work_id, start_command: workStartCommand(context, prepared.previous), reused: true };
+    const { parentWorkId, items, key, receipt } = prepared;
+    const registered = addWorkBatch(context, { parentWorkId, prepared: items });
     const id = String(registered.work_ids[key]);
     const work = context.db.get("SELECT * FROM works WHERE work_id = ?", [id]);
     appendFlowRunTimelineEvent(context, project.id, run.id, {
         type: "code_repair_created",
         work_id: id,
-        origin_work_ids: input.originWorkIds,
-        ...(receipt ? { check_receipt_id: receipt.id } : input.reviewFindings?.length ? { review_finding_ids: input.reviewFindings.map((finding) => finding.finding_ref) } : { semantic_unresolved: input.semanticUnresolved })
+        origin_work_ids: prepared.input.originWorkIds,
+        ...(receipt ? { check_receipt_id: receipt.id } : prepared.input.reviewFindings?.length ? { review_finding_ids: prepared.input.reviewFindings.map((finding) => finding.finding_ref) } : { semantic_unresolved: prepared.input.semanticUnresolved })
     });
     refreshRunWorkProjection(context, project.id, run.id);
     return { ok: true, run_id: run.id, repair_work_id: id, start_command: workStartCommand(context, work) };
@@ -439,10 +476,7 @@ function receiptRepairPaths(workspaceRoot, receipt) {
     return [...paths].sort();
 }
 function coordinatorPrompt(context, input) {
-    const graph = codeWorkGraph(context, input.run.project_id, input.run.id);
-    const variables = getFlowRunVariables(context, { projectRoot: input.projectRoot, runId: input.run.id });
-    const capacity = variables.variables?.["runtime.subagent.available_slots"];
-    const template = fs.readFileSync(path.join(input.run.workspace_root, ".memory-bank", "dd-flow", "vnext", "code.md"), "utf8");
+    const { graph, capacity, template } = input;
     return [
         "<stage_identity>",
         `- RUN: ${input.run.id}`,
@@ -464,8 +498,8 @@ function coordinatorPrompt(context, input) {
         "</code_graph>",
         "",
         "<execution_commands>",
-        "Launch only entries listed in graph.ready. Use at most the known available slot count. Every registered CODE Work runs in a fresh child Session, including a serial dependency chain; the coordinator owns dispatch and the stage conclusion, not implementation Work. Every child starts with its exact start_command and receives its complete packet from dd-flow. After a Work finishes, use the graph returned by work finish to launch newly ready Work. To refresh the parent graph yourself use the exact command: " + `${flowCommand(context)} work ls --run ${input.run.id} --ready --project-root ${JSON.stringify(input.projectRoot)} --json`,
-        "A quiet child is still running until the harness reports its turn completed, failed, cancelled or explicitly needs attention. An elapsed nominal wait, silence, or no new artifact is not an unresponsive-worker failure. Never interrupt, replace, relaunch, or stage-block a still-running child for that reason, even if an external controller asks. Long work finish and stage finish commands emit check progress on stderr. After you issue the exact CODE stage finish command, wait for that same command to return once: a completed command with a non-zero exit and structured `code_gate_failed` output is its terminal result, not a reason to keep waiting. Read that returned error and run its repair command; do not inspect its PID, start a second finish command, or infer failure from quiet output. Close a disposable child only after its Work is accepted or explicitly failed/cancelled and the harness reports the turn settled.",
+        "Do not choose a provider delegation tool from this stage prompt. At each work_fanout boundary, stop at the Work-graph boundary; the shared controller supplies the selected adapter's native tool, exact parameters, child task, and wait contract. It launches only entries listed in graph.ready and uses at most the qualified capacity. Every registered CODE Work runs in a fresh child Session, including a serial dependency chain. The coordinator launches those children only through the controller-supplied native delegation instruction; it must never invoke a Work start_command itself. Each child receives its complete packet from dd-flow and runs its own exact start_command. After a Work finishes, the controller uses the graph returned by work finish to launch newly ready Work. To refresh the parent graph yourself use the exact command: " + `${flowCommand(context)} work ls --run ${input.run.id} --ready --project-root ${JSON.stringify(input.projectRoot)} --json`,
+        "A quiet child is still running until the harness reports its turn completed, failed, cancelled or explicitly needs attention. An elapsed nominal wait, silence, or no new artifact is not an unresponsive-worker failure. Never interrupt, replace, relaunch, or stage-block a still-running child for that reason, even if an external controller asks. Long work finish and stage finish commands emit check progress on stderr. After you issue the exact CODE stage finish command, wait for that same command to return once: a completed command with a non-zero exit and structured `code_gate_failed` output is its terminal result, not a reason to keep waiting. Its repair_command only creates the repair Work; use it with the required origin Work IDs, then end the Turn. Do not invoke that new Work's start_command from the coordinator Session, inspect its PID, start a second finish command, or infer failure from quiet output. Close a disposable child only after its Work is accepted or explicitly failed/cancelled and the harness reports the turn settled.",
         `A repairable engine, harness, or environment failure is not a user question. Record it without finishing CODE: ${flowCommand(context)} stage block ${input.run.id} --stage code --work ${input.rootWork.work_id} --kind <engine|harness|environment> --code <stable-code> --summary-stdin --retryable --project-root ${JSON.stringify(input.projectRoot)} --json. Repair it externally, then run the exact unblock_command returned by dd-flow and continue this same stage.`,
         `When every CODE and repair Work is completed, write ${path.join(input.root, "code-verification.json")} using the exact contract below. Mark passed only when all accepted requirements and current-gate acceptance criteria are implemented or explicitly evidenced; list every remaining issue in unresolved. Every evidence_refs item must already exist as a relative workspace path or run://${input.run.id}/ path. Do not claim a browser or other check receipt that was not retained. Then finish: ${finishCommand(context, input.run.id, input.projectRoot, path.join(input.root, "code-verification.json"))}`,
         "If the aggregate gate fails, do not stop after `code_gate_failed`: that rejected finish does not create a repair Work. In the same coordinator Turn, use its returned repair command with the relevant completed origin Work IDs and a concise repair objective, then stop so the runner can dispatch the newly declared repair. Do not edit invisibly in the root orchestrator.",
@@ -658,10 +692,9 @@ export function finishCommand(context, runId, projectRoot, verificationFile, ret
     return managedLifecycleCommand(context, `${flowCommand(context)} stage finish ${runId} --stage code --verification-file ${JSON.stringify(verificationFile)} --project-root ${JSON.stringify(projectRoot)} --json --progress-jsonl${retry}`);
 }
 function readVerification(context, input) {
-    const file = path.resolve(input.file);
-    const data = JSON.parse(fs.readFileSync(file, "utf8"));
-    validateSchema({ schemaName: "code-verification", file, data, projectRoot: input.projectRoot, ddFlowHome: context.ddFlowHome, runId: input.runId, runRoot: input.runRoot });
-    return data;
+    return prepareJsonSchema(input.file, "CODE verification", {
+        schemaName: "code-verification", projectRoot: input.projectRoot, ddFlowHome: context.ddFlowHome, runId: input.runId, runRoot: input.runRoot
+    }).value;
 }
 function verificationForFinish(context, input) {
     return readVerification(context, input);

package/dist/services/vnext-fanout.js

@@ -59,8 +59,10 @@ export function getVnextFanoutStatus(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const project = requireProjectByRoot(context, projectRoot);
     const run = context.db.get("SELECT run_root FROM runs WHERE project_id = ? AND id = ?", [project.id, input.runId]);
-    if (!run?.run_root)
-        throw new AppError("not_found", "RUN artifact root is unavailable", 1, { run_id: input.runId });
+    if (!run)
+        throw new AppError("not_found", "RUN is not registered", 1, { run_id: input.runId });
+    if (!run.run_root)
+        throw new AppError("runtime_artifact_missing", "RUN artifact root is unavailable", 1, { run_id: input.runId });
     const stageRoot = path.join(run.run_root, vnextStageDirectory(input.stage));
     const descriptor = readFanoutDescriptor(stageRoot);
     if (!descriptor)
@@ -93,15 +95,10 @@ export function getVnextFanoutStatus(context, input) {
  * Sessions need a provider execution identity: without one we report ambiguity
  * instead of applying a late event to the newest Work attempt. */
 export async function reconcileVnextFanout(context, input) {
+    const value = prepareNativeObservations(input.observations);
     const status = getVnextFanoutStatus(context, input);
     if (!status.orchestration)
         return { ok: true, issues: [], reconciled: [] };
-    const value = input.observations;
-    if (!value || typeof value.harness_id !== "string" || !value.harness_id || typeof value.parent_session_id !== "string" || !Array.isArray(value.children)
-        || value.children.some(child => !child || typeof child.session_id !== "string" || !["running", "unknown", "completed", "failed", "cancelled"].includes(String(child.status))))
-        throw new AppError("usage", "Expected native observations: harness_id, parent_session_id and children[{session_id,status}]", 2);
-    if (new Set(value.children.map(child => child.session_id)).size !== value.children.length)
-        throw new AppError("usage", "Native observations must contain each child Session exactly once", 2);
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const parent = storageSessionId({ harness_id: value.harness_id, session_id: value.parent_session_id });
     const issues = [], reconciled = [];
@@ -157,13 +154,17 @@ export async function reconcileVnextFanout(context, input) {
  * evidence for an earlier Work, while an unbound terminal child is retained
  * as an inconsistency instead of being rediscovered in a later review wave.
  */
-export function observeVnextNativeChildren(context, input) {
-    const value = input.observations;
-    if (!value || typeof value.harness_id !== "string" || !value.harness_id || typeof value.parent_session_id !== "string" || !Array.isArray(value.children)
-        || value.children.some(child => !child || typeof child.session_id !== "string" || !["running", "unknown", "completed", "failed", "cancelled"].includes(String(child.status))))
+export function prepareNativeObservations(observations) {
+    const value = observations;
+    if (!value || typeof value.harness_id !== "string" || !value.harness_id.trim() || typeof value.parent_session_id !== "string" || !value.parent_session_id.trim() || !Array.isArray(value.children)
+        || value.children.some(child => !child || typeof child.session_id !== "string" || !child.session_id.trim() || typeof child.status !== "string" || !["running", "unknown", "completed", "failed", "cancelled"].includes(child.status)))
         throw new AppError("usage", "Expected native observations: harness_id, parent_session_id and children[{session_id,status}]", 2);
     if (new Set(value.children.map(child => child.session_id)).size !== value.children.length)
         throw new AppError("usage", "Native observations must contain each child Session exactly once", 2);
+    return { harness_id: value.harness_id, parent_session_id: value.parent_session_id, children: value.children };
+}
+export function observeVnextNativeChildren(context, input) {
+    const value = prepareNativeObservations(input.observations);
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const parent = storageSessionId({ harness_id: value.harness_id, session_id: value.parent_session_id });
     const issues = [], history = [], pending = [];