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

package/dist/services/vnext-specify.js

@@ -1,19 +1,25 @@
+import { managedLifecycleCommand } from "./lifecycle-invocations.js";
 import crypto from "node:crypto";
 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, 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;
@@ -27,28 +33,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, 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) {
+    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");
@@ -61,11 +96,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.id);
     const workContext = {
         schema_id: "dd-flow/work-context@1",
         system: { run_id: run.id, work_id: workId, stage: stageId },
@@ -82,7 +112,7 @@ export function launchVnextSpecify(context, input) {
     };
     writeJson(contextPath, workContext);
     const pauseCommand = stagePauseCommand(context, { runId: run.id, stage: stageId, workId, projectRoot });
-    const prompt = renderPrompt({ workId, runId: run.id, projectRoot, stageRoot, resultPath, discussion, template, workContext, grounding, pauseCommand, pauseCommandTemplate: stagePauseCommandTemplate(pauseCommand), flow: flowCommand(context) });
+    const prompt = renderPrompt({ workId, runId: run.id, projectRoot, stageRoot, resultPath, discussion, template, workContext, grounding, pauseCommand, pauseCommandTemplate: stagePauseCommandTemplate(pauseCommand), finishCommand: managedLifecycleCommand(context, `${flowCommand(context)} stage finish ${run.id} --project-root ${JSON.stringify(projectRoot)} --stage specify --result-file ${JSON.stringify(path.join(stageRoot, "specify-result.json"))} --outcome specified --json`) });
     fs.writeFileSync(promptPath, prompt);
     const externalContext = applyExternalStageContext({ stageRoot, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
     context.db.run(`INSERT INTO works (work_id, project_id, run_id, parent_work_id, task, launch_policy, result_schema, depends_on_json, status, result, started_at, created_at, updated_at, completed_at)
@@ -126,7 +156,9 @@ export function submitVnextSpecify(context, input) {
     if (work.project_id !== project.id)
         throw new AppError("project_mismatch", "Work does not belong to --project-root", 1, { work_id: work.work_id });
     if (work.status !== "running") {
-        throw new AppError("invalid_work_state", "Work is not waiting for a SPECIFY result", 1, { work_id: work.work_id, status: work.status });
+        // This check precedes all result reads and mutations. A later legal state
+        // transition may make a new invocation appropriate, but never replays this one.
+        throw new AppError("invalid_work_state", "Work is not waiting for a SPECIFY result", 1, { work_id: work.work_id, status: work.status, retryable_no_effect: true });
     }
     const run = requireRun(context, projectRoot, work.run_id);
     if (runStatus(context, project.id, run.id) !== "running") {
@@ -156,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,
@@ -178,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;
@@ -187,9 +225,9 @@ export function submitVnextSpecify(context, input) {
             appendFlowRunTimelineEvent(context, run.project_id, run.id, { type: "work_completed", work_id: work.work_id, outcome, stage: stageId });
         if (continuesToProtocolize) {
             const nextWork = requireWork(context, work.work_id);
-            advanceFlowRun(context, { projectRoot, runId: run.id, status: "running", verdict: "specified", nextAction: "start_protocolize" });
+            advanceFlowRun(context, { settlementStage: "specify", projectRoot, runId: run.id, status: "running", verdict: "specified", nextAction: "start_protocolize" });
             refreshRunWorkProjection(context, run.project_id, run.id);
-            const nextCommand = `${flowCommand(context)} stage start ${run.id} --stage protocolize --project-root ${JSON.stringify(projectRoot)} --json`;
+            const nextCommand = managedLifecycleCommand(context, `${flowCommand(context)} stage start ${run.id} --stage protocolize --project-root ${JSON.stringify(projectRoot)} --json`);
             return {
                 ok: true,
                 schema_id: "dd-flow/vnext-work-submit@1",
@@ -241,13 +279,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 });
     }
@@ -260,11 +308,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);
@@ -299,28 +343,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",
@@ -368,6 +390,13 @@ function renderPrompt(input) {
         "```",
         "</trusted_runtime_context>",
         "",
+        "<workspace_contract>",
+        `- authoritative SPECIFY artifact directory: ${input.stageRoot}`,
+        `- result file to write: ${input.resultPath}`,
+        `- project root is read-only grounding for this Work: ${input.projectRoot}`,
+        "Write only the named result and stage-local artifacts. Do not switch cwd, create a worktree, or write another RUN/native home.",
+        "</workspace_contract>",
+        "",
         "<eval_input_boundary>",
         "Use only this prompt, the current project root, this stage workspace and project files reached through the supplied grounding. Do not read or search another RUN, transcript, prior result, reviewer material or other project under ~/.dd-flow or ~/.codex.",
         "If stage finish rejects the result, correct this same JSON result only from the returned validation error. Do not seek another schema or example outside this stage workspace.",
@@ -392,13 +421,14 @@ function renderPrompt(input) {
         "```",
         "The JSON must preserve the problem-space contract for a fresh PROTOCOLIZE worker: user intent, scope, acceptance and verification, settled defaults, relevant project facts, gap-method outcomes, task assessment, delivery shape and handoff. Use stable R-001... identifiers in requirements and AC-001... identifiers in acceptance_criteria. Do not describe implementation design.",
         "Do not finish while a material user question remains. Use stage pause instead of adding a question to specify.json.",
-        "If a user answer is required, make this the lifecycle command instead of finish. Run this exact one-command heredoc, replacing only the placeholder body with the concise user-facing question packet. The heredoc is the permitted stdin form; do not use cat, a pipe, a temporary file or a second shell command:",
+        "If a user answer is required, use the file and standalone lifecycle command below instead of finish. Write only the concise user-facing question packet to the named text file; do not combine file creation and dd-flow in one shell command:",
         "```sh",
         input.pauseCommandTemplate,
         "```",
         "The response tells you exactly what to ask and how to resume this same stage. Ask its user_message and stop the Turn.",
-        `Finish exactly once only after all questions are resolved. Run this as one standalone Bash command:\n\`${input.flow} stage finish ${input.runId} --project-root "${input.projectRoot}" --stage specify --result-file ${JSON.stringify(path.join(input.stageRoot, "specify-result.json"))} --outcome specified --json\`.`,
-        "Do not combine the lifecycle command with cat, skill reads, Git commands, pipes or shell operators. If finish reports a validation error, correct the same result file and rerun that exact command in this Session. After success, follow only its returned next directive; a focused eval controller may explicitly stop at this stage boundary.",
+        `Finish exactly once only after all questions are resolved. Run this as one standalone Bash command:\n\`${input.finishCommand}\`.`,
+        "Do not combine the lifecycle command with cat, skill reads, Git commands, pipes or shell operators. After success, follow only its returned next directive; a focused eval controller may explicitly stop at this stage boundary.",
+        stageLifecycleInstruction,
         "</output_contract>",
         ""
     ].join("\n");
@@ -562,12 +592,20 @@ export function readVnextFlowDefinition(projectRoot) {
     }
     return null;
 }
-function executionSnapshot(context, runId) {
-    const row = context.db.get("SELECT index_json FROM runs WHERE id = ?", [runId]);
+function executionSnapshot(context, projectId, runId, 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;
-    const handoff = snapshot?.execution_profile?.settings?.stage_session_mode;
+    return executionSnapshotFromProfile(context, snapshot?.execution_profile, projectRoot, workspaceRoot, 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, projectRoot, workspaceRoot, fromStage: "specify", stage: "protocolize", stageSessionMode: handoff, mergeMode: profile.settings.merge_mode }).session_mode;
+    }
     return { stage_handoff: { effective: handoff, source: "run_override" } };
 }
 function executionSnapshotFromPath(contextPath, workId) {