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

package/dist/services/vnext-plan.js

@@ -1,10 +1,12 @@
+import { managedLifecycleCommand } from "./lifecycle-invocations.js";
 import crypto from "node:crypto";
+import { withStageSettlement } 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 { 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";
@@ -50,7 +52,7 @@ export function startVnextPlan(context, input) {
     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");
+    context.db.beginWriteTransaction();
     let planWorkId;
     try {
         planWorkId = nextWorkId(context, project.id, "plan");
@@ -70,20 +72,20 @@ export function startVnextPlan(context, input) {
     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`;
+    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)} --json`,
-        `${flowCommand(context)} schema validate --schema plan-aspect-map --file ${JSON.stringify(mapPaths[index])} --project-root ${JSON.stringify(run.workspace_root)} --json`
+        `${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 capacityContext = typeof measuredCapacity === "number" && Number.isInteger(measuredCapacity) && measuredCapacity >= 0
-        ? `- The measured reviewer capacity is ${measuredCapacity}. This is a runtime fact for later PLAN-REVIEW dispatch; do not repeat the probe or invent a different value.`
-        : "- Reviewer capacity is not measured yet. PLAN must not probe or launch reviewers; PLAN-REVIEW will measure it once if review is enabled.";
-    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 measures current capacity once and schedules these semantic groups into waves; do not invent a capacity value here.";
+        ? `- 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
@@ -91,10 +93,13 @@ export function startVnextPlan(context, input) {
                 ? [`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(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 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 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 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);
+    // 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.
+    fs.writeFileSync(promptPath, `${prompt}\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`);
     const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
     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 } : {}) });
@@ -106,6 +111,9 @@ export function startVnextPlan(context, input) {
     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 } : {}) };
 }
 export function finishVnextPlan(context, input) {
+    return withStageSettlement(context, () => finishVnextPlanOwned(context, input));
+}
+function finishVnextPlanOwned(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const project = requireProjectByRoot(context, projectRoot);
     const run = requireRun(context, projectRoot, input.runId);
@@ -133,16 +141,23 @@ export function finishVnextPlan(context, input) {
         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 reviewCommand = managedLifecycleCommand(context, `${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 });
+    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" });
+    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: 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"));
@@ -155,11 +170,12 @@ 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];
         try {
-            validateSchema({ schemaName: "vnext-protocol-plan", file, projectRoot: workspaceRoot, ddFlowHome: context.ddFlowHome, runId: input.runId });
+            validateSchema({ schemaName: "vnext-protocol-plan", file, projectRoot: workspaceRoot, ddFlowHome: context.ddFlowHome, runId: input.runId, runRoot: input.home });
             const value = readPlan(file);
             assertPlanIdentity(value, planIdentity(input.home, input.runId, protocolId, ownership.get(protocolId) ?? []), file);
             validatePlanSemantics(file, new Set(ownership.get(protocolId) ?? []), obligations);
@@ -178,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 });
-            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 {
@@ -202,10 +226,10 @@ export function validateVnextPlanArtifacts(context, input) {
             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 });
+            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 });
@@ -218,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) {
@@ -231,10 +277,10 @@ export function validateVnextCodeHandoff(context, input) {
 const planTask = "Produce accepted plan.json and aspect-map.json artifacts.";
 function planExample(protocolId) { return { schema_id: "dd-flow/protocol-plan@6", plan_id: "PLAN-001", protocol_id: protocolId, revision: 1, title: "Example", summary: "A compact executable plan.", source_refs: [{ kind: "specify", id: "SPECIFY", path: "run://RUN-000/01-specify/specify.json", requirement_ids: ["R-001", "AC-001"] }], goal: { outcome: "Deliver the accepted behavior.", constraints: ["Keep the accepted scope."], non_goals: [] }, assessment: { scope_breadth: { level: "narrow", surfaces: ["one surface"], reason: "One vertical slice." }, solution_novelty: { level: "established", surfaces: ["existing pattern"], reason: "Reuse project practice." }, solution_uncertainty: { level: "low", surfaces: ["known behavior"], reason: "No open technical question." }, failure_impact: { level: "low", surfaces: ["local feature"], reason: "Reversible local change." }, selected_depth: "compact_plan", depth_trigger: "none" }, decisions: [], document_updates: [], checks: [{ id: "CHK-P1-TEST", command: "pnpm test", purpose: "Proves the changed behavior.", run_at: "work", availability: "available" }], items: [{ id: "P1", title: "Implement behavior", summary: "Change the owning surface.", details: "Follow the accepted requirement and project conventions.", depends_on: [], requirement_refs: ["R-001", "AC-001"], semantic_spine: { user_outcome: "The requested behavior is available.", component_responsibility: "Own the behavior.", must_preserve: ["Existing behavior."], non_goals: [], acceptance_contribution: "Makes AC-001 observable." }, execution_context: { required_read: ["apps/api/src/example.ts"], discovery_boundary: ["Related tests only."], planned_write_areas: ["apps/api/src/"], stop_conditions: ["Stop if accepted scope conflicts with current truth."] }, verification: { check_refs: ["CHK-P1-TEST"] } }], acceptance: [{ criterion_id: "AC-001", plan_item_ids: ["P1"], changed_surfaces: ["apps/api/src/example.ts"], path: "Exercise the accepted user path.", environment: "Local test environment.", fixtures: [], cleanup: "No persistent fixture.", check_refs: ["CHK-P1-TEST"], expected_evidence: ["Focused check passes."], proof_limits: ["Manual production evidence is not claimed."], gate: "work" }] }; }
 function aspectMapExample(protocolId) { return { $schema: "plan-aspect-map.schema.json", schema_id: "dd-flow/plan-aspect-map@3", protocol_id: protocolId, plan_id: "PLAN-001", plan_revision: 1, catalog_ref: { path: ".memory-bank/dd-flow/mb-sdlc/plan-aspects/aspects" }, routing: { initial_state: "orchestrator_local", selected_route: "local_compact", reason: "One genuinely small semantic unit.", groups: [] }, review_groups: [], aspects: [{ aspect_id: "example_aspect", applicability: "not_applicable", reason: "Only an example; use the supplied real catalog.", planned_artifact_refs: [] }] }; }
-function requireRun(context, root, id) { const project = requireProjectByRoot(context, root); const run = context.db.get("SELECT id, project_id, workspace_root, run_home_path FROM runs WHERE project_id = ? AND id = ?", [project.id, id]); if (!run)
+function requireRun(context, root, id) { const project = requireProjectByRoot(context, root); const run = context.db.get("SELECT id, project_id, workspace_root, run_root FROM runs WHERE project_id = ? AND id = ?", [project.id, id]); if (!run)
     throw new AppError("not_found", "RUN is not registered", 1); return run; }
-function requireHome(run) { if (!run.run_home_path)
-    throw new AppError("runtime_missing", "RUN workspace is unavailable", 1); return run.run_home_path; }
+function requireHome(run) { if (!run.run_root)
+    throw new AppError("runtime_missing", "RUN artifact root is unavailable", 1); return run.run_root; }
 function protocolIds(home) {
     const report = JSON.parse(fs.readFileSync(path.join(home, "02-protocolize", "stage-report.json"), "utf8"));
     const ids = report.semantic?.acceptance;
@@ -367,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)
@@ -386,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);
@@ -431,7 +479,7 @@ function projectCodeWorkBatch(input) {
             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}`),
-            result_schema: "dd-flow/code-work-result@2"
+            result_schema: "dd-flow/code-work-result@3"
         });
     }));
     const byProtocol = new Map(input.plans.map((plan) => [plan.protocolId, plan.value.items]));

package/dist/services/vnext-protocolize.js

@@ -1,3 +1,4 @@
+import { managedLifecycleCommand } from "./lifecycle-invocations.js";
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
@@ -7,6 +8,7 @@ import { previewNextEntityId } from "./ids.js";
 import { registerProtocol } from "./protocols.js";
 import { requireProjectByRoot } from "./projects.js";
 import { advanceFlowRun, appendFlowRunTimelineEvent, attachFlowRunStage, completeFlowRunStage, gitFacts, rebindFlowRunWorkspace } from "./runs.js";
+import { resolveStageTransition } from "./execution-policy.js";
 import { validateSchema } from "./schema-validation.js";
 import { assertStageStartHookEvent, hookSessionIdentity } from "./hooks.js";
 import { bindStageCoordinatorWork, refreshRunWorkProjection } from "./work-registry.js";
@@ -21,9 +23,15 @@ const stage = "protocolize";
 function stageSessionMode(context, run) {
     const row = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [run.project_id, run.id]);
     const value = row ? JSON.parse(row.index_json) : null;
-    const mode = value?.execution_profile?.settings?.stage_session_mode;
+    const profile = value?.execution_profile;
+    const mode = profile?.settings.stage_session_mode;
     if (mode !== "same_session" && mode !== "new_session")
         throw new AppError("execution_profile_invalid", "RUN is missing its frozen stage session mode", 1, { run_id: run.id });
+    if (profile?.settings.execution) {
+        if (!profile.agent_profiles)
+            throw new AppError("execution_profile_not_frozen", "Stage handoff requires frozen RUN profiles", 1);
+        return resolveStageTransition({ ddFlowHome: context.ddFlowHome, policy: profile.settings.execution, profiles: profile.agent_profiles, fromStage: "protocolize", stage: "plan", stageSessionMode: mode, mergeMode: profile.settings.merge_mode }).session_mode;
+    }
     return mode;
 }
 export function isVnextProtocolizeRun(context, input) {
@@ -54,13 +62,13 @@ export function prepareVnextProtocolize(context, input) {
     if (!fs.existsSync(templatePath))
         throw new AppError("not_found", "vNext PROTOCOLIZE prompt template is missing", 1, { path: templatePath });
     const pauseCommand = stagePauseCommand(context, { runId: run.id, stage, workId: work.work_id, projectRoot });
-    const prompt = renderPrompt({ projectRoot, runId: run.id, workId: work.work_id, specifyPath, obligations, resultPath, handoff: input.handoff, catalog: catalog(projectRoot), policy, template: fs.readFileSync(templatePath, "utf8"), pauseCommand, pauseCommandTemplate: stagePauseCommandTemplate(pauseCommand), flow: flowCommand(context) });
+    const prompt = renderPrompt({ projectRoot, runId: run.id, workId: work.work_id, specifyPath, obligations, resultPath, handoff: input.handoff, catalog: catalog(projectRoot), policy, template: fs.readFileSync(templatePath, "utf8"), pauseCommand, pauseCommandTemplate: stagePauseCommandTemplate(pauseCommand), finishCommand: managedLifecycleCommand(context, `${flowCommand(context)} stage finish ${run.id} --stage protocolize --project-root ${JSON.stringify(projectRoot)} --result-file ${JSON.stringify(resultPath)} --json`) });
     fs.writeFileSync(promptPath, prompt);
     // Preparation is deliberately non-productive: the standalone stage-start
     // command atomically installs external context, binds the worker and opens
     // the lifecycle Stage.  Do not make this prompt an implicit running stage.
     appendFlowRunTimelineEvent(context, project.id, run.id, { type: "stage_prepared", work_id: work.work_id, stage, handoff_mode: input.handoff.stage_handoff.effective });
-    const directive = input.handoff.stage_handoff.effective === "same_session" ? { kind: "continue_current_session", stage, prompt_path: promptPath, worker_prompt_markdown: prompt } : { kind: "await_new_session", stage, work_id: work.work_id, prompt_path: promptPath, resume_command: `${flowCommand(context)} stage start ${run.id} --stage protocolize --project-root ${JSON.stringify(projectRoot)} --json` };
+    const directive = input.handoff.stage_handoff.effective === "same_session" ? { kind: "continue_current_session", stage, prompt_path: promptPath, worker_prompt_markdown: prompt } : { kind: "await_new_session", stage, work_id: work.work_id, prompt_path: promptPath, resume_command: managedLifecycleCommand(context, `${flowCommand(context)} stage start ${run.id} --stage protocolize --project-root ${JSON.stringify(projectRoot)} --json`) };
     return { directive, prompt_path: promptPath };
 }
 export function startVnextProtocolize(context, input) {
@@ -77,7 +85,6 @@ export function startVnextProtocolize(context, input) {
         const handoff = specifyHandoff(path.join(requireRunHome(run), "01-specify", "work-context.json"), work.work_id);
         prepareVnextProtocolize(context, { projectRoot, runId: run.id, workId: work.work_id, handoff });
     }
-    const handoff = JSON.parse(fs.readFileSync(contextPath, "utf8"));
     const frozenContext = JSON.parse(fs.readFileSync(contextPath, "utf8"));
     const previous = context.db.get("SELECT ws.session_id, s.stop_reason FROM work_sessions ws LEFT JOIN sessions s ON s.project_id = ? AND s.session_id = ws.session_id WHERE ws.work_id = ? ORDER BY ws.created_at DESC LIMIT 1", [project.id, work.work_id]);
     const activeWorkSession = context.db.get("SELECT * FROM work_sessions WHERE work_id = ? AND status = 'running' ORDER BY created_at DESC LIMIT 1", [work.work_id]);
@@ -91,7 +98,7 @@ export function startVnextProtocolize(context, input) {
             return false;
         }
     })();
-    const mode = handoff.system?.handoff?.stage_handoff.effective;
+    const mode = frozenContext.system?.handoff?.stage_handoff.effective;
     const promptPath = path.join(protocolizeRoot, "prompt.md");
     const externalContext = applyExternalStageContext({ stageRoot: protocolizeRoot, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
     const sessionId = hookSessionIdentity(context, project.id, input.hookEventId).sessionId;
@@ -135,7 +142,7 @@ export function finishVnextProtocolize(context, input) {
     const root = path.join(requireRunHome(run), "02-protocolize");
     const resultFile = path.resolve(input.resultFile);
     inside(root, resultFile);
-    validateSchema({ schemaName: "vnext-protocolize-result", file: resultFile, projectRoot, ddFlowHome: context.ddFlowHome, runId: run.id });
+    validateSchema({ schemaName: "vnext-protocolize-result", file: resultFile, projectRoot, ddFlowHome: context.ddFlowHome, runId: run.id, runRoot: requireRunHome(run) });
     const result = readResult(resultFile);
     if (result.outcome !== "protocolized")
         throw new AppError("validation", "PROTOCOLIZE may finish only as protocolized; use stage pause for every user question", 2);
@@ -162,12 +169,12 @@ export function finishVnextProtocolize(context, input) {
     const reportMarkdown = path.join(root, "stage-report.md");
     const reportHtml = path.join(root, "stage-report.html");
     writeStageReport(root, report);
-    validateSchema({ schemaName: "stage-report", file: reportJson, projectRoot, ddFlowHome: context.ddFlowHome, runId: run.id });
+    validateSchema({ schemaName: "stage-report", file: reportJson, projectRoot, ddFlowHome: context.ddFlowHome, runId: run.id, runRoot: requireRunHome(run) });
     completeFlowRunStage(context, { projectRoot, runId: run.id, stage, status: "done", data: "protocolize-result.json", dataSchemaId: "dd-flow/vnext-protocolize-result@3", report: "stage-report.md", stageReport: "stage-report.html" });
     appendFlowRunTimelineEvent(context, project.id, run.id, { type: "protocol_documents_materialized", work_id: work.work_id, protocol_ids: protocolIds, stage });
-    advanceFlowRun(context, { projectRoot, runId: run.id, status: "running", verdict: "protocolized", nextAction: "start_plan" });
+    advanceFlowRun(context, { settlementStage: "protocolize", projectRoot, runId: run.id, status: "running", verdict: "protocolized", nextAction: "start_plan" });
     refreshRunWorkProjection(context, project.id, run.id);
-    const nextCommand = `${flowCommand(context)} stage start ${run.id} --stage plan --project-root ${JSON.stringify(projectRoot)} --json`;
+    const nextCommand = managedLifecycleCommand(context, `${flowCommand(context)} stage start ${run.id} --stage plan --project-root ${JSON.stringify(projectRoot)} --json`);
     return { ok: true, outcome: "protocolized", run_id: run.id, protocol_ids: protocolIds, workspace_root: workspaceRoot, git_policy: resolvedPolicy, next_action: "await_plan", next_command: nextCommand, next: { kind: "start_stage", stage: "plan", command: nextCommand, cwd: workspaceRoot, session_mode: resolvedPolicy.stage_session_mode }, artifacts: { result: resultFile, report_json: reportJson, report_markdown: reportMarkdown, report_html: reportHtml, protocols: protocolIds.map((id) => path.join(workspaceRoot, ".memory-bank", "protocol", id, "summary.md")) } };
 }
 function materialize(projectRoot, runId, runHome, result, obligations, ids, psetId) {
@@ -318,7 +325,7 @@ function readResult(file) {
 function acceptedSpecifyObligations(context, projectRoot, runId, specifyPath) {
     if (!fs.existsSync(specifyPath))
         throw new AppError("not_found", "PROTOCOLIZE requires accepted specify.json", 1, { path: specifyPath });
-    validateSchema({ schemaName: "vnext-specify", file: specifyPath, projectRoot, ddFlowHome: context.ddFlowHome, runId });
+    validateSchema({ schemaName: "vnext-specify", file: specifyPath, projectRoot, ddFlowHome: context.ddFlowHome, runId, runRoot: requireRunHome(requireRun(context, projectRoot, runId)) });
     const specify = readVnextSpecifyResult(specifyPath);
     return [
         ...specify.requirements.map((obligation) => ({ ...obligation, kind: "requirement" })),
@@ -435,7 +442,7 @@ function resultTemplate(obligations = []) {
 }
 function renderPrompt(input) {
     const obligationList = input.obligations.map((obligation) => `- ${obligation.id}: ${obligation.statement}`).join("\n");
-    return ["<work_context>", `- RUN: ${input.runId}`, `- Work: ${input.workId}`, `- Accepted SPECIFY JSON: ${input.specifyPath}`, `- Handoff: ${input.handoff.stage_handoff.effective}`, "</work_context>", "", "<accepted_obligations>", obligationList, "</accepted_obligations>", "", "<frozen_git_policy>", `- route: ${input.policy.route}`, `- integration branch: ${input.policy.integration_branch ?? "not applicable"}`, `- base ref: ${input.policy.base_ref ?? "not applicable"}`, `- feature branch: ${input.policy.feature_branch ?? "not applicable"}`, `- service worktree: ${input.policy.worktree_path ?? "not applicable"}`, `- bootstrap: ${input.policy.bootstrap_status}`, `- decision: ${input.policy.reason}`, "The CLI already created and bootstrapped this workspace at PROTOCOLIZE start. Do not create branches, worktrees, protocol files or Git commits yourself. This transition Work may run from the stable session; edit only the supplied RUN result file.", "</frozen_git_policy>", "", "<catalog>", input.catalog.length ? input.catalog.map((x) => `- ${x}`).join("\n") : "- inactive", "</catalog>", "", "<stage_instructions>", input.template.trim(), "</stage_instructions>", "", "<output_contract>", `Edit only ${input.resultPath}. Keep this exact JSON shape; CLI allocates ids and writes PRT/PSET/feature documents in the already provisioned workspace:\n\n\`\`\`json\n${JSON.stringify(resultTemplate(), null, 2)}\n\`\`\``, "Allocate every supplied R-* and AC-* exactly once in obligation_ownership. The CLI rejects unknown, duplicate or missing obligations, and every member must own at least one AC-*.", "If PROTOCOLIZE itself exposes a material user decision with no reasonable default, do not finish and do not return to SPECIFY. 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", input.pauseCommandTemplate, "```", "Ask the returned user_message and stop. Resume this same PROTOCOLIZE Work using the exact command returned by pause.", `When the answer is incorporated and the result is protocolized, finish:\n\n${input.flow} stage finish ${input.runId} --stage protocolize --project-root ${JSON.stringify(input.projectRoot)} --result-file ${JSON.stringify(input.resultPath)} --json`, "</output_contract>", ""].join("\n");
+    return ["<work_context>", `- RUN: ${input.runId}`, `- Work: ${input.workId}`, `- Accepted SPECIFY JSON: ${input.specifyPath}`, `- Handoff: ${input.handoff.stage_handoff.effective}`, "</work_context>", "", "<accepted_obligations>", obligationList, "</accepted_obligations>", "", "<frozen_git_policy>", `- route: ${input.policy.route}`, `- integration branch: ${input.policy.integration_branch ?? "not applicable"}`, `- base ref: ${input.policy.base_ref ?? "not applicable"}`, `- feature branch: ${input.policy.feature_branch ?? "not applicable"}`, `- service worktree: ${input.policy.worktree_path ?? "not applicable"}`, `- bootstrap: ${input.policy.bootstrap_status}`, `- decision: ${input.policy.reason}`, "The CLI already created and bootstrapped this workspace at PROTOCOLIZE start. Do not create branches, worktrees, protocol files or Git commits yourself. This transition Work may run from the stable session; edit only the supplied RUN result file.", "</frozen_git_policy>", "", "<catalog>", input.catalog.length ? input.catalog.map((x) => `- ${x}`).join("\n") : "- inactive", "</catalog>", "", "<stage_instructions>", input.template.trim(), "</stage_instructions>", "", "<output_contract>", `Edit only ${input.resultPath}. Keep this exact JSON shape; CLI allocates ids and writes PRT/PSET/feature documents in the already provisioned workspace:\n\n\`\`\`json\n${JSON.stringify(resultTemplate(), null, 2)}\n\`\`\``, "Allocate every supplied R-* and AC-* exactly once in obligation_ownership. The CLI rejects unknown, duplicate or missing obligations, and every member must own at least one AC-*.", "If PROTOCOLIZE itself exposes a material user decision with no reasonable default, do not finish and do not return to SPECIFY. 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", input.pauseCommandTemplate, "```", "Ask the returned user_message and stop. Resume this same PROTOCOLIZE Work using the exact command returned by pause.", `When the answer is incorporated and the result is protocolized, finish:\n\n${input.finishCommand}`, "</output_contract>", ""].join("\n");
 }
 function provisionWorkspaceForProtocolize(context, projectRoot, projectId, run, stageRoot) {
     const receiptPath = path.join(stageRoot, "workspace-route.json");
@@ -498,10 +505,10 @@ function featureIndex(epicRoot, featureSlug) {
 }
 function requireWork(context, id) { const work = context.db.get("SELECT * FROM works WHERE work_id = ?", [id]); if (!work)
     throw new AppError("not_found", "Work is not registered", 1, { work_id: id }); return work; }
-function requireRun(context, projectRoot, id) { const project = requireProjectByRoot(context, projectRoot); const run = context.db.get("SELECT id, short_id, slug, project_id, workspace_root, run_home_path FROM runs WHERE project_id = ? AND id = ?", [project.id, id]); if (!run)
+function requireRun(context, projectRoot, id) { const project = requireProjectByRoot(context, projectRoot); const run = context.db.get("SELECT id, short_id, slug, project_id, workspace_root, run_root FROM runs WHERE project_id = ? AND id = ?", [project.id, id]); if (!run)
     throw new AppError("not_found", "RUN is not registered", 1, { run_id: id }); return run; }
-function requireRunHome(run) { if (!run.run_home_path)
-    throw new AppError("runtime_missing", "RUN has no portable workspace", 1); return run.run_home_path; }
+function requireRunHome(run) { if (!run.run_root)
+    throw new AppError("runtime_missing", "RUN artifact root is unavailable", 1); return run.run_root; }
 function inside(root, file) { const relative = path.relative(root, file); if (relative.startsWith("..") || path.isAbsolute(relative))
     throw new AppError("path_escape", "Result must be inside the protocolize workspace", 2); }
 function writeJson(file, value) { const tmp = `${file}.${crypto.randomUUID()}.tmp`; fs.writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`); fs.renameSync(tmp, file); }

package/dist/services/vnext-specify.js

@@ -1,3 +1,4 @@
+import { managedLifecycleCommand } from "./lifecycle-invocations.js";
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
@@ -9,6 +10,7 @@ import { resolveProjectRoot, writeJsonAtomic } from "../storage/paths.js";
 import { preflightMemoryPermissions } from "./memory-permissions.js";
 import { registerProject, requireProjectByRoot } from "./projects.js";
 import { advanceFlowRun, appendFlowRunTimelineEvent, attachFlowRunStage, completeFlowRun, completeFlowRunStage, getFlowRunStatus, startFlowRun } from "./runs.js";
+import { resolveStageTransition } from "./execution-policy.js";
 import { validateSchema } from "./schema-validation.js";
 import { bindRunningWorkSession, refreshRunWorkProjection } from "./work-registry.js";
 import { nextWorkId } from "./ids.js";
@@ -65,7 +67,7 @@ export function launchVnextSpecify(context, input) {
     if (preflight.ok !== true)
         throw new AppError("permission_preflight_failed", "SPECIFY workspace is not writable", 1, { preflight });
     const grounding = projectGrounding(projectRoot);
-    const handoff = executionSnapshot(context, run.id);
+    const handoff = executionSnapshot(context, run.project_id, run.id);
     const workContext = {
         schema_id: "dd-flow/work-context@1",
         system: { run_id: run.id, work_id: workId, stage: stageId },
@@ -82,7 +84,7 @@ export function launchVnextSpecify(context, input) {
     };
     writeJson(contextPath, workContext);
     const pauseCommand = stagePauseCommand(context, { runId: run.id, stage: stageId, workId, projectRoot });
-    const prompt = renderPrompt({ workId, runId: run.id, projectRoot, stageRoot, resultPath, discussion, template, workContext, grounding, pauseCommand, pauseCommandTemplate: stagePauseCommandTemplate(pauseCommand), flow: flowCommand(context) });
+    const prompt = renderPrompt({ workId, runId: run.id, projectRoot, stageRoot, resultPath, discussion, template, workContext, grounding, pauseCommand, pauseCommandTemplate: stagePauseCommandTemplate(pauseCommand), finishCommand: managedLifecycleCommand(context, `${flowCommand(context)} stage finish ${run.id} --project-root ${JSON.stringify(projectRoot)} --stage specify --result-file ${JSON.stringify(path.join(stageRoot, "specify-result.json"))} --outcome specified --json`) });
     fs.writeFileSync(promptPath, prompt);
     const externalContext = applyExternalStageContext({ stageRoot, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
     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)
@@ -126,7 +128,9 @@ export function submitVnextSpecify(context, input) {
     if (work.project_id !== project.id)
         throw new AppError("project_mismatch", "Work does not belong to --project-root", 1, { work_id: work.work_id });
     if (work.status !== "running") {
-        throw new AppError("invalid_work_state", "Work is not waiting for a SPECIFY result", 1, { work_id: work.work_id, status: work.status });
+        // This check precedes all result reads and mutations. A later legal state
+        // transition may make a new invocation appropriate, but never replays this one.
+        throw new AppError("invalid_work_state", "Work is not waiting for a SPECIFY result", 1, { work_id: work.work_id, status: work.status, retryable_no_effect: true });
     }
     const run = requireRun(context, projectRoot, work.run_id);
     if (runStatus(context, project.id, run.id) !== "running") {
@@ -141,7 +145,7 @@ export function submitVnextSpecify(context, input) {
         throw new AppError("not_found", "--result-file must point to an existing file inside the SPECIFY workspace", 1, { result_file: input.resultFile });
     }
     try {
-        validateSchema({ schemaName: "vnext-specify", file: candidateFile, projectRoot, ddFlowHome: context.ddFlowHome, runId: run.id });
+        validateSchema({ schemaName: "vnext-specify", file: candidateFile, projectRoot, ddFlowHome: context.ddFlowHome, runId: run.id, runRoot: runHome });
         const result = readVnextSpecifyResult(candidateFile);
         validateObligations(result, candidateFile);
         const normalizedResult = `${JSON.stringify(result, null, 2)}\n`;
@@ -169,7 +173,7 @@ export function submitVnextSpecify(context, input) {
         const htmlPath = path.join(stageRoot, "stage-report.html");
         const report = buildStageReport({ run, work, workSession, outcome, result, resultMarkdown: renderedMarkdown, now, stageRoot, resultFile });
         writeStageReport(stageRoot, report);
-        validateSchema({ schemaName: "stage-report", file: reportPath, projectRoot, ddFlowHome: context.ddFlowHome, runId: run.id });
+        validateSchema({ schemaName: "stage-report", file: reportPath, projectRoot, ddFlowHome: context.ddFlowHome, runId: run.id, runRoot: runHome });
         completeFlowRunStage(context, {
             projectRoot,
             runId: run.id,
@@ -187,9 +191,9 @@ export function submitVnextSpecify(context, input) {
             appendFlowRunTimelineEvent(context, run.project_id, run.id, { type: "work_completed", work_id: work.work_id, outcome, stage: stageId });
         if (continuesToProtocolize) {
             const nextWork = requireWork(context, work.work_id);
-            advanceFlowRun(context, { projectRoot, runId: run.id, status: "running", verdict: "specified", nextAction: "start_protocolize" });
+            advanceFlowRun(context, { settlementStage: "specify", projectRoot, runId: run.id, status: "running", verdict: "specified", nextAction: "start_protocolize" });
             refreshRunWorkProjection(context, run.project_id, run.id);
-            const nextCommand = `${flowCommand(context)} stage start ${run.id} --stage protocolize --project-root ${JSON.stringify(projectRoot)} --json`;
+            const nextCommand = managedLifecycleCommand(context, `${flowCommand(context)} stage start ${run.id} --stage protocolize --project-root ${JSON.stringify(projectRoot)} --json`);
             return {
                 ok: true,
                 schema_id: "dd-flow/vnext-work-submit@1",
@@ -268,7 +272,7 @@ function readIntake(input) {
 }
 function requireRun(context, projectRoot, runId) {
     const project = requireProjectByRoot(context, projectRoot);
-    const run = context.db.get("SELECT id, project_id, project_root, workspace_root, run_home_path FROM runs WHERE project_id = ? AND id = ?", [project.id, runId]);
+    const run = context.db.get("SELECT id, project_id, project_root, workspace_root, run_root FROM runs WHERE project_id = ? AND id = ?", [project.id, runId]);
     if (!run)
         throw new AppError("not_found", "RUN is not registered", 1, { run_id: runId });
     return run;
@@ -280,9 +284,9 @@ function runStatus(context, projectId, runId) {
     return run.status;
 }
 function requiredRunHome(run) {
-    if (!run.run_home_path)
-        throw new AppError("runtime_missing", "RUN has no portable workspace", 1, { run_id: run.id });
-    return run.run_home_path;
+    if (!run.run_root)
+        throw new AppError("runtime_missing", "RUN has no portable artifact root", 1, { run_id: run.id });
+    return run.run_root;
 }
 function requireWork(context, workId) {
     const work = context.db.get("SELECT * FROM works WHERE work_id = ?", [workId]);
@@ -397,8 +401,8 @@ function renderPrompt(input) {
         input.pauseCommandTemplate,
         "```",
         "The response tells you exactly what to ask and how to resume this same stage. Ask its user_message and stop the Turn.",
-        `Finish exactly once only after all questions are resolved. Run this as one standalone Bash command:\n\`${input.flow} stage finish ${input.runId} --project-root "${input.projectRoot}" --stage specify --result-file ${JSON.stringify(path.join(input.stageRoot, "specify-result.json"))} --outcome specified --json\`.`,
-        "Do not combine the lifecycle command with cat, skill reads, Git commands, pipes or shell operators. If finish reports a validation error, correct the same result file and rerun that exact command in this Session. After success, follow only its returned next directive; a focused eval controller may explicitly stop at this stage boundary.",
+        `Finish exactly once only after all questions are resolved. Run this as one standalone Bash command:\n\`${input.finishCommand}\`.`,
+        "Do not combine the lifecycle command with cat, skill reads, Git commands, pipes or shell operators. If finish reports a validation error, correct the same result file and use its returned retry_command in this Session; only if no invocation-id was issued may you rerun the original command. After success, follow only its returned next directive; a focused eval controller may explicitly stop at this stage boundary.",
         "</output_contract>",
         ""
     ].join("\n");
@@ -562,12 +566,18 @@ export function readVnextFlowDefinition(projectRoot) {
     }
     return null;
 }
-function executionSnapshot(context, runId) {
-    const row = context.db.get("SELECT index_json FROM runs WHERE id = ?", [runId]);
+function executionSnapshot(context, projectId, runId) {
+    const row = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
     const snapshot = row ? JSON.parse(row.index_json) : null;
-    const handoff = snapshot?.execution_profile?.settings?.stage_session_mode;
+    const profile = snapshot?.execution_profile;
+    let handoff = profile?.settings.stage_session_mode;
     if (handoff !== "same_session" && handoff !== "new_session")
         throw new AppError("execution_profile_invalid", "RUN has no frozen stage session mode", 1, { run_id: runId });
+    if (profile?.settings.execution) {
+        if (!profile.agent_profiles)
+            throw new AppError("execution_profile_not_frozen", "Stage handoff requires frozen RUN profiles", 1);
+        handoff = resolveStageTransition({ ddFlowHome: context.ddFlowHome, policy: profile.settings.execution, profiles: profile.agent_profiles, fromStage: "specify", stage: "protocolize", stageSessionMode: handoff, mergeMode: profile.settings.merge_mode }).session_mode;
+    }
     return { stage_handoff: { effective: handoff, source: "run_override" } };
 }
 function executionSnapshotFromPath(contextPath, workId) {