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

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # @deksden-com/dd-flow-cli
 
+## 0.9.0-beta.0
+
+### Minor Changes
+
+- cef9b99: Add the vNext MERGE stage, project FIFO integration requests, same-session and
+  merge-server execution, integrated-tree verification receipts, and explicit
+  local delivery and cleanup policies. Upgrade the planned-check contract to
+  `code-check-profile@5` and project execution snapshots to
+  `project-execution@2`.
+
+### Patch Changes
+
+- 7a97bdf: Use one shell-aware lifecycle parser across every harness hook so quoted
+  absolute launchers bind correctly while diagnostic text cannot trigger a
+  trusted lifecycle event.
+
+## 0.8.0
+
+### Patch Changes
+
+- a092c98: Accept controlled OpenCode lifecycle events and cumulative root/child Session usage through the shared harness evidence path.
+- fb2395a: Accept trusted lifecycle events from controlled zcode-acp sessions and retain harness-native root, child, parent, and execution-daemon identities in Session evidence.
+- Promote the accepted SPECIFY-through-CODE-REVIEW runtime as stable 0.8.0 and align its shared compatibility, flow, stage-start and status schemas with Memory Bank 4.0.0.
+
+## 0.8.0-beta.138
+
+### Patch Changes
+
+- Replace CODE and repair file allowlists with optional `planned_write_areas`:
+  soft coordination hints that serialize likely concurrent collisions but never
+  deny a necessary project-local edit. Record unexpected actual paths as
+  `coordination.drift` instead of rejecting the Work.
+- Render the hard RUN workspace boundary separately from required reads,
+  discovery hints and planned coordination areas, so a worker can distinguish
+  semantic constraints from planning predictions.
+
+## 0.8.0-beta.137
+
+### Patch Changes
+
+- Transfer a running coordinator Work to a fresh Session at a frozen
+  `new_session` stage boundary, while still rejecting a second Session that
+  tries to repeat the same stage.
+
+## 0.8.0-beta.136
+
+### Patch Changes
+
+- Serialize the long CODE aggregate gate and reuse complete same-workspace
+  receipts after a client loses its command output, preventing a concurrent
+  retry from duplicating checks or colliding on receipt identifiers.
+
 ## 0.8.0-beta.135
 
 ### Patch Changes

package/README.md

@@ -97,7 +97,7 @@ dd-flow prompt render \
 
 For a non-plan worker, replace `--plan-item` with `--task-file <path>` pointing to a `dd-flow/worker-task@1` manifest inside the selected RUN home. The manifest embeds one existing plan-item-shaped `task`, so validation and rendered artifacts remain identical to the compatibility route.
 
-The selected item must contain `execution_context` and `semantic_spine`. The renderer accepts only registered profiles, validates the active RUN/workspace and source paths, then persists `launch-prompt.md`, `prompt-stack.json` and `render-report.json` in the RUN stage. The stack and render report both retain the validated read/discovery/write references. It records project sources as paths rather than copying their contents. `required_read` and `discovery_boundary` may use a checked `run://<relative-path>` reference for a source inside the selected RUN home; write scopes remain project-local.
+The selected item must contain `execution_context` and `semantic_spine`. The renderer accepts only registered profiles, validates the active RUN/workspace and source paths, then persists `launch-prompt.md`, `prompt-stack.json` and `render-report.json` in the RUN stage. The stack and render report both retain the validated read/discovery/coordination references. It records project sources as paths rather than copying their contents. `required_read` and `discovery_boundary` may use a checked `run://<relative-path>` reference for a source inside the selected RUN home. The RUN workspace is the hard write boundary; `planned_write_areas` are optional soft hints for concurrent-work coordination, never a file allowlist.
 
 Human help is available for the operator-facing command groups:
 
@@ -106,8 +106,7 @@ dd-flow --help
 dd-flow lane --help
 dd-flow lane workspace --help
 dd-flow lane lock --help
-dd-flow merge-queue --help
-dd-flow merge-queue wait-next --help
+dd-flow merge --help
 dd-flow cleanup --help
 dd-flow codex home --help
 dd-flow worktree --help
