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

package/dist/services/vnext-plan.js

@@ -0,0 +1,552 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { validateCheckPlacement, validateCodeCheckCommands } from "./code-checks.js";
+import { requireProjectByRoot } from "./projects.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { advanceFlowRun, appendFlowRunTimelineEvent, attachFlowRunStage, completeFlowRunStage, getFlowRunVariables, gitFacts } from "./runs.js";
+import { validateSchema } from "./schema-validation.js";
+import { bindRunningWorkSession, bindStageCoordinatorWork, ensureWorkRegistry, refreshRunWorkProjection, validateWorkBatchFile } from "./work-registry.js";
+import { flowCommand, stagePauseCommand, stagePauseCommandTemplate } from "./stage-pause.js";
+import { assertStageStartHookEvent } from "./hooks.js";
+import { requireVnextWorkspaceRoute } from "./vnext-workspace-policy.js";
+import { readVnextSpecifyResult } from "./vnext-specify.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 { subagentCapacityKey } from "./vnext-fanout.js";
+export function isVnextPlanRun(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 startVnextPlan(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: "plan", projectRoot, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
+    const workspaceRoute = requireVnextWorkspaceRoute({ projectRoot, runId: run.id, runHome: home, workspaceRoot: run.workspace_root, stage: "plan" });
+    const root = path.join(home, vnextStageDirectory("plan"));
+    fs.mkdirSync(root, { recursive: true });
+    const protocols = protocolIds(home);
+    if (!protocols.length)
+        throw new AppError("not_found", "PLAN requires accepted PROTOCOLIZE protocols", 1);
+    if (context.db.get("SELECT 1 FROM works WHERE project_id = ? AND run_id = ? AND task = ? AND status = 'running'", [project.id, run.id, planTask]))
+        throw new AppError("invalid_work_state", "PLAN already has a running Work", 1, { run_id: run.id });
+    const now = context.now();
+    const rootWork = 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", [project.id, run.id]);
+    if (!rootWork)
+        throw new AppError("runtime_missing", "vNext RUN has no root Work", 1);
+    // Imported stage fixtures have a synthetic running root with no prior agent.
+    // Bind it on the first real stage start so its child PLAN Work has a real parent.
+    if (!context.db.get("SELECT 1 FROM work_sessions WHERE work_id = ? LIMIT 1", [rootWork.work_id])) {
+        bindRunningWorkSession(context, { workId: rootWork.work_id, hookEventId: input.hookEventId, promptPath: path.join(root, "fixture-root.prompt.md") });
+    }
+    context.db.exec("BEGIN IMMEDIATE");
+    let planWorkId;
+    try {
+        planWorkId = nextWorkId(context, project.id, "plan");
+        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)`, [planWorkId, project.id, run.id, rootWork.work_id, planTask, now, now, now]);
+        context.db.exec("COMMIT");
+    }
+    catch (error) {
+        context.db.exec("ROLLBACK");
+        throw error;
+    }
+    const template = read(path.join(projectRoot, ".memory-bank", "dd-flow", "vnext", "plan.md"));
+    // A Desktop task may start above the materialized repository.  Lifecycle
+    // prompts therefore hand agents write targets as absolute paths: relative
+    // `.memory-bank/...` paths would otherwise silently land in the parent cwd.
+    assertProtocolWorkspace(run.workspace_root, protocols);
+    const planPaths = protocols.map((id) => path.join(run.workspace_root, ".memory-bank", "protocol", id, "plan.json"));
+    const mapPaths = protocols.map((id) => `${path.join(root, id, "aspect-map.json")}`);
+    const owned = protocolOwnership(home, protocols);
+    const identities = protocols.map((protocolId) => planIdentity(home, run.id, protocolId, owned.get(protocolId) ?? []));
+    planPaths.forEach((file, index) => ensurePlanSkeleton(file, protocols[index], identities[index]));
+    mapPaths.forEach((file, index) => ensureAspectMapSkeleton(file, protocols[index], identities[index], run.workspace_root));
+    const finishCommand = `${flowCommand(context)} stage finish ${run.id} --stage plan --project-root ${JSON.stringify(projectRoot)} --json`;
+    const pauseCommand = stagePauseCommand(context, { runId: run.id, stage: "plan", workId: planWorkId, projectRoot });
+    const pauseCommandTemplate = stagePauseCommandTemplate(pauseCommand);
+    const validationCommands = protocols.flatMap((_, index) => [
+        `${flowCommand(context)} schema validate --schema vnext-protocol-plan --file ${JSON.stringify(planPaths[index])} --project-root ${JSON.stringify(run.workspace_root)} --json`,
+        `${flowCommand(context)} schema validate --schema plan-aspect-map --file ${JSON.stringify(mapPaths[index])} --project-root ${JSON.stringify(run.workspace_root)} --json`
+    ]);
+    const runVariables = getFlowRunVariables(context, { projectRoot, runId: run.id });
+    const measuredCapacity = runVariables.variables[subagentCapacityKey];
+    const capacityContext = typeof measuredCapacity === "number" && Number.isInteger(measuredCapacity) && measuredCapacity >= 0
+        ? `- The measured reviewer capacity is ${measuredCapacity}. This is a runtime fact for later PLAN-REVIEW dispatch; do not repeat the probe or invent a different value.`
+        : "- Reviewer capacity is not measured yet. PLAN must not probe or launch reviewers; PLAN-REVIEW will measure it once if review is enabled.";
+    const reviewGroupingRule = "Group only semantically compatible applicable aspects, preserving real trust, irreversible, high-risk and hard-dependency boundaries. Prefer the fewest groups that retain independent review value, normally one review wave. Put two or three compatible aspects in a group; do not create one group per aspect merely for convenience. A later PLAN-REVIEW dispatch measures current capacity once and schedules these semantic groups into waves; do not invent a capacity value here.";
+    const checkProfile = path.join(run.workspace_root, ".memory-bank", "spec", "engineering", "code-check-profile.json");
+    const prompt = ["<stage_identity>", `- RUN: ${run.id}`, `- Work: ${planWorkId}`, "- stage: plan", "</stage_identity>", "", "<trusted_runtime_context>", "These facts were collected by dd-flow. Trust them; do not repeat CLI, Git, compatibility or permission discovery.", `- Project root: ${projectRoot}`, `- Workspace: ${run.workspace_root}`, `- Stage workspace: ${root}`, `- Git: ${JSON.stringify(gitFacts(run.workspace_root))}`, capacityContext, "</trusted_runtime_context>", "", "<workspace_contract>", `- route: ${workspaceRoute.route}`, `- feature branch: ${workspaceRoute.feature_branch ?? "not applicable"}`, `- base commit: ${workspaceRoute.base_ref ?? "not applicable"}`, `- write workspace: ${run.workspace_root}`, "The CLI has verified this frozen route. All project reads and writes for PLAN and later CODE happen in the write workspace; project root is only the stable runtime identity for lifecycle commands. Do not create, switch, merge or delete branches/worktrees.", "Keep the task runner's current cwd. Use the absolute paths in this packet instead of trying to set the provisioned workspace as a tool workdir.", "</workspace_contract>", "", "<accepted_inputs>", `- ${path.join(home, "01-specify", "specify.json")}`, `- ${path.join(home, "02-protocolize", "protocolize-result.json")}`, ...protocols.map((id) => `- ${path.join(run.workspace_root, ".memory-bank", "protocol", id, "summary.md")}`), "</accepted_inputs>", "", ...(fs.existsSync(checkProfile) ? ["<code_check_policy>", "You, not the CLI, select evidence for every accepted requirement and acceptance criterion. The profile only lists reusable aliases, mandatory project policy gates and guarded raw command prefixes. Inspect relevant package/test manifests before choosing a check. Do not classify checks by weight and do not omit a needed check because it looks expensive.", fs.readFileSync(checkProfile, "utf8").trim(), "</code_check_policy>", ""] : []), "<artifacts>", "The CLI has already materialized every artifact below as a partially filled draft. Edit these files in place; do not create replacements elsewhere.", "Prefilled and CLI-owned plan fields: schema_id, plan_id, protocol_id, initial revision and source_refs.", "Prefilled and CLI-owned aspect-map fields: schema_id, protocol_id, plan_id, plan revision, catalog_ref and every catalog aspect_id.", "You own the remaining semantic fields. Empty or missing semantic values are intentional draft markers and must be completed before validation.", ...planPaths.map((value) => `- partially filled plan: ${value}`), ...mapPaths.map((value) => `- partially filled aspect map: ${value}`), "</artifacts>", "", "<output_contract>", "Complete every named plan and aspect map in place. Do not create or edit code-work-batch.json: dd-flow derives it after validation.", "The CLI owns schema_id, plan_id, protocol_id, revision and source_refs. Preserve them exactly.", "Use protocol-plan@6. Its top-level checks[] is the single check catalog. Every check has id, command, purpose, run_at and availability. available means executable now. planned means one named P* Work first creates a NEW @check/... alias: planned therefore always needs provided_by and the exact alias definition. Existing @check aliases use the profile and do not repeat a definition. Items and acceptance entries use check_refs only; never duplicate command declarations.", "For each R-* and AC-*, choose an actually relevant proof: an existing focused test, a new planned alias plus its provider Work, a project policy gate, or an honestly limited external/manual proof. Every plan item needs at least one check_ref. The CLI validates ids, provider ordering, materialization and guarded command policy; it never chooses a check for you. A provider Work may verify itself with the alias it has just created. A consumer must depend on that provider.", "Each plan item must name concrete existing source/test paths in required_read. planned_write_areas is optional: use stable component directories or files only when they help coordinate parallel Work; it is never a write allowlist. Reference every owned R-* and AC-* in one or more items; every AC-* needs an observable acceptance proof.", "For every selected check, inspect its command's launch path and the runtime entrypoints it starts. The fixture/reset process, service process and client process must observe one intended environment and data world. If a required runtime entrypoint needs a code change, make that change explicit in the Work task and its verification. Use planned_write_areas only to advertise likely concurrent overlap; do not treat it as ownership or assume another Work will repair an omitted change. If an independent infrastructure Work is clearer, plan that Work explicitly and order consumers after it.", reviewGroupingRule, "Complete compact contract and schema paths:", `- protocol plan schema: ${path.join(run.workspace_root, ".memory-bank", "dd-flow", "schemas", "vnext-protocol-plan.schema.json")}`, `- aspect map schema: ${path.join(run.workspace_root, ".memory-bank", "dd-flow", "schemas", "plan-aspect-map.schema.json")}`, "Minimal valid protocol-plan shape:", "```json", JSON.stringify(planExample(protocols[0]), null, 2), "```", "Minimal valid aspect-map shape:", "```json", JSON.stringify(aspectMapExample(protocols[0]), null, 2), "```", "</output_contract>", "", "<execution_commands>", "PLAN never launches independent reviewers or registers CODE Work.", "If PLAN needs a material user decision 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", pauseCommandTemplate, "```", "Ask the returned user_message, stop, and resume this same PLAN Work with the exact returned command.", "Validate both partially filled drafts after completing their semantic fields:", ...validationCommands.map((command) => `- ${command}`), "Finish PLAN only after all questions are resolved and both validation commands pass:", finishCommand, "The response returns the only PLAN-REVIEW start command. Follow it; do not start CODE directly.", "</execution_commands>", "", "<stage_instructions>", template, "</stage_instructions>", ""].join("\n");
+    const artifactMaterialization = { status: "materialized", completeness: "partially_filled", plan_paths: planPaths, aspect_map_paths: mapPaths, cli_owned_plan_fields: ["schema_id", "plan_id", "protocol_id", "revision", "source_refs"], cli_owned_aspect_map_fields: ["schema_id", "protocol_id", "plan_id", "plan_revision", "catalog_ref", "aspects[].aspect_id"], validation_commands: validationCommands };
+    const promptPath = path.join(root, "stage-prompt.md");
+    fs.writeFileSync(promptPath, prompt);
+    const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
+    fs.writeFileSync(path.join(root, "work-context.json"), JSON.stringify({ schema_id: "dd-flow/work-context@1", system: { run_id: run.id, work_id: planWorkId, stage: "plan" }, workspace: { project_root: projectRoot, workspace_root: run.workspace_root, stage_root: root }, artifacts: artifactMaterialization, input: { protocols, owned_obligations: Object.fromEntries(owned) } }, null, 2));
+    const binding = bindStageCoordinatorWork(context, { workId: planWorkId, hookEventId: input.hookEventId, stage: "plan", promptPath, resultPath: path.join(root, "stage-report.json"), ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
+    attachFlowRunStage(context, { projectRoot, runId: run.id, stage: "plan", dir: "03-plan", status: "running", dataSchemaId: "dd-flow/protocol-plan@6" });
+    const workSessionId = String(binding.work_session_id);
+    const sessionId = String(binding.session_id);
+    refreshRunWorkProjection(context, project.id, run.id);
+    appendFlowRunTimelineEvent(context, project.id, run.id, { type: "work_session_started", stage: "plan", work_id: planWorkId, id: workSessionId, session_id: sessionId });
+    return { ok: true, run_id: run.id, work_id: planWorkId, id: workSessionId, artifact_materialization: artifactMaterialization, worker_prompt_markdown: fs.readFileSync(promptPath, "utf8"), prompt_path: promptPath, next_command: finishCommand, ...(externalContext ? { external_context: externalContext } : {}) };
+}
+export function finishVnextPlan(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, "03-plan");
+    requireVnextWorkspaceRoute({ projectRoot, runId: run.id, runHome: home, workspaceRoot: run.workspace_root, stage: "plan" });
+    const protocols = protocolIds(home);
+    if (!protocols.length)
+        throw new AppError("not_found", "PLAN requires accepted PROTOCOLIZE protocols", 1);
+    assertProtocolWorkspace(run.workspace_root, protocols);
+    const planFiles = protocols.map((id) => path.join(run.workspace_root, ".memory-bank", "protocol", id, "plan.json"));
+    const mapFiles = protocols.map((id) => path.join(root, id, "aspect-map.json"));
+    const batch = path.join(root, "code-work-batch.json");
+    const failures = validateVnextPlanArtifacts(context, { projectRoot, workspaceRoot: run.workspace_root, runId: run.id, home, protocols });
+    if (failures.length)
+        throw new AppError("validation", "PLAN artifacts have validation errors", 2, { errors: failures });
+    const work = context.db.get("SELECT work_id FROM works WHERE project_id = ? AND run_id = ? AND task = ? AND status = 'running' ORDER BY created_at DESC LIMIT 1", [project.id, run.id, planTask]);
+    if (!work)
+        throw new AppError("invalid_work_state", "PLAN has no running Work", 1);
+    const now = context.now();
+    const batchChecksum = checksum(batch);
+    context.db.run("UPDATE works SET status = 'completed', result = ?, completed_at = ?, updated_at = ? WHERE work_id = ?", ["PLAN accepted; awaiting PLAN-REVIEW", now, now, work.work_id]);
+    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", [work.work_id]);
+    if (!workSession?.session_id)
+        throw new AppError("trusted_session_binding_required", "PLAN finish requires its bound Agent WorkSession", 1, { work_id: work.work_id });
+    context.db.run("UPDATE work_sessions SET status = 'completed', result_path = ?, updated_at = ?, completed_at = ? WHERE id = ?", [path.join(root, "stage-report.json"), now, now, workSession.id]);
+    refreshRunWorkProjection(context, project.id, run.id);
+    const reviewCommand = `${flowCommand(context)} stage start ${run.id} --stage plan-review --project-root ${JSON.stringify(projectRoot)} --json`;
+    const report = { schema_id: "dd-flow/stage-report@1", run_id: run.id, stage: "plan", generated_at: now, verdict: "done", semantic: { result: `Accepted ${protocols.length} executable PLAN artifact${protocols.length === 1 ? "" : "s"}.`, acceptance: protocols, changed_files: [...planFiles.map((file) => path.relative(projectRoot, file)), ...mapFiles.map((file) => runRef(run.id, home, file)), runRef(run.id, home, batch)], checks: ["protocol-plan schema", "aspect-map schema", "cross-artifact references", "generated CODE batch"], evidence: [runRef(run.id, home, path.join(root, "stage-report.json"))], next_action: "start_plan_review", plans: planFiles.map((file) => path.relative(projectRoot, file)), aspect_maps: mapFiles.map((file) => runRef(run.id, home, file)), code_work_batch: runRef(run.id, home, batch), batch_checksum: batchChecksum }, mechanical: { started_at: stageStartedAt(home, now), finished_at: now, wall_clock_ms: Math.max(0, Date.parse(now) - Date.parse(stageStartedAt(home, now))), 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`, next_command: reviewCommand }, 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" } };
+    const reportJson = writeStageReport(root, report).json;
+    validateSchema({ schemaName: "stage-report", file: reportJson, projectRoot, ddFlowHome: context.ddFlowHome, runId: run.id });
+    completeFlowRunStage(context, { projectRoot, runId: run.id, stage: "plan", 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: "planned", nextAction: "start_plan_review" });
+    appendFlowRunTimelineEvent(context, project.id, run.id, { type: "plan_accepted", work_id: work.work_id, protocols, id: workSession.id, next_stage: "plan-review" });
+    return { ok: true, run_id: run.id, protocols, next_action: "start_plan_review", next_command: reviewCommand, next: { kind: "start_stage", stage: "plan-review", command: reviewCommand } };
+}
+export function validateVnextPlanArtifacts(context, input) {
+    const workspaceRoot = input.workspaceRoot ?? input.projectRoot;
+    const planFiles = input.protocols.map((id) => path.join(workspaceRoot, ".memory-bank", "protocol", id, "plan.json"));
+    const mapFiles = input.protocols.map((id) => path.join(input.home, "03-plan", id, "aspect-map.json"));
+    const batch = path.join(input.home, "03-plan", "code-work-batch.json");
+    const ownership = protocolOwnership(input.home, input.protocols);
+    const obligations = acceptedObligations(input.home);
+    const frozenDocumentBaselines = input.publishBatch === false && fs.existsSync(batch)
+        ? new Map(readJson(batch).works?.flatMap((work) => typeof work.key === "string" ? (work.document_updates ?? []).flatMap((update) => typeof update.path === "string" && (typeof update.baseline_sha256 === "string" || update.baseline_sha256 === null)
+            ? [[`${work.key}\u0000${update.path}`, update.baseline_sha256]]
+            : []) : []) ?? [])
+        : undefined;
+    const failures = [];
+    const plans = [];
+    for (const [index, file] of planFiles.entries()) {
+        const protocolId = input.protocols[index];
+        try {
+            validateSchema({ schemaName: "vnext-protocol-plan", file, projectRoot: workspaceRoot, ddFlowHome: context.ddFlowHome, runId: input.runId });
+            const value = readPlan(file);
+            assertPlanIdentity(value, planIdentity(input.home, input.runId, protocolId, ownership.get(protocolId) ?? []), file);
+            validatePlanSemantics(file, new Set(ownership.get(protocolId) ?? []), obligations);
+            validateCodeCheckCommands(workspaceRoot, value.checks.filter((check) => check.availability === "available").map((check) => check.command));
+            // Placement is a PLAN-time rule. A Work may legitimately materialize a
+            // new aggregate alias later, so rechecking against the changed profile
+            // at CODE entry would retroactively invalidate an accepted plan.
+            if (input.publishBatch !== false)
+                validateCheckPlacement(workspaceRoot, value.checks);
+            plans.push({ protocolId, file, value });
+        }
+        catch (error) {
+            failures.push(validationFailure(file, error));
+        }
+    }
+    for (const file of mapFiles) {
+        try {
+            normalizeAspectMapRefs(file, workspaceRoot, input.home, input.runId);
+            validateSchema({ schemaName: "plan-aspect-map", file, projectRoot: workspaceRoot, ddFlowHome: context.ddFlowHome });
+            validateAspectMap(file, input.protocols, workspaceRoot);
+        }
+        catch (error) {
+            failures.push(validationFailure(file, error));
+        }
+    }
+    if (!failures.length) {
+        const temporaryBatch = `${batch}.tmp-${crypto.randomUUID()}`;
+        try {
+            const projection = projectCodeWorkBatch({ home: input.home, workspaceRoot, runId: input.runId, plans, protocols: input.protocols, ...(frozenDocumentBaselines ? { frozenDocumentBaselines } : {}) });
+            validateProjectedPaths(projection, workspaceRoot, input.home, input.runId);
+            fs.writeFileSync(temporaryBatch, `${JSON.stringify(projection, null, 2)}\n`);
+            validateSchema({ schemaName: "code-work-batch", file: temporaryBatch, projectRoot: workspaceRoot, ddFlowHome: context.ddFlowHome, runId: input.runId });
+            validateWorkBatchFile(temporaryBatch);
+            if (input.publishBatch !== false) {
+                fs.renameSync(temporaryBatch, batch);
+            }
+            else if (!fs.existsSync(batch) || checksum(temporaryBatch) !== checksum(batch)) {
+                throw new AppError("stale_code_work_batch", "CODE batch no longer matches the accepted semantic PLAN", 2, { batch });
+            }
+        }
+        catch (error) {
+            failures.push(validationFailure(batch, error));
+        }
+        finally {
+            fs.rmSync(temporaryBatch, { force: true });
+        }
+    }
+    return failures;
+}
+/** CODE entry validates the same PLAN closure without changing an accepted batch. */
+export function validateVnextCodeHandoff(context, input) {
+    return validateVnextPlanArtifacts(context, {
+        ...input,
+        protocols: protocolIds(input.home),
+        publishBatch: false
+    });
+}
+const planTask = "Produce accepted plan.json and aspect-map.json artifacts.";
+function planExample(protocolId) { return { schema_id: "dd-flow/protocol-plan@6", plan_id: "PLAN-001", protocol_id: protocolId, revision: 1, title: "Example", summary: "A compact executable plan.", source_refs: [{ kind: "specify", id: "SPECIFY", path: "run://RUN-000/01-specify/specify.json", requirement_ids: ["R-001", "AC-001"] }], goal: { outcome: "Deliver the accepted behavior.", constraints: ["Keep the accepted scope."], non_goals: [] }, assessment: { scope_breadth: { level: "narrow", surfaces: ["one surface"], reason: "One vertical slice." }, solution_novelty: { level: "established", surfaces: ["existing pattern"], reason: "Reuse project practice." }, solution_uncertainty: { level: "low", surfaces: ["known behavior"], reason: "No open technical question." }, failure_impact: { level: "low", surfaces: ["local feature"], reason: "Reversible local change." }, selected_depth: "compact_plan", depth_trigger: "none" }, decisions: [], document_updates: [], checks: [{ id: "CHK-P1-TEST", command: "pnpm test", purpose: "Proves the changed behavior.", run_at: "work", availability: "available" }], items: [{ id: "P1", title: "Implement behavior", summary: "Change the owning surface.", details: "Follow the accepted requirement and project conventions.", depends_on: [], requirement_refs: ["R-001", "AC-001"], semantic_spine: { user_outcome: "The requested behavior is available.", component_responsibility: "Own the behavior.", must_preserve: ["Existing behavior."], non_goals: [], acceptance_contribution: "Makes AC-001 observable." }, execution_context: { required_read: ["apps/api/src/example.ts"], discovery_boundary: ["Related tests only."], planned_write_areas: ["apps/api/src/"], stop_conditions: ["Stop if accepted scope conflicts with current truth."] }, verification: { check_refs: ["CHK-P1-TEST"] } }], acceptance: [{ criterion_id: "AC-001", plan_item_ids: ["P1"], changed_surfaces: ["apps/api/src/example.ts"], path: "Exercise the accepted user path.", environment: "Local test environment.", fixtures: [], cleanup: "No persistent fixture.", check_refs: ["CHK-P1-TEST"], expected_evidence: ["Focused check passes."], proof_limits: ["Manual production evidence is not claimed."], gate: "work" }] }; }
+function aspectMapExample(protocolId) { return { $schema: "plan-aspect-map.schema.json", schema_id: "dd-flow/plan-aspect-map@3", protocol_id: protocolId, plan_id: "PLAN-001", plan_revision: 1, catalog_ref: { path: ".memory-bank/dd-flow/mb-sdlc/plan-aspects/aspects" }, routing: { initial_state: "orchestrator_local", selected_route: "local_compact", reason: "One genuinely small semantic unit.", groups: [] }, review_groups: [], aspects: [{ aspect_id: "example_aspect", applicability: "not_applicable", reason: "Only an example; use the supplied real catalog.", planned_artifact_refs: [] }] }; }
+function requireRun(context, root, id) { const project = requireProjectByRoot(context, root); const run = context.db.get("SELECT id, project_id, workspace_root, run_home_path FROM runs WHERE project_id = ? AND id = ?", [project.id, id]); 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 protocolIds(home) {
+    const report = JSON.parse(fs.readFileSync(path.join(home, "02-protocolize", "stage-report.json"), "utf8"));
+    const ids = report.semantic?.acceptance;
+    if (!Array.isArray(ids) || !ids.length || !ids.every((id) => typeof id === "string" && id.startsWith("PRT-")))
+        throw new AppError("runtime_missing", "Accepted PROTOCOLIZE protocol ids are missing", 1);
+    return ids;
+}
+function assertProtocolWorkspace(workspaceRoot, protocols) {
+    for (const id of protocols) {
+        const summary = path.join(workspaceRoot, ".memory-bank", "protocol", id, "summary.md");
+        if (!fs.existsSync(summary))
+            throw new AppError("workspace_protocol_missing", "PLAN requires protocol documents in the registered RUN workspace", 1, { workspace_root: workspaceRoot, protocol_id: id, expected: summary });
+    }
+}
+function read(file) { if (!fs.existsSync(file))
+    throw new AppError("not_found", "vNext PLAN prompt is missing", 1, { file }); return fs.readFileSync(file, "utf8"); }
+function readJson(file) { return JSON.parse(fs.readFileSync(file, "utf8")); }
+function checksum(file) { return crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex"); }
+function validateAspectMap(file, protocols, projectRoot) {
+    let value;
+    try {
+        value = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        throw new AppError("schema_validation", "aspect-map.json must be valid JSON", 2, { file });
+    }
+    const map = value;
+    if (map.schema_id !== "dd-flow/plan-aspect-map@3" || typeof map.protocol_id !== "string" || !protocols.includes(map.protocol_id) || !Array.isArray(map.aspects))
+        throw new AppError("schema_validation", "aspect-map.json does not match v3 contract", 2, { file });
+    const actual = map.aspects.map((aspect) => aspect.aspect_id).filter((id) => Boolean(id));
+    if (new Set(actual).size !== actual.length)
+        throw new AppError("validation", "aspect-map has duplicate aspect_id values", 2, { file });
+    const catalog = aspectCatalog(projectRoot);
+    if (catalog.length && (catalog.length !== actual.length || catalog.some((id) => !actual.includes(id))))
+        throw new AppError("validation", "aspect-map must cover the current aspect catalog exactly once", 2, { file, missing: catalog.filter((id) => !actual.includes(id)), unknown: actual.filter((id) => !catalog.includes(id)) });
+    for (const aspect of map.aspects)
+        if (aspect.applicability === "applicable" && !aspect.reason?.trim())
+            throw new AppError("validation", "Applicable aspect needs a concrete reason", 2, { file, aspect_id: aspect.aspect_id });
+    const groups = map.routing?.groups ?? [];
+    const grouped = groups.flatMap((group) => group.aspect_ids ?? []);
+    if (new Set(grouped).size !== grouped.length || grouped.some((id) => !actual.includes(id)))
+        throw new AppError("validation", "Aspect routing groups must reference each listed aspect at most once", 2, { file });
+    if (map.routing?.selected_route === "single_wave_grouped" && !groups.length)
+        throw new AppError("validation", "single_wave_grouped requires one or more explicit groups", 2, { file });
+    if (map.routing?.selected_route === "local_compact" && groups.length)
+        throw new AppError("validation", "local_compact cannot declare delegated groups", 2, { file });
+    if (map.routing?.selected_route === "single_wave_grouped" || map.routing?.selected_route === "multi_wave_grouped")
+        for (const aspectId of grouped)
+            if (map.aspects.find((item) => item.aspect_id === aspectId)?.applicability !== "applicable")
+                throw new AppError("validation", "Grouped route may contain only applicable aspects", 2, { file, aspect_id: aspectId });
+    const applicable = map.aspects.filter((aspect) => aspect.applicability === "applicable").map((aspect) => aspect.aspect_id).sort();
+    const reviewed = (map.review_groups ?? []).flatMap((group) => group.aspect_ids ?? []).sort();
+    if (new Set(reviewed).size !== reviewed.length || applicable.length !== reviewed.length || applicable.some((id, index) => reviewed[index] !== id)) {
+        throw new AppError("validation", "review_groups must cover every applicable aspect exactly once", 2, { file, applicable, reviewed });
+    }
+}
+function aspectCatalog(projectRoot) {
+    const root = path.join(projectRoot, ".memory-bank", "dd-flow", "mb-sdlc", "plan-aspects", "aspects");
+    if (!fs.existsSync(root))
+        return [];
+    return fs.readdirSync(root).filter((name) => name.endsWith(".md") && name !== "index.md" && !name.startsWith("00-")).map((name) => name.slice(0, -3)).sort();
+}
+function stageStartedAt(home, fallback) { try {
+    const run = JSON.parse(fs.readFileSync(path.join(home, "run.json"), "utf8"));
+    return run.stage_runs?.find((item) => item.stage === "plan")?.started_at ?? fallback;
+}
+catch {
+    return fallback;
+} }
+function validationFailure(file, error) { return { file, message: error instanceof Error ? error.message : String(error), ...(error instanceof AppError ? { details: error.details } : {}) }; }
+function acceptedObligations(home) {
+    const file = path.join(home, "01-specify", "specify.json");
+    if (!fs.existsSync(file))
+        throw new AppError("runtime_missing", "PLAN requires accepted specify.json", 1, { file });
+    const result = readVnextSpecifyResult(file);
+    return new Set([...result.requirements, ...result.acceptance_criteria].map((obligation) => obligation.id));
+}
+function protocolOwnership(home, protocols) {
+    const file = path.join(home, "02-protocolize", "protocolize-result.json");
+    const result = JSON.parse(fs.readFileSync(file, "utf8"));
+    const idsByMember = new Map(result.delivery.members.map((member, index) => [member.key, protocols[index]]));
+    const output = new Map(protocols.map((protocol) => [protocol, []]));
+    for (const item of result.obligation_ownership)
+        for (const member of item.member_keys)
+            output.get(idsByMember.get(member) ?? "")?.push(item.obligation_id);
+    return output;
+}
+function planIdentity(home, runId, protocolId, owned) {
+    const specify = path.join(home, "01-specify", "specify.json");
+    return {
+        schema_id: "dd-flow/protocol-plan@6",
+        plan_id: `PLAN-${protocolId.slice(4)}`,
+        protocol_id: protocolId,
+        revision: 1,
+        source_refs: [
+            { kind: "specify", id: "SPECIFY", path: runRef(runId, home, specify), requirement_ids: [...acceptedObligations(home)].sort(), sha256: checksum(specify) },
+            { kind: "protocol", id: protocolId, path: `.memory-bank/protocol/${protocolId}/summary.md`, requirement_ids: [...owned].sort() }
+        ]
+    };
+}
+function ensurePlanSkeleton(file, protocolId, identity) {
+    if (fs.existsSync(file))
+        return;
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    writeJson(file, { ...identity, title: "", summary: "", goal: { outcome: "", constraints: [], non_goals: [] }, assessment: {}, decisions: [], document_updates: [], checks: [], items: [], acceptance: [] });
+}
+function ensureAspectMapSkeleton(file, protocolId, identity, workspaceRoot) {
+    if (fs.existsSync(file))
+        return;
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    writeJson(file, {
+        $schema: "plan-aspect-map.schema.json",
+        schema_id: "dd-flow/plan-aspect-map@3",
+        protocol_id: protocolId,
+        plan_id: identity.plan_id,
+        plan_revision: identity.revision,
+        catalog_ref: { path: ".memory-bank/dd-flow/mb-sdlc/plan-aspects/aspects" },
+        routing: { initial_state: "orchestrator_local", groups: [] },
+        review_groups: [],
+        aspects: aspectCatalog(workspaceRoot).map((aspectId) => ({ aspect_id: aspectId, planned_artifact_refs: [] }))
+    });
+}
+function readPlan(file) { return JSON.parse(fs.readFileSync(file, "utf8")); }
+function assertPlanIdentity(value, identity, file) {
+    for (const key of ["schema_id", "plan_id", "protocol_id"])
+        if (value[key] !== identity[key])
+            throw new AppError("validation", `PLAN must preserve CLI-owned ${key}`, 2, { file, expected: identity[key], actual: value[key] });
+    if (!Number.isInteger(value.revision) || value.revision < identity.revision)
+        throw new AppError("validation", "PLAN revision must not precede the CLI-issued initial revision", 2, { file, initial_revision: identity.revision, actual: value.revision });
+    if (JSON.stringify(value.source_refs) !== JSON.stringify(identity.source_refs))
+        throw new AppError("validation", "PLAN must preserve CLI-owned source_refs", 2, { file });
+}
+function normalizeAspectMapRefs(file, projectRoot, runHome, runId) {
+    const map = JSON.parse(fs.readFileSync(file, "utf8"));
+    let changed = false;
+    const normalize = (value) => {
+        if (!path.isAbsolute(value))
+            return value;
+        const source = path.resolve(value);
+        const inProject = source.startsWith(`${projectRoot}${path.sep}`);
+        const inRun = source.startsWith(`${runHome}${path.sep}`);
+        if (!inProject && !inRun)
+            throw new AppError("path_escape", "Aspect-map artifact reference must stay in the project or RUN", 2, { file, path: value });
+        changed = true;
+        return inRun ? runRef(runId, runHome, source) : path.relative(projectRoot, source);
+    };
+    if (map.catalog_ref?.path)
+        map.catalog_ref.path = normalize(map.catalog_ref.path);
+    for (const aspect of map.aspects ?? [])
+        if (Array.isArray(aspect.planned_artifact_refs))
+            aspect.planned_artifact_refs = aspect.planned_artifact_refs.map(normalize);
+    if (changed)
+        fs.writeFileSync(file, `${JSON.stringify(map, null, 2)}\n`);
+}
+function projectCodeWorkBatch(input) {
+    const obligationMap = acceptedObligationMap(input.home);
+    const orientation = projectOrientation(input.workspaceRoot);
+    const works = input.plans.flatMap(({ protocolId, file, value }) => value.items.map((item) => {
+        const workKey = `${protocolId}:${item.id}`;
+        const documentUpdates = value.document_updates.filter((entry) => entry.owner === item.id).map((entry) => { const filePath = path.join(input.workspaceRoot, entry.path); const baselineKey = `${workKey}\u0000${entry.path}`; const frozen = input.frozenDocumentBaselines; return { ...entry, baseline_sha256: frozen?.has(baselineKey) ? frozen.get(baselineKey) : (fs.existsSync(filePath) && fs.statSync(filePath).isFile() ? checksum(filePath) : null) }; });
+        const documentPaths = documentUpdates.map((entry) => entry.path);
+        const existingDocumentPaths = documentUpdates.filter((entry) => entry.action === "update").map((entry) => entry.path);
+        return ({
+            schema_id: "dd-flow/code-work-packet@5",
+            key: workKey,
+            launch_policy: "fresh_agent_required",
+            source: { plan_id: value.plan_id, protocol_id: protocolId, plan_item_id: item.id, revision: value.revision, sha256: checksum(file) },
+            task: renderCodeTask(item, value.checks),
+            semantic_spine: item.semantic_spine,
+            requirements: item.requirement_refs.map((id) => ({ id, statement: obligationMap.get(id) ?? "" })),
+            acceptance: value.acceptance.filter((entry) => entry.plan_item_ids.includes(item.id)).map(({ plan_item_ids: _ids, changed_surfaces: _surfaces, ...entry }) => entry),
+            document_updates: documentUpdates,
+            // The profile is mutable by the Work which materializes a planned alias.
+            // Give it to that provider, not to every CODE Worker: consumers already
+            // receive the resolved check declaration in their packet, while making the
+            // profile a universal input would make an otherwise accepted batch look
+            // stale as soon as its provider performs its declared work.
+            required_read: [...new Set([
+                    ...orientation,
+                    ...item.execution_context.required_read,
+                    ...existingDocumentPaths,
+                    ...(value.checks.some((check) => check.availability === "planned" && check.provided_by === item.id)
+                        && fs.existsSync(path.join(input.workspaceRoot, ".memory-bank/spec/engineering/code-check-profile.json"))
+                        ? [".memory-bank/spec/engineering/code-check-profile.json"]
+                        : [])
+                ])],
+            discovery_boundary: item.execution_context.discovery_boundary,
+            planned_write_areas: [...new Set([...item.execution_context.planned_write_areas, ...documentPaths])],
+            checks: value.checks.filter((check) => item.verification.check_refs.includes(check.id)),
+            provides_checks: value.checks.filter((check) => check.availability === "planned" && check.provided_by === item.id),
+            stop_conditions: item.execution_context.stop_conditions,
+            depends_on: item.depends_on.map((dependency) => `${protocolId}:${dependency}`),
+            result_schema: "dd-flow/code-work-result@2"
+        });
+    }));
+    const byProtocol = new Map(input.plans.map((plan) => [plan.protocolId, plan.value.items]));
+    const result = JSON.parse(fs.readFileSync(path.join(input.home, "02-protocolize", "protocolize-result.json"), "utf8"));
+    const memberToProtocol = new Map(result.delivery.members.map((member, index) => [member.key, input.protocols[index]]));
+    for (const member of result.delivery.members) {
+        const protocolId = memberToProtocol.get(member.key);
+        const local = byProtocol.get(protocolId) ?? [];
+        const roots = local.filter((item) => item.depends_on.length === 0);
+        for (const blockedMember of member.blocked_by) {
+            const predecessor = memberToProtocol.get(blockedMember);
+            const predecessorItems = predecessor ? byProtocol.get(predecessor) ?? [] : [];
+            const dependedOn = new Set(predecessorItems.flatMap((item) => item.depends_on));
+            const terminals = predecessorItems.filter((item) => !dependedOn.has(item.id));
+            for (const root of roots) {
+                const work = works.find((item) => item.key === `${protocolId}:${root.id}`);
+                work.depends_on.push(...terminals.map((item) => `${predecessor}:${item.id}`));
+                work.depends_on = [...new Set(work.depends_on)].sort();
+            }
+        }
+    }
+    const ordered = [...works].sort((a, b) => a.key.localeCompare(b.key));
+    return { schema_id: "dd-flow/code-work-batch@5", sources: input.plans.map(({ protocolId, file, value }) => ({ plan_id: value.plan_id, protocol_id: protocolId, revision: value.revision, sha256: checksum(file) })), works: ordered };
+}
+function renderCodeTask(item, catalog) { const checks = catalog.filter((check) => item.verification.check_refs.includes(check.id)); return [item.title, item.summary, item.details, `Preserve: ${item.semantic_spine.must_preserve.join("; ")}`, `Checks: ${checks.map((check) => `${check.id}:${check.command}`).join("; ")}`, `Stop: ${item.execution_context.stop_conditions.join("; ")}`].join("\n\n"); }
+function validateProjectedPaths(batch, workspaceRoot, home, runId) {
+    for (const work of batch.works) {
+        for (const write of work.planned_write_areas)
+            assertProjectPath(write, workspaceRoot, "planned_write_areas");
+        for (const read of work.required_read) {
+            const existing = resolvePortablePath(read, workspaceRoot, home, runId);
+            if (existing && fs.existsSync(existing))
+                continue;
+            throw new AppError("validation", "CODE required_read path must exist at Work entry", 2, { work: work.key, read_path: read });
+        }
+    }
+}
+function acceptedObligationMap(home) {
+    const specify = readVnextSpecifyResult(path.join(home, "01-specify", "specify.json"));
+    const effective = new Map([...specify.requirements, ...specify.acceptance_criteria].map((item) => [item.id, item.statement]));
+    const protocolize = JSON.parse(fs.readFileSync(path.join(home, "02-protocolize", "protocolize-result.json"), "utf8"));
+    for (const amendment of protocolize.obligation_amendments ?? [])
+        effective.set(amendment.target_id, amendment.replacement);
+    return effective;
+}
+function projectOrientation(workspaceRoot) {
+    return [".memory-bank/index.md", ".memory-bank/spec/engineering/index.md", ".memory-bank/spec/engineering/coding-standards.md"]
+        .filter((item) => fs.existsSync(path.join(workspaceRoot, item)));
+}
+function assertProjectPath(value, workspaceRoot, label) {
+    if (!value || path.isAbsolute(value) || value.startsWith("run://") || value.split(/[\\/]/).includes(".."))
+        throw new AppError("path_escape", `${label} must be a project-relative path`, 2, { path: value });
+    const resolved = path.resolve(workspaceRoot, value);
+    if (!resolved.startsWith(`${path.resolve(workspaceRoot)}${path.sep}`))
+        throw new AppError("path_escape", `${label} escapes the project workspace`, 2, { path: value });
+}
+function resolvePortablePath(value, workspaceRoot, home, runId) {
+    if (value.startsWith("run://")) {
+        const prefix = `run://${runId}/`;
+        if (!value.startsWith(prefix) || value.slice(prefix.length).split("/").includes(".."))
+            throw new AppError("path_escape", "RUN read path must stay in this RUN", 2, { path: value });
+        return path.join(home, value.slice(prefix.length));
+    }
+    assertProjectPath(value, workspaceRoot, "required_read");
+    return path.join(workspaceRoot, value);
+}
+function writeJson(file, value) { const temporary = `${file}.${crypto.randomUUID()}.tmp`; fs.writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`); fs.renameSync(temporary, file); }
+function runRef(runId, runHome, file) { return `run://${runId}/${path.relative(runHome, file).split(path.sep).join("/")}`; }
+function validatePlanSemantics(file, ownedRefs, acceptedRefs) {
+    const plan = readPlan(file);
+    const items = plan.items ?? [];
+    const ids = new Set(items.map((item) => item.id).filter((id) => Boolean(id)));
+    if (ids.size !== items.length)
+        throw new AppError("validation", "PLAN item ids must be unique", 2, { file });
+    const invalidDocumentOwners = (plan.document_updates ?? []).filter((entry) => !ids.has(entry.owner));
+    if (invalidDocumentOwners.length)
+        throw new AppError("document_update_owner_invalid", "Every PLAN document update must have exactly one existing PLAN item id as owner", 2, { file, invalid: invalidDocumentOwners.map((entry) => ({ path: entry.path, owner: entry.owner })), allowed_owners: [...ids].sort() });
+    const realized = new Set();
+    const checks = new Map();
+    for (const check of plan.checks ?? []) {
+        if (checks.has(check.id))
+            throw new AppError("validation", "PLAN check ids must be unique", 2, { file, check_id: check.id });
+        if (check.availability === "planned" && (!check.provided_by || !ids.has(check.provided_by)))
+            throw new AppError("planned_check_provider_missing", "A planned check must name a PLAN item that provides it", 2, { file, check_id: check.id, provided_by: check.provided_by ?? null });
+        if (check.availability === "planned" && !check.command.startsWith("@check/"))
+            throw new AppError("planned_check_requires_alias", "A planned check must declare a new @check/... alias", 2, { file, check_id: check.id, command: check.command });
+        if (check.availability === "planned" && !check.definition)
+            throw new AppError("planned_check_definition_missing", "A planned check must declare its exact alias definition", 2, { file, check_id: check.id });
+        checks.set(check.id, check);
+    }
+    const ancestors = (itemId, seen = new Set()) => {
+        for (const dependency of items.find((item) => item.id === itemId)?.depends_on ?? [])
+            if (!seen.has(dependency)) {
+                seen.add(dependency);
+                ancestors(dependency, seen);
+            }
+        return seen;
+    };
+    for (const item of items) {
+        for (const dependency of item.depends_on ?? [])
+            if (!ids.has(dependency))
+                throw new AppError("validation", "PLAN item depends_on references an unknown item", 2, { file, item: item.id, dependency });
+        for (const ref of item.requirement_refs ?? []) {
+            if (!acceptedRefs.has(ref))
+                throw new AppError("validation", "PLAN item references an unknown SPECIFY obligation", 2, { file, item: item.id, ref });
+            if (!ownedRefs.has(ref))
+                throw new AppError("validation", "PLAN item references an obligation owned by another protocol", 2, { file, item: item.id, ref });
+            realized.add(ref);
+        }
+        for (const checkId of item.verification.check_refs ?? []) {
+            const check = checks.get(checkId);
+            if (!check)
+                throw new AppError("check_reference_unknown", "PLAN item references an unknown check", 2, { file, item: item.id, check_id: checkId });
+            if (check.availability === "planned" && check.provided_by !== item.id && !ancestors(item.id).has(check.provided_by))
+                throw new AppError("check_consumer_not_ordered_after_provider", "A Work may consume a planned check only after its provider", 2, { file, item: item.id, check_id: checkId, provider: check.provided_by });
+        }
+    }
+    const visiting = new Set();
+    const done = new Set();
+    const byId = new Map(items.map((item) => [item.id, item]));
+    const visit = (id) => { if (done.has(id))
+        return; if (visiting.has(id))
+        throw new AppError("validation", "PLAN item dependencies contain a cycle", 2, { file, item: id }); visiting.add(id); for (const dependency of byId.get(id)?.depends_on ?? [])
+        visit(dependency); visiting.delete(id); done.add(id); };
+    for (const id of ids)
+        visit(id);
+    for (const acceptance of plan.acceptance ?? []) {
+        if (!acceptance.criterion_id || !acceptance.criterion_id.startsWith("AC-") || !ownedRefs.has(acceptance.criterion_id))
+            throw new AppError("validation", "PLAN acceptance references an AC-* owned by this protocol", 2, { file, criterion_id: acceptance.criterion_id });
+        for (const id of acceptance.plan_item_ids ?? [])
+            if (!ids.has(id))
+                throw new AppError("validation", "PLAN acceptance references an unknown item", 2, { file, criterion_id: acceptance.criterion_id, plan_item_id: id });
+        for (const id of acceptance.check_refs ?? [])
+            if (!checks.has(id))
+                throw new AppError("check_reference_unknown", "PLAN acceptance references an unknown check", 2, { file, criterion_id: acceptance.criterion_id, check_id: id });
+    }
+    for (const obligation of ownedRefs)
+        if (!realized.has(obligation))
+            throw new AppError("validation", "Every protocol-owned obligation must be realized by a PLAN item", 2, { file, obligation_id: obligation });
+    for (const obligation of [...ownedRefs].filter((id) => id.startsWith("AC-")))
+        if (!plan.acceptance.some((acceptance) => acceptance.criterion_id === obligation))
+            throw new AppError("validation", "Every owned AC-* needs an observable PLAN acceptance entry", 2, { file, criterion_id: obligation });
+}