@deksden-com/dd-flow-cli 0.8.0 → 0.9.0-beta.0

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

@@ -5,7 +5,7 @@ import { execFileSync } from "node:child_process";
 import { AppError } from "../shared/errors.js";
 import { resolveProjectRoot } from "../storage/paths.js";
 import { requireProjectByRoot } from "./projects.js";
-import { appendFlowRunTimelineEvent, attachFlowRunStage, completeFlowRun, completeFlowRunStage, gitFacts } from "./runs.js";
+import { advanceFlowRun, appendFlowRunTimelineEvent, attachFlowRunStage, completeFlowRun, completeFlowRunStage, gitFacts } from "./runs.js";
 import { validateSchema } from "./schema-validation.js";
 import { flowCommand } from "./stage-pause.js";
 import { assertStageStartHookEvent } from "./hooks.js";
@@ -17,6 +17,7 @@ import { vnextStageDirectory } from "../domain/stage-catalog.js";
 import { writeStageReport } from "./stage-report-renderer.js";
 import { applyExternalStageContext } from "./stage-context.js";
 import { readFanoutDescriptor, writeFanoutDescriptor } from "./vnext-fanout.js";
+import { ensureVnextMergeRequest } from "./vnext-merge.js";
 const stage = "code-review";
 const stageDir = vnextStageDirectory(stage);
 const baselineAspects = ["goal_traceability", "coding_standards_design_review", "verification_evidence_review"];
@@ -84,11 +85,24 @@ export function addVnextCodeReviewRepair(context, input) {
     const origins = codeWorks(context, project.id, run.id).map((work) => work.work_id);
     if (!origins.length)
         throw new AppError("runtime_missing", "CODE-REVIEW repair requires completed CODE Work", 1);
+    const checks = new Map(codeWorks(context, project.id, run.id).flatMap((work) => {
+        const payload = readJsonString(work.payload_json);
+        return Array.isArray(payload.checks) ? payload.checks : [];
+    }).map((check) => [check.id, check]));
+    const requestedCheckRefs = [...new Set(selected.flatMap(({ finding_ref }) => input.checkRefsByFinding[finding_ref] ?? []))];
+    if (!requestedCheckRefs.length)
+        throw new AppError("review_repair_check_required", "Each accepted CODE-REVIEW repair needs an explicit causal CHK-* check reference", 2, { finding_ids: input.findingIds });
+    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");
     return addVnextCodeRepair(context, {
         projectRoot,
         runId: run.id,
         reviewFindingIds: selected.map((finding) => finding.finding_ref),
         reviewEvidenceRefs: selected.flatMap(({ finding }) => finding.evidence_refs),
+        reviewChecks,
+        reviewCheckRefs: requestedCheckRefs,
         originWorkIds: origins,
         objective: input.objective
     });
@@ -101,15 +115,17 @@ export async function finishVnextCodeReview(context, input) {
     const root = path.join(home, stageDir);
     const mode = effectiveMode(run, changedPaths(run.workspace_root));
     const reportPath = path.join(root, "stage-report.json");
-    if (stageStatus(run, stage) === "done" && fs.existsSync(reportPath))
-        return { ok: true, resumed: true, run_id: run.id, stage, outcome: "accepted", report_path: reportPath, next_action: "code_review_completed" };
+    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@2", summary: "CODE-REVIEW is disabled by RUN configuration.", findings: [] }, null, 2)}\n`);
+        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 });
     const decision = readJson(decisionFile);
     const reviewers = reviewerWorks(context, project.id, run.id);
@@ -120,6 +136,7 @@ export async function finishVnextCodeReview(context, input) {
         for (const work of reviewers)
             validateReviewerResult(context, work, run);
         const canonical = reviewDecisionForRepair(decision, reviewers);
+        const checkRefsByFinding = validateRepairChecks(context, { projectId: project.id, runId: run.id, decision: canonical.decision });
         let repairs = reviewRepairWorks(context, project.id, run.id, root);
         const decisionSha = sha256File(decisionFile);
         const frozenShaFile = path.join(root, ".decision-sha256");
@@ -127,8 +144,8 @@ export async function finishVnextCodeReview(context, input) {
             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) {
+            const repair = addVnextCodeReviewRepair(context, { projectRoot, runId: run.id, findingIds: fixIds, checkRefsByFinding, objective: `Resolve accepted CODE-REVIEW findings: ${fixIds.join(", ")}` });
             fs.writeFileSync(frozenShaFile, `${decisionSha}\n`);
-            const repair = addVnextCodeReviewRepair(context, { projectRoot, runId: run.id, findingIds: fixIds, objective: `Resolve accepted CODE-REVIEW findings: ${fixIds.join(", ")}` });
             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) } };
         }
         repairs = reviewRepairWorks(context, project.id, run.id, root);
