@deksden-com/dd-flow-cli 0.9.0-beta.14 → 0.9.0-beta.140

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

@@ -1,24 +1,34 @@
+import { managedLifecycleCommand } from "./lifecycle-invocations.js";
+import { stageLifecycleInstruction } from "../harness-runtime/lib/delegation-instructions.mjs";
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { execFileSync } from "node:child_process";
 import { AppError } from "../shared/errors.js";
+import { assertSourceRepairEligible } from "./check-runner-evidence.js";
 import { resolveProjectRoot } from "../storage/paths.js";
 import { requireProjectByRoot } from "./projects.js";
-import { advanceFlowRun, appendFlowRunTimelineEvent, attachFlowRunStage, completeFlowRun, completeFlowRunStage, freezeFlowRunReviewMode, gitFacts } from "./runs.js";
+import { advanceFlowRun, appendFlowRunTimelineEvent, attachFlowRunStage, completeFlowRun, completeFlowRunStage, prepareFlowRunStageCompletion, freezeFlowRunReviewMode, gitFacts } from "./runs.js";
 import { validateSchema } from "./schema-validation.js";
-import { flowCommand } from "./stage-pause.js";
+import { runtimeCommand, checkRetryArgs } from "./runtime-command.js";
 import { assertStageStartHookEvent } from "./hooks.js";
 import { requireVnextWorkspaceRoute } from "./vnext-workspace-policy.js";
-import { addVnextCodeRepair } from "./vnext-code.js";
-import { finalCodeCheckDeclarations, runCodeChecks, unchangedFinalGateFailures, workspaceFingerprint } from "./code-checks.js";
-import { addWorkBatch, bindStageCoordinatorWork, finishWork, refreshRunWorkProjection } from "./work-registry.js";
+import { addVnextCodeRepair, prepareVnextCodeRepair, registerAggregateCodeRepair, resumeAcceptedCodeStage } from "./vnext-code.js";
+import { finalCodeCheckDeclarations, runCodeChecks, validateFailedCheckRetry, workspaceChangedPaths } from "./code-checks.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 { acceptStageReport, prepareStageReport } from "./stage-report-renderer.js";
+import { prepareRunVerificationMatrix, acceptVerificationMatrix, commitVerificationMatrixStart, resumeVerificationMatrix, verificationMatrixInstruction, latestRunVerificationMatrix, publishVerificationMatrix } from "./verification-matrix.js";
+import { currentStagePrompt, applyExternalStageContext, prepareExternalStageContext } from "./stage-context.js";
 import { readFanoutDescriptor, writeFanoutDescriptor } from "./vnext-fanout.js";
-import { ensureVnextMergeRequest } from "./vnext-merge.js";
+import { stageGraphScope } from "./stage-work-graph.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";
+import { reviewerSourceInputs, reviewerSourceInstruction } from "./review-copy.js";
+import { reviewDefEvidence } from "./review-deferral.js";
+import { stageSuccessor } from "./vnext-contracts.js";
 const stage = "code-review";
 const stageDir = vnextStageDirectory(stage);
 const baselineAspects = ["goal_traceability", "coding_standards_design_review", "verification_evidence_review"];
