@deksden-com/dd-flow-cli 0.9.0-beta.11 → 0.9.0-beta.110

package/dist/services/vnext-protocolize.js

@@ -1,36 +1,49 @@
+import { managedLifecycleCommand } from "./lifecycle-invocations.js";
 import crypto from "node:crypto";
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { AppError } from "../shared/errors.js";
 import { projectFeatureWorktreePath, resolveProjectRoot } from "../storage/paths.js";
 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, prepareFlowRunStageCompletion, withStageSettlement, gitFacts, rebindFlowRunWorkspace } from "./runs.js";
+import { resolveStageTransition, stageExecutionCwd } 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 { acceptStageReport, prepareStageReport, publishStageReport } from "./stage-report-renderer.js";
+import { applyExternalStageContext, prepareExternalStageContext } from "./stage-context.js";
+import { prepareJsonSchema, prepareOutputFile } from "../cli/input-preparation.js";
+import { stageLifecycleInstruction } from "../harness-runtime/lib/delegation-instructions.mjs";
+import { withProjectionLock } from "../storage/projection-lock.js";
 const stage = "protocolize";
-function stageSessionMode(context, run) {
+function stageSessionMode(context, run, projectRoot, targetWorkspaceRoot) {
     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 });
-    return mode;
+    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, projectRoot, workspaceRoot: targetWorkspaceRoot, fromStage: "protocolize", stage: "plan", stageSessionMode: mode, mergeMode: profile.settings.merge_mode }).session_mode;
+    }
+    return stageExecutionCwd({ stage: "protocolize", projectRoot, workspaceRoot: targetWorkspaceRoot })
+        === stageExecutionCwd({ stage: "plan", projectRoot, workspaceRoot: targetWorkspaceRoot }) ? mode : "new_session";
 }
 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 +55,52 @@ 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) });
