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

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

@@ -2,7 +2,6 @@ import { managedLifecycleCommand } from "./lifecycle-invocations.js";
 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 { resolveProjectRoot } from "../storage/paths.js";
 import { requireProjectByRoot } from "./projects.js";
@@ -12,9 +11,9 @@ import { flowCommand } from "./stage-pause.js";
 import { assertStageStartHookEvent } from "./hooks.js";
 import { requireVnextWorkspaceRoute } from "./vnext-workspace-policy.js";
 import { addVnextCodeRepair, resumeAcceptedCodeStage } from "./vnext-code.js";
-import { finalCodeCheckDeclarations, runCodeChecks, validateFailedCheckRetry, workspaceFingerprint } from "./code-checks.js";
+import { finalCodeCheckDeclarations, runCodeChecks, validateFailedCheckRetry, workspaceChangedPaths } from "./code-checks.js";
 import { addWorkBatch, bindStageCoordinatorWork, finishStageCoordinatorWork, refreshRunWorkProjection } from "./work-registry.js";
-import { withStageSettlement, stageInputGuard } from "./runs.js";
+import { withStageSettlement } from "./runs.js";
 import { vnextStageDirectory } from "../domain/stage-catalog.js";
 import { writeStageReport } from "./stage-report-renderer.js";
 import { applyExternalStageContext } from "./stage-context.js";
@@ -55,7 +54,7 @@ export function startVnextCodeReview(context, input) {
     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", cycle, mode: mode.mode, mode_source: mode.source, mode_reason: mode.reason, ...(mode.mode !== "off" ? { read_only_input: { parent_work_id: rootWork.work_id } } : {}), code_report_sha256: sha256File(path.join(home, "05-code", "stage-report.json")) }, null, 2)}\n`);
     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(promptPath, prompt);
@@ -120,23 +119,23 @@ 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)
         throw new AppError("runtime_missing", "CODE-REVIEW effective mode was not frozen at stage start", 1);
-    const generation = assertRunMutationAllowed(context, project.id, run.id);
     if (reviewContext.code_report_sha256 !== sha256File(path.join(home, "05-code", "stage-report.json")))
         throw new AppError("code_review_input_changed", "Accepted CODE report changed after CODE-REVIEW start", 2);
     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);
-        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 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))
@@ -144,8 +143,8 @@ export async function finishVnextCodeReview(context, input) {
     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 decision = readCodeReviewDecision(decisionFile, reviewContext.accepted_decision, Boolean(input.decisionFile));
+    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);
     if (mode !== "off") {
@@ -158,15 +157,18 @@ export async function finishVnextCodeReview(context, input) {
         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, cycle);
-        const decisionSha = sha256File(decisionFile);
         const frozenShaFile = path.join(root, ".decision-sha256");
-        if (fs.existsSync(frozenShaFile) && fs.readFileSync(frozenShaFile, "utf8").trim() !== decisionSha)
+        if (!reviewContext.accepted_decision && fs.existsSync(frozenShaFile) && fs.readFileSync(frozenShaFile, "utf8").trim() !== sha256File(decisionFile))
             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 }, 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 next.finish_command with the unchanged decision file.", next: { finish_command: finishCommand(context, run.id, projectRoot, decisionFile) } };
+            return { ok: true, run_id: run.id, stage, outcome: "repair_required", repair, instruction: "Run the returned repair Work in one fresh child session. When it completes, invoke next.finish_command; this review cycle uses the decision already accepted by the runtime.", next: { finish_command: finishCommand(context, run.id, projectRoot, decisionFile) } };
         }
         repairs = reviewRepairWorks(context, project.id, run.id, root, cycle);
         const incompleteRepairs = repairs.filter((work) => work.status !== "completed");
@@ -175,7 +177,6 @@ export async function finishVnextCodeReview(context, input) {
         validateDecision(context, { decision: canonical.decision, reviewers: canonical.reviewers, repairs, workspaceRoot: run.workspace_root });
     }
     const outcome = decision.findings.some((item) => item.disposition === "defer") ? "accepted_with_DEF" : "accepted";