@@ -26,57 +36,93 @@ 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 } : {}) });
-    requireVnextWorkspaceRoute({ projectRoot, runId: run.id, runHome: home, workspaceRoot: run.workspace_root, stage });
+    assertRunMutationAllowed(context, project.id, run.id);
+    requireVnextWorkspaceRoute(context, { 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)) {
-        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")) } };
-    }
+    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) };
+    const attachment = 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 reviewerInputs = mode.mode === "off" ? [] : reviewerSourceInputs(run.workspace_root, groups.flatMap(group => group.aspect_ids));
+    const batch = { works: groups.map((group, index) => ({ key: `code-review-${index + 1}`, task: `${reviewerTask(home, group)}\n${reviewerSourceInstruction(run.workspace_root, group.aspect_ids)}`, 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));
+    const matrix = mode.mode === "off" ? null : prepareRunVerificationMatrix(context, { projectId: project.id, runId: run.id, stage, role: "input", stageAttempt: attachment.attempt });
+    return { ...common, resumed: false, mode, cycle, codeReportSha256, groups, batch, items, template, checks, matrix, reviewerInputs };
+}
+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) {
+        if (effectiveMode(prepared.home, run).mode !== "off")
+            resumeVerificationMatrix(context, project.id, run.id, stage);
+        const externalContext = applyExternalStageContext({ context, 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 delivered = currentStagePrompt(context, existingPrompt);
+        const orchestration = prepared.orchestration;
+        return { ok: true, resumed: true, run_id: run.id, stage, stage_status: prepared.prior, id: binding.work_session_id, ...delivered, ...(externalContext ? { external_context: externalContext } : {}), ...(orchestration ? { orchestration } : {}), next: { finish_command: finishCommand(context, run.id, projectRoot, path.join(root, "decision.json")) } };
+    }
+    const { mode, cycle, groups, batch, items, template, checks, codeReportSha256 } = prepared;
+    prepareFlowRunStageAttachment(context, { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@1" }, true);
+    const aspectMapChecksums = mode.mode === "off" ? [] : fs.readdirSync(path.join(run.run_root, "03-plan"), { withFileTypes: true })
+        .filter(entry => entry.isDirectory() && fs.existsSync(path.join(run.run_root, "03-plan", entry.name, "aspect-map.json")))
+        .map(entry => ({ path: `03-plan/${entry.name}/aspect-map.json`, sha256: sha256File(path.join(run.run_root, "03-plan", entry.name, "aspect-map.json")) }))
+        .sort((a, b) => a.path.localeCompare(b.path));
     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, workspace_fingerprint: workspaceFingerprint(run.workspace_root), 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", reviewer_inputs: prepared.reviewerInputs, cycle, mode: mode.mode, mode_source: mode.source, mode_reason: mode.reason, ...(mode.mode !== "off" ? { read_only_input: { parent_work_id: rootWork.work_id, version: 3 } } : {}), code_report_sha256: codeReportSha256, review_batch_sha256: sha256Value(`${JSON.stringify(batch, null, 2)}\n`), aspect_map_checksums: aspectMapChecksums }, null, 2)}\n`);
     if (mode.mode === "off") {
-        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(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${stageLifecycleInstruction}\n`;
         fs.writeFileSync(promptPath, prompt);
-        const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
+        const externalContext = applyExternalStageContext({ context, 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 } : {}) });
-        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 attachmentInput = { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@1" };
+        attachFlowRunStage(context, attachmentInput, prepareFlowRunStageAttachment(context, attachmentInput));
+        return { ok: true, run_id: run.id, stage, mode: mode.mode, mode_source: mode.source, id: binding.work_session_id, ...currentStagePrompt(context, promptPath), ...(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 })}\n${stageLifecycleInstruction}\n${verificationMatrixInstruction(prepared.matrix?.metadata ?? null, prepared.home, "reviewing whether current evidence proves the accepted obligations")}\n`;
     fs.writeFileSync(promptPath, prompt);
-    const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
+    const externalContext = applyExternalStageContext({ context, 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 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" });
+    const registered = addWorkBatch(context, { parentWorkId: rootWork.work_id, value: batch, prepared: items, stage, cycle });
+    const orchestration = writeFanoutDescriptor(root, { stage, parent_work_id: rootWork.work_id, dispatch: "none", capacity_required: true, scope: stageGraphScope(context, project.id, run.id, stage) });
+    const attachmentInput = { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@1", inputSha256: sha256Value(JSON.stringify({ batch: sha256File(batchFile), aspect_maps: aspectMapChecksums })) };
+    const attachment = prepareFlowRunStageAttachment(context, attachmentInput);
+    commitVerificationMatrixStart(context, prepared.matrix, () => attachFlowRunStage(context, attachmentInput, attachment));
     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")) } };
+    return { ok: true, run_id: run.id, stage, mode: mode.mode, mode_source: mode.source, id: binding.work_session_id, ...currentStagePrompt(context, promptPath), ...(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);
@@ -100,10 +146,8 @@ export function addVnextCodeReviewRepair(context, input) {
     const unknown = requestedCheckRefs.filter((ref) => !checks.has(ref));
     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)).filter((check) => check.run_at !== "external");
-    if (!reviewChecks.length)
-        throw new AppError("review_repair_executable_check_required", "CODE-REVIEW repair requires at least one executable causal check; external-only evidence cannot validate a repair Work", 2, { finding_ids: input.findingIds, check_refs: requestedCheckRefs });
-    return addVnextCodeRepair(context, {
+    const reviewChecks = requestedCheckRefs.map((ref) => checks.get(ref));
+    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 +155,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);
@@ -119,6 +167,14 @@ export async function finishVnextCodeReview(context, input) {
     const run = requireRun(context, project.id, input.runId);
     const home = requireHome(run);
     const root = path.join(home, stageDir);
+    const generation = assertRunMutationAllowed(context, project.id, run.id);
+    const reportPath = path.join(root, "stage-report.json");
+    if (stageStatus(run, stage) === "done" && fs.existsSync(reportPath)) {
+        const report = readJson(reportPath);
+        const next = report.semantic?.next_action ?? "code_review_completed";
+        resumeAcceptedCodeStage(context, run, projectRoot, stage, report, next);
+        return { ok: true, resumed: true, run_id: run.id, stage, outcome: "accepted", report_path: reportPath, next_action: next };
+    }
     const reviewContext = readJson(path.join(root, "review-context.json"));
     const mode = reviewContext.mode;
     if (!mode)
@@ -128,40 +184,48 @@ export async function finishVnextCodeReview(context, input) {
     const handoffFailures = validateVnextCodeHandoff(context, { projectRoot, workspaceRoot: run.workspace_root, runId: run.id, home });
     if (handoffFailures.length)
         throw new AppError("validation", "CODE-REVIEW handoff no longer matches the accepted PLAN", 2, { errors: handoffFailures });
-    const reportPath = path.join(root, "stage-report.json");
-    if (stageStatus(run, stage) === "done" && fs.existsSync(reportPath)) {
-        const report = readJson(reportPath);
-        return { ok: true, resumed: true, run_id: run.id, stage, outcome: "accepted", report_path: reportPath, next_action: report.semantic?.next_action ?? "code_review_completed" };
-    }
     const rootWork = requireRootWork(context, project.id, run.id);
     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`);
-    validateSchema({ schemaName: "code-review-decision", file: decisionFile, projectRoot: run.workspace_root, ddFlowHome: context.ddFlowHome, runId: run.id, runRoot: home });
-    const decision = readJson(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);
+    const defEvidence = decision.findings.filter(item => item.disposition === "defer").map(item => reviewDefEvidence(run.workspace_root, item.def_id));
     if (mode !== "off") {
+        assertCodeReviewCoverage(reviewGroups(home), reviewers);
         const incomplete = reviewers.filter((work) => work.status !== "completed");
         if (incomplete.length)
             throw new AppError("reviewer_jobs_incomplete", "CODE-REVIEW cannot finish while reviewer Work is unsettled", 2, { works: incomplete.map((work) => ({ work_id: work.work_id, status: work.status })) });
         for (const work of reviewers)
             validateReviewerResult(context, work, run);
         const canonical = reviewDecisionForRepair(decision, reviewers);
+        if (reviewContext.accepted_decision && JSON.stringify(reviewContext.def_evidence ?? []) !== JSON.stringify(defEvidence))
+            throw new AppError("deferral_invalid", "Accepted DEF evidence changed during review repair", 2);
         const checkRefsByFinding = validateRepairChecks(context, { projectId: project.id, runId: run.id, decision: canonical.decision });
         let repairs = reviewRepairWorks(context, project.id, run.id, root, cycle);
-        const decisionSha = sha256File(decisionFile);
         const frozenShaFile = path.join(root, ".decision-sha256");
-        if (fs.existsSync(frozenShaFile) && fs.readFileSync(frozenShaFile, "utf8").trim() !== decisionSha)
+        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) {
+            // Accept the value once. Repairs consume this decision, not a mutable
+            // operator file. Reuse the existing context artifact and review cycle.
+            const contextFile = path.join(root, "review-context.json"), temporary = `${contextFile}.tmp-${crypto.randomUUID()}`;
+            fs.writeFileSync(temporary, `${JSON.stringify({ ...reviewContext, accepted_decision: decision, def_evidence: defEvidence }, 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(", ")}` });
-            fs.writeFileSync(frozenShaFile, `${decisionSha}\n`);
-            return { ok: true, run_id: run.id, stage, outcome: "repair_required", decision_sha256: decisionSha, repair, instruction: "Run the returned repair Work in one fresh child session. When it completes, invoke the same stage finish command again with the unchanged decision file.", next: { finish_command: finishCommand(context, run.id, projectRoot, decisionFile) } };
+            const retained = latestRunVerificationMatrix(context, project.id, run.id, stage, "input");
+            return { ok: true, run_id: run.id, stage, outcome: "repair_required", repair, ...(retained ? { verification_matrix: retained.metadata } : {}), 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.\n${verificationMatrixInstruction(retained?.metadata ?? null, home, "the accepted review decision and repair")}`, 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");
@@ -172,41 +236,92 @@ export async function finishVnextCodeReview(context, input) {
     const outcome = decision.findings.some((item) => item.disposition === "defer") ? "accepted_with_DEF" : "accepted";
     const repairs = reviewRepairWorks(context, project.id, run.id, root, cycle);
     const finalChecks = finalCodeCheckDeclarations(run.workspace_root, codeWorks(context, project.id, run.id).flatMap((work) => { const payload = readJsonString(work.payload_json); return Array.isArray(payload.checks) ? payload.checks : []; }));
-    const unchangedFailures = unchangedFinalGateFailures(context, { projectId: project.id, runId: run.id, workspaceRoot: run.workspace_root, declarations: finalChecks });
-    if (unchangedFailures.length)
-        throw new AppError("code_review_gate_repair_required", "CODE-REVIEW final gate already failed for the unchanged workspace; repair the evidenced failure before retrying", 2, { outcome: "repair_required", retry_after_workspace_change: true, workspace_fingerprint: unchangedFailures[0].workspace_fingerprint, failures: unchangedFailures });
-    const receipts = await runCodeChecks(context, { projectId: project.id, runId: run.id, runHome: home, workspaceRoot: run.workspace_root, artifactDir: stageDir, scope: "aggregate", checks: finalChecks, ...(input.progress ? { progress: input.progress } : {}) });
+    if (input.retryCheckId) {
+        validateFailedCheckRetry(context, { projectId: project.id, runId: run.id, receiptId: input.retryCheckId, declarations: finalChecks, reason: input.retryReason });
+        appendFlowRunTimelineEvent(context, project.id, run.id, { type: "check_retry_requested", check_receipt_id: input.retryCheckId, stage, reason: input.retryReason ?? "operator retry" });
+    }
+    const receipts = await runCodeChecks(context, { projectId: project.id, runId: run.id, runHome: home, workspaceRoot: run.workspace_root, artifactDir: stageDir, scope: "aggregate", checks: finalChecks, ...(input.retryCheckId ? { retryReceiptId: input.retryCheckId, retryReason: input.retryReason } : {}), ...(input.progress ? { progress: input.progress } : {}) });
+    const matrix = prepareRunVerificationMatrix(context, { projectId: project.id, runId: run.id, stage, role: "output", receipts, semanticFile: decisionFile });
     const failed = receipts.filter((receipt) => receipt.status !== "passed");
-    if (failed.length)
+    if (failed.length) {
+        assertSourceRepairEligible(failed);
+        context.db.writeTransaction(() => acceptVerificationMatrix(context, matrix));
+        publishVerificationMatrix(context, matrix);
         throw new AppError("code_review_gate_failed", "CODE-REVIEW repair changed the project but the aggregate gate failed", 2, {
             failures: failed,
             outcome: "repair_required",
             retry_after_workspace_change: true,
             workspace_fingerprint: failed[0].workspace_fingerprint,
-            repair_command: `${flowCommand(context)} work repair add --run ${run.id} --from-check ${failed[0].id} --origin-work <WORK-ID> --task-stdin --project-root ${JSON.stringify(projectRoot)} --json`
+            continuation: registerAggregateCodeRepair(context, { projectRoot, runId: run.id, stage, failures: failed, checks: finalChecks, generation }),
+            ...(matrix ? { verification_matrix: matrix.metadata } : {}),
+            instruction: `Repair Work is already registered. End this Turn so the controller can launch a fresh child; after it finishes, repeat finish with the already accepted review decision. Do not redo review.\n${verificationMatrixInstruction(matrix?.metadata ?? null, home, "the current aggregate failures and repair")}`
         });
+    }
     const stopTarget = executionStopTarget(run);
     const nextAction = stopTarget === "merge_completed" ? "start_merge" : "code_review_completed";
     const now = context.now();
     const startedAt = stageStartedAt(run, now);
-    const report = { schema_id: "dd-flow/stage-report@1", run_id: run.id, stage, generated_at: now, verdict: "done", semantic: { result: `Independent CODE review completed: ${reviewers.length} reviewer Work(s), ${repairs.length} repair Work(s).`, acceptance: ["all_selected_review_groups_completed", "all_material_findings_classified", ...(repairs.length ? ["all_accepted_repairs_completed"] : []), "current_final_gate_passed"], run_changed_files: changedPaths(run.workspace_root), checks: receipts.map((receipt) => receipt.command), evidence: [...reviewers.flatMap((work) => readJsonString(work.result).findings.flatMap((finding) => finding.evidence_refs)), ...receipts.map((receipt) => runRef(run.id, home, receipt.receipt_path))], next_action: nextAction, code_review: { mode, reviewer_work_ids: reviewers.map((work) => work.work_id), repair_work_ids: repairs.map((work) => work.work_id), decision } }, mechanical: { started_at: startedAt, finished_at: now, wall_clock_ms: Math.max(0, Date.parse(now) - Date.parse(startedAt)), git: gitFacts(run.workspace_root), session_stats_command: `${flowCommand(context)} stat run sessions ls --run ${run.id} --project-root ${JSON.stringify(projectRoot)} --json`, usage_stats_command: `${flowCommand(context)} stat usage --run ${run.id} --project-root ${JSON.stringify(projectRoot)} --json` }, artifacts: { json: "stage-report.json", markdown: "stage-report.md", html: "stage-report.html" }, validation: { status: "passed" } };
+    const report = { schema_id: "dd-flow/stage-report@1", run_id: run.id, stage, generated_at: now, verdict: "done", semantic: { result: `Independent CODE review completed: ${reviewers.length} reviewer Work(s), ${repairs.length} repair Work(s).`, acceptance: ["all_selected_review_groups_completed", "all_material_findings_classified", ...(repairs.length ? ["all_accepted_repairs_completed"] : []), "current_final_gate_passed"], run_changed_files: changedPaths(run.workspace_root), checks: receipts.map((receipt) => receipt.command), evidence: [...reviewers.flatMap((work) => readJsonString(work.result).findings.flatMap((finding) => finding.evidence_refs)), ...receipts.map((receipt) => runRef(run.id, home, receipt.receipt_path))], next_action: nextAction, code_review: { mode, reviewer_work_ids: reviewers.map((work) => work.work_id), repair_work_ids: repairs.map((work) => work.work_id), decision } }, mechanical: { started_at: startedAt, finished_at: now, wall_clock_ms: Math.max(0, Date.parse(now) - Date.parse(startedAt)), git: gitFacts(run.workspace_root), session_stats_command: runtimeCommand(context, ["stat", "run", "sessions", "ls", "--run", run.id, "--project-root", projectRoot, "--json"]), usage_stats_command: runtimeCommand(context, ["stat", "usage", "--run", run.id, "--project-root", projectRoot, "--json"]) }, artifacts: { json: "stage-report.json", markdown: "stage-report.md", html: "stage-report.html" }, validation: { status: "passed" } };
     // The request must exist before CODE-REVIEW becomes terminal. Otherwise a
     // merge-gate error creates an irrecoverable `done` report with no MRG-*.
     const acceptedPaths = changedPaths(run.workspace_root);
-    const mergeRequest = nextAction === "start_merge" ? ensureVnextMergeRequest(context, { projectRoot, runId: run.id, acceptedPaths }) : null;
-    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" });
-    appendFlowRunTimelineEvent(context, project.id, run.id, { type: "code_review_completed", work_id: rootWork.work_id, outcome });
-    if (nextAction === "start_merge")
-        advanceFlowRun(context, { projectRoot, runId: run.id, status: "running", verdict: "code_review_completed", nextAction });
-    else {
-        await finishWork(context, rootWork.work_id, JSON.stringify(report, null, 2));
-        completeFlowRun(context, { projectRoot, runId: run.id, status: "done", verdict: "code_review_completed", nextAction: undefined });
+    let mergeRequest = null;
+    assertRunMutationAllowed(context, project.id, run.id, generation);
+    const prepareMerge = nextAction === "start_merge" ? prepareVnextMergeRequest(context, { projectRoot, runId: run.id, acceptedPaths }) : null;
+    if (matrix)
+        Object.assign(report.semantic, { verification_matrix: matrix.metadata });
+    if (JSON.stringify(defEvidence) !== JSON.stringify(decision.findings.filter(item => item.disposition === "defer").map(item => reviewDefEvidence(run.workspace_root, item.def_id))))
+        throw new AppError("deferral_invalid", "DEF evidence changed while final checks ran", 2);
+    Object.assign(report.semantic, { def_evidence: defEvidence });
+    const preparedReport = prepareStageReport(report);
+    const completionInput = { 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", dataSha256: preparedReport.sha256, git: report.mechanical.git };
+    withStageSettlement(context, () => {
+        assertRunMutationAllowed(context, project.id, run.id, generation);
+        const currentReviewers = reviewerWorks(context, project.id, run.id, cycle);
+        const currentRepairs = reviewRepairWorks(context, project.id, run.id, root, cycle);
+        if (currentReviewers.length !== reviewers.length || currentRepairs.length !== repairs.length || [...currentReviewers, ...currentRepairs].some(work => work.status !== "completed" || ![...reviewers, ...repairs].some(accepted => accepted.work_id === work.work_id && accepted.result === work.result))) {
+            throw new AppError("reviewer_jobs_incomplete", "Review or repair results changed while the final checks were running", 2);
+        }
+        mergeRequest = prepareMerge?.() ?? null;
+        const preparedCompletion = prepareFlowRunStageCompletion(context, completionInput);
+        acceptVerificationMatrix(context, matrix);
+        acceptStageReport(context, { projectId: project.id, runId: run.id, stage, root, prepared: preparedReport });
+        completeFlowRunStage(context, completionInput, preparedCompletion);
+        appendFlowRunTimelineEvent(context, project.id, run.id, { type: "code_review_completed", work_id: rootWork.work_id, outcome });
+        if (nextAction === "start_merge")
+            advanceFlowRun(context, { settlementStage: "code-review", projectRoot, runId: run.id, status: "running", verdict: "code_review_completed", nextAction });
+        else {
+            finishStageCoordinatorWork(context, rootWork.work_id, JSON.stringify(report, null, 2));
+            completeFlowRun(context, { projectRoot, runId: run.id, status: "done", verdict: "code_review_completed", nextAction: undefined });
+        }
+        refreshRunWorkProjection(context, project.id, run.id);
+    });
+    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: stageSuccessor(context, { projectRoot, runId: run.id, stage: "merge", command: runtimeCommand(context, ["stage", "start", run.id, "--stage", "merge", "--project-root", projectRoot, "--json", "--progress-jsonl"]) }) } : {}) };
+}
+export function readCodeReviewDecision(file, accepted, explicit = false, prepared) {
+    if (!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 });
     }
-    refreshRunWorkProjection(context, project.id, run.id);
-    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: `${flowCommand(context)} stage start ${run.id} --stage merge --project-root ${JSON.stringify(projectRoot)} --json --progress-jsonl` } } : {}) };
+    return accepted;
+}
+function disabledReviewDecision() {
+    return { schema_id: "dd-flow/code-review-decision@3", summary: "CODE-REVIEW is disabled by RUN configuration.", findings: [] };
 }
-function reviewGroups(home) {
+/** 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 = [];
     for (const file of findFiles(path.join(home, "03-plan"), "aspect-map.json")) {
@@ -221,19 +336,40 @@ function reviewGroups(home) {
     if (!declared.length)
         return [{ key: "baseline", aspect_ids: [...expected].sort() }];
     const assigned = new Set();
+    const scoped = new Set();
     for (const group of declared)
         for (const aspectId of group.aspect_ids) {
-            if (assigned.has(aspectId))
-                throw new AppError("code_review_groups_invalid", "A CODE-REVIEW aspect appears in more than one accepted group", 2, { aspect_id: aspectId });
+            const assignment = `${group.key.slice(0, group.key.lastIndexOf("/"))}/${aspectId}`;
+            if (scoped.has(assignment))
+                throw new AppError("code_review_groups_invalid", "A CODE-REVIEW aspect appears in more than one group of the same protocol", 2, { aspect_id: aspectId });
+            scoped.add(assignment);
             assigned.add(aspectId);
         }
     const missing = [...expected].filter((aspectId) => !assigned.has(aspectId)).sort();
     return [...declared, ...(missing.length ? [{ key: "baseline", aspect_ids: missing }] : [])];
 }
+export function assertCodeReviewCoverage(groups, reviewers) {
+    const expected = new Map(groups.map(group => [group.key, [...group.aspect_ids].sort()]));
+    if (!expected.size || expected.size !== groups.length)
+        throw new AppError("reviewer_coverage_invalid", "CODE-REVIEW expected group identities must be nonempty and unique", 2);
+    const seen = new Set();
+    for (const work of reviewers) {
+        const group = readJsonString(work.payload_json).group;
+        if (!group?.key || seen.has(group.key) || !expected.has(group.key) || !Array.isArray(group.aspect_ids) || JSON.stringify([...group.aspect_ids].sort()) !== JSON.stringify(expected.get(group.key)))
+            throw new AppError("reviewer_coverage_invalid", "CODE-REVIEW Work does not match its expected group", 2, { work_id: work.work_id });
+        seen.add(group.key);
+    }
+    const missing = [...expected.keys()].filter(key => !seen.has(key));
+    if (missing.length || !expected.size)
+        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 same Finish command again. 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 passed its declared checks; each check proves only its named contour and proof limits, not complete semantic acceptance. Conduct independent quality review and do not manually rerun every declared check.", "</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: " + runtimeCommand(context, ["work", "ls", "--run", input.run.id, "--ready", "--project-root", 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 aggregate gate fails with repair_required, its repair Work is already registered with all causal checks. End this Turn so the controller launches a fresh child. Do not copy receipt IDs, create another repair, invoke its start_command in the coordinator, or 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 known = new Map(canonicalCodeFindings(reviewers).map((item) => [item.finding_ref, item.finding]));
+    const refs = decision.findings.map(item => item.finding_ref);
+    if (new Set(refs).size !== refs.length || refs.some(ref => !known.has(ref)))
+        throw new AppError("review_evidence_invalid", "CODE decisions must use unique known canonical finding references", 2, { finding_refs: refs });
     const items = new Map(decision.findings.map((item) => [item.finding_ref, item]));
     const duplicates = new Set();
     for (const item of decision.findings.filter((entry) => entry.disposition === "duplicate")) {
@@ -249,6 +385,9 @@ function canonicalReviewEvidence(decision, reviewers) {
         }
         if (!cursor)
             throw new AppError("review_evidence_invalid", "Duplicate finding chain must end at a decided canonical finding", 2, { finding_ref: item.finding_ref });
+        if (["p0", "p1"].includes(known.get(item.finding_ref).priority) && cursor.disposition !== "fix") {
+            throw new AppError("review_material_disposition_invalid", "P0/P1 duplicate findings must resolve to a fixed canonical finding", 2, { finding_ref: item.finding_ref, canonical_finding_ref: cursor.finding_ref, disposition: cursor.disposition });
+        }
         duplicates.add(item.finding_ref);
     }
     return {
@@ -299,8 +438,7 @@ function validateDecision(context, input) {
         if (item.disposition === "fix" && !repaired.some((work) => requiredChecks.every((ref) => reviewCheckRefs(work).includes(ref))))
             throw new AppError("review_repair_check_missing", "A fixed CODE-REVIEW finding needs a repair Work that retains every selected causal check", 2, { finding_ref: findingRef, check_refs: requiredChecks });
         if (finding.priority === "p2" && item.disposition === "defer") {
-            if (!item.def_id || !fs.existsSync(path.join(input.workspaceRoot, ".memory-bank", "defs", `${item.def_id}.md`)))
-                throw new AppError("deferral_invalid", "A deferred P2 requires a named durable DEF", 2, { finding_ref: findingRef, def_id: item.def_id ?? null });
+            reviewDefEvidence(input.workspaceRoot, item.def_id);
         }
         if (finding.priority === "p3" && item.disposition === "defer")
             throw new AppError("deferral_invalid", "P3 observations are not deferred as DEF", 2, { finding_ref: findingRef });
@@ -357,13 +495,9 @@ function effectiveMode(home, run) { const index = JSON.parse(run.index_json); if
     return { mode: "standard", source: "project_policy", reason: "A failed integration gate requires independent review of its source repair." }; const configured = index.settings?.code_review; const requested = configured?.mode ?? "auto"; if (requested !== "auto")
     return { mode: requested, source: configured?.source === "user_instruction" ? "user_instruction" : "project_policy", reason: configured?.reason ?? "Frozen RUN configuration." }; const assessments = findFiles(path.join(home, "03-plan"), "plan.json").map((file) => readJson(file)); const deep = assessments.some((plan) => plan.assessment?.failure_impact?.level === "high" || plan.assessment?.solution_uncertainty?.level === "high"); return { mode: deep ? "deep" : "standard", source: "plan_assessment", reason: deep ? "Accepted PLAN assessment records high impact or uncertainty." : "Accepted PLAN assessment requires the standard independent review." }; }
 function executionStopTarget(run) { return JSON.parse(run.index_json).execution_profile?.settings?.stop_target ?? "code_review_completed"; }
-function changedPaths(workspaceRoot) { try {
-    return execFileSync("git", ["status", "--porcelain=v1", "--untracked-files=all"], { cwd: workspaceRoot, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).split(/\r?\n/).filter(Boolean).map((line) => line.slice(3).replace(/^.* -> /, ""));
-}
-catch {
-    return [];
-} }
+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;
 }
@@ -391,7 +525,9 @@ function requireRun(context, projectId, runId) { const run = context.db.get("SEL
     throw new AppError("not_found", "RUN is not registered", 1); return run; }
 function requireHome(run) { if (!run.run_root)
     throw new AppError("runtime_missing", "RUN artifact root is unavailable", 1); return run.run_root; }
-function finishCommand(context, runId, projectRoot, decision) { return `${flowCommand(context)} stage finish ${runId} --stage code-review --decision-file ${JSON.stringify(decision)} --project-root ${JSON.stringify(projectRoot)} --json --progress-jsonl`; }
+export function finishCommand(context, runId, projectRoot, decision, retryCheckId) {
+    return managedLifecycleCommand(context, runtimeCommand(context, ["stage", "finish", runId, "--stage", "code-review", "--decision-file", decision, "--project-root", projectRoot, "--json", "--progress-jsonl", ...checkRetryArgs(context, projectRoot, runId, retryCheckId)]));
+}
 function findFiles(root, name) { if (!fs.existsSync(root))
     return []; const out = []; for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
     const file = path.join(root, entry.name);
@@ -409,4 +545,3 @@ function readJsonString(value) { try {
 catch {
     return {};
 } }
-function writeReport(root, report) { writeStageReport(root, report); }