@@ -144,20 +161,33 @@ export async function finishVnextCodeReview(context, input) {
     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 = repairs.length ? 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 } : {}) }) : [];
-    const failed = receipts.filter((receipt) => receipt.status === "failed");
+    const failed = receipts.filter((receipt) => receipt.status !== "passed");
     if (failed.length)
-        throw new AppError("code_review_gate_failed", "CODE-REVIEW repair changed the project but the aggregate gate failed", 2, { failures: failed });
+        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`
+        });
+    const stopTarget = executionStopTarget(run);
+    const nextAction = stopTarget === "merge_completed" ? "start_merge" : "code_review_completed";
     const now = context.now();
     const startedAt = stageStartedAt(run, now);
-    writeProtocolFlowStatus(run.workspace_root, home, run.id, "CODE-REVIEW complete; this RUN reached its configured terminal boundary.");
-    const report = { schema_id: "dd-flow/stage-report@1", run_id: run.id, stage, generated_at: now, verdict: "done", semantic: { result: decision.summary, acceptance: ["all_selected_review_groups_completed", "all_material_findings_classified", ...(repairs.length ? ["all_accepted_repairs_completed", "post_repair_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: "code_review_completed", 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" } };
+    writeProtocolFlowStatus(run.workspace_root, home, run.id, nextAction === "start_merge" ? "CODE-REVIEW complete; MERGE is queued." : "CODE-REVIEW complete; this RUN reached its configured terminal boundary.");
+    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", "post_repair_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" } };
     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" });
-    await finishWork(context, rootWork.work_id, JSON.stringify(report, null, 2));
     appendFlowRunTimelineEvent(context, project.id, run.id, { type: "code_review_completed", work_id: rootWork.work_id, outcome });
-    completeFlowRun(context, { projectRoot, runId: run.id, status: "done", verdict: "code_review_completed", nextAction: undefined });
+    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 });
+    }
     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: "code_review_completed" };
+    const mergeRequest = nextAction === "start_merge" ? ensureVnextMergeRequest(context, { projectRoot, runId: run.id }) : null;
+    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` } } : {}) };
 }
 function reviewGroups(run, home, mode) {
     const aspectMapFiles = findFiles(path.join(home, "03-plan"), "aspect-map.json");
@@ -173,7 +203,7 @@ function reviewGroups(run, home, mode) {
     return Array.from({ length: Math.ceil(all.length / chunk) }, (_, index) => ({ key: `group-${index + 1}`, aspect_ids: all.slice(index * chunk, (index + 1) * chunk) }));
 }
 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")}. 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. Finding ids must use the unique prefix FIND-${group.key}-. 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"); 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_home_path, "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. The first Finish freezes this decision and creates one repair Work when needed. Run it, then call the same Finish command again. Review is not repeated.", "```json", JSON.stringify({ schema_id: "dd-flow/code-review-decision@2", summary: "Evidence-backed conclusion.", findings: [{ finding_ref: "WRK-001-review/FIND-001", disposition: "fix | defer | reject | duplicate", reason: "Why this classification is correct.", 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 = 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_home_path, "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 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]));
@@ -210,6 +240,8 @@ export function reviewDecisionForRepair(decision, reviewers) {
         if (["p0", "p1"].includes(finding.priority) && item.disposition !== "fix") {
             throw new AppError("review_material_disposition_invalid", "P0/P1 CODE-REVIEW findings must be fixed, not rejected or deferred", 2, { finding_ref: findingRef, disposition: item.disposition });
         }
+        if (item.disposition === "fix" && !item.check_refs?.length)
+            throw new AppError("review_repair_check_required", "Each accepted CODE-REVIEW repair needs an explicit causal CHK-* check reference", 2, { finding_ref: findingRef });
     }
     return { ...canonical, fix_ids: canonical.decision.findings.filter((item) => item.disposition === "fix").map((item) => item.finding_ref) };
 }
@@ -217,15 +249,24 @@ function validateDecision(context, input) {
     const findings = canonicalCodeFindings(input.reviewers);
     const known = new Map(findings.map((item) => [item.finding_ref, item.finding]));
     const decisions = new Map(input.decision.findings.map((item) => [item.finding_ref, item]));
-    const repaired = new Set(input.repairs.flatMap((work) => { const result = readJsonString(work.result); return Array.isArray(result.resolved_finding_refs) ? result.resolved_finding_refs.filter((value) => typeof value === "string") : []; }));
+    const repairedBy = new Map();
+    for (const work of input.repairs) {
+        const result = readJsonString(work.result);
+        for (const ref of Array.isArray(result.resolved_finding_refs) ? result.resolved_finding_refs.filter((value) => typeof value === "string") : [])
+            repairedBy.set(ref, [...(repairedBy.get(ref) ?? []), work]);
+    }
     for (const { finding_ref: findingRef, finding } of findings) {
         const item = decisions.get(findingRef);
         if (!item)
             throw new AppError("review_evidence_invalid", "Every material CODE review finding needs one decision", 2, { finding_ref: findingRef });
-        if (["p0", "p1"].includes(finding.priority) && !(item.disposition === "fix" && repaired.has(findingRef)))
+        const repaired = repairedBy.get(findingRef) ?? [];
+        if (["p0", "p1"].includes(finding.priority) && !(item.disposition === "fix" && repaired.length))
             throw new AppError("review_unresolved_material", "P0/P1 findings must be explicitly resolved by a completed clean repair Work", 2, { finding_ref: findingRef });
-        if (item.disposition === "fix" && !repaired.has(findingRef))
+        if (item.disposition === "fix" && !repaired.length)
             throw new AppError("review_repair_missing", "A fixed CODE-REVIEW finding needs a completed clean repair Work that explicitly resolves it", 2, { finding_ref: findingRef });
+        const requiredChecks = item.check_refs ?? [];
+        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 });
@@ -241,6 +282,16 @@ function validateReviewerResult(context, work, run) { if (!work.result)
     throw new AppError("review_evidence_invalid", "Reviewer Work has no result", 2, { work_id: work.work_id }); const file = path.join(requireHome(run), stageDir, `${work.work_id}.result.json`); fs.writeFileSync(file, work.result); validateSchema({ schemaName: "code-review-result", file, projectRoot: run.workspace_root, ddFlowHome: context.ddFlowHome, runId: run.id }); }
 function reviewerWorks(context, projectId, runId) { return context.db.all("SELECT * FROM works WHERE project_id = ? AND run_id = ? ORDER BY created_at, work_id", [projectId, runId]).filter((work) => { const p = readJsonString(work.payload_json); return Boolean(p && p.kind === "code-review"); }); }
 function codeWorks(context, projectId, runId) { return context.db.all("SELECT * FROM works WHERE project_id = ? AND run_id = ? AND status = 'completed' ORDER BY created_at, work_id", [projectId, runId]).filter((work) => readJsonString(work.payload_json).schema_id === "dd-flow/code-work-packet@5" && !reviewFindingIds(work).length); }
+function acceptedCodeChecks(context, projectId, runId) { return codeWorks(context, projectId, runId).flatMap((work) => { const payload = readJsonString(work.payload_json); return Array.isArray(payload.checks) ? payload.checks : []; }); }
+function validateRepairChecks(context, input) { const known = new Set(acceptedCodeChecks(context, input.projectId, input.runId).map((check) => check.id)); const selected = {}; for (const item of input.decision.findings.filter((item) => item.disposition === "fix")) {
+    const refs = [...new Set(item.check_refs ?? [])];
+    if (!refs.length)
+        throw new AppError("review_repair_check_required", "Each accepted CODE-REVIEW repair needs an explicit causal CHK-* check reference", 2, { finding_ref: item.finding_ref });
+    const unknown = refs.filter((ref) => !known.has(ref));
+    if (unknown.length)
+        throw new AppError("review_check_reference_unknown", "CODE-REVIEW repair selects a check absent from the accepted CODE handoff", 2, { finding_ref: item.finding_ref, check_refs: unknown });
+    selected[item.finding_ref] = refs;
+} return selected; }
 function reviewRepairWorks(context, projectId, runId, root) { return context.db.all("SELECT * FROM works WHERE project_id = ? AND run_id = ? ORDER BY created_at, work_id", [projectId, runId]).filter((work) => isCodeReviewStageRepair(work, root)); }
 export function isCodeReviewStageRepair(work, root) {
     if (reviewFindingIds(work).length)
@@ -256,8 +307,11 @@ export function isCodeReviewStageRepair(work, root) {
 }
 function reviewFindingIds(work) { const repair = readJsonString(work.payload_json).repair; if (!repair || typeof repair !== "object" || Array.isArray(repair))
     return []; const ids = repair.review_finding_ids; return Array.isArray(ids) ? ids.filter((value) => typeof value === "string") : []; }
+function reviewCheckRefs(work) { const repair = readJsonString(work.payload_json).repair; if (!repair || typeof repair !== "object" || Array.isArray(repair))
+    return []; const refs = repair.review_check_refs; return Array.isArray(refs) ? refs.filter((value) => typeof value === "string") : []; }
 function canonicalCodeFindings(works) { return works.flatMap((work) => readJsonString(work.result).findings.map((finding) => ({ finding_ref: `${work.work_id}/${finding.finding_id}`, finding }))); }
 function effectiveMode(run, paths) { const index = JSON.parse(run.index_json); const requested = index.settings?.code_review?.mode ?? "auto"; return requested === "auto" ? (paths.length ? "standard" : "off") : requested; }
+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(/^.* -> /, ""));
 }

package/dist/services/vnext-code.js

@@ -15,6 +15,7 @@ import { readVnextSpecifyResult } from "./vnext-specify.js";
 import { addWorkBatch, bindStageCoordinatorWork, codeWorkGraph, finishWork, refreshRunWorkProjection, validateWorkBatchFile, workStartCommand } from "./work-registry.js";
 import { vnextStageDirectory } from "../domain/stage-catalog.js";
 import { writeStageReport } from "./stage-report-renderer.js";
+import { ensureVnextMergeRequest } from "./vnext-merge.js";
 import { assertStageStartHookEvent } from "./hooks.js";
 import { applyExternalStageContext } from "./stage-context.js";
 import { readFanoutDescriptor, writeFanoutDescriptor } from "./vnext-fanout.js";
@@ -161,7 +162,7 @@ export async function finishVnextCode(context, input) {
             release();
         }
     }
-    const failed = receipts.filter((receipt) => receipt.status === "failed");
+    const failed = receipts.filter((receipt) => receipt.status !== "passed");
     if (failed.length) {
         throw new AppError("code_gate_failed", "CODE remains running because the aggregate project gate failed", 2, {
             failures: failed,
@@ -177,7 +178,7 @@ export async function finishVnextCode(context, input) {
     const timing = stageTiming(home, stage, now);
     const changedPaths = [...new Set(works.flatMap((work) => resultPaths(work.result)))];
     const next = nextAction(run, changedPaths);
-    writeProtocolFlowStatus(run.workspace_root, home, run.id, next === "start_code_review" ? "CODE complete; CODE-REVIEW is next." : "CODE complete; this RUN reached its configured terminal boundary.");
+    writeProtocolFlowStatus(run.workspace_root, home, run.id, next === "start_code_review" ? "CODE complete; CODE-REVIEW is next." : next === "start_merge" ? "CODE complete; MERGE is queued." : "CODE complete; this RUN reached its configured terminal boundary.");
     const report = {
         schema_id: "dd-flow/stage-report@1",
         run_id: run.id,
@@ -234,8 +235,9 @@ export async function finishVnextCode(context, input) {
         completeFlowRun(context, { projectRoot, runId: run.id, status: "done", verdict: "code_completed", nextAction: undefined });
     }
     else {
-        advanceFlowRun(context, { projectRoot, runId: run.id, status: "running", verdict: "code_completed", nextAction: "start_code_review" });
+        advanceFlowRun(context, { projectRoot, runId: run.id, status: "running", verdict: "code_completed", nextAction: next });
     }
+    const mergeRequest = next === "start_merge" ? ensureVnextMergeRequest(context, { projectRoot, runId: run.id }) : null;
     return {
         ok: true,
         run_id: run.id,
@@ -243,7 +245,7 @@ export async function finishVnextCode(context, input) {
         outcome: "accepted",
         report_path: path.join(root, "stage-report.json"),
         next_action: next,
-        ...(next === "start_code_review" ? { next: { kind: "start_stage", stage: "code-review", command: `${flowCommand(context)} stage start ${run.id} --stage code-review --project-root ${JSON.stringify(projectRoot)} --json` } } : {})
+        ...(next === "start_code_review" ? { next: { kind: "start_stage", stage: "code-review", command: `${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: `${flowCommand(context)} stage start ${run.id} --stage merge --project-root ${JSON.stringify(projectRoot)} --json --progress-jsonl` } } : {})
     };
 }
 export function addVnextCodeRepair(context, input) {
@@ -289,7 +291,7 @@ export function addVnextCodeRepair(context, input) {
         repair: {
             origin_work_ids: origins.map((work) => work.work_id),
             ...(receipt ? { check_receipt_id: receipt.id, failure_receipt_path: receipt.receipt_path } : {}),
-            ...(input.reviewFindingIds?.length ? { review_finding_ids: unique(input.reviewFindingIds), review_evidence_refs: unique(input.reviewEvidenceRefs ?? []) } : {})
+            ...(input.reviewFindingIds?.length ? { review_finding_ids: unique(input.reviewFindingIds), review_evidence_refs: unique(input.reviewEvidenceRefs ?? []), review_check_refs: unique(input.reviewCheckRefs ?? (input.reviewChecks ?? []).map((check) => check.id)) } : {})
         },
         task: input.objective,
         semantic_spine: {
@@ -301,7 +303,9 @@ export function addVnextCodeRepair(context, input) {
         },
         requirements: uniqueBy(invariantPackets.flatMap((value) => value.requirements), (value) => value.id),
         acceptance: uniqueBy(invariantPackets.flatMap((value) => value.acceptance), (value) => JSON.stringify(value)),
-        document_updates: receipt ? [] : uniqueBy(packets.flatMap((value) => value.document_updates).filter((update) => (input.reviewEvidenceRefs ?? []).some((reference) => reference === update.path || reference.startsWith(`${update.path}:`) || reference.endsWith(`/${update.path}`))), (value) => JSON.stringify(value)),
+        // A CODE-REVIEW repair changes delivered code/evidence, never the
+        // already accepted PLAN or its ownership declaration.
+        document_updates: [],
         required_read: unique([...(receipt ? [receipt.receipt_path] : input.reviewEvidenceRefs ?? []), ...packets.flatMap((value) => value.required_read)]),
         discovery_boundary: unique(packets.flatMap((value) => value.discovery_boundary)),
         // These are collision-avoidance hints. Receipt paths enrich the coordinator
@@ -310,11 +314,11 @@ export function addVnextCodeRepair(context, input) {
         // Receipts record the resolved shell command. A repair must retain the
         // accepted declaration (including its immutable @check alias) and only
         // change when it runs, so work finish can validate it again.
-        checks: uniqueBy([...(failedCheck ? [{ ...failedCheck, purpose: "Re-run the failed accepted check.", run_at: "work" }] : []), ...packets.flatMap((value) => value.checks)], (check) => check.id),
+        checks: selectRepairChecks({ ...(failedCheck ? { failedCheck } : {}), ...(input.reviewChecks ? { reviewChecks: input.reviewChecks } : {}) }),
         provides_checks: [],
         stop_conditions: unique([
             ...invariantPackets.flatMap((value) => value.stop_conditions),
-            ...(receipt ? ["Stop and report the blocker if the proposed repair contradicts an accepted requirement or non-goal."] : [])
+            ...(receipt ? ["Stop and report the blocker if the proposed repair contradicts an accepted requirement or non-goal."] : ["Do not modify accepted PLAN artifacts, code-work-batch.json, or review decisions. Stop and report if the finding cannot be repaired within accepted scope."])
         ]),
         depends_on: origins.map((work) => work.work_id),
         result_schema: "dd-flow/code-work-result@2"
@@ -340,6 +344,13 @@ export function addVnextCodeRepair(context, input) {
     refreshRunWorkProjection(context, project.id, run.id);
     return { ok: true, run_id: run.id, repair_work_id: id, start_command: workStartCommand(context, work) };
 }
+/** The repair Work runs only the check that motivated it; the stage retains the aggregate gate. */
+export function selectRepairChecks(input) {
+    const checks = input.failedCheck
+        ? [{ ...input.failedCheck, purpose: "Re-run the failed accepted check.", run_at: "work" }]
+        : (input.reviewChecks ?? []).map((check) => ({ ...check, purpose: `Prove the CODE-REVIEW repair: ${check.purpose}`, run_at: "work" }));
+    return uniqueBy(checks, (check) => check.id);
+}
 function receiptRepairPaths(workspaceRoot, receipt) {
     const root = path.resolve(workspaceRoot);
     const text = [receipt.stdout_path, receipt.stderr_path]
@@ -394,7 +405,7 @@ function coordinatorPrompt(context, input) {
         "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: 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.",
         `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, use the returned repair command with the relevant completed origin Work IDs and a concise repair objective. Do not edit invisibly in the root orchestrator.",
+        "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.",
         "</execution_commands>",
         "",
         "<verification_contract>",
@@ -416,8 +427,9 @@ export function profileCommands(workspaceRoot) {
 function latestReceiptsByCommand(receipts) {
     const latest = new Map();
     for (const receipt of receipts)
-        latest.set(receipt.declaration_id, receipt);
-    return [...latest.values()];
+        for (const ref of receipt.check_refs)
+            latest.set(ref, receipt);
+    return [...new Set(latest.values())];
 }
 /**
  * A CODE finish may be retried after a client loses the long command's output.
@@ -429,8 +441,10 @@ export function reusableAggregateGateReceipts(context, input) {
     const current = workspaceFingerprint(input.workspaceRoot);
     const latest = new Map();
     for (const receipt of checkReceipts(context, { projectId: input.projectId, runId: input.runId })) {
-        if (receipt.scope === "aggregate" && expected.has(receipt.declaration_id))
-            latest.set(receipt.declaration_id, receipt);
+        if (receipt.scope === "aggregate")
+            for (const ref of receipt.check_refs)
+                if (expected.has(ref))
+                    latest.set(ref, receipt);
     }
     if (latest.size !== expected.size)
         return null;
@@ -480,10 +494,10 @@ function processAlive(pid) {
         return false;
     }
 }
-function verificationProjection(works, receipts) {
+export function verificationProjection(works, receipts) {
     const packets = works.map((work) => packet(work)).filter((value) => value !== null);
     const declarations = uniqueBy(packets.flatMap((value) => value.checks), (value) => value.id);
-    const receiptByDeclaration = new Map(receipts.map((receipt) => [receipt.declaration_id, receipt]));
+    const receiptByDeclaration = new Map(receipts.flatMap((receipt) => receipt.check_refs.map((ref) => [ref, receipt])));
     const evidence = new Map();
     for (const work of works) {
         const result = readJsonResult(work.result);
@@ -492,9 +506,19 @@ function verificationProjection(works, receipts) {
                 evidence.set(item.criterion_id, unique([...(evidence.get(item.criterion_id) ?? []), ...(item.refs ?? [])]));
     }
     const acceptance = uniqueBy(packets.flatMap((value) => value.acceptance), (value) => value.criterion_id);
+    const hasEvidence = (criterionId) => (evidence.get(criterionId)?.length ?? 0) > 0;
+    const isPassed = (checkId, criterionId) => receiptByDeclaration.get(checkId)?.status === "passed" || (declarations.find((check) => check.id === checkId)?.run_at === "external" && hasEvidence(criterionId));
     return {
-        checks: declarations.map((check) => { const receipt = receiptByDeclaration.get(check.id); return { id: check.id, run_at: check.run_at, status: receipt?.status ?? (["work", "code", "readiness"].includes(check.run_at) ? "failed" : "not_due"), receipt_ref: receipt?.receipt_path ?? null }; }),
-        acceptance: acceptance.map((item) => ({ criterion_id: item.criterion_id, gate: item.gate, status: ["work", "code", "readiness"].includes(item.gate) ? ((item.check_refs.every((id) => receiptByDeclaration.get(id)?.status === "passed") && (evidence.get(item.criterion_id)?.length ?? 0) > 0) ? "confirmed" : "unresolved") : "not_due", check_refs: item.check_refs, evidence_refs: evidence.get(item.criterion_id) ?? [] }))
+        checks: declarations.map((check) => {
+            const receipt = receiptByDeclaration.get(check.id);
+            const externallyEvidenced = check.run_at === "external" && acceptance.some((item) => item.check_refs.includes(check.id) && hasEvidence(item.criterion_id));
+            return { id: check.id, run_at: check.run_at, status: receipt?.status ?? (externallyEvidenced ? "evidence_recorded" : ["work", "code", "readiness"].includes(check.run_at) ? "failed" : "not_due"), receipt_ref: receipt?.receipt_path ?? null };
+        }),
+        acceptance: acceptance.map((item) => {
+            const external = item.check_refs.some((id) => declarations.find((check) => check.id === id)?.run_at === "external");
+            const confirmed = item.check_refs.every((id) => isPassed(id, item.criterion_id)) && hasEvidence(item.criterion_id);
+            return { criterion_id: item.criterion_id, gate: item.gate, status: confirmed ? (external ? "confirmed_with_external_evidence" : "confirmed") : ["work", "code", "readiness"].includes(item.gate) ? "unresolved" : "not_due", check_refs: item.check_refs, evidence_refs: evidence.get(item.criterion_id) ?? [] };
+        })
     };
 }
 function readJsonResult(value) { try {
@@ -640,7 +664,10 @@ function nextAction(run, changedPaths) {
     const index = JSON.parse(run.index_json);
     const requested = index.settings?.code_review?.mode ?? "auto";
     const enabled = requested === "off" ? false : requested === "auto" ? changedPaths.length > 0 : true;
-    return enabled && index.execution_profile?.settings?.stop_target === "code_review_completed" ? "start_code_review" : "code_completed";
+    const stopTarget = index.execution_profile?.settings?.stop_target;
+    if (enabled && (stopTarget === "code_review_completed" || stopTarget === "merge_completed"))
+        return "start_code_review";
+    return stopTarget === "merge_completed" ? "start_merge" : "code_completed";
 }
 function stageStatus(run, name) {
     try {

package/dist/services/vnext-execution-profile.js

@@ -13,14 +13,17 @@ export function loadVnextExecutionProfile(projectRoot) {
         throw new AppError("execution_profile_missing", "vNext flow requires .memory-bank/dd-flow/project-execution.json", 1, { file, cause: String(error) });
     }
     const profile = value;
-    if (profile.schema_id !== "dd-flow/project-execution@1"
+    if (profile.schema_id !== "dd-flow/project-execution@2"
         || (profile.stage_session_mode !== undefined && profile.stage_session_mode !== "same_session" && profile.stage_session_mode !== "new_session")
         || !["auto", "off", "standard", "deep"].includes(String(profile.plan_review_mode))
         || (profile.code_review_mode !== undefined && !["auto", "off", "standard", "deep"].includes(String(profile.code_review_mode)))
-        || !["code_completed", "code_review_completed"].includes(String(profile.stop_target))
+        || !["same_session", "server"].includes(String(profile.merge_mode))
+        || profile.merge_delivery?.strategy !== "local"
+        || !["retain", "delete_after_success"].includes(String(profile.merge_cleanup?.source))
+        || !["code_completed", "code_review_completed", "merge_completed"].includes(String(profile.stop_target))
         || !profile.code_bootstrap || typeof profile.code_bootstrap.command !== "string" || !profile.code_bootstrap.command.trim()
         || typeof profile.code_bootstrap.policy_ref !== "string" || !profile.code_bootstrap.policy_ref.trim()) {
-        throw new AppError("execution_profile_invalid", "Project execution profile does not match dd-flow/project-execution@1", 1, { file });
+        throw new AppError("execution_profile_invalid", "Project execution profile does not match dd-flow/project-execution@2", 1, { file });
     }
     return { ...profile, stage_session_mode: profile.stage_session_mode ?? "same_session", code_review_mode: profile.code_review_mode ?? "off" };
 }