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

package/dist/services/stage-lifecycle.js

@@ -0,0 +1,572 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+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 { validateSchema } from "./schema-validation.js";
+import { reconcileSessionCoverage } 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";
+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 attached = runView(attachFlowRunStage(context, {
+        projectRoot,
+        runId: input.runId,
+        stage: input.stage,
+        dir,
+        status: "running",
+        dataSchemaId: dataSchemaForStage(input.stage)
+    }));
+    const runHome = runHomePath(attached.run);
+    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 promptPath = path.join(stageRoot, "stage-prompt.md");
+    const prompt = composeStagePrompt(context, projectRoot, before, attached, input.stage, dir);
+    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;
+    atomicWrite(promptDataPath, {
+        schema_id: "dd-flow/stage-prompt@1",
+        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"],
+        aliases: {
+            project: projectRoot,
+            workspace: attached.run.workspace_root,
+            run: attached.run.id,
+            stage: stageRoot,
+            protocol: attached.run.subject.id,
+            intake: path.join(runHome, "intake"),
+            ...(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"]
+    });
+    validateSchema({ schemaName: "stage-prompt", file: promptDataPath, projectRoot });
+    atomicWrite(path.join(stageRoot, "stage-start.json"), {
+        schema_id: "dd-flow/stage-start@1",
+        run_id: attached.run.id,
+        stage: input.stage,
+        dir,
+        attempt: attached.index.stage_runs?.find((stage) => stage.stage === input.stage)?.attempt ?? "try-001",
+        prompt: promptPath,
+        started_at: context.now()
+    });
+    return {
+        ok: true,
+        schema_id: "dd-flow/stage-start-response@1",
+        run_id: attached.run.id,
+        stage: input.stage,
+        attempt_number: attemptNumber,
+        stage_root: stageRoot,
+        archive_path: null,
+        prompt_path: promptPath,
+        aliases: {
+            project: projectRoot,
+            workspace: attached.run.workspace_root,
+            run: attached.run.id,
+            stage: stageRoot,
+            protocol: attached.run.subject.id,
+            intake: path.join(runHome, "intake"),
+            ...(input.stage === "plan" ? { plan: planPath, "aspect-map": aspectMapPath } : {})
+        },
+        ...(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 },
+        run: attached.run,
+        prompt: { path: promptPath, data_path: promptDataPath },
+        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 }));
+    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 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);
+    validateSchema({ schemaName: "stage-finish-input", file: semanticFile, projectRoot });
+    const semantic = readSemanticFile(semanticFile, runHome);
+    const status = input.status ?? "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 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: input.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")
+        throw new AppError("validation", "RUN status is malformed", 2);
+    const view = value;
+    if (!view.run || !view.index)
+        throw new AppError("validation", "RUN status is missing run or index", 2);
+    return view;
+}
+function syncProtocolLifecycle(context, projectId, protocolId, stage, status, nextAction) {
+    const targetStage = protocolStageForRunStage(stage);
+    if (!targetStage)
+        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 effectiveNextAction = nextAction ?? nextActionForProtocolStage(effectiveStage);
+    if (effectiveStage === state.stage && effectiveStatus === state.status && effectiveNextAction === state.next_action)
+        return;
+    const nextState = {
+        ...state,
+        stage: effectiveStage,
+        status: effectiveStatus,
+        next_action: effectiveNextAction,
+        updated_at: context.now()
+    };
+    persistProtocolState(context, protocol, nextState);
+    appendAudit(context, {
+        protocolId,
+        projectId,
+        eventType: "protocol.stage_lifecycle_synced",
+        payload: {
+            source_stage: stage,
+            from: state.stage,
+            to: effectiveStage,
+            status: effectiveStatus,
+            requested_rank: requestedRank
+        }
+    });
+}
+function protocolStageForRunStage(stage) {
+    if (stage === "specify")
+        return "specify";
+    if (stage === "plan")
+        return "plan";
+    if (stage === "code" || stage === "implementation")
+        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 nextActionForProtocolStage(stage) {
+    if (stage === "registered" || stage === "specify")
+        return "run_plan";
+    if (stage === "plan")
+        return "run_code_flow";
+    if (stage === "implementation")
+        return "run_readiness_gate";
+    return `continue_${stage}`;
+}
+function runHomePath(run) {
+    return run.run_home_path ?? path.dirname(run.run_index_path);
+}
+function defaultStageDir(stage) {
+    const normalized = stage === "implementation" ? "code" : stage;
+    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()}`;
+}
+function dataSchemaForStage(stage) {
+    if (stage === "plan")
+        return "dd-flow/plan-stage-report@5";
+    if (stage === "code" || stage === "implementation")
+        return "dd-flow/code-stage-report@2";
+    if (stage === "merge")
+        return "dd-flow/merge-stage-report@2";
+    return "dd-flow/code-stage-report@2";
+}
+function composeStagePrompt(context, projectRoot, before, current, stage, dir) {
+    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)`;
+    }).join("\n\n");
+    const protocol = safeProtocolState(context, current.run.project_id, current.run.subject.id);
+    return [
+        "# Stage Prompt",
+        "",
+        "## Identity",
+        `- 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"}`,
+        "",
+        "## Runtime",
+        `- 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"}`,
+        "",
+        "## 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"}`,
+        "",
+        "## Instructions",
+        instructions,
+        "",
+        "## CLI",
+        "Use the project-compatible dd-flow CLI for state transitions and artifact registration. Keep paths inside the selected workspace and RUN home.",
+        "",
+        "## Boundaries",
+        "Do not use raw Git as a workspace manager, unverified tools, PATH/latest fallbacks, recursive unrelated validation, or model-supplied session identity.",
+        "",
+        "## Completion Contract",
+        `Finish with: dd-flow stage finish ${current.run.id} --stage ${stage} --project-root <project-root> --semantic-file @stage/stage-input.json --json`,
+        "The CLI must generate validated JSON, Markdown, HTML and protocol-summary evidence.",
+    ].join("\n");
+}
+function safeProtocolState(context, projectId, protocolId) {
+    try {
+        const protocol = requireProtocol(context, protocolId, projectId);
+        return readProtocolRuntimeState(context, protocol).state;
+    }
+    catch {
+        return undefined;
+    }
+}
+function readSemanticFile(file, runHome) {
+    const resolved = path.resolve(file);
+    ensureWithin(runHome, resolved, "semantic file");
+    if (!fs.existsSync(resolved))
+        throw new AppError("not_found", "Semantic input file is missing", 1, { path: file });
+    const value = JSON.parse(fs.readFileSync(resolved, "utf8"));
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new AppError("validation", "Semantic input must be a JSON object", 2);
+    return value;
+}
+function resolveStageFile(file, stageRoot, runHome) {
+    const candidate = file === "@stage" || file.startsWith("@stage/")
+        ? path.join(stageRoot, file.slice("@stage".length).replace(/^[/\\]/u, ""))
+        : path.resolve(file);
+    ensureWithin(runHome, candidate, "semantic file");
+    return candidate;
+}
+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 checks = stringArray(semantic.checks, []);
+    const evidence = stringArray(semantic.evidence, []);
+    const acceptance = stringArray(semantic.acceptance, []);
+    const finishedAt = context.now();
+    const startedAt = view.index.stage_runs?.find((item) => item.stage === stage)?.started_at ?? finishedAt;
+    const usage = usageForRun(context, { projectId: view.run.project_id, runId: view.run.id, groupBy: "session" });
+    const usageCoverage = usage && typeof usage === "object" && "coverage" in usage ? usage.coverage : { status: "unavailable", expected: [], observed: [], missing_sessions: [] };
+    const wallClockMs = Math.max(0, Date.parse(finishedAt) - Date.parse(startedAt));
+    if (planFinish) {
+        const plan = planFinish.canonical.plan;
+        const routeDecision = plan.route_decision;
+        const codeHandoff = plan.code_handoff;
+        const nextAction = stringValue(semantic.next_action) ?? "run code";
+        return {
+            schema_id: "dd-flow/plan-stage-report@5",
+            generated_at: finishedAt,
+            protocol: {
+                id: view.run.subject.id,
+                title: view.run.subject.id,
+                project: view.run.project_id,
+                branch: view.index.execution?.git?.branch ?? "unknown",
+                stage: "plan"
+            },
+            overall: {
+                verdict: status === "done" ? "ready_for_code" : status === "blocked" ? "plan_blocked" : "degraded",
+                verdict_label: status === "done" ? "Ready for code" : "Plan requires attention",
+                score: status === "done" ? 5 : 0,
+                score_max: 5,
+                next_action: nextAction,
+                summary: result
+            },
+            route: [{
+                    label: "planning route",
+                    value: stringValue(routeDecision?.selected_route) ?? "local_compact",
+                    note: stringValue(routeDecision?.reason) ?? "Resolved by the canonical protocol plan."
+                }],
+            plan_ref: {
+                path: path.relative(view.run.project_root, planFinish.plan_path).split(path.sep).join("/"),
+                plan_id: planFinish.canonical.plan.plan_id,
+                revision: planFinish.canonical.revision,
+                sha256: planFinish.canonical.sha256,
+                item_count: planFinish.canonical.plan.items.length
+            },
+            aspect_map_ref: {
+                path: planFinish.aspect_map_path,
+                sha256: planFinish.aspect_map_sha256,
+                coverage_count: planFinish.aspect_count
+            },
+            execution_summary: { wall_clock_ms: wallClockMs },
+            delta_lint: {
+                status: lint.status,
+                selected_files: lint.files,
+                finding_count: lint.finding_count
+            },
+            transition: { status: status === "done" ? "applied" : "blocked", next_stage: status === "done" ? "implementation" : "plan" },
+            handoff: {
+                code_prompt: ".memory-bank/dd-flow/code.md",
+                must_read: Array.isArray(codeHandoff?.must_read) && codeHandoff.must_read.length > 0 ? codeHandoff.must_read : [planFinish.plan_path],
+                next_gate: nextAction
+            }
+        };
+    }
+    return {
+        schema_id: "dd-flow/stage-report@1",
+        run_id: view.run.id,
+        stage,
+        generated_at: finishedAt,
+        verdict: status,
+        semantic: {
+            result,
+            acceptance,
+            changed_files: changedFiles,
+            checks,
+            evidence,
+            next_action: stringValue(semantic.next_action) ?? "Resolve the stage result before continuing.",
+            ...(Array.isArray(semantic.reviewer_findings) ? { reviewer_findings: semantic.reviewer_findings } : {}),
+            ...(Array.isArray(semantic.def_outcomes) ? { def_outcomes: semantic.def_outcomes } : {})
+        },
+        mechanical: {
+            started_at: startedAt,
+            finished_at: finishedAt,
+            wall_clock_ms: wallClockMs,
+            git: view.index.execution?.git ?? {},
+            session_coverage: workerCoverage(context, view.run.project_id, view.run.id),
+            usage_coverage: usageCoverage
+        },
+        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")
+        },
+        validation: {
+            permission_scope: "known_targets_only",
+            memory_bank_scope: "changed_files_and_links_only",
+            status: "passed"
+        },
+        breadcrumbs: [{ label: "RUN", href: view.run.run_index_path, status: "available" }]
+    };
+}
+function preparePlanFinish(context, projectRoot, view, stageRoot) {
+    const planPath = planJsonPath(projectRoot, view.run.subject.id);
+    const canonical = boundCanonicalPlan(context, {
+        projectId: view.run.project_id,
+        protocolId: view.run.subject.id,
+        planPath
+    });
+    const aspectMapPath = path.join(stageRoot, "aspect-map.json");
+    if (!fs.existsSync(aspectMapPath)) {
+        throw new AppError("not_found", "PLAN aspect-map.json is missing", 1, { path: aspectMapPath });
+    }
+    const raw = fs.readFileSync(aspectMapPath, "utf8");
+    const value = JSON.parse(raw);
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new AppError("validation", "PLAN aspect-map.json must be a JSON object", 2, { path: aspectMapPath });
+    }
+    const map = value;
+    const rows = [map.aspects, map.coverage, map.units].find(Array.isArray);
+    return {
+        canonical,
+        plan_path: planPath,
+        aspect_map_path: aspectMapPath,
+        aspect_map_sha256: crypto.createHash("sha256").update(raw).digest("hex"),
+        aspect_count: rows?.length ?? 0
+    };
+}
+function stringValue(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function stringArray(value, fallback) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === "string") ? value : fallback;
+}
+function gitChangedFiles(workspaceRoot) {
+    const result = spawnSync("git", ["-C", workspaceRoot, "status", "--short"], { encoding: "utf8" });
+    if (result.status !== 0)
+        return [];
+    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 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);
+    const diagnostics = report.diagnostics.filter((diagnostic) => diagnostic !== "expected_worker_units_missing" || jobs.length > 0);
+    return {
+        status: diagnostics.length === 0 && missingJobs.length === 0 ? "complete" : "partial",
+        expected: report.expected_unit_ids,
+        observed: report.observed_unit_ids,
+        missing: report.missing_unit_ids,
+        diagnostics: [...diagnostics, ...(missingJobs.length > 0 ? ["jobs_unfinished"] : [])],
+        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"))))];
+    for (const file of files)
+        ensureWithin(projectRoot, path.resolve(projectRoot, file), "lint target");
+    if (files.length === 0) {
+        return { ok: true, status: "not_applicable_no_changed_docs", files, finding_count: 0 };
+    }
+    const binary = process.env.MB_LINT_BIN ?? "mb-lint";
+    const result = spawnSync(binary, ["--root", projectRoot, "--files", ...files, "--format", "json"], { cwd: projectRoot, encoding: "utf8" });
+    if (result.error || result.status === null) {
+        throw new AppError("lint_gate_unavailable", "Selected-file mb-lint is unavailable", 1, { binary, files, cause: String(result.error ?? "process did not start") });
+    }
+    let parsed = {};
+    try {
+        parsed = result.stdout ? JSON.parse(result.stdout) : {};
+    }
+    catch {
+        throw new AppError("lint_gate_invalid_output", "Selected-file mb-lint did not return JSON", 1, { binary, files });
+    }
+    if (result.status !== 0) {
+        throw new AppError("lint_gate_failed", "Selected-file mb-lint reported blocking findings", 1, { binary, files, result: parsed });
+    }
+    const findingCount = parsed && typeof parsed === "object" && Array.isArray(parsed.findings)
+        ? parsed.findings.length
+        : 0;
+    return { ok: true, status: "passed", binary, files, finding_count: findingCount, result: parsed };
+}
+function renderMarkdown(report) {
+    const plan = report.schema_id === "dd-flow/plan-stage-report@5";
+    const stage = plan ? "plan" : typeof report.stage === "string" ? report.stage : "unknown";
+    const semantic = plan
+        ? report.overall
+        : report.semantic;
+    return [
+        `# Stage ${stage}`,
+        "",
+        `- Verdict: ${String(plan ? semantic.verdict : report.verdict ?? "unknown")}`,
+        `- Result: ${plan ? semantic.summary ?? "" : semantic?.result ?? ""}`,
+        `- Next action: ${semantic?.next_action ?? ""}`,
+        "",
+        "## Generated artifacts",
+        "",
+        "The CLI generated the canonical JSON, Markdown, HTML and protocol-summary outputs.",
+        ""
+    ].join("\n");
+}
+function renderHtml(projectRoot, report) {
+    const plan = report.schema_id === "dd-flow/plan-stage-report@5";
+    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");
+    if (!fs.existsSync(templatePath))
+        throw new AppError("stage_report_template_missing", "Code 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 });
+    }
+    const embedded = JSON.stringify(report).replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/&/g, "\\u0026");
+    return template.replace(canonicalMarker, embedded).replace(legacyMarker, embedded);
+}
+function updateProtocolSummary(context, projectRoot, view, report, dataPath, htmlPath, markdownPath) {
+    const protocolRoot = path.join(view.run.workspace_root, ".memory-bank", "protocol");
+    if (!fs.existsSync(protocolRoot))
+        return undefined;
+    const document = fs.readdirSync(protocolRoot).find((entry) => entry.startsWith(`${view.run.subject.id}-`) && entry.endsWith(".md"));
+    if (!document)
+        return undefined;
+    const summaryPath = path.join(protocolRoot, document.slice(0, -3), "summary.md");
+    if (!fs.existsSync(summaryPath))
+        return undefined;
+    const stage = typeof report.stage === "string" ? report.stage : "unknown";
+    const plan = report.schema_id === "dd-flow/plan-stage-report@5";
+    const effectiveStage = plan ? "plan" : stage;
+    const result = plan
+        ? report.overall.summary ?? ""
+        : report.semantic?.result ?? "";
+    const marker = `<!-- dd-flow:stage:${effectiveStage} -->`;
+    const block = [marker, `## Runtime stage: ${effectiveStage}`, "", `- Run: ${view.run.id}`, `- Verdict: ${String(plan ? report.overall.verdict : report.verdict ?? "unknown")}`, `- Result: ${result}`, `- JSON: ${dataPath}`, `- Markdown: ${markdownPath}`, `- HTML: ${htmlPath}`, "", marker].join("\n");
+    const current = fs.readFileSync(summaryPath, "utf8");
+    const next = current.includes(marker)
+        ? current.replace(new RegExp(`${escapeRegExp(marker)}[\\s\\S]*?${escapeRegExp(marker)}`, "m"), block)
+        : `${current.trimEnd()}\n\n${block}\n`;
+    atomicWrite(summaryPath, next);
+    return summaryPath;
+}
+function atomicWrite(file, value) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
+    fs.writeFileSync(tmp, typeof value === "string" ? value : `${JSON.stringify(value, null, 2)}\n`);
+    fs.renameSync(tmp, file);
+}
+function ensureWithin(root, candidate, label) {
+    const relative = path.relative(path.resolve(root), path.resolve(candidate));
+    if (relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative)))
+        return;
+    throw new AppError("path_unsafe", `${label} must stay within its root`, 2, { root, candidate });
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\\]\\]/g, "\\$&");
+}