@deksden-com/dd-flow-cli 0.9.0-beta.75 → 0.9.0-beta.79

package/dist/services/vnext-protocolize.js

@@ -7,18 +7,19 @@ 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]);
@@ -38,7 +39,7 @@ 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);
@@ -50,44 +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), finishCommand: managedLifecycleCommand(context, `${flowCommand(context)} stage finish ${run.id} --stage protocolize --project-root ${JSON.stringify(projectRoot)} --result-file ${JSON.stringify(resultPath)} --json`) });
+    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: 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 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 {
@@ -95,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 = frozenContext.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
@@ -110,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.
@@ -140,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, runRoot: requireRunHome(run) });
-    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"));
@@ -316,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, 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) {
@@ -444,16 +483,17 @@ 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.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 });
@@ -461,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;
 }
@@ -509,7 +570,12 @@ 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);
+    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)

package/dist/services/vnext-specify.js

@@ -4,18 +4,21 @@ import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { AppError } from "../shared/errors.js";
-import { applyExternalStageContext } from "./stage-context.js";
+import { applyExternalStageContext, prepareExternalStageContext } from "./stage-context.js";
 import { ensureVnextWorkStorage } from "../storage/database.js";
-import { resolveProjectRoot, writeJsonAtomic } from "../storage/paths.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, startFlowRun } from "./runs.js";
+import { advanceFlowRun, appendFlowRunTimelineEvent, attachFlowRunStage, completeFlowRun, completeFlowRunStage, getFlowRunStatus, prepareFlowRunStart, startFlowRun } from "./runs.js";
 import { resolveStageTransition } from "./execution-policy.js";
 import { validateSchema } from "./schema-validation.js";
 import { bindRunningWorkSession, refreshRunWorkProjection } from "./work-registry.js";
 import { nextWorkId } from "./ids.js";
 import { flowCommand, stagePauseCommand, stagePauseCommandTemplate } from "./stage-pause.js";
 import { writeStageReport } 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";
 const flowId = "mb-sdlc-vnext-specify";
 const protocolizeFlowId = "mb-sdlc-vnext-protocolize";
 const flowVersion = 4;
@@ -29,28 +32,57 @@ export function isVnextSpecifyRun(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 IN ('vnext_specify', 'vnext_protocolize')", [project.id, input.runId]));
 }
