@deksden-com/dd-flow-cli 0.9.0-beta.1 → 0.9.0-beta.100

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";
@@ -6,31 +7,39 @@ import { projectFeatureWorktreePath, resolveProjectRoot } from "../storage/paths
 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 { advanceFlowRun, appendFlowRunTimelineEvent, attachFlowRunStage, completeFlowRunStage, prepareFlowRunStageAttachment, 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";
 import { runTargetedMemoryBankLint } from "./stage-lifecycle.js";
-import { bootstrapManagedWorktree, createManagedWorktree, recordManagedWorktree } from "./worktrees.js";
+import { bootstrapManagedWorktree, createManagedWorktree, prepareManagedWorktree, prepareManagedWorktreeBootstrapSources, recordManagedWorktree } from "./worktrees.js";
 import { loadVnextWorkspacePolicy, requireVnextWorkspaceRoute, vnextRunBranch } from "./vnext-workspace-policy.js";
 import { readVnextSpecifyResult } from "./vnext-specify.js";
 import { flowCommand, stagePauseCommand, stagePauseCommandTemplate } from "./stage-pause.js";
 import { writeStageReport } from "./stage-report-renderer.js";
-import { applyExternalStageContext } from "./stage-context.js";
+import { applyExternalStageContext, prepareExternalStageContext } from "./stage-context.js";
+import { prepareJsonSchema, prepareOutputFile } from "../cli/input-preparation.js";
 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) {
     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 prepareVnextProtocolize(context, input) {
+export function prepareVnextProtocolizeArtifacts(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const project = requireProjectByRoot(context, projectRoot);
     const run = requireRun(context, projectRoot, input.runId);
@@ -42,45 +51,50 @@ export function prepareVnextProtocolize(context, input) {
     const specifyPath = path.join(runHome, "01-specify", "specify.json");
     const specifyMarkdownPath = path.join(runHome, "01-specify", "specify.md");
     const obligations = acceptedSpecifyObligations(context, projectRoot, run.id, specifyPath);
-    fs.mkdirSync(stageRoot, { recursive: true });
     const resultPath = path.join(stageRoot, "protocolize-result.json");
     const promptPath = path.join(stageRoot, "prompt.md");
-    const policy = provisionWorkspaceForProtocolize(context, projectRoot, project.id, run, stageRoot);
+    const templatePath = path.join(projectRoot, ".memory-bank", "dd-flow", "vnext", "protocolize.md");
+    if (!fs.existsSync(templatePath))
+        throw new AppError("runtime_artifact_missing", "vNext PROTOCOLIZE prompt template is missing", 1, { path: templatePath });
+    const template = fs.readFileSync(templatePath, "utf8");
+    const projectCatalog = catalog(projectRoot);
+    if (!["same_session", "new_session"].includes(input.handoff?.stage_handoff?.effective))
+        throw new AppError("runtime_context_invalid", "PROTOCOLIZE requires a frozen handoff policy", 1);
+    for (const file of [promptPath, path.join(stageRoot, "work-context.json"), ...(!fs.existsSync(resultPath) ? [resultPath] : [])])
+        prepareOutputFile(file);
+    const workspace = prepareWorkspaceForProtocolize(context, projectRoot, project.id, run, stageRoot);
+    return { projectRoot, project, run, work, stageRoot, specifyPath, specifyMarkdownPath, obligations, resultPath, promptPath, template, projectCatalog, workspace };
+}
+/** Materialize the next-stage packet; this is execution, not read-only CLI preparation. */
+export function prepareVnextProtocolize(context, input, prepared = prepareVnextProtocolizeArtifacts(context, input)) {
+    const { projectRoot, project, run, work, stageRoot, specifyPath, specifyMarkdownPath, obligations, resultPath, promptPath, template, projectCatalog } = prepared;
+    fs.mkdirSync(stageRoot, { recursive: true });
+    const policy = provisionWorkspaceForProtocolize(context, projectRoot, run, prepared.workspace);
     const routedRun = requireRun(context, projectRoot, run.id);
-    writeJson(path.join(stageRoot, "work-context.json"), { schema_id: "dd-flow/vnext-protocolize-context@2", system: { run_id: run.id, work_id: work.work_id, stage, handoff: input.handoff }, input: { accepted_specify_json: specifyPath, accepted_specify_markdown: specifyMarkdownPath }, catalog: catalog(projectRoot), workspace: { project_root: projectRoot, workspace_root: routedRun.workspace_root, stage_root: stageRoot, git_policy: policy } });
+    writeJson(path.join(stageRoot, "work-context.json"), { schema_id: "dd-flow/vnext-protocolize-context@2", system: { run_id: run.id, work_id: work.work_id, stage, handoff: input.handoff }, input: { accepted_specify_json: specifyPath, accepted_specify_markdown: specifyMarkdownPath }, catalog: projectCatalog, workspace: { project_root: projectRoot, workspace_root: routedRun.workspace_root, stage_root: stageRoot, git_policy: policy } });
     if (!fs.existsSync(resultPath))
         writeJson(resultPath, resultTemplate(obligations));
-    const templatePath = path.join(projectRoot, ".memory-bank", "dd-flow", "vnext", "protocolize.md");
-    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: projectCatalog, policy, template, 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.
+    // Packet publication does not itself bind a Session or open the 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) {
+export function prepareVnextProtocolizeStart(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const project = requireProjectByRoot(context, projectRoot);
     const run = requireRun(context, projectRoot, input.runId);
-    assertStageStartHookEvent(context, { projectId: project.id, eventKey: input.hookEventId, runId: run.id, stage, projectRoot, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
     const work = context.db.get("SELECT * 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 (!work || work.status !== "running")
         throw new AppError("invalid_work_state", "PROTOCOLIZE is not ready for an Agent WorkSession", 1, { run_id: run.id });
     const protocolizeRoot = path.join(requireRunHome(run), "02-protocolize");
     const contextPath = path.join(protocolizeRoot, "work-context.json");
-    if (!fs.existsSync(contextPath)) {
-        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]);
+    const frozenContext = fs.existsSync(contextPath) ? readProtocolizeContext(contextPath) : null;
+    const handoff = frozenContext?.system?.handoff ?? specifyHandoff(path.join(requireRunHome(run), "01-specify", "work-context.json"), work.work_id);
+    const packetInput = { projectRoot, runId: run.id, workId: work.work_id, handoff };
+    const packet = frozenContext ? null : prepareVnextProtocolizeArtifacts(context, packetInput);
     const stageAttached = (() => {
         const row = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [project.id, run.id]);
         try {
@@ -88,12 +102,35 @@ export function startVnextProtocolize(context, input) {
             return index.stage_runs?.some((item) => item.stage === stage) ?? false;
         }
         catch {
-            return false;
+            throw new AppError("runtime_artifact_invalid", "RUN stage index is malformed", 1);
         }
     })();
-    const mode = handoff.system?.handoff?.stage_handoff.effective;
+    if (!stageAttached)
+        prepareFlowRunStageAttachment(context, { projectRoot, runId: run.id, stage, dir: "02-protocolize", status: "running", dataSchemaId: "dd-flow/vnext-protocolize-result@3" });
+    const mode = handoff.stage_handoff.effective;
     const promptPath = path.join(protocolizeRoot, "prompt.md");
-    const externalContext = applyExternalStageContext({ stageRoot: protocolizeRoot, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
+    if (frozenContext)
+        fs.readFileSync(promptPath, "utf8");
+    if (input.externalContext) {
+        prepareExternalStageContext({ stageRoot: protocolizeRoot, loaded: input.externalContext });
+        prepareOutputFile(promptPath);
+    }
+    return { projectRoot, project, run, work, protocolizeRoot, contextPath, frozenContext, packetInput, packet, stageAttached, mode, promptPath };
+}
+function readProtocolizeContext(file) {
+    try {
+        const value = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (["same_session", "new_session"].includes(value?.system?.handoff?.stage_handoff?.effective))
+            return value;
+    }
+    catch { /* retained context is not a caller argument */ }
+    throw new AppError("runtime_context_invalid", "PROTOCOLIZE context is missing a valid frozen handoff", 1, { file });
+}
+export function startVnextProtocolize(context, input, prepared = prepareVnextProtocolizeStart(context, input)) {
+    const { projectRoot, project, run, work, protocolizeRoot, contextPath, packetInput, packet, stageAttached, mode, promptPath } = prepared;
+    assertStageStartHookEvent(context, { projectId: project.id, eventKey: input.hookEventId, runId: run.id, stage, projectRoot, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
+    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]);
     const sessionId = hookSessionIdentity(context, project.id, input.hookEventId).sessionId;
     // A stage-entry eval snapshot deliberately stops the canonical binding. Its
     // Subject starts from a fork of the captured starter Session, so the stale
@@ -103,6 +140,10 @@ export function startVnextProtocolize(context, input) {
         throw new AppError("handoff_session_mismatch", "Project policy requires PROTOCOLIZE to continue in the SPECIFY session", 1);
     if (mode === "new_session" && previous?.session_id === sessionId)
         throw new AppError("handoff_session_mismatch", "Project policy requires PROTOCOLIZE to start in a fresh session", 1);
+    if (packet)
+        prepareVnextProtocolize(context, packetInput, packet);
+    const frozenContext = prepared.frozenContext ?? readProtocolizeContext(contextPath);
+    const externalContext = applyExternalStageContext({ stageRoot: protocolizeRoot, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
     const binding = bindStageCoordinatorWork(context, { workId: work.work_id, hookEventId: input.hookEventId, stage, promptPath, resultPath: path.join(requireRunHome(run), "02-protocolize", "stage-report.json"), ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
     // Same-session handoff deliberately reuses the root Work/Session that
     // SPECIFY opened. That is not evidence that PROTOCOLIZE is already attached.
@@ -133,10 +174,9 @@ export function finishVnextProtocolize(context, input) {
     if (!work)
         throw new AppError("not_found", "RUN has no PROTOCOLIZE Work", 1, { run_id: run.id });
     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 });
-    const result = readResult(resultFile);
+    const resultFile = prepareProtocolizeResultPath(requireRunHome(run), input.resultFile);
+    const result = input.result ?? readResult(resultFile, { projectRoot, ddFlowHome: context.ddFlowHome, runId: run.id, runRoot: requireRunHome(run) });
+    validateSchema({ schemaName: "vnext-protocolize-result", file: resultFile, data: result, projectRoot, ddFlowHome: context.ddFlowHome, runId: run.id, runRoot: requireRunHome(run) });
     if (result.outcome !== "protocolized")
         throw new AppError("validation", "PROTOCOLIZE may finish only as protocolized; use stage pause for every user question", 2);
     const acceptedObligations = acceptedSpecifyObligations(context, projectRoot, run.id, path.join(requireRunHome(run), "01-specify", "specify.json"));
@@ -162,12 +202,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) {
@@ -309,21 +349,27 @@ function appendIndexEntry(indexPath, childPath, label) {
 }
 function epicRootFor(projectRoot, value) { const resolved = path.resolve(projectRoot, value); const relative = path.relative(projectRoot, resolved); if (relative.startsWith("..") || path.isAbsolute(relative))
     throw new AppError("path_escape", "epic_path must stay inside the project", 2, { epic_path: value }); return path.basename(resolved) === "index.md" ? path.dirname(resolved) : resolved; }
-function readResult(file) {
-    if (!fs.existsSync(file))
-        throw new AppError("not_found", "PROTOCOLIZE result is missing", 1, { file });
-    const value = JSON.parse(fs.readFileSync(file, "utf8"));
-    return value;
+function readResult(file, context) {
+    return prepareJsonSchema(file, "PROTOCOLIZE result", {
+        schemaName: "vnext-protocolize-result", projectRoot: context.projectRoot, ddFlowHome: context.ddFlowHome, runId: context.runId, runRoot: context.runRoot
+    }).value;
 }
 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 });
-    const specify = readVnextSpecifyResult(specifyPath);
-    return [
-        ...specify.requirements.map((obligation) => ({ ...obligation, kind: "requirement" })),
-        ...specify.acceptance_criteria.map((obligation) => ({ ...obligation, kind: "acceptance" }))
-    ];
+        throw new AppError("runtime_artifact_missing", "PROTOCOLIZE requires accepted specify.json", 1, { path: specifyPath });
+    try {
+        const specify = readVnextSpecifyResult(specifyPath);
+        validateSchema({ schemaName: "vnext-specify", file: specifyPath, data: specify, projectRoot, ddFlowHome: context.ddFlowHome, runId, runRoot: requireRunHome(requireRun(context, projectRoot, runId)) });
+        return [
+            ...specify.requirements.map((obligation) => ({ ...obligation, kind: "requirement" })),
+            ...specify.acceptance_criteria.map((obligation) => ({ ...obligation, kind: "acceptance" }))
+        ];
+    }
+    catch (error) {
+        if (!(error instanceof AppError) || !["validation", "schema_validation", "invalid_json"].includes(error.code))
+            throw error;
+        throw new AppError("runtime_artifact_invalid", "Accepted SPECIFY result is invalid", 1, { path: specifyPath, cause_code: error.code });
+    }
 }
 /** SPECIFY is historical input; only a HITL-backed protocol amendment may alter its effective wording. */
 function effectiveObligations(result, accepted) {
@@ -435,18 +481,19 @@ 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(input.obligations), null, 2)}\n\`\`\``, "obligation_id values and their one-per-obligation entries are prefilled by the CLI. Preserve those IDs exactly; change only member_keys when semantic ownership requires it. 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. 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", 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) {
+function prepareWorkspaceForProtocolize(context, projectRoot, projectId, run, stageRoot) {
     const receiptPath = path.join(stageRoot, "workspace-route.json");
     if (fs.existsSync(receiptPath))
-        return readWorkspaceRouteReceipt(stageRoot).policy;
+        return { kind: "retained", policy: readWorkspaceRouteReceipt(stageRoot).policy };
+    prepareOutputFile(receiptPath);
     const config = loadVnextWorkspacePolicy(projectRoot);
     const stableFacts = gitFacts(projectRoot);
+    const sessionMode = stageSessionMode(context, run);
     if (config.workspace.route === "integration_branch_direct") {
-        const policy = { route: "integration_branch_direct", integration_branch: config.workspace.integration_branch, base_ref: stableFacts.head, feature_branch: null, worktree_path: null, reason: "Project workspace configuration explicitly selects the integration checkout.", provision_stage: "protocolize_start", stage_session_mode: stageSessionMode(context, run), provisioned: true, bootstrap_status: "not_applicable" };
-        writeJson(receiptPath, { schema_id: "dd-flow/vnext-workspace-route@1", policy, created: null, bootstrap: null });
-        return policy;
+        const policy = { route: "integration_branch_direct", integration_branch: config.workspace.integration_branch, base_ref: stableFacts.head, feature_branch: null, worktree_path: null, reason: "Project workspace configuration explicitly selects the integration checkout.", provision_stage: "protocolize_start", stage_session_mode: sessionMode, provisioned: true, bootstrap_status: "not_applicable" };
+        return { kind: "direct", receiptPath, policy };
     }
     if (stableFacts.status === "unavailable" || !stableFacts.head || stableFacts.branch !== config.workspace.integration_branch) {
         throw new AppError("workspace_route_invalid", "Configured feature worktree requires a clean, known integration checkout", 1, { expected_integration_branch: config.workspace.integration_branch, actual: stableFacts, project_root: projectRoot });
@@ -454,10 +501,31 @@ function provisionWorkspaceForProtocolize(context, projectRoot, projectId, run,
     const branch = vnextRunBranch(config, run);
     const holder = path.basename(projectRoot).replace(/[^a-zA-Z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "project";
     const worktreePath = projectFeatureWorktreePath(context.ddFlowHome, projectId, `RUN-${run.short_id}`, holder);
-    const created = createManagedWorktree(context, { projectRoot, branch, base: stableFacts.head, path: worktreePath });
+    let create;
+    try {
+        create = prepareManagedWorktree({ projectRoot, branch, base: stableFacts.head, path: worktreePath });
+    }
+    catch (error) {
+        if (error instanceof AppError && error.exitCode === 2)
+            throw new AppError("workspace_route_invalid", "The frozen RUN workspace route cannot be provisioned", 1, { cause_code: error.code, run_id: run.id });
+        throw error;
+    }
+    prepareManagedWorktreeBootstrapSources(projectRoot);
+    return { kind: "feature", receiptPath, config, stableFacts, sessionMode, branch, create };
+}
+function provisionWorkspaceForProtocolize(context, projectRoot, run, prepared) {
+    if (prepared.kind === "retained")
+        return prepared.policy;
+    const { receiptPath } = prepared;
+    if (prepared.kind === "direct") {
+        writeJson(receiptPath, { schema_id: "dd-flow/vnext-workspace-route@1", policy: prepared.policy, created: null, bootstrap: null });
+        return prepared.policy;
+    }
+    const { config, stableFacts, sessionMode, branch, create } = prepared;
+    const created = createManagedWorktree(context, create, create);
     const bootstrap = bootstrapManagedWorktree(context, { projectRoot, worktreePath: created.worktreePath });
     rebindFlowRunWorkspace(context, { projectRoot, runId: run.id, workspaceRoot: created.worktreePath, reason: "PROTOCOLIZE start provisioned the configured feature-worktree route" });
-    const policy = { route: "feature_worktree", integration_branch: config.workspace.integration_branch, base_ref: stableFacts.head, feature_branch: branch, worktree_path: created.worktreePath, reason: "Project workspace configuration requires a managed feature worktree before durable protocol documents exist.", provision_stage: "protocolize_start", stage_session_mode: stageSessionMode(context, run), provisioned: true, bootstrap_status: bootstrap.status };
+    const policy = { route: "feature_worktree", integration_branch: config.workspace.integration_branch, base_ref: stableFacts.head, feature_branch: branch, worktree_path: created.worktreePath, reason: "Project workspace configuration requires a managed feature worktree before durable protocol documents exist.", provision_stage: "protocolize_start", stage_session_mode: sessionMode, provisioned: true, bootstrap_status: bootstrap.status };
     writeJson(receiptPath, { schema_id: "dd-flow/vnext-workspace-route@1", policy, created, bootstrap });
     return policy;
 }
@@ -498,11 +566,16 @@ 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 inside(root, file) { const relative = path.relative(root, file); if (relative.startsWith("..") || path.isAbsolute(relative))
+function requireRunHome(run) { if (!run.run_root)
+    throw new AppError("runtime_missing", "RUN artifact root is unavailable", 1); return run.run_root; }
+export function prepareProtocolizeResultPath(runHome, file) {
+    const resolved = path.resolve(file);
+    inside(path.join(runHome, "02-protocolize"), resolved);
+    return resolved;
+}
+function inside(root, file) { const relative = path.relative(root, file); if (relative === ".." || relative.startsWith(`..${path.sep}`) || 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); }
 function slug(value) { const normalized = value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, ""); if (!normalized)