@deksden-com/dd-flow-cli 0.6.0 → 0.8.0-beta.135

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",
@@ -92,11 +93,26 @@ function runtimeFacts(view, projectRoot) {
         workspace_root: view.run.workspace_root,
         run_id: view.run.id,
         protocol_id: view.run.subject.id,
+        runtime: {
+            source: "dd-flow",
+            state: "trusted",
+            flow_kind: view.run.flow_kind
+        },
         git: view.index.execution?.git ?? { branch: null, head: null, status: "unavailable" }
     };
 }
 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);
@@ -117,12 +133,25 @@ export function startStage(context, input) {
     const preflight = stagePreflight(projectRoot, stageRoot);
     if (preflight.ok !== true)
         throw new AppError("permission_preflight_failed", "Stage workspace is not writable", 1, { preflight });
-    syncProtocolLifecycle(context, attached.run.project_id, attached.run.subject.id, input.stage, "running");
-    if (input.sessionId) {
+    if (attached.run.subject.type === "protocol") {
+        syncProtocolLifecycle(context, attached.run.project_id, attached.run.subject.id, input.stage, "running");
+    }
+    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,
@@ -138,11 +167,16 @@ 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");
     const attempt = attached.index.stage_runs?.find((stage) => stage.stage === input.stage)?.attempt ?? "try-001";
     const attemptNumber = Number(attempt.replace("try-", "")) || 1;
+    const sources = stageInstructionSources(context, projectRoot, attached.run.flow_kind, input.stage);
     atomicWrite(promptDataPath, {
         schema_id: "dd-flow/stage-prompt@2",
         run_id: attached.run.id,
@@ -157,16 +191,32 @@ 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 },
-        source_fragments: stageInstructionSources(context, projectRoot, attached.run.flow_kind, input.stage).map((source) => source.label),
+        source_fragments: sources.map((source) => source.label),
         authoritative_facts: runtimeFacts(attached, projectRoot),
-        preflight,
-        required_context: stageInstructionSources(context, projectRoot, attached.run.flow_kind, input.stage).map((source) => source.label),
+        preflight: {
+            compatibility: {
+                status: "checked",
+                operation: `stage.${input.stage}`,
+                project_root: projectRoot
+            },
+            permissions: preflight,
+            session_binding: {
+                status: sessionId ? "bound" : "unavailable",
+                session_id: sessionId
+            }
+        },
+        required_context: sources.map((source) => ({
+            path: source.label,
+            reason: "Stage-specific canonical instruction source",
+            stop_condition: "Stop when the source no longer contains unresolved requirements for this stage"
+        })),
         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,
@@ -185,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,
@@ -196,7 +247,7 @@ export function startStage(context, input) {
         },
         ...(input.stage === "plan" ? { plan_ref: planPath, aspect_map_ref: aspectMapPath } : {}),
         resolved_context: { run: attached.run, stage: { name: input.stage, dir, status: "running" } },
-        next_command: `dd-flow stage finish ${attached.run.id} --stage ${input.stage} --outcome done --project-root ${JSON.stringify(projectRoot)} --json`,
+        next_command: stageFinishCommand(attached.run, projectRoot, input.stage),
         permission_probe: preflight,
         run: attached.run,
         prompt: { path: promptPath, data_path: promptDataPath },
@@ -220,48 +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 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 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 });
+    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 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: planFinish ? "plan-stage-report" : "stage-report", file: dataPath, projectRoot });
-    atomicWrite(reportPath, renderMarkdown(report));
-    atomicWrite(htmlPath, renderHtml(projectRoot, report));
-    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
-    });
-    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")
@@ -277,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;
@@ -303,7 +374,7 @@ function syncProtocolLifecycle(context, projectId, protocolId, stage, status, ne
             from: state.stage,
             to: effectiveStage,
             status: effectiveStatus,
-            requested_rank: requestedRank
+            outcome: status
         }
     });
 }
@@ -316,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")
@@ -352,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")
@@ -360,6 +440,39 @@ function dataSchemaForStage(stage) {
         return "dd-flow/merge-stage-report@2";
     return "dd-flow/code-stage-report@2";
 }
+function stageReportSchemaName(stage, planFinish) {
+    if (planFinish)
+        return "plan-stage-report";
+    if (stage === "code" || stage === "implementation")
+        return "code-stage-report";
+    if (stage === "merge")
+        return "merge-stage-report";
+    return "stage-report";
+}
+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} --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);
     const runHome = runHomePath(current.run);