-    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.
+    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`) });
+    const workspaceContract = ["<workspace_contract>", `- stage artifact directory: ${stageRoot}`, `- provisioned project workspace for later stages: ${policy.worktree_path ?? projectRoot}`, `- this PROTOCOLIZE Session remains in its launch directory: ${projectRoot}`, `Write only the named result file in the stage artifact directory; do not write project files, another RUN, another native home, branches, worktrees or Git commits. Do not change the Session directory to the newly provisioned worktree.`, "The CLI performs all protocol document materialization after the result is accepted.", "</workspace_contract>"].join("\n");
+    const promptWithWorkspaceContract = prompt.replace("</work_context>", `</work_context>\n\n${workspaceContract}`);
+    fs.writeFileSync(promptPath, promptWithWorkspaceContract);
+    // 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: promptWithWorkspaceContract } : { 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 +108,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 +146,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,26 +180,34 @@ 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, 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);
+    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) });
     const acceptedObligations = acceptedSpecifyObligations(context, projectRoot, run.id, path.join(requireRunHome(run), "01-specify", "specify.json"));
-    const obligations = effectiveObligations(result, acceptedObligations);
-    validateDelivery(projectRoot, result, obligations);
-    const protocolIds = result.delivery.members.map((member) => allocateProtocolId(context, projectRoot, member.slug));
-    const psetId = result.delivery.kind === "protocol_set" ? allocatePsetId(projectRoot, result.delivery.slug) : null;
+    let obligations;
+    try {
+        if (result.outcome !== "protocolized")
+            throw new AppError("validation", "PROTOCOLIZE may finish only as protocolized; use stage pause for every user question", 2);
+        obligations = effectiveObligations(result, acceptedObligations);
+        validateDelivery(projectRoot, result, obligations);
+    }
+    catch (error) {
+        if (!(error instanceof AppError) || error.code !== "validation" || error.exitCode !== 2)
+            throw error;
+        throw new AppError(error.code, error.message, error.exitCode, { ...error.details, phase: "prepare", effect: "no_effect", recoverable: true });
+    }
     const resolvedPolicy = requireVnextWorkspaceRoute({ projectRoot, runId: run.id, runHome: requireRunHome(run), workspaceRoot: run.workspace_root, stage: "protocolize" });
     const receipt = readWorkspaceRouteReceipt(root);
     const workspaceRoot = run.workspace_root;
-    const changedFiles = materialize(workspaceRoot, run.id, requireRunHome(run), result, obligations, protocolIds, psetId);
+    const intent = prepareProtocolizeIntent(context, run, resultFile, result, obligations);
+    publishProtocolizeIntent(context, project.id, intent);
+    const protocolIds = intent.protocol_ids;
+    const changedFiles = intent.changed_files;
     for (const protocolId of protocolIds)
         registerProtocol(context, { handshakeId: protocolId, projectRoot, workspacePath: workspaceRoot });
     if (receipt.created && receipt.bootstrap) {
         for (const protocolId of protocolIds)
-            recordManagedWorktree(context, { protocolId, projectRoot, branch: requiredPolicyValue(resolvedPolicy.feature_branch, "feature branch"), base: requiredPolicyValue(resolvedPolicy.base_ref, "base ref"), created: receipt.created, bootstrap: receipt.bootstrap });
+            ensureManagedWorktreeRecorded(context, { protocolId, projectRoot, branch: requiredPolicyValue(resolvedPolicy.feature_branch, "feature branch"), base: requiredPolicyValue(resolvedPolicy.base_ref, "base ref"), created: receipt.created, bootstrap: receipt.bootstrap });
     }
     const now = context.now();
     const workSession = completeWorkSession(context, work.work_id, resultFile, now);
@@ -161,15 +216,150 @@ export function finishVnextProtocolize(context, input) {
     const reportJson = path.join(root, "stage-report.json");
     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, 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" });
+    const currentIndex = JSON.parse(context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [project.id, run.id]).index_json);
+    const stageDone = currentIndex.stage_runs.some(item => item.stage === stage && item.status === "done");
+    if (stageDone) {
+        publishStageReport(context, project.id, run.id, stage, root);
+        if (!fs.existsSync(reportJson))
+            throw new AppError("protocolize_report_missing", "Completed PROTOCOLIZE has no accepted report to replay", 1, { run_id: run.id, report_path: reportJson });
+    }
+    else {
+        const preparedReport = prepareStageReport(report);
+        validateSchema({ schemaName: "stage-report", file: reportJson, data: preparedReport.normalized, projectRoot, ddFlowHome: context.ddFlowHome, runId: run.id, runRoot: requireRunHome(run) });
+        const completion = { 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", dataSha256: crypto.createHash("sha256").update(fs.readFileSync(resultFile)).digest("hex") };
+        const preparedCompletion = prepareFlowRunStageCompletion(context, completion);
+        withStageSettlement(context, () => {
+            acceptStageReport(context, { projectId: project.id, runId: run.id, stage, root, prepared: preparedReport });
+            completeFlowRunStage(context, completion, preparedCompletion);
+        });
+        appendFlowRunTimelineEvent(context, project.id, run.id, { type: "protocol_documents_materialized", work_id: work.work_id, protocol_ids: protocolIds, stage });
+    }
+    if (currentIndex.verdict !== "protocolized")
+        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 prepareProtocolizeIntent(context, run, resultFile, result, obligations) {
+    const row = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [run.project_id, run.id]);
+    const index = row ? JSON.parse(row.index_json) : null;
+    const attempt = index?.stage_runs?.find(item => item.stage === stage)?.attempt;
+    if (!attempt)
+        throw new AppError("protocolize_owner_missing", "PROTOCOLIZE has no owning Stage attempt", 1, { run_id: run.id });
+    const resultSha = sha256(fs.readFileSync(resultFile));
+    const retained = readProtocolizeIntent(context, run.project_id, run.id, attempt);
+    if (retained) {
+        if (retained.workspace_root !== run.workspace_root || retained.result_sha256 !== resultSha)
+            throw new AppError("protocolize_intent_conflict", "Accepted PROTOCOLIZE publication belongs to different result or workspace bytes", 1, { run_id: run.id, attempt });
+        return retained;
+    }
+    const projectRoot = run.workspace_root;
+    const protocolIds = allocateProtocolIds(context, run.project_id, projectRoot, result.delivery.members.map(member => member.slug));
+    const psetId = result.delivery.kind === "protocol_set" ? allocatePsetId(context, run.project_id, projectRoot, result.delivery.slug) : null;
+    const draft = fs.mkdtempSync(path.join(os.tmpdir(), "dd-flow-protocolize-"));
+    try {
+        // A draft must never follow a workspace symlink back into the live tree.
+        fs.cpSync(path.join(projectRoot, ".memory-bank"), path.join(draft, ".memory-bank"), { recursive: true, filter: source => !fs.lstatSync(source).isSymbolicLink() });
+        const feature = result.feature.epic_path && path.isAbsolute(result.feature.epic_path)
+            ? { ...result.feature, epic_path: path.join(draft, path.relative(projectRoot, result.feature.epic_path)) }
+            : result.feature;
+        const draftResult = { ...result, feature };
+        const changedFiles = materialize(draft, run.id, requireRunHome(run), draftResult, obligations, protocolIds, psetId);
+        const files = changedFiles.map(relative => {
+            const source = path.join(projectRoot, relative), target = path.join(draft, relative);
+            const bytes = fs.readFileSync(target, "utf8");
+            return { relative, before_sha256: fs.existsSync(source) ? sha256(fs.readFileSync(source)) : null, after_sha256: sha256(bytes), bytes };
+        });
+        const candidate = { run_id: run.id, attempt, workspace_root: projectRoot, result_sha256: resultSha, protocol_ids: protocolIds, pset_id: psetId, changed_files: changedFiles, files };
+        return context.db.writeTransaction(() => {
+            const raced = readProtocolizeIntent(context, run.project_id, run.id, attempt);
+            if (raced) {
+                if (raced.workspace_root !== projectRoot || raced.result_sha256 !== resultSha)
+                    throw new AppError("protocolize_intent_conflict", "A competing PROTOCOLIZE publication was accepted", 1, { run_id: run.id, attempt });
+                return raced;
+            }
+            const reserved = new Set(context.db.all("SELECT payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.protocolize_intent'", [run.project_id])
+                .flatMap(row => { const prior = JSON.parse(row.payload_json); return [...prior.protocol_ids, ...(prior.pset_id ? [prior.pset_id] : [])]; }));
+            if ([...protocolIds, ...(psetId ? [psetId] : [])].some(id => reserved.has(id)))
+                throw new AppError("protocolize_id_reserved", "Another PROTOCOLIZE attempt reserved the selected document ID; retry to allocate a new one", 1, { run_id: run.id });
+            context.db.run("INSERT INTO audit_events (project_id, event_type, forced, payload_json, created_at) VALUES (?, 'flow_run.protocolize_intent', 0, ?, ?)", [run.project_id, JSON.stringify(candidate), context.now()]);
+            return candidate;
+        });
+    }
+    finally {
+        fs.rmSync(draft, { recursive: true, force: true });
+    }
+}
+function readProtocolizeIntent(context, projectId, runId, attempt) {
+    const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.protocolize_intent' ORDER BY id DESC", [projectId]);
+    return rows.map(row => JSON.parse(row.payload_json)).find(item => item.run_id === runId && item.attempt === attempt) ?? null;
+}
+function publishProtocolizeIntent(context, projectId, intent) {
+    const memory = path.join(intent.workspace_root, ".memory-bank");
+    withProjectionLock(path.join(context.ddFlowHome, "locks", `protocolize-${projectId}.publish-lock`), () => {
+        for (const file of intent.files) {
+            if (!file.relative.startsWith(".memory-bank/") || sha256(file.bytes) !== file.after_sha256)
+                throw new AppError("protocolize_intent_invalid", "Accepted PROTOCOLIZE file is invalid", 1, { relative: file.relative });
+            const target = path.resolve(intent.workspace_root, file.relative);
+            inside(memory, target);
+            assertNoSymlinkPath(memory, target);
+            const current = fs.existsSync(target) ? sha256(fs.readFileSync(target)) : null;
+            if (current !== file.before_sha256 && current !== file.after_sha256)
+                throw new AppError("protocolize_publication_conflict", "PROTOCOLIZE target changed since publication was accepted", 1, { target });
+        }
+        for (const file of intent.files) {
+            const target = path.resolve(intent.workspace_root, file.relative);
+            if (fs.existsSync(target) && sha256(fs.readFileSync(target)) === file.after_sha256)
+                continue;
+            fs.mkdirSync(path.dirname(target), { recursive: true });
+            const temporary = `${target}.${crypto.randomUUID()}.tmp`;
+            try {
+                fs.writeFileSync(temporary, file.bytes, { flag: "wx" });
+                if (file.before_sha256 === null) {
+                    try {
+                        fs.linkSync(temporary, target);
+                    }
+                    catch (error) {
+                        if (error.code !== "EEXIST" || sha256(fs.readFileSync(target)) !== file.after_sha256)
+                            throw error;
+                    }
+                }
+                else {
+                    if (sha256(fs.readFileSync(target)) !== file.before_sha256)
+                        throw new AppError("protocolize_publication_conflict", "PROTOCOLIZE target changed during publication", 1, { target });
+                    fs.renameSync(temporary, target);
+                }
+            }
+            finally {
+                fs.rmSync(temporary, { force: true });
+            }
+        }
+    });
+}
+function assertNoSymlinkPath(memory, target) {
+    for (let cursor = memory;; cursor = path.join(cursor, path.relative(cursor, target).split(path.sep)[0])) {
+        try {
+            if (fs.lstatSync(cursor).isSymbolicLink())
+                throw new AppError("protocolize_publication_conflict", "PROTOCOLIZE publication cannot follow a workspace symlink", 1, { target, symlink: cursor });
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        if (cursor === target)
+            break;
+    }
+}
+function ensureManagedWorktreeRecorded(context, input) {
+    const existing = context.db.get("SELECT wr.feature_branch, wr.base_ref, wr.worktree_path FROM worktree_records wr JOIN protocols p ON p.project_id = wr.project_id AND p.id = wr.protocol_id WHERE p.project_root = ? AND p.id = ? AND wr.status = 'active' ORDER BY wr.created_at DESC LIMIT 1", [input.projectRoot, input.protocolId]);
+    if (existing) {
+        if (existing.feature_branch !== input.branch || existing.base_ref !== input.base || existing.worktree_path !== input.created.worktreePath)
+            throw new AppError("worktree_already_exists", "Existing managed worktree record conflicts with the accepted PROTOCOLIZE route", 1, { protocol_id: input.protocolId });
+        return;
+    }
+    recordManagedWorktree(context, input);
+}
+function sha256(bytes) { return crypto.createHash("sha256").update(bytes).digest("hex"); }
 function materialize(projectRoot, runId, runHome, result, obligations, ids, psetId) {
     const psetPath = psetId ? path.join(projectRoot, ".memory-bank", "protocol", "_set", `${psetId}.md`) : null;
     const created = [];
@@ -309,21 +499,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, runRoot: requireRunHome(requireRun(context, projectRoot, 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 +631,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}`, stageLifecycleInstruction, "</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);
     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 sessionMode = stageSessionMode(context, run, projectRoot, projectRoot);
