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

package/dist/services/vnext-plan.js

@@ -1,171 +1,241 @@
+export const planCheckInstruction = "Use protocol-plan@6. Its top-level checks[] is the single check catalog. Every check has id, command, purpose, run_at and availability. available means executable now. planned means one named P* Work first creates a NEW @check/... alias: planned therefore always needs provided_by and the exact alias definition. Every semantic @check alias, including an existing one, repeats its exact accepted profile command in definition so later stages can detect drift. Items and acceptance entries use check_refs only; never duplicate command declarations.";
+import { managedLifecycleCommand } from "./lifecycle-invocations.js";
+import { prepareJsonSchema, prepareOutputFile } from "../cli/input-preparation.js";
 import crypto from "node:crypto";
+import { withStageSettlement, prepareFlowRunStageAttachment, prepareFlowRunStageCompletion } from "./runs.js";
 import fs from "node:fs";
 import path from "node:path";
 import { AppError } from "../shared/errors.js";
-import { effectiveCheckDeclarations, readCodeCheckProfile, validateCheckDeclaration, validateCheckPlacement, validateCodeCheckCommands } from "./code-checks.js";
+import { effectiveCheckDeclarations, readCodeCheckProfile, validateCheckDeclaration, validateCheckPlacement, validateCodeCheckCommands, validateTerminatingCheckCommand } 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";
+import { bindRunningWorkSession, bindStageCoordinatorWork, ensureWorkRegistry, refreshRunWorkProjection, validateWorkBatch } from "./work-registry.js";
 import { flowCommand, stagePauseCommand, stagePauseCommandTemplate } from "./stage-pause.js";
 import { assertStageStartHookEvent } from "./hooks.js";
 import { requireVnextWorkspaceRoute } from "./vnext-workspace-policy.js";
 import { readVnextSpecifyResult } from "./vnext-specify.js";
 import { nextWorkId } from "./ids.js";
 import { vnextStageDirectory } from "../domain/stage-catalog.js";
-import { writeStageReport } from "./stage-report-renderer.js";
-import { applyExternalStageContext } from "./stage-context.js";
+import { acceptStageReport, prepareStageReport } from "./stage-report-renderer.js";
+import { currentStagePrompt, applyExternalStageContext, prepareExternalStageContext } from "./stage-context.js";
 import { subagentCapacityKey } from "./vnext-fanout.js";
+import { stageLifecycleInstruction } from "../harness-runtime/lib/delegation-instructions.mjs";
+import { prepareRunVerificationMatrix, acceptVerificationMatrix, commitVerificationMatrixStart, verificationMatrixInstruction } from "./verification-matrix.js";
+import { stageSuccessor } from "./vnext-contracts.js";
 export function isVnextPlanRun(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     return Boolean(context.db.get("SELECT id FROM runs WHERE project_id = ? AND id = ? AND flow_kind = 'vnext_protocolize'", [project.id, input.runId]));
 }