-    const assertInputs = stageInputGuard(context, project.id, run.id, () => [workspaceFingerprint(run.workspace_root), sha256File(decisionFile), sha256File(path.join(home, "05-code", "stage-report.json"))]);
     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 : []; }));
     if (input.retryCheckId) {
@@ -202,11 +203,15 @@ export async function finishVnextCodeReview(context, input) {
     // merge-gate error creates an irrecoverable `done` report with no MRG-*.
     const acceptedPaths = changedPaths(run.workspace_root);
     let mergeRequest = null;
-    assertInputs();
+    assertRunMutationAllowed(context, project.id, run.id, generation);
     const prepareMerge = nextAction === "start_merge" ? prepareVnextMergeRequest(context, { projectRoot, runId: run.id, acceptedPaths }) : null;
     withStageSettlement(context, () => {
         assertRunMutationAllowed(context, project.id, run.id, generation);
-        assertInputs();
+        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;
         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" });
@@ -221,6 +226,14 @@ export async function finishVnextCodeReview(context, input) {
     });
     return { ok: true, run_id: run.id, stage, outcome, report_path: path.join(root, "stage-report.json"), next_action: nextAction, ...(mergeRequest ? { merge_request: mergeRequest, next: { kind: "start_stage", stage: "merge", command: managedLifecycleCommand(context, `${flowCommand(context)} stage start ${run.id} --stage merge --project-root ${JSON.stringify(projectRoot)} --json --progress-jsonl`) } } : {}) };
 }
+export function readCodeReviewDecision(file, accepted, explicit = false) {
+    if (!accepted)
+        return readJson(file);
+    if (explicit && fs.existsSync(file) && JSON.stringify(readJson(file)) !== JSON.stringify(accepted)) {
+        throw new AppError("review_decision_changed", "This review cycle already accepted a different decision", 2, { decision_file: file });
+    }
+    return accepted;
+}
 export function reviewGroups(home) {
     const expected = new Set(baselineAspects);
     const declared = [];
@@ -390,12 +403,7 @@ 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 stageStatus(run, name) { try {
     return JSON.parse(run.index_json).stage_runs?.find((item) => item.stage === name)?.status ?? null;

package/dist/services/vnext-code.js

@@ -1,7 +1,5 @@
 import { managedLifecycleCommand } from "./lifecycle-invocations.js";
 import crypto from "node:crypto";
-import { stageInputGuard } from "./runs.js";
-import { workspaceFingerprint } from "./code-checks.js";
 import { runWorkspaceBootstrap } from "./workspace-bootstrap.js";
 import fs from "node:fs";
 import path from "node:path";
@@ -25,6 +23,22 @@ import { readFanoutDescriptor, writeFanoutDescriptor } from "./vnext-fanout.js";
 import { assertRunMutationAllowed } from "./run-recovery.js";
 const stage = "code";
 const stageDir = vnextStageDirectory("code");
+/** A controller prepares slow, deterministic project tooling before it asks an
+ * agent to enter CODE or a restored CODE_REVIEW. The subsequent lifecycle tool call remains the sole
+ * authority for attaching and binding the Stage. */
+export async function prepareVnextCodeWorkspace(context, input) {
+    if (context.env.DD_FLOW_CODE_READINESS_OWNER !== input.ownerId) {
+        throw new AppError("code_readiness_owner_mismatch", "CODE readiness preparation must use its controller's frozen owner", 1, { owner_id: input.ownerId });
+    }
+    const projectRoot = resolveProjectRoot(input.projectRoot);
+    const project = requireProjectByRoot(context, projectRoot);
+    const run = requireRun(context, project.id, input.runId);
+    assertRunMutationAllowed(context, project.id, run.id);
+    requireVnextWorkspaceRoute({ projectRoot, runId: run.id, runHome: requireHome(run), workspaceRoot: run.workspace_root, stage: input.stage ?? stage });
+    const root = path.join(requireHome(run), stageDir);
+    fs.mkdirSync(root, { recursive: true });
+    return ensureCodeWorkspaceReady(context, project.id, run, root, [], input.progress, { force: input.stage !== "code-review" });
+}
 export async function startVnextCode(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const project = requireProjectByRoot(context, projectRoot);
@@ -145,7 +159,6 @@ export async function finishVnextCode(context, input) {
         throw new AppError("obligation_coverage_incomplete", "CODE graph does not cover every accepted obligation", 2, { missing });
     }
     // Reject a malformed semantic receipt before running the expensive gate.
-    const assertInputs = stageInputGuard(context, project.id, run.id, () => [workspaceFingerprint(run.workspace_root), crypto.createHash("sha256").update(fs.readFileSync(input.verificationFile)).digest("hex")]);
     const verification = verificationForFinish(context, { file: input.verificationFile, projectRoot: run.workspace_root, runId: run.id, runRoot: home });
     if (verification.verdict === "blocked") {
         return { ok: true, run_id: run.id, stage, outcome: "blocked", verification, instruction: "CODE remains running. Resolve the stated external or user-input blocker in this same coordinator session, update code-verification.json, then invoke this same stage finish command again." };
@@ -192,12 +205,10 @@ export async function finishVnextCode(context, input) {
         throw new AppError("code_acceptance_unresolved", "CODE cannot finish until every due acceptance criterion has current checks and evidence", 2, { unresolved: unresolvedAcceptance });
     const now = context.now();
     const timing = stageTiming(home, stage, now);
-    const reportedPaths = [...new Set(works.flatMap((work) => resultPaths(work.result)))];
-    const observedChangedPaths = workspaceChangedPaths(run.workspace_root);
-    const changedPaths = observedChangedPaths ?? reportedPaths;
-    const missingReportedPaths = observedChangedPaths === null ? [] : reportedPaths.filter((item) => !observedChangedPaths.includes(item));
-    if (missingReportedPaths.length)
-        throw new AppError("changed_path_not_materialized", "CODE Work reported paths that are not changed in the accepted workspace", 2, { paths: missingReportedPaths });
+    // Work result paths are provenance, not a mutable filesystem oracle. The
+    // stage reports one shared Git observation; ignored machine repairs are
+    // rejected before a Work can become completed.
+    const changedPaths = workspaceChangedPaths(run.workspace_root);
     const next = nextAction(run, changedPaths);
     const report = {
         schema_id: "dd-flow/stage-report@1",
@@ -237,11 +248,14 @@ export async function finishVnextCode(context, input) {
     // Do it before materialising a terminal stage report or changing RUN state,
     // so an invalid merge policy leaves CODE safely running and retryable.
     let mergeRequest = null;
-    assertInputs();
+    assertRunMutationAllowed(context, project.id, run.id, generation);
     const prepareMerge = next === "start_merge" ? prepareVnextMergeRequest(context, { projectRoot, runId: run.id, acceptedPaths: changedPaths }) : null;
     withStageSettlement(context, () => {
         assertRunMutationAllowed(context, project.id, run.id, generation);
-        assertInputs();
+        const currentWorks = codeWorks(context, project.id, run.id);
+        if (currentWorks.length !== works.length || currentWorks.some(work => work.status !== "completed" || !works.some(accepted => accepted.work_id === work.work_id && accepted.result === work.result))) {
+            throw new AppError("code_graph_incomplete", "CODE results changed while the final checks were running", 2);
+        }
         mergeRequest = prepareMerge?.() ?? null;
         writeReport(root, report);
         completeFlowRunStage(context, {
@@ -581,15 +595,45 @@ function requireRun(context, projectId, runId) {
     return run;
 }
 /** CODE, not PROTOCOLIZE, makes a checkout ready for project tooling. */
-async function ensureCodeWorkspaceReady(context, projectId, run, root, readinessChecks, progress) {
+export function isReusablePreparedCodeReadiness(value, expected) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const receipt = value;
+    return receipt.schema_id === "dd-flow/workspace-readiness@2"
+        && receipt.status === "passed"
+        && receipt.prepared_by === expected.ownerId
+        && receipt.workspace_root === expected.workspaceRoot
+        && receipt.command === expected.command
+        && receipt.policy_ref === expected.policyRef;
+}
+function readPreparedReadiness(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+async function ensureCodeWorkspaceReady(context, projectId, run, root, readinessChecks, progress, options = {}) {
     const profile = JSON.parse(run.index_json);
     const bootstrap = profile.execution_profile?.settings?.code_bootstrap;
     if (!bootstrap || typeof bootstrap.command !== "string" || typeof bootstrap.policy_ref !== "string") {
         throw new AppError("execution_profile_invalid", "CODE requires a frozen bootstrap command in the RUN execution profile", 1, { run_id: run.id });
     }
     const receiptPath = path.join(root, "workspace-readiness.json");
-    // Re-run the project bootstrap on stage entry: a prior receipt cannot prove
-    // that ignored dependencies or local services still exist.
+    const ownerId = context.env.DD_FLOW_CODE_READINESS_OWNER;
+    if (!options.force && ownerId && isReusablePreparedCodeReadiness(readPreparedReadiness(receiptPath), {
+        ownerId,
+        workspaceRoot: run.workspace_root,
+        command: bootstrap.command,
+        policyRef: bootstrap.policy_ref
+    })) {
+        progress?.("workspace bootstrap already prepared by this controller");
+        return readPreparedReadiness(receiptPath);
+    }
+    // Unowned and stale receipts are never trusted: a direct stage entry still
+    // performs its own readiness check.  Only the same controller can hand a
+    // freshly prepared workspace to its immediately following lifecycle call.
     const startedAt = new Date().toISOString();
     progress?.(`workspace bootstrap started: ${bootstrap.command}`);
     const result = await runWorkspaceBootstrap(context, { projectId, runId: run.id, runHome: requireHome(run), workspaceRoot: run.workspace_root, command: bootstrap.command, artifactDir: "05-code/readiness", progress });
@@ -597,7 +641,7 @@ async function ensureCodeWorkspaceReady(context, projectId, run, root, readiness
     const checks = bootstrapPassed && readinessChecks.length
         ? await runCodeChecks(context, { projectId, runId: run.id, runHome: requireHome(run), workspaceRoot: run.workspace_root, scope: "aggregate", artifactDir: "05-code/readiness", checks: readinessChecks, ...(progress ? { progress } : {}) })
         : [];
-    const receipt = { schema_id: "dd-flow/workspace-readiness@2", workspace_root: run.workspace_root, command: bootstrap.command, policy_ref: bootstrap.policy_ref, started_at: startedAt, finished_at: new Date().toISOString(), status: bootstrapPassed && checks.every((check) => check.status === "passed") ? "passed" : "failed", process_id: result.process_id, stdout_path: result.stdout_path, stderr_path: result.stderr_path, completion_path: result.completion_path, exit_code: result.exit_code, stdout: result.stdout, stderr: result.stderr, check_declarations: readinessChecks, checks: checks.map((check) => ({ id: check.id, status: check.status, receipt_path: check.receipt_path })), ...(result.error ? { error: result.error } : {}), receipt_path: receiptPath };
+    const receipt = { schema_id: "dd-flow/workspace-readiness@2", workspace_root: run.workspace_root, command: bootstrap.command, policy_ref: bootstrap.policy_ref, started_at: startedAt, finished_at: new Date().toISOString(), status: bootstrapPassed && checks.every((check) => check.status === "passed") ? "passed" : "failed", ...(ownerId ? { prepared_by: ownerId } : {}), process_id: result.process_id, stdout_path: result.stdout_path, stderr_path: result.stderr_path, completion_path: result.completion_path, exit_code: result.exit_code, stdout: result.stdout, stderr: result.stderr, check_declarations: readinessChecks, checks: checks.map((check) => ({ id: check.id, status: check.status, receipt_path: check.receipt_path })), ...(result.error ? { error: result.error } : {}), receipt_path: receiptPath };
     fs.writeFileSync(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`);
     if (receipt.status !== "passed")
         throw new AppError("workspace_readiness_failed", "CODE workspace bootstrap failed", 1, receipt);
@@ -615,8 +659,9 @@ export function finishCommand(context, runId, projectRoot, verificationFile, ret
 }
 function readVerification(context, input) {
     const file = path.resolve(input.file);
-    validateSchema({ schemaName: "code-verification", file, projectRoot: input.projectRoot, ddFlowHome: context.ddFlowHome, runId: input.runId, runRoot: input.runRoot });
-    return JSON.parse(fs.readFileSync(file, "utf8"));
+    const data = JSON.parse(fs.readFileSync(file, "utf8"));
+    validateSchema({ schemaName: "code-verification", file, data, projectRoot: input.projectRoot, ddFlowHome: context.ddFlowHome, runId: input.runId, runRoot: input.runRoot });
+    return data;
 }
 function verificationForFinish(context, input) {
     return readVerification(context, input);
@@ -673,15 +718,6 @@ function changedPathsFromReport(file) {
         return [];
     }
 }
-function resultPaths(result) {
-    try {
-        const value = JSON.parse(result ?? "");
-        return Array.isArray(value.changed_paths) ? value.changed_paths.filter((item) => typeof item === "string") : [];
-    }
-    catch {
-        return [];
-    }
-}
 function unique(values) {
     return [...new Set(values)];
 }

package/dist/services/vnext-merge.js

@@ -16,7 +16,7 @@ import { validateSchema } from "./schema-validation.js";
 import { writeStageReport } from "./stage-report-renderer.js";
 import { bindStageCoordinatorWork, createChildWork, failWork, finishFanInWork, finishWork, refreshRunWorkProjection, startStageCoordinatorWork } from "./work-registry.js";
 import { addVnextCodeRepair } from "./vnext-code.js";
-import { checkReceiptEvidenceValid, checkReceipts, effectiveCheckDeclarations, readCodeCheckProfile, runCodeChecks, validateFailedCheckRetry, workspaceFingerprint } from "./code-checks.js";
+import { checkReceiptEvidenceValid, checkReceipts, effectiveCheckDeclarations, readCodeCheckProfile, runCodeChecks, validateFailedCheckRetry, workspaceChangedPaths, workspaceFingerprint } from "./code-checks.js";
 import { applyExternalStageContext } from "./stage-context.js";
 import { ensureLaneWorkspace, heartbeatLaneLock, releaseLaneLock, waitAcquireLaneLock } from "./lanes.js";
 import { assertRunMutationAllowed } from "./run-recovery.js";
@@ -72,11 +72,13 @@ export function prepareVnextMergeRequest(context, input) {
         const frozen = JSON.parse(fs.readFileSync(freezeFile, "utf8"));
         sourceCommit = frozen.run_id === run.id && typeof frozen.source_commit === "string" ? frozen.source_commit : "";
         sourcePaths = Array.isArray(frozen.paths) ? frozen.paths : [];
-        if (!sourceCommit || gitValue(run.workspace_root, ["rev-parse", "HEAD"]) !== sourceCommit || (accepted && JSON.stringify(accepted) !== JSON.stringify(sourcePaths)))
+        // A retry sees a clean tree: the original paths are already in sourceCommit.
+        // Reuse that receipt, but never accept new edits merely because names match.
+        if (!sourceCommit || frozen.source_workspace !== run.workspace_root || frozen.source_branch !== sourceBranch || gitValue(run.workspace_root, ["rev-parse", "HEAD"]) !== sourceCommit || meaningfulStatus(run.workspace_root, ignored).length)
             throw new AppError("merge_source_freeze_conflict", "Existing MERGE source freeze does not match the accepted source", 2, { freeze_file: freezeFile });
     }
     else {
-        sourcePaths = [...new Set(meaningfulStatus(run.workspace_root, ignored).map(statusPath))].sort();
+        sourcePaths = meaningfulStatus(run.workspace_root, ignored);
         if (accepted) {
             const unexpected = sourcePaths.filter((item) => !accepted.includes(item));
             const absent = accepted.filter((item) => !sourcePaths.includes(item));
@@ -491,15 +493,13 @@ function requireOwnedActiveRequest(context, input) { const project = requireProj
 function assertExecutionBaseline(request) { const head = gitValue(request.target_workspace, ["rev-parse", "HEAD"], true); if (request.checkpoint === "baseline_locked" && head !== request.execution_target_head)
     throw new AppError("merge_target_changed", "Integration target changed after the lane baseline was locked", 1, { expected: request.execution_target_head, actual: head }); }
 function recovery(context, request, code, detail) { context.db.run("UPDATE merge_requests SET status = 'recovery_required', last_error_json = ?, updated_at = ? WHERE merge_request_id = ?", [JSON.stringify({ code, detail }), context.now(), request.merge_request_id]); throw new AppError("merge_recovery_required", "MERGE mutation could not be reconciled automatically", 1, { merge_request_id: request.merge_request_id, code, detail }); }
-function commitPendingSource(cwd, runId, ignored) { const paths = meaningfulStatus(cwd, ignored).map(statusPath); if (!paths.length)
+function commitPendingSource(cwd, runId, ignored) { const paths = meaningfulStatus(cwd, ignored); if (!paths.length)
     return; git(cwd, ["add", "-A", "--", ...paths]); git(cwd, ["commit", "-m", `chore(${runId.toLowerCase()}): freeze accepted source`]); }
-function commitIntegration(cwd, runId, ignored) { const mergeHead = fs.existsSync(path.join(gitDirectory(cwd), "MERGE_HEAD")); const paths = meaningfulStatus(cwd, ignored).map(statusPath); if (!mergeHead && !paths.length)
+function commitIntegration(cwd, runId, ignored) { const mergeHead = fs.existsSync(path.join(gitDirectory(cwd), "MERGE_HEAD")); const paths = meaningfulStatus(cwd, ignored); if (!mergeHead && !paths.length)
     return; if (paths.length)
     git(cwd, ["add", "-A", "--", ...paths]); git(cwd, ["commit", "-m", `merge(${runId.toLowerCase()}): integrate accepted source`]); }
 function ignoredGitPaths(context, projectId) { return [readProjectConfig(context, projectId).dashboard.markdown_path.replaceAll("\\", "/")]; }
-function meaningfulStatus(cwd, ignored) { const result = spawnSync("git", ["status", "--porcelain=v1", "--untracked-files=all"], { cwd, encoding: "utf8" }); if (result.status !== 0)
-    return []; return result.stdout.split(/\r?\n/).filter(Boolean).filter((line) => !ignored.includes(statusPath(line))); }
-function statusPath(line) { const value = line.slice(3); const renamed = value.includes(" -> ") ? value.slice(value.lastIndexOf(" -> ") + 4) : value; return renamed.replace(/^"|"$/g, ""); }
+function meaningfulStatus(cwd, ignored) { return workspaceChangedPaths(cwd).filter((item) => !ignored.includes(item)); }
 function unmerged(cwd) { const value = gitValue(cwd, ["diff", "--name-only", "--diff-filter=U"], true); return value.split(/\r?\n/).filter(Boolean); }
 function gitDirectory(cwd) { const value = gitValue(cwd, ["rev-parse", "--git-dir"]); return path.resolve(cwd, value); }
 function git(cwd, args) { try {

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

@@ -1,6 +1,6 @@
 import { managedLifecycleCommand } from "./lifecycle-invocations.js";
 import crypto from "node:crypto";
-import { withStageSettlement, stageInputGuard } from "./runs.js";
+import { withStageSettlement } from "./runs.js";
 import fs from "node:fs";
 import path from "node:path";
 import { AppError } from "../shared/errors.js";
@@ -11,7 +11,7 @@ import { addWorkBatch, bindStageCoordinatorWork, ensureWorkRegistry, refreshRunW
 import { validateSchema } from "./schema-validation.js";
 import { flowCommand, stagePauseCommand, stagePauseCommandTemplate } from "./stage-pause.js";
 import { assertStageStartHookEvent } from "./hooks.js";
-import { validateVnextPlanArtifacts } from "./vnext-plan.js";
+import { prepareVnextPlanArtifacts, validateVnextPlanArtifacts } from "./vnext-plan.js";
 import { requireVnextWorkspaceRoute } from "./vnext-workspace-policy.js";
 import { nextWorkId } from "./ids.js";
 import { vnextStageDirectory } from "../domain/stage-catalog.js";
@@ -104,7 +104,7 @@ export function startVnextPlanReview(context, input) {
     const workSessionId = String(binding.work_session_id);
     const sessionId = String(binding.session_id);
     const orchestration = writeFanoutDescriptor(root, { stage, parent_work_id: workId, dispatch: "plan-review", capacity_required: true });
-    writeJson(path.join(root, "work-context.json"), { schema_id: "dd-flow/plan-review-context@1", system: { run_id: run.id, work_id: workId, stage, requested_mode: requested, effective_mode: effective, plan_revision: currentPlanRevision(home, run.workspace_root), plan_checksum: planChecksum, batch_checksum: batchChecksum }, groups, workspace: { project_root: projectRoot, workspace_root: run.workspace_root, stage_root: root, plan_root: planRoot } });
+    writeJson(path.join(root, "work-context.json"), { schema_id: "dd-flow/plan-review-context@1", read_only_input: { parent_work_id: workId }, system: { run_id: run.id, work_id: workId, stage, requested_mode: requested, effective_mode: effective, plan_revision: currentPlanRevision(home, run.workspace_root), plan_checksum: planChecksum, batch_checksum: batchChecksum }, groups, workspace: { project_root: projectRoot, workspace_root: run.workspace_root, stage_root: root, plan_root: planRoot } });
     refreshRunWorkProjection(context, project.id, run.id);
     appendFlowRunTimelineEvent(context, project.id, run.id, { type: "work_session_started", stage, work_id: workId, id: workSessionId, session_id: sessionId });
     return { ok: true, run_id: run.id, stage, outcome: "review_required", work_id: workId, id: workSessionId, prompt_path: promptPath, worker_prompt_markdown: fs.readFileSync(promptPath, "utf8"), ...(externalContext ? { external_context: externalContext } : {}), orchestration, plan_review: { requested_mode: requested, effective_mode: effective, policy_source: policySource(run), groups }, next: { dispatch_command: dispatchCommand(context, run.id, projectRoot), finish_command: finishCommand(context, run.id, projectRoot, path.join(root, "decision.json")) } };
@@ -173,6 +173,9 @@ export function recordVnextPlanReviewCapacity(context, input) {
     return { ok: true, run_id: run.id, capacity: { available_slots: input.availableSlots, source: "harness_qualification" } };
 }
 export function finishVnextPlanReview(context, input) {
+    return withStageSettlement(context, () => finishPlanReviewOwned(context, input));
+}
+function finishPlanReviewOwned(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const project = requireProjectByRoot(context, projectRoot);
     const run = requireRun(context, projectRoot, input.runId);
@@ -184,7 +187,6 @@ export function finishVnextPlanReview(context, input) {
     if (!parent || parent.status !== "running")
         throw new AppError("invalid_work_state", "PLAN-REVIEW has no running parent Work", 2);
     const decisionPath = path.resolve(input.decisionFile ?? path.join(root, "decision.json"));
-    const assertInputs = stageInputGuard(context, project.id, run.id, () => [planSetChecksum(home, run.workspace_root), checksum(batch), checksum(decisionPath), checksum(path.join(root, "work-context.json"))]);
     const decision = readDecision(context, projectRoot, run.id, home, decisionPath);
     const children = context.db.all("SELECT work_id, task, status, result, created_at FROM works WHERE project_id = ? AND run_id = ? AND parent_work_id = ?", [project.id, run.id, parent.work_id]);
     const contextFile = readJson(path.join(root, "work-context.json"));
@@ -198,8 +200,7 @@ export function finishVnextPlanReview(context, input) {
         throw new AppError("stage_pause_required", "A user or decision blocker must pause the current PLAN-REVIEW Work with `dd-flow stage pause`; do not finish the stage as blocked", 2, { run_id: run.id, stage, work_id: parent.work_id });
     }
     if (["failed", "cancelled"].includes(decision.outcome)) {
-        preserveDecisionReceipt(root, decisionPath);
-        return withStageSettlement(context, () => { assertInputs(); return finishTerminalReview(context, { projectRoot, projectId: project.id, run, root, planRoot, batch, parentWorkId: parent.work_id, children, contextFile, decision }); });
+        return withStageSettlement(context, () => { preserveDecisionReceipt(root, decisionPath); return finishTerminalReview(context, { projectRoot, projectId: project.id, run, root, planRoot, batch, parentWorkId: parent.work_id, children, contextFile, decision }); });
     }
     if (children.some((child) => child.status === "created" || child.status === "running"))
         throw new AppError("worker_jobs_incomplete", "PLAN-REVIEW finish requires all reviewer Works to settle", 1, { works: children.map((child) => ({ work_id: child.work_id, status: child.status })) });
@@ -233,21 +234,20 @@ export function finishVnextPlanReview(context, input) {
     else if (decision.correction.status !== "not_required" || planRevision !== reviewedPlanRevision || currentPlanChecksum !== contextFile.system?.plan_checksum) {
         throw new AppError("validation", "A clean PLAN review must not claim an unverified correction", 2);
     }
-    const planFailures = validateVnextPlanArtifacts(context, { projectRoot, workspaceRoot: run.workspace_root, runId: run.id, home, protocols: protocolIdsForReview(home) });
-    if (planFailures.length)
-        throw new AppError("validation", "Corrected PLAN artifacts have validation errors", 2, { errors: planFailures });
+    const prepared = prepareVnextPlanArtifacts(context, { projectRoot, workspaceRoot: run.workspace_root, runId: run.id, home, protocols: protocolIdsForReview(home) });
+    if (prepared.failures.length)
+        throw new AppError("validation", "Corrected PLAN artifacts have validation errors", 2, { errors: prepared.failures });
     if (needsCorrection) {
-        const initialBatchChecksum = contextFile.system?.batch_checksum;
-        if (!initialBatchChecksum || checksum(batch) === initialBatchChecksum)
-            throw new AppError("stale_code_work_batch", "Applied PLAN correction must regenerate the proposed CODE batch", 2, { batch, initial_batch_checksum: initialBatchChecksum });
+        // Regeneration above is authoritative. A valid PLAN correction need not
+        // change the derived CODE tasks (for example, a clarified explanation).
         if (decision.correction.changed_paths.some((item) => item.endsWith("code-work-batch.json")))
             throw new AppError("validation", "Generated CODE batch must not be listed as an agent-authored correction", 2, { changed_paths: decision.correction.changed_paths });
     }
-    preserveDecisionReceipt(root, decisionPath);
     const finalPlanChecksum = planSetChecksum(home, run.workspace_root);
-    const finalBatchChecksum = checksum(batch);
+    const finalBatchChecksum = prepared.batchChecksum;
     return withStageSettlement(context, () => {
-        assertInputs();
+        prepared.publish();
+        preserveDecisionReceipt(root, decisionPath);
         const registered = registerCode(context, project.id, run.id, batch);
         const now = context.now();
         settleReviewParent(context, { projectRoot, projectId: project.id, runId: run.id, parentWorkId: parent.work_id, status: "completed", result: decision.summary, reason: "plan_review_completed", resultPath: path.join(root, "stage-report.json") });
@@ -393,7 +393,7 @@ catch {
 function rootWorkId(context, projectId, runId) { const root = context.db.get("SELECT work_id FROM works WHERE project_id = ? AND run_id = ? AND parent_work_id IS NULL ORDER BY created_at LIMIT 1", [projectId, runId]); if (!root)
     throw new AppError("runtime_missing", "vNext RUN has no root Work", 1); return root.work_id; }
 function registerCode(context, projectId, runId, batch) { return addWorkBatch(context, { parentWorkId: rootWorkId(context, projectId, runId), file: batch }); }
-function readDecision(context, projectRoot, runId, runRoot, file) { validateSchema({ schemaName: "plan-review-decision", file, projectRoot, runId, runRoot, ddFlowHome: context.ddFlowHome }); return readJson(file); }
+function readDecision(context, projectRoot, runId, runRoot, file) { const data = readJson(file); validateSchema({ schemaName: "plan-review-decision", file, data, projectRoot, runId, runRoot, ddFlowHome: context.ddFlowHome }); return data; }
 function preserveDecisionReceipt(root, source) {
     const receipt = path.join(root, "decision.receipt.json");
     const bytes = fs.readFileSync(source);

package/dist/services/vnext-plan.js

@@ -6,7 +6,7 @@ import path from "node:path";
 import { AppError } from "../shared/errors.js";
 import { effectiveCheckDeclarations, readCodeCheckProfile, validateCheckDeclaration, validateCheckPlacement, validateCodeCheckCommands } from "./code-checks.js";
 import { requireProjectByRoot } from "./projects.js";
-import { resolveProjectRoot } from "../storage/paths.js";
+import { canonicalPath, resolveProjectRoot } from "../storage/paths.js";
 import { advanceFlowRun, appendFlowRunTimelineEvent, attachFlowRunStage, completeFlowRunStage, getFlowRunVariables, gitFacts } from "./runs.js";
 import { validateSchema } from "./schema-validation.js";
 import { bindRunningWorkSession, bindStageCoordinatorWork, ensureWorkRegistry, refreshRunWorkProjection, validateWorkBatchFile } from "./work-registry.js";
@@ -151,6 +151,13 @@ function finishVnextPlanOwned(context, input) {
     return { ok: true, run_id: run.id, protocols, next_action: "start_plan_review", next_command: reviewCommand, next: { kind: "start_stage", stage: "plan-review", command: reviewCommand } };
 }
 export function validateVnextPlanArtifacts(context, input) {
+    const prepared = prepareVnextPlanArtifacts(context, input);
+    if (!prepared.failures.length && input.publishBatch !== false)
+        prepared.publish();
+    return prepared.failures;
+}
+/** Validate in scratch files; publish only after the caller accepts its inputs. */
+export function prepareVnextPlanArtifacts(context, input) {
     const workspaceRoot = input.workspaceRoot ?? input.projectRoot;
     const planFiles = input.protocols.map((id) => path.join(workspaceRoot, ".memory-bank", "protocol", id, "plan.json"));
     const mapFiles = input.protocols.map((id) => path.join(input.home, "03-plan", id, "aspect-map.json"));
@@ -163,6 +170,7 @@ export function validateVnextPlanArtifacts(context, input) {
             : []) : []) ?? [])
         : undefined;
     const failures = [];
+    const publications = new Map();
     const plans = [];
     for (const [index, file] of planFiles.entries()) {
         const protocolId = input.protocols[index];
@@ -186,14 +194,22 @@ export function validateVnextPlanArtifacts(context, input) {
         }
     }
     for (const file of mapFiles) {
+        const temporary = `${file}.tmp-${crypto.randomUUID()}`;
         try {
-            normalizeAspectMapRefs(file, workspaceRoot, input.home, input.runId);
-            validateSchema({ schemaName: "plan-aspect-map", file, projectRoot: workspaceRoot, ddFlowHome: context.ddFlowHome, runId: input.runId, runRoot: input.home });
-            validateAspectMap(file, input.protocols, workspaceRoot);
+            const bytes = normalizedAspectMapRefs(file, workspaceRoot, input.home, input.runId);
+            if (input.publishBatch === false && bytes !== fs.readFileSync(file, "utf8"))
+                throw new AppError("validation", "Accepted aspect-map requires normalization; regenerate it in PLAN", 2, { file });
+            fs.writeFileSync(temporary, bytes);
+            validateSchema({ schemaName: "plan-aspect-map", file: temporary, projectRoot: workspaceRoot, ddFlowHome: context.ddFlowHome, runId: input.runId, runRoot: input.home });
+            validateAspectMap(temporary, input.protocols, workspaceRoot);
+            publications.set(file, bytes);
         }
         catch (error) {
             failures.push(validationFailure(file, error));
         }
+        finally {
+            fs.rmSync(temporary, { force: true });
+        }
     }
     if (!failures.length) {
         try {
@@ -213,7 +229,7 @@ export function validateVnextPlanArtifacts(context, input) {
             validateSchema({ schemaName: "code-work-batch", file: temporaryBatch, projectRoot: workspaceRoot, ddFlowHome: context.ddFlowHome, runId: input.runId, runRoot: input.home });
             validateWorkBatchFile(temporaryBatch);
             if (input.publishBatch !== false) {
-                fs.renameSync(temporaryBatch, batch);
+                publications.set(batch, fs.readFileSync(temporaryBatch, "utf8"));
             }
             else if (!fs.existsSync(batch) || checksum(temporaryBatch) !== checksum(batch)) {
                 throw new AppError("stale_code_work_batch", "CODE batch no longer matches the accepted semantic PLAN", 2, { batch });
@@ -226,7 +242,29 @@ export function validateVnextPlanArtifacts(context, input) {
             fs.rmSync(temporaryBatch, { force: true });
         }
     }
-    return failures;
+    return { failures, batchChecksum: publications.has(batch) ? crypto.createHash("sha256").update(publications.get(batch)).digest("hex") : null,
+        publish: () => {
+            if (failures.length)
+                throw new AppError("validation", "Cannot publish invalid PLAN artifacts", 2, { errors: failures });
+            const published = [];
+            try {
+                for (const [file, bytes] of publications) {
+                    const temporary = `${file}.tmp-${crypto.randomUUID()}`;
+                    try {
+                        fs.writeFileSync(temporary, bytes);
+                        fs.renameSync(temporary, file);
+                        published.push(file);
+                    }
+                    finally {
+                        fs.rmSync(temporary, { force: true });
+                    }
+                }
+            }
+            catch (cause) {
+                throw new AppError("plan_publication_failed", cause instanceof Error ? cause.message : String(cause), 1, { effect: "unknown", published_files: published, business_commit: false });
+            }
+        }
+    };
 }
 /** CODE entry validates the same PLAN closure without changing an accepted batch. */
 export function validateVnextCodeHandoff(context, input) {
@@ -375,13 +413,16 @@ function assertPlanIdentity(value, identity, file) {
     if (JSON.stringify(value.source_refs) !== JSON.stringify(identity.source_refs))
         throw new AppError("validation", "PLAN must preserve CLI-owned source_refs", 2, { file });
 }
-function normalizeAspectMapRefs(file, projectRoot, runHome, runId) {
-    const map = JSON.parse(fs.readFileSync(file, "utf8"));
+function normalizedAspectMapRefs(file, projectRoot, runHome, runId) {
+    projectRoot = canonicalPath(projectRoot);
+    runHome = canonicalPath(runHome);
+    const bytes = fs.readFileSync(file, "utf8");
+    const map = JSON.parse(bytes);
     let changed = false;
     const normalize = (value) => {
         if (!path.isAbsolute(value))
             return value;
-        const source = path.resolve(value);
+        const source = canonicalPath(value, false);
         const inProject = source.startsWith(`${projectRoot}${path.sep}`);
         const inRun = source.startsWith(`${runHome}${path.sep}`);
         if (!inProject && !inRun)
@@ -394,8 +435,7 @@ function normalizeAspectMapRefs(file, projectRoot, runHome, runId) {
     for (const aspect of map.aspects ?? [])
         if (Array.isArray(aspect.planned_artifact_refs))
             aspect.planned_artifact_refs = aspect.planned_artifact_refs.map(normalize);
-    if (changed)
-        fs.writeFileSync(file, `${JSON.stringify(map, null, 2)}\n`);
+    return changed ? `${JSON.stringify(map, null, 2)}\n` : bytes;
 }
 function projectCodeWorkBatch(input) {
     const obligationMap = acceptedObligationMap(input.home);