@deksden-com/dd-flow-cli 0.9.0-beta.0 → 0.9.0-beta.7

package/dist/services/vnext-plan.js

@@ -2,7 +2,7 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { AppError } from "../shared/errors.js";
-import { validateCheckDeclaration, validateCheckPlacement, validateCodeCheckCommands } from "./code-checks.js";
+import { effectiveCheckDeclarations, readCodeCheckProfile, validateCheckDeclaration, 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";
@@ -29,13 +29,18 @@ export function startVnextPlan(context, input) {
     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);
+    // Static inputs are checked before PLAN creates a Work or materializes a
+    // draft. A rejected start is therefore side-effect free and safe to retry.
+    const template = read(path.join(projectRoot, ".memory-bank", "dd-flow", "vnext", "plan.md"));
+    assertProtocolWorkspace(run.workspace_root, protocols);
+    const { profile: codeCheckProfile } = readCodeCheckProfile(run.workspace_root);
     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 root = path.join(home, vnextStageDirectory("plan"));
+    fs.mkdirSync(root, { recursive: true });
     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)
@@ -56,11 +61,9 @@ export function startVnextPlan(context, input) {
         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);
@@ -76,12 +79,19 @@ export function startVnextPlan(context, input) {
     ]);
     const runVariables = getFlowRunVariables(context, { projectRoot, runId: run.id });
     const measuredCapacity = runVariables.variables[subagentCapacityKey];
+    const mergeRequired = runEndsAtMerge(context, projectRoot, run.id);
     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. Every semantic @check alias, including an existing one, repeats its exact accepted profile command in definition so later stages can detect drift. 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 policyMergeAliases = codeCheckProfile?.mandatory_by_gate.merge ?? [];
+    const mergeContract = mergeRequired
+        ? ["<merge_gate_contract>", ...(policyMergeAliases.length
+                ? [`This RUN must reach MERGE. Project policy already supplies the mandatory merge gate${policyMergeAliases.length === 1 ? "" : "s"}: ${policyMergeAliases.join(", ")}. Do not duplicate them in semantic checks[]. Add another merge check only when the task genuinely needs additional evidence.`]
+                : ["This RUN must reach MERGE and project policy supplies no merge gate. Select at least one real top-level checks[] entry with run_at: merge. It may use an existing project alias or a planned alias materialised by a named P* provider Work. This is a planning obligation: do not defer it to CODE-REVIEW or MERGE."]), "The CLI validates the effective merge gate but never invents one or migrates an incompatible project policy.", "</merge_gate_contract>", ""]
+        : [];
+    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>", ""] : []), ...mergeContract, "<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. Every semantic @check alias, including an existing one, repeats its exact accepted profile command in definition so later stages can detect drift. 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);
@@ -177,6 +187,15 @@ export function validateVnextPlanArtifacts(context, input) {
             failures.push(validationFailure(file, error));
         }
     }
+    if (!failures.length) {
+        try {
+            validatePsetCheckIdentity(plans);
+            validateRequiredMergeGate(context, input, plans);
+        }
+        catch (error) {
+            failures.push(validationFailure(batch, error));
+        }
+    }
     if (!failures.length) {
         const temporaryBatch = `${batch}.tmp-${crypto.randomUUID()}`;
         try {
@@ -285,7 +304,7 @@ function stageStartedAt(home, fallback) { try {
 catch {
     return fallback;
 } }
-function validationFailure(file, error) { return { file, message: error instanceof Error ? error.message : String(error), ...(error instanceof AppError ? { details: error.details } : {}) }; }
+function validationFailure(file, error) { return { file, message: error instanceof Error ? error.message : String(error), ...(error instanceof AppError ? { code: error.code, details: error.details } : {}) }; }
 function acceptedObligations(home) {
     const file = path.join(home, "01-specify", "specify.json");
     if (!fs.existsSync(file))
@@ -395,6 +414,7 @@ function projectCodeWorkBatch(input) {
             // stale as soon as its provider performs its declared work.
             required_read: [...new Set([
                     ...orientation,
+                    path.relative(input.workspaceRoot, file).split(path.sep).join("/"),
                     ...item.execution_context.required_read,
                     ...existingDocumentPaths,
                     ...(value.checks.some((check) => check.availability === "planned" && check.provided_by === item.id)
@@ -547,9 +567,14 @@ function validatePlanSemantics(file, ownedRefs, acceptedRefs) {
         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))
+        for (const id of acceptance.check_refs ?? []) {
+            const check = checks.get(id);
+            if (!check)
                 throw new AppError("check_reference_unknown", "PLAN acceptance references an unknown check", 2, { file, criterion_id: acceptance.criterion_id, check_id: id });
+            for (const itemId of acceptance.plan_item_ids ?? [])
+                if (check.availability === "planned" && check.provided_by !== itemId && !ancestors(itemId).has(check.provided_by))
+                    throw new AppError("check_consumer_not_ordered_after_provider", "Acceptance may consume a planned check only after its provider", 2, { file, criterion_id: acceptance.criterion_id, item: itemId, check_id: id, provider: check.provided_by });
+        }
     }
     for (const obligation of ownedRefs)
         if (!realized.has(obligation))
@@ -558,3 +583,26 @@ function validatePlanSemantics(file, ownedRefs, acceptedRefs) {
         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 });
 }
+function validatePsetCheckIdentity(plans) {
+    const owners = new Map();
+    for (const plan of plans)
+        for (const check of plan.value.checks) {
+            const prior = owners.get(check.id);
+            if (prior)
+                throw new AppError("duplicate_pset_check_id", "PLAN check ids must be unique across the whole PSET", 2, { check_id: check.id, protocols: [prior, plan.protocolId] });
+            owners.set(check.id, plan.protocolId);
+        }
+}
+function runEndsAtMerge(context, projectRoot, runId) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(projectRoot));
+    const row = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [project.id, runId]);
+    return JSON.parse(row?.index_json ?? "{}").execution_profile?.settings?.stop_target === "merge_completed";
+}
+function validateRequiredMergeGate(context, input, plans) {
+    if (!runEndsAtMerge(context, input.projectRoot, input.runId))
+        return;
+    const declared = plans.flatMap(({ value }) => value.checks);
+    if (effectiveCheckDeclarations(input.workspaceRoot ?? input.projectRoot, declared, ["merge"]).length === 0) {
+        throw new AppError("merge_gate_plan_missing", "PLAN for a RUN ending in MERGE must declare at least one semantic or project-policy merge check", 2, { run_id: input.runId });
+    }
+}

package/dist/services/work-registry.js

@@ -4,12 +4,14 @@ import path from "node:path";
 import { AppError } from "../shared/errors.js";
 import { findRecentMatchingHookEvent, claimStageStartHookEvent, claimWorkStartHookEvent, hookSessionIdentity, workStartMatchKey } from "./hooks.js";
 import { validateSchema } from "./schema-validation.js";
-import { resolveProjectRoot, resolveRunReferences, writeJsonAtomic } from "../storage/paths.js";
+import { resolveProjectRoot, resolveRunReferences } from "../storage/paths.js";
 import { refreshRunSessionProjection } from "./run-projection.js";
-import { readCodeCheckProfile, runCodeChecks } from "./code-checks.js";
+import { readCodeCheckProfile, runCodeChecks, workspaceFingerprint } from "./code-checks.js";
 import { nextWorkId, nextWorkIds } from "./ids.js";
 import { appendFlowRunTimelineEvent } from "./runs.js";
 import { flowCommand } from "./stage-pause.js";
+import { assertPortableArtifactRef } from "./portable-refs.js";
+import { publicSessionIdentity } from "./session-identity.js";
 const workColumns = "work_id, project_id, run_id, parent_work_id, task, launch_policy, result_schema, payload_json, depends_on_json, status, result, created_at, started_at, updated_at, completed_at";
 export function ensureWorkRegistry(context) { context.db.exec("SELECT 1 FROM works LIMIT 1"); context.db.exec("SELECT 1 FROM work_sessions LIMIT 1"); }
 export function createChildWork(context, input) {
@@ -111,7 +113,7 @@ export function listWorks(context, input) {
             return { ...work, payload: parsePayload(work), payload_json: undefined, depends_on: parseDependencies(work), ready: isReadyNow, ...(isReadyNow ? { start_command: workStartCommand(context, work) } : {}), ...(input.includeResults ? {} : { result: undefined }) };
         }) };
 }