-export function launchVnextSpecify(context, input) {
-    ensureVnextWorkStorage(context.db);
+export function prepareVnextSpecifyStart(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
-    registerProject(context, { root: projectRoot });
     const intake = readIntake(input);
     const discussion = intake.markdown.trim();
     if (!discussion)
         throw new AppError("validation", "SPECIFY intake must not be empty", 2);
     const flow = assertFlowDefinition(projectRoot);
     const template = readRequiredFile(path.join(projectRoot, ".memory-bank", "dd-flow", "vnext", "specify.md"), "vNext SPECIFY prompt template");
-    const started = input.runId ? null : startFlowRun(context, {
-        projectRoot,
-        flowKind: flow.id === protocolizeFlowId ? "vnext_protocolize" : "vnext_specify",
-        subjectType: "discussion",
-        subjectId: "SPECIFY",
-        slug: input.slug ?? "specify",
-        nextAction: "await_work_session"
-    });
+    const startInput = { projectRoot, flowKind: flow.id === protocolizeFlowId ? "vnext_protocolize" : "vnext_specify", subjectType: "discussion", subjectId: "SPECIFY", slug: input.slug ?? "specify", nextAction: "await_work_session" };
+    const start = input.runId ? undefined : prepareFlowRunStart(context, startInput);
+    if (input.runId)
+        assertSpecifyNotStarted(context, projectRoot, input.runId);
+    const run = input.runId ? requireRun(context, projectRoot, input.runId) : undefined;
+    if (!run) {
+        const project = context.db.get("SELECT id FROM projects WHERE root = ?", [projectRoot]);
+        prepareOutputDirectory(project ? path.join(projectHome(context.ddFlowHome, project.id), "runs") : path.join(context.ddFlowHome, "projects"));
+    }
+    if (run) {
+        assertRunMutationAllowed(context, run.project_id, run.id);
+        const home = requiredRunHome(run), stageRoot = path.join(home, "01-specify");
+        for (const relative of ["intake/discussion.md", "01-specify/prompt.md", "01-specify/work-context.json"])
+            prepareOutputFile(path.join(home, relative));
+        if (input.externalContext)
+            prepareExternalStageContext({ stageRoot, loaded: input.externalContext });
+    }
+    const preflight = preflightMemoryPermissions({ root: projectRoot, memoryBank: ".memory-bank", flow: "custom", mode: "read", targets: [{ path: ".memory-bank", mode: "read" }] });
+    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);
+    return { projectRoot, intake, discussion, template, startInput, start, preflight, grounding, handoff };
+}
+function assertSpecifyNotStarted(context, projectRoot, runId) {
+    const existing = getFlowRunStatus(context, { projectRoot, runId });
+    if (existing.index?.stage_runs?.some(entry => entry.stage === stageId))
+        throw new AppError("stage_already_started", "SPECIFY is already started for this RUN", 1, { run_id: runId });
+}
+export function launchVnextSpecify(context, input, prepared = prepareVnextSpecifyStart(context, input)) {
+    const { projectRoot, intake, discussion, template, startInput, start, preflight, grounding, handoff } = prepared;
+    if (input.runId)
+        assertSpecifyNotStarted(context, projectRoot, input.runId);
+    const project = requireProjectByRoot(context, projectRoot);
+    const identity = hookSessionIdentity(context, project.id, input.hookEventId);
+    if (input.runId) {
+        assertRunMutationAllowed(context, project.id, input.runId);
+        assertRecoveryHookCurrent(context, project.id, input.runId, identity);
+    }
+    ensureVnextWorkStorage(context.db);
+    registerProject(context, { root: projectRoot });
+    const started = input.runId ? null : startFlowRun(context, startInput, start);
     const run = requireRun(context, projectRoot, input.runId ?? started.run.id);
-    const existingStages = getFlowRunStatus(context, { projectRoot, runId: run.id });
-    if (existingStages.index?.stage_runs?.some((entry) => entry.stage === stageId))
-        throw new AppError("stage_already_started", "SPECIFY is already started for this RUN", 1, { run_id: run.id });
     const runHome = requiredRunHome(run);
     const stageRoot = path.join(runHome, "01-specify");
     const intakeDir = path.join(runHome, "intake");
@@ -63,11 +95,6 @@ export function launchVnextSpecify(context, input) {
     const contextPath = path.join(stageRoot, "work-context.json");
     const workId = nextWorkId(context, run.project_id, "root");
     const now = context.now();
-    const preflight = writablePreflight(projectRoot, stageRoot);
-    if (preflight.ok !== true)
-        throw new AppError("permission_preflight_failed", "SPECIFY workspace is not writable", 1, { preflight });
-    const grounding = projectGrounding(projectRoot);
-    const handoff = executionSnapshot(context, run.project_id, run.id);
     const workContext = {
         schema_id: "dd-flow/work-context@1",
         system: { run_id: run.id, work_id: workId, stage: stageId },
@@ -245,13 +272,23 @@ export function finishVnextSpecifyStage(context, input) {
     const run = requireRun(context, projectRoot, input.runId);
     const stageRoot = path.join(requiredRunHome(run), "01-specify");
     const acceptedResult = path.join(stageRoot, "specify.json");
-    const suppliedResult = input.resultJson ?? readRequiredFile(path.resolve(input.resultFile ?? acceptedResult), "SPECIFY result");
+    const source = input.resultFile ? path.resolve(input.resultFile) : acceptedResult;
+    const prepared = input.result
+        ? { file: source, value: input.result }
+        : input.resultJson !== undefined
+            ? prepareJsonText(input.resultJson, { file: "<stdin>", label: "SPECIFY result" })
+            : prepareJsonSchema(source, "SPECIFY result", { schemaName: "vnext-specify", projectRoot, ddFlowHome: context.ddFlowHome, runId: run.id, runRoot: requiredRunHome(run) });
+    try {
+        validateSchema({ schemaName: "vnext-specify", file: prepared.file, data: prepared.value, projectRoot, ddFlowHome: context.ddFlowHome, runId: run.id, runRoot: requiredRunHome(run) });
+        validateObligations(prepared.value, prepared.file);
+    }
+    catch (error) {
+        return prepareError(error, { file: prepared.file, label: "SPECIFY result" });
+    }
     const candidate = path.join(stageRoot, `.specify-candidate-${crypto.randomUUID()}.json`);
-    writeText(candidate, suppliedResult);
-    // A previous worker contract allowed the final projection path as input.
-    // Do not leave that unvalidated payload behind as an accepted-looking result.
-    if (input.resultFile && path.resolve(input.resultFile) === acceptedResult)
-        fs.rmSync(acceptedResult, { force: true });
+    // Candidate storage starts only after the exact input has passed schema and
+    // semantic checks; it is never the caller's source file.
+    writeText(candidate, `${JSON.stringify(prepared.value, null, 2)}\n`);
     try {
         return submitVnextSpecify(context, { projectRoot, workId: work.work_id, resultFile: candidate, outcome: input.outcome });
     }
@@ -264,11 +301,7 @@ function readIntake(input) {
         return { markdown: input.intakeMarkdown };
     if (!input.intakeFile)
         throw new AppError("usage", "SPECIFY intake is required", 2);
-    const intakeFile = path.resolve(input.intakeFile);
-    if (!fs.existsSync(intakeFile) || !fs.statSync(intakeFile).isFile()) {
-        throw new AppError("not_found", "--intake-file must point to an existing file", 1, { intake_file: input.intakeFile });
-    }
-    return { markdown: fs.readFileSync(intakeFile, "utf8") };
+    return { markdown: prepareTextFile(input.intakeFile, "SPECIFY intake").text };
 }
 function requireRun(context, projectRoot, runId) {
     const project = requireProjectByRoot(context, projectRoot);
@@ -303,28 +336,6 @@ function requireWorkSession(context, workSessionId) {
 function latestWorkSession(context, workId) {
     return context.db.get("SELECT * FROM work_sessions WHERE work_id = ? ORDER BY created_at DESC, id DESC LIMIT 1", [workId]) ?? null;
 }
-function writablePreflight(projectRoot, stageRoot) {
-    const memoryBank = preflightMemoryPermissions({
-        root: projectRoot,
-        memoryBank: ".memory-bank",
-        flow: "custom",
-        mode: "write",
-        targets: [{ path: ".memory-bank", mode: "read" }]
-    });
-    const probe = path.join(stageRoot, `.dd-flow-probe-${crypto.randomUUID()}`);
-    try {
-        fs.writeFileSync(probe, "");
-        fs.rmSync(probe);
-        return { ...memoryBank, ok: memoryBank.ok === true, stage_workspace: { path: stageRoot, status: "passed" } };
-    }
-    catch (error) {
-        try {
-            fs.rmSync(probe, { force: true });
-        }
-        catch { /* best effort */ }
-        return { ...memoryBank, ok: false, stage_workspace: { path: stageRoot, status: "failed", message: String(error) } };
-    }
-}
 function projectGrounding(projectRoot) {
     return [
         ".memory-bank/index.md",
@@ -402,7 +413,7 @@ 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 validation error, correct the same result file and use its returned retry_command in this Session; only if no invocation-id was issued may you rerun the original command. After success, follow only its returned next directive; a focused eval controller may explicitly stop at this stage boundary.",
+        "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.",
         "</output_contract>",
         ""
     ].join("\n");
@@ -569,7 +580,9 @@ export function readVnextFlowDefinition(projectRoot) {
 function executionSnapshot(context, projectId, runId) {
     const row = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
     const snapshot = row ? JSON.parse(row.index_json) : null;
-    const profile = snapshot?.execution_profile;
+    return executionSnapshotFromProfile(context, snapshot?.execution_profile, runId);
+}
+function executionSnapshotFromProfile(context, profile, 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 });