-export function startVnextPlan(context, input) {
-    ensureWorkRegistry(context);
+export function prepareVnextPlanStart(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const project = requireProjectByRoot(context, projectRoot);
     const run = requireRun(context, projectRoot, input.runId);
     const home = requireHome(run);
-    assertStageStartHookEvent(context, { projectId: project.id, eventKey: input.hookEventId, runId: run.id, stage: "plan", projectRoot, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
-    const workspaceRoute = requireVnextWorkspaceRoute({ projectRoot, runId: run.id, runHome: home, workspaceRoot: run.workspace_root, stage: "plan" });
+    const workspaceRoute = requireVnextWorkspaceRoute(context, { projectRoot, runId: run.id, runHome: home, workspaceRoot: run.workspace_root, stage: "plan" });
     const protocols = protocolIds(home);
     if (!protocols.length)
-        throw new AppError("not_found", "PLAN requires accepted PROTOCOLIZE protocols", 1);
+        throw new AppError("runtime_artifact_missing", "PLAN requires accepted PROTOCOLIZE protocols", 1);
     // Static inputs are checked before PLAN creates a Work or materializes a
-    // draft. A rejected start is therefore side-effect free and safe to retry.
+    // draft. Retained corruption is still an infrastructure failure, not a typo.
     const template = read(path.join(projectRoot, ".memory-bank", "dd-flow", "vnext", "plan.md"));
     assertProtocolWorkspace(run.workspace_root, protocols);
     const { profile: codeCheckProfile } = readCodeCheckProfile(run.workspace_root);
     if (context.db.get("SELECT 1 FROM works WHERE project_id = ? AND run_id = ? AND task = ? AND status = 'running'", [project.id, run.id, planTask]))
         throw new AppError("invalid_work_state", "PLAN already has a running Work", 1, { run_id: run.id });
+    const attachment = prepareFlowRunStageAttachment(context, { projectRoot, runId: run.id, stage: "plan", dir: "03-plan", status: "running", dataSchemaId: "dd-flow/protocol-plan@6" });
     const root = path.join(home, vnextStageDirectory("plan"));
-    fs.mkdirSync(root, { recursive: true });
-    const now = context.now();
+    if (input.externalContext)
+        prepareExternalStageContext({ stageRoot: root, loaded: input.externalContext });
     const rootWork = 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", [project.id, run.id]);
     if (!rootWork)
         throw new AppError("runtime_missing", "vNext RUN has no root Work", 1);
+    const planPaths = protocols.map(id => path.join(run.workspace_root, ".memory-bank", "protocol", id, "plan.json"));
+    const mapPaths = protocols.map(id => path.join(root, id, "aspect-map.json"));
+    const owned = protocolOwnership(home, protocols);
+    const identities = protocols.map(protocolId => planIdentity(home, run.id, protocolId, owned.get(protocolId) ?? []));
+    const aspects = aspectCatalog(run.workspace_root);
+    const runVariables = getFlowRunVariables(context, { projectRoot, runId: run.id });
+    const mergeRequired = runEndsAtMerge(context, projectRoot, run.id);
+    const git = gitFacts(run.workspace_root);
+    for (const file of [...planPaths, ...mapPaths, ...["stage-prompt.md", "work-context.json", "fixture-root.prompt.md"].map(name => path.join(root, name))])
+        prepareOutputFile(file);
+    const matrix = prepareRunVerificationMatrix(context, { projectId: project.id, runId: run.id, stage: "plan", role: "input", stageAttempt: attachment.attempt });
+    return { projectRoot, project, run, home, root, rootWork, workspaceRoute, protocols, template, codeCheckProfile, planPaths, mapPaths, owned, identities, aspects, runVariables, mergeRequired, git, matrix };
+}
+export function startVnextPlan(context, input, prepared = prepareVnextPlanStart(context, input)) {
+    const { projectRoot, project, run, root, rootWork, workspaceRoute, protocols, template, codeCheckProfile, planPaths, mapPaths, owned, identities, aspects, runVariables, mergeRequired, git, home } = prepared;
+    ensureWorkRegistry(context);
+    assertStageStartHookEvent(context, { projectId: project.id, eventKey: input.hookEventId, runId: run.id, stage: "plan", projectRoot, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
+    if (context.db.get("SELECT 1 FROM works WHERE project_id = ? AND run_id = ? AND task = ? AND status = 'running'", [project.id, run.id, planTask]))
+        throw new AppError("invalid_work_state", "PLAN already has a running Work", 1, { run_id: run.id });
+    prepareFlowRunStageAttachment(context, { projectRoot, runId: run.id, stage: "plan", dir: "03-plan", status: "running", dataSchemaId: "dd-flow/protocol-plan@6" }, true);
+    fs.mkdirSync(root, { recursive: true });
+    const now = context.now();
     // Imported stage fixtures have a synthetic running root with no prior agent.
     // Bind it on the first real stage start so its child PLAN Work has a real parent.
     if (!context.db.get("SELECT 1 FROM work_sessions WHERE work_id = ? LIMIT 1", [rootWork.work_id])) {
         bindRunningWorkSession(context, { workId: rootWork.work_id, hookEventId: input.hookEventId, promptPath: path.join(root, "fixture-root.prompt.md") });
     }
-    context.db.exec("BEGIN IMMEDIATE");
-    let planWorkId;
-    try {
-        planWorkId = nextWorkId(context, project.id, "plan");
+    const planWorkId = context.db.writeTransaction(() => {
+        if (context.db.get("SELECT 1 FROM works WHERE project_id = ? AND run_id = ? AND task = ? AND status = 'running'", [project.id, run.id, planTask]))
+            throw new AppError("invalid_work_state", "PLAN already has a running Work", 1, { run_id: run.id });
+        const planWorkId = nextWorkId(context, project.id, "plan");
         context.db.run(`INSERT INTO works (work_id, project_id, run_id, parent_work_id, task, launch_policy, result_schema, depends_on_json, status, result, started_at, created_at, updated_at, completed_at) VALUES (?, ?, ?, ?, ?, 'reuse_allowed', NULL, '[]', 'running', NULL, ?, ?, ?, NULL)`, [planWorkId, project.id, run.id, rootWork.work_id, planTask, now, now, now]);
-        context.db.exec("COMMIT");
-    }
-    catch (error) {
-        context.db.exec("ROLLBACK");
-        throw error;
-    }
+        return planWorkId;
+    });
     // A Desktop task may start above the materialized repository.  Lifecycle
     // prompts therefore hand agents write targets as absolute paths: relative
     // `.memory-bank/...` paths would otherwise silently land in the parent cwd.
-    const planPaths = protocols.map((id) => path.join(run.workspace_root, ".memory-bank", "protocol", id, "plan.json"));
-    const mapPaths = protocols.map((id) => `${path.join(root, id, "aspect-map.json")}`);
-    const owned = protocolOwnership(home, protocols);
-    const identities = protocols.map((protocolId) => planIdentity(home, run.id, protocolId, owned.get(protocolId) ?? []));
     planPaths.forEach((file, index) => ensurePlanSkeleton(file, protocols[index], identities[index]));
-    mapPaths.forEach((file, index) => ensureAspectMapSkeleton(file, protocols[index], identities[index], run.workspace_root));
-    const finishCommand = `${flowCommand(context)} stage finish ${run.id} --stage plan --project-root ${JSON.stringify(projectRoot)} --json`;
+    mapPaths.forEach((file, index) => ensureAspectMapSkeleton(file, protocols[index], identities[index], aspects));
+    const finishCommand = managedLifecycleCommand(context, `${flowCommand(context)} stage finish ${run.id} --stage plan --project-root ${JSON.stringify(projectRoot)} --json`);
     const pauseCommand = stagePauseCommand(context, { runId: run.id, stage: "plan", workId: planWorkId, projectRoot });
     const pauseCommandTemplate = stagePauseCommandTemplate(pauseCommand);
     const validationCommands = protocols.flatMap((_, index) => [
         `${flowCommand(context)} schema validate --schema vnext-protocol-plan --file ${JSON.stringify(planPaths[index])} --project-root ${JSON.stringify(run.workspace_root)} --run ${run.id} --json`,
         `${flowCommand(context)} schema validate --schema plan-aspect-map --file ${JSON.stringify(mapPaths[index])} --project-root ${JSON.stringify(run.workspace_root)} --run ${run.id} --json`
     ]);
-    const runVariables = getFlowRunVariables(context, { projectRoot, runId: run.id });
     const measuredCapacity = runVariables.variables[subagentCapacityKey];
-    const mergeRequired = runEndsAtMerge(context, projectRoot, run.id);
+    const planReviewMode = requestedPlanReviewMode(context, project.id, run.id);
     const capacityContext = typeof measuredCapacity === "number" && Number.isInteger(measuredCapacity) && measuredCapacity >= 0
         ? `- The qualified reviewer capacity is ${measuredCapacity}. This is a runtime fact for later PLAN-REVIEW dispatch; do not repeat qualification or invent a different value.`
         : "- Reviewer capacity is not qualified yet. PLAN must not qualify or launch reviewers; an external harness controller supplies it before fan-out.";
     const reviewGroupingRule = "Group only semantically compatible applicable aspects, preserving real trust, irreversible, high-risk and hard-dependency boundaries. Prefer the fewest groups that retain independent review value, normally one review wave. Put two or three compatible aspects in a group; do not create one group per aspect merely for convenience. A later PLAN-REVIEW dispatch uses externally qualified capacity to schedule these semantic groups into waves; do not invent a capacity value here.";
-    const checkProfile = path.join(run.workspace_root, ".memory-bank", "spec", "engineering", "code-check-profile.json");
     const policyMergeAliases = codeCheckProfile?.mandatory_by_gate.merge ?? [];
     const mergeContract = mergeRequired
         ? ["<merge_gate_contract>", ...(policyMergeAliases.length
                 ? [`This RUN must reach MERGE. Project policy already supplies the mandatory merge gate${policyMergeAliases.length === 1 ? "" : "s"}: ${policyMergeAliases.join(", ")}. Do not duplicate them in semantic checks[]. Add another merge check only when the task genuinely needs additional evidence.`]
                 : ["This RUN must reach MERGE and project policy supplies no merge gate. Select at least one real top-level checks[] entry with run_at: merge. It may use an existing project alias or a planned alias materialised by a named P* provider Work. This is a planning obligation: do not defer it to CODE-REVIEW or MERGE."]), "The CLI validates the effective merge gate but never invents one or migrates an incompatible project policy.", "</merge_gate_contract>", ""]
         : [];
-    const prompt = ["<stage_identity>", `- RUN: ${run.id}`, `- Work: ${planWorkId}`, "- stage: plan", "</stage_identity>", "", "<trusted_runtime_context>", "These facts were collected by dd-flow. Trust them; do not repeat CLI, Git, compatibility or permission discovery.", `- Project root: ${projectRoot}`, `- Workspace: ${run.workspace_root}`, `- Stage workspace: ${root}`, `- Git: ${JSON.stringify(gitFacts(run.workspace_root))}`, capacityContext, "</trusted_runtime_context>", "", "<workspace_contract>", `- route: ${workspaceRoute.route}`, `- feature branch: ${workspaceRoute.feature_branch ?? "not applicable"}`, `- base commit: ${workspaceRoute.base_ref ?? "not applicable"}`, `- write workspace: ${run.workspace_root}`, "The CLI has verified this frozen route. All project reads and writes for PLAN and later CODE happen in the write workspace; project root is only the stable runtime identity for lifecycle commands. Do not create, switch, merge or delete branches/worktrees.", "Keep the task runner's current cwd. Use the absolute paths in this packet instead of trying to set the provisioned workspace as a tool workdir.", "</workspace_contract>", "", "<accepted_inputs>", `- ${path.join(home, "01-specify", "specify.json")}`, `- ${path.join(home, "02-protocolize", "protocolize-result.json")}`, ...protocols.map((id) => `- ${path.join(run.workspace_root, ".memory-bank", "protocol", id, "summary.md")}`), "</accepted_inputs>", "", ...(fs.existsSync(checkProfile) ? ["<code_check_policy>", "You, not the CLI, select evidence for every accepted requirement and acceptance criterion. The profile only lists reusable aliases, mandatory project policy gates and guarded raw command prefixes. Inspect relevant package/test manifests before choosing a check. Do not classify checks by weight and do not omit a needed check because it looks expensive.", fs.readFileSync(checkProfile, "utf8").trim(), "</code_check_policy>", ""] : []), ...mergeContract, "<artifacts>", "The CLI has already materialized every artifact below as a partially filled draft. Edit these files in place; do not create replacements elsewhere.", "Prefilled and CLI-owned plan fields: schema_id, plan_id, protocol_id, initial revision and source_refs.", "Prefilled and CLI-owned aspect-map fields: schema_id, protocol_id, plan_id, plan revision, catalog_ref and every catalog aspect_id.", "You own the remaining semantic fields. Empty or missing semantic values are intentional draft markers and must be completed before validation.", ...planPaths.map((value) => `- partially filled plan: ${value}`), ...mapPaths.map((value) => `- partially filled aspect map: ${value}`), "</artifacts>", "", "<output_contract>", "Complete every named plan and aspect map in place. Do not create or edit code-work-batch.json: dd-flow derives it after validation.", "The CLI owns schema_id, plan_id, protocol_id, revision and source_refs. Preserve them exactly.", "Use protocol-plan@6. Its top-level checks[] is the single check catalog. Every check has id, command, purpose, run_at and availability. available means executable now. planned means one named P* Work first creates a NEW @check/... alias: planned therefore always needs provided_by and the exact alias definition. Every semantic @check alias, including an existing one, repeats its exact accepted profile command in definition so later stages can detect drift. Items and acceptance entries use check_refs only; never duplicate command declarations.", "For each R-* and AC-*, choose an actually relevant proof: an existing focused test, a new planned alias plus its provider Work, a project policy gate, or an honestly limited external/manual proof. Every plan item needs at least one check_ref. The CLI validates ids, provider ordering, materialization and guarded command policy; it never chooses a check for you. A provider Work may verify itself with the alias it has just created. A consumer must depend on that provider.", "Each plan item must name concrete existing source/test paths in required_read. planned_write_areas is optional: use stable component directories or files only when they help coordinate parallel Work; it is never a write allowlist. Reference every owned R-* and AC-* in one or more items; every AC-* needs an observable acceptance proof.", "For every selected check, inspect its command's launch path and the runtime entrypoints it starts. The fixture/reset process, service process and client process must observe one intended environment and data world. If a required runtime entrypoint needs a code change, make that change explicit in the Work task and its verification. Use planned_write_areas only to advertise likely concurrent overlap; do not treat it as ownership or assume another Work will repair an omitted change. If an independent infrastructure Work is clearer, plan that Work explicitly and order consumers after it.", reviewGroupingRule, "Complete compact contract and schema paths:", `- protocol plan schema: ${path.join(run.workspace_root, ".memory-bank", "dd-flow", "schemas", "vnext-protocol-plan.schema.json")}`, `- aspect map schema: ${path.join(run.workspace_root, ".memory-bank", "dd-flow", "schemas", "plan-aspect-map.schema.json")}`, "Minimal valid protocol-plan shape:", "```json", JSON.stringify(planExample(protocols[0]), null, 2), "```", "Minimal valid aspect-map shape:", "```json", JSON.stringify(aspectMapExample(protocols[0]), null, 2), "```", "</output_contract>", "", "<execution_commands>", "PLAN never launches independent reviewers or registers CODE Work.", "If PLAN needs a material user decision with no reasonable default, run this exact one-command heredoc, replacing only its placeholder body. The heredoc is the permitted stdin form; do not use cat, a pipe, a temporary file or a second shell command:", "```sh", pauseCommandTemplate, "```", "Ask the returned user_message, stop, and resume this same PLAN Work with the exact returned command.", "Validate both partially filled drafts after completing their semantic fields:", ...validationCommands.map((command) => `- ${command}`), "Finish PLAN only after all questions are resolved and both validation commands pass:", finishCommand, "The response returns the only PLAN-REVIEW start command. Follow it; do not start CODE directly.", "</execution_commands>", "", "<stage_instructions>", template, "</stage_instructions>", ""].join("\n");
+    const prompt = ["<stage_identity>", `- RUN: ${run.id}`, `- Work: ${planWorkId}`, "- stage: plan", "</stage_identity>", "", "<trusted_runtime_context>", "These facts were collected by dd-flow. Trust them; do not repeat CLI, Git, compatibility or permission discovery.", `- Project root: ${projectRoot}`, `- Workspace: ${run.workspace_root}`, `- Stage workspace: ${root}`, `- Git: ${JSON.stringify(git)}`, capacityContext, "</trusted_runtime_context>", "", "<workspace_contract>", `- route: ${workspaceRoute.route}`, `- feature branch: ${workspaceRoute.feature_branch ?? "not applicable"}`, `- base commit: ${workspaceRoute.base_ref ?? "not applicable"}`, `- write workspace: ${run.workspace_root}`, "The CLI has verified this frozen route. All project reads and writes for PLAN and later CODE happen in the write workspace; project root is only the stable runtime identity for lifecycle commands. Do not create, switch, merge or delete branches/worktrees.", "Keep the task runner's current cwd. Use the absolute paths in this packet instead of trying to set the provisioned workspace as a tool workdir.", "</workspace_contract>", "", "<accepted_inputs>", `- ${path.join(home, "01-specify", "specify.json")}`, `- ${path.join(home, "02-protocolize", "protocolize-result.json")}`, ...protocols.map((id) => `- ${path.join(run.workspace_root, ".memory-bank", "protocol", id, "summary.md")}`), "</accepted_inputs>", "", ...(codeCheckProfile ? ["<code_check_policy>", "You, not the CLI, select evidence for every accepted requirement and acceptance criterion. The profile only lists reusable aliases, mandatory project policy gates and guarded raw command prefixes. Inspect relevant package/test manifests before choosing a check. Do not classify checks by weight and do not omit a needed check because it looks expensive.", JSON.stringify(codeCheckProfile, null, 2), "</code_check_policy>", ""] : []), ...mergeContract, "<artifacts>", "The CLI has already materialized every artifact below as a partially filled draft. Edit these files in place; do not create replacements elsewhere.", "Prefilled and CLI-owned plan fields: schema_id, plan_id, protocol_id, initial revision and source_refs.", "Prefilled and CLI-owned aspect-map fields: schema_id, protocol_id, plan_id, plan revision, catalog_ref and every catalog aspect_id.", "You own the remaining semantic fields. Empty or missing semantic values are intentional draft markers and must be completed before validation.", ...planPaths.map((value) => `- partially filled plan: ${value}`), ...mapPaths.map((value) => `- partially filled aspect map: ${value}`), "</artifacts>", "", "<output_contract>", "Complete every named plan and aspect map in place. Do not create or edit code-work-batch.json: dd-flow derives it after validation.", "The CLI owns schema_id, plan_id, protocol_id, revision and source_refs. Preserve them exactly.", planCheckInstruction, "For each R-* and AC-*, choose an actually relevant proof: an existing focused test, a new planned alias plus its provider Work, a project policy gate, or an autonomous executable check. Every plan item needs at least one check_ref. The CLI validates ids, provider ordering, materialization and guarded command policy; it never chooses a check for you. A provider Work may verify itself with the alias it has just created. A consumer must depend on that provider.", "Each check must terminate and return an exit status. Never declare a bare dev/start/serve/watch service command as a check; use a finite test that manages its own service lifecycle (for example, a browser test with a webServer fixture).", "Each plan item must name concrete existing source/test paths in required_read. planned_write_areas is optional: use stable component directories or files only when they help coordinate parallel Work; it is never a write allowlist. Reference every owned R-* and AC-* in one or more items; every AC-* needs an observable acceptance proof.", "For every selected check, inspect its command's launch path and the runtime entrypoints it starts. The fixture/reset process, service process and client process must observe one intended environment and data world. If a required runtime entrypoint needs a code change, make that change explicit in the Work task and its verification. Use planned_write_areas only to advertise likely concurrent overlap; do not treat it as ownership or assume another Work will repair an omitted change. If an independent infrastructure Work is clearer, plan that Work explicitly and order consumers after it.", reviewGroupingRule, "Complete compact contract and schema paths:", `- protocol plan schema: ${path.join(run.workspace_root, ".memory-bank", "dd-flow", "schemas", "vnext-protocol-plan.schema.json")}`, `- aspect map schema: ${path.join(run.workspace_root, ".memory-bank", "dd-flow", "schemas", "plan-aspect-map.schema.json")}`, "Minimal valid protocol-plan shape:", "```json", JSON.stringify(planExample(protocols[0]), null, 2), "```", "Minimal valid aspect-map shape:", "```json", JSON.stringify(aspectMapExample(protocols[0]), null, 2), "```", "</output_contract>", "", "<execution_commands>", "PLAN never launches independent reviewers or registers CODE Work.", "If PLAN needs a material user decision with no reasonable default, write the question packet to the named text file, then run the separate standalone lifecycle command below. Do not combine file creation and dd-flow in one shell command:", "```sh", pauseCommandTemplate, "```", "Ask the returned user_message, stop, and resume this same PLAN Work with the exact returned command.", "Validate both partially filled drafts after completing their semantic fields:", ...validationCommands.map((command) => `- ${command}`), "Finish PLAN only after all questions are resolved and both validation commands pass:", finishCommand, "The response returns the only PLAN-REVIEW start command. Follow it; do not start CODE directly.", "</execution_commands>", "", "<stage_instructions>", template, "</stage_instructions>", ""].join("\n");
     const artifactMaterialization = { status: "materialized", completeness: "partially_filled", plan_paths: planPaths, aspect_map_paths: mapPaths, cli_owned_plan_fields: ["schema_id", "plan_id", "protocol_id", "revision", "source_refs"], cli_owned_aspect_map_fields: ["schema_id", "protocol_id", "plan_id", "plan_revision", "catalog_ref", "aspects[].aspect_id"], validation_commands: validationCommands };
     const promptPath = path.join(root, "stage-prompt.md");
-    fs.writeFileSync(promptPath, prompt);
-    const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
+    // This explicit final rule supersedes historical pack wording: a flow gate
+    // has only executable autonomous evidence. Human or external confirmation
+    // is neither a check nor a permitted completion condition.
+    const reviewModeRule = planReviewMode === "standard" || planReviewMode === "deep"
+        ? `PLAN-REVIEW mode is ${planReviewMode}: assign at least one genuinely applicable aspect to a review group. Small feature size alone does not make every aspect not applicable; PLAN finish rejects an empty review set.`
+        : `PLAN-REVIEW mode is ${planReviewMode}: include review groups only for genuinely applicable aspects; an empty set is allowed.`;
+    fs.writeFileSync(promptPath, `${prompt}\n<review_mode_rule>${reviewModeRule}</review_mode_rule>\n<verification_rule>Every flow check must be an autonomous executable command. Do not declare external/manual proof or a human review as a check, evidence substitute, DEF, or gate. The only user interaction supported by this flow is an explicit stage pause for a material unanswered question.</verification_rule>\n${stageLifecycleInstruction}\n`);
+    const externalContext = applyExternalStageContext({ context, stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
+    if (prepared.matrix)
+        fs.appendFileSync(promptPath, verificationMatrixInstruction(prepared.matrix.metadata, home, "designing the source PLAN and its tests"));
     fs.writeFileSync(path.join(root, "work-context.json"), JSON.stringify({ schema_id: "dd-flow/work-context@1", system: { run_id: run.id, work_id: planWorkId, stage: "plan" }, workspace: { project_root: projectRoot, workspace_root: run.workspace_root, stage_root: root }, artifacts: artifactMaterialization, input: { protocols, owned_obligations: Object.fromEntries(owned) } }, null, 2));
     const binding = bindStageCoordinatorWork(context, { workId: planWorkId, hookEventId: input.hookEventId, stage: "plan", promptPath, resultPath: path.join(root, "stage-report.json"), ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
-    attachFlowRunStage(context, { projectRoot, runId: run.id, stage: "plan", dir: "03-plan", status: "running", dataSchemaId: "dd-flow/protocol-plan@6" });
+    const attachmentInput = { projectRoot, runId: run.id, stage: "plan", dir: "03-plan", status: "running", dataSchemaId: "dd-flow/protocol-plan@6" };
+    const attachment = prepareFlowRunStageAttachment(context, attachmentInput);
+    commitVerificationMatrixStart(context, prepared.matrix, () => attachFlowRunStage(context, attachmentInput, attachment));
     const workSessionId = String(binding.work_session_id);
     const sessionId = String(binding.session_id);
     refreshRunWorkProjection(context, project.id, run.id);
     appendFlowRunTimelineEvent(context, project.id, run.id, { type: "work_session_started", stage: "plan", work_id: planWorkId, id: workSessionId, session_id: sessionId });
-    return { ok: true, run_id: run.id, work_id: planWorkId, id: workSessionId, artifact_materialization: artifactMaterialization, worker_prompt_markdown: fs.readFileSync(promptPath, "utf8"), prompt_path: promptPath, next_command: finishCommand, ...(externalContext ? { external_context: externalContext } : {}) };
+    return { ok: true, run_id: run.id, work_id: planWorkId, id: workSessionId, artifact_materialization: artifactMaterialization, ...currentStagePrompt(context, promptPath), next_command: finishCommand, ...(externalContext ? { external_context: externalContext } : {}) };
+}
+export function prepareVnextPlanFinish(context, input) {
+    const projectRoot = resolveProjectRoot(input.projectRoot);
+    const run = requireRun(context, projectRoot, input.runId), home = requireHome(run);
+    requireVnextWorkspaceRoute(context, { projectRoot, runId: run.id, runHome: home, workspaceRoot: run.workspace_root, stage: "plan" });
+    const protocols = protocolIds(home);
+    assertProtocolWorkspace(run.workspace_root, protocols);
+    const prepared = prepareVnextPlanArtifacts(context, { projectRoot, workspaceRoot: run.workspace_root, runId: run.id, home, protocols });
+    if (prepared.failures.length)
+        throw new AppError("validation", "PLAN artifacts have validation errors", 2, { errors: prepared.failures, phase: "prepare", effect: "no_effect", recoverable: true });
+    return prepared;
 }
 export function finishVnextPlan(context, input) {
+    return finishVnextPlanOwned(context, input);
+}
+function finishVnextPlanOwned(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const project = requireProjectByRoot(context, projectRoot);
     const run = requireRun(context, projectRoot, input.runId);
     const home = requireHome(run);
     const root = path.join(home, "03-plan");
-    requireVnextWorkspaceRoute({ projectRoot, runId: run.id, runHome: home, workspaceRoot: run.workspace_root, stage: "plan" });
+    requireVnextWorkspaceRoute(context, { projectRoot, runId: run.id, runHome: home, workspaceRoot: run.workspace_root, stage: "plan" });
     const protocols = protocolIds(home);
     if (!protocols.length)
-        throw new AppError("not_found", "PLAN requires accepted PROTOCOLIZE protocols", 1);
+        throw new AppError("runtime_artifact_missing", "PLAN requires accepted PROTOCOLIZE protocols", 1);
     assertProtocolWorkspace(run.workspace_root, protocols);
     const planFiles = protocols.map((id) => path.join(run.workspace_root, ".memory-bank", "protocol", id, "plan.json"));
     const mapFiles = protocols.map((id) => path.join(root, id, "aspect-map.json"));
     const batch = path.join(root, "code-work-batch.json");
-    const failures = validateVnextPlanArtifacts(context, { projectRoot, workspaceRoot: run.workspace_root, runId: run.id, home, protocols });
-    if (failures.length)
-        throw new AppError("validation", "PLAN artifacts have validation errors", 2, { errors: failures });
+    const prepared = input.prepared ?? prepareVnextPlanFinish(context, input);
+    if (prepared.failures.length)
+        throw new AppError("validation", "PLAN artifacts have validation errors", 2, { errors: prepared.failures, phase: "prepare", effect: "no_effect", recoverable: true });
     const work = context.db.get("SELECT work_id FROM works WHERE project_id = ? AND run_id = ? AND task = ? AND status = 'running' ORDER BY created_at DESC LIMIT 1", [project.id, run.id, planTask]);
     if (!work)
         throw new AppError("invalid_work_state", "PLAN has no running Work", 1);
-    const now = context.now();
-    const batchChecksum = checksum(batch);
-    context.db.run("UPDATE works SET status = 'completed', result = ?, completed_at = ?, updated_at = ? WHERE work_id = ?", ["PLAN accepted; awaiting PLAN-REVIEW", now, now, work.work_id]);
     const workSession = context.db.get("SELECT id, session_id FROM work_sessions WHERE work_id = ? AND status = 'running' ORDER BY created_at DESC LIMIT 1", [work.work_id]);
     if (!workSession?.session_id)
         throw new AppError("trusted_session_binding_required", "PLAN finish requires its bound Agent WorkSession", 1, { work_id: work.work_id });
-    context.db.run("UPDATE work_sessions SET status = 'completed', result_path = ?, updated_at = ?, completed_at = ? WHERE id = ?", [path.join(root, "stage-report.json"), now, now, workSession.id]);
-    refreshRunWorkProjection(context, project.id, run.id);
-    const reviewCommand = `${flowCommand(context)} stage start ${run.id} --stage plan-review --project-root ${JSON.stringify(projectRoot)} --json`;
-    const report = { schema_id: "dd-flow/stage-report@1", run_id: run.id, stage: "plan", generated_at: now, verdict: "done", semantic: { result: `Accepted ${protocols.length} executable PLAN artifact${protocols.length === 1 ? "" : "s"}.`, acceptance: protocols, changed_files: [...planFiles.map((file) => path.relative(projectRoot, file)), ...mapFiles.map((file) => runRef(run.id, home, file)), runRef(run.id, home, batch)], checks: ["protocol-plan schema", "aspect-map schema", "cross-artifact references", "generated CODE batch"], evidence: [runRef(run.id, home, path.join(root, "stage-report.json"))], next_action: "start_plan_review", plans: planFiles.map((file) => path.relative(projectRoot, file)), aspect_maps: mapFiles.map((file) => runRef(run.id, home, file)), code_work_batch: runRef(run.id, home, batch), batch_checksum: batchChecksum }, mechanical: { started_at: stageStartedAt(home, now), finished_at: now, wall_clock_ms: Math.max(0, Date.parse(now) - Date.parse(stageStartedAt(home, now))), 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`, next_command: reviewCommand }, artifacts: { json: "stage-report.json", markdown: "stage-report.md", html: "stage-report.html", summary: "stage-report.md" }, validation: { permission_scope: "known_targets_only", memory_bank_scope: "changed_files_and_links_only", status: "passed" } };
-    const reportJson = writeStageReport(root, report).json;
-    validateSchema({ schemaName: "stage-report", file: reportJson, projectRoot, ddFlowHome: context.ddFlowHome, runId: run.id, runRoot: home });
-    completeFlowRunStage(context, { projectRoot, runId: run.id, stage: "plan", status: "done", data: "stage-report.json", dataSchemaId: "dd-flow/stage-report@1", report: "stage-report.md", stageReport: "stage-report.html" });
-    advanceFlowRun(context, { projectRoot, runId: run.id, status: "running", verdict: "planned", nextAction: "start_plan_review" });
-    appendFlowRunTimelineEvent(context, project.id, run.id, { type: "plan_accepted", work_id: work.work_id, protocols, id: workSession.id, next_stage: "plan-review" });
-    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 } };
+    prepared.publish();
+    const now = context.now();
+    const batchChecksum = checksum(batch);
+    const next = stageSuccessor(context, { projectRoot, runId: run.id, stage: "plan-review", command: `${flowCommand(context)} stage start ${run.id} --stage plan-review --project-root ${JSON.stringify(projectRoot)} --json` });
+    const startedAt = stageStartedAt(home, now);
+    const report = { schema_id: "dd-flow/stage-report@1", run_id: run.id, stage: "plan", generated_at: now, verdict: "done", semantic: { result: `Accepted ${protocols.length} executable PLAN artifact${protocols.length === 1 ? "" : "s"}.`, acceptance: protocols, changed_files: [...planFiles.map((file) => path.relative(projectRoot, file)), ...mapFiles.map((file) => runRef(run.id, home, file)), runRef(run.id, home, batch)], checks: ["protocol-plan schema", "aspect-map schema", "cross-artifact references", "generated CODE batch"], evidence: [runRef(run.id, home, path.join(root, "stage-report.json"))], next_action: "start_plan_review", plans: planFiles.map((file) => path.relative(projectRoot, file)), aspect_maps: mapFiles.map((file) => runRef(run.id, home, file)), code_work_batch: runRef(run.id, home, batch), batch_checksum: batchChecksum }, 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`, ...(next.command ? { next_command: next.command } : {}) }, artifacts: { json: "stage-report.json", markdown: "stage-report.md", html: "stage-report.html", summary: "stage-report.md" }, validation: { permission_scope: "known_targets_only", memory_bank_scope: "changed_files_and_links_only", status: "passed" } };
+    Object.assign(report.semantic, {
+        plan_checksums: planFiles.map((file) => ({ path: path.relative(run.workspace_root, file).split(path.sep).join("/"), sha256: checksum(file) })),
+        aspect_map_checksums: mapFiles.map((file) => ({ path: path.relative(home, file).split(path.sep).join("/"), sha256: checksum(file) }))
+    });
+    const matrix = prepareRunVerificationMatrix(context, { projectId: project.id, runId: run.id, stage: "plan", role: "output" });
+    if (matrix)
+        Object.assign(report.semantic, { verification_matrix: matrix.metadata });
+    const preparedReport = prepareStageReport(report);
+    validateSchema({ schemaName: "stage-report", file: path.join(root, "stage-report.json"), data: preparedReport.normalized, projectRoot, ddFlowHome: context.ddFlowHome, runId: run.id, runRoot: home });
+    const completionInput = { projectRoot, runId: run.id, stage: "plan", status: "done", data: "stage-report.json", dataSchemaId: "dd-flow/stage-report@1", report: "stage-report.md", stageReport: "stage-report.html", dataSha256: preparedReport.sha256, git: report.mechanical.git };
+    const preparedCompletion = prepareFlowRunStageCompletion(context, completionInput);
+    return withStageSettlement(context, () => {
+        const current = context.db.get("SELECT status FROM works WHERE work_id = ?", [work.work_id]);
+        if (current?.status !== "running")
+            throw new AppError("invalid_work_state", "PLAN Work changed during finish preparation", 1);
+        context.db.run("UPDATE works SET status = 'completed', result = ?, completed_at = ?, updated_at = ? WHERE work_id = ?", ["PLAN accepted; awaiting PLAN-REVIEW", now, now, work.work_id]);
+        context.db.run("UPDATE work_sessions SET status = 'completed', result_path = ?, updated_at = ?, completed_at = ? WHERE id = ?", [path.join(root, "stage-report.json"), now, now, workSession.id]);
+        acceptVerificationMatrix(context, matrix);
+        acceptStageReport(context, { projectId: project.id, runId: run.id, stage: "plan", root, prepared: preparedReport });
+        completeFlowRunStage(context, completionInput, preparedCompletion);
+        refreshRunWorkProjection(context, project.id, run.id);
+        advanceFlowRun(context, { settlementStage: "plan", projectRoot, runId: run.id, status: "running", verdict: "planned", nextAction: "start_plan_review" });
+        appendFlowRunTimelineEvent(context, project.id, run.id, { type: "plan_accepted", work_id: work.work_id, protocols, id: workSession.id, next_stage: "plan-review" });
+        return { ok: true, run_id: run.id, protocols, next_action: "start_plan_review", ...(next.command ? { next_command: next.command } : {}), next };
+    });
 }
 export function validateVnextPlanArtifacts(context, input) {
+    // Validation never repairs or republishes accepted artifacts. PLAN and
+    // PLAN-REVIEW finish explicitly publish their prepared projection on accept.
+    return prepareVnextPlanArtifacts(context, { ...input, publishBatch: false }).failures;
+}
+/** Validate in memory; 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"));
+    let reviewGroupCount = 0;
     const batch = path.join(input.home, "03-plan", "code-work-batch.json");
     const ownership = protocolOwnership(input.home, input.protocols);
     const obligations = acceptedObligations(input.home);
+    const mergeEnding = runEndsAtMerge(context, input.projectRoot, input.runId);
     const frozenDocumentBaselines = input.publishBatch === false && fs.existsSync(batch)
         ? new Map(readJson(batch).works?.flatMap((work) => typeof work.key === "string" ? (work.document_updates ?? []).flatMap((update) => typeof update.path === "string" && (typeof update.baseline_sha256 === "string" || update.baseline_sha256 === null)
             ? [[`${work.key}\u0000${update.path}`, update.baseline_sha256]]
             : []) : []) ?? [])
         : undefined;
     const failures = [];
+    const publications = new Map();
     const plans = [];
     for (const [index, file] of planFiles.entries()) {
         const protocolId = input.protocols[index];
         try {
-            validateSchema({ schemaName: "vnext-protocol-plan", file, projectRoot: workspaceRoot, ddFlowHome: context.ddFlowHome, runId: input.runId, runRoot: input.home });
-            const value = readPlan(file);
+            const { value } = prepareJsonSchema(file, "PLAN", { schemaName: "vnext-protocol-plan", projectRoot: workspaceRoot, ddFlowHome: context.ddFlowHome, runId: input.runId, runRoot: input.home });
             assertPlanIdentity(value, planIdentity(input.home, input.runId, protocolId, ownership.get(protocolId) ?? []), file);
-            validatePlanSemantics(file, new Set(ownership.get(protocolId) ?? []), obligations);
+            validatePlanSemantics(file, value, new Set(ownership.get(protocolId) ?? []), obligations, mergeEnding);
             validateCodeCheckCommands(workspaceRoot, value.checks.filter((check) => check.availability === "available").map((check) => check.command));
             for (const check of value.checks.filter((item) => item.availability === "available"))
                 validateCheckDeclaration(workspaceRoot, check);
+            for (const check of value.checks.filter((item) => item.availability === "planned" && item.definition))
+                validateTerminatingCheckCommand(check.definition, check.id);
             // Placement is a PLAN-time rule. A Work may legitimately materialize a
             // new aggregate alias later, so rechecking against the changed profile
             // at CODE entry would retroactively invalidate an accepted plan.
@@ -179,14 +249,25 @@ export function validateVnextPlanArtifacts(context, input) {
     }
     for (const file of mapFiles) {
         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 source = prepareJsonSchema(file, "PLAN aspect map", { schemaName: "plan-aspect-map", projectRoot: workspaceRoot, ddFlowHome: context.ddFlowHome, runId: input.runId, runRoot: input.home }).text;
+            const bytes = normalizedAspectMapRefs(file, source, workspaceRoot, input.home, input.runId);
+            if (input.publishBatch === false && bytes !== source)
+                throw new AppError("validation", "Accepted aspect-map requires normalization; regenerate it in PLAN", 2, { file });
+            const value = JSON.parse(bytes);
+            validateAspectMap(file, input.protocols, workspaceRoot, value);
+            reviewGroupCount += Array.isArray(value.review_groups) ? value.review_groups.length : 0;
+            publications.set(file, bytes);
         }
         catch (error) {
             failures.push(validationFailure(file, error));
         }
     }
+    if (!failures.length && reviewGroupCount === 0) {
+        const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+        const mode = requestedPlanReviewMode(context, project.id, input.runId);
+        if (mode === "standard" || mode === "deep")
+            failures.push(validationFailure(mapFiles[0] ?? batch, new AppError("validation", "Configured PLAN-REVIEW requires at least one applicable aspect and review group in the PLAN map", 2, { mode })));
+    }
     if (!failures.length) {
         try {
             validatePsetCheckIdentity(plans);
@@ -197,35 +278,52 @@ export function validateVnextPlanArtifacts(context, input) {
         }
     }
     if (!failures.length) {
-        const temporaryBatch = `${batch}.tmp-${crypto.randomUUID()}`;
         try {
             const projection = projectCodeWorkBatch({ home: input.home, workspaceRoot, runId: input.runId, plans, protocols: input.protocols, ...(frozenDocumentBaselines ? { frozenDocumentBaselines } : {}) });
             validateProjectedPaths(projection, workspaceRoot, input.home, input.runId);
-            fs.writeFileSync(temporaryBatch, `${JSON.stringify(projection, null, 2)}\n`);
-            validateSchema({ schemaName: "code-work-batch", file: temporaryBatch, projectRoot: workspaceRoot, ddFlowHome: context.ddFlowHome, runId: input.runId, runRoot: input.home });
-            validateWorkBatchFile(temporaryBatch);
+            const bytes = `${JSON.stringify(projection, null, 2)}\n`;
+            validateSchema({ schemaName: "code-work-batch", file: batch, data: projection, projectRoot: workspaceRoot, ddFlowHome: context.ddFlowHome, runId: input.runId, runRoot: input.home });
+            validateWorkBatch(projection);
             if (input.publishBatch !== false) {
-                fs.renameSync(temporaryBatch, batch);
+                publications.set(batch, bytes);
             }
-            else if (!fs.existsSync(batch) || checksum(temporaryBatch) !== checksum(batch)) {
+            else if (!fs.existsSync(batch) || crypto.createHash("sha256").update(bytes).digest("hex") !== checksum(batch)) {
                 throw new AppError("stale_code_work_batch", "CODE batch no longer matches the accepted semantic PLAN", 2, { batch });
             }
         }
         catch (error) {
             failures.push(validationFailure(batch, error));
         }
-        finally {
-            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) {
     return validateVnextPlanArtifacts(context, {
         ...input,
-        protocols: protocolIds(input.home),
-        publishBatch: false
+        protocols: protocolIds(input.home)
     });
 }
 const planTask = "Produce accepted plan.json and aspect-map.json artifacts.";
@@ -250,16 +348,18 @@ function assertProtocolWorkspace(workspaceRoot, protocols) {
     }
 }
 function read(file) { if (!fs.existsSync(file))
-    throw new AppError("not_found", "vNext PLAN prompt is missing", 1, { file }); return fs.readFileSync(file, "utf8"); }
+    throw new AppError("runtime_artifact_missing", "vNext PLAN prompt is missing", 1, { file }); return fs.readFileSync(file, "utf8"); }
 function readJson(file) { return JSON.parse(fs.readFileSync(file, "utf8")); }
 function checksum(file) { return crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex"); }
-function validateAspectMap(file, protocols, projectRoot) {
-    let value;
-    try {
-        value = JSON.parse(fs.readFileSync(file, "utf8"));
-    }
-    catch {
-        throw new AppError("schema_validation", "aspect-map.json must be valid JSON", 2, { file });
+function validateAspectMap(file, protocols, projectRoot, prepared) {
+    let value = prepared;
+    if (value === undefined) {
+        try {
+            value = JSON.parse(fs.readFileSync(file, "utf8"));
+        }
+        catch {
+            throw new AppError("schema_validation", "aspect-map.json must be valid JSON", 2, { file });
+        }
     }
     const map = value;
     if (map.schema_id !== "dd-flow/plan-aspect-map@3" || typeof map.protocol_id !== "string" || !protocols.includes(map.protocol_id) || !Array.isArray(map.aspects))
@@ -304,7 +404,13 @@ function stageStartedAt(home, fallback) { try {
 catch {
     return fallback;
 } }
-function validationFailure(file, error) { return { file, message: error instanceof Error ? error.message : String(error), ...(error instanceof AppError ? { code: error.code, details: error.details } : {}) }; }
+function validationFailure(file, error) {
+    // Aggregate diagnosed artifact mistakes only. Runtime/schema/storage failures
+    // must retain their original code rather than becoming a safe PLAN retry.
+    if (!(error instanceof AppError) || error.exitCode !== 2 || ["schema_not_found", "invalid_code_check_profile"].includes(error.code))
+        throw error;
+    return { file, message: error.message, code: error.code, details: error.details };
+}
 function acceptedObligations(home) {
     const file = path.join(home, "01-specify", "specify.json");
     if (!fs.existsSync(file))
@@ -341,7 +447,7 @@ function ensurePlanSkeleton(file, protocolId, identity) {
     fs.mkdirSync(path.dirname(file), { recursive: true });
     writeJson(file, { ...identity, title: "", summary: "", goal: { outcome: "", constraints: [], non_goals: [] }, assessment: {}, decisions: [], document_updates: [], checks: [], items: [], acceptance: [] });
 }
-function ensureAspectMapSkeleton(file, protocolId, identity, workspaceRoot) {
+function ensureAspectMapSkeleton(file, protocolId, identity, aspects) {
     if (fs.existsSync(file))
         return;
     fs.mkdirSync(path.dirname(file), { recursive: true });
@@ -354,10 +460,9 @@ function ensureAspectMapSkeleton(file, protocolId, identity, workspaceRoot) {
         catalog_ref: { path: ".memory-bank/dd-flow/mb-sdlc/plan-aspects/aspects" },
         routing: { initial_state: "orchestrator_local", groups: [] },
         review_groups: [],
-        aspects: aspectCatalog(workspaceRoot).map((aspectId) => ({ aspect_id: aspectId, planned_artifact_refs: [] }))
+        aspects: aspects.map((aspectId) => ({ aspect_id: aspectId, planned_artifact_refs: [] }))
     });
 }
-function readPlan(file) { return JSON.parse(fs.readFileSync(file, "utf8")); }
 function assertPlanIdentity(value, identity, file) {
     for (const key of ["schema_id", "plan_id", "protocol_id"])
         if (value[key] !== identity[key])
@@ -367,13 +472,17 @@ 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, bytes, projectRoot, runHome, runId) {
+    projectRoot = canonicalPath(projectRoot);
+    runHome = canonicalPath(runHome);
+    const map = JSON.parse(bytes);
+    if (!map || typeof map !== "object" || Array.isArray(map))
+        throw new AppError("schema_validation", "PLAN aspect map must be an object", 2, { file });
     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)
@@ -386,10 +495,9 @@ 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) {
+export function projectCodeWorkBatch(input) {
     const obligationMap = acceptedObligationMap(input.home);
     const orientation = projectOrientation(input.workspaceRoot);
     const works = input.plans.flatMap(({ protocolId, file, value }) => value.items.map((item) => {
@@ -424,10 +532,9 @@ function projectCodeWorkBatch(input) {
                 ])],
             discovery_boundary: item.execution_context.discovery_boundary,
             planned_write_areas: [...new Set([...item.execution_context.planned_write_areas, ...documentPaths])],
-            // A criterion belongs to every listed Work. Its proof must travel with
-            // those Work packets as well as item-local verification; otherwise CODE
-            // silently loses readiness/code checks declared only by acceptance.
-            checks: value.checks.filter((check) => itemCheckRefs(item, value.acceptance).includes(check.id)),
+            // CODE still needs acceptance-only aggregate declarations in its packets;
+            // work checks belong only to the item that explicitly verifies them.
+            checks: value.checks.filter((check) => itemCheckRefs(item, value.acceptance, value.checks).includes(check.id)),
             provides_checks: value.checks.filter((check) => check.availability === "planned" && check.provided_by === item.id),
             stop_conditions: item.execution_context.stop_conditions,
             depends_on: item.depends_on.map((dependency) => `${protocolId}:${dependency}`),
@@ -456,10 +563,15 @@ function projectCodeWorkBatch(input) {
     const ordered = [...works].sort((a, b) => a.key.localeCompare(b.key));
     return { schema_id: "dd-flow/code-work-batch@5", sources: input.plans.map(({ protocolId, file, value }) => ({ plan_id: value.plan_id, protocol_id: protocolId, revision: value.revision, sha256: checksum(file) })), works: ordered };
 }
-function itemCheckRefs(item, acceptance) {
-    return [...new Set([...item.verification.check_refs, ...acceptance.filter((entry) => entry.plan_item_ids.includes(item.id)).flatMap((entry) => entry.check_refs)])];
+function itemCheckRefs(item, acceptance, catalog) {
+    const aggregate = new Set(catalog.filter((check) => check.run_at !== "work").map((check) => check.id));
+    return [...new Set([...item.verification.check_refs, ...acceptance.filter((entry) => entry.plan_item_ids.includes(item.id)).flatMap((entry) => entry.check_refs.filter((ref) => aggregate.has(ref)))])];
+}
+function renderCodeTask(item, catalog, acceptance = []) {
+    const local = catalog.filter((check) => check.run_at === "work" && item.verification.check_refs.includes(check.id));
+    const aggregate = catalog.filter((check) => check.run_at !== "work" && itemCheckRefs(item, acceptance, catalog).includes(check.id));
+    return [item.title, item.summary, item.details, `Preserve: ${item.semantic_spine.must_preserve.join("; ")}`, `Work checks: ${local.map((check) => `${check.id}:${check.command}`).join("; ")}`, `Later aggregate checks (CODE/MERGE; do not run in this Work): ${aggregate.map((check) => `${check.id}:${check.command}`).join("; ")}`, `Stop: ${item.execution_context.stop_conditions.join("; ")}`].join("\n\n");
 }
-function renderCodeTask(item, catalog, acceptance = []) { const checks = catalog.filter((check) => itemCheckRefs(item, acceptance).includes(check.id)); return [item.title, item.summary, item.details, `Preserve: ${item.semantic_spine.must_preserve.join("; ")}`, `Checks: ${checks.map((check) => `${check.id}:${check.command}`).join("; ")}`, `Stop: ${item.execution_context.stop_conditions.join("; ")}`].join("\n\n"); }
 function validateProjectedPaths(batch, workspaceRoot, home, runId) {
     for (const work of batch.works) {
         for (const write of work.planned_write_areas)
@@ -503,8 +615,7 @@ function resolvePortablePath(value, workspaceRoot, home, runId) {
 }
 function writeJson(file, value) { const temporary = `${file}.${crypto.randomUUID()}.tmp`; fs.writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`); fs.renameSync(temporary, file); }
 function runRef(runId, runHome, file) { return `run://${runId}/${path.relative(runHome, file).split(path.sep).join("/")}`; }
-function validatePlanSemantics(file, ownedRefs, acceptedRefs) {
-    const plan = readPlan(file);
+function validatePlanSemantics(file, plan, ownedRefs, acceptedRefs, mergeEnding) {
     const items = plan.items ?? [];
     const ids = new Set(items.map((item) => item.id).filter((id) => Boolean(id)));
     if (ids.size !== items.length)
@@ -517,6 +628,8 @@ function validatePlanSemantics(file, ownedRefs, acceptedRefs) {
     for (const check of plan.checks ?? []) {
         if (checks.has(check.id))
             throw new AppError("validation", "PLAN check ids must be unique", 2, { file, check_id: check.id });
+        if (mergeEnding && check.run_at === "release")
+            throw new AppError("check_gate_unreachable", "A RUN ending at MERGE cannot execute RELEASE checks", 2, { file, check_id: check.id });
         if (check.availability === "planned" && (!check.provided_by || !ids.has(check.provided_by)))
             throw new AppError("planned_check_provider_missing", "A planned check must name a PLAN item that provides it", 2, { file, check_id: check.id, provided_by: check.provided_by ?? null });
         if (check.availability === "planned" && !check.command.startsWith("@check/"))
@@ -525,6 +638,8 @@ function validatePlanSemantics(file, ownedRefs, acceptedRefs) {
             throw new AppError("planned_check_definition_missing", "A planned check must declare its exact alias definition", 2, { file, check_id: check.id });
         checks.set(check.id, check);
     }
+    const localChecks = new Set(items.flatMap((item) => item.verification.check_refs));
+    const acceptanceIds = new Set();
     const ancestors = (itemId, seen = new Set()) => {
         for (const dependency of items.find((item) => item.id === itemId)?.depends_on ?? [])
             if (!seen.has(dependency)) {
@@ -548,7 +663,7 @@ function validatePlanSemantics(file, ownedRefs, acceptedRefs) {
             const check = checks.get(checkId);
             if (!check)
                 throw new AppError("check_reference_unknown", "PLAN item references an unknown check", 2, { file, item: item.id, check_id: checkId });
-            if (check.availability === "planned" && check.provided_by !== item.id && !ancestors(item.id).has(check.provided_by))
+            if (check.run_at === "work" && check.availability === "planned" && check.provided_by !== item.id && !ancestors(item.id).has(check.provided_by))
                 throw new AppError("check_consumer_not_ordered_after_provider", "A Work may consume a planned check only after its provider", 2, { file, item: item.id, check_id: checkId, provider: check.provided_by });
         }
     }
@@ -564,6 +679,11 @@ function validatePlanSemantics(file, ownedRefs, acceptedRefs) {
     for (const acceptance of plan.acceptance ?? []) {
         if (!acceptance.criterion_id || !acceptance.criterion_id.startsWith("AC-") || !ownedRefs.has(acceptance.criterion_id))
             throw new AppError("validation", "PLAN acceptance references an AC-* owned by this protocol", 2, { file, criterion_id: acceptance.criterion_id });
+        if (acceptanceIds.has(acceptance.criterion_id))
+            throw new AppError("duplicate_plan_criterion", "PLAN acceptance criterion ids must be unique within a protocol", 2, { file, criterion_id: acceptance.criterion_id });
+        acceptanceIds.add(acceptance.criterion_id);
+        if (mergeEnding && acceptance.gate === "release")
+            throw new AppError("check_gate_unreachable", "A RUN ending at MERGE cannot prove RELEASE acceptance", 2, { file, criterion_id: acceptance.criterion_id });
         for (const id of acceptance.plan_item_ids ?? [])
             if (!ids.has(id))
                 throw new AppError("validation", "PLAN acceptance references an unknown item", 2, { file, criterion_id: acceptance.criterion_id, plan_item_id: id });
@@ -571,9 +691,10 @@ function validatePlanSemantics(file, ownedRefs, acceptedRefs) {
             const check = checks.get(id);
             if (!check)
                 throw new AppError("check_reference_unknown", "PLAN acceptance references an unknown check", 2, { file, criterion_id: acceptance.criterion_id, check_id: id });
-            for (const itemId of acceptance.plan_item_ids ?? [])
-                if (check.availability === "planned" && check.provided_by !== itemId && !ancestors(itemId).has(check.provided_by))
-                    throw new AppError("check_consumer_not_ordered_after_provider", "Acceptance may consume a planned check only after its provider", 2, { file, criterion_id: acceptance.criterion_id, item: itemId, check_id: id, provider: check.provided_by });
+            if ((acceptance.gate !== "release" && check.run_at === "release") || (!["merge", "release"].includes(acceptance.gate) && check.run_at === "merge"))
+                throw new AppError("check_gate_unreachable", "PLAN acceptance references a check after its gate", 2, { file, criterion_id: acceptance.criterion_id, check_id: id, gate: acceptance.gate, run_at: check.run_at });
+            if (check.run_at === "work" && !localChecks.has(id))
+                throw new AppError("work_check_unassigned", "A work check referenced by acceptance needs an explicit verifying PLAN item", 2, { file, criterion_id: acceptance.criterion_id, check_id: id });
         }
     }
     for (const obligation of ownedRefs)
@@ -593,6 +714,10 @@ function validatePsetCheckIdentity(plans) {
             owners.set(check.id, plan.protocolId);
         }
 }
+function requestedPlanReviewMode(context, projectId, runId) {
+    const row = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
+    return JSON.parse(row?.index_json ?? "{}").settings?.plan_review?.mode ?? "auto";
+}
 function runEndsAtMerge(context, projectRoot, runId) {
     const project = requireProjectByRoot(context, resolveProjectRoot(projectRoot));
     const row = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [project.id, runId]);