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

package/dist/services/sessions.js

@@ -8,6 +8,7 @@ import { appendAudit } from "./audit.js";
 import { cancelLaneWaitersForWorker } from "./lanes.js";
 import { checkpointSessionUsage } from "./usage.js";
 import { refreshRunSessionProjection } from "./run-projection.js";
+import { reconcileSessionCoverageRows } from "../domain/session-coverage.js";
 import { appendFlowRunTimelineEvent } from "./runs.js";
 export function recordFlowSessionObservation(context, input) {
     const duplicate = context.db.get("SELECT id FROM flow_session_segments WHERE project_id = ? AND event_key = ?", [input.projectId, input.eventKey]);
@@ -99,68 +100,7 @@ export function getFlowSessionStatus(context, input) {
     };
 }
 export function reconcileSessionCoverage(sessions) {
-    const sessionCounts = countValues(sessions.map((session) => session.session_id));
-    const duplicateSessionIds = [...sessionCounts.entries()].filter(([, count]) => count > 1).map(([id]) => id).sort();
-    const invalidSessionIds = [];
-    const parsed = sessions.map((session) => {
-        try {
-            return { session, units: normalizeCoverageUnits(JSON.parse(session.coverage_units_json || "[]")) };
-        }
-        catch {
-            invalidSessionIds.push(session.session_id);
-            return { session, units: [] };
-        }
-    });
-    const orchestrators = parsed.filter(({ session }) => session.session_kind === "orchestrator");
-    const expectedCounts = countValues(orchestrators.flatMap(({ units }) => units.map((unit) => unit.unit_id)));
-    const expectedUnitIds = [...expectedCounts.keys()].sort();
-    const duplicateExpectedUnitIds = [...expectedCounts.entries()].filter(([, count]) => count > 1).map(([id]) => id).sort();
-    const observedOwners = new Map();
-    for (const { session, units } of parsed) {
-        if (session.session_kind === "orchestrator")
-            continue;
-        for (const unit of units) {
-            const owners = observedOwners.get(unit.unit_id) ?? [];
-            owners.push(session.session_id);
-            observedOwners.set(unit.unit_id, owners);
-        }
-    }
-    const observedUnitIds = [...observedOwners.keys()].sort();
-    const missingUnitIds = expectedUnitIds.filter((unitId) => !observedOwners.has(unitId));
-    const duplicateUnitIds = [...observedOwners.entries()].filter(([, owners]) => new Set(owners).size > 1).map(([id]) => id).sort();
-    const diagnostics = [];
-    if (orchestrators.length === 0)
-        diagnostics.push("orchestrator_session_missing");
-    if (orchestrators.length > 1)
-        diagnostics.push("multiple_orchestrator_sessions");
-    if (expectedUnitIds.length === 0)
-        diagnostics.push("expected_worker_units_missing");
-    if (missingUnitIds.length > 0)
-        diagnostics.push("expected_worker_units_unobserved");
-    if (duplicateUnitIds.length > 0 || duplicateExpectedUnitIds.length > 0)
-        diagnostics.push("duplicate_coverage_binding");
-    if (duplicateSessionIds.length > 0)
-        diagnostics.push("duplicate_session_binding");
-    if (invalidSessionIds.length > 0)
-        diagnostics.push("invalid_coverage_units");
-    const unavailable = orchestrators.length === 0 || expectedUnitIds.length === 0 || invalidSessionIds.length > 0;
-    const partial = orchestrators.length !== 1
-        || missingUnitIds.length > 0
-        || duplicateUnitIds.length > 0
-        || duplicateExpectedUnitIds.length > 0
-        || duplicateSessionIds.length > 0;
-    return {
-        status: unavailable ? "unavailable" : partial ? "partial" : "complete",
-        expected_unit_ids: expectedUnitIds,
-        observed_unit_ids: observedUnitIds,
-        missing_unit_ids: missingUnitIds,
-        duplicate_unit_ids: duplicateUnitIds,
-        duplicate_expected_unit_ids: duplicateExpectedUnitIds,
-        duplicate_session_ids: duplicateSessionIds,
-        orchestrator_session_ids: orchestrators.map(({ session }) => session.session_id).sort(),
-        invalid_session_ids: [...new Set(invalidSessionIds)].sort(),
-        diagnostics
-    };
+    return reconcileSessionCoverageRows(sessions);
 }
 export function stopFlowSession(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
@@ -245,9 +185,10 @@ export function updateFlowSessionContinuation(context, projectId, sessionId, act
     return nextCount;
 }
 export function flowSessionPayloadFromRegisterCommand(command) {
-    if (!/\bdd-flow\s+session\s+register\b/.test(command)) {
+    if (/\bdd-flow\s+stage\s+start\b/.test(command))
+        return flowSessionPayloadFromStageStartCommand(command);
+    if (!/\bdd-flow\s+session\s+register\b/.test(command))
         return undefined;
-    }
     const payloadBase64 = optionFromCommand(command, "payload-base64");
     const payloadJson = optionFromCommand(command, "payload-json");
     const payloadFile = optionFromCommand(command, "payload-file");
@@ -256,6 +197,25 @@ export function flowSessionPayloadFromRegisterCommand(command) {
     }
     return decodeFlowSessionPayload({ payloadBase64, payloadJson, payloadFile });
 }
+function flowSessionPayloadFromStageStartCommand(command) {
+    const projectRoot = optionFromCommand(command, "project-root");
+    const stage = optionFromCommand(command, "stage");
+    const run = command.match(/\bdd-flow\s+stage\s+start\s+([^\s]+)/)?.[1];
+    if (!projectRoot || !stage || !run || run.startsWith("--"))
+        return undefined;
+    return {
+        project_root: projectRoot,
+        flow_kind: ["code", "implementation", "readiness", "merge"].includes(stage) ? "implementation" : "planning",
+        run_id: run,
+        protocol_id: null,
+        worker_id: null,
+        workspace_path: null,
+        continuation_policy: "go_router",
+        session_kind: "orchestrator",
+        current_stage: stage,
+        coverage_units: []
+    };
+}
 function decodeFlowSessionPayload(input) {
     if (input.payloadFile) {
         return normalizeFlowSessionPayload(parseJsonObject(fs.readFileSync(input.payloadFile, "utf8"), "session payload"));
@@ -485,9 +445,8 @@ function sessionKind(payload) {
 function normalizeCoverageUnits(value) {
     if (value === undefined || value === null)
         return [];
-    if (!Array.isArray(value)) {
+    if (!Array.isArray(value))
         throw new AppError("validation", "coverage_units must be an array", 2);
-    }
     return value.map((item, index) => {
         if (!item || typeof item !== "object" || Array.isArray(item)) {
             throw new AppError("validation", `coverage_units[${index}] must be an object`, 2);
@@ -496,16 +455,17 @@ function normalizeCoverageUnits(value) {
         if (typeof object.unit_id !== "string" || object.unit_id.length === 0) {
             throw new AppError("validation", `coverage_units[${index}].unit_id is required`, 2);
         }
-        const optional = (key) => object[key] === undefined || object[key] === null ? null : typeof object[key] === "string" ? object[key] : (() => { throw new AppError("validation", `coverage_units[${index}].${key} must be a string`, 2); })();
+        const optional = (key) => {
+            const field = object[key];
+            if (field === undefined || field === null)
+                return null;
+            if (typeof field === "string")
+                return field;
+            throw new AppError("validation", `coverage_units[${index}].${key} must be a string`, 2);
+        };
         return { unit_id: object.unit_id, group_id: optional("group_id"), job_id: optional("job_id"), kind: optional("kind") };
     });
 }
-function countValues(values) {
-    const counts = new Map();
-    for (const value of values)
-        counts.set(value, (counts.get(value) ?? 0) + 1);
-    return counts;
-}
 function requiredStringField(payload, key) {
     const value = stringField(payload, key, true);
     if (!value) {

package/dist/services/stage-lifecycle.js

@@ -5,20 +5,111 @@ import { spawnSync } from "node:child_process";
 import { requireProjectByRoot } from "./projects.js";
 import { appendAudit } from "./audit.js";
 import { persistProtocolState, requireProtocol, readProtocolRuntimeState } from "./protocols.js";
-import { attachFlowRunStage, completeFlowRunStage, getFlowRunStatus } from "./runs.js";
+import { attachFlowRunStage, completeFlowRunStage, getFlowRunStatus, startFlowRun } from "./runs.js";
 import { validateSchema } from "./schema-validation.js";
-import { reconcileSessionCoverage } from "./sessions.js";
+import { reconcileSessionCoverage, registerFlowSession } from "./sessions.js";
 import { usageForRun } from "./usage.js";
 import { boundCanonicalPlan } from "./plan-runtime.js";
 import { AppError } from "../shared/errors.js";
 import { planJsonPath, resolveProjectRoot } from "../storage/paths.js";
+import { resolveCanonRoot } from "./canon.js";
+import { preflightMemoryPermissions } from "./memory-permissions.js";
+import { registerProject } from "./projects.js";
+import { registerProtocol } from "./protocols.js";
+import { previewNextEntityId } from "./ids.js";
+const stagePromptSections = [
+    "stage_identity",
+    "authoritative_runtime_facts",
+    "preflight",
+    "task_intake",
+    "applicable_instructions",
+    "required_context",
+    "work_contract",
+    "completion_contract"
+];
+function bootstrapStageRun(context, projectRoot, input) {
+    if (input.stage !== "specify") {
+        throw new AppError("validation", "--bootstrap currently starts the initial specify stage only", 2, { stage: input.stage });
+    }
+    const subject = input.bootstrap?.subject.trim();
+    if (!subject)
+        throw new AppError("usage", "--bootstrap requires --subject", 2);
+    registerProject(context, { root: projectRoot });
+    const preview = previewNextEntityId(context, { projectRoot, type: "protocol", slug: subject });
+    const protocolId = preview.entity.id;
+    registerProtocol(context, { handshakeId: protocolId, projectRoot });
+    const started = startFlowRun(context, {
+        projectRoot,
+        flowKind: "mb_sdlc",
+        subjectType: "protocol",
+        subjectId: protocolId,
+        slug: subject,
+        nextAction: "run_specify"
+    });
+    const intakeFile = input.bootstrap?.intakeFile;
+    if (intakeFile) {
+        const source = path.resolve(intakeFile);
+        if (!fs.existsSync(source) || !fs.statSync(source).isFile()) {
+            throw new AppError("not_found", "--intake-file must point to an existing file", 1, { intake_file: intakeFile });
+        }
+        const intakeDir = path.join(started.run.run_home_path ?? path.dirname(started.run.id), "intake");
+        fs.mkdirSync(intakeDir, { recursive: true });
+        fs.copyFileSync(source, path.join(intakeDir, "user-request.md"));
+    }
+    return started.run.id;
+}
+function stagePreflight(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-permission-${crypto.randomUUID()}`);
+    try {
+        fs.writeFileSync(probe, "");
+        fs.renameSync(probe, `${probe}.renamed`);
+        fs.rmSync(`${probe}.renamed`);
+        return { ...memoryBank, ok: memoryBank.ok === true, stage_workspace: { path: stageRoot, status: "passed" } };
+    }
+    catch (error) {
+        for (const candidate of [probe, `${probe}.renamed`]) {
+            try {
+                fs.rmSync(candidate, { force: true });
+            }
+            catch { /* best effort */ }
+        }
+        return { ...memoryBank, ok: false, stage_workspace: { path: stageRoot, status: "failed", message: String(error) } };
+    }
+}
+function flowKindForStage(stage) {
+    return ["code", "implementation", "readiness", "merge"].includes(stage) ? "implementation" : "planning";
+}
+function runtimeFacts(view, projectRoot) {
+    return {
+        project_root: 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) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
-    const before = runView(getFlowRunStatus(context, { projectRoot, runId: input.runId }));
-    const dir = input.dir ?? defaultStageDir(input.stage);
+    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);
+    const before = runView(getFlowRunStatus(context, { projectRoot, runId }));
+    const dir = input.dir ?? defaultStageDir(input.stage, before.run.flow_kind);
     const attached = runView(attachFlowRunStage(context, {
         projectRoot,
-        runId: input.runId,
+        runId,
         stage: input.stage,
         dir,
         status: "running",
@@ -28,22 +119,45 @@ export function startStage(context, input) {
     const stageRoot = path.join(runHome, dir);
     ensureWithin(runHome, stageRoot, "stage root");
     fs.mkdirSync(stageRoot, { recursive: true });
-    syncProtocolLifecycle(context, attached.run.project_id, attached.run.subject.id, input.stage, "running");
+    const preflight = stagePreflight(projectRoot, stageRoot);
+    if (preflight.ok !== true)
+        throw new AppError("permission_preflight_failed", "Stage workspace is not writable", 1, { preflight });
+    if (attached.run.subject.type === "protocol") {
+        syncProtocolLifecycle(context, attached.run.project_id, attached.run.subject.id, input.stage, "running");
+    }
+    if (input.sessionId) {
+        registerFlowSession(context, {
+            sessionId: input.sessionId,
+            payloadJson: JSON.stringify({
+                project_root: projectRoot,
+                flow_kind: flowKindForStage(input.stage),
+                run_id: attached.run.id,
+                protocol_id: attached.run.subject.id,
+                worker_id: null,
+                workspace_path: attached.run.workspace_root,
+                continuation_policy: "go_router",
+                session_kind: "orchestrator",
+                current_stage: input.stage,
+                cwd: attached.run.workspace_root
+            })
+        });
+    }
     const promptPath = path.join(stageRoot, "stage-prompt.md");
-    const prompt = composeStagePrompt(context, projectRoot, before, attached, input.stage, dir);
+    const prompt = composeStagePrompt(context, projectRoot, before, attached, input.stage, dir, preflight);
     atomicWrite(promptPath, prompt);
     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@1",
+        schema_id: "dd-flow/stage-prompt@2",
         run_id: attached.run.id,
         stage: input.stage,
         generated_at: context.now(),
         prompt_path: promptPath,
-        sections: ["stage_identity", "runtime_context", "intake", "applicable_instructions", "stage_cli", "file_boundaries", "completion_contract"],
+        sections: stagePromptSections,
         aliases: {
             project: projectRoot,
             workspace: attached.run.workspace_root,
@@ -54,11 +168,30 @@ export function startStage(context, input) {
             ...(input.stage === "plan" ? { plan: planPath, "aspect-map": aspectMapPath } : {})
         },
         write_boundary: { current: "@stage", archive: attempt, archive_writable: false },
-        source_fragments: input.stage === "plan" ? [".memory-bank/dd-flow/plan.md"] : [".memory-bank/dd-flow/code.md", ".memory-bank/dd-flow/mb-sdlc/code/implement.md"]
+        source_fragments: sources.map((source) => source.label),
+        authoritative_facts: runtimeFacts(attached, projectRoot),
+        preflight: {
+            compatibility: {
+                status: "checked",
+                operation: `stage.${input.stage}`,
+                project_root: projectRoot
+            },
+            permissions: preflight,
+            session_binding: {
+                status: input.sessionId ? "bound" : "not_bound",
+                session_id: input.sessionId ?? null
+            }
+        },
+        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 });
     atomicWrite(path.join(stageRoot, "stage-start.json"), {
-        schema_id: "dd-flow/stage-start@1",
+        schema_id: "dd-flow/stage-start@2",
         run_id: attached.run.id,
         stage: input.stage,
         dir,
@@ -68,7 +201,7 @@ export function startStage(context, input) {
     });
     return {
         ok: true,
-        schema_id: "dd-flow/stage-start-response@1",
+        schema_id: "dd-flow/stage-start-response@2",
         run_id: attached.run.id,
         stage: input.stage,
         attempt_number: attemptNumber,
@@ -86,32 +219,33 @@ 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",
-        permission_probe: { status: "known_targets_only", project_root: projectRoot },
+        next_command: stageFinishCommand(attached.run, projectRoot, input.stage),
+        permission_probe: preflight,
         run: attached.run,
         prompt: { path: promptPath, data_path: promptDataPath },
+        worker_prompt_markdown: prompt,
         lifecycle: "stage start -> semantic work -> stage finish"
     };
 }
 export function finishStage(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
-    const view = runView(getFlowRunStatus(context, { projectRoot, runId: input.runId }));
+    if (!input.runId)
+        throw new AppError("usage", "stage finish requires a RUN id", 2);
+    const runId = input.runId;
+    const view = runView(getFlowRunStatus(context, { projectRoot, runId }));
     const existing = view.index.stage_runs?.find((stage) => stage.stage === input.stage);
     if (!existing) {
         throw new AppError("not_found", `Run stage is not attached: ${input.stage}`, 1, { run_id: view.run.id, stage: input.stage });
     }
-    const dir = existing.dir ?? input.dir ?? defaultStageDir(input.stage);
+    const dir = existing.dir ?? input.dir ?? defaultStageDir(input.stage, view.run.flow_kind);
     const runHome = runHomePath(view.run);
     const stageRoot = path.join(runHome, dir);
     ensureWithin(runHome, stageRoot, "stage root");
     fs.mkdirSync(stageRoot, { recursive: true });
-    if (!input.semanticFile) {
-        throw new AppError("stage_finish_input_required", "Stage finish requires --semantic-file with dd-flow/stage-finish-input@1", 2);
-    }
-    const semanticFile = resolveStageFile(input.semanticFile, stageRoot, runHome);
+    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.status ?? "done";
+    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 });
     }
@@ -128,14 +262,16 @@ export function finishStage(context, input) {
     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 });
+    validateSchema({ schemaName: stageReportSchemaName(input.stage, planFinish), 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));
+    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: input.runId,
+        runId,
         stage: input.stage,
         status,
         stageReport: htmlPath,
@@ -223,8 +359,20 @@ function nextActionForProtocolStage(stage) {
 function runHomePath(run) {
     return run.run_home_path ?? path.dirname(run.run_index_path);
 }
-function defaultStageDir(stage) {
+export function defaultStageDir(stage, flowKind) {
     const normalized = stage === "implementation" ? "code" : stage;
+    if (flowKind === "mb-upgrade") {
+        const upgrade = {
+            preflight: "01-preflight",
+            "diff-analysis": "02-diff-analysis",
+            upgrade: "03-upgrade",
+            lint: "04-lint",
+            review: "05-review",
+            merge: "06-merge"
+        };
+        if (upgrade[normalized])
+            return upgrade[normalized];
+    }
     const known = { specify: "01-specify", plan: "02-plan", code: "03-code", readiness: "03-code", merge: "04-merge" };
     return known[normalized] ?? `03-${normalized.replace(/[^a-z0-9]+/gi, "-").toLowerCase()}`;
 }
@@ -237,54 +385,109 @@ function dataSchemaForStage(stage) {
         return "dd-flow/merge-stage-report@2";
     return "dd-flow/code-stage-report@2";
 }
-function composeStagePrompt(context, projectRoot, before, current, stage, dir) {
+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} --outcome done --project-root ${JSON.stringify(projectRoot)}${compatibilityMode} --json`;
+}
+function composeStagePrompt(context, projectRoot, before, current, stage, dir, preflight) {
     const project = requireProjectByRoot(context, projectRoot);
     const runHome = runHomePath(current.run);
-    const flowFiles = stage === "plan"
-        ? [".memory-bank/dd-flow/plan.md"]
-        : [".memory-bank/dd-flow/code.md", ".memory-bank/dd-flow/mb-sdlc/code/implement.md"];
-    const instructions = flowFiles.map((file) => {
-        const absolute = path.join(projectRoot, file);
-        return fs.existsSync(absolute) ? `### ${file}\n\n${fs.readFileSync(absolute, "utf8").trim()}` : `### ${file}\n\n(unavailable)`;
+    const instructions = stageInstructionSources(context, projectRoot, current.run.flow_kind, stage).map(({ label, absolute }) => {
+        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 Prompt",
-        "",
-        "## Identity",
+        "<stage_identity>",
+        "# Stage work packet",
         `- Project: ${project.id}`,
         `- Run: ${current.run.id}`,
         `- Protocol: ${current.run.subject.id}`,
         `- Stage: ${stage}`,
         `- Attempt: ${current.index.stage_runs?.find((item) => item.stage === stage)?.attempt ?? "try-001"}`,
+        "</stage_identity>",
         "",
-        "## Runtime",
+        "<authoritative_runtime_facts>",
+        "These facts were collected by dd-flow. Trust them; do not re-run CLI, Git, compatibility, or permission discovery unless the semantic work changes the relevant state.",
         `- Project root: ${projectRoot}`,
         `- Workspace root: ${current.run.workspace_root}`,
         `- Run home: ${runHome}`,
         `- Stage root: ${path.join(runHome, dir)}`,
         `- Git branch: ${current.index.execution?.git?.branch ?? "unknown"}`,
         `- Git head: ${current.index.execution?.git?.head ?? "unknown"}`,
+        "</authoritative_runtime_facts>",
+        "",
+        "<preflight>",
+        `- Permission probe: ${String(preflight.ok === true ? "passed" : "failed")}.`,
+        "- CLI compatibility was checked before this state-changing command.",
+        "</preflight>",
         "",
-        "## Intake",
+        "<task_intake>",
         "Raw intake and provider telemetry stay under the RUN home. Promote only durable decisions to the protocol summary.",
         `- Protocol next action: ${protocol?.next_action ?? "not recorded"}`,
         `- Previous stage: ${before.index.stage_runs?.map((item) => `${item.stage}:${item.status}`).join(", ") || "none"}`,
+        "</task_intake>",
         "",
-        "## Instructions",
+        "<applicable_instructions>",
         instructions,
+        "</applicable_instructions>",
         "",
-        "## CLI",
-        "Use the project-compatible dd-flow CLI for state transitions and artifact registration. Keep paths inside the selected workspace and RUN home.",
+        "<required_context>",
+        requiredContext || "- No additional stage-specific source is required.",
+        "</required_context>",
         "",
-        "## Boundaries",
-        "Do not use raw Git as a workspace manager, unverified tools, PATH/latest fallbacks, recursive unrelated validation, or model-supplied session identity.",
+        "<work_contract>",
+        "Perform only the semantic work for this stage. Write current-stage artifacts to `@stage`; `@stage/try-NNN` is read-only archive history.",
+        "Do not repeat deterministic preflight, global CLI help, runtime/Git inspection, session registration, report rendering, summary generation, or state transition work.",
+        "</work_contract>",
         "",
-        "## Completion Contract",
-        `Finish with: dd-flow stage finish ${current.run.id} --stage ${stage} --project-root <project-root> --semantic-file @stage/stage-input.json --json`,
+        "<completion_contract>",
+        `Write semantic output to \`@stage/stage-input.json\`, then run: \`${stageFinishCommand(current.run, projectRoot, stage)}\`.`,
         "The CLI must generate validated JSON, Markdown, HTML and protocol-summary evidence.",
+        "</completion_contract>",
     ].join("\n");
 }
+function stageInstructionSources(context, projectRoot, flowKind, stage) {
+    if (flowKind === "mb-upgrade") {
+        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,
+                bootstrap: canon.bootstrap
+            });
+        }
+        const flowRoot = canon.canon.flow_root;
+        const stageSupport = {
+            "diff-analysis": "mb-upgrade/diff-analysis.md",
+            lint: "mb-upgrade/lint-verification.md",
+            review: "mb-upgrade/review/index.md",
+            merge: "mb-upgrade/merge.md"
+        };
+        return ["mb-upgrade.md", "mb-upgrade/index.md", stageSupport[stage]]
+            .filter((file) => Boolean(file))
+            .map((file) => ({ label: `canonical:${file}`, absolute: path.join(flowRoot, file) }));
+    }
+    const filesByStage = {
+        specify: [".memory-bank/dd-flow/mb-sdlc/specify/stage.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"],
+        readiness: [".memory-bank/dd-flow/mb-sdlc/code/readiness.md"],
+        merge: [".memory-bank/dd-flow/merge.md"]
+    };
+    const files = filesByStage[stage] ?? [".memory-bank/dd-flow/mb-sdlc/specify/stage.md"];
+    return files.map((file) => ({ label: file, absolute: path.join(projectRoot, file) }));
+}
 function safeProtocolState(context, projectId, protocolId) {
     try {
         const protocol = requireProtocol(context, protocolId, projectId);
@@ -376,6 +579,34 @@ 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",
         run_id: view.run.id,
@@ -446,6 +677,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)
@@ -469,7 +722,7 @@ function workerCoverage(context, projectId, runId) {
 }
 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"))))];
+    const files = [...new Set(declared.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) {