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

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @deksden-com/dd-flow-cli
 
+## 0.7.0
+
+### Minor Changes
+
+- Add target-driven engine routing, explicit storage migration safety, immutable RUN engine bindings, engine schema registry validation, and self-contained plan execution guidance.
+
 ## 0.6.0
 
 ### Minor Changes

package/README.md

@@ -355,9 +355,16 @@ Codex integration is explicit and auditable. Managed Codex homes and hooks are l
 ```bash
 dd-flow codex home plan --project-root "$PROJECT_ROOT" --json
 dd-flow codex hooks status --project-root "$PROJECT_ROOT" --target isolated --json
-dd-flow codex hook handle --event Stop --project-root "$PROJECT_ROOT" --json
+dd-flow codex hook handle --event Stop --json
 ```
 
+Installed Codex hooks intentionally omit `--project-root`: Codex supplies the
+session `cwd` in the hook JSON on stdin, and the handler resolves the registered
+project from that path. The option remains available as a manual override. If
+the CLI is upgraded, reinstall the hook in each active `CODEX_HOME`, verify it
+with `dd-flow codex hooks status`, and start a new Codex session;
+`--project-root` belongs to installer/status commands, not the stored handler.
+
 ## Verification
 
 Local verification for this repository:

package/dist/build-info.json

