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

package/dist/services/vnext-specify.js

@@ -1,19 +1,24 @@
+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, 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;
@@ -27,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");
@@ -61,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.id);
     const workContext = {
         schema_id: "dd-flow/work-context@1",
         system: { run_id: run.id, work_id: workId, stage: stageId },
@@ -82,7 +111,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 +155,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") {
@@ -141,7 +172,7 @@ export function submitVnextSpecify(context, input) {
         throw new AppError("not_found", "--result-file must point to an existing file inside the SPECIFY workspace", 1, { result_file: input.resultFile });
     }
     try {
-        validateSchema({ schemaName: "vnext-specify", file: candidateFile, projectRoot, ddFlowHome: context.ddFlowHome, runId: run.id });
+        validateSchema({ schemaName: "vnext-specify", file: candidateFile, projectRoot, ddFlowHome: context.ddFlowHome, runId: run.id, runRoot: runHome });
         const result = readVnextSpecifyResult(candidateFile);
         validateObligations(result, candidateFile);
         const normalizedResult = `${JSON.stringify(result, null, 2)}\n`;
@@ -169,7 +200,7 @@ export function submitVnextSpecify(context, input) {
         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 });
+        validateSchema({ schemaName: "stage-report", file: reportPath, projectRoot, ddFlowHome: context.ddFlowHome, runId: run.id, runRoot: runHome });
         completeFlowRunStage(context, {
             projectRoot,
             runId: run.id,
@@ -187,9 +218,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 +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 });
     }
@@ -260,15 +301,11 @@ 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);
-    const run = context.db.get("SELECT id, project_id, project_root, workspace_root, run_home_path FROM runs WHERE project_id = ? AND id = ?", [project.id, runId]);
+    const run = context.db.get("SELECT id, project_id, project_root, workspace_root, run_root FROM runs WHERE project_id = ? AND id = ?", [project.id, runId]);
     if (!run)
         throw new AppError("not_found", "RUN is not registered", 1, { run_id: runId });
     return run;
@@ -280,9 +317,9 @@ function runStatus(context, projectId, runId) {
     return run.status;
 }
 function requiredRunHome(run) {
-    if (!run.run_home_path)
-        throw new AppError("runtime_missing", "RUN has no portable workspace", 1, { run_id: run.id });
-    return run.run_home_path;
+    if (!run.run_root)
+        throw new AppError("runtime_missing", "RUN has no portable artifact root", 1, { run_id: run.id });
+    return run.run_root;
 }
 function requireWork(context, workId) {
     const work = context.db.get("SELECT * FROM works WHERE work_id = ?", [workId]);
@@ -299,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",
@@ -392,13 +407,13 @@ 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. 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");
@@ -562,12 +577,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) {
+    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, 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 });
+    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;
+    }
     return { stage_handoff: { effective: handoff, source: "run_override" } };
 }
 function executionSnapshotFromPath(contextPath, workId) {