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

package/dist/services/vnext-specify.js

@@ -17,6 +17,7 @@ import { writeStageReport } from "./stage-report-renderer.js";
 const flowId = "mb-sdlc-vnext-specify";
 const protocolizeFlowId = "mb-sdlc-vnext-protocolize";
 const flowVersion = 4;
+const protocolizeFlowVersion = 5;
 const stageId = "specify";
 const entryId = "default";
 export function isVnextSpecifyFlow(projectRoot) {
@@ -553,8 +554,10 @@ export function readVnextFlowDefinition(projectRoot) {
             ? definition.stages.specify?.entries?.default
             : undefined;
         const ordered = Array.isArray(actions?.actions) ? actions.actions : [];
-        if ((definition.id === flowId || definition.id === protocolizeFlowId) && definition.version === flowVersion && ordered.length === 3) {
-            return { id: definition.id };
+        const definitionId = typeof definition.id === "string" ? definition.id : null;
+        const supportedVersion = definitionId === flowId ? flowVersion : definitionId === protocolizeFlowId ? protocolizeFlowVersion : null;
+        if (definitionId && supportedVersion !== null && definition.version === supportedVersion && ordered.length === 3) {
+            return { id: definitionId };
         }
     }
     return null;

package/dist/services/vnext-workspace-policy.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { spawnSync } from "node:child_process";
 import { AppError } from "../shared/errors.js";
 import { gitFacts } from "./runs.js";
 const configRelativePath = path.join(".memory-bank", "dd-flow", "project-workspace.json");
@@ -74,13 +75,18 @@ export function requireVnextWorkspaceRoute(input) {
             throw new AppError("workspace_route_missing", `${input.stage} requires a provisioned feature worktree`, 1, { run_id: input.runId, workspace_root: workspaceRoot, policy });
         }
         const facts = gitFacts(workspaceRoot);
-        if (facts.status === "unavailable" || facts.branch !== policy.feature_branch || facts.head !== policy.base_ref) {
-            throw new AppError("workspace_route_invalid", `${input.stage} workspace no longer matches its frozen feature branch and base`, 1, { run_id: input.runId, workspace_root: workspaceRoot, expected: policy, actual: facts });
+        const ancestry = facts.head ? gitAncestry(workspaceRoot, policy.base_ref, facts.head) : { ok: false, status: null, error: "missing HEAD" };
+        if (facts.status === "unavailable" || facts.branch !== policy.feature_branch || !ancestry.ok) {
+            throw new AppError("workspace_route_invalid", `${input.stage} workspace no longer matches its frozen feature branch and base`, 1, { run_id: input.runId, workspace_root: workspaceRoot, expected: policy, actual: facts, ancestry });
         }
     }
     return policy;
 }
 function realPath(value) { return fs.existsSync(value) ? fs.realpathSync(value) : path.resolve(value); }
+function gitAncestry(workspaceRoot, ancestor, descendant) {
+    const result = spawnSync("git", ["-C", workspaceRoot, "merge-base", "--is-ancestor", ancestor, descendant], { encoding: "utf8" });
+    return { ok: result.status === 0, status: result.status, error: result.error ? String(result.error) : null };
+}
 function safeSlug(value) {
     const slug = value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
     return slug || "work";

package/dist/services/work-registry.js

@@ -6,11 +6,22 @@ import { findRecentMatchingHookEvent, claimStageStartHookEvent, claimWorkStartHo
 import { validateSchema } from "./schema-validation.js";
 import { resolveProjectRoot, resolveRunReferences, writeJsonAtomic } from "../storage/paths.js";
 import { refreshRunSessionProjection } from "./run-projection.js";
-import { runCodeChecks } from "./code-checks.js";
-import { nextWorkId } from "./ids.js";
+import { readCodeCheckProfile, runCodeChecks } from "./code-checks.js";
+import { nextWorkId, nextWorkIds } from "./ids.js";
 import { appendFlowRunTimelineEvent } from "./runs.js";
+import { flowCommand } from "./stage-pause.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) {
+    const parent = requireWork(context, input.parentWorkId);
+    if (parent.status !== "running")
+        throw new AppError("invalid_work_state", "Child Work requires a running parent", 2, { parent_work_id: parent.work_id, status: parent.status });
+    const id = nextWorkId(context, parent.project_id, input.slug);
+    const now = context.now();
+    context.db.run(`INSERT INTO works (${workColumns}) VALUES (?, ?, ?, ?, ?, ?, ?, ?, '[]', 'created', NULL, ?, NULL, ?, NULL)`, [id, parent.project_id, parent.run_id, parent.work_id, input.task, input.launchPolicy, input.resultSchema ?? null, input.payload ? JSON.stringify(input.payload) : null, now, now]);
+    refreshRunWorkProjection(context, parent.project_id, parent.run_id);
+    return requireWork(context, id);
+}
 /** Validate a proposed batch before PLAN accepts it, without registering Work. */
 export function validateWorkBatchFile(file) {
     const parsed = readJson(file);
@@ -54,7 +65,8 @@ export function addWorkBatch(context, input) {
     const now = context.now();
     context.db.exec("BEGIN IMMEDIATE");
     try {
-        const ids = new Map(items.map((item) => [item.key, nextWorkId(context, parent.project_id, item.key)]));
+        const allocated = nextWorkIds(context, parent.project_id, items.map((item) => item.key));
+        const ids = new Map(items.map((item, index) => [item.key, allocated[index]]));
         const resolve = (value) => ids.get(value) ?? value;
         const proposed = items.map((item) => ({ ...item, id: ids.get(item.key), parentId: item.parent ? resolve(item.parent) : parent.work_id, dependencies: (item.depends_on ?? []).map(resolve) }));
         assertNoCycles(proposed.map((item) => ({ id: item.id, dependencies: item.dependencies })));
@@ -128,7 +140,13 @@ export function mutateWorkDeps(context, input) {
 export function deleteWork(context, id) { const work = requireWork(context, id); const canonical = work.work_id; if (work.status !== "created" || work.started_at || context.db.get("SELECT 1 FROM works WHERE parent_work_id = ? LIMIT 1", [canonical]) || context.db.get("SELECT 1 FROM works WHERE depends_on_json LIKE ? LIMIT 1", [`%${canonical}%`]))
     throw new AppError("invalid_work_state", "Only an unstarted unreferenced Work may be deleted", 2); context.db.run("DELETE FROM works WHERE work_id = ?", [canonical]); refreshRunWorkProjection(context, work.project_id, work.run_id); return { ok: true, deleted: canonical }; }
 export function shortWorkId(id) { return /^WRK-\d{3,}(?:-|$)/.exec(id)?.[0]?.replace(/-$/, "") ?? id; }
-export function workStartCommand(context, work) { const run = requireRun(context, work.project_id, work.run_id); return `DD_FLOW_HOME=${JSON.stringify(context.ddFlowHome)} dd-flow work start ${work.work_id} --project-root ${JSON.stringify(run.project_root)} --json`; }
+/**
+ * Return the engine-bound command, never a PATH-dependent `dd-flow` token.
+ * Fan-out workers run in independently spawned harnesses where the adapter's
+ * PATH is not inherited; using the shared lifecycle command keeps them on the
+ * same captured runtime as their parent stage.
+ */
+export function workStartCommand(context, work) { const run = requireRun(context, work.project_id, work.run_id); return `${flowCommand(context)} work start ${work.work_id} --project-root ${JSON.stringify(run.project_root)} --json`; }
 export function startWork(context, id, input) {
     ensureWorkRegistry(context);
     const work = requireWork(context, id);
@@ -137,7 +155,7 @@ export function startWork(context, id, input) {
     if (!isReady(context, work)) {
         const blockers = readinessBlockers(context, work);
         const ready = context.db.all(`SELECT ${workColumns} FROM works WHERE project_id = ? AND run_id = ? AND status = 'created' ORDER BY created_at, work_id`, [work.project_id, work.run_id]).filter((candidate) => isReady(context, candidate)).map((candidate) => ({ work_id: candidate.work_id, start_command: workStartCommand(context, candidate) }));
-        throw new AppError("work_not_ready", "Work cannot start until dependencies complete and overlapping write scopes are free", 2, { work_id: id, blockers, ready });
+        throw new AppError("work_not_ready", "Work cannot start until dependencies complete and overlapping planned coordination areas are free", 2, { work_id: id, blockers, ready });
     }
     const run = requireRun(context, work.project_id, work.run_id);
     if (input.projectRoot && resolveProjectRoot(input.projectRoot) !== resolveProjectRoot(run.project_root))
@@ -165,8 +183,31 @@ export function bindRunningWorkSession(context, input) {
     const identity = hookSessionIdentity(context, work.project_id, input.hookEventId);
     const active = 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", [work.work_id]);
     if (active) {
-        if (active.session_id !== identity.sessionId)
-            throw new AppError("handoff_session_mismatch", "The active Work is already bound to a different Session", 1, { work_id: work.work_id });
+        if (active.session_id !== identity.sessionId) {
+            // A frozen `new_session` policy may transfer the same coordinator Work
+            // only to its next stage. Repeating the same stage from another Session
+            // remains a conflict because its result path is unchanged.
+            if (!input.allowStageHandoff || path.resolve(active.result_path ?? "") === path.resolve(input.resultPath ?? ""))
+                throw new AppError("handoff_session_mismatch", "The active Work is already bound to a different Session", 1, { work_id: work.work_id });
+            const now = context.now();
+            const id = `WS-${crypto.randomUUID()}`;
+            context.db.exec("BEGIN IMMEDIATE");
+            try {
+                context.db.run("UPDATE work_sessions SET status = 'completed', completed_at = ?, updated_at = ? WHERE id = ?", [now, now, active.id]);
+                const stillRunning = context.db.get("SELECT 1 FROM work_sessions WHERE session_id = ? AND status = 'running' LIMIT 1", [active.session_id]);
+                if (!stillRunning)
+                    context.db.run("UPDATE sessions SET status = 'idle', updated_at = ? WHERE project_id = ? AND session_id = ?", [now, work.project_id, active.session_id]);
+                bindSession(context, work, run, identity, now);
+                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)", [id, work.work_id, identity.sessionId, input.hookEventId, input.promptPath, input.resultPath ?? null, now, now]);
+                context.db.exec("COMMIT");
+            }
+            catch (error) {
+                context.db.exec("ROLLBACK");
+                throw error;
+            }
+            refreshRunWorkProjection(context, work.project_id, work.run_id);
+            return { work_session_id: id, session_id: identity.sessionId, handed_off: true };
+        }
         context.db.run("UPDATE work_sessions SET prompt_path = ?, result_path = COALESCE(?, result_path), updated_at = ? WHERE id = ?", [input.promptPath, input.resultPath ?? null, context.now(), active.id]);
         return { work_session_id: active.id, session_id: identity.sessionId, reused: true };
     }
@@ -190,7 +231,8 @@ export function bindStageCoordinatorWork(context, input) {
     const work = requireWork(context, input.workId);
     const run = requireRun(context, work.project_id, work.run_id);
     claimStageStartHookEvent(context, { projectId: work.project_id, eventKey: input.hookEventId, runId: work.run_id, stage: input.stage, projectRoot: run.project_root, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
-    const binding = bindRunningWorkSession(context, input);
+    const snapshot = JSON.parse((context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [work.project_id, work.run_id])?.index_json) ?? "{}");
+    const binding = bindRunningWorkSession(context, { ...input, allowStageHandoff: snapshot.execution_profile?.settings?.stage_session_mode === "new_session" });
     context.db.run("UPDATE sessions SET current_stage = ?, updated_at = ? WHERE project_id = ? AND session_id = ?", [input.stage, context.now(), work.project_id, binding.session_id]);
     refreshRunSessionProjection(context, work.project_id, work.run_id);
     return binding;
@@ -203,7 +245,7 @@ export function startStageCoordinatorWork(context, input) {
     const run = requireRun(context, work.project_id, work.run_id);
     if (input.projectRoot && resolveProjectRoot(input.projectRoot) !== resolveProjectRoot(run.project_root))
         throw new AppError("project_mismatch", "stage coordinator project root does not match its RUN", 1, { work_id: work.work_id });
-    const identity = claimStageStartHookEvent(context, { projectId: work.project_id, eventKey: input.hookEventId, runId: work.run_id, stage: input.stage, projectRoot: run.project_root });
+    const identity = claimStageStartHookEvent(context, { projectId: work.project_id, eventKey: input.hookEventId, runId: work.run_id, stage: input.stage, projectRoot: run.project_root, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
     const binding = startBoundWork(context, work, run, identity, input.hookEventId);
     const sessionId = String(binding.session_binding.session_id ?? "");
     context.db.run("UPDATE sessions SET current_stage = ?, updated_at = ? WHERE project_id = ? AND session_id = ?", [input.stage, context.now(), work.project_id, sessionId]);
@@ -223,6 +265,8 @@ export function startBoundWork(context, work, run, identity, hookEventId) {
     context.db.exec("BEGIN IMMEDIATE");
     try {
         bindSession(context, work, run, identity, now);
+        if (work.parent_work_id && work.launch_policy === "reuse_allowed")
+            context.db.run("UPDATE work_sessions SET status = 'completed', completed_at = ?, updated_at = ? WHERE session_id = ? AND status = 'running' AND work_id <> ?", [now, now, identity.sessionId, work.work_id]);
         const claimed = context.db.run("UPDATE works SET status = 'running', started_at = ?, updated_at = ? WHERE work_id = ? AND status = 'created'", [now, now, work.work_id]);
         if (claimed.changes !== 1)
             throw new AppError("conflict", "Work was claimed concurrently", 1, { work_id: work.work_id });
@@ -241,6 +285,10 @@ export function startBoundWork(context, work, run, identity, hookEventId) {
     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 } };
 }
 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("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); }
 export function retryWork(context, id, reason) { const work = requireWork(context, id); id = work.work_id; if (work.status !== "failed")
@@ -261,14 +309,19 @@ async function settle(context, id, status, result, progress) {
     if (work.status === "running" && !link)
         throw new AppError("runtime_missing", "Running Work has no open Work/Session link", 1, { work_id: id });
     let receipts = [];
+    let coordinationDrift = [];
     if (status === "completed") {
         validateWorkResult(work, result, run.project_root, run.workspace_root, run.id, link?.result_path ?? null);
         const packet = codePacket(work);
         if (packet) {
-            validateChangedPaths(packet, result);
+            // CODE packets are projected from a PLAN that already validated this
+            // profile. Check it even when the Work has only raw focused checks, so a
+            // worker cannot complete after downgrading the frozen project contract.
+            readCodeCheckProfile(run.workspace_root);
+            coordinationDrift = plannedAreaDrift(packet, result);
             const artifactDir = path.relative(requireRunHome(run), path.dirname(link.result_path));
             receipts = await runCodeChecks(context, { projectId: work.project_id, runId: work.run_id, runHome: requireRunHome(run), workspaceRoot: run.workspace_root, workId: work.work_id, artifactDir, scope: "work", checks: packet.checks.filter((check) => check.run_at === "work"), ...(progress ? { progress } : {}) });
-            const failed = receipts.filter((receipt) => receipt.status === "failed");
+            const failed = receipts.filter((receipt) => receipt.status !== "passed");
             if (failed.length)
                 throw new AppError("work_checks_failed", "Work remains running because required checks failed", 2, { work_id: id, failures: failed, all_receipts: receipts });
         }
@@ -293,18 +346,16 @@ async function settle(context, id, status, result, progress) {
     }
     refreshRunWorkProjection(context, work.project_id, work.run_id);
     const newlyReady = context.db.all(`SELECT ${workColumns} FROM works WHERE project_id = ? AND run_id = ? AND status = 'created' ORDER BY created_at, work_id`, [work.project_id, work.run_id]).filter((candidate) => isReady(context, candidate)).map((candidate) => ({ work_id: candidate.work_id, start_command: workStartCommand(context, candidate) }));
-    appendFlowRunTimelineEvent(context, work.project_id, work.run_id, { type: `work_${status}`, work_id: work.work_id, session_id: link?.session_id ?? null });
+    appendFlowRunTimelineEvent(context, work.project_id, work.run_id, { type: `work_${status}`, work_id: work.work_id, session_id: link?.session_id ?? null, ...(coordinationDrift.length ? { coordination_drift: coordinationDrift } : {}) });
     for (const ready of newlyReady)
         appendFlowRunTimelineEvent(context, work.project_id, work.run_id, { type: "work_dependency_unblocked", work_id: ready.work_id, completed_dependency: work.work_id });
-    return { ok: true, work_id: id, status, checks: receipts, newly_ready: newlyReady, graph: codeWorkGraph(context, work.project_id, work.run_id), usage: { status: "provisional", reason: "final usage is controller-owned" } };
+    return { ok: true, work_id: id, status, checks: receipts, coordination: { planned_write_areas: codePacket(work)?.planned_write_areas ?? [], drift: coordinationDrift }, newly_ready: newlyReady, graph: codeWorkGraph(context, work.project_id, work.run_id), usage: { status: "provisional", reason: "final usage is controller-owned" } };
 }
-function validateChangedPaths(packet, result) {
+function plannedAreaDrift(packet, result) {
     const changed = JSON.parse(result).changed_paths;
-    if (!Array.isArray(changed))
-        return;
-    const outside = changed.filter((item) => typeof item === "string" && !packet.write_scope.some((scope) => item === scope || item.startsWith(`${scope}/`)));
-    if (outside.length)
-        throw new AppError("write_scope_violation", "CODE Work result declares paths outside its accepted write scope", 2, { outside, write_scope: packet.write_scope });
+    if (!Array.isArray(changed) || packet.planned_write_areas.length === 0)
+        return [];
+    return changed.filter((item) => typeof item === "string" && !packet.planned_write_areas.some((area) => item === area || item.startsWith(`${area}/`)));
 }
 function bindSession(context, work, run, identity, now) {
     const priorWorkSession = context.db.get("SELECT session_id FROM work_sessions WHERE work_id = ? ORDER BY created_at DESC LIMIT 1", [work.work_id])?.session_id ?? null;
@@ -370,12 +421,12 @@ function validateCodeWorkResult(work, value, projectRoot) {
     }
 }
 function renderWorkerPrompt(context, work, run, dependencies, resultPath) {
-    const command = `DD_FLOW_HOME=${JSON.stringify(context.ddFlowHome)} dd-flow`;
+    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 only this Work's semantic_spine.acceptance_contribution, task, write_scope, and declared checks. A criterion may name another ordered Work's UI, documentation, or evidence surface; do not fail merely because that surface is outside this Work's write_scope.", JSON.stringify(packet.acceptance, null, 2), "</acceptance_context>", "", "<required_read>", ...packet.required_read.map((item) => `- ${resolveRunReferences(item, work.run_id, requireRunHome(run))}`), "</required_read>", "", "<discovery_boundary>", ...packet.discovery_boundary.map((item) => `- ${item}`), "</discovery_boundary>", "", "<write_scope>", ...packet.write_scope.map((item) => `- ${item}`), "</write_scope>", "", ...(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>", ""] : [];
+    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>", "", "<contract_failure>", "Successful completion requires empty deviations and blockers and every assigned document update in changed_paths. If a required path is missing from write_scope, do not report success: fail this Work with that exact path and the retained receipt so the coordinator can correct the packet.", "</contract_failure>", "");
-    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>", "", "<workspace_contract>", `All project reads and writes belong under ${run.workspace_root}. Project root is only the stable lifecycle identity for dd-flow commands. Do not create, switch, merge or delete branches/worktrees.`, "</workspace_contract>", "", ...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 for a contractual scope conflict where a required repair path lies outside this Work's write_scope. Quote the exact receipt plus the error or missing path. A project check failure inside this Work's scope must be fixed before Finish.", "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 scope-contract case: ${command} work fail ${work.work_id} --reason "receipt path + exact error or missing write_scope path" --project-root ${JSON.stringify(run.project_root)} --json`, "</completion>", ""].join("\n");
+        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");
 }
 function resultSchemaGuidance(work) {
     const schema = work.result_schema;
@@ -435,27 +486,27 @@ catch {
 function isReady(context, work) { return work.status === "created" && readinessBlockers(context, work).length === 0; }
 function readinessBlockers(context, work) {
     const blockers = parseDependencies(work).flatMap((id) => { const dependency = context.db.get("SELECT status FROM works WHERE work_id = ?", [id]); return dependency?.status === "completed" ? [] : [{ kind: "dependency", work_id: id, status: dependency?.status ?? "missing" }]; });
-    const scope = workWriteScope(work);
-    if (scope.length === 0)
+    const areas = workPlannedWriteAreas(work);
+    if (areas.length === 0)
         return blockers;
     for (const running of context.db.all(`SELECT ${workColumns} FROM works WHERE project_id = ? AND run_id = ? AND status = 'running' AND work_id != ?`, [work.project_id, work.run_id, work.work_id])) {
-        const overlap = overlappingScopes(scope, workWriteScope(running));
+        const overlap = overlappingAreas(areas, workPlannedWriteAreas(running));
         if (overlap.length)
-            blockers.push({ kind: "write_scope", work_id: running.work_id, paths: overlap });
+            blockers.push({ kind: "planned_write_area", work_id: running.work_id, paths: overlap });
     }
     return blockers;
 }
-function workWriteScope(work) { const payload = parsePayload(work); return Array.isArray(payload?.write_scope) ? payload.write_scope.filter((item) => typeof item === "string").map((item) => item.replaceAll("\\", "/").replace(/^\.\//, "").replace(/\/$/, "")) : []; }
-function overlappingScopes(left, right) { const overlap = new Set(); for (const a of left)
+function workPlannedWriteAreas(work) { const payload = parsePayload(work); return Array.isArray(payload?.planned_write_areas) ? payload.planned_write_areas.filter((item) => typeof item === "string").map((item) => item.replaceAll("\\", "/").replace(/^\.\//, "").replace(/\/$/, "")) : []; }
+function overlappingAreas(left, right) { const overlap = new Set(); for (const a of left)
     for (const b of right)
         if (a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`))
             overlap.add(a.length <= b.length ? a : b); return [...overlap]; }
 function validateItem(value, requireExecutionContext = false) { if (!value || typeof value !== "object" || Array.isArray(value))
     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@4"; if (requireExecutionContext && !code)
-    throw new AppError("validation", "CODE batch requires code-work-packet@4 items", 2, { key: item.key }); for (const key of code ? ["required_read", "discovery_boundary", "write_scope", "checks", "provides_checks", "stop_conditions"] : [])
-    if (!Array.isArray(item[key]) || (key !== "provides_checks" && item[key].length === 0))
-        throw new AppError("validation", `CODE work item requires ${key === "provides_checks" ? "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", "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))
+        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))
@@ -480,7 +531,7 @@ function parsePayload(work) { if (!work.payload_json)
 catch {
     return null;
 } }
-function codePacket(work) { const value = parsePayload(work); if (value?.schema_id !== "dd-flow/code-work-packet@4")
+function codePacket(work) { const value = parsePayload(work); if (value?.schema_id !== "dd-flow/code-work-packet@5")
     return null; return value; }
 function assertNoCycles(nodes) { const local = new Map(nodes.map((node) => [node.id, node.dependencies.filter((dependency) => nodes.some((candidate) => candidate.id === dependency))])); const active = new Set(); const done = new Set(); const visit = (id) => { if (active.has(id))
     throw new AppError("validation", "Work dependencies contain a cycle", 2); if (done.has(id))

package/dist/storage/database.js

@@ -58,13 +58,21 @@ export function ensureVnextWorkStorage(db) {
       work_id TEXT,
       scope TEXT NOT NULL,
       declaration_id TEXT NOT NULL,
+      check_refs_json TEXT NOT NULL DEFAULT '[]',
+      gate TEXT NOT NULL DEFAULT 'work',
       command TEXT NOT NULL,
+      input_hash TEXT NOT NULL DEFAULT '',
+      verification_epoch TEXT NOT NULL DEFAULT '',
       status TEXT NOT NULL,
       exit_code INTEGER,
       stdout_path TEXT NOT NULL,
       stderr_path TEXT NOT NULL,
       receipt_path TEXT NOT NULL,
       workspace_fingerprint TEXT NOT NULL,
+      before_fingerprint TEXT NOT NULL DEFAULT '',
+      after_fingerprint TEXT NOT NULL DEFAULT '',
+      profile_hash TEXT,
+      mutation_paths_json TEXT NOT NULL DEFAULT '[]',
       artifacts_json TEXT NOT NULL,
       started_at TEXT NOT NULL,
       finished_at TEXT NOT NULL,
@@ -474,6 +482,56 @@ function migrate(db) {
     CREATE INDEX IF NOT EXISTS idx_check_receipts_run
       ON check_receipts(project_id, run_id, started_at);
 
+    CREATE TABLE IF NOT EXISTS merge_requests (
+      merge_request_id TEXT PRIMARY KEY,
+      project_id TEXT NOT NULL,
+      run_id TEXT NOT NULL,
+      executor_work_id TEXT NOT NULL,
+      protocol_ids_json TEXT NOT NULL,
+      source_workspace TEXT NOT NULL,
+      source_branch TEXT NOT NULL,
+      source_commit TEXT NOT NULL,
+      target_workspace TEXT NOT NULL,
+      target_branch TEXT NOT NULL,
+      enqueue_target_head TEXT,
+      execution_target_head TEXT,
+      integration_commit TEXT,
+      execution_route TEXT NOT NULL,
+      status TEXT NOT NULL,
+      dispatch_owner TEXT,
+      dispatch_lease_token TEXT,
+      dispatch_lease_expires_at TEXT,
+      lock_acquired_at TEXT,
+      checkpoint TEXT NOT NULL DEFAULT 'queued',
+      profile_hash TEXT,
+      adapter_receipt_json TEXT,
+      result_json TEXT,
+      last_error_json TEXT,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      completed_at TEXT,
+      FOREIGN KEY(project_id, run_id) REFERENCES runs(project_id, id),
+      FOREIGN KEY(executor_work_id) REFERENCES works(work_id)
+    );
+    CREATE INDEX IF NOT EXISTS idx_merge_requests_fifo
+      ON merge_requests(project_id, status, created_at, merge_request_id);
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_merge_requests_run
+      ON merge_requests(project_id, run_id);
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_merge_requests_active_project
+      ON merge_requests(project_id)
+      WHERE status IN ('active', 'waiting_user', 'action_required', 'recovery_required');
+
+    CREATE TABLE IF NOT EXISTS merge_servers (
+      server_id TEXT PRIMARY KEY,
+      profile_id TEXT NOT NULL,
+      status TEXT NOT NULL,
+      pid INTEGER,
+      started_at TEXT NOT NULL,
+      heartbeat_at TEXT NOT NULL,
+      stopped_at TEXT,
+      journal_path TEXT NOT NULL
+    );
+
     CREATE TABLE IF NOT EXISTS flow_run_flag_mutations (
       project_id TEXT NOT NULL,
       run_id TEXT NOT NULL,
@@ -685,6 +743,14 @@ function migrate(db) {
     ensureColumn(db, "check_receipts", "declaration_id", "ALTER TABLE check_receipts ADD COLUMN declaration_id TEXT NOT NULL DEFAULT 'CHK-LEGACY'");
     ensureColumn(db, "check_receipts", "workspace_fingerprint", "ALTER TABLE check_receipts ADD COLUMN workspace_fingerprint TEXT NOT NULL DEFAULT ''");
     ensureColumn(db, "check_receipts", "artifacts_json", "ALTER TABLE check_receipts ADD COLUMN artifacts_json TEXT NOT NULL DEFAULT '[]'");
+    ensureColumn(db, "check_receipts", "check_refs_json", "ALTER TABLE check_receipts ADD COLUMN check_refs_json TEXT NOT NULL DEFAULT '[]'");
+    ensureColumn(db, "check_receipts", "gate", "ALTER TABLE check_receipts ADD COLUMN gate TEXT NOT NULL DEFAULT 'work'");
+    ensureColumn(db, "check_receipts", "input_hash", "ALTER TABLE check_receipts ADD COLUMN input_hash TEXT NOT NULL DEFAULT ''");
+    ensureColumn(db, "check_receipts", "verification_epoch", "ALTER TABLE check_receipts ADD COLUMN verification_epoch TEXT NOT NULL DEFAULT ''");
+    ensureColumn(db, "check_receipts", "before_fingerprint", "ALTER TABLE check_receipts ADD COLUMN before_fingerprint TEXT NOT NULL DEFAULT ''");
+    ensureColumn(db, "check_receipts", "after_fingerprint", "ALTER TABLE check_receipts ADD COLUMN after_fingerprint TEXT NOT NULL DEFAULT ''");
+    ensureColumn(db, "check_receipts", "profile_hash", "ALTER TABLE check_receipts ADD COLUMN profile_hash TEXT");
+    ensureColumn(db, "check_receipts", "mutation_paths_json", "ALTER TABLE check_receipts ADD COLUMN mutation_paths_json TEXT NOT NULL DEFAULT '[]'");
     ensureColumn(db, "hook_events", "event_key", "ALTER TABLE hook_events ADD COLUMN event_key TEXT");
     ensureColumn(db, "hook_events", "match_key", "ALTER TABLE hook_events ADD COLUMN match_key TEXT");
     ensureColumn(db, "hook_events", "claimed_at", "ALTER TABLE hook_events ADD COLUMN claimed_at TEXT");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deksden-com/dd-flow-cli",
-  "version": "0.8.0-beta.135",
+  "version": "0.9.0-beta.0",
   "description": "Mechanical runtime CLI for dd-flow workflows.",
   "type": "module",
   "bin": {
@@ -27,6 +27,7 @@
   },
   "dependencies": {
     "ajv": "^8.20.0",
+    "shell-quote": "^1.10.0",
     "smol-toml": "^1.6.1",
     "yaml": "^2.9.0"
   },