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

package/dist/services/vnext-plan-review.js

@@ -0,0 +1,499 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { requireProjectByRoot } from "./projects.js";
+import { advanceFlowRun, appendFlowRunTimelineEvent, attachFlowRunStage, completeFlowRun, completeFlowRunStage, getFlowRunVariables, gitFacts, setRuntimeRunVariable } from "./runs.js";
+import { addWorkBatch, bindStageCoordinatorWork, ensureWorkRegistry, refreshRunWorkProjection, workStartCommand } from "./work-registry.js";
+import { validateSchema } from "./schema-validation.js";
+import { flowCommand, stagePauseCommand, stagePauseCommandTemplate } from "./stage-pause.js";
+import { assertStageStartHookEvent } from "./hooks.js";
+import { validateVnextPlanArtifacts } from "./vnext-plan.js";
+import { requireVnextWorkspaceRoute } from "./vnext-workspace-policy.js";
+import { nextWorkId } from "./ids.js";
+import { vnextStageDirectory } from "../domain/stage-catalog.js";
+import { writeStageReport } from "./stage-report-renderer.js";
+import { applyExternalStageContext } from "./stage-context.js";
+import { capacityProbe, readFanoutDescriptor, subagentCapacityKey, writeFanoutDescriptor } from "./vnext-fanout.js";
+const stage = "plan-review";
+const stageDir = vnextStageDirectory(stage);
+const reviewTask = "Independently review the accepted PLAN and decide whether CODE may open.";
+const capacityProbeFanoutSize = capacityProbe.fanout_size;
+const capacityProbeHoldSeconds = capacityProbe.probe_hold_seconds;
+const capacityProbeDeadlineSeconds = capacityProbe.cleanup_deadline_seconds;
+export function isVnextPlanReviewRun(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    return Boolean(context.db.get("SELECT id FROM runs WHERE project_id = ? AND id = ? AND flow_kind = 'vnext_protocolize'", [project.id, input.runId]));
+}
+export function startVnextPlanReview(context, input) {
+    ensureWorkRegistry(context);
+    const projectRoot = resolveProjectRoot(input.projectRoot);
+    const project = requireProjectByRoot(context, projectRoot);
+    const run = requireRun(context, projectRoot, input.runId);
+    const home = requireHome(run);
+    assertStageStartHookEvent(context, { projectId: project.id, eventKey: input.hookEventId, runId: run.id, stage, projectRoot, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
+    const workspaceRoute = requireVnextWorkspaceRoute({ projectRoot, runId: run.id, runHome: home, workspaceRoot: run.workspace_root, stage: "plan-review" });
+    const planRoot = path.join(home, "03-plan");
+    const root = path.join(home, stageDir);
+    const batch = path.join(planRoot, "code-work-batch.json");
+    if (!fs.existsSync(path.join(planRoot, "stage-report.json")) || !fs.existsSync(batch))
+        throw new AppError("not_found", "PLAN-REVIEW requires the accepted PLAN report and proposed CODE batch", 1);
+    const requested = requestedMode(run);
+    const protocolIds = protocolIdsForReview(home);
+    assertReviewWorkspace(run.workspace_root, protocolIds);
+    const groups = reviewGroups(home, run.workspace_root);
+    const effective = resolveMode(requested, groups, home, run.workspace_root);
+    const existing = context.db.get("SELECT work_id, status FROM works WHERE project_id = ? AND run_id = ? AND task = ? ORDER BY created_at DESC LIMIT 1", [project.id, run.id, reviewTask]);
+    if (existing?.status === "running") {
+        const promptPath = path.join(root, "stage-prompt.md");
+        const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
+        return { ...preparedExisting(context, { projectRoot, projectId: project.id, run, root, workId: existing.work_id, hookEventId: input.hookEventId, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}), requested, effective, groups, batchChecksum: checksum(batch), planChecksum: checksum(path.join(planRoot, "stage-report.json")) }), ...(externalContext ? { external_context: externalContext } : {}) };
+    }
+    const priorStage = readIndex(run).stage_runs?.find((entry) => entry.stage === stage);
+    if (priorStage?.status === "done") {
+        const report = readJson(path.join(root, "stage-report.json"));
+        const outcome = report.semantic?.plan_review?.outcome;
+        if (outcome === "off" || outcome === "accepted")
+            return { ok: true, run_id: run.id, stage, outcome: outcome === "off" ? "review_off" : "accepted", ...(report.semantic?.code ? { code: report.semantic.code } : {}), next: { kind: "start_stage", stage: "code", command: codeCommand(context, run.id, projectRoot) }, idempotent: true };
+        throw new AppError("invalid_work_state", "PLAN-REVIEW is already terminal; corrections are applied in the same review Work and are not re-reviewed automatically", 2, { run_id: run.id, outcome });
+    }
+    fs.mkdirSync(root, { recursive: true });
+    const now = context.now();
+    const batchChecksum = checksum(batch);
+    const planChecksum = checksum(path.join(planRoot, "stage-report.json"));
+    if (effective === "off") {
+        const failures = validateVnextPlanArtifacts(context, { projectRoot, workspaceRoot: run.workspace_root, runId: run.id, home, protocols: protocolIds });
+        if (failures.length)
+            throw new AppError("validation", "PLAN artifacts have validation errors", 2, { errors: failures });
+        const rootWork = rootWorkId(context, project.id, run.id);
+        const promptPath = path.join(root, "stage-prompt.md");
+        fs.writeFileSync(promptPath, "PLAN-REVIEW is disabled by the frozen RUN configuration.\n");
+        const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
+        bindStageCoordinatorWork(context, { workId: rootWork, hookEventId: input.hookEventId, stage, promptPath, resultPath: path.join(root, "stage-report.json"), ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
+        attachFlowRunStage(context, { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/plan-review-decision@3" });
+        const registered = registerCode(context, project.id, run.id, batch);
+        const report = reportFor({ run, mode: effective, requested, outcome: "off", groups: [], batchChecksum, planChecksum, code: registered, now, projectRoot, flow: flowCommand(context) });
+        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" });
+        advanceFlowRun(context, { projectRoot, runId: run.id, status: "running", verdict: "plan_review_off", nextAction: "start_code" });
+        appendFlowRunTimelineEvent(context, project.id, run.id, { type: "plan_review_opened", mode: effective, outcome: "off" });
+        return { ok: true, run_id: run.id, stage, outcome: "review_off", ...(externalContext ? { external_context: externalContext } : {}), plan_review: { requested_mode: requested, effective_mode: effective, policy_source: policySource(run), reason: "No applicable independent review group." }, next: { kind: "start_stage", stage: "code", command: codeCommand(context, run.id, projectRoot) } };
+    }
+    const rootWork = rootWorkId(context, project.id, run.id);
+    const workId = nextWorkId(context, project.id, "plan-review");
+    context.db.run("INSERT INTO works (work_id, project_id, run_id, parent_work_id, task, launch_policy, result_schema, depends_on_json, status, result, started_at, created_at, updated_at, completed_at) VALUES (?, ?, ?, ?, ?, 'reuse_allowed', NULL, '[]', 'running', NULL, ?, ?, ?, NULL)", [workId, project.id, run.id, rootWork, reviewTask, now, now, now]);
+    const pauseCommand = stagePauseCommand(context, { runId: run.id, stage, workId, projectRoot });
+    const prompt = orchestratorPrompt(context, { projectRoot, run, home, root, workId, requested, effective, groups, batchChecksum, planChecksum, workspaceRoute, pauseCommand, pauseCommandTemplate: stagePauseCommandTemplate(pauseCommand) });
+    const promptPath = path.join(root, "stage-prompt.md");
+    fs.writeFileSync(promptPath, prompt);
+    const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
+    let binding;
+    try {
+        binding = bindStageCoordinatorWork(context, { workId, hookEventId: input.hookEventId, stage, promptPath, resultPath: path.join(root, "stage-report.json"), ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
+    }
+    catch (error) {
+        context.db.run("DELETE FROM works WHERE work_id = ? AND status = 'running'", [workId]);
+        fs.rmSync(promptPath, { force: true });
+        throw error;
+    }
+    attachFlowRunStage(context, { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/plan-review-decision@3" });
+    markReviewPending(home, groups);
+    const workSessionId = String(binding.work_session_id);
+    const sessionId = String(binding.session_id);
+    const orchestration = writeFanoutDescriptor(root, { stage, parent_work_id: workId, dispatch: "plan-review", capacity_required: true });
+    writeJson(path.join(root, "work-context.json"), { schema_id: "dd-flow/plan-review-context@1", system: { run_id: run.id, work_id: workId, stage, requested_mode: requested, effective_mode: effective, plan_revision: currentPlanRevision(home, run.workspace_root), plan_checksum: planChecksum, batch_checksum: batchChecksum }, groups, workspace: { project_root: projectRoot, workspace_root: run.workspace_root, stage_root: root, plan_root: planRoot } });
+    refreshRunWorkProjection(context, project.id, run.id);
+    appendFlowRunTimelineEvent(context, project.id, run.id, { type: "work_session_started", stage, work_id: workId, id: workSessionId, session_id: sessionId });
+    return { ok: true, run_id: run.id, stage, outcome: "review_required", work_id: workId, id: workSessionId, prompt_path: promptPath, worker_prompt_markdown: fs.readFileSync(promptPath, "utf8"), ...(externalContext ? { external_context: externalContext } : {}), orchestration, plan_review: { requested_mode: requested, effective_mode: effective, policy_source: policySource(run), groups }, next: { dispatch_command: dispatchCommand(context, run.id, projectRoot), finish_command: finishCommand(context, run.id, projectRoot, path.join(root, "decision.json")) } };
+}
+export function dispatchVnextPlanReview(context, input) {
+    ensureWorkRegistry(context);
+    const projectRoot = resolveProjectRoot(input.projectRoot);
+    const project = requireProjectByRoot(context, projectRoot);
+    const run = requireRun(context, projectRoot, input.runId);
+    const home = requireHome(run);
+    const root = path.join(home, stageDir);
+    const contextFile = readJson(path.join(root, "work-context.json"));
+    const groups = contextFile.groups ?? [];
+    if (!groups.length || contextFile.system?.effective_mode === "off")
+        throw new AppError("invalid_work_state", "PLAN-REVIEW dispatch requires an enabled review stage", 2);
+    const parent = context.db.get("SELECT work_id, status FROM works WHERE project_id = ? AND run_id = ? AND task = ? ORDER BY created_at DESC LIMIT 1", [project.id, run.id, reviewTask]);
+    if (!parent || parent.status !== "running")
+        throw new AppError("invalid_work_state", "PLAN-REVIEW has no running parent Work", 2);
+    const capacity = ensureReviewCapacity(context, { projectRoot, runId: run.id });
+    if (capacity.pending)
+        return capacity.response;
+    if (capacity.availableSlots < 1)
+        throw new AppError("no_subagent_capacity", "PLAN-REVIEW requires one fresh reviewer Session but no probe launch succeeded", 1, { run_id: run.id });
+    const existing = context.db.all("SELECT work_id, task, status, result, created_at, launch_policy FROM works WHERE project_id = ? AND run_id = ? AND parent_work_id = ?", [project.id, run.id, parent.work_id]);
+    const latest = (group) => existing.find((item) => item.task === group.task);
+    const pending = groups.filter((group) => !latest(group));
+    if (pending.length) {
+        const file = path.join(root, ".dispatch.json");
+        writeJson(file, { works: pending.map((group) => ({ key: group.key, task: group.task, depends_on: group.depends_on, launch_policy: "fresh_agent_required", result_schema: "dd-flow/plan-review-result@1", payload: { kind: "plan-review", group: { key: group.key, aspect_ids: group.aspect_ids } } })) });
+        try {
+            addWorkBatch(context, { parentWorkId: parent.work_id, file });
+        }
+        finally {
+            fs.rmSync(file, { force: true });
+        }
+    }
+    const created = context.db.all("SELECT work_id, task, status, launch_policy, created_at FROM works WHERE project_id = ? AND run_id = ? AND parent_work_id = ?", [project.id, run.id, parent.work_id]);
+    const reviews = groups.map((group) => { const work = created.find((item) => item.task === group.task); if (!work)
+        throw new AppError("runtime_missing", "Reviewer Work was not created", 1, { group: group.key }); const ready = work.status === "created" && isReviewWorkReady(context, work.work_id); return { group: group.key, work_id: work.work_id, status: work.status, depends_on: group.depends_on, ready, ...(ready ? { start_command: workStartCommand(context, { ...work, project_id: project.id, run_id: run.id }) } : {}) }; });
+    refreshRunWorkProjection(context, project.id, run.id);
+    appendFlowRunTimelineEvent(context, project.id, run.id, { type: "plan_review_dispatched", work_id: parent.work_id, groups: reviews.map((item) => ({ group: item.group, work_id: item.work_id })) });
+    const waves = plannedReviewWaves(groups, capacity.availableSlots);
+    return { ok: true, run_id: run.id, stage, capacity: { available_slots: capacity.availableSlots }, routing: { group_count: groups.length, planned_waves: waves.length, waves, preference: "Use one wave when semantic compatibility permits; hard dependencies create later waves." }, review_works: reviews, next_action: "launch_ready_reviews" };
+}
+// Capacity is a RUN fact shared by every fan-out stage.
+const reviewCapacityKey = subagentCapacityKey;
+/** Capacity is observed immediately before this stage dispatches reviewers. */
+export function recordVnextPlanReviewCapacity(context, input) {
+    if (!Number.isInteger(input.availableSlots) || input.availableSlots < 0 || input.availableSlots > 15) {
+        throw new AppError("validation", "--available-slots must be an integer from 0 to 15", 2);
+    }
+    const projectRoot = resolveProjectRoot(input.projectRoot);
+    const project = requireProjectByRoot(context, projectRoot);
+    const run = requireRun(context, projectRoot, input.runId);
+    const variables = getFlowRunVariables(context, { projectRoot, runId: run.id });
+    const prior = variables.variables[reviewCapacityKey];
+    if (typeof prior === "number") {
+        if (prior === input.availableSlots)
+            return { ok: true, run_id: run.id, capacity: { available_slots: prior, source: "bounded_probe", reused: true } };
+        setRuntimeRunVariable(context, { projectRoot, runId: run.id, key: reviewCapacityKey, value: input.availableSlots });
+        appendFlowRunTimelineEvent(context, project.id, run.id, { type: "subagent_capacity_refreshed", previous_available_slots: prior, available_slots: input.availableSlots, fanout_size: capacityProbeFanoutSize });
+        return { ok: true, run_id: run.id, capacity: { available_slots: input.availableSlots, previous_available_slots: prior, source: "bounded_probe", refreshed: true } };
+    }
+    setRuntimeRunVariable(context, { projectRoot, runId: run.id, key: reviewCapacityKey, value: input.availableSlots });
+    appendFlowRunTimelineEvent(context, project.id, run.id, { type: "subagent_capacity_observed", available_slots: input.availableSlots, fanout_size: capacityProbeFanoutSize });
+    return { ok: true, run_id: run.id, capacity: { available_slots: input.availableSlots, source: "one_shot_fanout", fanout_size: capacityProbeFanoutSize } };
+}
+export function finishVnextPlanReview(context, input) {
+    const projectRoot = resolveProjectRoot(input.projectRoot);
+    const project = requireProjectByRoot(context, projectRoot);
+    const run = requireRun(context, projectRoot, input.runId);
+    const home = requireHome(run);
+    const root = path.join(home, stageDir);
+    const planRoot = path.join(home, "03-plan");
+    const batch = path.join(planRoot, "code-work-batch.json");
+    const parent = context.db.get("SELECT work_id, status FROM works WHERE project_id = ? AND run_id = ? AND task = ? ORDER BY created_at DESC LIMIT 1", [project.id, run.id, reviewTask]);
+    if (!parent || parent.status !== "running")
+        throw new AppError("invalid_work_state", "PLAN-REVIEW has no running parent Work", 2);
+    const decisionPath = path.resolve(input.decisionFile ?? path.join(root, "decision.json"));
+    const decision = readDecision(context, projectRoot, run.id, decisionPath);
+    const children = context.db.all("SELECT work_id, task, status, result, created_at FROM works WHERE project_id = ? AND run_id = ? AND parent_work_id = ? AND task <> 'Capacity probe: return ready and finish this Work.'", [project.id, run.id, parent.work_id]);
+    const contextFile = readJson(path.join(root, "work-context.json"));
+    const groups = contextFile.groups ?? [];
+    const reviewedPlanRevision = contextFile.system?.plan_revision;
+    if (!Number.isInteger(reviewedPlanRevision) || reviewedPlanRevision < 1)
+        throw new AppError("runtime_missing", "PLAN-REVIEW starting revision is unavailable", 1);
+    const planRevision = currentPlanRevision(home, run.workspace_root);
+    if (["blocked", "failed", "cancelled"].includes(decision.outcome)) {
+        preserveDecisionReceipt(root, decisionPath);
+        return finishTerminalReview(context, { projectRoot, projectId: project.id, run, root, planRoot, batch, parentWorkId: parent.work_id, children, contextFile, decision });
+    }
+    if (children.some((child) => child.status === "created" || child.status === "running"))
+        throw new AppError("worker_jobs_incomplete", "PLAN-REVIEW finish requires all reviewer Works to settle", 1, { works: children.map((child) => ({ work_id: child.work_id, status: child.status })) });
+    const latestChildren = latestReviewChildren(children);
+    const evidenceFailures = reviewerEvidenceFailures(context, { projectId: project.id, parentWorkId: parent.work_id, children: latestChildren, groups, planRevision: reviewedPlanRevision });
+    if (evidenceFailures.length)
+        throw new AppError("review_evidence_invalid", "PLAN-REVIEW reviewer evidence is incomplete, stale, or not isolated", 2, { errors: evidenceFailures });
+    if (decision.outcome !== "accepted")
+        throw new AppError("validation", "Unsupported PLAN-REVIEW decision outcome", 2, { outcome: decision.outcome });
+    // A completed reviewer can legitimately report `blocked` when an upstream
+    // plan uncertainty prevents it from approving its aspect. That is evidence
+    // for the coordinator to classify and fix in this one review pass, not an
+    // infrastructure failure or a reason to start another review cycle.
+    const needsCorrection = latestChildren.some((child) => ["needs_changes", "blocked"].includes(reviewerVerdict(child.result)));
+    if (latestChildren.some((child) => child.status !== "completed"))
+        throw new AppError("blocked", "PLAN-REVIEW cannot accept incomplete reviewer evidence", 2);
+    const materialFindingIds = canonicalReviewerFindings(latestChildren).filter(({ finding }) => ["blocker", "high", "medium"].includes(finding.severity)).map(({ finding_ref }) => finding_ref);
+    const decidedFindingIds = new Set(decision.finding_decisions.map((finding) => finding.finding_ref).filter((id) => Boolean(id)));
+    if (new Set(materialFindingIds).size !== materialFindingIds.length || materialFindingIds.some((id) => !decidedFindingIds.has(id)))
+        throw new AppError("review_evidence_invalid", "Every material reviewer finding needs one stable decision", 2, { material_finding_ids: materialFindingIds, decided_finding_ids: [...decidedFindingIds] });
+    if (needsCorrection) {
+        if (decision.correction.status !== "applied")
+            throw new AppError("validation", "Reviewer findings require an in-place correction receipt", 2);
+        if (decision.correction.previous_plan_revision !== reviewedPlanRevision || planRevision <= reviewedPlanRevision || decision.correction.changed_paths.length === 0)
+            throw new AppError("validation", "Applied PLAN correction must advance revision and list changed paths", 2, { reviewed_plan_revision: reviewedPlanRevision, final_plan_revision: planRevision });
+    }
+    else if (decision.correction.status !== "not_required" || planRevision !== reviewedPlanRevision) {
+        throw new AppError("validation", "A clean PLAN review must not claim an unverified correction", 2);
+    }
+    const planFailures = validateVnextPlanArtifacts(context, { projectRoot, workspaceRoot: run.workspace_root, runId: run.id, home, protocols: protocolIdsForReview(home) });
+    if (planFailures.length)
+        throw new AppError("validation", "Corrected PLAN artifacts have validation errors", 2, { errors: planFailures });
+    if (needsCorrection) {
+        const initialBatchChecksum = contextFile.system?.batch_checksum;
+        if (!initialBatchChecksum || checksum(batch) === initialBatchChecksum)
+            throw new AppError("stale_code_work_batch", "Applied PLAN correction must regenerate the proposed CODE batch", 2, { batch, initial_batch_checksum: initialBatchChecksum });
+        if (decision.correction.changed_paths.some((item) => item.endsWith("code-work-batch.json")))
+            throw new AppError("validation", "Generated CODE batch must not be listed as an agent-authored correction", 2, { changed_paths: decision.correction.changed_paths });
+    }
+    preserveDecisionReceipt(root, decisionPath);
+    const finalPlanChecksum = checksum(path.join(run.workspace_root, ".memory-bank", "protocol", protocolIdsForReview(home)[0], "plan.json"));
+    const finalBatchChecksum = checksum(batch);
+    const registered = registerCode(context, project.id, run.id, batch);
+    const now = context.now();
+    settleReviewParent(context, { projectRoot, projectId: project.id, runId: run.id, parentWorkId: parent.work_id, status: "completed", result: decision.summary, reason: "plan_review_completed", resultPath: path.join(root, "stage-report.json") });
+    const report = reportFor({ run, mode: contextFile.system?.effective_mode ?? "standard", requested: contextFile.system?.requested_mode ?? "auto", outcome: "accepted", groups, batchChecksum: contextFile.system?.batch_checksum ?? finalBatchChecksum, planChecksum: contextFile.system?.plan_checksum ?? finalPlanChecksum, finalBatchChecksum, finalPlanChecksum, initialPlanRevision: reviewedPlanRevision, finalPlanRevision: planRevision, code: registered, now, projectRoot, decision, children: latestChildren, flow: flowCommand(context) });
+    applyReviewResults(home, latestChildren, decision);
+    writeReport(root, report);
+    refreshRunWorkProjection(context, project.id, run.id);
+    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" });
+    advanceFlowRun(context, { projectRoot, runId: run.id, status: "running", verdict: "plan_review_accepted", nextAction: "start_code" });
+    appendFlowRunTimelineEvent(context, project.id, run.id, { type: "plan_review_accepted", work_id: parent.work_id, code: registered });
+    return { ok: true, run_id: run.id, stage, outcome: "accepted", code: registered, next_action: "start_code", next: { kind: "start_stage", stage: "code", command: codeCommand(context, run.id, projectRoot) } };
+}
+function preparedExisting(context, input) {
+    const promptPath = path.join(input.root, "stage-prompt.md");
+    const binding = bindStageCoordinatorWork(context, { workId: input.workId, hookEventId: input.hookEventId, stage, promptPath, resultPath: path.join(input.root, "stage-report.json"), ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
+    const orchestration = readFanoutDescriptor(input.root) ?? writeFanoutDescriptor(input.root, { stage, parent_work_id: input.workId, dispatch: "plan-review", capacity_required: true });
+    return { ok: true, resumed: true, run_id: input.run.id, stage, outcome: "review_required", work_id: input.workId, id: binding.work_session_id, prompt_path: promptPath, worker_prompt_markdown: fs.readFileSync(promptPath, "utf8"), orchestration, plan_review: { requested_mode: input.requested, effective_mode: input.effective, policy_source: policySource(input.run), groups: input.groups }, next: { dispatch_command: dispatchCommand(context, input.run.id, input.projectRoot), finish_command: finishCommand(context, input.run.id, input.projectRoot, path.join(input.root, "decision.json")) } };
+}
+function orchestratorPrompt(context, input) {
+    const template = read(path.join(input.projectRoot, ".memory-bank", "dd-flow", "vnext", "plan-review.md"));
+    const decision = path.join(input.root, "decision.json");
+    const revision = currentPlanRevision(input.home, input.run.workspace_root);
+    const workspaceContract = ["<workspace_contract>", `- route: ${input.workspaceRoute.route}`, `- feature branch: ${input.workspaceRoute.feature_branch ?? "not applicable"}`, `- base commit: ${input.workspaceRoute.base_ref ?? "not applicable"}`, `- read/write workspace: ${input.run.workspace_root}`, "The CLI verified this frozen route. All plan and correction writes belong in the named workspace; project root remains only the stable lifecycle identity. Do not create, switch, merge or delete branches/worktrees.", "</workspace_contract>"].join("\n");
+    return ["<stage_identity>", `- RUN: ${input.run.id}`, `- Work: ${input.workId}`, "- Stage: plan-review", `- Mode: ${input.effective}`, "</stage_identity>", "", "<trusted_runtime_context>", "These facts were collected by dd-flow. Trust them; do not repeat CLI, Git, compatibility, permission or schema discovery.", `- Project root: ${input.projectRoot}`, `- Stage workspace: ${input.root}`, `- PLAN revision: ${revision}`, `- PLAN report checksum: ${input.planChecksum}`, `- Generated CODE batch checksum: ${input.batchChecksum}`, "</trusted_runtime_context>", "", workspaceContract, "", "<review_groups>", ...input.groups.map((group) => `- ${group.key}: ${group.aspect_ids.join(", ")}`), "</review_groups>", "", "<execution_commands>", `Dispatch fresh reviewers: ${dispatchCommand(context, input.run.id, input.projectRoot)}`, `If dispatch requests capacity, run exactly one concurrent fan-out of ${capacityProbeFanoutSize} probes. This measures the harness limit; it is not a task to obtain ${capacityProbeFanoutSize} successful probes. Start #01…#${capacityProbeFanoutSize} once, all together, using all-settled handling so one rejection does not hide the other outcomes. A rejected launch is expected evidence. Never retry, replace, or add a probe. Each started probe calls no tools, reads no files, creates no children, waits ${capacityProbeHoldSeconds} seconds, then returns exactly AGENT-NN. For cleanup, wait at most ${capacityProbeDeadlineSeconds} seconds from the first launch, terminate every unfinished probe, then release every finished probe session that the harness permits. Only after that cleanup record the number of launches that started successfully, not the number of replacement attempts or late completions: ${capacityRecordCommand(context, input.run.id, input.projectRoot, "<successful-initial-launches>")}. Capacity probes are not Works and are never registered.`, "After dispatch, launch at most the measured capacity at once. If more independent reviewer Works remain, wait for the current wave to settle, then start the unchanged queued Works in the next wave. A reviewer launch rejected before it starts is not review evidence: do not create a replacement; wait for a running wave to settle and start that same queued Work. Each reviewer must be a genuinely fresh harness child Session. The lifecycle adapter binds that observed Session; do not bind or supply a Session ID manually. Reviewers are read-only and must not create children. As soon as a reviewer result is accepted, release that reviewer Session when the harness permits; do not let finished disposable workers occupy slots before the next wave.", "Review the execution environment of every selected check as part of its proof: a reset/fixture process, service process and client process must share the intended data and configuration world. A runtime entrypoint that can break that invariant must be explicit in one Work's task and verification and ordered before its consumer. planned_write_areas may advertise likely overlap, but do not treat them as ownership; required_read alone is not a delivery plan.", "If the final decision needs user input with no reasonable default, run this exact one-command heredoc, replacing only its placeholder body. The heredoc is the permitted stdin form; do not use cat, a pipe, a temporary file or a second shell command:", "```sh", input.pauseCommandTemplate, "```", "Ask the returned user_message, stop, then resume this same PLAN-REVIEW Work. Do not write decision.json or finish first.", `When all reviewer results are complete and every user question is resolved, classify every material finding, fix accepted findings in this same PLAN-REVIEW Work, then write ${decision} and finish: ${finishCommand(context, input.run.id, input.projectRoot, decision)}`, "Reviewer findings use local FIND-NNN ids. dd-flow exposes each finding to this coordinator as WRK-.../FIND-NNN; use that canonical finding_ref in the decision.", "A completed reviewer result with needs_changes or blocked is evidence, not the stage outcome. Classify its material findings and apply accepted fixes in this one review pass; do not start a second review automatically. Only a missing, malformed or unfinished reviewer result blocks the stage. For an accepted correction, increment PLAN revision and update only plan.json and the relevant aspect map. Do not edit or list code-work-batch.json: the CLI validates final PLAN and regenerates it. If no material correction is needed, set correction.status=not_required. The CLI checks mechanical handoff coherence; it does not prove semantic correctness.", "```json", JSON.stringify({ schema_id: "dd-flow/plan-review-decision@3", outcome: "accepted | blocked | failed | cancelled", summary: "Concise evidence-backed final decision.", finding_decisions: [{ finding_ref: "WRK-001-review/FIND-001", decision: "accepted_fix | rejected | deferred_as_DEF | requires_user | duplicate", reason: "Why." }], correction: { status: "not_required | applied", previous_plan_revision: revision, changed_paths: [], summary: "No material correction was needed, or summarize the applied correction." } }, null, 2), "```", "</execution_commands>", "", "<stage_instructions>", template, "</stage_instructions>", ""].join("\n");
+}
+function reviewGroups(home, workspaceRoot) {
+    const root = path.join(home, "03-plan");
+    const reports = JSON.parse(fs.readFileSync(path.join(home, "02-protocolize", "stage-report.json"), "utf8"));
+    const protocols = reports.semantic?.acceptance ?? [];
+    const groups = [];
+    for (const protocolId of protocols) {
+        const mapPath = path.join(root, protocolId, "aspect-map.json");
+        const map = readJson(mapPath);
+        const review = map.review_groups?.filter((group) => group.id && group.aspect_ids?.length).map((group) => ({ id: group.id, aspect_ids: group.aspect_ids })) ?? [];
+        const groupForAspect = new Map(review.flatMap((group) => group.aspect_ids.map((aspectId) => [aspectId, `${protocolId}/${group.id}`])));
+        for (const group of review) {
+            const key = `${protocolId}/${group.id}`;
+            const dependencies = new Set();
+            for (const aspectId of group.aspect_ids)
+                for (const dependency of aspectDependencies(workspaceRoot, aspectId)) {
+                    const dependencyGroup = groupForAspect.get(dependency);
+                    if (dependencyGroup && dependencyGroup !== key)
+                        dependencies.add(dependencyGroup);
+                }
+            groups.push({ key, protocol_id: protocolId, aspect_ids: group.aspect_ids, depends_on: [...dependencies].sort(), task: `Review PLAN group ${key}: ${group.aspect_ids.join(", ")}. Read run://${path.basename(home)}/03-plan/${protocolId}/aspect-map.json and the referenced plan. Try to falsify ambiguous behavior and missing verification. For every selected check that starts fixture/reset, service, or client processes, verify that they share the intended data/configuration world and that any runtime entrypoint requiring change is explicit in a Work task and verification and ordered before its consumer. planned_write_areas are coordination hints, not ownership. Do not edit plan or product files. Return one aspect entry for every assigned aspect, with exact evidence references and concise findings. Finish with the JSON contract supplied in your work prompt.` });
+        }
+    }
+    return groups;
+}
+function aspectDependencies(workspaceRoot, aspectId) {
+    const file = path.join(workspaceRoot, ".memory-bank", "dd-flow", "mb-sdlc", "plan-aspects", "aspects", `${aspectId}.md`);
+    try {
+        const match = fs.readFileSync(file, "utf8").match(/^depends_on:\s*\[([^\]]*)\]/m);
+        return match?.[1]?.split(",").map((value) => value.trim()).filter(Boolean) ?? [];
+    }
+    catch {
+        return [];
+    }
+}
+function isReviewWorkReady(context, workId) {
+    const row = context.db.get("SELECT depends_on_json FROM works WHERE work_id = ?", [workId]);
+    const dependencies = row ? JSON.parse(row.depends_on_json) : [];
+    return dependencies.every((dependency) => context.db.get("SELECT status FROM works WHERE work_id = ?", [dependency])?.status === "completed");
+}
+function plannedReviewWaves(groups, capacity) {
+    const remaining = new Map(groups.map((group) => [group.key, group]));
+    const completed = new Set();
+    const waves = [];
+    while (remaining.size) {
+        const ready = [...remaining.values()].filter((group) => group.depends_on.every((dependency) => completed.has(dependency)));
+        if (!ready.length)
+            throw new AppError("validation", "PLAN-REVIEW group dependencies contain a cycle", 2);
+        for (let offset = 0; offset < ready.length; offset += capacity) {
+            const wave = ready.slice(offset, offset + capacity).map((group) => group.key);
+            waves.push(wave);
+            for (const key of wave) {
+                remaining.delete(key);
+                completed.add(key);
+            }
+        }
+    }
+    return waves;
+}
+export function capacityProbeResponse(context, input) {
+    return { ok: true, run_id: input.runId, stage, outcome: "capacity_probe_required", capacity_probe: { ...capacityProbe, controller_instruction: "Launch exactly one concurrent batch of 15 independent leaf probes. Use all-settled behavior: every initial launch is attempted once, and a launch rejection is expected evidence of the current limit. Do not retry, replace, or add probes. Count the initial launches that returned a live session handle. Successful probes must not call tools, read files, create children or run dd-flow; they wait 60 seconds then return exactly AGENT-NN. Wait only for cleanup, at most 180 seconds from first launch; terminate unfinished probes, then close/delete every finished probe session that the harness permits. Record only the initial successful-launch count after cleanup." }, next_action: "run_one_shot_capacity_probe_then_retry_dispatch", next: { record_command: capacityRecordCommand(context, input.runId, input.projectRoot, "<successful-initial-launches>"), retry_command: dispatchCommand(context, input.runId, input.projectRoot) } };
+}
+function ensureReviewCapacity(context, input) {
+    const variables = getFlowRunVariables(context, { projectRoot: input.projectRoot, runId: input.runId });
+    const known = variables.variables[reviewCapacityKey];
+    if (typeof known === "number" && Number.isInteger(known) && known >= 0)
+        return { pending: false, availableSlots: known };
+    return { pending: true, response: capacityProbeResponse(context, { projectRoot: input.projectRoot, runId: input.runId }) };
+}
+function protocolIdsForReview(home) {
+    const report = readJson(path.join(home, "02-protocolize", "stage-report.json"));
+    return Array.isArray(report.semantic?.acceptance) ? report.semantic.acceptance.filter((value) => typeof value === "string") : [];
+}
+/** The aspect map is a PLAN routing manifest; reviewer state lives in Work results. */
+function markReviewPending(_home, _groups) { }
+/** Review evidence is immutable child Work output plus the stage decision. */
+function applyReviewResults(_home, _children, _decision) { }
+function canonicalReviewerFindings(children) { return children.flatMap((child) => (reviewerResult(child.result)?.aspects ?? []).flatMap((aspect) => aspect.findings.map((finding) => ({ finding_ref: `${child.work_id}/${finding.finding_id}`, finding })))); }
+function resolveMode(requested, groups, home, projectRoot) {
+    if (requested !== "auto")
+        return requested;
+    if (!groups.length)
+        return "off";
+    const plans = protocolIdsForReview(home).map((id) => readJson(path.join(projectRoot, ".memory-bank", "protocol", id, "plan.json")));
+    return plans.some((plan) => plan.assessment?.failure_impact?.level === "high" || plan.assessment?.solution_uncertainty?.level === "high") ? "deep" : "standard";
+}
+function assertReviewWorkspace(workspaceRoot, protocols) {
+    for (const id of protocols) {
+        const plan = path.join(workspaceRoot, ".memory-bank", "protocol", id, "plan.json");
+        if (!fs.existsSync(plan))
+            throw new AppError("workspace_plan_missing", "PLAN-REVIEW requires PLAN artifacts in the registered RUN workspace", 1, { workspace_root: workspaceRoot, protocol_id: id, expected: plan });
+    }
+}
+function readIndex(run) { try {
+    return JSON.parse(run.index_json);
+}
+catch {
+    return {};
+} }
+function requestedMode(run) { try {
+    const index = JSON.parse(run.index_json);
+    const mode = index.settings?.plan_review?.mode;
+    return mode && ["auto", "off", "standard", "deep"].includes(mode) ? mode : "auto";
+}
+catch {
+    return "auto";
+} }
+function policySource(run) { try {
+    const index = JSON.parse(run.index_json);
+    return index.settings?.plan_review?.source ?? "default";
+}
+catch {
+    return "default";
+} }
+function rootWorkId(context, projectId, runId) { const root = context.db.get("SELECT work_id FROM works WHERE project_id = ? AND run_id = ? AND parent_work_id IS NULL ORDER BY created_at LIMIT 1", [projectId, runId]); if (!root)
+    throw new AppError("runtime_missing", "vNext RUN has no root Work", 1); return root.work_id; }
+function registerCode(context, projectId, runId, batch) { return addWorkBatch(context, { parentWorkId: rootWorkId(context, projectId, runId), file: batch }); }
+function readDecision(context, projectRoot, runId, file) { validateSchema({ schemaName: "plan-review-decision", file, projectRoot, runId, ddFlowHome: context.ddFlowHome }); return readJson(file); }
+function preserveDecisionReceipt(root, source) {
+    const receipt = path.join(root, "decision.receipt.json");
+    const bytes = fs.readFileSync(source);
+    if (fs.existsSync(receipt)) {
+        if (!bytes.equals(fs.readFileSync(receipt)))
+            throw new AppError("decision_receipt_conflict", "The immutable PLAN-REVIEW decision receipt already contains a different payload", 2, { receipt });
+        return;
+    }
+    fs.writeFileSync(receipt, bytes);
+}
+function reviewerResult(result) { try {
+    const value = JSON.parse(result ?? "");
+    return Array.isArray(value.aspects) ? value : null;
+}
+catch {
+    return null;
+} }
+function reviewerVerdict(result) { return reviewerResult(result)?.overall_verdict ?? ""; }
+function latestReviewChildren(children) { return children; }
+function currentPlanRevision(home, projectRoot) {
+    const revisions = protocolIdsForReview(home).map((id) => Number(readJson(path.join(projectRoot, ".memory-bank", "protocol", id, "plan.json")).revision));
+    if (!revisions.length || revisions.some((value) => !Number.isInteger(value) || value < 1))
+        throw new AppError("runtime_missing", "Accepted PLAN revision is unavailable", 1);
+    return Math.max(...revisions);
+}
+function reviewerEvidenceFailures(context, input) {
+    const parent = context.db.get("SELECT session_id FROM work_sessions WHERE work_id = ? ORDER BY created_at DESC LIMIT 1", [input.parentWorkId]);
+    const failures = [];
+    for (const group of input.groups) {
+        const child = input.children.find((item) => item.task === group.task);
+        if (!child || child.status !== "completed") {
+            failures.push({ group: group.key, error: "reviewer_work_not_completed" });
+            continue;
+        }
+        const result = reviewerResult(child.result);
+        if (!result || result.plan_revision !== input.planRevision) {
+            failures.push({ group: group.key, work_id: child.work_id, error: "reviewer_result_missing_or_stale" });
+            continue;
+        }
+        const actual = result.aspects.map((item) => item.aspect_id);
+        if (actual.length !== group.aspect_ids.length || new Set(actual).size !== actual.length || group.aspect_ids.some((id) => !actual.includes(id)) || result.aspects.some((item) => item.evidence_refs.length === 0))
+            failures.push({ group: group.key, work_id: child.work_id, error: "reviewer_aspect_coverage_invalid", expected_aspects: group.aspect_ids, actual_aspects: actual });
+        const workSession = context.db.get("SELECT session_id, status FROM work_sessions WHERE work_id = ? ORDER BY created_at DESC LIMIT 1", [child.work_id]);
+        if (!workSession?.session_id || workSession.status !== "completed" || workSession.session_id === parent?.session_id)
+            failures.push({ group: group.key, work_id: child.work_id, error: "reviewer_session_not_fresh", parent_session_id: parent?.session_id ?? null, reviewer_session_id: workSession?.session_id ?? null });
+    }
+    return failures;
+}
+function settleReviewParent(context, input) {
+    const now = context.now();
+    context.db.run("UPDATE works SET status = ?, result = ?, completed_at = ?, updated_at = ? WHERE work_id = ?", [input.status, input.result, now, now, input.parentWorkId]);
+    const workSession = context.db.get("SELECT id, session_id FROM work_sessions WHERE work_id = ? AND status = 'running' ORDER BY created_at DESC LIMIT 1", [input.parentWorkId]);
+    if (!workSession)
+        return;
+    context.db.run("UPDATE work_sessions SET status = ?, result_path = COALESCE(?, result_path), completed_at = ?, updated_at = ? WHERE id = ?", [input.status, input.resultPath ?? null, now, now, workSession.id]);
+}
+function finishTerminalReview(context, input) {
+    const now = context.now();
+    const childStatus = input.decision.outcome === "cancelled" ? "cancelled" : "failed";
+    // A terminal decision is structured cancellation of the review subtree. It
+    // must settle probes as well as semantic reviewers before its parent Work
+    // can settle; otherwise the RUN contains abandoned active Work/Session links.
+    settleReviewChildren(context, { projectId: input.projectId, runId: input.run.id, parentWorkId: input.parentWorkId, status: childStatus, reason: `PLAN-REVIEW terminal decision: ${input.decision.summary}`, now });
+    settleReviewParent(context, { projectRoot: input.projectRoot, projectId: input.projectId, runId: input.run.id, parentWorkId: input.parentWorkId, status: childStatus, result: input.decision.summary, reason: `plan_review_${input.decision.outcome}`, resultPath: path.join(input.root, "stage-report.json") });
+    const rootWork = rootWorkId(context, input.projectId, input.run.id);
+    context.db.run("UPDATE works SET status = ?, result = ?, completed_at = ?, updated_at = ? WHERE work_id = ? AND status = 'running'", [childStatus, input.decision.summary, now, now, rootWork]);
+    closeRunningWorkSession(context, rootWork, childStatus, now);
+    const settledChildren = context.db.all("SELECT work_id, task, status, result, created_at FROM works WHERE project_id = ? AND run_id = ? AND parent_work_id = ? AND task <> 'Capacity probe: return ready and finish this Work.'", [input.projectId, input.run.id, input.parentWorkId]);
+    const report = reportFor({ run: input.run, mode: input.contextFile.system?.effective_mode ?? "standard", requested: input.contextFile.system?.requested_mode ?? "auto", outcome: input.decision.outcome, groups: input.contextFile.groups ?? [], batchChecksum: input.contextFile.system?.batch_checksum ?? checksum(input.batch), planChecksum: input.contextFile.system?.plan_checksum ?? checksum(path.join(input.planRoot, "stage-report.json")), code: {}, now, projectRoot: input.projectRoot, decision: input.decision, children: latestReviewChildren(settledChildren), flow: flowCommand(context) });
+    writeReport(input.root, report);
+    refreshRunWorkProjection(context, input.projectId, input.run.id);
+    const stageStatus = input.decision.outcome === "cancelled" ? "skipped" : input.decision.outcome === "failed" ? "failed" : "blocked";
+    completeFlowRunStage(context, { projectRoot: input.projectRoot, runId: input.run.id, stage, status: stageStatus, data: "stage-report.json", dataSchemaId: "dd-flow/stage-report@1", report: "stage-report.md", stageReport: "stage-report.html" });
+    completeFlowRun(context, { projectRoot: input.projectRoot, runId: input.run.id, status: input.decision.outcome === "cancelled" ? "cancelled" : input.decision.outcome === "failed" ? "failed" : "blocked", verdict: `plan_review_${input.decision.outcome}`, nextAction: "resolve_plan_review_blocker" });
+    appendFlowRunTimelineEvent(context, input.projectId, input.run.id, { type: "plan_review_terminal", outcome: input.decision.outcome, work_id: input.parentWorkId });
+    return { ok: true, run_id: input.run.id, stage, outcome: input.decision.outcome, next_action: "resolve_plan_review_blocker" };
+}
+function settleReviewChildren(context, input) {
+    const active = context.db.all("SELECT work_id FROM works WHERE project_id = ? AND run_id = ? AND parent_work_id = ? AND status IN ('created', 'running')", [input.projectId, input.runId, input.parentWorkId]);
+    for (const child of active) {
+        context.db.run("UPDATE works SET status = ?, result = ?, completed_at = ?, updated_at = ? WHERE work_id = ?", [input.status, input.reason, input.now, input.now, child.work_id]);
+        closeRunningWorkSession(context, child.work_id, input.status, input.now);
+    }
+}
+function closeRunningWorkSession(context, workId, status, now) {
+    context.db.run("UPDATE work_sessions SET status = ?, completed_at = ?, updated_at = ? WHERE work_id = ? AND status = 'running'", [status, now, now, workId]);
+}
+function reportFor(input) {
+    const accepted = input.outcome === "accepted" || input.outcome === "off";
+    const result = input.outcome === "off" ? "Independent PLAN review was explicitly or automatically skipped." : accepted ? "Independent PLAN review accepted the plan." : `PLAN-REVIEW stopped with outcome: ${input.outcome}.`;
+    const decision = input.decision;
+    const correction = decision?.correction ?? null;
+    const timing = stageTiming(input.run, input.now);
+    const sessionCommand = `${input.flow} stat run sessions ls --run ${input.run.id} --project-root ${JSON.stringify(input.projectRoot)} --json`;
+    const usageCommand = `${input.flow} stat usage --run ${input.run.id} --project-root ${JSON.stringify(input.projectRoot)} --json`;
+    const changedFiles = correction?.status === "applied" ? correction.changed_paths : [];
+    return { schema_id: "dd-flow/stage-report@1", run_id: input.run.id, stage, generated_at: input.now, verdict: accepted ? "done" : input.outcome, semantic: { result, acceptance: [input.outcome], changed_files: changedFiles, checks: ["accepted PLAN report", "generated CODE batch", "reviewer evidence", ...(correction ? ["mechanical correction receipt"] : [])], evidence: [], next_action: accepted ? "start_code" : "resolve_plan_review_blocker", plan_review: { requested_mode: input.requested, effective_mode: input.mode, outcome: input.outcome, groups: input.groups.map((group) => group.key), initial_plan_revision: input.initialPlanRevision ?? null, final_plan_revision: input.finalPlanRevision ?? input.initialPlanRevision ?? null, initial_plan_checksum: input.planChecksum, final_plan_checksum: input.finalPlanChecksum ?? input.planChecksum, initial_batch_checksum: input.batchChecksum, final_batch_checksum: input.finalBatchChecksum ?? input.batchChecksum, correction, decision: input.decision ?? null, reviewer_works: input.children?.map((child) => ({ work_id: child.work_id, status: child.status, verdict: reviewerVerdict(child.result) })) ?? [] }, plan_checksum: input.finalPlanChecksum ?? input.planChecksum, batch_checksum: input.finalBatchChecksum ?? input.batchChecksum, code: input.code }, mechanical: { started_at: timing.started_at, finished_at: input.now, wall_clock_ms: timing.wall_clock_ms, git: gitFacts(input.run.workspace_root), session_stats_command: sessionCommand, usage_stats_command: usageCommand, ...(accepted ? { next_command: `${input.flow} stage start ${input.run.id} --stage code --project-root ${JSON.stringify(input.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" } };
+}
+function stageTiming(run, now) { const started = readIndex(run).stage_runs?.find((item) => item.stage === stage && typeof item.started_at === "string"); const startedAt = started?.started_at ?? now; const milliseconds = Date.parse(now) - Date.parse(startedAt); return { started_at: startedAt, wall_clock_ms: Number.isFinite(milliseconds) && milliseconds >= 0 ? milliseconds : null }; }
+function writeReport(root, report) {
+    writeStageReport(root, report);
+}
+function codeCommand(context, runId, projectRoot) { return `${flowCommand(context)} stage start ${runId} --stage code --project-root ${JSON.stringify(projectRoot)} --json`; }
+function dispatchCommand(context, runId, projectRoot) { return `${flowCommand(context)} plan-review dispatch ${runId} --project-root ${JSON.stringify(projectRoot)} --json`; }
+function finishCommand(context, runId, projectRoot, decision) { return `${flowCommand(context)} stage finish ${runId} --stage plan-review --project-root ${JSON.stringify(projectRoot)} --decision-file ${JSON.stringify(decision)} --json`; }
+function capacityRecordCommand(context, runId, projectRoot, availableSlots) { return `${flowCommand(context)} run capacity record ${runId} --available-slots ${availableSlots} --project-root ${JSON.stringify(projectRoot)} --json`; }
+function requireRun(context, projectRoot, runId) { const project = requireProjectByRoot(context, projectRoot); const run = context.db.get("SELECT id, project_id, workspace_root, run_home_path, index_json FROM runs WHERE project_id = ? AND id = ?", [project.id, runId]); if (!run)
+    throw new AppError("not_found", "RUN is not registered", 1); return run; }
+function requireHome(run) { if (!run.run_home_path)
+    throw new AppError("runtime_missing", "RUN workspace is unavailable", 1); return run.run_home_path; }
+function read(file) { if (!fs.existsSync(file))
+    throw new AppError("not_found", "Required vNext prompt is missing", 1, { file }); return fs.readFileSync(file, "utf8"); }
+function readJson(file) { try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+catch {
+    throw new AppError("validation", "Expected valid JSON artifact", 2, { file });
+} }
+function writeJson(file, value) { const temporary = `${file}.${crypto.randomUUID()}.tmp`; fs.writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`); fs.renameSync(temporary, file); }
+function checksum(file) { return crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex"); }