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

package/dist/services/vnext-code.js

@@ -0,0 +1,686 @@
+import crypto from "node:crypto";
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { aggregateCheckDeclarations, checkReceipts, codeExecutionEnvironment, finalCodeCheckDeclarations, runCodeChecks, unchangedFinalGateFailures, workspaceFingerprint } from "./code-checks.js";
+import { requireProjectByRoot } from "./projects.js";
+import { appendFlowRunTimelineEvent, advanceFlowRun, attachFlowRunStage, completeFlowRunStage, completeFlowRun, getFlowRunVariables, gitFacts } from "./runs.js";
+import { validateSchema } from "./schema-validation.js";
+import { flowCommand } from "./stage-pause.js";
+import { validateVnextCodeHandoff } from "./vnext-plan.js";
+import { requireVnextWorkspaceRoute } from "./vnext-workspace-policy.js";
+import { readVnextSpecifyResult } from "./vnext-specify.js";
+import { addWorkBatch, bindStageCoordinatorWork, codeWorkGraph, finishWork, refreshRunWorkProjection, validateWorkBatchFile, workStartCommand } from "./work-registry.js";
+import { vnextStageDirectory } from "../domain/stage-catalog.js";
+import { writeStageReport } from "./stage-report-renderer.js";
+import { assertStageStartHookEvent } from "./hooks.js";
+import { applyExternalStageContext } from "./stage-context.js";
+import { readFanoutDescriptor, writeFanoutDescriptor } from "./vnext-fanout.js";
+const stage = "code";
+const stageDir = vnextStageDirectory("code");
+export async function startVnextCode(context, input) {
+    const projectRoot = resolveProjectRoot(input.projectRoot);
+    const project = requireProjectByRoot(context, projectRoot);
+    const run = requireRun(context, project.id, input.runId);
+    assertStageStartHookEvent(context, { projectId: project.id, eventKey: input.hookEventId, runId: run.id, stage, projectRoot, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
+    const home = requireHome(run);
+    requireVnextWorkspaceRoute({ projectRoot, runId: input.runId, runHome: home, workspaceRoot: run.workspace_root, stage });
+    const existingRoot = path.join(home, stageDir);
+    const existingPrompt = path.join(existingRoot, "stage-prompt.md");
+    const existingStage = stageStatus(run, stage);
+    if (existingStage && fs.existsSync(existingPrompt)) {
+        const externalContext = applyExternalStageContext({ stageRoot: existingRoot, promptPath: existingPrompt, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
+        const prompt = fs.readFileSync(existingPrompt, "utf8");
+        const rootWork = requireRootWork(context, project.id, input.runId);
+        const orchestration = readFanoutDescriptor(existingRoot) ?? writeFanoutDescriptor(existingRoot, { stage, parent_work_id: rootWork.work_id, dispatch: "none", capacity_required: true });
+        return { ok: true, resumed: true, run_id: run.id, stage, stage_status: existingStage, prompt_path: existingPrompt, worker_prompt_markdown: prompt, ...(externalContext ? { external_context: externalContext } : {}), orchestration, graph: codeWorkGraph(context, project.id, run.id), next: { refresh_graph_command: `${flowCommand(context)} work ls --run ${run.id} --ready --project-root ${JSON.stringify(projectRoot)} --json`, finish_command: finishCommand(context, input.runId, projectRoot, path.join(existingRoot, "code-verification.json")) } };
+    }
+    const batch = path.join(home, "03-plan", "code-work-batch.json");
+    const handoffFailures = validateVnextCodeHandoff(context, {
+        projectRoot,
+        workspaceRoot: run.workspace_root,
+        runId: input.runId,
+        home
+    });
+    if (handoffFailures.length) {
+        throw new AppError("validation", "CODE handoff no longer matches the accepted PLAN", 2, { errors: handoffFailures });
+    }
+    validateSchema({
+        schemaName: "code-work-batch",
+        file: batch,
+        projectRoot: run.workspace_root,
+        ddFlowHome: context.ddFlowHome,
+        runId: input.runId
+    });
+    validateWorkBatchFile(batch);
+    const root = path.join(home, stageDir);
+    fs.mkdirSync(root, { recursive: true });
+    const readiness = await ensureCodeWorkspaceReady(context, project.id, run, root, [], input.progress);
+    const rootWork = requireRootWork(context, project.id, input.runId);
+    const promptPath = path.join(root, "stage-prompt.md");
+    const prompt = coordinatorPrompt(context, { projectRoot, run, root, rootWork, readiness });
+    fs.writeFileSync(promptPath, prompt);
+    const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
+    const binding = bindStageCoordinatorWork(context, {
+        workId: rootWork.work_id,
+        hookEventId: input.hookEventId,
+        stage,
+        promptPath,
+        resultPath: path.join(root, "stage-report.json"),
+        ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {})
+    });
+    attachFlowRunStage(context, {
+        projectRoot,
+        runId: input.runId,
+        stage,
+        dir: stageDir,
+        status: "running",
+        dataSchemaId: "dd-flow/stage-report@1"
+    });
+    const graph = codeWorkGraph(context, project.id, input.runId);
+    const orchestration = writeFanoutDescriptor(root, { stage, parent_work_id: rootWork.work_id, dispatch: "none", capacity_required: true });
+    appendFlowRunTimelineEvent(context, project.id, input.runId, { type: "code_started", work_id: rootWork.work_id, graph });
+    return {
+        ok: true,
+        run_id: input.runId,
+        stage,
+        root_work_id: rootWork.work_id,
+        id: binding.work_session_id,
+        prompt_path: promptPath,
+        worker_prompt_markdown: fs.readFileSync(promptPath, "utf8"),
+        ...(externalContext ? { external_context: externalContext } : {}),
+        graph,
+        orchestration,
+        readiness,
+        next: { refresh_graph_command: `${flowCommand(context)} work ls --run ${run.id} --ready --project-root ${JSON.stringify(projectRoot)} --json`, finish_command: finishCommand(context, input.runId, projectRoot, path.join(root, "code-verification.json")) }
+    };
+}
+export async function finishVnextCode(context, input) {
+    const projectRoot = resolveProjectRoot(input.projectRoot);
+    const project = requireProjectByRoot(context, projectRoot);
+    const run = requireRun(context, project.id, input.runId);
+    const home = requireHome(run);
+    const root = path.join(home, stageDir);
+    requireVnextWorkspaceRoute({ projectRoot, runId: run.id, runHome: home, workspaceRoot: run.workspace_root, stage });
+    if (stageStatus(run, stage) === "done" && fs.existsSync(path.join(root, "stage-report.json"))) {
+        return { ok: true, resumed: true, run_id: run.id, stage, outcome: "accepted", report_path: path.join(root, "stage-report.json"), next_action: nextAction(run, changedPathsFromReport(path.join(root, "stage-report.json"))) };
+    }
+    const handoffFailures = validateVnextCodeHandoff(context, {
+        projectRoot,
+        workspaceRoot: run.workspace_root,
+        runId: run.id,
+        home
+    });
+    if (handoffFailures.length) {
+        throw new AppError("validation", "CODE handoff no longer matches the accepted PLAN", 2, { errors: handoffFailures });
+    }
+    const works = codeWorks(context, project.id, run.id);
+    if (!works.length)
+        throw new AppError("runtime_missing", "CODE has no registered implementation Work", 1);
+    const incomplete = works.filter((work) => work.status !== "completed");
+    if (incomplete.length) {
+        throw new AppError("code_graph_incomplete", "CODE cannot finish while implementation or repair Work is unsettled", 2, {
+            works: incomplete.map((work) => ({ work_id: work.work_id, status: work.status }))
+        });
+    }
+    const accepted = readVnextSpecifyResult(path.join(home, "01-specify", "specify.json"));
+    const expected = new Set([...accepted.requirements, ...accepted.acceptance_criteria].map((item) => item.id));
+    const covered = new Set(works.flatMap((work) => packet(work)?.requirements.map((item) => item.id) ?? []));
+    const missing = [...expected].filter((id) => !covered.has(id));
+    if (missing.length) {
+        throw new AppError("obligation_coverage_incomplete", "CODE graph does not cover every accepted obligation", 2, { missing });
+    }
+    // Reject a malformed semantic receipt before running the expensive gate.
+    const verification = verificationForFinish(context, { file: input.verificationFile, projectRoot: run.workspace_root, runId: run.id });
+    if (verification.verdict !== "passed" || verification.unresolved.length > 0) {
+        throw new AppError("code_verification_incomplete", "CODE verification is not accepted; create or complete the necessary repair Work first", 2, { verification });
+    }
+    const checks = finalCodeCheckDeclarations(run.workspace_root, works.flatMap((work) => packet(work)?.checks ?? []));
+    const unchangedFailures = unchangedFinalGateFailures(context, { projectId: project.id, runId: run.id, workspaceRoot: run.workspace_root, declarations: checks });
+    if (unchangedFailures.length)
+        throw new AppError("code_gate_repair_required", "CODE final gate already failed for the unchanged workspace; repair the evidenced failure before retrying", 2, { outcome: "repair_required", retry_after_workspace_change: true, workspace_fingerprint: unchangedFailures[0].workspace_fingerprint, failures: unchangedFailures });
+    let receipts = reusableAggregateGateReceipts(context, { projectId: project.id, runId: run.id, workspaceRoot: run.workspace_root, checks });
+    if (!receipts) {
+        const release = acquireAggregateGateLock(root);
+        try {
+            // A prior caller may have completed the slow gate while this caller was
+            // waiting to acquire the lock. Reuse that immutable evidence.
+            receipts = reusableAggregateGateReceipts(context, { projectId: project.id, runId: run.id, workspaceRoot: run.workspace_root, checks }) ?? await runCodeChecks(context, {
+                projectId: project.id,
+                runId: run.id,
+                runHome: home,
+                workspaceRoot: run.workspace_root,
+                scope: "aggregate",
+                checks,
+                ...(input.progress ? { progress: input.progress } : {})
+            });
+        }
+        finally {
+            release();
+        }
+    }
+    const failed = receipts.filter((receipt) => receipt.status === "failed");
+    if (failed.length) {
+        throw new AppError("code_gate_failed", "CODE remains running because the aggregate project gate failed", 2, {
+            failures: failed,
+            outcome: "repair_required",
+            retry_after_workspace_change: true,
+            workspace_fingerprint: failed[0].workspace_fingerprint,
+            repair_command: `${flowCommand(context)} work repair add --run ${run.id} --from-check ${failed[0].id} --origin-work <WORK-ID> --task-stdin --project-root ${JSON.stringify(projectRoot)} --json`
+        });
+    }
+    const allReceipts = checkReceipts(context, { projectId: project.id, runId: run.id });
+    const finalReceipts = latestReceiptsByCommand(allReceipts);
+    const now = context.now();
+    const timing = stageTiming(home, stage, now);
+    const changedPaths = [...new Set(works.flatMap((work) => resultPaths(work.result)))];
+    const next = nextAction(run, changedPaths);
+    writeProtocolFlowStatus(run.workspace_root, home, run.id, next === "start_code_review" ? "CODE complete; CODE-REVIEW is next." : "CODE complete; this RUN reached its configured terminal boundary.");
+    const report = {
+        schema_id: "dd-flow/stage-report@1",
+        run_id: run.id,
+        stage,
+        generated_at: now,
+        verdict: "done",
+        verification: verificationProjection(works, finalReceipts),
+        semantic: {
+            result: `Completed ${works.length} CODE Work item${works.length === 1 ? "" : "s"}; ${finalReceipts.filter((receipt) => receipt.status === "passed").length} current final check receipt${finalReceipts.length === 1 ? "" : "s"} passed.`,
+            acceptance: [...expected],
+            changed_files: changedPaths,
+            checks: finalReceipts.map((receipt) => receipt.command),
+            evidence: finalReceipts.map((receipt) => receipt.receipt_path),
+            next_action: next,
+            code: {
+                work_ids: works.map((work) => work.work_id),
+                requirement_coverage: [...covered].sort(),
+                repairs: works.filter((work) => packet(work)?.repair).map((work) => ({ work_id: work.work_id, ...packet(work).repair })),
+                verification
+            },
+            plan_conformance: verification
+        },
+        mechanical: {
+            started_at: timing.started_at,
+            finished_at: now,
+            wall_clock_ms: timing.wall_clock_ms,
+            git: gitFacts(run.workspace_root),
+            graph: codeWorkGraph(context, project.id, run.id),
+            session_stats_command: `${flowCommand(context)} stat run sessions ls --run ${run.id} --project-root ${JSON.stringify(projectRoot)} --json`,
+            usage_stats_command: `${flowCommand(context)} stat usage --run ${run.id} --project-root ${JSON.stringify(projectRoot)} --json`
+        },
+        artifacts: { json: "stage-report.json", markdown: "stage-report.md", html: "stage-report.html", summary: "stage-report.md" },
+        validation: { permission_scope: "known_targets_only", memory_bank_scope: "changed_files_and_links_only", status: "passed" }
+    };
+    writeReport(root, report);
+    completeFlowRunStage(context, {
+        projectRoot,
+        runId: run.id,
+        stage,
+        status: "done",
+        data: "stage-report.json",
+        dataSchemaId: "dd-flow/stage-report@1",
+        report: "stage-report.md",
+        stageReport: "stage-report.html"
+    });
+    const rootWork = requireRootWork(context, project.id, run.id);
+    appendFlowRunTimelineEvent(context, project.id, run.id, {
+        type: "code_accepted",
+        work_id: rootWork.work_id,
+        checks: finalReceipts.map((receipt) => receipt.id)
+    });
+    if (next === "code_completed") {
+        await finishWork(context, rootWork.work_id, JSON.stringify(report, null, 2));
+        completeFlowRun(context, { projectRoot, runId: run.id, status: "done", verdict: "code_completed", nextAction: undefined });
+    }
+    else {
+        advanceFlowRun(context, { projectRoot, runId: run.id, status: "running", verdict: "code_completed", nextAction: "start_code_review" });
+    }
+    return {
+        ok: true,
+        run_id: run.id,
+        stage,
+        outcome: "accepted",
+        report_path: path.join(root, "stage-report.json"),
+        next_action: next,
+        ...(next === "start_code_review" ? { next: { kind: "start_stage", stage: "code-review", command: `${flowCommand(context)} stage start ${run.id} --stage code-review --project-root ${JSON.stringify(projectRoot)} --json` } } : {})
+    };
+}
+export function addVnextCodeRepair(context, input) {
+    const projectRoot = resolveProjectRoot(input.projectRoot);
+    const project = requireProjectByRoot(context, projectRoot);
+    const run = requireRun(context, project.id, input.runId);
+    const home = requireHome(run);
+    if (!input.objective.trim())
+        throw new AppError("validation", "Repair objective must not be empty", 2);
+    if (!input.checkReceiptId && !input.reviewFindingIds?.length) {
+        throw new AppError("validation", "Repair needs a failed check receipt or CODE-REVIEW finding", 2);
+    }
+    const receipt = input.checkReceiptId ? context.db.get("SELECT id, declaration_id, run_id, command, status, receipt_path, stdout_path, stderr_path FROM check_receipts WHERE project_id = ? AND id = ?", [
+        project.id,
+        input.checkReceiptId
+    ]) : undefined;
+    if (input.checkReceiptId && (!receipt || receipt.run_id !== run.id || receipt.status !== "failed")) {
+        throw new AppError("validation", "Repair requires a failed check receipt from the same RUN", 2, {
+            check_receipt_id: input.checkReceiptId
+        });
+    }
+    const origins = [...new Set(input.originWorkIds)].map((id) => requireCodeWork(context, project.id, run.id, id));
+    const packets = origins.map((work) => packet(work));
+    const invariantPackets = receipt
+        ? codeWorks(context, project.id, run.id).map((work) => packet(work)).filter((value) => !value.repair)
+        : packets;
+    const first = packets[0];
+    const declaredChecks = finalCodeCheckDeclarations(run.workspace_root, packets.flatMap((value) => value.checks));
+    const failedCheck = receipt ? declaredChecks.find((check) => check.id === receipt.declaration_id) : undefined;
+    if (receipt && !failedCheck) {
+        throw new AppError("repair_check_declaration_missing", "Repair receipt is not backed by an accepted CODE check declaration", 2, {
+            check_receipt_id: receipt.id,
+            declaration_id: receipt.declaration_id
+        });
+    }
+    const key = input.reviewFindingIds?.length ? "code-review-repair" : "code-gate-repair";
+    const receiptWriteScope = receipt ? receiptRepairPaths(run.workspace_root, receipt) : [];
+    const repair = {
+        schema_id: "dd-flow/code-work-packet@5",
+        key,
+        launch_policy: "fresh_agent_required",
+        source: first.source,
+        repair: {
+            origin_work_ids: origins.map((work) => work.work_id),
+            ...(receipt ? { check_receipt_id: receipt.id, failure_receipt_path: receipt.receipt_path } : {}),
+            ...(input.reviewFindingIds?.length ? { review_finding_ids: unique(input.reviewFindingIds), review_evidence_refs: unique(input.reviewEvidenceRefs ?? []) } : {})
+        },
+        task: input.objective,
+        semantic_spine: {
+            user_outcome: receipt ? `Restore the accepted behavior after aggregate failure: ${input.objective}` : `Resolve accepted CODE-REVIEW finding: ${input.objective}`,
+            component_responsibility: "Diagnose and repair the failed accepted CODE result without changing unrelated behavior.",
+            must_preserve: unique(invariantPackets.flatMap((value) => value.semantic_spine.must_preserve)),
+            non_goals: unique(invariantPackets.flatMap((value) => value.semantic_spine.non_goals)),
+            acceptance_contribution: receipt ? `Make failed check pass: ${receipt.command}` : `Resolve CODE-REVIEW finding(s): ${input.reviewFindingIds.join(", ")}`
+        },
+        requirements: uniqueBy(invariantPackets.flatMap((value) => value.requirements), (value) => value.id),
+        acceptance: uniqueBy(invariantPackets.flatMap((value) => value.acceptance), (value) => JSON.stringify(value)),
+        document_updates: receipt ? [] : uniqueBy(packets.flatMap((value) => value.document_updates).filter((update) => (input.reviewEvidenceRefs ?? []).some((reference) => reference === update.path || reference.startsWith(`${update.path}:`) || reference.endsWith(`/${update.path}`))), (value) => JSON.stringify(value)),
+        required_read: unique([...(receipt ? [receipt.receipt_path] : input.reviewEvidenceRefs ?? []), ...packets.flatMap((value) => value.required_read)]),
+        discovery_boundary: unique(packets.flatMap((value) => value.discovery_boundary)),
+        // These are collision-avoidance hints. Receipt paths enrich the coordinator
+        // picture but never restrict the repair's project-local edits.
+        planned_write_areas: unique([...packets.flatMap((value) => value.planned_write_areas), ...receiptWriteScope]),
+        // Receipts record the resolved shell command. A repair must retain the
+        // accepted declaration (including its immutable @check alias) and only
+        // change when it runs, so work finish can validate it again.
+        checks: uniqueBy([...(failedCheck ? [{ ...failedCheck, purpose: "Re-run the failed accepted check.", run_at: "work" }] : []), ...packets.flatMap((value) => value.checks)], (check) => check.id),
+        provides_checks: [],
+        stop_conditions: unique([
+            ...invariantPackets.flatMap((value) => value.stop_conditions),
+            ...(receipt ? ["Stop and report the blocker if the proposed repair contradicts an accepted requirement or non-goal."] : [])
+        ]),
+        depends_on: origins.map((work) => work.work_id),
+        result_schema: "dd-flow/code-work-result@2"
+    };
+    const file = path.join(home, stageDir, `.repair-${crypto.randomUUID()}.json`);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify({ works: [repair] }, null, 2)}\n`);
+    let registered;
+    try {
+        registered = addWorkBatch(context, { parentWorkId: requireRootWork(context, project.id, run.id).work_id, file });
+    }
+    finally {
+        fs.rmSync(file, { force: true });
+    }
+    const id = String(registered.work_ids[key]);
+    const work = context.db.get("SELECT * FROM works WHERE work_id = ?", [id]);
+    appendFlowRunTimelineEvent(context, project.id, run.id, {
+        type: "code_repair_created",
+        work_id: id,
+        origin_work_ids: input.originWorkIds,
+        ...(receipt ? { check_receipt_id: receipt.id } : { review_finding_ids: input.reviewFindingIds })
+    });
+    refreshRunWorkProjection(context, project.id, run.id);
+    return { ok: true, run_id: run.id, repair_work_id: id, start_command: workStartCommand(context, work) };
+}
+function receiptRepairPaths(workspaceRoot, receipt) {
+    const root = path.resolve(workspaceRoot);
+    const text = [receipt.stdout_path, receipt.stderr_path]
+        .filter((file) => fs.existsSync(file))
+        .map((file) => fs.readFileSync(file, "utf8"))
+        .join("\n");
+    const paths = new Set();
+    for (const raw of text.split(/\s+/)) {
+        const token = raw
+            .replace(/^[^A-Za-z0-9_@./\\-]+|[^A-Za-z0-9_@./\\-]+$/g, "")
+            .replace(/:\d+(?::\d+)?$/, "");
+        if (!token || token.split(/[\\/]/).includes(".."))
+            continue;
+        const absolute = path.isAbsolute(token) ? path.resolve(token) : path.resolve(root, token);
+        const relative = path.relative(root, absolute).split(path.sep).join("/");
+        if (!relative || relative.startsWith("../") || path.isAbsolute(relative))
+            continue;
+        if (relative.split("/").some((part) => part === ".git" || part === "node_modules"))
+            continue;
+        if (fs.existsSync(absolute) && fs.statSync(absolute).isFile())
+            paths.add(relative);
+    }
+    return [...paths].sort();
+}
+function coordinatorPrompt(context, input) {
+    const graph = codeWorkGraph(context, input.run.project_id, input.run.id);
+    const variables = getFlowRunVariables(context, { projectRoot: input.projectRoot, runId: input.run.id });
+    const capacity = variables.variables?.["runtime.subagent.available_slots"];
+    const template = fs.readFileSync(path.join(input.run.workspace_root, ".memory-bank", "dd-flow", "vnext", "code.md"), "utf8");
+    return [
+        "<stage_identity>",
+        `- RUN: ${input.run.id}`,
+        `- root Work: ${input.rootWork.work_id}`,
+        "- stage: code",
+        "</stage_identity>",
+        "",
+        "<trusted_runtime_context>",
+        `- project root: ${input.projectRoot}`,
+        `- immutable write workspace: ${input.run.workspace_root}`,
+        `- stage workspace: ${input.root}`,
+        `- workspace readiness receipt: ${String(input.readiness.receipt_path)}`,
+        `- available subagent slots: ${typeof capacity === "number" ? capacity : "not measured; delegate conservatively"}`,
+        "The CLI validated the accepted PLAN projection, workspace route and registered Work graph. Do not repeat that discovery.",
+        "</trusted_runtime_context>",
+        "",
+        "<code_graph>",
+        JSON.stringify(graph, null, 2),
+        "</code_graph>",
+        "",
+        "<execution_commands>",
+        "Launch only entries listed in graph.ready. Use at most the known available slot count. Every registered CODE Work runs in a fresh child Session, including a serial dependency chain; the coordinator owns dispatch and the stage conclusion, not implementation Work. Every child starts with its exact start_command and receives its complete packet from dd-flow. After a Work finishes, use the graph returned by work finish to launch newly ready Work. To refresh the parent graph yourself use the exact command: " + `${flowCommand(context)} work ls --run ${input.run.id} --ready --project-root ${JSON.stringify(input.projectRoot)} --json`,
+        "A quiet child is still running until the harness reports its turn completed, failed, cancelled or explicitly needs attention. An elapsed nominal wait, silence, or no new artifact is not an unresponsive-worker failure. Never interrupt, replace, relaunch, or stage-block a still-running child for that reason, even if an external controller asks. Long work finish and stage finish commands emit check progress on stderr. After you issue the exact CODE stage finish command, wait for that same command to return: do not inspect its PID, start a second finish command, or infer failure from quiet output. Close a disposable child only after its Work is accepted or explicitly failed/cancelled and the harness reports the turn settled.",
+        `A repairable engine, harness, or environment failure is not a user question. Record it without finishing CODE: ${flowCommand(context)} stage block ${input.run.id} --stage code --work ${input.rootWork.work_id} --kind <engine|harness|environment> --code <stable-code> --summary-stdin --retryable --project-root ${JSON.stringify(input.projectRoot)} --json. Repair it externally, then run the exact unblock_command returned by dd-flow and continue this same stage.`,
+        `When every CODE and repair Work is completed, write ${path.join(input.root, "code-verification.json")} using the exact contract below. Mark passed only when all accepted requirements and current-gate acceptance criteria are implemented or explicitly evidenced; list every remaining issue in unresolved. Every evidence_refs item must already exist as a relative workspace path or run://${input.run.id}/ path. Do not claim a browser or other check receipt that was not retained. Then finish: ${finishCommand(context, input.run.id, input.projectRoot, path.join(input.root, "code-verification.json"))}`,
+        "If the aggregate gate fails, use the returned repair command with the relevant completed origin Work IDs and a concise repair objective. Do not edit invisibly in the root orchestrator.",
+        "</execution_commands>",
+        "",
+        "<verification_contract>",
+        "```json",
+        JSON.stringify({ schema_id: "dd-flow/code-verification@2", verdict: "passed | needs_repair | blocked", summary: "Evidence-backed conclusion.", unresolved: [], deviations: [] }, null, 2),
+        "```",
+        "The CLI verifies graph coverage and executes all deterministic checks. Do not duplicate its report; record only your semantic conclusion and evidence.",
+        "</verification_contract>",
+        "",
+        "<stage_instructions>",
+        template,
+        "</stage_instructions>",
+        ""
+    ].join("\n");
+}
+export function profileCommands(workspaceRoot) {
+    return aggregateCheckDeclarations(workspaceRoot).map((check) => check.command);
+}
+function latestReceiptsByCommand(receipts) {
+    const latest = new Map();
+    for (const receipt of receipts)
+        latest.set(receipt.declaration_id, receipt);
+    return [...latest.values()];
+}
+/**
+ * A CODE finish may be retried after a client loses the long command's output.
+ * Reusing complete, same-workspace receipts is correct; rerunning them is both
+ * expensive and can race the still-settling original invocation.
+ */
+export function reusableAggregateGateReceipts(context, input) {
+    const expected = new Set(input.checks.map((check) => check.id));
+    const current = workspaceFingerprint(input.workspaceRoot);
+    const latest = new Map();
+    for (const receipt of checkReceipts(context, { projectId: input.projectId, runId: input.runId })) {
+        if (receipt.scope === "aggregate" && expected.has(receipt.declaration_id))
+            latest.set(receipt.declaration_id, receipt);
+    }
+    if (latest.size !== expected.size)
+        return null;
+    const receipts = input.checks.map((check) => latest.get(check.id));
+    return receipts.every((receipt) => receipt.status === "passed" && receipt.workspace_fingerprint === current) ? receipts : null;
+}
+/** One aggregate gate per RUN; a second invocation must wait, never duplicate it. */
+function acquireAggregateGateLock(root) {
+    const directory = path.join(root, "checks");
+    const lock = path.join(directory, ".aggregate-gate.lock");
+    fs.mkdirSync(directory, { recursive: true });
+    try {
+        const descriptor = fs.openSync(lock, "wx");
+        fs.writeFileSync(descriptor, JSON.stringify({ pid: process.pid, started_at: new Date().toISOString() }));
+        fs.closeSync(descriptor);
+    }
+    catch (error) {
+        if (!isExistingLock(error))
+            throw error;
+        const activePid = lockPid(lock);
+        if (activePid && processAlive(activePid)) {
+            throw new AppError("code_gate_in_progress", "CODE aggregate gate is already running; wait for that exact stage finish command to return", 1, { pid: activePid, lock });
+        }
+        fs.rmSync(lock, { force: true });
+        return acquireAggregateGateLock(root);
+    }
+    return () => fs.rmSync(lock, { force: true });
+}
+function isExistingLock(error) {
+    return Boolean(error && typeof error === "object" && error.code === "EEXIST");
+}
+function lockPid(lock) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(lock, "utf8"));
+        return Number.isInteger(parsed.pid) && Number(parsed.pid) > 0 ? Number(parsed.pid) : null;
+    }
+    catch {
+        return null;
+    }
+}
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function verificationProjection(works, receipts) {
+    const packets = works.map((work) => packet(work)).filter((value) => value !== null);
+    const declarations = uniqueBy(packets.flatMap((value) => value.checks), (value) => value.id);
+    const receiptByDeclaration = new Map(receipts.map((receipt) => [receipt.declaration_id, receipt]));
+    const evidence = new Map();
+    for (const work of works) {
+        const result = readJsonResult(work.result);
+        for (const item of result.evidence ?? [])
+            if (item.criterion_id)
+                evidence.set(item.criterion_id, unique([...(evidence.get(item.criterion_id) ?? []), ...(item.refs ?? [])]));
+    }
+    const acceptance = uniqueBy(packets.flatMap((value) => value.acceptance), (value) => value.criterion_id);
+    return {
+        checks: declarations.map((check) => { const receipt = receiptByDeclaration.get(check.id); return { id: check.id, run_at: check.run_at, status: receipt?.status ?? (["work", "code", "readiness"].includes(check.run_at) ? "failed" : "not_due"), receipt_ref: receipt?.receipt_path ?? null }; }),
+        acceptance: acceptance.map((item) => ({ criterion_id: item.criterion_id, gate: item.gate, status: ["work", "code", "readiness"].includes(item.gate) ? ((item.check_refs.every((id) => receiptByDeclaration.get(id)?.status === "passed") && (evidence.get(item.criterion_id)?.length ?? 0) > 0) ? "confirmed" : "unresolved") : "not_due", check_refs: item.check_refs, evidence_refs: evidence.get(item.criterion_id) ?? [] }))
+    };
+}
+function readJsonResult(value) { try {
+    const parsed = JSON.parse(value ?? "{}");
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+}
+catch {
+    return {};
+} }
+function stageTiming(home, name, finishedAt) {
+    const run = JSON.parse(fs.readFileSync(path.join(home, "run.json"), "utf8"));
+    const startedAt = run.stage_runs?.find((item) => item.stage === name)?.started_at;
+    const started = Date.parse(startedAt ?? "");
+    const finished = Date.parse(finishedAt);
+    if (!startedAt || !Number.isFinite(started) || !Number.isFinite(finished)) {
+        throw new AppError("stage_timing_unavailable", "CODE lifecycle timestamps are unavailable or invalid", 1, { stage: name, started_at: startedAt ?? null, finished_at: finishedAt });
+    }
+    return { started_at: startedAt, wall_clock_ms: Math.max(0, finished - started) };
+}
+function codeWorks(context, projectId, runId) {
+    return context.db
+        .all("SELECT * FROM works WHERE project_id = ? AND run_id = ? ORDER BY created_at, work_id", [projectId, runId])
+        .filter((work) => Boolean(packet(work)));
+}
+function packet(work) {
+    if (!work.payload_json)
+        return null;
+    try {
+        const value = JSON.parse(work.payload_json);
+        return value.schema_id === "dd-flow/code-work-packet@5" ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+function requireCodeWork(context, projectId, runId, workId) {
+    const work = context.db.get("SELECT * FROM works WHERE project_id = ? AND run_id = ? AND work_id = ?", [
+        projectId,
+        runId,
+        workId
+    ]);
+    if (!work || work.status !== "completed" || !packet(work)) {
+        throw new AppError("validation", "Repair origin must be a completed CODE Work in the same RUN", 2, { work_id: workId });
+    }
+    return work;
+}
+function requireRootWork(context, projectId, runId) {
+    const work = context.db.get("SELECT * FROM works WHERE project_id = ? AND run_id = ? AND parent_work_id IS NULL ORDER BY created_at LIMIT 1", [projectId, runId]);
+    if (!work || work.status !== "running")
+        throw new AppError("runtime_missing", "vNext RUN has no running root Work", 1);
+    return work;
+}
+function requireRun(context, projectId, runId) {
+    const run = context.db.get("SELECT id, project_id, run_home_path, workspace_root, index_json FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
+    if (!run)
+        throw new AppError("not_found", "RUN is not registered", 1);
+    return run;
+}
+/** CODE, not PROTOCOLIZE, makes a checkout ready for project tooling. */
+async function ensureCodeWorkspaceReady(context, projectId, run, root, readinessChecks, progress) {
+    const profile = JSON.parse(run.index_json);
+    const bootstrap = profile.execution_profile?.settings?.code_bootstrap;
+    if (!bootstrap || typeof bootstrap.command !== "string" || typeof bootstrap.policy_ref !== "string") {
+        throw new AppError("execution_profile_invalid", "CODE requires a frozen bootstrap command in the RUN execution profile", 1, { run_id: run.id });
+    }
+    const receiptPath = path.join(root, "workspace-readiness.json");
+    const prior = readReadiness(receiptPath);
+    if (prior?.workspace_root === run.workspace_root && prior.command === bootstrap.command && prior.status === "passed" && JSON.stringify(prior.check_declarations ?? []) === JSON.stringify(readinessChecks))
+        return { ...prior, reused: true };
+    const startedAt = new Date().toISOString();
+    progress?.(`workspace bootstrap started: ${bootstrap.command}`);
+    const result = await runBootstrap(bootstrap.command, run.workspace_root, codeExecutionEnvironment(run.workspace_root), progress);
+    const bootstrapPassed = result.exit_code === 0 && !result.error;
+    const checks = bootstrapPassed && readinessChecks.length
+        ? await runCodeChecks(context, { projectId, runId: run.id, runHome: requireHome(run), workspaceRoot: run.workspace_root, scope: "aggregate", artifactDir: "05-code/readiness", checks: readinessChecks, ...(progress ? { progress } : {}) })
+        : [];
+    const receipt = { schema_id: "dd-flow/workspace-readiness@2", workspace_root: run.workspace_root, command: bootstrap.command, policy_ref: bootstrap.policy_ref, started_at: startedAt, finished_at: new Date().toISOString(), status: bootstrapPassed && checks.every((check) => check.status === "passed") ? "passed" : "failed", exit_code: result.exit_code, stdout: result.stdout, stderr: result.stderr, check_declarations: readinessChecks, checks: checks.map((check) => ({ id: check.id, status: check.status, receipt_path: check.receipt_path })), ...(result.error ? { error: result.error } : {}), receipt_path: receiptPath };
+    fs.writeFileSync(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`);
+    if (receipt.status !== "passed")
+        throw new AppError("workspace_readiness_failed", "CODE workspace bootstrap failed", 1, receipt);
+    progress?.("workspace bootstrap passed");
+    return receipt;
+}
+function runBootstrap(command, cwd, environment, progress) {
+    return new Promise((resolve) => {
+        const started = Date.now();
+        const child = spawn("/bin/sh", ["-lc", command], { cwd, env: environment, stdio: ["ignore", "pipe", "pipe"] });
+        let stdout = "";
+        let stderr = "";
+        let error = null;
+        child.stdout.setEncoding("utf8").on("data", (chunk) => { stdout += chunk; });
+        child.stderr.setEncoding("utf8").on("data", (chunk) => { stderr += chunk; });
+        const heartbeat = setInterval(() => progress?.(`workspace bootstrap still running (${Math.floor((Date.now() - started) / 1000)}s)`), 15_000);
+        const timeout = setTimeout(() => child.kill("SIGTERM"), 15 * 60 * 1000);
+        child.once("error", (value) => { error = value.message; });
+        child.once("close", (exitCode, signal) => {
+            clearInterval(heartbeat);
+            clearTimeout(timeout);
+            resolve({ exit_code: exitCode, stdout, stderr, error: error ?? (signal ? `terminated by ${signal}` : null) });
+        });
+    });
+}
+function readReadiness(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function requireHome(run) {
+    if (!run.run_home_path)
+        throw new AppError("runtime_missing", "RUN workspace is unavailable", 1);
+    return run.run_home_path;
+}
+function finishCommand(context, runId, projectRoot, verificationFile) {
+    return `${flowCommand(context)} stage finish ${runId} --stage code --verification-file ${JSON.stringify(verificationFile)} --project-root ${JSON.stringify(projectRoot)} --json --progress-jsonl`;
+}
+function readVerification(context, input) {
+    const file = path.resolve(input.file);
+    validateSchema({ schemaName: "code-verification", file, projectRoot: input.projectRoot, ddFlowHome: context.ddFlowHome, runId: input.runId });
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+function verificationForFinish(context, input) {
+    return readVerification(context, input);
+}
+/** Keep protocol summaries truthful after deterministic lifecycle transitions. */
+export function writeProtocolFlowStatus(workspaceRoot, runHome, runId, status) {
+    const reportPath = path.join(runHome, "02-protocolize", "stage-report.json");
+    if (!fs.existsSync(reportPath))
+        return;
+    const report = JSON.parse(fs.readFileSync(reportPath, "utf8"));
+    const protocolIds = Array.isArray(report.semantic?.acceptance) ? report.semantic.acceptance.filter((value) => typeof value === "string") : [];
+    for (const protocolId of protocolIds) {
+        const file = path.join(workspaceRoot, ".memory-bank", "protocol", protocolId, "summary.md");
+        if (!fs.existsSync(file))
+            continue;
+        const previous = fs.readFileSync(file, "utf8").replace(/\n## Latest RUN state\n[\s\S]*$/u, "\n");
+        fs.writeFileSync(file, `${previous.trimEnd()}\n\n## Latest RUN state\n\n- Source RUN: ${runId}\n- ${status}\n`);
+    }
+}
+function nextAction(run, changedPaths) {
+    const index = JSON.parse(run.index_json);
+    const requested = index.settings?.code_review?.mode ?? "auto";
+    const enabled = requested === "off" ? false : requested === "auto" ? changedPaths.length > 0 : true;
+    return enabled && index.execution_profile?.settings?.stop_target === "code_review_completed" ? "start_code_review" : "code_completed";
+}
+function stageStatus(run, name) {
+    try {
+        return JSON.parse(run.index_json).stage_runs?.find((item) => item.stage === name)?.status ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function changedPathsFromReport(file) {
+    try {
+        const value = JSON.parse(fs.readFileSync(file, "utf8"));
+        return Array.isArray(value.semantic?.changed_files) ? value.semantic.changed_files.filter((item) => typeof item === "string") : [];
+    }
+    catch {
+        return [];
+    }
+}
+function resultPaths(result) {
+    try {
+        const value = JSON.parse(result ?? "");
+        return Array.isArray(value.changed_paths) ? value.changed_paths.filter((item) => typeof item === "string") : [];
+    }
+    catch {
+        return [];
+    }
+}
+function unique(values) {
+    return [...new Set(values)];
+}
+function uniqueBy(values, key) {
+    const seen = new Set();
+    return values.filter((value) => {
+        const id = key(value);
+        if (seen.has(id))
+            return false;
+        seen.add(id);
+        return true;
+    });
+}
+function writeReport(root, report) {
+    writeStageReport(root, report);
+}