@@ -1,11 +1,11 @@
 {
   "cli_package": "@deksden-com/dd-flow-cli",
-  "cli_version": "0.6.0",
-  "cli_commit": "22cf9c8f5293168dae76212c9a4b74b90a1efeab",
-  "built_at": "2026-08-12T05:09:56.163Z",
+  "cli_version": "0.7.0",
+  "cli_commit": "a09f6b663231d3179bea64b2fd9bb4ffa30096c2",
+  "built_at": "2026-08-13T04:31:51.147Z",
   "built_with_canon": {
-    "version": "3.1.0",
-    "commit": "c201167b896a039ff4881d6d816b9735fba2f799",
+    "version": "3.2.0",
+    "commit": "2a1aaec84ee7d62b9f5a6549de5d1f0cb88082c0",
     "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",

package/dist/cli/help.js

@@ -12,13 +12,13 @@ Core commands:
   version                       Print the installed dd-flow CLI package version.
   status                        Inspect dd-flow runtime, project and canon roots.
   engine install/list/info      Manage locally installed dd-flow engine snapshots.
-  engine resolve/doctor         Inspect router engine selection and health.
+  engine resolve/doctor/bind-run Inspect router selection, health, and recover a legacy RUN binding.
   canon register/status/resolve Register and resolve the canonical Memory Bank.
   project register/status/summary Register a project, inspect state, and publish project summaries.
   project resolve/archive       Resolve typed ids and archive stale project roots.
   project migrate-ids           Migrate old project ids.
   protocol register/status/transition Register, inspect, transition and repair protocol state.
-  migration impact/plan/report/verify Assess release impact and prepare mb-upgrade migration evidence.
+  migration impact/plan/report/verify/apply Assess release impact and explicitly apply mb-upgrade migration evidence.
   cleanup scan/apply            Detect and repair stale local runtime state.
   run start/status/list/timeline/usage/flags Track concrete flow executions, timing, source-aware usage and RUN-local flow flags.
   stage start/finish           Run the canonical two-command stage lifecycle and generate evidence.
@@ -28,7 +28,7 @@ Core commands:
   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/next       Claim, wait for, complete, or fail merge jobs.
+  merge-queue status/claim/next Claim, wait for, complete, or fail merge jobs.
   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.
@@ -86,6 +86,7 @@ Usage:
   dd-flow engine info [--package <name>] [--version <version>] --json
   dd-flow engine resolve [--project-root <root>] --json
   dd-flow engine doctor [--project-root <root>] --json
+  dd-flow engine bind-run <RUN-ID> --project-root <root> --engine-version <version> --reason <text> [--integrity-checksum <sha256>] --json
 
 The globally invoked dd-flow command is the stable router surface. Engine snapshots live under DD_FLOW_HOME/engines and are selected by project Memory Bank compatibility data. Running an old package through npx can install that package's own engine without replacing the global router:
 
@@ -93,11 +94,14 @@ The globally invoked dd-flow command is the stable router surface. Engine snapsh
 
 Router-native engine commands never mutate project runtime data. Normal project commands are routed to a compatible engine or fail closed with a missing-engine diagnostic.
 
+engine bind-run is the one recovery command for a legacy RUN without an engine-binding sidecar. It probes the requested installed snapshot with run status before atomically writing an immutable binding; later RUN commands route through that snapshot.
+
 Examples:
   dd-flow engine install --json
   dd-flow engine list --json
   dd-flow engine resolve --project-root "$PWD" --json
-  dd-flow engine doctor --project-root "$PWD" --json`
+  dd-flow engine doctor --project-root "$PWD" --json
+  dd-flow engine bind-run RUN-193 --project-root "$PWD" --engine-version 0.4.2 --reason "legacy flow-run@1" --json`
     ],
     [
         "status",
@@ -234,11 +238,12 @@ New registrations use full typed ids such as PRJ-001-dd-flow-playground and shor
         `dd-flow migration - plan and verify mb-upgrade runtime/home data migrations
 
 Usage:
-  dd-flow migration plan --project-root <root> [--source-version <version>] [--target-version <version>] [--run <RUN-ID>] [--backup-path <path>] [--backup-created-at <iso>] [--allow-active true|false] --json
-  dd-flow migration report --project-root <root> [--source-version <version>] [--target-version <version>] [--run <RUN-ID>] [--backup-path <path>] [--backup-created-at <iso>] [--allow-active true|false] --json
+  dd-flow migration plan --project-root <root> [--source-version <version>] [--target-version <version>] [--run <RUN-ID>] [--backup-path <path>] [--backup-created-at <iso>] --json
+  dd-flow migration report --project-root <root> [--source-version <version>] [--target-version <version>] [--run <RUN-ID>] [--backup-path <path>] [--backup-created-at <iso>] --json
   dd-flow migration verify --file <mb-upgrade-migration-report.json> --json
+  dd-flow migration apply --project-root <root> --file <mb-upgrade-migration-report.json> --json
 
-Migration commands are evidence and guardrail helpers for canonical mb-upgrade. They do not silently migrate runtime/home data during ordinary CLI use. Applying migrations remains an explicit mb-upgrade contour with backup, adjacent migration chain, active-state handling, derived artifact regeneration and post-upgrade verification.
+Migration commands are evidence and guardrail helpers for canonical mb-upgrade. They do not silently migrate runtime/home data during ordinary CLI use. Applying migrations is an explicit contour requiring a real verified backup, adjacent migration chain, quiescent shared home, recovery evidence and idempotent rerun.
 
 Related commands:
   dd-flow status --project-root <root> --json
@@ -354,13 +359,14 @@ start is idempotent: if a worker, claimed job, or active merge lock already exis
 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. 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.
+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
@@ -527,6 +533,12 @@ Usage:
   dd-flow codex home print-env --project-root <root> [--profile <name>] --json
   dd-flow codex home remove --project-root <root> [--profile <name>] --mode keep-shared|remove-owned --json
 
+  dd-flow codex hook handle --event <HookEventName> [--project-root <root>] --json
+
+Managed hooks omit --project-root. Codex supplies cwd in the stdin payload; the
+handler resolves the registered project from cwd. The option is only a manual
+override.
+
 Managed homes isolate dd-flow hooks while sharing selected Codex state from the source home.`
     ],
     [

package/dist/cli/run-cli.js

@@ -1,12 +1,12 @@
 import fs from "node:fs";
-import { createContext } from "../runtime/context.js";
+import { createContext, createRouterContext } from "../runtime/context.js";
 import { helpForArgs } from "./help.js";
 import { AppError, isAppError } from "../shared/errors.js";
 import { writeJson } from "../shared/json.js";
 import { archiveProject, getProjectStatus, migrateProjectIds, registerProject, resolveProject } from "../services/projects.js";
 import { cancelProtocol, getProtocolBlockers, getProtocolStatus, getReadyProtocols, implementProtocol, readyForMerge, registerProtocol, requireProtocol, syncProtocolFromRun, transitionProtocol } from "../services/protocols.js";
 import { blockPlanItem, completePlanItem, getPlanStatus, skipPlanItem, startPlanItem } from "../services/plans.js";
-import { cancelMergeQueueJob, claimNextMergeJob, claimMergeBundle, completeMergeBundle, completeMergeJob, failMergeBundle, failMergeJob, getMergeBundleStatus, getMergeQueueStatus, noteMergeJob, waitNextMergeJob } from "../services/merge-queue.js";
+import { cancelMergeQueueJob, claimNextMergeJob, claimMergeJob, claimMergeBundle, completeMergeBundle, completeMergeJob, failMergeBundle, failMergeJob, getMergeBundleStatus, getMergeQueueStatus, noteMergeJob, waitNextMergeJob } from "../services/merge-queue.js";
 import { getMergeWorkerStatus, oneShotMergeClaim, startMergeWorker, stopProjectMergeWorker } from "../services/merge-worker.js";
 import { cleanupApply, cleanupScan } from "../services/cleanup.js";
 import { getCodexHomeStatus, getCodexHooksStatus, handleCodexHook, initCodexHome, installCodexHooks, planCodexHome, printCodexHomeEnv, printCodexHooks, removeCodexHome, removeCodexHooks } from "../services/hooks.js";
@@ -24,12 +24,13 @@ import { attachFlowRunStage, completeFlowRun, completeFlowRunStage, getFlowRunTi
 import { previewNextEntityId } from "../services/ids.js";
 import { validateSchema } from "../services/schema-validation.js";
 import { preflightMemoryPermissions } from "../services/memory-permissions.js";
-import { assessMigrationImpact, planMigration, verifyMigrationReport } from "../services/migrations.js";
+import { applyMigration, assessMigrationImpact, assertUpgradeRunStorageReady, planMigration, verifyMigrationReport } from "../services/migrations.js";
 import { publishProjectSummary } from "../services/project-summary.js";
 import { requireProjectByRoot } from "../services/projects.js";
 import { resolveProjectRoot } from "../storage/paths.js";
-import { doctorEngines, engineInfo, installCurrentEngine, listEngines, resolveEngine, resolveOperationProjectRoot, routeArgsThroughEngine } from "../services/engines.js";
+import { doctorEngines, bindRunEngine, engineInfo, installCurrentEngine, listEngines, resolveEngine, resolveExplicitProjectRoot, resolveOperationProjectRoot, routeArgsThroughEngine } from "../services/engines.js";
 import { preflightCliCompatibility } from "../services/compatibility-preflight.js";
+import { classifyCliOperation, requiresExplicitUpgradeAuthorization } from "../services/cli-operation-classifier.js";
 import { renderWorkerPrompt } from "../services/prompts.js";
 import { finishStage, startStage } from "../services/stage-lifecycle.js";
 const defaultIo = {
@@ -58,20 +59,27 @@ export async function runCli(args, io = defaultIo, env = process.env) {
             io.stdout.write(`${help}\n`);
             return 0;
         }
-        const context = createContext(env);
+        const classification = classifyCliOperation(output.args, env);
+        if (requiresExplicitUpgradeAuthorization(output.args) && classification.mode !== "mb_upgrade") {
+            throw new AppError("upgrade_authorization_required", "This mb-upgrade command requires the explicit mb-upgrade authorization marker and allowlisted target context", 1, {
+                operation: classification.operation,
+                required_marker: "DD_FLOW_COMPATIBILITY_MODE=mb-upgrade"
+            });
+        }
+        const routerContext = createRouterContext(env);
         emitHumanProgress(io, output, progress, "start");
-        const scopeProjectRoot = resolveOperationProjectRoot(context, output.args);
-        const routed = await routeArgsThroughEngine(context, output.args, io, io.stdin, env, scopeProjectRoot);
+        const scopeProjectRoot = resolveProjectRootBeforeRouting(output.args, env);
+        const routed = await routeArgsThroughEngine(routerContext, output.json ? [...output.args, "--json"] : output.args, io, io.stdin, env, scopeProjectRoot);
         if (routed?.routed && !routed.inProcess) {
             emitHumanProgress(io, output, progress, "done");
             return routed.exitCode;
         }
         const dispatchContext = routed?.inProcess
-            ? createContext({ ...env, DD_FLOW_ENGINE_MODE: "1", DD_FLOW_ENGINE_HOME: "in-process", DD_FLOW_ROUTED_FROM: getCliVersionReport().cli.version })
-            : context;
+            ? createContext({ ...env, DD_FLOW_ENGINE_MODE: "1", DD_FLOW_ENGINE_HOME: "in-process", DD_FLOW_ROUTED_FROM: getCliVersionReport().cli.version }, databaseModeForCommand(output.args, classification))
+            : createContext(env, databaseModeForCommand(output.args, classification));
         preflightCliCompatibility(dispatchContext, output.args, env, scopeProjectRoot);
-        const result = await dispatch(output.args, dispatchContext, io, scopeProjectRoot);
-        const refreshWarnings = refreshDashboardsAfterMutation(context, output.args, result, scopeProjectRoot);
+        const result = await dispatch(output.args, dispatchContext, io, scopeProjectRoot, classification);
+        const refreshWarnings = refreshDashboardsAfterMutation(dispatchContext, output.args, result, scopeProjectRoot);
         const resultWithWarnings = addWarnings(result, refreshWarnings);
         emitHumanProgress(io, output, progress, "done");
         const payload = attachProgress(resultWithWarnings, progress, output);
@@ -94,6 +102,34 @@ export async function runCli(args, io = defaultIo, env = process.env) {
         return isAppError(error) ? error.exitCode : 1;
     }
 }
+function resolveProjectRootBeforeRouting(args, env) {
+    const explicit = resolveExplicitProjectRoot(args);
+    if (explicit)
+        return explicit;
+    try {
+        // Router identity lookup is read-only; it must not initialize or migrate runtime storage.
+        return resolveOperationProjectRoot(createContext(env, "read_existing"), args);
+    }
+    catch {
+        return null;
+    }
+}
+function databaseModeForCommand(args, classification) {
+    const [family, command] = args;
+    if (family === "engine" ||
+        family === "version" ||
+        family === "schema" ||
+        family === "canon" && command === "resolve" ||
+        classification.mode === "read_only_diagnostics" ||
+        classification.mode === "mb_upgrade" && (family === "status" ||
+            family === "engine" ||
+            family === "migration" && ["impact", "plan", "report", "verify", "apply"].includes(command ?? "") ||
+            family === "memory" && command === "permissions" ||
+            family === "dashboard" && ["data", "open"].includes(command ?? "") ||
+            family === "session" && command === "status"))
+        return "read_existing";
+    return "initialize";
+}
 function renderHumanError(payload) {
     const lines = [`dd-flow: ${payload.error.message}`];
     const details = recordObject(payload.error.details);
@@ -380,11 +416,11 @@ function stringValue(value) {
 function shortSha(value) {
     return value ? value.slice(0, 12) : "unknown";
 }
-async function dispatch(args, context, io, scopeProjectRoot = null) {
+async function dispatch(args, context, io, scopeProjectRoot = null, classification = classifyCliOperation(args, context.env)) {
     const [family, command, ...rest] = args;
     const parsed = parseArgs(rest);
     if (family === "engine") {
-        return dispatchEngine(context, command, parsed);
+        return dispatchEngine(context, command, parsed, classification);
     }
     if (family === "status") {
         const rootParsed = parseArgs([command ?? "", ...rest]);
@@ -597,13 +633,13 @@ async function dispatch(args, context, io, scopeProjectRoot = null) {
         return dispatchDashboard(context, command, parsed);
     }
     if (family === "schema") {
-        return dispatchSchema(command, parsed);
+        return dispatchSchema(context, command, parsed);
     }
     if (family === "memory") {
         return dispatchMemory(command, parsed);
     }
     if (family === "migration") {
-        return dispatchMigration(context, command, parsed);
+        return dispatchMigration(context, command, parsed, classification);
     }
     if (family === "codex" && command === "hooks") {
         return dispatchCodexHooks(context, parsed);
@@ -619,7 +655,7 @@ async function dispatch(args, context, io, scopeProjectRoot = null) {
     }
     throw new AppError("usage", `Unknown command: ${args.join(" ") || "<empty>"}`, 2);
 }
-function dispatchEngine(context, command, parsed) {
+function dispatchEngine(context, command, parsed, classification) {
     if (command === "install") {
         return installCurrentEngine(context, { force: hasOption(parsed, "force") });
     }
@@ -630,14 +666,32 @@ function dispatchEngine(context, command, parsed) {
         return engineInfo(context, { packageName: optionalOption(parsed, "package"), version: optionalOption(parsed, "version") });
     }
     if (command === "resolve") {
-        return resolveEngine(context, { projectRoot: optionalOption(parsed, "project-root") ?? optionalOption(parsed, "root") });
+        return resolveEngine(context, {
+            projectRoot: optionalOption(parsed, "project-root") ?? optionalOption(parsed, "root"),
+            env: context.env,
+            classification
+        });
     }
     if (command === "doctor") {
-        return doctorEngines(context, { projectRoot: optionalOption(parsed, "project-root") ?? optionalOption(parsed, "root") });
+        return doctorEngines(context, {
+            projectRoot: optionalOption(parsed, "project-root") ?? optionalOption(parsed, "root"),
+            env: context.env,
+            classification
+        });
+    }
+    if (command === "bind-run") {
+        return bindRunEngine(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            runId: requiredPosition(parsed, 0, "run-id"),
+            packageName: optionalOption(parsed, "package"),
+            engineVersion: requiredOption(parsed, "engine-version"),
+            integrityChecksum: optionalOption(parsed, "integrity-checksum"),
+            reason: requiredOption(parsed, "reason")
+        });
     }
     throw new AppError("usage", `Unknown engine command: ${command ?? "<empty>"}`, 2);
 }
-function dispatchMigration(context, command, parsed) {
+function dispatchMigration(context, command, parsed, classification) {
     if (command === "impact")
         return assessMigrationImpact(context, { projectRoot: requiredOption(parsed, "project-root"), ...(optionalOption(parsed, "target-version") ? { targetVersion: optionalOption(parsed, "target-version") } : {}), ...(optionalOption(parsed, "mode") ? { mode: optionalOption(parsed, "mode") } : {}) });
     if (command === "plan" || command === "report") {
@@ -648,12 +702,26 @@ function dispatchMigration(context, command, parsed) {
             runId: optionalOption(parsed, "run"),
             backupPath: optionalOption(parsed, "backup-path"),
             backupCreatedAt: optionalOption(parsed, "backup-created-at"),
-            allowActive: parseOptionalBoolean(optionalOption(parsed, "allow-active"), "allow-active") ?? false
+            allowActive: false,
+            classification
         });
     }
     if (command === "verify") {
         return verifyMigrationReport(context, { file: requiredOption(parsed, "file") });
     }
+    if (command === "apply") {
+        return applyMigration(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            sourceVersion: optionalOption(parsed, "source-version"),
+            targetVersion: optionalOption(parsed, "target-version"),
+            runId: optionalOption(parsed, "run"),
+            backupPath: optionalOption(parsed, "backup-path"),
+            backupCreatedAt: optionalOption(parsed, "backup-created-at"),
+            reportFile: optionalOption(parsed, "file"),
+            allowActive: false,
+            classification
+        });
+    }
     throw new AppError("usage", `Unknown migration command: ${command ?? "<empty>"}`, 2);
 }
 function dispatchCanon(context, command, parsed) {
@@ -682,6 +750,14 @@ function dispatchMergeQueue(context, command, parsed, scopeProjectRoot) {
             workspacePath: workspacePathOption(parsed)
         });
     }
+    if (command === "claim") {
+        return claimMergeJob(context, {
+            protocolId: requiredPosition(parsed, 0, "protocol-id"),
+            projectRoot: requiredOptionOrScope(parsed, scopeProjectRoot, "project-root"),
+            workerId: requiredWorkerId(parsed),
+            workspacePath: workspacePathOption(parsed)
+        });
+    }
     if (command === "wait-next") {
         return waitNextMergeJob(context, {
             projectRoot: requiredOptionOrScope(parsed, scopeProjectRoot, "project-root"),
@@ -887,6 +963,9 @@ function dispatchSession(context, command, parsed) {
 }
 function dispatchRun(context, command, parsed) {
     if (command === "start") {
+        if (optionalOption(parsed, "flow-kind") === "mb-upgrade") {
+            assertUpgradeRunStorageReady(context, requiredOption(parsed, "project-root"));
+        }
         const protocolOverrides = readOptionalJsonFile(optionalOption(parsed, "protocol-override-file"));
         return startFlowRun(context, {
             projectRoot: requiredOption(parsed, "project-root"),
@@ -1144,7 +1223,7 @@ function withDashboardGuidance(action, target, result, options = {}) {
         related_commands: relatedDashboardCommands(action, target.kind)
     };
 }
-function dispatchSchema(command, parsed) {
+function dispatchSchema(context, command, parsed) {
     if (command === "validate") {
         const schemaDir = optionalOption(parsed, "schema-dir");
         const projectRoot = optionalOption(parsed, "project-root");
@@ -1152,7 +1231,8 @@ function dispatchSchema(command, parsed) {
             schemaName: requiredOption(parsed, "schema"),
             file: requiredOption(parsed, "file"),
             ...(schemaDir ? { schemaDir } : {}),
-            ...(projectRoot ? { projectRoot } : {})
+            ...(projectRoot ? { projectRoot } : {}),
+            ddFlowHome: context.ddFlowHome
         });
     }
     throw new AppError("usage", `Unknown schema command: ${command ?? "<empty>"}`, 2);
@@ -1679,7 +1759,7 @@ function projectRootForLaneMutation(command, parsed) {
     return ["acquire", "heartbeat", "release", "wait-acquire"].includes(action) ? requiredOption(parsed, "project-root") : undefined;
 }
 function projectRootForMergeQueueMutation(context, command, parsed) {
-    if (["next", "wait-next"].includes(command ?? "")) {
+    if (["next", "wait-next", "claim"].includes(command ?? "")) {
         return requiredOption(parsed, "project-root");
     }
     if (["complete", "fail", "cancel"].includes(command ?? "")) {
@@ -1700,7 +1780,7 @@ function isScopedProtocolMutation(family, command) {
     if (family === "worktree")
         return ["create", "bootstrap", "close"].includes(command ?? "");
     if (family === "merge-queue")
-        return ["complete", "note", "fail", "cancel"].includes(command ?? "");
+        return ["claim", "complete", "note", "fail", "cancel"].includes(command ?? "");
     return false;
 }
 function projectRootFromResult(result) {

package/dist/domain/flow-contract.js

@@ -64,6 +64,17 @@ export function loadProjectFlowContract(projectRoot) {
     if (!contractPath) {
         return defaultFlowContract;
     }
+    return loadFlowContractFile(contractPath);
+}
+/**
+ * Canonical-only flows execute against the pinned canonical contract before
+ * the target project flow pack is synchronized. Keep this path explicit so a
+ * stale project-local contract cannot become the upgrade RUN authority.
+ */
+export function loadCanonicalFlowContract(flowRoot) {
+    return loadFlowContractFile(path.join(flowRoot, "flow-contract.json"));
+}
+function loadFlowContractFile(contractPath) {
     try {
         const value = readFlowContractObject(contractPath);
         validateFlowContractStructure(value);

package/dist/runtime/context.js

@@ -1,10 +1,16 @@
 import { getDatabase } from "../storage/database.js";
 import { resolveDdFlowHome } from "../storage/paths.js";
-export function createContext(env) {
+export function createRouterContext(env) {
+    return {
+        ddFlowHome: resolveDdFlowHome(env),
+        now: () => new Date().toISOString()
+    };
+}
+export function createContext(env, mode = "initialize") {
     const ddFlowHome = resolveDdFlowHome(env);
     return {
         ddFlowHome,
-        db: getDatabase(ddFlowHome),
+        db: getDatabase(ddFlowHome, mode),
         env,
         now: () => new Date().toISOString()
     };

package/dist/schemas/code-stage-report.schema.json

@@ -124,10 +124,15 @@
     "run": {
       "type": "object",
       "additionalProperties": true,
-      "required": ["run_id", "run_state"],
+      "required": ["run_id"],
+      "anyOf": [
+        {"required": ["run_state"]},
+        {"required": ["run_index"]}
+      ],
       "properties": {
         "run_id": { "type": "string", "pattern": "^RUN-[0-9]{3}-[a-z0-9]+(?:-[a-z0-9]+)*$" },
-        "run_state": { "type": "string", "minLength": 1 }
+        "run_state": { "type": "string", "minLength": 1 },
+        "run_index": { "type": "string", "minLength": 1 }
       }
     },
     "stage": {

package/dist/schemas/engine-manifest.schema.json

@@ -44,6 +44,28 @@
         "items": { "type": "string", "minLength": 1 }
       }
     },
+    "schema_registry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schema_id", "entries"],
+      "properties": {
+        "schema_id": { "const": "dd-flow/engine-schema-registry@1" },
+        "entries": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["name", "id", "path", "checksum"],
+            "properties": {
+              "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+              "id": { "type": "string", "minLength": 1 },
+              "path": { "type": "string", "pattern": "^dist/schemas/[a-z0-9][a-z0-9-]*\\.schema\\.json$" },
+              "checksum": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+            }
+          }
+        }
+      }
+    },
     "integrity": {
       "type": "object",
       "additionalProperties": false,

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

@@ -123,6 +123,7 @@
         "expected": {"type": "array", "items": {"type": "string"}},
         "observed": {"type": "array", "items": {"type": "string"}},
         "missing": {"type": "array", "items": {"type": "string"}},
+        "diagnostics": {"type": "array", "items": {"type": "string"}},
         "reason": {"type": "string"}
       }
     },

package/dist/schemas/mb-upgrade-migration-report.schema.json

@@ -70,12 +70,14 @@
     },
     "backup": {
       "type": "object",
-      "required": ["status", "path", "created_at", "rollback_route"],
+      "required": ["status", "path", "created_at", "rollback_route", "size_bytes", "sha256"],
       "additionalProperties": true,
       "properties": {
         "status": { "enum": ["present", "planned", "missing"] },
         "path": { "type": ["string", "null"] },
         "created_at": { "type": ["string", "null"] },
+        "size_bytes": { "type": ["integer", "null"], "minimum": 1 },
+        "sha256": { "type": ["string", "null"], "pattern": "^[a-f0-9]{64}$" },
         "rollback_route": { "type": "string", "minLength": 1 }
       }
     },

package/dist/schemas/merge-stage-report-legacy-0.4.2.schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "dd-flow/merge-stage-report@2/engine-0.4.2",
+  "title": "Merge stage report emitted by dd-flow engine 0.4.2",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["schema_id", "run", "stage", "project", "subject", "overall", "breadcrumbs", "implemented_goals", "acceptance_scenarios", "changed_files", "checks", "review", "review_gates", "defs"],
+  "properties": {
+    "schema_id": { "const": "dd-flow/merge-stage-report@2" },
+    "run": { "type": "object", "required": ["run_id", "run_index"], "properties": { "run_id": { "type": "string", "pattern": "^RUN-[0-9]{3}-[a-z0-9]+(?:-[a-z0-9]+)*$" }, "run_index": { "type": "string", "minLength": 1 } } },
+    "stage": { "type": "object", "required": ["name", "dir", "status"] },
+    "project": { "type": "object", "required": ["id", "title"] },
+    "subject": { "type": "object", "required": ["id", "title"] },
+    "overall": { "type": "object", "required": ["verdict", "summary", "next_action"], "properties": { "verdict": { "enum": ["accepted", "blocked", "failed"] }, "summary": { "type": "string", "minLength": 1 }, "next_action": { "type": "string", "minLength": 1 } } },
+    "breadcrumbs": { "type": "array" },
+    "implemented_goals": { "type": "array" },
+    "acceptance_scenarios": { "type": "array" },
+    "changed_files": { "type": "array" },
+    "checks": { "type": "array" },
+    "review": { "type": "object" },
+    "review_gates": { "type": "array" },
+    "defs": { "type": "array" }
+  }
+}

package/dist/schemas/run-engine-binding.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "dd-flow/run-engine-binding@1",
+  "title": "Immutable RUN engine binding",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_id", "run_id", "project_root", "bound_at", "source", "reason", "engine", "probe"],
+  "properties": {
+    "schema_id": {"const": "dd-flow/run-engine-binding@1"},
+    "run_id": {"type": "string", "pattern": "^RUN-[0-9]+-[a-z0-9][a-z0-9-]*$"},
+    "project_root": {"type": "string", "minLength": 1},
+    "bound_at": {"type": "string", "format": "date-time"},
+    "source": {"enum": ["run_creation", "legacy_recovery"]},
+    "reason": {"type": "string", "minLength": 1},
+    "engine": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["package_name", "package_version", "engine_version", "integrity_checksum", "snapshot_root"],
+      "properties": {
+        "package_name": {"type": "string", "minLength": 1},
+        "package_version": {"type": "string", "minLength": 1},
+        "engine_version": {"type": "string", "minLength": 1},
+        "integrity_checksum": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
+        "snapshot_root": {"type": "string", "minLength": 1}
+      }
+    },
+    "probe": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "command"],
+      "properties": {
+        "status": {"enum": ["not_required", "passed"]},
+        "command": {"type": ["string", "null"]}
+      }
+    }
+  }
+}

package/dist/schemas/stage-prompt.schema.json

@@ -23,13 +23,13 @@
     "stage": {"type": "string", "minLength": 1},
     "generated_at": {"type": "string", "format": "date-time"},
     "prompt_path": {"type": "string", "minLength": 1},
-    "sections": {"type": "array", "minItems": 8, "maxItems": 8, "items": {"enum": ["stage_identity", "authoritative_runtime_facts", "preflight", "task_intake", "applicable_instructions", "required_context", "work_contract", "completion_contract"]}},
+    "sections": {"const": ["stage_identity", "authoritative_runtime_facts", "preflight", "task_intake", "applicable_instructions", "required_context", "work_contract", "completion_contract"]},
     "aliases": {"type": "object", "required": ["project", "workspace", "run", "stage", "protocol", "intake"], "additionalProperties": {"type": "string"}},
     "write_boundary": {"type": "object", "required": ["current", "archive", "archive_writable"], "properties": {"current": {"const": "@stage"}, "archive": {"pattern": "try-[0-9]{3}"}, "archive_writable": {"const": false}}, "additionalProperties": false},
     "source_fragments": {"type": "array", "items": {"type": "string", "minLength": 1}},
-    "authoritative_facts": {"type": "object", "additionalProperties": true},
-    "preflight": {"type": "object", "additionalProperties": true},
-    "required_context": {"type": "array", "items": {"type": "string", "minLength": 1}},
+    "authoritative_facts": {"type": "object", "required": ["git", "runtime"], "additionalProperties": true},
+    "preflight": {"type": "object", "required": ["compatibility", "permissions", "session_binding"], "additionalProperties": true},
+    "required_context": {"type": "array", "items": {"type": "object", "additionalProperties": false, "required": ["path", "reason", "stop_condition"], "properties": {"path": {"type": "string", "minLength": 1}, "reason": {"type": "string", "minLength": 1}, "stop_condition": {"type": "string", "minLength": 1}}}},
     "worker_prompt_markdown": {"type": "string", "minLength": 1}
   }
 }

package/dist/services/canon.js

@@ -36,7 +36,21 @@ export function getCanonStatus(context, input = {}) {
     };
 }
 export function resolveCanonRoot(context, input = {}) {
-    const candidates = canonCandidates(context, input);
+    return resolveCanonCandidates(canonCandidates(context, input));
+}
+/** Read only: resolve an explicit/environment/nearby canon without opening DD_FLOW_HOME. */
+export function resolveCanonRootBeforeContext(env, input = {}) {
+    const candidates = [];
+    if (input.explicitRoot)
+        candidates.push(validateCanonCandidate("explicit", input.explicitRoot));
+    else if (env.DD_MEMORYBANK)
+        candidates.push(validateCanonCandidate("env", env.DD_MEMORYBANK));
+    else
+        for (const known of knownCanonRoots())
+            candidates.push(validateCanonCandidate("known", known));
+    return resolveCanonCandidates(uniqueBy(candidates, (candidate) => `${candidate.source}:${candidate.root}`));
+}
+function resolveCanonCandidates(candidates) {
     const validCandidates = candidates.filter((candidate) => candidate.valid && candidate.realpath);
     const uniqueValid = uniqueBy(validCandidates, (candidate) => candidate.realpath ?? candidate.root);
     const blockers = candidates.flatMap((candidate) => candidate.blockers);