-export function showWork(context, id) { const work = requireWork(context, id); const sessions = context.db.all("SELECT id, work_id, session_id, hook_event_id, status, prompt_path, result_path, created_at, completed_at FROM work_sessions WHERE work_id = ? ORDER BY created_at", [work.work_id]); return { work: { ...work, short_id: shortWorkId(work.work_id), payload: parsePayload(work), payload_json: undefined, depends_on: parseDependencies(work), sessions } }; }
+export function showWork(context, id) { const work = requireWork(context, id); const sessions = context.db.all("SELECT ws.id, ws.work_id, ws.session_id, ws.hook_event_id, ws.status, ws.prompt_path, ws.result_path, ws.created_at, ws.completed_at, s.harness AS harness_id, COALESCE(s.provider_session_id, s.session_id) AS native_session_id FROM work_sessions ws LEFT JOIN sessions s ON s.project_id = ? AND s.session_id = ws.session_id WHERE ws.work_id = ? ORDER BY ws.created_at", [work.project_id, work.work_id]); return { work: { ...work, short_id: shortWorkId(work.work_id), payload: parsePayload(work), payload_json: undefined, depends_on: parseDependencies(work), sessions: sessions.map(({ session_id, harness_id, native_session_id, ...session }) => ({ ...session, ...(harness_id && native_session_id ? { session: publicSessionIdentity({ harness: harness_id, provider_session_id: native_session_id, session_id }) } : {}) })) } }; }
 export function mutateWorkDeps(context, input) {
     const work = requireWork(context, input.workId);
     if (input.action === "list")
@@ -262,6 +264,17 @@ export function startBoundWork(context, work, run, identity, hookEventId) {
     fs.mkdirSync(directory, { recursive: true });
     const promptPath = path.join(directory, "prompt.md");
     const resultPath = path.join(directory, "result.json");
+    const contextPath = path.join(directory, "context.json");
+    const dependencyResults = parseDependencies(work).map((dependency) => context.db.get("SELECT work_id, result FROM works WHERE work_id = ?", [dependency])).filter(Boolean);
+    const prompt = renderWorkerPrompt(context, work, run, dependencyResults);
+    const payload = parsePayload(work);
+    const readOnly = payload?.read_only === true;
+    const workContext = { schema_id: "dd-flow/work-context@1", run_id: work.run_id, work_id: work.work_id, parent_work_id: work.parent_work_id, project_root: run.project_root, workspace_root: run.workspace_root, run_root: requireRunHome(run), depends_on: parseDependencies(work), launch_policy: work.launch_policy, result_schema: work.result_schema, read_only: readOnly, ...(readOnly ? { workspace_fingerprint: workspaceFingerprint(run.workspace_root) } : {}) };
+    const token = crypto.randomUUID();
+    const promptCandidate = `${promptPath}.${token}.tmp`;
+    const contextCandidate = `${contextPath}.${token}.tmp`;
+    fs.writeFileSync(promptCandidate, prompt);
+    fs.writeFileSync(contextCandidate, `${JSON.stringify(workContext, null, 2)}\n`);
     context.db.exec("BEGIN IMMEDIATE");
     try {
         bindSession(context, work, run, identity, now);
@@ -271,23 +284,23 @@ export function startBoundWork(context, work, run, identity, hookEventId) {
         if (claimed.changes !== 1)
             throw new AppError("conflict", "Work was claimed concurrently", 1, { work_id: work.work_id });
         context.db.run(`INSERT INTO work_sessions (id, work_id, session_id, hook_event_id, status, prompt_path, result_path, created_at, updated_at, completed_at) VALUES (?, ?, ?, ?, 'running', ?, ?, ?, ?, NULL)`, [linkId, work.work_id, identity.sessionId, hookEventId, promptPath, resultPath, now, now]);
+        fs.renameSync(promptCandidate, promptPath);
+        fs.renameSync(contextCandidate, contextPath);
         context.db.exec("COMMIT");
     }
     catch (error) {
         context.db.exec("ROLLBACK");
+        fs.rmSync(promptCandidate, { force: true });
+        fs.rmSync(contextCandidate, { force: true });
         throw error;
     }
-    const dependencyResults = parseDependencies(work).map((dependency) => context.db.get("SELECT work_id, result FROM works WHERE work_id = ?", [dependency])).filter(Boolean);
-    const prompt = renderWorkerPrompt(context, work, run, dependencyResults, resultPath);
-    writeJsonAtomic(path.join(directory, "context.json"), { schema_id: "dd-flow/work-context@1", run_id: work.run_id, work_id: work.work_id, parent_work_id: work.parent_work_id, project_root: run.project_root, workspace_root: run.workspace_root, run_root: requireRunHome(run), depends_on: parseDependencies(work), launch_policy: work.launch_policy, result_schema: work.result_schema });
-    fs.writeFileSync(promptPath, prompt);
     refreshRunWorkProjection(context, work.project_id, work.run_id);
-    return { ok: true, work_id: work.work_id, work_session_id: linkId, worker_prompt_markdown: prompt, prompt_path: promptPath, session_binding: { source: "PreToolUse", session_id: identity.sessionId } };
+    return { ok: true, work_id: work.work_id, work_session_id: linkId, worker_prompt_markdown: prompt, prompt_path: promptPath, session_binding: { source: "PreToolUse", session: { harness_id: identity.harness, session_id: identity.nativeSessionId } } };
 }
 export function finishWork(context, id, result, progress) { return settle(context, id, "completed", result, progress); }
 /** Structured fan-in closes a parent after its Session was handed to a child. */
 export function finishFanInWork(context, id, result) { const work = requireWork(context, id); if (work.status !== "running")
-    throw new AppError("invalid_work_state", "Fan-in Work is not running", 2, { work_id: work.work_id, status: work.status }); if (context.db.get("SELECT 1 FROM works WHERE parent_work_id = ? AND status IN ('created','running') LIMIT 1", [work.work_id]))
+    throw new AppError("invalid_work_state", "Fan-in Work is not running", 2, { work_id: work.work_id, status: work.status }); if (context.db.get("SELECT 1 FROM works WHERE parent_work_id = ? AND status IN ('created','running','paused') LIMIT 1", [work.work_id]))
     throw new AppError("active_child_work", "Fan-in Work still has active children", 2, { work_id: work.work_id }); const now = context.now(); context.db.run("UPDATE works SET status = 'completed', result = ?, completed_at = ?, updated_at = ? WHERE work_id = ?", [result, now, now, work.work_id]); context.db.run("UPDATE work_sessions SET status = 'completed', completed_at = COALESCE(completed_at, ?), updated_at = ? WHERE work_id = ? AND status = 'running'", [now, now, work.work_id]); refreshRunWorkProjection(context, work.project_id, work.run_id); appendFlowRunTimelineEvent(context, work.project_id, work.run_id, { type: "work_completed", work_id: work.work_id, fan_in: true }); return { ok: true, work_id: work.work_id, status: "completed", fan_in: true }; }
 export function failWork(context, id, reason) { return settle(context, id, "failed", reason); }
 export function cancelWork(context, id, reason) { return settle(context, id, "cancelled", reason); }
@@ -302,7 +315,7 @@ async function settle(context, id, status, result, progress) {
     id = work.work_id;
     if (work.status !== "running" && !(status === "cancelled" && work.status === "created"))
         throw new AppError("invalid_work_state", "Work is not running", 2, { status: work.status });
-    if (status === "completed" && context.db.get("SELECT 1 FROM works WHERE parent_work_id = ? AND status IN ('created', 'running') LIMIT 1", [id]))
+    if (status === "completed" && context.db.get("SELECT 1 FROM works WHERE parent_work_id = ? AND status IN ('created', 'running', 'paused') LIMIT 1", [id]))
         throw new AppError("active_child_work", "Work cannot complete while a child Work is active", 2, { work_id: id });
     const run = requireRun(context, work.project_id, work.run_id);
     const link = context.db.get("SELECT id, work_id, session_id, hook_event_id, status, prompt_path, result_path, created_at, completed_at FROM work_sessions WHERE work_id = ? AND status = 'running' ORDER BY created_at DESC LIMIT 1", [id]);
@@ -311,7 +324,14 @@ async function settle(context, id, status, result, progress) {
     let receipts = [];
     let coordinationDrift = [];
     if (status === "completed") {
-        validateWorkResult(work, result, run.project_root, run.workspace_root, run.id, link?.result_path ?? null);
+        if (parsePayload(work)?.read_only === true) {
+            const contextFile = link ? path.join(path.dirname(link.prompt_path), "context.json") : "";
+            const baseline = contextFile && fs.existsSync(contextFile) ? JSON.parse(fs.readFileSync(contextFile, "utf8")).workspace_fingerprint : null;
+            const current = workspaceFingerprint(run.workspace_root);
+            if (typeof baseline !== "string" || baseline !== current)
+                throw new AppError("read_only_work_mutated_workspace", "Read-only Work changed the accepted workspace", 2, { work_id: work.work_id, baseline, current });
+        }
+        validateWorkResult(work, result, run.project_root, run.workspace_root, requireRunHome(run), run.id, link?.result_path ?? null);
         const packet = codePacket(work);
         if (packet) {
             // CODE packets are projected from a PLAN that already validated this
@@ -362,21 +382,33 @@ function bindSession(context, work, run, identity, now) {
     const inferredParentSession = work.parent_work_id
         ? context.db.get("SELECT session_id FROM work_sessions WHERE work_id = ? ORDER BY created_at DESC LIMIT 1", [work.parent_work_id])?.session_id ?? null
         : priorWorkSession && priorWorkSession !== identity.sessionId ? priorWorkSession : null;
-    const parentSession = identity.parentSessionId ?? inferredParentSession;
+    // Work ancestry and provider-tree containment are different relations. An
+    // isolated worker is logically a child Work but physically a provider root.
+    const parentSession = inferredParentSession ?? identity.parentSessionId;
+    const providerParentSession = identity.parentSessionId;
     if (work.parent_work_id && !parentSession)
         throw new AppError("parent_session_required", "Child Work requires a confirmed parent Work/Session link", 1, { work_id: work.work_id, parent_work_id: work.parent_work_id });
     if (work.launch_policy === "fresh_agent_required" && (identity.sessionId === parentSession || context.db.get("SELECT 1 FROM work_sessions ws JOIN works w ON w.work_id = ws.work_id WHERE w.project_id = ? AND w.run_id = ? AND ws.session_id = ? LIMIT 1", [work.project_id, work.run_id, identity.sessionId])))
         throw new AppError("fresh_session_required", "This Work requires a fresh Session in this RUN", 1, { work_id: work.work_id, session_id: identity.sessionId });
-    const existing = context.db.get("SELECT session_id, parent_session_id FROM sessions WHERE project_id = ? AND session_id = ?", [work.project_id, identity.sessionId]);
+    const existing = context.db.get("SELECT session_id, parent_session_id, provider_parent_session_id FROM sessions WHERE project_id = ? AND session_id = ?", [work.project_id, identity.sessionId]);
     if (existing && existing.parent_session_id && parentSession && existing.parent_session_id !== parentSession)
         throw new AppError("session_parent_conflict", "Observed Session already has a different immutable parent", 1, { session_id: identity.sessionId });
-    context.db.run(`INSERT INTO sessions (session_id, project_id, harness, provider_session_id, agent_id, parent_session_id, provider, model, reasoning, mode, agent_type, project_root, flow_kind, status, run_id, protocol_id, worker_id, workspace_path, continuation_policy, current_stage, next_action, last_action_hash, continuation_count, stop_reason, transcript_path, cwd, metadata_json, coverage_units_json, created_at, updated_at, stopped_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'vnext', 'active', ?, NULL, ?, ?, 'go_router', 'work', NULL, NULL, 0, NULL, ?, ?, '{}', '[]', ?, ?, NULL) ON CONFLICT(session_id, project_id) DO UPDATE SET harness = excluded.harness, provider_session_id = COALESCE(excluded.provider_session_id, provider_session_id), agent_id = COALESCE(excluded.agent_id, agent_id), parent_session_id = COALESCE(excluded.parent_session_id, parent_session_id), provider = COALESCE(excluded.provider, provider), model = COALESCE(excluded.model, model), reasoning = COALESCE(excluded.reasoning, reasoning), mode = COALESCE(excluded.mode, mode), agent_type = COALESCE(excluded.agent_type, agent_type), flow_kind = excluded.flow_kind, run_id = excluded.run_id, worker_id = excluded.worker_id, workspace_path = excluded.workspace_path, transcript_path = COALESCE(excluded.transcript_path, transcript_path), cwd = excluded.cwd, updated_at = excluded.updated_at`, [identity.sessionId, work.project_id, identity.harness, identity.providerSessionId, identity.agentId, existing?.parent_session_id ?? (parentSession === identity.sessionId ? null : parentSession), identity.provider, identity.model, identity.reasoning, identity.mode, identity.agentType, run.project_root, work.run_id, work.work_id, run.workspace_root, identity.transcriptPath, run.workspace_root, now, now]);
+    if (existing?.provider_parent_session_id && providerParentSession && existing.provider_parent_session_id !== providerParentSession)
+        throw new AppError("provider_session_parent_conflict", "Observed provider Session already has a different immutable provider parent", 1, { session_id: identity.sessionId });
+    context.db.run(`INSERT INTO sessions (session_id, project_id, harness, provider_session_id, provider_parent_session_id, agent_id, parent_session_id, provider, model, reasoning, mode, agent_type, project_root, flow_kind, status, run_id, protocol_id, worker_id, workspace_path, continuation_policy, current_stage, next_action, last_action_hash, continuation_count, stop_reason, transcript_path, cwd, metadata_json, coverage_units_json, created_at, updated_at, stopped_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'vnext', 'active', ?, NULL, ?, ?, 'go_router', 'work', NULL, NULL, 0, NULL, ?, ?, '{}', '[]', ?, ?, NULL) ON CONFLICT(session_id, project_id) DO UPDATE SET harness = excluded.harness, provider_session_id = COALESCE(excluded.provider_session_id, provider_session_id), provider_parent_session_id = COALESCE(excluded.provider_parent_session_id, provider_parent_session_id), agent_id = COALESCE(excluded.agent_id, agent_id), parent_session_id = COALESCE(excluded.parent_session_id, parent_session_id), provider = COALESCE(excluded.provider, provider), model = COALESCE(excluded.model, model), reasoning = COALESCE(excluded.reasoning, reasoning), mode = COALESCE(excluded.mode, mode), agent_type = COALESCE(excluded.agent_type, agent_type), flow_kind = excluded.flow_kind, run_id = excluded.run_id, worker_id = excluded.worker_id, workspace_path = excluded.workspace_path, transcript_path = COALESCE(excluded.transcript_path, transcript_path), cwd = excluded.cwd, updated_at = excluded.updated_at`, [identity.sessionId, work.project_id, identity.harness, identity.providerSessionId, providerParentSession, identity.agentId, existing?.parent_session_id ?? (parentSession === identity.sessionId ? null : parentSession), identity.provider, identity.model, identity.reasoning, identity.mode, identity.agentType, run.project_root, work.run_id, work.work_id, run.workspace_root, identity.transcriptPath, run.workspace_root, now, now]);
     reactivateBoundSession(context, work.project_id, identity.sessionId, now);
 }
+/** Register the trusted physical Session before a paused Work moves to it. */
+export function bindSessionForResume(context, workId, identity, now) {
+    const work = requireWork(context, workId);
+    if (work.status !== "paused")
+        throw new AppError("invalid_work_state", "Only a paused Work can bind a resume Session", 1, { work_id: work.work_id, status: work.status });
+    bindSession(context, work, requireRun(context, work.project_id, work.run_id), identity, now);
+}
 function reactivateBoundSession(context, projectId, sessionId, now) {
     context.db.run("UPDATE sessions SET status = 'active', stop_reason = NULL, stopped_at = NULL, updated_at = ? WHERE project_id = ? AND session_id = ?", [now, projectId, sessionId]);
 }
-function validateWorkResult(work, result, projectRoot, workspaceRoot, runId, resultPath) {
+function validateWorkResult(work, result, projectRoot, workspaceRoot, runHome, runId, resultPath) {
     if (!work.result_schema)
         return;
     if (!resultPath)
@@ -388,20 +420,35 @@ function validateWorkResult(work, result, projectRoot, workspaceRoot, runId, res
     catch {
         throw new AppError("validation", "Work result must be JSON for its declared result schema", 2, { work_id: work.work_id, result_schema: work.result_schema });
     }
-    fs.writeFileSync(resultPath, result);
-    validateSchema({ schemaName: work.result_schema.replace(/^dd-flow\//, "").replace(/@\d+$/, ""), file: resultPath, projectRoot, runId });
+    const candidate = `${resultPath}.candidate-${process.pid}`;
+    fs.writeFileSync(candidate, result);
+    try {
+        validateSchema({ schemaName: work.result_schema.replace(/^dd-flow\//, "").replace(/@\d+$/, ""), file: candidate, projectRoot, runId });
+    }
+    finally {
+        fs.rmSync(candidate, { force: true });
+    }
     if (work.result_schema === "dd-flow/code-work-result@2")
-        validateCodeWorkResult(work, parsed, workspaceRoot);
+        validateCodeWorkResult(work, parsed, workspaceRoot, runHome, runId);
     if (work.result_schema === "dd-flow/code-review-result@1")
-        validateCodeReviewResultIdentity(work, parsed);
+        validateCodeReviewResult(work, parsed, { workspaceRoot, runHome, runId });
+    if (work.result_schema === "dd-flow/plan-review-result@1")
+        validatePlanReviewResult(work, parsed, { workspaceRoot, runHome, runId });
 }
-function validateCodeWorkResult(work, value, projectRoot) {
+function validateCodeWorkResult(work, value, projectRoot, runHome, runId) {
     const result = value;
     if ((result.deviations?.length ?? 0) > 0 || (result.blockers?.length ?? 0) > 0)
         throw new AppError("work_contract_incomplete", "CODE Work cannot complete with unresolved deviations or blockers; fail the Work and report the contract mismatch", 2, { work_id: work.work_id, deviations: result.deviations ?? [], blockers: result.blockers ?? [] });
     const packet = codePacket(work);
     if (!packet)
         return;
+    const acceptedCriteria = new Set(packet.acceptance.map((item) => item.criterion_id).filter((item) => typeof item === "string"));
+    for (const item of result.evidence ?? []) {
+        if (!item.criterion_id || !acceptedCriteria.has(item.criterion_id))
+            throw new AppError("evidence_criterion_unknown", "CODE Work evidence must reference an acceptance criterion assigned to this Work", 2, { work_id: work.work_id, criterion_id: item.criterion_id ?? null });
+        for (const ref of item.refs ?? [])
+            assertPortableArtifactRef(ref, { workspaceRoot: projectRoot, runHome, runId });
+    }
     const documentUpdates = (packet.document_updates ?? []);
     const changed = new Set(result.changed_paths ?? []);
     const missingDocuments = documentUpdates.map((entry) => entry.path).filter((entry) => !changed.has(entry));
@@ -413,6 +460,8 @@ function validateCodeWorkResult(work, value, projectRoot) {
         throw new AppError("document_update_not_materialized", "Assigned durable document updates must exist and differ from their PLAN baseline", 2, { work_id: work.work_id, unchanged_paths: unchangedDocuments });
     const assigned = packet.repair?.review_finding_ids ?? [];
     if (assigned.length) {
+        if ((result.changed_paths?.length ?? 0) === 0)
+            throw new AppError("review_repair_no_change", "Review repair must materialize a project change; a no-op cannot resolve a finding", 2, { work_id: work.work_id, findings: assigned });
         const resolved = new Set(result.resolved_finding_refs ?? []);
         const missing = assigned.filter((finding) => !resolved.has(finding));
         const unexpected = [...resolved].filter((finding) => !assigned.includes(finding));
@@ -420,24 +469,25 @@ function validateCodeWorkResult(work, value, projectRoot) {
             throw new AppError("review_repair_incomplete", "Review repair must explicitly resolve exactly its assigned finding references", 2, { work_id: work.work_id, missing, unexpected });
     }
 }
-function renderWorkerPrompt(context, work, run, dependencies, resultPath) {
+function renderWorkerPrompt(context, work, run, dependencies) {
     const command = flowCommand(context);
     const packet = codePacket(work);
     const codeContext = packet ? ["<semantic_spine>", JSON.stringify(packet.semantic_spine, null, 2), "</semantic_spine>", "", ...(packet.repair ? ["<repair_context>", JSON.stringify(packet.repair, null, 2), "Read the failed receipt and its linked stdout/stderr before editing. Preserve the accepted origin context and fix only the evidenced failure.", "</repair_context>", ""] : []), "<accepted_requirements>", JSON.stringify(packet.requirements, null, 2), "</accepted_requirements>", "", "<acceptance_context>", "The criteria below are end-to-end context. Complete this Work's semantic contribution and declared checks; another ordered Work may own a different acceptance surface.", JSON.stringify(packet.acceptance, null, 2), "</acceptance_context>", "", "<required_read>", "These are mandatory starting sources, not a read allowlist. Read any additional project files needed to implement the Work correctly.", ...packet.required_read.map((item) => `- ${resolveRunReferences(item, work.run_id, requireRunHome(run))}`), "</required_read>", "", "<discovery_boundary>", "These are likely discovery areas, not a hard boundary. Expand project-local investigation when required and report material additions.", ...packet.discovery_boundary.map((item) => `- ${item}`), "</discovery_boundary>", "", "<planned_write_areas>", "SOFT COORDINATION HINT ONLY. These paths help the coordinator avoid concurrent collisions. They do not grant or deny write permission and do not limit the files needed for this Work. You may create or change any project file under workspace_root that is necessary and in semantic scope; report every actual changed path.", ...(packet.planned_write_areas.length ? packet.planned_write_areas.map((item) => `- ${item}`) : ["- none predicted; derive the necessary files from the task"]), "</planned_write_areas>", "", ...(packet.provides_checks.length ? ["<provided_checks>", ...packet.provides_checks.map((item) => `- ${item.id}: materialize ${item.command}${item.definition ? ` as ${item.definition}` : ""}; it is not usable until this Work finishes.`), "Update the declared project command or alias before Work finish. The CLI verifies the materialization and then executes the check.", "</provided_checks>", ""] : []), "<verification>", ...packet.checks.map((item) => `- ${item.id} at ${item.run_at}: ${item.command} — ${item.purpose}`), "The CLI executes work-scoped checks and retains their receipts. Report semantic evidence only; do not rerun declared checks manually.", "</verification>", "", "<stop_conditions>", ...packet.stop_conditions.map((item) => `- ${item}`), "</stop_conditions>", ""] : [];
     if (packet)
         codeContext.push("<document_updates>", JSON.stringify(packet.document_updates, null, 2), "Materialize every listed update. dd-flow verifies the resulting file against its PLAN-time baseline.", "</document_updates>", "", "<completion_contract>", "Successful completion requires empty deviations and blockers and every assigned document update in changed_paths. A necessary path outside planned_write_areas is normal coordination drift, not a blocker; include it in changed_paths and continue.", "</completion_contract>", "");
-    return ["<work>", `- work_id: ${work.work_id}`, `- run_id: ${work.run_id}`, `- project_root: ${run.project_root}`, `- workspace_root: ${run.workspace_root}`, `- run_home: ${requireRunHome(run)}`, "</work>", "", "<hard_write_boundary>", `HARD RULE: all project reads and writes must remain under ${run.workspace_root}.`, "Do not write through project_root, outside workspace_root, into another RUN, or into Git/worktree control data. Do not create, switch, merge or delete branches/worktrees.", "Accepted requirements, non-goals and stop_conditions are semantic hard boundaries. planned_write_areas is not.", "</hard_write_boundary>", "", ...codeContext, "<dependency_results>", JSON.stringify(dependencies.filter(Boolean), null, 2), "</dependency_results>", "", "<task>", resolveRunReferences(work.task, work.run_id, requireRunHome(run)), "</task>", "", ...(work.result_schema ? ["<result_contract>", `Return JSON matching \`${work.result_schema}\`.`, ...resultSchemaGuidance(work), `Write it to ${resultPath}.`, "</result_contract>", ""] : []), "<completion>", "The CLI runs every declared required check before accepting this Work. A failed receipt means only that the check failed; it is not proof of an engine, harness, dependency, or environment blocker.", "Read the failed receipt and its stdout/stderr. Fix project-owned source, migration, test, formatting, or configuration errors in this same Work, then call Finish again. Do not invent a cause that does not appear in the retained output.", "Use Fail only for a concrete external blocker after deterministic bootstrap or a contradiction with an accepted requirement/non-goal. Never fail merely because a necessary project path was absent from planned_write_areas.", "Finish may run for several minutes. Preserve the shell tool's process/session handle and poll that same invocation until it exits; progress arrives as JSONL on stderr. Never reissue Finish merely because final stdout has not arrived.", `Finish as one standalone command: ${command} work finish ${work.work_id} --result-file ${JSON.stringify(resultPath)} --project-root ${JSON.stringify(run.project_root)} --json --progress-jsonl`, `Fail only for an evidenced external or semantic-contract blocker: ${command} work fail ${work.work_id} --reason "receipt path + exact external or semantic blocker" --project-root ${JSON.stringify(run.project_root)} --json`, "</completion>", ""].join("\n");
+    return ["<work>", `- work_id: ${work.work_id}`, `- run_id: ${work.run_id}`, `- project_root: ${run.project_root}`, `- workspace_root: ${run.workspace_root}`, `- run_home: ${requireRunHome(run)}`, "</work>", "", "<hard_write_boundary>", `HARD RULE: project source reads and writes must remain under ${run.workspace_root}.`, "Do not write through project_root, outside workspace_root, into another RUN, or into Git/worktree control data. Do not create, switch, merge or delete branches/worktrees.", "RUN artifacts are read-only evidence: refer to them with run:// URIs and let dd-flow persist your submitted result. Accepted requirements, non-goals and stop_conditions are semantic hard boundaries. planned_write_areas is not.", "</hard_write_boundary>", "", ...codeContext, "<dependency_results>", JSON.stringify(dependencies.filter(Boolean), null, 2), "</dependency_results>", "", "<task>", resolveRunReferences(work.task, work.run_id, requireRunHome(run)), "</task>", "", ...(work.result_schema ? ["<result_contract>", `Return JSON matching \`${work.result_schema}\`.`, ...resultSchemaGuidance(work, run.id), "Do not create result.json yourself. Send the JSON to dd-flow on stdin; it atomically validates and stores the canonical receipt.", "</result_contract>", ""] : []), "<completion>", "The CLI runs every declared required check before accepting this Work. A failed receipt means only that the check failed; it is not proof of an engine, harness, dependency, or environment blocker.", "Read the failed receipt and its stdout/stderr. Fix project-owned source, migration, test, formatting, or configuration errors in this same Work, then call Finish again. Do not invent a cause that does not appear in the retained output.", "Use Fail only for a concrete external blocker after deterministic bootstrap or a contradiction with an accepted requirement/non-goal. Never fail merely because a necessary project path was absent from planned_write_areas.", "Finish may run for several minutes. Preserve the shell tool's process/session handle and poll that same invocation until it exits; progress arrives as JSONL on stderr. Never reissue Finish merely because final stdout has not arrived.", `Finish as one standalone command, piping your JSON object to stdin: ${command} work finish ${work.work_id} --result-stdin --project-root ${JSON.stringify(run.project_root)} --json --progress-jsonl`, `Fail only for an evidenced external or semantic-contract blocker: ${command} work fail ${work.work_id} --reason "receipt path + exact external or semantic blocker" --project-root ${JSON.stringify(run.project_root)} --json`, "</completion>", ""].join("\n");
 }
-function resultSchemaGuidance(work) {
+function resultSchemaGuidance(work, runId) {
     const schema = work.result_schema;
+    const refs = `Evidence refs for project source are relative to workspace_root; RUN evidence uses run://${runId}/path/to/artifact.`;
     if (schema === "dd-flow/code-work-result@2")
-        return ["Use this complete minimal shape. For a review repair, also include resolved_finding_refs with exactly the finding references assigned in repair_context:", "```json", JSON.stringify({ schema_id: schema, summary: "What was implemented.", changed_paths: ["project-relative/path"], evidence: [{ criterion_id: "AC-001", refs: ["project-relative/evidence"] }], deviations: [], blockers: [], resolved_finding_refs: [] }, null, 2), "```"];
+        return [refs, "Use this complete minimal shape. For a review repair, also include resolved_finding_refs with exactly the finding references assigned in repair_context:", "```json", JSON.stringify({ schema_id: schema, summary: "What was implemented.", changed_paths: ["project-relative/path"], evidence: [{ criterion_id: "AC-001", refs: ["project-relative/evidence", `run://${runId}/05-code/checks/receipt.json`] }], deviations: [], blockers: [], resolved_finding_refs: [] }, null, 2), "```"];
     if (schema === "dd-flow/code-review-result@1") {
-        return ["Assess every assigned aspect exactly once. Number findings locally inside this reviewer Work as FIND-001, FIND-002, ...; dd-flow adds the Work id to form the canonical reference.", "Use this complete minimal shape. Report only material, direct-evidence findings; taste and cosmetics are not findings:", "```json", JSON.stringify({ schema_id: schema, verdict: "pass | findings | blocked", summary: "Concise evidence-backed conclusion.", aspects: [{ aspect_id: "assigned_aspect_id", verdict: "pass | findings | blocked", summary: "Conclusion.", evidence_refs: ["path/to/file"] }], findings: [{ finding_id: "FIND-001", aspect_id: "assigned_aspect_id", priority: "p0 | p1 | p2 | p3", problem: "Violated obligation or rule.", impact: "Concrete risk or failure.", evidence_refs: ["path/to/file"], obligation_refs: ["R-001 | AC-001 | policy ref"] }] }, null, 2), "```"];
+        return [refs, "Assess every assigned aspect exactly once. Number findings locally inside this reviewer Work as FIND-001, FIND-002, ...; dd-flow adds the Work id to form the canonical reference.", "Use this complete minimal shape. Report only material, direct-evidence findings; taste and cosmetics are not findings:", "```json", JSON.stringify({ schema_id: schema, verdict: "pass | findings | blocked", summary: "Concise evidence-backed conclusion.", aspects: [{ aspect_id: "assigned_aspect_id", verdict: "pass | findings | blocked", summary: "Conclusion.", evidence_refs: ["path/to/file", `run://${runId}/05-code/checks/receipt.json`] }], findings: [{ finding_id: "FIND-001", aspect_id: "assigned_aspect_id", priority: "p0 | p1 | p2 | p3", problem: "Violated obligation or rule.", impact: "Concrete risk or failure.", evidence_refs: ["path/to/file"], obligation_refs: ["R-001 | AC-001 | policy ref"] }] }, null, 2), "```"];
     }
     if (schema !== "dd-flow/plan-review-result@1")
         return [];
-    return ["Use this complete minimal shape; do not add fields. Number findings locally inside this reviewer Work as FIND-001, FIND-002, ...; dd-flow adds the Work id when the coordinator classifies them:", "```json", JSON.stringify({ schema_id: schema, plan_revision: 1, overall_verdict: "pass | watch | needs_changes | blocked", summary: "Concise evidence-backed conclusion.", aspects: [{ aspect_id: "assigned_aspect_id", verdict: "pass | watch | needs_changes | blocked", summary: "Conclusion for this aspect.", evidence_refs: ["path/to/file"], findings: [{ finding_id: "FIND-001", severity: "high | medium | low | info", summary: "Problem, if any.", evidence_refs: ["path/to/file"] }] }] }, null, 2), "```"];
+    return [refs, "Use this complete minimal shape; do not add fields. Number findings locally inside this reviewer Work as FIND-001, FIND-002, ...; dd-flow adds the Work id when the coordinator classifies them:", "```json", JSON.stringify({ schema_id: schema, plan_revision: 1, overall_verdict: "pass | watch | needs_changes | blocked", summary: "Concise evidence-backed conclusion.", aspects: [{ aspect_id: "assigned_aspect_id", verdict: "pass | watch | needs_changes | blocked", summary: "Conclusion for this aspect.", evidence_refs: ["path/to/file", `run://${runId}/03-plan/plan.json`], findings: [{ finding_id: "FIND-001", severity: "high | medium | low | info", summary: "Problem, if any.", evidence_refs: ["path/to/file"] }] }] }, null, 2), "```"];
 }
 export function validateCodeReviewResultIdentity(work, value) {
     const group = codeReviewGroup(work);
@@ -458,6 +508,57 @@ export function validateCodeReviewResultIdentity(work, value) {
         throw new AppError("review_evidence_invalid", "CODE reviewer finding ids must be local FIND-NNN ids and aspect refs must stay inside the assigned review group", 2, { work_id: work.work_id, group: group.key, required_format: "FIND-NNN", invalid, wrong_aspect: wrongAspect });
     }
 }
+/**
+ * CODE review evidence is part of the Work contract, not a late stage-level
+ * concern.  Reject it before `works.result` becomes authoritative so a later
+ * fan-in cannot discover a malformed accepted reviewer result.
+ */
+function validateCodeReviewResult(work, value, input) {
+    validateCodeReviewResultIdentity(work, value);
+    const result = value;
+    const findings = result.findings ?? [];
+    // A reviewer is a child Work and cannot pause its coordinator-owned Stage.
+    // Its structured blocked result is evidence for the coordinator, which then
+    // either resolves the gap or pauses the Stage itself.
+    if ((result.verdict === "pass" && findings.length > 0) || (result.verdict === "findings" && findings.length === 0)) {
+        throw new AppError("review_evidence_invalid", "CODE reviewer verdict must agree with whether material findings are present", 2, { work_id: work.work_id, verdict: result.verdict, findings: findings.length });
+    }
+    const references = [
+        ...(result.aspects ?? []).flatMap((aspect) => Array.isArray(aspect.evidence_refs) ? aspect.evidence_refs : []),
+        ...(result.findings ?? []).flatMap((finding) => Array.isArray(finding.evidence_refs) ? finding.evidence_refs : [])
+    ];
+    for (const ref of references) {
+        if (typeof ref !== "string")
+            throw new AppError("review_evidence_invalid", "CODE reviewer evidence references must be strings", 2, { work_id: work.work_id, ref });
+        assertPortableArtifactRef(ref, input);
+    }
+}
+export function validatePlanReviewResult(work, value, input) {
+    const group = codeReviewGroup(work);
+    if (!group)
+        throw new AppError("review_evidence_invalid", "PLAN reviewer Work has no assigned review group", 2, { work_id: work.work_id });
+    const result = value;
+    const aspects = result.aspects ?? [];
+    const ids = aspects.map((item) => item.aspect_id ?? "");
+    const expected = new Set(group.aspect_ids);
+    const missing = group.aspect_ids.filter((id) => !ids.includes(id));
+    const unexpected = ids.filter((id) => !expected.has(id));
+    if (new Set(ids).size !== ids.length || missing.length || unexpected.length)
+        throw new AppError("review_evidence_invalid", "PLAN reviewer result must assess every assigned aspect exactly once", 2, { work_id: work.work_id, group: group.key, missing, unexpected });
+    const findingIds = aspects.flatMap((aspect) => aspect.findings ?? []).map((finding) => finding.finding_id ?? "");
+    const invalid = findingIds.filter((id) => !/^FIND-\d{3}$/.test(id));
+    if (new Set(findingIds).size !== findingIds.length || invalid.length)
+        throw new AppError("review_evidence_invalid", "PLAN reviewer finding ids must be unique local FIND-NNN ids", 2, { work_id: work.work_id, invalid });
+    const refs = aspects.flatMap((aspect) => [
+        ...(Array.isArray(aspect.evidence_refs) ? aspect.evidence_refs : []),
+        ...(aspect.findings ?? []).flatMap((finding) => Array.isArray(finding.evidence_refs) ? finding.evidence_refs : [])
+    ]);
+    for (const ref of refs) {
+        if (typeof ref !== "string")
+            throw new AppError("review_evidence_invalid", "PLAN reviewer evidence references must be strings", 2, { work_id: work.work_id, ref });
+        assertPortableArtifactRef(ref, input);
+    }
+}
 function codeReviewGroup(work) {
     const payload = parsePayload(work);
     const group = payload?.group;
@@ -505,12 +606,14 @@ function validateItem(value, requireExecutionContext = false) { if (!value || ty
     throw new AppError("validation", "work item must be an object", 2); const item = value; if (typeof item.key !== "string" || !item.key || typeof item.task !== "string" || !item.task.trim())
     throw new AppError("validation", "work item requires key and task", 2); const code = item.schema_id === "dd-flow/code-work-packet@5"; if (requireExecutionContext && !code)
     throw new AppError("validation", "CODE batch requires code-work-packet@5 items", 2, { key: item.key }); for (const key of code ? ["required_read", "discovery_boundary", "planned_write_areas", "checks", "provides_checks", "stop_conditions"] : [])
-    if (!Array.isArray(item[key]) || (!['provides_checks', 'planned_write_areas'].includes(key) && item[key].length === 0))
+    if (!Array.isArray(item[key]) || (!['provides_checks', 'planned_write_areas', 'checks'].includes(key) && item[key].length === 0) || (key === "checks" && item[key].length === 0 && !allowsEmptyRepairChecks(item)))
         throw new AppError("validation", `CODE work item requires ${['provides_checks', 'planned_write_areas'].includes(key) ? "an array" : `non-empty ${key}`}`, 2, { key: item.key }); if (item.depends_on !== undefined && (!Array.isArray(item.depends_on) || !item.depends_on.every((entry) => typeof entry === "string")))
     throw new AppError("validation", "depends_on must be a string array", 2); if (item.parent !== undefined && typeof item.parent !== "string")
     throw new AppError("validation", "parent must be a string", 2); if (item.launch_policy !== undefined && item.launch_policy !== "reuse_allowed" && item.launch_policy !== "fresh_agent_required")
     throw new AppError("validation", "launch_policy must be reuse_allowed or fresh_agent_required", 2); if (item.result_schema !== undefined && (typeof item.result_schema !== "string" || !item.result_schema))
     throw new AppError("validation", "result_schema must be a non-empty schema id", 2); const payload = code ? item : (item.payload && typeof item.payload === "object" && !Array.isArray(item.payload) ? item.payload : undefined); return { key: item.key, task: item.task, ...(Array.isArray(item.depends_on) ? { depends_on: item.depends_on } : {}), ...(typeof item.parent === "string" ? { parent: item.parent } : {}), ...(typeof item.launch_policy === "string" ? { launch_policy: item.launch_policy } : {}), ...(typeof item.result_schema === "string" ? { result_schema: item.result_schema } : {}), ...(payload ? { payload } : {}) }; }
+function allowsEmptyRepairChecks(item) { const repair = item.repair; if (!repair || typeof repair !== "object" || Array.isArray(repair))
+    return false; const value = repair; return typeof value.check_receipt_id === "string" || (Array.isArray(value.review_check_refs) && value.review_check_refs.some((ref) => typeof ref === "string")) || (Array.isArray(value.semantic_unresolved) && value.semantic_unresolved.some((item) => typeof item === "string")); }
 function readJson(file) { try {
     return JSON.parse(fs.readFileSync(path.resolve(file), "utf8"));
 }