+        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 +651,32 @@ 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 });
+    const sessionMode = stageSessionMode(context, run, projectRoot, 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;
 }
@@ -475,8 +694,27 @@ function readWorkspaceRouteReceipt(root) {
 }
 function requiredPolicyValue(value, label) { if (!value)
     throw new AppError("runtime_missing", `PROTOCOLIZE Git policy is missing ${label}`, 1); return value; }
-function allocateProtocolId(context, projectRoot, name) { return previewNextEntityId(context, { projectRoot, type: "protocol", slug: name }).entity.id; }
-function allocatePsetId(projectRoot, value) { const root = path.join(projectRoot, ".memory-bank", "protocol", "_set"); const used = fs.existsSync(root) ? fs.readdirSync(root).map((file) => /^PSET-(\d+)-/.exec(file)?.[1]).filter((item) => Boolean(item)).map(Number) : []; return `PSET-${String(Math.max(0, ...used) + 1).padStart(3, "0")}-${slug(value)}`; }
+function allocateProtocolIds(context, projectId, projectRoot, names) {
+    if (!names.length)
+        return [];
+    const first = previewNextEntityId(context, { projectRoot, type: "protocol", slug: names[0] }).entity.id;
+    const used = protocolizeReservedNumbers(context, projectId, "protocol_ids", /^PRT-(\d+)-/);
+    const sequence = Math.max(Number(/^PRT-(\d+)-/.exec(first)?.[1] ?? 1) - 1, ...used) + 1;
+    return names.map((name, index) => `PRT-${String(sequence + index).padStart(3, "0")}-${slug(name)}`);
+}
+function allocatePsetId(context, projectId, projectRoot, value) {
+    const root = path.join(projectRoot, ".memory-bank", "protocol", "_set");
+    const used = fs.existsSync(root) ? fs.readdirSync(root).map((file) => /^PSET-(\d+)-/.exec(file)?.[1]).filter((item) => Boolean(item)).map(Number) : [];
+    return `PSET-${String(Math.max(0, ...used, ...protocolizeReservedNumbers(context, projectId, "pset_id", /^PSET-(\d+)-/)) + 1).padStart(3, "0")}-${slug(value)}`;
+}
+function protocolizeReservedNumbers(context, projectId, field, pattern) {
+    const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.protocolize_intent'", [projectId]);
+    return rows.flatMap(row => {
+        const value = JSON.parse(row.payload_json);
+        const ids = field === "protocol_ids" ? value.protocol_ids : value.pset_id ? [value.pset_id] : [];
+        return ids.map(id => Number(pattern.exec(id)?.[1])).filter(Number.isFinite);
+    });
+}
 function catalog(projectRoot) {
     const memory = path.join(projectRoot, ".memory-bank");
     const candidates = [
@@ -502,7 +740,15 @@ function requireRun(context, projectRoot, id) { const project = requireProjectBy
     throw new AppError("not_found", "RUN is not registered", 1, { run_id: id }); return run; }
 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))
+export function prepareProtocolizeResultPath(runHome, file) {
+    const resolved = path.resolve(file);
+    inside(path.join(runHome, "02-protocolize"), resolved);
+    const canonical = path.join(runHome, "02-protocolize", "protocolize-result.json");
+    if (resolved !== canonical)
+        throw new AppError("protocolize_result_path_invalid", "PROTOCOLIZE result must be the canonical Stage data file named by its completion receipt", 2, { result_file: resolved, expected: canonical });
+    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)