@deksden-com/dd-flow-cli 0.7.0 → 0.8.0

package/dist/services/vnext-specify.js

@@ -0,0 +1,595 @@
+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 { ensureVnextWorkStorage } from "../storage/database.js";
+import { 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 { 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";
+const flowId = "mb-sdlc-vnext-specify";
+const protocolizeFlowId = "mb-sdlc-vnext-protocolize";
+const flowVersion = 4;
+const stageId = "specify";
+const entryId = "default";
+export function isVnextSpecifyFlow(projectRoot) {
+    return Boolean(readVnextFlowDefinition(projectRoot));
+}
+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);
+    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 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");
+    fs.mkdirSync(stageRoot, { recursive: true });
+    fs.mkdirSync(intakeDir, { recursive: true });
+    const discussionPath = path.join(intakeDir, "discussion.md");
+    writeText(discussionPath, intake.markdown);
+    const promptPath = path.join(stageRoot, "prompt.md");
+    const resultPath = path.join(stageRoot, "specify.json");
+    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 },
+        execution: handoff,
+        workspace: { project_root: projectRoot, workspace_root: run.workspace_root, git: gitFacts(run.workspace_root) },
+        input: { discussion_path: discussionPath, discussion },
+        runtime: {
+            compatibility: { status: "checked", operation: "flow.launch" },
+            permissions: preflight,
+            session_binding: { status: "bound", source: "PreToolUse" }
+        },
+        artifacts: { stage_root: stageRoot, prompt_path: promptPath, result_path: resultPath },
+        grounding: grounding.map(({ source }) => source)
+    };
+    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) });
+    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)
+     VALUES (?, ?, ?, NULL, ?, ?, NULL, '[]', 'running', NULL, ?, ?, ?, NULL)`, [workId, run.project_id, run.id, "Complete the requested MB-SDLC flow through its configured stop target.", "reuse_allowed", now, now, now]);
+    const binding = bindRunningWorkSession(context, { workId, hookEventId: input.hookEventId, promptPath, resultPath });
+    const workSessionId = String(binding.work_session_id);
+    attachFlowRunStage(context, {
+        projectRoot,
+        runId: run.id,
+        stage: stageId,
+        dir: "01-specify",
+        status: "running",
+        dataSchemaId: "dd-flow/specify@1"
+    });
+    refreshRunWorkProjection(context, run.project_id, run.id);
+    appendFlowRunTimelineEvent(context, run.project_id, run.id, {
+        type: "work_waiting_for_agent",
+        work_id: workId,
+        work_session_id: workSessionId,
+        stage: stageId,
+        action_index: 1
+    });
+    return {
+        ok: true,
+        schema_id: "dd-flow/vnext-work-launch@1",
+        outcome: "work_session_required",
+        run_id: run.id,
+        work_id: workId,
+        work_session_id: workSessionId,
+        prompt_path: promptPath,
+        result_path: resultPath,
+        work_context_path: contextPath,
+        worker_prompt_markdown: fs.readFileSync(promptPath, "utf8"),
+        ...(externalContext ? { external_context: externalContext } : {})
+    };
+}
+export function submitVnextSpecify(context, input) {
+    const projectRoot = resolveProjectRoot(input.projectRoot);
+    const project = requireProjectByRoot(context, projectRoot);
+    const work = requireWork(context, input.workId);
+    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 });
+    }
+    const run = requireRun(context, projectRoot, work.run_id);
+    if (runStatus(context, project.id, run.id) !== "running") {
+        throw new AppError("run_terminal", "SPECIFY result cannot finish after its RUN has reached a terminal state", 1, { run_id: run.id });
+    }
+    const runHome = requiredRunHome(run);
+    const stageRoot = path.join(runHome, "01-specify");
+    const candidateFile = path.resolve(input.resultFile);
+    const resultFile = path.join(stageRoot, "specify.json");
+    requireInside(stageRoot, candidateFile, "--result-file");
+    if (!fs.existsSync(candidateFile) || !fs.statSync(candidateFile).isFile()) {
+        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 });
+        const result = readVnextSpecifyResult(candidateFile);
+        validateObligations(result, candidateFile);
+        const normalizedResult = `${JSON.stringify(result, null, 2)}\n`;
+        const renderedMarkdown = renderSpecifyMarkdown(result);
+        writeJsonAtomic(resultFile, result);
+        if (candidateFile !== resultFile)
+            fs.rmSync(candidateFile);
+        writeText(path.join(stageRoot, "specify.md"), renderedMarkdown);
+        const outcome = input.outcome;
+        const now = context.now();
+        const continuesToProtocolize = outcome === "specified" && flowKind(context, project.id, run.id) === "vnext_protocolize";
+        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 });
+        completeFlowRunStage(context, {
+            projectRoot,
+            runId: run.id,
+            stage: stageId,
+            status: outcome === "specified" ? "done" : outcome === "cancelled" ? "skipped" : "failed",
+            data: "specify.json",
+            dataSchemaId: "dd-flow/specify@1",
+            report: "stage-report.md",
+            stageReport: "stage-report.html"
+        });
+        const updatedWork = requireWork(context, work.work_id);
+        const updatedWorkSession = workSession ? requireWorkSession(context, workSession.id) : null;
+        refreshRunWorkProjection(context, run.project_id, run.id);
+        if (!continuesToProtocolize)
+            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" });
+            refreshRunWorkProjection(context, run.project_id, run.id);
+            const nextCommand = `${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",
+                outcome,
+                run_id: run.id,
+                work: workProjection(nextWork, latestWorkSession(context, work.work_id)),
+                next: { kind: "start_stage", stage: "protocolize", command: nextCommand, handoff_mode: handoff.stage_handoff.effective },
+                artifacts: { result_json: resultFile, result_markdown: path.join(stageRoot, "specify.md"), report_json: reportPath, report_markdown: markdownPath, report_html: htmlPath }
+            };
+        }
+        completeFlowRun(context, {
+            projectRoot,
+            runId: run.id,
+            status: outcome === "specified" ? "done" : outcome,
+            verdict: outcome,
+            nextAction: outcome === "specified" ? "start_protocolize" : "none"
+        });
+        return {
+            ok: true,
+            schema_id: "dd-flow/vnext-work-submit@1",
+            outcome,
+            run_id: run.id,
+            work: workProjection(updatedWork, updatedWorkSession),
+            artifacts: { result_json: resultFile, result_markdown: path.join(stageRoot, "specify.md"), report_json: reportPath, report_markdown: markdownPath, report_html: htmlPath }
+        };
+    }
+    catch (error) {
+        refreshRunWorkProjection(context, run.project_id, run.id);
+        appendFlowRunTimelineEvent(context, run.project_id, run.id, { type: "work_result_rejected", work_id: work.work_id, stage: stageId });
+        throw error;
+    }
+}
+export function getVnextWorkStatus(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const work = context.db.get("SELECT * FROM works WHERE work_id = ?", [input.workId]);
+    if (!work)
+        throw new AppError("not_found", "Work is not registered", 1, { work_id: input.workId });
+    if (work.project_id !== project.id)
+        throw new AppError("project_mismatch", "Work does not belong to --project-root", 1, { work_id: work.work_id });
+    const workSession = context.db.get("SELECT id, session_id, status, prompt_path, result_path, created_at, completed_at FROM work_sessions WHERE work_id = ? ORDER BY created_at DESC LIMIT 1", [work.work_id]);
+    return { ok: true, work: { ...work, ...(workSession ? { work_session: workSession } : {}) } };
+}
+export function finishVnextSpecifyStage(context, input) {
+    const projectRoot = resolveProjectRoot(input.projectRoot);
+    const project = requireProjectByRoot(context, projectRoot);
+    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, input.runId]);
+    if (!work)
+        throw new AppError("not_found", "RUN has no vNext SPECIFY Work", 1, { run_id: input.runId, stage: stageId });
+    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 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 });
+    try {
+        return submitVnextSpecify(context, { projectRoot, workId: work.work_id, resultFile: candidate, outcome: input.outcome });
+    }
+    finally {
+        fs.rmSync(candidate, { force: true });
+    }
+}
+function readIntake(input) {
+    if (input.intakeMarkdown !== undefined)
+        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") };
+}
+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]);
+    if (!run)
+        throw new AppError("not_found", "RUN is not registered", 1, { run_id: runId });
+    return run;
+}
+function runStatus(context, projectId, runId) {
+    const run = context.db.get("SELECT status FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
+    if (!run)
+        throw new AppError("not_found", "RUN is not registered", 1, { run_id: 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;
+}
+function requireWork(context, workId) {
+    const work = context.db.get("SELECT * FROM works WHERE work_id = ?", [workId]);
+    if (!work)
+        throw new AppError("not_found", "Work is not registered", 1, { work_id: workId });
+    return work;
+}
+function requireWorkSession(context, workSessionId) {
+    const workSession = context.db.get("SELECT * FROM work_sessions WHERE id = ?", [workSessionId]);
+    if (!workSession)
+        throw new AppError("not_found", "Agent WorkSession is not registered", 1, { id: workSessionId });
+    return workSession;
+}
+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",
+        ".memory-bank/structure.md",
+        ".memory-bank/project-policy.md",
+        ".memory-bank/mbb/index.md",
+        ".memory-bank/spec/index.md",
+        ".memory-bank/scenarios/index.md",
+        ".memory-bank/defs/index.md",
+        ".memory-bank/protocol/index.md",
+        ".memory-bank/plans/index.md"
+    ]
+        .map((source) => ({ source, absolute: path.join(projectRoot, source) }))
+        .filter(({ absolute }) => fs.existsSync(absolute) && fs.statSync(absolute).isFile())
+        .map(({ source, absolute }) => ({ source, content: compactMarkdown(fs.readFileSync(absolute, "utf8")) }));
+}
+function compactMarkdown(markdown) {
+    const parts = markdown.trim().split(/^---\s*$/m);
+    const frontmatter = parts.length >= 3 ? parts[1] ?? "" : "";
+    const body = parts.length >= 3 ? parts.slice(2).join("---") : markdown;
+    const metadata = frontmatter.split(/\r?\n/).filter((line) => /^(description|purpose|status):/.test(line.trim()));
+    const overview = body.split(/\r?\n/).map((line) => line.trim()).filter(Boolean).slice(0, 12);
+    return [...metadata, ...overview].join("\n").slice(0, 1600);
+}
+function renderPrompt(input) {
+    return [
+        "<work_identity>",
+        `- Flow: ${flowId}@${flowVersion}`,
+        `- RUN: ${input.runId}`,
+        `- Work: ${input.workId}`,
+        `- Stage: ${stageId}.${entryId}`,
+        "</work_identity>",
+        "",
+        "<user_discussion>",
+        input.discussion,
+        "</user_discussion>",
+        "",
+        "<trusted_runtime_context>",
+        "These facts were collected by dd-flow. Trust them; do not repeat CLI, Git, compatibility or permission discovery.",
+        "- This beta Work uses the vNext SPECIFY flow; historical protocol-first lifecycle text in project documents is not an instruction for this Work.",
+        `- Project root: ${input.projectRoot}`,
+        `- Stage workspace: ${input.stageRoot}`,
+        "```json",
+        JSON.stringify(input.workContext.workspace, null, 2),
+        "```",
+        "</trusted_runtime_context>",
+        "",
+        "<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.",
+        "</eval_input_boundary>",
+        "",
+        "<project_grounding>",
+        input.grounding.length === 0
+            ? "No project Memory Bank index was present; state this limitation explicitly if it affects the result."
+            : input.grounding.map(({ source, content }) => `### ${source}\n${content}`).join("\n\n"),
+        "These are bounded navigation excerpts. Read a referenced project file only when its specific content is necessary to settle a requirement or gap.",
+        "</project_grounding>",
+        "",
+        "<stage_instructions>",
+        input.template,
+        "</stage_instructions>",
+        "",
+        "<output_contract>",
+        `Write one complete JSON result to ${path.join(input.stageRoot, "specify-result.json")}. dd-flow validates it, atomically stores it as \`specify.json\` and renders \`specify.md\`.`,
+        "The JSON shape below is the complete contract. R-* and AC-* are the only structured semantic lists. Put all other narrative content into the four Markdown strings in sections.",
+        "```json",
+        JSON.stringify(specifyExample(), null, 2),
+        "```",
+        "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:",
+        "```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.",
+        "</output_contract>",
+        ""
+    ].join("\n");
+}
+function buildStageReport(input) {
+    return {
+        schema_id: "dd-flow/stage-report@1",
+        run_id: input.run.id,
+        stage: stageId,
+        generated_at: input.now,
+        verdict: input.outcome === "specified" ? "done" : input.outcome,
+        semantic: {
+            result: input.result.summary,
+            acceptance: input.result.acceptance_criteria.map((criterion) => criterion.id),
+            changed_files: [],
+            checks: ["specified result contract", "stage-report schema"],
+            evidence: [input.resultFile, path.join(input.stageRoot, "specify.md")],
+            next_action: input.outcome === "specified" ? "start_protocolize" : "none",
+            document_path: input.resultFile,
+            document_sha256: crypto.createHash("sha256").update(fs.readFileSync(input.resultFile)).digest("hex"),
+            projection_path: path.join(input.stageRoot, "specify.md"),
+            projection_sha256: crypto.createHash("sha256").update(input.resultMarkdown).digest("hex"),
+            work_id: input.work.work_id,
+            id: input.workSession?.id ?? null,
+            session_id: input.workSession?.session_id ?? null
+        },
+        mechanical: {
+            started_at: input.work.created_at,
+            finished_at: input.now,
+            wall_clock_ms: Math.max(0, Date.parse(input.now) - Date.parse(input.work.created_at)),
+            git: gitFacts(input.run.workspace_root),
+            observability: "query dd-flow stat after all RUN sessions have settled"
+        },
+        artifacts: {
+            json: path.join(input.stageRoot, "stage-report.json"),
+            markdown: path.join(input.stageRoot, "stage-report.md"),
+            html: path.join(input.stageRoot, "stage-report.html"),
+            summary: path.join(input.stageRoot, "stage-report.md")
+        },
+        validation: { permission_scope: "known_targets_only", memory_bank_scope: "changed_files_and_links_only", status: "passed" },
+        breadcrumbs: [{ label: "RUN", href: input.run.id, status: "available" }]
+    };
+}
+function specifyExample() {
+    return {
+        schema_id: "dd-flow/specify@1",
+        summary: "Clarified outcome.",
+        requirements: [{ id: "R-001", statement: "The system preserves the accepted business rule." }],
+        acceptance_criteria: [{ id: "AC-001", statement: "The actor observes the accepted result." }],
+        sections: {
+            problem_and_scope: "## Goal\n\n- State the problem, actors, in-scope and out-of-scope behavior.",
+            acceptance_and_verification: "## Scenario\n\n- State the observable path and evidence.",
+            gaps_defaults_and_project_facts: "## Baseline\n\n- Record the selected gap methods, defaults and binding project facts.",
+            assessment_and_protocolize_handoff: "## Handoff\n\n- Record assessment, delivery-shape seed, material sources and verification seeds."
+        }
+    };
+}
+export function readVnextSpecifyResult(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        throw new AppError("validation", "SPECIFY result must be valid JSON", 2, { file, message: String(error) });
+    }
+}
+function validateObligations(result, file) {
+    const errors = [];
+    const validate = (values, prefix) => {
+        const ids = new Set();
+        values.forEach((value, index) => {
+            const valuePath = `${prefix === "R" ? "requirements" : "acceptance_criteria"}[${index}]`;
+            if (ids.has(value.id))
+                errors.push({ path: `${valuePath}.id`, message: `SPECIFY ${prefix}-* ids must be unique` });
+            ids.add(value.id);
+            if (!new RegExp(`^${prefix}-[0-9]{3,}$`).test(value.id) || !value.statement.trim()) {
+                errors.push({ path: valuePath, message: `SPECIFY ${prefix}-* obligations need a stable id and non-empty statement` });
+            }
+        });
+    };
+    validate(result.requirements, "R");
+    validate(result.acceptance_criteria, "AC");
+    if (errors.length)
+        throw new AppError("validation", "SPECIFY obligations have validation errors", 2, { file, errors });
+}
+export function renderSpecifyMarkdown(result) {
+    const render = (values) => values.map((value) => `- ${value.id}: ${value.statement.trim()}`).join("\n");
+    return [
+        "# Summary", "", result.summary.trim(), "",
+        "# User problem and scope", "", result.sections.problem_and_scope.trim(), "",
+        "# Requirements", "", render(result.requirements), "",
+        "# Acceptance criteria", "", render(result.acceptance_criteria), "",
+        "# Acceptance and verification", "", result.sections.acceptance_and_verification.trim(), "",
+        "# Gaps, defaults and project facts", "", result.sections.gaps_defaults_and_project_facts.trim(), "",
+        "# Assessment and PROTOCOLIZE handoff", "", result.sections.assessment_and_protocolize_handoff.trim(), ""
+    ].join("\n");
+}
+function workProjection(work, workSession) {
+    return {
+        schema_id: "dd-flow/work@1",
+        ...work,
+        work_session: workSession ? {
+            id: workSession.id,
+            work_id: workSession.work_id,
+            status: workSession.status,
+            prompt_path: workSession.prompt_path,
+            result_path: workSession.result_path,
+            created_at: workSession.created_at,
+            updated_at: workSession.updated_at,
+            completed_at: workSession.completed_at
+        } : null
+    };
+}
+function writeJson(file, value) {
+    const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
+    fs.writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`);
+    fs.renameSync(tmp, file);
+}
+function writeText(file, content) {
+    const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
+    fs.writeFileSync(tmp, content);
+    fs.renameSync(tmp, file);
+}
+function requireInside(root, candidate, label) {
+    const relative = path.relative(root, candidate);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new AppError("path_escape", `${label} must be inside the SPECIFY workspace`, 2, { root, candidate });
+    }
+}
+function readRequiredFile(file, label) {
+    if (!fs.existsSync(file) || !fs.statSync(file).isFile())
+        throw new AppError("not_found", `${label} is missing`, 1, { file });
+    const content = fs.readFileSync(file, "utf8").trim();
+    if (!content)
+        throw new AppError("validation", `${label} is empty`, 2, { file });
+    return content;
+}
+function assertFlowDefinition(projectRoot) {
+    const definition = readVnextFlowDefinition(projectRoot);
+    if (!definition) {
+        throw new AppError("validation", "vNext SPECIFY flow definition does not match this beta engine", 2, { expected: `${flowId}@${flowVersion}` });
+    }
+    return definition;
+}
+export function readVnextFlowDefinition(projectRoot) {
+    for (const file of [
+        path.join(projectRoot, ".memory-bank", "dd-flow", "vnext", "mb-sdlc-vnext-protocolize.json"),
+        path.join(projectRoot, ".memory-bank", "dd-flow", "vnext", "mb-sdlc-vnext-specify.json")
+    ]) {
+        if (!fs.existsSync(file))
+            continue;
+        const definition = JSON.parse(readRequiredFile(file, "vNext SPECIFY flow definition"));
+        const actions = definition.stages && typeof definition.stages === "object"
+            ? definition.stages.specify?.entries?.default
+            : undefined;
+        const ordered = Array.isArray(actions?.actions) ? actions.actions : [];
+        if ((definition.id === flowId || definition.id === protocolizeFlowId) && definition.version === flowVersion && ordered.length === 3) {
+            return { id: definition.id };
+        }
+    }
+    return null;
+}
+function executionSnapshot(context, runId) {
+    const row = context.db.get("SELECT index_json FROM runs WHERE id = ?", [runId]);
+    const snapshot = row ? JSON.parse(row.index_json) : null;
+    const handoff = snapshot?.execution_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 });
+    return { stage_handoff: { effective: handoff, source: "run_override" } };
+}
+function executionSnapshotFromPath(contextPath, workId) {
+    try {
+        const value = JSON.parse(fs.readFileSync(contextPath, "utf8"));
+        if (value.execution?.stage_handoff?.effective === "same_session" || value.execution?.stage_handoff?.effective === "new_session")
+            return value.execution;
+    }
+    catch { /* a malformed runtime context is an engine error below */ }
+    throw new AppError("runtime_context_invalid", "SPECIFY Work is missing its immutable handoff policy", 1, { work_id: workId });
+}
+function flowKind(context, projectId, runId) {
+    return context.db.get("SELECT flow_kind FROM runs WHERE project_id = ? AND id = ?", [projectId, runId])?.flow_kind ?? null;
+}
+function gitFacts(workspaceRoot) {
+    const read = (args) => {
+        const result = spawnSync("git", ["-C", workspaceRoot, ...args], { encoding: "utf8" });
+        return result.status === 0 ? result.stdout.trim() || null : null;
+    };
+    const statusResult = spawnSync("git", ["-C", workspaceRoot, "status", "--porcelain", "--untracked-files=all"], { encoding: "utf8" });
+    const status = statusResult.status === 0 ? statusResult.stdout.trim() : null;
+    return {
+        branch: read(["branch", "--show-current"]),
+        head: read(["rev-parse", "HEAD"]),
+        status: status === null ? "unavailable" : status.length > 0 ? "dirty" : "clean",
+        remotes: (read(["remote"]) ?? "").split(/\r?\n/).filter(Boolean)
+    };
+}