@@ -189,7 +188,29 @@ When the task stops using the shared checkout:
 dd-flow lane lock release --project-root "$PROJECT_ROOT" --lane direct-main --worker-id "$PROTOCOL_ID" --path "$PWD" --lease-token "$TOKEN" --reason done --json
 ```
 
-## Merge Queue Recipe
+## vNext MERGE recipe
+
+CODE/CODE-REVIEW closure creates the `MRG-*` request and returns the exact
+standalone stage-start command. Run it unchanged. The accepted packet then
+provides the exact `merge apply` and `stage finish` commands; do not reconstruct
+Git operations or lifecycle arguments manually.
+
+For unattended execution, store a validated agent profile under
+`DD_FLOW_HOME/agent-profiles/<id>.json` and run:
+
+```bash
+dd-flow merge serve --agent-profile <id> --max-parallel-projects 4 --progress-jsonl
+dd-flow merge server status --json
+```
+
+The server preserves FIFO inside one project and may serve different projects
+concurrently. Same-session and server routes use the same MRG, Work, checks and
+stage report.
+
+## Classic merge queue recipe
+
+The commands below belong to the classic protocol runtime. The vNext flow does
+not call them or fall back to them.
 
 Prompts enqueue protocols only after explicit readiness signals exist:
 
@@ -368,6 +389,12 @@ The installed hook writes invocation markers, forwarded stderr, and the final
 exit code to `${DD_FLOW_HOME:-$HOME/.dd-flow}/logs/codex-hook.log`. An absent
 start marker means Codex did not invoke the hook; a start marker without a
 successful finish marker identifies a hook launch or handler failure.
+
+All harness event handlers use the same lifecycle shell parser. It recognizes
+`dd-flow` as the actual command word, including a quoted absolute executable,
+and does not treat occurrences in search patterns, JSON, comments or heredoc
+bodies as lifecycle calls. Real lifecycle calls joined to other shell commands
+remain invalid and receive a standalone retry.
 `--project-root` belongs to installer/status commands, not the stored handler.
 
 ## Verification

package/dist/build-info.json

@@ -1,15 +1,15 @@
 {
   "cli_package": "@deksden-com/dd-flow-cli",
-  "cli_version": "0.8.0-beta.135",
-  "cli_commit": "05b606d42418d944364abb013ce02f3e78149916",
-  "built_at": "2026-08-30T15:27:46.996Z",
+  "cli_version": "0.9.0-beta.0",
+  "cli_commit": "ade3ebb2888bf804bec3879bbf7ed4600ff651fc",
+  "built_at": "2026-09-01T20:01:20.985Z",
   "built_with_canon": {
-    "version": null,
-    "commit": null,
-    "flow_contract": null,
-    "repo_root": null,
-    "memorybank_root": null,
-    "flow_root": null,
-    "layout": null
+    "version": "4.0.0",
+    "commit": "bd6494ad11bca9544d9b483bd7fe37049e6d00fe",
+    "flow_contract": "dd-flow-canonical-2026-08",
+    "repo_root": "/Users/deksden/Documents/_Projects/dd-memorybank",
+    "memorybank_root": "/Users/deksden/Documents/_Projects/dd-memorybank/.memory-bank",
+    "flow_root": "/Users/deksden/Documents/_Projects/dd-memorybank/.memory-bank/dd-flow",
+    "layout": "dot_memory_bank"
   }
 }

package/dist/cli/help.js

@@ -28,9 +28,8 @@ Core commands:
   plan status/item/reviews      Inspect plans, update SQLite progress, or dispatch vNext grouped reviews.
   prompt render                 Render one bounded, RUN-local worker launch prompt.
   lane workspace/lock/status    Manage shared workspace lanes and leases.
-  merge status/one-shot/bundle  Inspect, claim, or complete merge work from the current session.
-  merge-worker status/start/stop Manage long-lived project merge workers.
-  merge-queue status/claim/next Claim, wait for, complete, or fail merge jobs.
+  merge request/apply           Inspect, route and execute vNext MERGE requests.
+  merge serve/status/stop       Run or inspect the deterministic vNext merge server.
   session register/status/stop  Register flow sessions and stop workers.
   dashboard data/render/open/refresh Render, refresh, open, and inspect project/global dashboards.
   schema validate             Validate canonical dd-flow JSON data contracts.
@@ -60,8 +59,9 @@ Examples:
   dd-flow protocol transition PRT-001-demo --to implementation --payload-file transition.json --json
   dd-flow lane workspace set --project-root "$PWD" --lane merge --path "$PWD" --branch main --json
   dd-flow lane lock acquire --project-root "$PWD" --lane merge --worker-id worker-1 --path "$PWD" --ttl 300 --reason "merge worker" --json
-  dd-flow merge status --project-root "$PWD" --json
-  dd-flow merge-worker start --project-root "$PWD" --worker-id merge-worker --path "$PWD" --json
+  dd-flow merge request status MRG-001 --project-root "$PWD" --json
+  dd-flow merge apply MRG-001 --work WRK-001 --project-root "$PWD" --json --progress-jsonl
+  dd-flow merge serve --agent-profile codex-luna-xhigh --progress-jsonl
 
 Default output is human-readable. Use --json for hooks, prompts, scripts and other agent automation; JSON mode never mixes human progress text into stdout.
 
@@ -204,9 +204,9 @@ Usage:
   dd-flow work show <WORK-ID> --json
   dd-flow work start <WORK-ID> --project-root <root> --json
   dd-flow work finish <WORK-ID> (--result-file <path>|--result-stdin) --project-root <root> --json
-  dd-flow work repair add --run <RUN-ID> --from-check <CHECK-ID> --origin-work <WORK-ID>... [--write-scope <path>...] --task-stdin --project-root <root> --json
+  dd-flow work repair add --run <RUN-ID> --from-check <CHECK-ID> --origin-work <WORK-ID>... --task-stdin --project-root <root> --json
 
-CODE workers receive their full accepted packet from work start. work finish validates the result and executes the packet's focused checks before completion. A failed aggregate CODE gate returns the exact failed receipt and repair command; repair add creates a new Work from the selected completed origin context plus that failure evidence. Exact existing project files named by the retained receipt output are added to its repair scope deterministically; repeat --write-scope only for an additional path not named there.`
+CODE workers receive their full accepted packet from work start. work finish validates the result and executes the packet's focused checks before completion. A failed aggregate CODE gate returns the exact failed receipt and repair command; repair add creates a new Work from the selected completed origin context plus that failure evidence. Its planned write areas are coordination hints only; the repair may change any necessary project file inside its RUN workspace.`
     ],
     [
         "id",
@@ -363,53 +363,17 @@ The renderer accepts only registered profiles: code_implementation, documentatio
     ],
     [
         "merge",
-        `dd-flow merge - current-session merge entrypoint helpers
+        `dd-flow merge - deterministic vNext integration queue and executor
 
 Usage:
-  dd-flow merge status --project-root <root> [--path <workspace>] --json
-  dd-flow merge one-shot --project-root <root> --worker-id <id> [--path <workspace>] --json
-  dd-flow merge bundle status --project-root <root> --path <workspace> --json
-  dd-flow merge bundle claim --project-root <root> --worker-id <id> --path <workspace> --json
-  dd-flow merge bundle complete --project-root <root> --worker-id <id> --path <workspace> --summary <text> --json
-  dd-flow merge bundle fail --project-root <root> --worker-id <id> --path <workspace> --reason <text> --requeue true|false --json
+  dd-flow merge request status <MRG-ID> --project-root <root> --json
+  dd-flow merge request route <MRG-ID> --mode same_session|server --reason <text> --project-root <root> --json
+  dd-flow merge apply <MRG-ID> --work <WRK-ID> --project-root <root> --json --progress-jsonl
+  dd-flow merge serve --agent-profile <id> [--once] [--poll-seconds <n>] [--max-parallel-projects <n>] --progress-jsonl
+  dd-flow merge server status --json
+  dd-flow merge server stop <MSV-ID> --json
 
-merge status reports active merge worker, claimed protocols, active merge lane lock, queue state and branch_context when --path is provided. merge one-shot keeps legacy single-protocol behavior and also returns branch_context. merge bundle commands operate on all ready protocols in the current branch/worktree: status is read-only, claim requires the merge lane lock owner, complete closes all claimed protocols after branch integration, and fail requeues or fails the claimed bundle.`
-    ],
-    [
-        "merge-worker",
-        `dd-flow merge-worker - manage long-lived project merge workers
-
-Usage:
-  dd-flow merge-worker status --project-root <root> --json
-  dd-flow merge-worker start --project-root <root> --worker-id <id> [--path <workspace>] [--branch <branch>] --json
-  dd-flow merge-worker stop --project-root <root> [--worker-id <id>] --reason <text> --json
-
-start is idempotent: if a worker, claimed job, or active merge lock already exists it returns status instead of creating a duplicate worker. stop is no-op/status when no worker exists, refuses ambiguous multiple workers unless --worker-id is provided, stops idle workers immediately, and marks busy workers as stop-after-current while preserving the claimed job and lock.`
-    ],
-    [
-        "merge-queue",
-        `dd-flow merge-queue - inspect and process ready-for-merge protocols
-
-Usage:
-  dd-flow merge-queue status --project-root <root> --json
-  dd-flow merge-queue next --project-root <root> --worker-id <id> [--path <workspace>] --json
-  dd-flow merge-queue claim <protocol-id> [--project-root <root>] --worker-id <id> [--path <workspace>] --json
-  dd-flow merge-queue wait-next --project-root <root> --worker-id <id> [--path <workspace>] --timeout <seconds> --poll-interval <seconds> [--acquire-lock true] --json
-  dd-flow merge-queue complete <protocol-id> [--project-root <root>] --worker-id <id> [--path <workspace>] --summary <text> --json
-  dd-flow merge-queue note <protocol-id> [--project-root <root>] --worker-id <id> --summary <text> --json
-  dd-flow merge-queue fail <protocol-id> [--project-root <root>] --worker-id <id> [--path <workspace>] --reason <text> --requeue true|false --json
-  dd-flow merge-queue cancel <protocol-id> [--project-root <root>] --reason <text> [--worker-id <id>] [--path <workspace>] [--force] --json
-
-The worker must own the merge lane from the registered merge workspace before claiming, completing, or failing queued protocols. next remains FIFO; claim <protocol-id> atomically claims only that ready/requeued job. Outputs use queue_item/protocol/claim as the primary contract and retain job as a compatibility alias. note updates the final completion summary after post-complete cleanup and does not require a lane lock. --path defaults to the current working directory. Use --worker-id as the owner identity.
-
-For branch-level integration prefer:
-  dd-flow merge bundle status --project-root "$PWD" --path "$PWD" --json
-  dd-flow merge bundle claim --project-root "$PWD" --worker-id merge-worker --path "$PWD" --json
-
-Examples:
-  dd-flow merge-queue wait-next --project-root "$PWD" --worker-id merge-worker --path "$PWD" --timeout 1200 --poll-interval 10 --acquire-lock true --json
-  dd-flow merge-queue complete PRT-123 --project-root "$PWD" --worker-id merge-worker --path "$PWD" --summary "merged locally; cleanup follows" --json
-  dd-flow merge-queue note PRT-123 --project-root "$PWD" --worker-id merge-worker --summary "merged, pushed, checked, and cleanup completed" --json`
+CODE or CODE-REVIEW creates one MRG request and child MERGE Work. stage start waits in the shared project FIFO, reports progress, locks the execution target baseline and returns the exact apply/finish commands. merge apply is the only supported initial Git mutation. merge serve is a deterministic dispatcher: it launches a fresh Session through the configured harness adapter but does not perform agent work itself. It preserves FIFO inside each project and may serve different projects concurrently up to the explicit bound.`
     ],
     [
         "cleanup",
@@ -420,18 +384,6 @@ Usage:
   dd-flow cleanup apply --project-root <root> --plan-file <file> --reason <text> [--force] --json
 
 cleanup scan is read-only and returns deterministic findings plus plan.actions. cleanup apply validates project identity, action kinds, reason, and destructive force requirements before mutating runtime state, then reports requested/applied/changed/skipped action results. Worktree record cleanup marks a checkout removed only when its path is already absent; existing checkouts are kept instead of being silently deleted. Use this for stale queue jobs, missing protocol runtime snapshots, stale sessions, expired locks, and terminal-protocol worktree records.`
-    ],
-    [
-        "merge-queue wait-next",
-        `dd-flow merge-queue wait-next - wait for the next ready merge protocol
-
-Usage:
-  dd-flow merge-queue wait-next --project-root <root> --worker-id <id> [--path <workspace>] --timeout <seconds> --poll-interval <seconds> [--acquire-lock true] --json
-
-Use this from a shell or supervisor to wait outside model tokens. Live merge workers should prefer long waits, for example --timeout 1200 --poll-interval 10, so the agent sleeps inside the CLI process instead of spending model tokens on frequent polling. If --acquire-lock true is used, wait-next first enters the generic FIFO lane waiter path (lane lock wait-acquire --lane merge), then heartbeats the merge lock while waiting for a ready protocol. A lock acquired by this command is released on timeout. If a protocol is ready, it is claimed atomically. If no protocol appears before the timeout, the command returns outcome: wait_timeout with queue_item: null and legacy job: null.
-
-Examples:
-  dd-flow merge-queue wait-next --project-root "$PWD" --worker-id supervisor --path "$PWD" --timeout 1200 --poll-interval 10 --acquire-lock true --json`
     ],
     [
         "session",

package/dist/cli/run-cli.js

@@ -17,6 +17,7 @@ import { getProjectConfigStatus, setProjectConfigValue } from "../services/confi
 import { getCanonStatus, registerCanonRoot, resolveCanonRoot } from "../services/canon.js";
 import { getRuntimeStatus } from "../services/status.js";
 import { getCliVersionReport } from "../services/build-info.js";
+import { parseCommandArgs } from "../services/lifecycle-command.js";
 import { autoRefreshDashboards, dashboardData, getCmuxStatus, openDashboard, openGlobalDashboard, openProtocolDashboard, refreshAllDashboards, refreshDashboard, refreshGlobalDashboard, renderDashboard, renderGlobalDashboard } from "../services/dashboard.js";
 import { dashboardTargetSummary, preferredDashboardCommand, relatedDashboardCommands, resolveDashboardTarget } from "../services/dashboard-targets.js";
 import { getFlowSessionStatus, registerFlowSession, stopFlowSession, stopMergeWorker, syncFlowSessionUsage } from "../services/sessions.js";
@@ -38,6 +39,8 @@ import { finishVnextPlan, isVnextPlanRun, startVnextPlan } from "../services/vne
 import { dispatchVnextPlanReview, finishVnextPlanReview, isVnextPlanReviewRun, recordVnextPlanReviewCapacity, startVnextPlanReview } from "../services/vnext-plan-review.js";
 import { addVnextCodeRepair, finishVnextCode, startVnextCode } from "../services/vnext-code.js";
 import { addVnextCodeReviewRepair, finishVnextCodeReview, isVnextCodeReviewRun, startVnextCodeReview } from "../services/vnext-code-review.js";
+import { applyVnextMerge, finishVnextMerge, getVnextMergeRequest, isVnextMergeRun, routeVnextMergeRequest, startVnextMerge } from "../services/vnext-merge.js";
+import { mergeServerStatus, serveMergeRequests, stopMergeServer } from "../services/merge-server.js";
 import { getVnextFanoutStatus } from "../services/vnext-fanout.js";
 import { pauseStageForUser, resumeStageAfterUser } from "../services/stage-pause.js";
 import { blockStageForRuntime, unblockStageAfterRuntimeRepair } from "../services/stage-blocker.js";
@@ -217,7 +220,7 @@ function progressForCommand(args) {
         ];
     }
     if ((family === "cleanup" && command === "apply") ||
-        (family === "merge" && command === "one-shot") ||
+        family === "merge" ||
         family === "merge-worker" ||
         (family === "protocol" && command === "cancel") ||
         (family === "project" && command === "archive") ||
@@ -666,7 +669,7 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
                 projectRoot: requiredScopeProjectRoot(scopeProjectRoot, "work repair add"),
                 runId: requiredOption(parsed, "run"),
                 findingIds: findings,
-                writeScope: parsed.options.get("write-scope") ?? [],
+                checkRefsByFinding: Object.fromEntries(findings.map((finding) => [finding, parsed.options.get("check-ref") ?? []])),
                 objective: await readStdin(io.stdin)
             });
         if (!hasOption(parsed, "from-check"))
@@ -678,7 +681,6 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
             runId: requiredOption(parsed, "run"),
             checkReceiptId: requiredOption(parsed, "from-check"),
             originWorkIds: origins,
-            writeScope: parsed.options.get("write-scope") ?? [],
             objective: await readStdin(io.stdin)
         });
     }
@@ -783,6 +785,10 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
             hookEventId ??= claimVnextStageStart(requiredPosition(parsed, 0, "run-id"));
             return attachExternalStageContext(startVnextCodeReview(context, { projectRoot, runId: requiredPosition(parsed, 0, "run-id"), hookEventId, ...(contextSha256 ? { contextSha256 } : {}), ...(externalContext ? { externalContext } : {}) }), externalContext);
         }
+        if (!bootstrap && stage === "merge" && isVnextMergeRun(context, { projectRoot, runId: requiredPosition(parsed, 0, "run-id") })) {
+            hookEventId ??= claimVnextStageStart(requiredPosition(parsed, 0, "run-id"));
+            return attachExternalStageContext(await startVnextMerge(context, { projectRoot, runId: requiredPosition(parsed, 0, "run-id"), hookEventId, progress: commandProgress(io, output), ...(contextSha256 ? { contextSha256 } : {}), ...(externalContext ? { externalContext } : {}) }), externalContext);
+        }
         if (intakeStdin) {
             throw new AppError("usage", "--intake-stdin is only available for vNext SPECIFY", 2);
         }
@@ -855,6 +861,11 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
                 throw new AppError("usage", "vNext CODE-REVIEW uses --decision-file", 2);
             return await finishVnextCodeReview(context, { projectRoot, runId, ...(optionalOption(parsed, "decision-file") ? { decisionFile: optionalOption(parsed, "decision-file") } : {}), progress: commandProgress(io, output) });
         }
+        if (stage === "merge" && isVnextMergeRun(context, { projectRoot, runId })) {
+            if (resultStdin || semanticFile || resultFile || hasOption(parsed, "outcome"))
+                throw new AppError("usage", "vNext MERGE uses the Work result path returned by stage start", 2);
+            return await finishVnextMerge(context, { projectRoot, runId, requestId: requiredOption(parsed, "request"), workId: requiredOption(parsed, "work"), progress: commandProgress(io, output) });
+        }
         if (hasOption(parsed, "outcome") || hasOption(parsed, "result-file") || resultStdin) {
             throw new AppError("usage", "--outcome, --result-file and --result-stdin are only available for vNext SPECIFY", 2);
         }
@@ -922,7 +933,7 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
         return dispatchMergeQueue(context, command, parsed, requiredScopeProjectRootForOptional(scopeProjectRoot, command, parsed));
     }
     if (family === "merge") {
-        return dispatchMerge(context, command, parsed);
+        return await dispatchMerge(context, command, parsed, commandProgress(io, output));
     }
     if (family === "merge-worker") {
         return dispatchMergeWorker(context, command, parsed);
@@ -1158,7 +1169,35 @@ function dispatchMergeQueue(context, command, parsed, scopeProjectRoot) {
     }
     throw new AppError("usage", `Unknown merge-queue command: ${command ?? "<empty>"}`, 2);
 }
-function dispatchMerge(context, command, parsed) {
+async function dispatchMerge(context, command, parsed, progress) {
+    if (command === "serve") {
+        const pollSeconds = optionalPositiveNumber(parsed, "poll-seconds");
+        const maxParallelProjects = optionalPositiveNumber(parsed, "max-parallel-projects", true);
+        return await serveMergeRequests(context, { profileId: requiredOption(parsed, "agent-profile"), once: hasOption(parsed, "once"), ...(pollSeconds ? { pollSeconds } : {}), ...(maxParallelProjects ? { maxParallelProjects } : {}), ...(progress ? { progress } : {}) });
+    }
+    if (command === "server") {
+        const action = requiredPosition(parsed, 0, "server action");
+        if (action === "status")
+            return mergeServerStatus(context);
+        if (action === "stop")
+            return stopMergeServer(context, { serverId: requiredPosition(parsed, 1, "server-id") });
+        throw new AppError("usage", `Unknown merge server action: ${action}`, 2);
+    }
+    if (command === "apply")
+        return applyVnextMerge(context, { projectRoot: requiredOption(parsed, "project-root"), requestId: requiredPosition(parsed, 0, "merge-request-id"), workId: requiredOption(parsed, "work"), ...(progress ? { progress } : {}) });
+    if (command === "request") {
+        const action = requiredPosition(parsed, 0, "request action");
+        const requestId = requiredPosition(parsed, 1, "merge-request-id");
+        if (action === "status")
+            return getVnextMergeRequest(context, { projectRoot: requiredOption(parsed, "project-root"), requestId });
+        if (action === "route") {
+            const mode = requiredOption(parsed, "mode");
+            if (mode !== "same_session" && mode !== "server")
+                throw new AppError("usage", "--mode must be same_session or server", 2);
+            return routeVnextMergeRequest(context, { projectRoot: requiredOption(parsed, "project-root"), requestId, mode, reason: requiredOption(parsed, "reason") });
+        }
+        throw new AppError("usage", `Unknown merge request action: ${action}`, 2);
+    }
     if (command === "status") {
         return getMergeWorkerStatus(context, { projectRoot: requiredOption(parsed, "project-root"), workspacePath: optionalOption(parsed, "path") });
     }
@@ -1989,26 +2028,7 @@ function parseFlowFlagOverrides(values) {
     return result;
 }
 function parseArgs(args) {
-    const positional = [];
-    const options = new Map();
-    for (let index = 0; index < args.length; index += 1) {
-        const value = args[index];
-        if (value?.startsWith("--")) {
-            const key = value.slice(2);
-            const next = args[index + 1];
-            if (!next || next.startsWith("--")) {
-                options.set(key, [...(options.get(key) ?? []), flagValue]);
-            }
-            else {
-                options.set(key, [...(options.get(key) ?? []), next]);
-                index += 1;
-            }
-        }
-        else if (value) {
-            positional.push(value);
-        }
-    }
-    return { positional, options };
+    return parseCommandArgs(args);
 }
 function requiredPosition(parsed, index, label) {
     const value = parsed.positional[index];
@@ -2082,6 +2102,15 @@ function optionalNumber(parsed, key) {
     }
     return parsedNumber;
 }
+function optionalPositiveNumber(parsed, key, integer = false) {
+    const value = optionalNumber(parsed, key);
+    if (typeof value === "undefined")
+        return undefined;
+    if (value <= 0 || (integer && !Number.isInteger(value))) {
+        throw new AppError("validation", `--${key} must be a positive${integer ? " integer" : ""} number`, 2);
+    }
+    return value;
+}
 function requiredWorkerId(parsed) {
     return requiredOption(parsed, "worker-id");
 }
@@ -2176,7 +2205,7 @@ function projectRootForMutation(context, args, result, resolvedScope) {
     if (family === "merge-queue") {
         return projectRootForMergeQueueMutation(context, command, parsed);
     }
-    if (family === "merge" && command === "one-shot") {
+    if (family === "merge" && ["one-shot", "apply", "request"].includes(command ?? "")) {
         return requiredOption(parsed, "project-root");
     }
     if (family === "merge-worker" && ["start", "stop"].includes(command ?? "")) {

package/dist/domain/stage-catalog.js

@@ -5,8 +5,8 @@ export const vnextStages = [
     { id: "plan", directory: "03-plan", result: "stage-report.json", schema: "dd-flow/stage-report@2", next: ["plan-review", "code"] },
     { id: "plan-review", directory: "04-plan-review", result: "decision.json", schema: "dd-flow/plan-review-decision@3", next: ["code"] },
     { id: "code", directory: "05-code", result: "code-verification.json", schema: "dd-flow/code-verification@2", next: ["code-review", "merge"] },
-    { id: "code-review", directory: "06-code-review", result: "decision.json", schema: "dd-flow/code-review-decision@2", next: ["merge"] },
-    { id: "merge", directory: "07-merge", result: "merge-result.json", schema: "dd-flow/merge-result@1", next: [] }
+    { id: "code-review", directory: "06-code-review", result: "decision.json", schema: "dd-flow/code-review-decision@3", next: ["merge"] },
+    { id: "merge", directory: "07-merge", result: "stage-report.json", schema: "dd-flow/stage-report@2", next: [] }
 ];
 export function vnextStage(id) {
     const stage = vnextStages.find((candidate) => candidate.id === id);

package/dist/domain/validation.js

@@ -113,7 +113,7 @@ function validateExecutionContext(input, itemId) {
         prompt_profile: requireString(context.prompt_profile, `Plan item ${itemId} execution_context.prompt_profile`),
         required_read: requireStringArray(context.required_read, `Plan item ${itemId} execution_context.required_read`),
         discovery_boundary: requireStringArray(context.discovery_boundary, `Plan item ${itemId} execution_context.discovery_boundary`),
-        write_scope: requireStringArray(context.write_scope, `Plan item ${itemId} execution_context.write_scope`),
+        planned_write_areas: requireStringArray(context.planned_write_areas, `Plan item ${itemId} execution_context.planned_write_areas`),
         checks: requireStringArray(context.checks, `Plan item ${itemId} execution_context.checks`)
     };
 }

package/dist/schemas/agent-profile.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "dd-flow/agent-profile@1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_id", "id", "harness", "provider", "model", "reasoning", "mode", "permission"],
+  "properties": {
+    "schema_id": {"const": "dd-flow/agent-profile@1"},
+    "id": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$"},
+    "harness": {"enum": ["codex", "zcode", "agy", "opencode", "grok"]},
+    "provider": {"type": "string", "minLength": 1},
+    "model": {"type": "string", "minLength": 1},
+    "reasoning": {"type": "string", "minLength": 1},
+    "mode": {"type": "string", "minLength": 1},
+    "permission": {"enum": ["allow", "deny"]}
+  }
+}

package/dist/schemas/code-review-decision.schema.json

@@ -1,11 +1,11 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "dd-flow/code-review-decision@2",
+  "$id": "dd-flow/code-review-decision@3",
   "type": "object",
   "additionalProperties": false,
   "required": ["schema_id", "summary", "findings"],
   "properties": {
-    "schema_id": {"const": "dd-flow/code-review-decision@2"},
+    "schema_id": {"const": "dd-flow/code-review-decision@3"},
     "summary": {"type": "string", "minLength": 1},
     "findings": {
       "type": "array",
@@ -17,9 +17,11 @@
           "finding_ref": {"type": "string", "pattern": "^WRK-[^/]+/FIND-[0-9]{3}$"},
           "disposition": {"enum": ["fix", "defer", "reject", "duplicate"]},
           "reason": {"type": "string", "minLength": 1},
+          "check_refs": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"type": "string", "pattern": "^CHK-[A-Za-z0-9-]+$"}},
           "def_id": {"type": "string", "minLength": 1},
           "duplicate_of": {"type": "string", "minLength": 1}
-        }
+        },
+        "allOf": [{"if": {"properties": {"disposition": {"const": "fix"}}}, "then": {"required": ["check_refs"]}}]
       }
     }
   }

package/dist/schemas/code-work-batch.schema.json

@@ -1,11 +1,11 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "dd-flow/code-work-batch@4",
+  "$id": "dd-flow/code-work-batch@5",
   "type": "object",
   "additionalProperties": false,
   "required": ["schema_id", "sources", "works"],
   "properties": {
-    "schema_id": {"const": "dd-flow/code-work-batch@4"},
+    "schema_id": {"const": "dd-flow/code-work-batch@5"},
     "sources": {"type": "array", "minItems": 1, "items": {"type": "object", "additionalProperties": false, "required": ["plan_id", "protocol_id", "revision", "sha256"], "properties": {"plan_id": {"type": "string", "minLength": 1}, "protocol_id": {"type": "string", "minLength": 1}, "revision": {"type": "integer", "minimum": 1}, "sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"}}}},
     "works": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/work"}}
   },
@@ -19,6 +19,6 @@
     "check": {"type": "object", "additionalProperties": false, "required": ["id", "command", "purpose", "run_at", "availability"], "properties": {"id": {"type": "string", "pattern": "^CHK-[A-Za-z0-9-]+$"}, "command": {"type": "string", "minLength": 1}, "purpose": {"type": "string", "minLength": 1}, "run_at": {"enum": ["work", "code", "readiness", "merge", "release", "external"]}, "availability": {"enum": ["available", "planned"]}, "provided_by": {"type": "string", "minLength": 1}, "definition": {"type": "string", "minLength": 1}, "required_artifacts": {"type": "array", "uniqueItems": true, "items": {"type": "string", "minLength": 1}}}, "allOf": [{"if": {"properties": {"availability": {"const": "planned"}}, "required": ["availability"]}, "then": {"required": ["provided_by", "definition"], "properties": {"command": {"pattern": "^@check/"}}}}]},
     "documentUpdate": {"type": "object", "additionalProperties": false, "required": ["path", "action", "owner", "reason", "baseline_sha256"], "properties": {"path": {"type": "string", "minLength": 1}, "action": {"enum": ["create", "update"]}, "owner": {"type": "string", "minLength": 1}, "reason": {"type": "string", "minLength": 1}, "baseline_sha256": {"type": ["string", "null"], "pattern": "^[a-f0-9]{64}$"}}},
     "repair": {"type": "object", "additionalProperties": false, "required": ["origin_work_ids"], "anyOf": [{"required": ["check_receipt_id", "failure_receipt_path"]}, {"required": ["review_finding_ids", "review_evidence_refs"]}], "properties": {"origin_work_ids": {"$ref": "#/$defs/strings"}, "check_receipt_id": {"type": "string", "minLength": 1}, "failure_receipt_path": {"type": "string", "minLength": 1}, "review_finding_ids": {"$ref": "#/$defs/strings"}, "review_evidence_refs": {"$ref": "#/$defs/strings"}}},
-    "work": {"type": "object", "additionalProperties": false, "required": ["schema_id", "key", "launch_policy", "source", "task", "semantic_spine", "requirements", "acceptance", "document_updates", "required_read", "discovery_boundary", "write_scope", "checks", "provides_checks", "stop_conditions", "depends_on", "result_schema"], "properties": {"schema_id": {"const": "dd-flow/code-work-packet@4"}, "key": {"type": "string", "minLength": 1}, "launch_policy": {"const": "fresh_agent_required"}, "source": {"$ref": "#/$defs/source"}, "repair": {"$ref": "#/$defs/repair"}, "task": {"type": "string", "minLength": 1}, "semantic_spine": {"$ref": "#/$defs/spine"}, "requirements": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/obligation"}}, "acceptance": {"type": "array", "items": {"$ref": "#/$defs/acceptance"}}, "document_updates": {"type": "array", "items": {"$ref": "#/$defs/documentUpdate"}}, "required_read": {"$ref": "#/$defs/strings"}, "discovery_boundary": {"$ref": "#/$defs/strings"}, "write_scope": {"$ref": "#/$defs/strings"}, "checks": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/check"}}, "provides_checks": {"type": "array", "items": {"$ref": "#/$defs/check"}}, "stop_conditions": {"$ref": "#/$defs/strings"}, "depends_on": {"type": "array", "uniqueItems": true, "items": {"type": "string", "minLength": 1}}, "result_schema": {"const": "dd-flow/code-work-result@2"}}}
+    "work": {"type": "object", "additionalProperties": false, "required": ["schema_id", "key", "launch_policy", "source", "task", "semantic_spine", "requirements", "acceptance", "document_updates", "required_read", "discovery_boundary", "planned_write_areas", "checks", "provides_checks", "stop_conditions", "depends_on", "result_schema"], "properties": {"schema_id": {"const": "dd-flow/code-work-packet@5"}, "key": {"type": "string", "minLength": 1}, "launch_policy": {"const": "fresh_agent_required"}, "source": {"$ref": "#/$defs/source"}, "repair": {"$ref": "#/$defs/repair"}, "task": {"type": "string", "minLength": 1}, "semantic_spine": {"$ref": "#/$defs/spine"}, "requirements": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/obligation"}}, "acceptance": {"type": "array", "items": {"$ref": "#/$defs/acceptance"}}, "document_updates": {"type": "array", "items": {"$ref": "#/$defs/documentUpdate"}}, "required_read": {"$ref": "#/$defs/strings", "description": "Mandatory starting sources, not a read allowlist."}, "discovery_boundary": {"$ref": "#/$defs/strings", "description": "Likely discovery areas; additional project-local reads are allowed."}, "planned_write_areas": {"type": "array", "items": {"type": "string", "minLength": 1}, "description": "Soft coordination hints only. A worker may change any necessary project file inside the RUN workspace."}, "checks": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/check"}}, "provides_checks": {"type": "array", "items": {"$ref": "#/$defs/check"}}, "stop_conditions": {"$ref": "#/$defs/strings", "description": "Hard semantic or external stop conditions; path prediction drift is not a stop condition."}, "depends_on": {"type": "array", "uniqueItems": true, "items": {"type": "string", "minLength": 1}}, "result_schema": {"const": "dd-flow/code-work-result@2"}}}
   }
 }

package/dist/schemas/compatibility.schema.json

@@ -51,6 +51,38 @@
         "status": { "type": "string", "minLength": 1 }
       }
     },
+    "upgrade_contract": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["model", "authorization", "storage_mutation", "run_creation", "post_sync_routing", "contexts", "order"],
+      "properties": {
+        "model": { "const": "dual_context_target_routing" },
+        "authorization": { "const": "command_allowlist" },
+        "storage_mutation": { "const": "explicit_migration_apply_only" },
+        "run_creation": { "const": "after_storage_readiness" },
+        "post_sync_routing": { "const": "marker_free_project_current" },
+        "contexts": {
+          "type": "array",
+          "const": ["project_current", "upgrade_target", "effective_execution"]
+        },
+        "order": {
+          "type": "array",
+          "const": [
+            "pin_target_canon",
+            "verify_target_router",
+            "resolve_contexts",
+            "read_only_diagnostics",
+            "check_shared_home_activity",
+            "verify_backup",
+            "plan_adjacent_migration",
+            "apply_migration_explicitly",
+            "create_upgrade_run",
+            "sync_canonical_layer",
+            "verify_marker_free_normal_route"
+          ]
+        }
+      }
+    },
     "contracts": {
       "type": "object",
       "additionalProperties": false,

package/dist/schemas/flow-contract.schema.json

@@ -34,12 +34,13 @@
     "specifications": {
       "type": "array",
       "minItems": 3,
+      "uniqueItems": true,
       "items": {
         "type": "object",
         "additionalProperties": false,
         "required": ["id", "version", "sha256"],
         "properties": {
-          "id": {"enum": ["SPC-004", "SPC-005", "SPC-006"]},
+          "id": {"enum": ["SPC-004", "SPC-005", "SPC-006", "SPC-009", "SPC-010", "SPC-011"]},
           "version": {"type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$"},
           "sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"}
         }
@@ -180,7 +181,7 @@
         "source_of_truth": {"const": "canonical prompts and schemas"},
         "runtime_owner": {"const": "dd-flow-cli"},
         "lint_owner": {"const": "mb-lint"},
-        "integrated_gate": {"const": "compatible releases plus clean specify-to-plan eval"}
+        "integrated_gate": {"type": "string", "minLength": 1}
       }
     }
   }

package/dist/schemas/merge-result.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "dd-flow/merge-result@1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_id", "outcome", "summary", "conflict_resolution", "verification_summary", "residual_risks"],
+  "properties": {
+    "schema_id": {"const": "dd-flow/merge-result@1"},
+    "outcome": {"enum": ["completed", "blocked"]},
+    "summary": {"type": "string", "minLength": 1},
+    "conflict_resolution": {"type": "string"},
+    "verification_summary": {"type": "string", "minLength": 1},
+    "residual_risks": {"type": "array", "items": {"type": "string", "minLength": 1}}
+  }
+}