@deksden-com/dd-flow-cli 0.9.0-beta.104 → 0.9.0-beta.106

package/dist/services/vnext-protocolize.js

@@ -1,14 +1,15 @@
 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, prepareFlowRunStageAttachment, gitFacts, rebindFlowRunWorkspace } from "./runs.js";
-import { resolveStageTransition } from "./execution-policy.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";
@@ -17,11 +18,13 @@ import { bootstrapManagedWorktree, createManagedWorktree, prepareManagedWorktree
 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 { 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 profile = value?.execution_profile;
@@ -31,9 +34,10 @@ function stageSessionMode(context, run) {
     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 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 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));
@@ -76,7 +80,7 @@ export function prepareVnextProtocolize(context, input, prepared = prepareVnextP
         writeJson(resultPath, resultTemplate(obligations));
     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: 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}`, `- project workspace: ${policy.worktree_path ?? projectRoot}`, `- project root (read-only identity): ${projectRoot}`, `Before editing the result, change into the project workspace: cd -- ${JSON.stringify(policy.worktree_path ?? 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.`, "The CLI performs all protocol document materialization after the result is accepted.", "</workspace_contract>"].join("\n");
+    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.
@@ -184,17 +188,18 @@ export function finishVnextProtocolize(context, input) {
     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;
     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);
@@ -203,15 +208,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, { settlementStage: "protocolize", 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 = 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 = [];
@@ -483,7 +623,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(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");
+    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 prepareWorkspaceForProtocolize(context, projectRoot, projectId, run, stageRoot) {
     const receiptPath = path.join(stageRoot, "workspace-route.json");
@@ -492,8 +632,8 @@ function prepareWorkspaceForProtocolize(context, projectRoot, projectId, run, st
     prepareOutputFile(receiptPath);
     const config = loadVnextWorkspacePolicy(projectRoot);
     const stableFacts = gitFacts(projectRoot);
-    const sessionMode = stageSessionMode(context, run);
     if (config.workspace.route === "integration_branch_direct") {
+        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 };
     }
@@ -503,6 +643,7 @@ function prepareWorkspaceForProtocolize(context, projectRoot, projectId, run, st
     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 sessionMode = stageSessionMode(context, run, projectRoot, worktreePath);
     let create;
     try {
         create = prepareManagedWorktree({ projectRoot, branch, base: stableFacts.head, path: worktreePath });
@@ -545,8 +686,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 = [
@@ -575,6 +735,9 @@ function requireRunHome(run) { if (!run.run_root)
 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))

package/dist/services/vnext-specify.js

@@ -9,16 +9,17 @@ import { ensureVnextWorkStorage } from "../storage/database.js";
 import { projectHome, 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, prepareFlowRunStart, startFlowRun } from "./runs.js";
+import { advanceFlowRun, appendFlowRunTimelineEvent, attachFlowRunStage, completeFlowRun, completeFlowRunStage, getFlowRunStatus, prepareFlowRunStageCompletion, prepareFlowRunStart, startFlowRun, withStageSettlement } 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";
 import { flowCommand, stagePauseCommand, stagePauseCommandTemplate } from "./stage-pause.js";
-import { writeStageReport } from "./stage-report-renderer.js";
+import { acceptStageReport, prepareStageReport } from "./stage-report-renderer.js";
 import { prepareError, prepareJsonSchema, prepareJsonText, prepareOutputDirectory, prepareOutputFile, prepareTextFile } from "../cli/input-preparation.js";
 import { hookSessionIdentity } from "./hooks.js";
 import { assertRecoveryHookCurrent, assertRunMutationAllowed } from "./run-recovery.js";
+import { stageLifecycleInstruction } from "../harness-runtime/lib/delegation-instructions.mjs";
 const flowId = "mb-sdlc-vnext-specify";
 const protocolizeFlowId = "mb-sdlc-vnext-protocolize";
 const flowVersion = 4;
@@ -61,7 +62,7 @@ export function prepareVnextSpecifyStart(context, input) {
     if (preflight.ok !== true)
         throw new AppError("permission_preflight_failed", "SPECIFY project context is not readable", 1, { preflight });
     const grounding = projectGrounding(projectRoot);
-    const handoff = run ? executionSnapshot(context, run.project_id, run.id) : executionSnapshotFromProfile(context, start?.executionProfile);
+    const handoff = run ? executionSnapshot(context, run.project_id, run.id, projectRoot, run.workspace_root) : executionSnapshotFromProfile(context, start?.executionProfile, projectRoot, projectRoot);
     return { projectRoot, intake, discussion, template, startInput, start, preflight, grounding, handoff };
 }
 function assertSpecifyNotStarted(context, projectRoot, runId) {
@@ -187,21 +188,14 @@ export function submitVnextSpecify(context, input) {
         const handoff = continuesToProtocolize ? executionSnapshotFromPath(path.join(stageRoot, "work-context.json"), work.work_id) : null;
         const sameSessionContinuation = handoff?.stage_handoff.effective === "same_session";
         const terminal = !continuesToProtocolize && (outcome === "specified" || outcome === "failed" || outcome === "cancelled");
-        if (terminal) {
-            context.db.run("UPDATE works SET status = ?, result = ?, completed_at = ?, updated_at = ? WHERE work_id = ?", [outcome === "specified" ? "completed" : outcome, normalizedResult, now, now, work.work_id]);
-            context.db.run("UPDATE work_sessions SET status = ?, result_path = ?, completed_at = ?, updated_at = ? WHERE work_id = ? AND status = 'running'", [outcome === "specified" ? "completed" : outcome, resultFile, now, now, work.work_id]);
-        }
         const workSession = latestWorkSession(context, work.work_id);
-        if (workSession && !sameSessionContinuation) {
-            context.db.run("UPDATE work_sessions SET status = 'completed', result_path = ?, updated_at = ?, completed_at = ? WHERE id = ?", [resultFile, now, now, workSession.id]);
-        }
         const reportPath = path.join(stageRoot, "stage-report.json");
         const markdownPath = path.join(stageRoot, "stage-report.md");
         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, runRoot: runHome });
-        completeFlowRunStage(context, {
+        const preparedReport = prepareStageReport(report);
+        validateSchema({ schemaName: "stage-report", file: reportPath, data: preparedReport.normalized, projectRoot, ddFlowHome: context.ddFlowHome, runId: run.id, runRoot: runHome });
+        const completion = {
             projectRoot,
             runId: run.id,
             stage: stageId,
@@ -209,7 +203,20 @@ export function submitVnextSpecify(context, input) {
             data: "specify.json",
             dataSchemaId: "dd-flow/specify@1",
             report: "stage-report.md",
-            stageReport: "stage-report.html"
+            stageReport: "stage-report.html",
+            dataSha256: crypto.createHash("sha256").update(fs.readFileSync(resultFile)).digest("hex")
+        };
+        const preparedCompletion = prepareFlowRunStageCompletion(context, completion);
+        withStageSettlement(context, () => {
+            const current = requireWork(context, work.work_id);
+            if (current.status !== "running" || current.updated_at !== work.updated_at)
+                throw new AppError("work_generation_stale", "SPECIFY Work changed during finish preparation", 1, { work_id: work.work_id });
+            if (terminal && context.db.run("UPDATE works SET status = ?, result = ?, completed_at = ?, updated_at = ? WHERE work_id = ? AND status = 'running' AND updated_at = ?", [outcome === "specified" ? "completed" : outcome, normalizedResult, now, now, work.work_id, work.updated_at]).changes !== 1)
+                throw new AppError("work_generation_stale", "SPECIFY Work changed during finish preparation", 1, { work_id: work.work_id });
+            if (workSession && !sameSessionContinuation && context.db.run("UPDATE work_sessions SET status = 'completed', result_path = ?, updated_at = ?, completed_at = ? WHERE id = ? AND status = 'running' AND updated_at = ?", [resultFile, now, now, workSession.id, workSession.updated_at]).changes !== 1)
+                throw new AppError("work_generation_stale", "SPECIFY Session changed during finish preparation", 1, { work_id: work.work_id, work_session_id: workSession.id });
+            acceptStageReport(context, { projectId: project.id, runId: run.id, stage: stageId, root: stageRoot, prepared: preparedReport });
+            completeFlowRunStage(context, completion, preparedCompletion);
         });
         const updatedWork = requireWork(context, work.work_id);
         const updatedWorkSession = workSession ? requireWorkSession(context, workSession.id) : null;
@@ -420,7 +427,8 @@ function renderPrompt(input) {
         "```",
         "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.finishCommand}\`.`,
-        "Do not combine the lifecycle command with cat, skill reads, Git commands, pipes or shell operators. If finish reports a no-effect validation error, correct the same result file and use its returned retry_command in this Session. Internal invocation IDs are bound by the runtime and must not be copied or invented. After success, follow only its returned next directive; a focused eval controller may explicitly stop at this stage boundary.",
+        "Do not combine the lifecycle command with cat, skill reads, Git commands, pipes or shell operators. After success, follow only its returned next directive; a focused eval controller may explicitly stop at this stage boundary.",
+        stageLifecycleInstruction,
         "</output_contract>",
         ""
     ].join("\n");
@@ -584,19 +592,19 @@ export function readVnextFlowDefinition(projectRoot) {
     }
     return null;
 }
-function executionSnapshot(context, projectId, runId) {
+function executionSnapshot(context, projectId, runId, projectRoot, workspaceRoot) {
     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;
-    return executionSnapshotFromProfile(context, snapshot?.execution_profile, runId);
+    return executionSnapshotFromProfile(context, snapshot?.execution_profile, projectRoot, workspaceRoot, runId);
 }
-function executionSnapshotFromProfile(context, profile, runId) {
+function executionSnapshotFromProfile(context, profile, projectRoot, workspaceRoot, runId) {
     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;
+        handoff = resolveStageTransition({ ddFlowHome: context.ddFlowHome, policy: profile.settings.execution, profiles: profile.agent_profiles, projectRoot, workspaceRoot, fromStage: "specify", stage: "protocolize", stageSessionMode: handoff, mergeMode: profile.settings.merge_mode }).session_mode;
     }
     return { stage_handoff: { effective: handoff, source: "run_override" } };
 }