@@ -367,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",
@@ -405,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>",
@@ -414,14 +525,16 @@ function composeStagePrompt(context, projectRoot, before, current, stage, dir, p
         "</work_contract>",
         "",
         "<completion_contract>",
-        `Write semantic output to \`@stage/stage-input.json\`, then run: \`dd-flow stage finish ${current.run.id} --stage ${stage} --outcome done --project-root ${JSON.stringify(projectRoot)} --json\`.`,
+        `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");
 }
 function stageInstructionSources(context, projectRoot, flowKind, stage) {
     if (flowKind === "mb-upgrade") {
-        const canon = resolveCanonRoot(context);
+        const canon = resolveCanonRoot(context, context.env.DD_MEMORYBANK ? { explicitRoot: context.env.DD_MEMORYBANK } : {});
         if (!canon.ok || !canon.canon) {
             throw new AppError("canon_unavailable", "mb-upgrade stage prompt requires the canonical Memory Bank", 1, {
                 blockers: canon.blockers,
@@ -440,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"],
@@ -469,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, ""))
@@ -478,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, []);
@@ -541,12 +699,41 @@ function buildStageReport(context, view, stage, status, semantic, stageRoot, lin
             }
         };
     }
+    if (stage === "code" || stage === "implementation") {
+        return {
+            schema_id: "dd-flow/code-stage-report@2",
+            run: { run_id: view.run.id, run_state: view.run.run_index_path },
+            stage: { name: stage, dir: path.basename(stageRoot), status },
+            project: { id: view.run.project_id, title: path.basename(view.run.project_root) },
+            subject: { id: view.run.subject.id, title: view.run.subject.id },
+            flow_flags: flowFlagsReportProjection(view.index.flow_flags),
+            overall: {
+                verdict: status === "done" ? "accepted" : status,
+                summary: result,
+                next_action: stringValue(semantic.next_action) ?? "Proceed to readiness."
+            },
+            breadcrumbs: [{ label: "RUN", href: view.run.run_index_path, status: "available" }],
+            implemented_goals: [{ title: `Stage ${stage}`, summary: result }],
+            acceptance_scenarios: acceptance.map((summary, index) => ({
+                id: `SCN-${stage}-${index + 1}`,
+                title: `Acceptance ${index + 1}`,
+                verdict: "accepted",
+                steps: [{ title: "Stage finish", summary }],
+                evidence: evidence.map((item) => ({ path: item, label: item }))
+            })),
+            changed_files: changedFiles.map((file) => ({ path: file, label: file })),
+            checks: checks.map((name) => ({ name, status: "passed" })),
+            review: { verdict: status === "done" ? "accepted" : status, findings: [] },
+            defs: Array.isArray(semantic.def_outcomes) ? semantic.def_outcomes : []
+        };
+    }
     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,
@@ -554,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 } : {})
         },
@@ -568,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",
@@ -611,6 +798,28 @@ function stringValue(value) {
 function stringArray(value, fallback) {
     return Array.isArray(value) && value.every((entry) => typeof entry === "string") ? value : fallback;
 }
+function flowFlagsReportProjection(value) {
+    if (!value) {
+        return {
+            flow_kind: "unknown",
+            snapshot_revision: 1,
+            resolution_status: "legacy_incomplete",
+            values: {},
+            snapshot_checksum: "0".repeat(64)
+        };
+    }
+    return {
+        ...(value.contract ? { contract: value.contract } : {}),
+        flow_kind: value.flow_kind ?? "unknown",
+        ...(value.preset ? { preset: value.preset } : {}),
+        snapshot_revision: value.snapshot_revision ?? 1,
+        resolution_status: value.resolution_status ?? "legacy_incomplete",
+        values: value.values ?? {},
+        ...(value.snapshot_checksum ? { snapshot_checksum: value.snapshot_checksum } : { snapshot_checksum: "0".repeat(64) }),
+        ...(Array.isArray(value.floors_applied) ? { floors_applied: value.floors_applied } : {}),
+        ...(value.resolved_at ? { resolved_at: value.resolved_at } : {})
+    };
+}
 function gitChangedFiles(workspaceRoot) {
     const result = spawnSync("git", ["-C", workspaceRoot, "status", "--short"], { encoding: "utf8" });
     if (result.status !== 0)
@@ -618,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);
@@ -632,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.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) {
@@ -681,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);