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

package/dist/services/stage-lifecycle.js

@@ -17,6 +17,7 @@ import { preflightMemoryPermissions } from "./memory-permissions.js";
 import { registerProject } from "./projects.js";
 import { registerProtocol } from "./protocols.js";
 import { previewNextEntityId } from "./ids.js";
+import { hookSessionIdentity, sessionIdForHookEvent } from "./hooks.js";
 const stagePromptSections = [
     "stage_identity",
     "authoritative_runtime_facts",
@@ -101,7 +102,17 @@ function runtimeFacts(view, projectRoot) {
     };
 }
 export function startStage(context, input) {
+    if (input.requireSessionBinding && !input.hookEventId) {
+        throw new AppError("trusted_session_binding_required", "This stage requires a trusted harness lifecycle binding; run it from a controlled Session with the dd-flow adapter enabled", 1);
+    }
     const projectRoot = resolveProjectRoot(input.projectRoot);
+    let requiredSessionId = null;
+    let requiredIdentity = null;
+    if (input.requireSessionBinding) {
+        registerProject(context, { root: projectRoot });
+        requiredIdentity = hookSessionIdentity(context, requireProjectByRoot(context, projectRoot).id, input.hookEventId);
+        requiredSessionId = requiredIdentity.sessionId;
+    }
     const runId = input.bootstrap ? bootstrapStageRun(context, projectRoot, input) : input.runId;
     if (!runId)
         throw new AppError("usage", "stage start requires a RUN id or --bootstrap", 2);
@@ -125,11 +136,22 @@ export function startStage(context, input) {
     if (attached.run.subject.type === "protocol") {
         syncProtocolLifecycle(context, attached.run.project_id, attached.run.subject.id, input.stage, "running");
     }
-    if (input.sessionId) {
+    const sessionId = requiredSessionId ?? (input.hookEventId ? sessionIdForHookEvent(context, attached.run.project_id, input.hookEventId) : null);
+    if (sessionId) {
+        const identity = requiredIdentity ?? (input.hookEventId ? hookSessionIdentity(context, attached.run.project_id, input.hookEventId) : null);
         registerFlowSession(context, {
-            sessionId: input.sessionId,
+            sessionId,
             payloadJson: JSON.stringify({
                 project_root: projectRoot,
+                harness: identity?.harness ?? "codex-desktop",
+                provider_session_id: identity?.providerSessionId ?? sessionId,
+                agent_id: identity?.agentId ?? null,
+                provider: identity?.provider ?? null,
+                model: identity?.model ?? null,
+                reasoning: identity?.reasoning ?? null,
+                mode: identity?.mode ?? null,
+                agent_type: identity?.agentType ?? null,
+                parent_session_id: identity?.parentSessionId ?? null,
                 flow_kind: flowKindForStage(input.stage),
                 run_id: attached.run.id,
                 protocol_id: attached.run.subject.id,
@@ -145,6 +167,10 @@ export function startStage(context, input) {
     const promptPath = path.join(stageRoot, "stage-prompt.md");
     const prompt = composeStagePrompt(context, projectRoot, before, attached, input.stage, dir, preflight);
     atomicWrite(promptPath, prompt);
+    const semanticInputPath = path.join(stageRoot, "stage-input.json");
+    if (!fs.existsSync(semanticInputPath)) {
+        atomicWrite(semanticInputPath, semanticInputTemplate(input.stage));
+    }
     const promptDataPath = path.join(stageRoot, "stage-prompt.json");
     const planPath = planJsonPath(projectRoot, attached.run.subject.id);
     const aspectMapPath = path.join(stageRoot, "aspect-map.json");
@@ -165,6 +191,7 @@ export function startStage(context, input) {
             stage: stageRoot,
             protocol: attached.run.subject.id,
             intake: path.join(runHome, "intake"),
+            input: semanticInputPath,
             ...(input.stage === "plan" ? { plan: planPath, "aspect-map": aspectMapPath } : {})
         },
         write_boundary: { current: "@stage", archive: attempt, archive_writable: false },
@@ -178,8 +205,8 @@ export function startStage(context, input) {
             },
             permissions: preflight,
             session_binding: {
-                status: input.sessionId ? "bound" : "not_bound",
-                session_id: input.sessionId ?? null
+                status: sessionId ? "bound" : "unavailable",
+                session_id: sessionId
             }
         },
         required_context: sources.map((source) => ({
@@ -189,7 +216,7 @@ export function startStage(context, input) {
         })),
         worker_prompt_markdown: prompt
     });
-    validateSchema({ schemaName: "stage-prompt", file: promptDataPath, projectRoot });
+    validateSchema({ schemaName: "stage-prompt", file: promptDataPath, projectRoot, runId: attached.run.id, ddFlowHome: context.ddFlowHome });
     atomicWrite(path.join(stageRoot, "stage-start.json"), {
         schema_id: "dd-flow/stage-start@2",
         run_id: attached.run.id,
@@ -208,6 +235,7 @@ export function startStage(context, input) {
         stage_root: stageRoot,
         archive_path: null,
         prompt_path: promptPath,
+        semantic_input_path: semanticInputPath,
         aliases: {
             project: projectRoot,
             workspace: attached.run.workspace_root,
@@ -243,50 +271,71 @@ export function finishStage(context, input) {
     ensureWithin(runHome, stageRoot, "stage root");
     fs.mkdirSync(stageRoot, { recursive: true });
     const semanticFile = resolveStageFile(input.semanticFile ?? "@stage/stage-input.json", stageRoot, runHome);
-    validateSchema({ schemaName: "stage-finish-input", file: semanticFile, projectRoot });
-    const semantic = readSemanticFile(semanticFile, runHome);
-    const status = input.outcome ?? "done";
-    if (!["done", "blocked", "failed"].includes(status)) {
-        throw new AppError("validation", "Stage finish status must be done, blocked, or failed", 2, { status });
-    }
-    const coverage = workerCoverage(context, view.run.project_id, view.run.id);
-    if (coverage.status !== "complete") {
-        throw new AppError("worker_coverage_incomplete", "Stage finish requires complete worker coverage", 1, { coverage });
+    const receipt = beginFinishReceipt(context, stageRoot, semanticFile, view.run.id, input.stage);
+    try {
+        validateSchema({ schemaName: "stage-finish-input", file: semanticFile, projectRoot, runId, ddFlowHome: context.ddFlowHome });
+        const semantic = readSemanticFile(semanticFile, runHome);
+        const status = stringValue(semantic.status) ?? "done";
+        if (!["done", "waiting_for_user", "blocked", "failed"].includes(status)) {
+            throw new AppError("validation", "Stage finish status must be done, waiting_for_user, blocked, or failed", 2, { status });
+        }
+        validateStageOutcome(input.stage, status, semantic);
+        const coverage = workerCoverage(context, view.run.project_id, view.run.id);
+        if (coverage.jobs.missing?.length) {
+            throw new AppError("worker_jobs_incomplete", "Stage finish requires all declared worker jobs", 1, { coverage });
+        }
+        const lint = runTargetedMemoryBankLint(projectRoot);
+        const planFinish = input.stage === "plan"
+            ? preparePlanFinish(context, projectRoot, view, stageRoot)
+            : undefined;
+        const report = buildStageReport(context, view, input.stage, status, semantic, stageRoot, lint, planFinish);
+        const dataPath = path.join(stageRoot, "stage-report.json");
+        const reportPath = path.join(stageRoot, "stage-report.md");
+        const htmlPath = path.join(stageRoot, "stage-report.html");
+        atomicWrite(dataPath, report);
+        validateSchema({ schemaName: stageReportSchemaName(input.stage, planFinish), file: dataPath, projectRoot, runId, ddFlowHome: context.ddFlowHome });
+        atomicWrite(reportPath, renderMarkdown(report));
+        atomicWrite(htmlPath, renderHtml(projectRoot, report));
+        if (view.run.subject.type === "protocol") {
+            syncProtocolLifecycle(context, view.run.project_id, view.run.subject.id, input.stage, status, stringValue(semantic.next_action));
+        }
+        const summaryPath = updateProtocolSummary(context, projectRoot, view, report, dataPath, htmlPath, reportPath);
+        const completed = completeFlowRunStage(context, {
+            projectRoot,
+            runId,
+            stage: input.stage,
+            status,
+            stageReport: htmlPath,
+            data: dataPath,
+            dataSchemaId: String(report.schema_id),
+            report: reportPath
+        });
+        finishReceipt(receipt, { outcome: "accepted", result: { status, report: dataPath } });
+        appendAudit(context, {
+            projectId: view.run.project_id,
+            ...(view.run.subject.type === "protocol" ? { protocolId: view.run.subject.id } : {}),
+            eventType: "stage.finish.accepted",
+            payload: { run_id: runId, stage: input.stage, status, receipt: receipt.path, semantic_sha256: receipt.semantic_sha256 }
+        });
+        return {
+            ok: true,
+            schema_id: "dd-flow/stage-finish@1",
+            ...(completed && typeof completed === "object" && !Array.isArray(completed) ? completed : {}),
+            artifacts: { json: dataPath, markdown: reportPath, html: htmlPath, finish_receipt: receipt.path, ...(summaryPath ? { protocol_summary: summaryPath } : {}) },
+            gates: { worker_coverage: coverage, targeted_lint: lint },
+            generated: true
+        };
     }
-    const lint = runTargetedMemoryBankLint(projectRoot, semantic);
-    const planFinish = input.stage === "plan"
-        ? preparePlanFinish(context, projectRoot, view, stageRoot)
-        : undefined;
-    const report = buildStageReport(context, view, input.stage, status, semantic, stageRoot, lint, planFinish);
-    const dataPath = path.join(stageRoot, "stage-report.json");
-    const reportPath = path.join(stageRoot, "stage-report.md");
-    const htmlPath = path.join(stageRoot, "stage-report.html");
-    atomicWrite(dataPath, report);
-    validateSchema({ schemaName: stageReportSchemaName(input.stage, planFinish), file: dataPath, projectRoot });
-    atomicWrite(reportPath, renderMarkdown(report));
-    atomicWrite(htmlPath, renderHtml(projectRoot, report));
-    if (view.run.subject.type === "protocol") {
-        syncProtocolLifecycle(context, view.run.project_id, view.run.subject.id, input.stage, status, stringValue(semantic.next_action));
+    catch (error) {
+        finishReceipt(receipt, { outcome: "rejected", error: finishError(error) });
+        appendAudit(context, {
+            projectId: view.run.project_id,
+            ...(view.run.subject.type === "protocol" ? { protocolId: view.run.subject.id } : {}),
+            eventType: "stage.finish.rejected",
+            payload: { run_id: runId, stage: input.stage, receipt: receipt.path, semantic_sha256: receipt.semantic_sha256, error: finishError(error) }
+        });
+        throw error;
     }
-    const summaryPath = updateProtocolSummary(context, projectRoot, view, report, dataPath, htmlPath, reportPath);
-    const completed = completeFlowRunStage(context, {
-        projectRoot,
-        runId,
-        stage: input.stage,
-        status,
-        stageReport: htmlPath,
-        data: dataPath,
-        dataSchemaId: String(report.schema_id),
-        report: reportPath
-    });
-    return {
-        ok: true,
-        schema_id: "dd-flow/stage-finish@1",
-        ...(completed && typeof completed === "object" && !Array.isArray(completed) ? completed : {}),
-        artifacts: { json: dataPath, markdown: reportPath, html: htmlPath, ...(summaryPath ? { protocol_summary: summaryPath } : {}) },
-        gates: { worker_coverage: coverage, targeted_lint: lint },
-        generated: true
-    };
 }
 function runView(value) {
     if (!value || typeof value !== "object")
@@ -302,12 +351,9 @@ function syncProtocolLifecycle(context, projectId, protocolId, stage, status, ne
         return;
     const protocol = requireProtocol(context, protocolId, projectId);
     const { state } = readProtocolRuntimeState(context, protocol);
-    const currentRank = protocolStageRank(state.stage);
-    const requestedRank = protocolStageRank(targetStage);
-    const completedTarget = status === "done" ? nextStageAfterFinish(targetStage) : targetStage;
-    const completedRank = protocolStageRank(completedTarget);
-    const effectiveStage = completedRank >= currentRank ? completedTarget : state.stage;
-    const effectiveStatus = status === "done" ? "running" : status;
+    const transition = lifecycleTransition(targetStage, status);
+    const effectiveStage = transition.stage;
+    const effectiveStatus = transition.status;
     const effectiveNextAction = nextAction ?? nextActionForProtocolStage(effectiveStage);
     if (effectiveStage === state.stage && effectiveStatus === state.status && effectiveNextAction === state.next_action)
         return;
@@ -328,7 +374,7 @@ function syncProtocolLifecycle(context, projectId, protocolId, stage, status, ne
             from: state.stage,
             to: effectiveStage,
             status: effectiveStatus,
-            requested_rank: requestedRank
+            outcome: status
         }
     });
 }
@@ -341,11 +387,18 @@ function protocolStageForRunStage(stage) {
         return "implementation";
     return null;
 }
-function nextStageAfterFinish(stage) {
-    return stage === "specify" ? "plan" : "implementation";
-}
-function protocolStageRank(stage) {
-    return { registered: 0, specify: 1, plan: 2, implementation: 3 }[stage] ?? -1;
+function lifecycleTransition(stage, status) {
+    if (status === "running")
+        return { stage, status };
+    if (status === "waiting_for_user" || status === "blocked" || status === "failed")
+        return { stage, status };
+    if (status !== "done")
+        throw new AppError("invalid_transition", `Unknown stage outcome: ${status}`, 2);
+    return stage === "specify"
+        ? { stage: "plan", status: "running" }
+        : stage === "plan"
+            ? { stage: "implementation", status: "running" }
+            : { stage: "readiness", status: "running" };
 }
 function nextActionForProtocolStage(stage) {
     if (stage === "registered" || stage === "specify")
@@ -377,6 +430,8 @@ export function defaultStageDir(stage, flowKind) {
     return known[normalized] ?? `03-${normalized.replace(/[^a-z0-9]+/gi, "-").toLowerCase()}`;
 }
 function dataSchemaForStage(stage) {
+    if (stage === "specify")
+        return "dd-flow/stage-finish-input@1";
     if (stage === "plan")
         return "dd-flow/plan-stage-report@5";
     if (stage === "code" || stage === "implementation")
@@ -396,7 +451,27 @@ function stageReportSchemaName(stage, planFinish) {
 }
 function stageFinishCommand(run, projectRoot, stage) {
     const compatibilityMode = run.flow_kind === "mb-upgrade" ? " --compatibility-mode mb-upgrade" : "";
-    return `dd-flow stage finish ${run.id} --stage ${stage} --outcome done --project-root ${JSON.stringify(projectRoot)}${compatibilityMode} --json`;
+    return `dd-flow stage finish ${run.id} --stage ${stage} --project-root ${JSON.stringify(projectRoot)}${compatibilityMode} --json`;
+}
+function semanticInputTemplate(stage) {
+    const waiting = stage === "specify";
+    return {
+        schema_id: "dd-flow/stage-finish-input@1",
+        status: waiting ? "waiting_for_user" : "done",
+        result: "Replace this placeholder with the stage result.",
+        acceptance: ["Replace with the acceptance evidence for this stage."],
+        checks: ["Replace with a check actually performed."],
+        evidence: ["Replace with a durable evidence path or reference."],
+        ...(waiting ? {
+            questions: [{
+                    id: "Q-001",
+                    question: "Replace with an unresolved product decision.",
+                    impact: "Replace with the consequence of leaving it unresolved.",
+                    recommendation: "Replace with the smallest recommended decision."
+                }]
+        } : {}),
+        next_action: waiting ? "waiting_for_user: obtain the clarification packet" : "Continue to the next approved stage."
+    };
 }
 function composeStagePrompt(context, projectRoot, before, current, stage, dir, preflight) {
     const project = requireProjectByRoot(context, projectRoot);
@@ -405,8 +480,6 @@ function composeStagePrompt(context, projectRoot, before, current, stage, dir, p
         return fs.existsSync(absolute) ? `### ${label}\n\n${fs.readFileSync(absolute, "utf8").trim()}` : `### ${label}\n\n(unavailable)`;
     }).join("\n\n");
     const protocol = safeProtocolState(context, current.run.project_id, current.run.subject.id);
-    const requiredContext = stageInstructionSources(context, projectRoot, current.run.flow_kind, stage)
-        .map(({ label }) => `- Read: \`${label}\``).join("\n");
     return [
         "<stage_identity>",
         "# Stage work packet",
@@ -443,7 +516,7 @@ function composeStagePrompt(context, projectRoot, before, current, stage, dir, p
         "</applicable_instructions>",
         "",
         "<required_context>",
-        requiredContext || "- No additional stage-specific source is required.",
+        "The bounded canonical instructions above are already included in this packet. Do not reopen them, prime.md, indexes, CLI help, Git status, or runtime state unless new semantic evidence makes a specific source necessary.",
         "</required_context>",
         "",
         "<work_contract>",
@@ -453,7 +526,9 @@ function composeStagePrompt(context, projectRoot, before, current, stage, dir, p
         "",
         "<completion_contract>",
         `Write semantic output to \`@stage/stage-input.json\`, then run: \`${stageFinishCommand(current.run, projectRoot, stage)}\`.`,
+        "`@stage/stage-input.json` already contains the only valid field layout. Replace every placeholder; do not add mechanical fields such as changed_files. Set `status` to `done`, `waiting_for_user`, `blocked`, or `failed`. For `waiting_for_user`, preserve each question as a structured item in `questions` with id, question, impact, and recommended answer when known. For SPECIFY, `done` means there are no unresolved structured questions.",
         "The CLI must generate validated JSON, Markdown, HTML and protocol-summary evidence.",
+        "If finish rejects a required semantic status or a successful receipt disagrees with it, stop immediately with `flow_contract_conflict`: do not rewrite the result to another permitted status, retry finish, repair RUN state, or start a downstream stage.",
         "</completion_contract>",
     ].join("\n");
 }
@@ -478,7 +553,9 @@ function stageInstructionSources(context, projectRoot, flowKind, stage) {
             .map((file) => ({ label: `canonical:${file}`, absolute: path.join(flowRoot, file) }));
     }
     const filesByStage = {
-        specify: [".memory-bank/dd-flow/mb-sdlc/specify/stage.md"],
+        specify: [
+            ".memory-bank/dd-flow/mb-sdlc/specify/packet.md"
+        ],
         plan: [".memory-bank/dd-flow/plan.md"],
         code: [".memory-bank/dd-flow/code.md", ".memory-bank/dd-flow/mb-sdlc/code/implement.md"],
         implementation: [".memory-bank/dd-flow/code.md", ".memory-bank/dd-flow/mb-sdlc/code/implement.md"],
@@ -507,6 +584,49 @@ function readSemanticFile(file, runHome) {
         throw new AppError("validation", "Semantic input must be a JSON object", 2);
     return value;
 }
+function validateStageOutcome(stage, status, semantic) {
+    if (stage !== "specify")
+        return;
+    const questions = Array.isArray(semantic.questions) ? semantic.questions : [];
+    if (status === "waiting_for_user" && questions.length === 0) {
+        throw new AppError("semantic_status_inconsistent", "SPECIFY waiting_for_user requires at least one structured question", 2);
+    }
+    if (status === "done" && questions.length > 0) {
+        throw new AppError("semantic_status_inconsistent", "SPECIFY done cannot contain unresolved structured questions", 2);
+    }
+}
+function beginFinishReceipt(context, stageRoot, semanticFile, runId, stage) {
+    const receiptDir = path.join(stageRoot, "finish-receipts");
+    fs.mkdirSync(receiptDir, { recursive: true });
+    const number = fs.readdirSync(receiptDir).filter((file) => /^\d{3}\.json$/u.test(file)).length + 1;
+    const receiptPath = path.join(receiptDir, `${String(number).padStart(3, "0")}.json`);
+    let raw = null;
+    try {
+        raw = fs.readFileSync(semanticFile, "utf8");
+    }
+    catch { /* receipt records the missing input below */ }
+    const semanticSha = raw === null ? null : crypto.createHash("sha256").update(raw).digest("hex");
+    atomicWrite(receiptPath, {
+        schema_id: "dd-flow/stage-finish-receipt@1",
+        run_id: runId,
+        stage,
+        attempted_at: context.now(),
+        semantic_file: semanticFile,
+        semantic_sha256: semanticSha,
+        semantic_input_raw: raw,
+        outcome: "pending"
+    });
+    return { path: receiptPath, semantic_sha256: semanticSha };
+}
+function finishReceipt(receipt, outcome) {
+    const current = JSON.parse(fs.readFileSync(receipt.path, "utf8"));
+    atomicWrite(receipt.path, { ...current, ...outcome, finished_at: new Date().toISOString() });
+}
+function finishError(error) {
+    if (error instanceof AppError)
+        return { code: error.code, message: error.message, details: error.details };
+    return { code: "unexpected", message: String(error) };
+}
 function resolveStageFile(file, stageRoot, runHome) {
     const candidate = file === "@stage" || file.startsWith("@stage/")
         ? path.join(stageRoot, file.slice("@stage".length).replace(/^[/\\]/u, ""))
@@ -516,7 +636,7 @@ function resolveStageFile(file, stageRoot, runHome) {
 }
 function buildStageReport(context, view, stage, status, semantic, stageRoot, lint, planFinish) {
     const result = stringValue(semantic.result) ?? `Stage ${stage} finished with status ${status}.`;
-    const changedFiles = stringArray(semantic.changed_files, gitChangedFiles(view.run.workspace_root));
+    const changedFiles = gitChangedFiles(view.run.workspace_root);
     const checks = stringArray(semantic.checks, []);
     const evidence = stringArray(semantic.evidence, []);
     const acceptance = stringArray(semantic.acceptance, []);
@@ -608,11 +728,12 @@ function buildStageReport(context, view, stage, status, semantic, stageRoot, lin
         };
     }
     return {
-        schema_id: "dd-flow/stage-report@1",
+        schema_id: "dd-flow/stage-report@2",
         run_id: view.run.id,
         stage,
         generated_at: finishedAt,
         verdict: status,
+        summary: result,
         semantic: {
             result,
             acceptance,
@@ -620,6 +741,7 @@ function buildStageReport(context, view, stage, status, semantic, stageRoot, lin
             checks,
             evidence,
             next_action: stringValue(semantic.next_action) ?? "Resolve the stage result before continuing.",
+            ...(Array.isArray(semantic.questions) ? { questions: semantic.questions } : {}),
             ...(Array.isArray(semantic.reviewer_findings) ? { reviewer_findings: semantic.reviewer_findings } : {}),
             ...(Array.isArray(semantic.def_outcomes) ? { def_outcomes: semantic.def_outcomes } : {})
         },
@@ -634,8 +756,7 @@ function buildStageReport(context, view, stage, status, semantic, stageRoot, lin
         artifacts: {
             json: path.join(stageRoot, "stage-report.json"),
             markdown: path.join(stageRoot, "stage-report.md"),
-            html: path.join(stageRoot, "stage-report.html"),
-            summary: path.join(stageRoot, "stage-report.md")
+            html: path.join(stageRoot, "stage-report.html")
         },
         validation: {
             permission_scope: "known_targets_only",
@@ -706,7 +827,7 @@ function gitChangedFiles(workspaceRoot) {
     return result.stdout.split(/\r?\n/).filter(Boolean).map((line) => line.slice(3).trim()).filter(Boolean);
 }
 function workerCoverage(context, projectId, runId) {
-    const sessions = context.db.all("SELECT * FROM flow_sessions WHERE project_id = ? AND run_id = ? ORDER BY created_at, session_id", [projectId, runId]);
+    const sessions = context.db.all("SELECT * FROM sessions WHERE project_id = ? AND run_id = ? ORDER BY created_at, session_id", [projectId, runId]);
     const report = reconcileSessionCoverage(sessions);
     const jobs = context.db.all("SELECT job_id, status FROM flow_jobs WHERE project_id = ? AND run_id = ? ORDER BY job_id", [projectId, runId]);
     const missingJobs = jobs.filter((job) => job.status !== "done").map((job) => job.job_id);
@@ -720,9 +841,8 @@ function workerCoverage(context, projectId, runId) {
         jobs: { expected: jobs.map((job) => job.job_id), missing: missingJobs }
     };
 }
-function runTargetedMemoryBankLint(projectRoot, semantic) {
-    const declared = stringArray(semantic.changed_files, []);
-    const files = [...new Set(declared.filter((file) => file.startsWith(".memory-bank/") && file.toLowerCase().endsWith(".md") && !file.split(/[\\/]/u).some((part) => part === ".." || part.startsWith(".env"))))];
+export function runTargetedMemoryBankLint(projectRoot, selectedFiles) {
+    const files = [...new Set((selectedFiles ?? gitChangedFiles(projectRoot)).filter((file) => file.startsWith(".memory-bank/") && file.toLowerCase().endsWith(".md") && !file.split(/[\\/]/u).some((part) => part === ".." || part.startsWith(".env"))))];
     for (const file of files)
         ensureWithin(projectRoot, path.resolve(projectRoot, file), "lint target");
     if (files.length === 0) {
@@ -769,16 +889,19 @@ function renderMarkdown(report) {
 }
 function renderHtml(projectRoot, report) {
     const plan = report.schema_id === "dd-flow/plan-stage-report@5";
+    const specify = report.schema_id === "dd-flow/stage-report@2" && report.stage === "specify";
     const templatePath = path.join(projectRoot, plan
         ? ".memory-bank/dd-flow/mb-sdlc/plan/stage-report-template.html"
-        : ".memory-bank/dd-flow/mb-sdlc/code/stage-report-template.html");
+        : specify
+            ? ".memory-bank/dd-flow/mb-sdlc/specify/stage-report-template.html"
+            : ".memory-bank/dd-flow/mb-sdlc/code/stage-report-template.html");
     if (!fs.existsSync(templatePath))
-        throw new AppError("stage_report_template_missing", "Code stage report template is missing", 1, { path: templatePath });
+        throw new AppError("stage_report_template_missing", "Stage report template is missing", 1, { path: templatePath });
     const template = fs.readFileSync(templatePath, "utf8");
     const canonicalMarker = "__STAGE_REPORT_DATA__";
     const legacyMarker = "__CODE_DASHBOARD_DATA__";
     if (!template.includes(canonicalMarker) && (!template.includes("script id=\"code-data\"") || !template.includes(legacyMarker))) {
-        throw new AppError("stage_report_template_invalid", "Code stage report template is missing required anchors", 1, { path: templatePath });
+        throw new AppError("stage_report_template_invalid", "Stage report template is missing required anchors", 1, { path: templatePath });
     }
     const embedded = JSON.stringify(report).replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/&/g, "\\u0026");
     return template.replace(canonicalMarker, embedded).replace(legacyMarker, embedded);

package/dist/services/stage-pause.js

@@ -0,0 +1,175 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { findRecentMatchingHookEvent, claimStageResumeHookEvent, stageResumeMatchKey } from "./hooks.js";
+import { requireProjectByRoot } from "./projects.js";
+import { appendFlowRunTimelineEvent, pauseFlowRunStage, resumeFlowRunStage } from "./runs.js";
+import { refreshRunWorkProjection } from "./work-registry.js";
+export function pauseStageForUser(context, input) {
+    const projectRoot = resolveProjectRoot(input.projectRoot);
+    const project = requireProjectByRoot(context, projectRoot);
+    const run = requireRun(context, project.id, input.runId);
+    const work = requireWork(context, project.id, run.id, input.workId);
+    if (work.status !== "running")
+        throw new AppError("invalid_work_state", "Only a running Work can pause", 1, { work_id: work.work_id, status: work.status });
+    const question = input.question;
+    if (!question.trim())
+        throw new AppError("validation", "stage pause requires a non-empty user question", 2);
+    const stage = requireStage(run, input.stage, "running");
+    const pauseId = nextPauseId(requireRunHome(run));
+    const pauseRoot = path.join(requireRunHome(run), "intake", "hitl", `${pauseId}-${safeStage(input.stage)}`);
+    const questionPath = path.join(pauseRoot, "question.md");
+    fs.mkdirSync(pauseRoot, { recursive: true });
+    fs.writeFileSync(questionPath, question);
+    const now = context.now();
+    context.db.run("UPDATE works SET status = 'paused', updated_at = ? WHERE work_id = ? AND status = 'running'", [now, work.work_id]);
+    pauseFlowRunStage(context, { projectRoot, runId: run.id, stage: stage.stage, workId: work.work_id, pauseId, questionPath });
+    refreshRunWorkProjection(context, project.id, run.id);
+    const resume = stageResumeCommand(context, { runId: run.id, stage: stage.stage, workId: work.work_id, projectRoot });
+    const resumeTemplate = `${resume} <<'USER_ANSWER'\n<paste the complete user answer exactly>\nUSER_ANSWER`;
+    return {
+        ok: true,
+        outcome: "paused",
+        run_id: run.id,
+        work_id: work.work_id,
+        stage: stage.stage,
+        pause: { id: pauseId, reason: "waiting_for_user", question_path: questionPath, user_message: question },
+        next_action: "ask_user_then_resume_same_stage",
+        agent_instruction: "Send user_message to the user and stop this Turn. When the user answers, do not interpret or edit the answer first: make resume_command the first flow command, pass the complete raw answer on stdin, then follow the returned continuation prompt. Do not create a RUN, Work, attempt, or stage start.",
+        resume_command: resume,
+        resume_command_template: resumeTemplate
+    };
+}
+export function resumeStageAfterUser(context, input) {
+    const projectRoot = resolveProjectRoot(input.projectRoot);
+    const project = requireProjectByRoot(context, projectRoot);
+    const run = requireRun(context, project.id, input.runId);
+    const work = requireWork(context, project.id, run.id, input.workId);
+    if (work.status !== "paused")
+        throw new AppError("invalid_work_state", "stage resume requires its paused Work", 1, { work_id: work.work_id, status: work.status });
+    const stage = requireStage(run, input.stage, "paused");
+    if (!stage.pause || stage.pause.work_id !== work.work_id || stage.pause.answer_path)
+        throw new AppError("invalid_stage_state", "Stage has no unanswered pause for this Work", 1, { run_id: run.id, stage: stage.stage, work_id: work.work_id });
+    if (!input.answer.trim())
+        throw new AppError("validation", "stage resume requires a non-empty user answer", 2);
+    const hookEventId = input.hookEventId ?? findRecentMatchingHookEvent(context, {
+        projectId: project.id,
+        matchKey: stageResumeMatchKey(run.id, stage.stage, work.work_id, projectRoot),
+        errorCode: "trusted_stage_resume_required",
+        operation: "stage resume"
+    }).eventKey;
+    const identity = claimStageResumeHookEvent(context, {
+        projectId: project.id,
+        runId: run.id,
+        stage: stage.stage,
+        workId: work.work_id,
+        projectRoot,
+        eventKey: hookEventId
+    });
+    const answerPath = path.join(path.dirname(stage.pause.question_path), "answer.md");
+    fs.writeFileSync(answerPath, input.answer);
+    const now = context.now();
+    const workSession = context.db.get("SELECT id, session_id, prompt_path, result_path, status FROM work_sessions WHERE work_id = ? AND status = 'running' ORDER BY created_at DESC LIMIT 1", [work.work_id]);
+    if (!workSession)
+        throw new AppError("runtime_missing", "Paused Work has no open Session link", 1, { work_id: work.work_id });
+    if (workSession.session_id !== identity.sessionId) {
+        context.db.run("UPDATE work_sessions SET status = 'completed', updated_at = ?, completed_at = ? WHERE id = ?", [now, now, workSession.id]);
+        context.db.run("INSERT INTO work_sessions (id, work_id, session_id, hook_event_id, status, prompt_path, result_path, created_at, updated_at, completed_at) VALUES (?, ?, ?, ?, 'running', ?, ?, ?, ?, NULL)", [`WSES-${crypto.randomUUID()}`, work.work_id, identity.sessionId, identity.hookEventId, workSession.prompt_path, workSession.result_path, now, now]);
+    }
+    context.db.run("UPDATE works SET status = 'running', updated_at = ? WHERE work_id = ? AND status = 'paused'", [now, work.work_id]);
+    resumeFlowRunStage(context, { projectRoot, runId: run.id, stage: stage.stage, workId: work.work_id, answerPath });
+    refreshRunWorkProjection(context, project.id, run.id);
+    appendFlowRunTimelineEvent(context, project.id, run.id, { type: "stage_resume_session_bound", stage: stage.stage, work_id: work.work_id, session_id: identity.sessionId });
+    const prompt = fs.readFileSync(workSession.prompt_path, "utf8");
+    const continuation = [
+        prompt.trimEnd(),
+        "",
+        "<hitl_resume>",
+        `- Pause: ${stage.pause.id}`,
+        `- Question source: ${stage.pause.question_path}`,
+        `- Answer source: ${answerPath}`,
+        "- Continue the same stage, Work and attempt. Do not call stage start or repeat completed preparation.",
+        "",
+        "<user_question>",
+        fs.readFileSync(stage.pause.question_path, "utf8"),
+        "</user_question>",
+        "",
+        "<user_answer>",
+        input.answer,
+        "</user_answer>",
+        "</hitl_resume>",
+        ""
+    ].join("\n");
+    return { ok: true, outcome: "resumed", run_id: run.id, work_id: work.work_id, stage: stage.stage, pause_id: stage.pause.id, question_path: stage.pause.question_path, answer_path: answerPath, prompt_path: workSession.prompt_path, worker_prompt_markdown: continuation, next_action: `continue_${stage.stage}` };
+}
+export function stagePauseCommand(context, input) {
+    return `${flowCommand(context)} stage pause ${input.runId} --stage ${input.stage} --work ${input.workId} --question-stdin --project-root ${JSON.stringify(input.projectRoot)} --json`;
+}
+/**
+ * The only shell form allowed for an agent-owned HITL pause.  Supplying a
+ * complete heredoc makes stdin explicit without asking an agent to invent a
+ * pipe, a temporary file or a second command.
+ */
+export function stagePauseCommandTemplate(command) {
+    return `${command} <<'USER_QUESTION'
+## Q-001 — <short decision title>
+
+Why this decision is required:
+- <one sentence>
+
+Options:
+- <option A>
+- <option B>
+
+Recommendation:
+- <one option and reason>
+
+Effect on scope or acceptance:
+- <one sentence>
+USER_QUESTION`;
+}
+function stageResumeCommand(context, input) {
+    return `${flowCommand(context)} stage resume ${input.runId} --stage ${input.stage} --work ${input.workId} --answer-stdin --project-root ${JSON.stringify(input.projectRoot)} --json`;
+}
+export function flowCommand(context) {
+    const defaultHome = path.resolve(path.join(os.homedir(), ".dd-flow"));
+    return context.ddFlowHome === defaultHome ? "dd-flow" : `DD_FLOW_HOME=${JSON.stringify(context.ddFlowHome)} dd-flow`;
+}
+function requireRun(context, projectId, id) {
+    const rows = context.db.all("SELECT id, short_id, project_id, project_root, run_home_path, index_json FROM runs WHERE project_id = ? AND (id = ? OR short_id = ?)", [projectId, id, id]);
+    if (rows.length !== 1)
+        throw new AppError(rows.length ? "ambiguous_alias" : "not_found", rows.length ? "RUN alias is ambiguous" : "RUN is not registered", 1, { run_id: id });
+    return rows[0];
+}
+function requireWork(context, projectId, runId, workId) {
+    const work = context.db.get("SELECT work_id, project_id, run_id, status FROM works WHERE project_id = ? AND run_id = ? AND work_id = ?", [projectId, runId, workId]);
+    if (!work)
+        throw new AppError("not_found", "Work does not belong to this RUN", 1, { run_id: runId, work_id: workId });
+    return work;
+}
+function requireStage(run, stage, status) {
+    const index = JSON.parse(run.index_json);
+    const found = index.stage_runs?.find((item) => item.stage === stage);
+    if (!found || found.status !== status)
+        throw new AppError("invalid_stage_state", `Stage must be ${status}`, 1, { run_id: run.id, stage, status: found?.status ?? "missing" });
+    return found;
+}
+function requireRunHome(run) {
+    if (!run.run_home_path)
+        throw new AppError("runtime_missing", "RUN has no artifact home", 1, { run_id: run.id });
+    return run.run_home_path;
+}
+function nextPauseId(runHome) {
+    const root = path.join(runHome, "intake", "hitl");
+    const max = fs.existsSync(root) ? fs.readdirSync(root).reduce((value, name) => Math.max(value, Number(name.match(/^HITL-(\d+)/)?.[1] ?? 0)), 0) : 0;
+    return `HITL-${String(max + 1).padStart(3, "0")}`;
+}
+function safeStage(stage) {
+    const value = stage.trim().toLowerCase();
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value))
+        throw new AppError("validation", "stage name is invalid", 2, { stage });
+    return value;
+}