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

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

@@ -0,0 +1,305 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { AppError } from "../shared/errors.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { requireProjectByRoot } from "./projects.js";
+import { appendFlowRunTimelineEvent, attachFlowRunStage, completeFlowRun, completeFlowRunStage, gitFacts } from "./runs.js";
+import { validateSchema } from "./schema-validation.js";
+import { flowCommand } from "./stage-pause.js";
+import { assertStageStartHookEvent } from "./hooks.js";
+import { requireVnextWorkspaceRoute } from "./vnext-workspace-policy.js";
+import { addVnextCodeRepair, writeProtocolFlowStatus } from "./vnext-code.js";
+import { finalCodeCheckDeclarations, runCodeChecks, unchangedFinalGateFailures } from "./code-checks.js";
+import { addWorkBatch, bindStageCoordinatorWork, finishWork, refreshRunWorkProjection } from "./work-registry.js";
+import { vnextStageDirectory } from "../domain/stage-catalog.js";
+import { writeStageReport } from "./stage-report-renderer.js";
+import { applyExternalStageContext } from "./stage-context.js";
+import { readFanoutDescriptor, writeFanoutDescriptor } from "./vnext-fanout.js";
+const stage = "code-review";
+const stageDir = vnextStageDirectory(stage);
+const baselineAspects = ["goal_traceability", "coding_standards_design_review", "verification_evidence_review"];
+export function isVnextCodeReviewRun(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 startVnextCodeReview(context, input) {
+    const projectRoot = resolveProjectRoot(input.projectRoot);
+    const project = requireProjectByRoot(context, projectRoot);
+    const run = requireRun(context, project.id, input.runId);
+    const home = requireHome(run);
+    assertStageStartHookEvent(context, { projectId: project.id, eventKey: input.hookEventId, runId: run.id, stage, projectRoot, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
+    requireVnextWorkspaceRoute({ projectRoot, runId: run.id, runHome: home, workspaceRoot: run.workspace_root, stage });
+    if (!fs.existsSync(path.join(home, "05-code", "stage-report.json")))
+        throw new AppError("not_found", "CODE-REVIEW requires an accepted CODE report", 1);
+    const root = path.join(home, stageDir);
+    fs.mkdirSync(root, { recursive: true });
+    const rootWork = requireRootWork(context, project.id, run.id);
+    const prior = stageStatus(run, stage);
+    const existingPrompt = path.join(root, "stage-prompt.md");
+    if (prior && fs.existsSync(existingPrompt)) {
+        const externalContext = applyExternalStageContext({ stageRoot: root, promptPath: existingPrompt, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
+        const binding = bindStageCoordinatorWork(context, { workId: rootWork.work_id, hookEventId: input.hookEventId, stage, promptPath: existingPrompt, resultPath: path.join(root, "stage-report.json"), ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
+        const prompt = fs.readFileSync(existingPrompt, "utf8");
+        const orchestration = readFanoutDescriptor(root);
+        return { ok: true, resumed: true, run_id: run.id, stage, stage_status: prior, id: binding.work_session_id, prompt_path: existingPrompt, worker_prompt_markdown: prompt, ...(externalContext ? { external_context: externalContext } : {}), ...(orchestration ? { orchestration } : {}), next: { finish_command: finishCommand(context, run.id, projectRoot, path.join(root, "decision.json")) } };
+    }
+    const mode = effectiveMode(run, changedPaths(run.workspace_root));
+    const promptPath = path.join(root, "stage-prompt.md");
+    if (mode === "off") {
+        const prompt = `<stage_identity>\n- RUN: ${run.id}\n- stage: code-review\n- mode: off\n</stage_identity>\n\nCODE-REVIEW is disabled by the frozen RUN configuration. Finish with: ${finishCommand(context, run.id, projectRoot, path.join(root, "decision.json"))}\n`;
+        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: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@1" });
+        return { ok: true, run_id: run.id, stage, mode, id: binding.work_session_id, prompt_path: promptPath, worker_prompt_markdown: fs.readFileSync(promptPath, "utf8"), ...(externalContext ? { external_context: externalContext } : {}), next: { finish_command: finishCommand(context, run.id, projectRoot, path.join(root, "decision.json")) } };
+    }
+    const groups = reviewGroups(run, home, mode);
+    const batch = { works: groups.map((group, index) => ({ key: `code-review-${index + 1}`, task: reviewerTask(home, group), launch_policy: "fresh_agent_required", result_schema: "dd-flow/code-review-result@1", payload: { kind: "code-review", group, read_only: true } })) };
+    const batchFile = path.join(root, "review-work-batch.json");
+    fs.writeFileSync(batchFile, `${JSON.stringify(batch, null, 2)}\n`);
+    const prompt = orchestratorPrompt(context, { projectRoot, run, root, rootWork, mode, groups });
+    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 } : {}) });
+    const registered = addWorkBatch(context, { parentWorkId: rootWork.work_id, file: batchFile });
+    const orchestration = writeFanoutDescriptor(root, { stage, parent_work_id: rootWork.work_id, dispatch: "none", capacity_required: true });
+    attachFlowRunStage(context, { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@1" });
+    appendFlowRunTimelineEvent(context, project.id, run.id, { type: "code_review_started", work_id: rootWork.work_id, mode, groups, registered });
+    return { ok: true, run_id: run.id, stage, mode, id: binding.work_session_id, prompt_path: promptPath, worker_prompt_markdown: fs.readFileSync(promptPath, "utf8"), ...(externalContext ? { external_context: externalContext } : {}), orchestration, review: { groups, works: registered }, next: { finish_command: finishCommand(context, run.id, projectRoot, path.join(root, "decision.json")) } };
+}
+/** Create a narrow CODE repair from accepted independent-review evidence. */
+export function addVnextCodeReviewRepair(context, input) {
+    const projectRoot = resolveProjectRoot(input.projectRoot);
+    const project = requireProjectByRoot(context, projectRoot);
+    const run = requireRun(context, project.id, input.runId);
+    const reviewers = reviewerWorks(context, project.id, run.id);
+    const findings = canonicalCodeFindings(reviewers);
+    const selected = findings.filter((finding) => input.findingIds.includes(finding.finding_ref));
+    if (selected.length !== new Set(input.findingIds).size)
+        throw new AppError("not_found", "CODE-REVIEW repair references an unknown or ambiguous finding", 2, { finding_ids: input.findingIds });
+    if (selected.some(({ finding }) => finding.priority === "p3"))
+        throw new AppError("validation", "P3 observations are not CODE repair inputs", 2, { finding_ids: input.findingIds });
+    const origins = codeWorks(context, project.id, run.id).map((work) => work.work_id);
+    if (!origins.length)
+        throw new AppError("runtime_missing", "CODE-REVIEW repair requires completed CODE Work", 1);
+    return addVnextCodeRepair(context, {
+        projectRoot,
+        runId: run.id,
+        reviewFindingIds: selected.map((finding) => finding.finding_ref),
+        reviewEvidenceRefs: selected.flatMap(({ finding }) => finding.evidence_refs),
+        originWorkIds: origins,
+        objective: input.objective
+    });
+}
+export async function finishVnextCodeReview(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);
+    const mode = effectiveMode(run, changedPaths(run.workspace_root));
+    const reportPath = path.join(root, "stage-report.json");
+    if (stageStatus(run, stage) === "done" && fs.existsSync(reportPath))
+        return { ok: true, resumed: true, run_id: run.id, stage, outcome: "accepted", report_path: reportPath, next_action: "code_review_completed" };
+    const rootWork = requireRootWork(context, project.id, run.id);
+    const coordinator = context.db.get("SELECT session_id, result_path FROM work_sessions WHERE work_id = ? AND status = 'running' ORDER BY created_at DESC LIMIT 1", [rootWork.work_id]);
+    if (!coordinator || path.resolve(coordinator.result_path ?? "") !== path.resolve(reportPath))
+        throw new AppError("code_review_session_binding_conflict", "CODE-REVIEW can finish only after its successful stage start bound the coordinator Session and report path", 1, { run_id: run.id, expected_result_path: reportPath, actual_result_path: coordinator?.result_path ?? null });
+    const decisionFile = input.decisionFile ?? path.join(root, "decision.json");
+    if (!fs.existsSync(decisionFile) && mode === "off")
+        fs.writeFileSync(decisionFile, `${JSON.stringify({ schema_id: "dd-flow/code-review-decision@2", summary: "CODE-REVIEW is disabled by RUN configuration.", findings: [] }, null, 2)}\n`);
+    validateSchema({ schemaName: "code-review-decision", file: decisionFile, projectRoot: run.workspace_root, ddFlowHome: context.ddFlowHome, runId: run.id });
+    const decision = readJson(decisionFile);
+    const reviewers = reviewerWorks(context, project.id, run.id);
+    if (mode !== "off") {
+        const incomplete = reviewers.filter((work) => work.status !== "completed");
+        if (incomplete.length)
+            throw new AppError("reviewer_jobs_incomplete", "CODE-REVIEW cannot finish while reviewer Work is unsettled", 2, { works: incomplete.map((work) => ({ work_id: work.work_id, status: work.status })) });
+        for (const work of reviewers)
+            validateReviewerResult(context, work, run);
+        const canonical = reviewDecisionForRepair(decision, reviewers);
+        let repairs = reviewRepairWorks(context, project.id, run.id, root);
+        const decisionSha = sha256File(decisionFile);
+        const frozenShaFile = path.join(root, ".decision-sha256");
+        if (fs.existsSync(frozenShaFile) && fs.readFileSync(frozenShaFile, "utf8").trim() !== decisionSha)
+            throw new AppError("review_decision_changed", "The accepted CODE-REVIEW decision cannot change during repair", 2, { decision_file: decisionFile });
+        const fixIds = canonical.fix_ids;
+        if (fixIds.length && repairs.length === 0) {
+            fs.writeFileSync(frozenShaFile, `${decisionSha}\n`);
+            const repair = addVnextCodeReviewRepair(context, { projectRoot, runId: run.id, findingIds: fixIds, objective: `Resolve accepted CODE-REVIEW findings: ${fixIds.join(", ")}` });
+            return { ok: true, run_id: run.id, stage, outcome: "repair_required", decision_sha256: decisionSha, repair, instruction: "Run the returned repair Work in one fresh child session. When it completes, invoke the same stage finish command again with the unchanged decision file.", next: { finish_command: finishCommand(context, run.id, projectRoot, decisionFile) } };
+        }
+        repairs = reviewRepairWorks(context, project.id, run.id, root);
+        const incompleteRepairs = repairs.filter((work) => work.status !== "completed");
+        if (incompleteRepairs.length)
+            throw new AppError("review_repair_incomplete", "CODE-REVIEW cannot finish while a repair Work is unsettled", 2, { works: incompleteRepairs.map((work) => ({ work_id: work.work_id, status: work.status })) });
+        validateDecision(context, { decision: canonical.decision, reviewers: canonical.reviewers, repairs, workspaceRoot: run.workspace_root });
+    }
+    const outcome = decision.findings.some((item) => item.disposition === "defer") ? "accepted_with_DEF" : "accepted";
+    const repairs = reviewRepairWorks(context, project.id, run.id, root);
+    const finalChecks = finalCodeCheckDeclarations(run.workspace_root, codeWorks(context, project.id, run.id).flatMap((work) => { const payload = readJsonString(work.payload_json); return Array.isArray(payload.checks) ? payload.checks : []; }));
+    const unchangedFailures = repairs.length ? unchangedFinalGateFailures(context, { projectId: project.id, runId: run.id, workspaceRoot: run.workspace_root, declarations: finalChecks }) : [];
+    if (unchangedFailures.length)
+        throw new AppError("code_review_gate_repair_required", "CODE-REVIEW 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 });
+    const receipts = repairs.length ? await runCodeChecks(context, { projectId: project.id, runId: run.id, runHome: home, workspaceRoot: run.workspace_root, artifactDir: stageDir, scope: "aggregate", checks: finalChecks, ...(input.progress ? { progress: input.progress } : {}) }) : [];
+    const failed = receipts.filter((receipt) => receipt.status === "failed");
+    if (failed.length)
+        throw new AppError("code_review_gate_failed", "CODE-REVIEW repair changed the project but the aggregate gate failed", 2, { failures: failed });
+    const now = context.now();
+    const startedAt = stageStartedAt(run, now);
+    writeProtocolFlowStatus(run.workspace_root, home, run.id, "CODE-REVIEW 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", semantic: { result: decision.summary, acceptance: ["all_selected_review_groups_completed", "all_material_findings_classified", ...(repairs.length ? ["all_accepted_repairs_completed", "post_repair_final_gate_passed"] : [])], run_changed_files: changedPaths(run.workspace_root), checks: receipts.map((receipt) => receipt.command), evidence: [...reviewers.flatMap((work) => readJsonString(work.result).findings.flatMap((finding) => finding.evidence_refs)), ...receipts.map((receipt) => runRef(run.id, home, receipt.receipt_path))], next_action: "code_review_completed", code_review: { mode, reviewer_work_ids: reviewers.map((work) => work.work_id), repair_work_ids: repairs.map((work) => work.work_id), decision } }, mechanical: { started_at: startedAt, finished_at: now, wall_clock_ms: Math.max(0, Date.parse(now) - Date.parse(startedAt)), git: gitFacts(run.workspace_root), 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" }, validation: { 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" });
+    await finishWork(context, rootWork.work_id, JSON.stringify(report, null, 2));
+    appendFlowRunTimelineEvent(context, project.id, run.id, { type: "code_review_completed", work_id: rootWork.work_id, outcome });
+    completeFlowRun(context, { projectRoot, runId: run.id, status: "done", verdict: "code_review_completed", nextAction: undefined });
+    refreshRunWorkProjection(context, project.id, run.id);
+    return { ok: true, run_id: run.id, stage, outcome, report_path: path.join(root, "stage-report.json"), next_action: "code_review_completed" };
+}
+function reviewGroups(run, home, mode) {
+    const aspectMapFiles = findFiles(path.join(home, "03-plan"), "aspect-map.json");
+    const ids = new Set(baselineAspects);
+    for (const file of aspectMapFiles) {
+        const map = readJson(file);
+        for (const aspect of map.aspects ?? [])
+            if (aspect.applicability === "applicable" && aspect.aspect_id)
+                ids.add(aspect.aspect_id);
+    }
+    const all = [...ids];
+    const chunk = mode === "deep" ? 1 : 3;
+    return Array.from({ length: Math.ceil(all.length / chunk) }, (_, index) => ({ key: `group-${index + 1}`, aspect_ids: all.slice(index * chunk, (index + 1) * chunk) }));
+}
+function reviewerTask(home, group) { return `Read-only independent CODE review for ${group.key}. Assess every assigned aspect exactly once: ${group.aspect_ids.join(", ")}. Read the accepted PLAN, ${path.join(home, "05-code", "stage-report.json")}, and any files needed under the bounded CODE evidence root ${path.join(home, "05-code")}. Report only material, evidenced defects: a violated obligation or rule, direct evidence, impact, and minimum required outcome. Do not report taste, cosmetics, or untargeted refactoring. Finding ids must use the unique prefix FIND-${group.key}-. Return dd-flow/code-review-result@1.`; }
+function orchestratorPrompt(context, input) { const template = read(path.join(input.run.workspace_root, ".memory-bank", "dd-flow", "vnext", "code-review.md")); const decision = path.join(input.root, "decision.json"); return ["<stage_identity>", `- RUN: ${input.run.id}`, `- root Work: ${input.rootWork.work_id}`, `- stage: ${stage}`, `- mode: ${input.mode}`, "</stage_identity>", "", "<trusted_runtime_context>", `- project root: ${input.projectRoot}`, `- immutable write workspace: ${input.run.workspace_root}`, `- stage workspace: ${input.root}`, `- bounded CODE evidence root: ${path.join(input.run.run_home_path, "05-code")}`, "CODE is already semantically verified and all declared checks passed. Do not redo CODE verification; conduct independent quality review.", "</trusted_runtime_context>", "", "<review_groups>", ...input.groups.map((group) => `- ${group.key}: ${group.aspect_ids.join(", ")}`), "</review_groups>", "", "<execution_commands>", "Each reviewer Work must run in one fresh child session. The coordinator must never claim a reviewer Work itself. Start each ready Work with its exact start_command from the work graph; it receives the task and result schema. Reviewers are read-only and must not create subagents. Do not interrupt a quiet worker.", `Ready reviewer Works: ${flowCommand(context)} work ls --run ${input.run.id} --ready --project-root ${JSON.stringify(input.projectRoot)} --json`, `Finish only after every reviewer Work settles and you have written ${decision}: ${finishCommand(context, input.run.id, input.projectRoot, decision)}`, "Reviewer results use local FIND-NNN ids. Classify them by the canonical WRK-.../FIND-NNN finding_ref returned by dd-flow. Fix P0/P1. Fix bounded safe P2 by default; defer only a legitimate P2 with a named DEF. P3 is an observation or a reasoned rejection, not automatic repair/DEF. The first Finish freezes this decision and creates one repair Work when needed. Run it, then call the same Finish command again. Review is not repeated.", "```json", JSON.stringify({ schema_id: "dd-flow/code-review-decision@2", summary: "Evidence-backed conclusion.", findings: [{ finding_ref: "WRK-001-review/FIND-001", disposition: "fix | defer | reject | duplicate", reason: "Why this classification is correct.", def_id: "DEF-0001 only for an allowed P2 deferral", duplicate_of: "canonical finding_ref only for duplicate" }] }, null, 2), "```", "</execution_commands>", "", "<stage_instructions>", template, "</stage_instructions>", ""].join("\n"); }
+function canonicalReviewEvidence(decision, reviewers) {
+    const known = new Set(canonicalCodeFindings(reviewers).map((item) => item.finding_ref));
+    const items = new Map(decision.findings.map((item) => [item.finding_ref, item]));
+    const duplicates = new Set();
+    for (const item of decision.findings.filter((entry) => entry.disposition === "duplicate")) {
+        if (!item.duplicate_of || !known.has(item.duplicate_of) || item.duplicate_of === item.finding_ref)
+            throw new AppError("review_evidence_invalid", "A duplicate finding must name a different known canonical finding", 2, { finding_ref: item.finding_ref, duplicate_of: item.duplicate_of ?? null });
+        let cursor = item;
+        const seen = new Set();
+        while (cursor?.disposition === "duplicate") {
+            if (seen.has(cursor.finding_ref))
+                throw new AppError("review_evidence_invalid", "Duplicate finding links must be acyclic", 2, { finding_ref: item.finding_ref });
+            seen.add(cursor.finding_ref);
+            cursor = cursor.duplicate_of ? items.get(cursor.duplicate_of) : undefined;
+        }
+        if (!cursor)
+            throw new AppError("review_evidence_invalid", "Duplicate finding chain must end at a decided canonical finding", 2, { finding_ref: item.finding_ref });
+        duplicates.add(item.finding_ref);
+    }
+    return {
+        decision: { ...decision, findings: decision.findings.filter((item) => !duplicates.has(item.finding_ref)) },
+        reviewers: reviewers.map((work) => { const result = readJsonString(work.result); return { ...work, result: JSON.stringify({ ...result, findings: result.findings.filter((finding) => !duplicates.has(`${work.work_id}/${finding.finding_id}`)) }) }; })
+    };
+}
+/** Freeze the complete, valid repair set before creating any repair Work. */
+export function reviewDecisionForRepair(decision, reviewers) {
+    const canonical = canonicalReviewEvidence(decision, reviewers);
+    const findings = canonicalCodeFindings(canonical.reviewers);
+    const decisions = new Map(canonical.decision.findings.map((item) => [item.finding_ref, item]));
+    for (const { finding_ref: findingRef, finding } of findings) {
+        const item = decisions.get(findingRef);
+        if (!item)
+            throw new AppError("review_evidence_invalid", "Every material CODE review finding needs one decision", 2, { finding_ref: findingRef });
+        if (["p0", "p1"].includes(finding.priority) && item.disposition !== "fix") {
+            throw new AppError("review_material_disposition_invalid", "P0/P1 CODE-REVIEW findings must be fixed, not rejected or deferred", 2, { finding_ref: findingRef, disposition: item.disposition });
+        }
+    }
+    return { ...canonical, fix_ids: canonical.decision.findings.filter((item) => item.disposition === "fix").map((item) => item.finding_ref) };
+}
+function validateDecision(context, input) {
+    const findings = canonicalCodeFindings(input.reviewers);
+    const known = new Map(findings.map((item) => [item.finding_ref, item.finding]));
+    const decisions = new Map(input.decision.findings.map((item) => [item.finding_ref, item]));
+    const repaired = new Set(input.repairs.flatMap((work) => { const result = readJsonString(work.result); return Array.isArray(result.resolved_finding_refs) ? result.resolved_finding_refs.filter((value) => typeof value === "string") : []; }));
+    for (const { finding_ref: findingRef, finding } of findings) {
+        const item = decisions.get(findingRef);
+        if (!item)
+            throw new AppError("review_evidence_invalid", "Every material CODE review finding needs one decision", 2, { finding_ref: findingRef });
+        if (["p0", "p1"].includes(finding.priority) && !(item.disposition === "fix" && repaired.has(findingRef)))
+            throw new AppError("review_unresolved_material", "P0/P1 findings must be explicitly resolved by a completed clean repair Work", 2, { finding_ref: findingRef });
+        if (item.disposition === "fix" && !repaired.has(findingRef))
+            throw new AppError("review_repair_missing", "A fixed CODE-REVIEW finding needs a completed clean repair Work that explicitly resolves it", 2, { finding_ref: findingRef });
+        if (finding.priority === "p2" && item.disposition === "defer") {
+            if (!item.def_id || !fs.existsSync(path.join(input.workspaceRoot, ".memory-bank", "defs", `${item.def_id}.md`)))
+                throw new AppError("deferral_invalid", "A deferred P2 requires a named durable DEF", 2, { finding_ref: findingRef, def_id: item.def_id ?? null });
+        }
+        if (finding.priority === "p3" && item.disposition === "defer")
+            throw new AppError("deferral_invalid", "P3 observations are not deferred as DEF", 2, { finding_ref: findingRef });
+    }
+    for (const item of input.decision.findings)
+        if (!known.has(item.finding_ref))
+            throw new AppError("review_evidence_invalid", "Decision references an unknown reviewer finding", 2, { finding_ref: item.finding_ref });
+}
+function validateReviewerResult(context, work, run) { if (!work.result)
+    throw new AppError("review_evidence_invalid", "Reviewer Work has no result", 2, { work_id: work.work_id }); const file = path.join(requireHome(run), stageDir, `${work.work_id}.result.json`); fs.writeFileSync(file, work.result); validateSchema({ schemaName: "code-review-result", file, projectRoot: run.workspace_root, ddFlowHome: context.ddFlowHome, runId: run.id }); }
+function reviewerWorks(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) => { const p = readJsonString(work.payload_json); return Boolean(p && p.kind === "code-review"); }); }
+function codeWorks(context, projectId, runId) { return context.db.all("SELECT * FROM works WHERE project_id = ? AND run_id = ? AND status = 'completed' ORDER BY created_at, work_id", [projectId, runId]).filter((work) => readJsonString(work.payload_json).schema_id === "dd-flow/code-work-packet@5" && !reviewFindingIds(work).length); }
+function reviewRepairWorks(context, projectId, runId, root) { return context.db.all("SELECT * FROM works WHERE project_id = ? AND run_id = ? ORDER BY created_at, work_id", [projectId, runId]).filter((work) => isCodeReviewStageRepair(work, root)); }
+export function isCodeReviewStageRepair(work, root) {
+    if (reviewFindingIds(work).length)
+        return true;
+    const repair = readJsonString(work.payload_json).repair;
+    if (!repair || typeof repair !== "object" || Array.isArray(repair))
+        return false;
+    const receipt = repair.failure_receipt_path;
+    if (typeof receipt !== "string" || !receipt)
+        return false;
+    const relative = path.relative(path.resolve(root), path.resolve(receipt));
+    return relative !== "" && relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+function reviewFindingIds(work) { const repair = readJsonString(work.payload_json).repair; if (!repair || typeof repair !== "object" || Array.isArray(repair))
+    return []; const ids = repair.review_finding_ids; return Array.isArray(ids) ? ids.filter((value) => typeof value === "string") : []; }
+function canonicalCodeFindings(works) { return works.flatMap((work) => readJsonString(work.result).findings.map((finding) => ({ finding_ref: `${work.work_id}/${finding.finding_id}`, finding }))); }
+function effectiveMode(run, paths) { const index = JSON.parse(run.index_json); const requested = index.settings?.code_review?.mode ?? "auto"; return requested === "auto" ? (paths.length ? "standard" : "off") : requested; }
+function changedPaths(workspaceRoot) { try {
+    return execFileSync("git", ["status", "--porcelain=v1", "--untracked-files=all"], { cwd: workspaceRoot, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).split(/\r?\n/).filter(Boolean).map((line) => line.slice(3).replace(/^.* -> /, ""));
+}
+catch {
+    return [];
+} }
+function sha256File(file) { return crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex"); }
+function stageStatus(run, name) { try {
+    return JSON.parse(run.index_json).stage_runs?.find((item) => item.stage === name)?.status ?? null;
+}
+catch {
+    return null;
+} }
+function stageStartedAt(run, fallback) { try {
+    return JSON.parse(run.index_json).stage_runs?.find((item) => item.stage === stage)?.started_at ?? fallback;
+}
+catch {
+    return fallback;
+} }
+function runRef(runId, home, file) { const relative = path.relative(home, file).split(path.sep).join("/"); return relative && !relative.startsWith("../") ? `run://${runId}/${relative}` : file; }
+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, workspace_root, run_home_path, 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; }
+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, decision) { return `${flowCommand(context)} stage finish ${runId} --stage code-review --decision-file ${JSON.stringify(decision)} --project-root ${JSON.stringify(projectRoot)} --json --progress-jsonl`; }
+function findFiles(root, name) { if (!fs.existsSync(root))
+    return []; const out = []; for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    const file = path.join(root, entry.name);
+    if (entry.isDirectory())
+        out.push(...findFiles(file, name));
+    else if (entry.name === name)
+        out.push(file);
+} return out; }
+function read(file) { return fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "Apply independent code review only; preserve accepted scope and report material evidence."; }
+function readJson(file) { return JSON.parse(fs.readFileSync(file, "utf8")); }
+function readJsonString(value) { try {
+    const valueJson = JSON.parse(value ?? "");
+    return valueJson && typeof valueJson === "object" && !Array.isArray(valueJson) ? valueJson : {};
+}
+catch {
+    return {};
+} }
+function writeReport(root, report) { writeStageReport(root, report); }