@deksden-com/dd-flow-cli 0.3.1 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @deksden-com/dd-flow-cli
 
+## 0.4.1
+
+### Patch Changes
+
+- Preserve `--project-root` through engine routing, compatibility preflight, protocol services, nested lookups, merge-queue commands, and post-mutation dashboard refresh. Duplicate rootless protocol ids fail closed without side effects, while successful mutations remain successful when an optional dashboard projection fails.
+
+- Include production dependencies in installed engine snapshots, so a routed CLI works outside the source checkout.
+
+## Unreleased
+
+### Patch Changes
+
+- Make `PRT-*` and `RUN-*` allocation, persistence and resolution project-scoped. SQLite migrates legacy global primary keys without renumbering ids, including databases whose columns were appended in historical order; duplicate full ids may coexist across projects, and ambiguous context-free protocol lookup fails closed with project candidates.
+
+- Allow `prompt render` to preserve validated RUN-local `required_read` and discovery references through `run://<relative-path>`, while keeping write scopes project-local and rejecting traversal or environment-secret paths.
+
+## 0.4.0
+
+### Minor Changes
+
+- Add branch/workspace protocol context for agents: `protocol branch-status`, `branch_context` in protocol and merge JSON outputs, and branch bundle status with eligible, not-ready and claimed protocol lists.
+
+  Add `merge bundle status|claim|complete|fail` commands so a merge worker can integrate one feature branch containing multiple ready protocols under the existing merge lane lock.
+
+### Patch Changes
+
+- cfdcf1d: Fix compatibility status reporting so selected compatible engines advertise `normal_write` in `allowed_modes`; blocked operations are now reported only when a write is actually blocked by missing or incompatible engine resolution.
+
 ## 0.3.1
 
 ### Patch Changes

package/README.md

@@ -72,17 +72,33 @@ Register and inspect a protocol:
 
 ```bash
 dd-flow protocol register HANDSHAKE-001 --project-root "$PWD" --json
-dd-flow protocol status PRT-HANDSHAKE-001 --json
+dd-flow protocol status PRT-HANDSHAKE-001 --project-root "$PWD" --json
 ```
 
 Attach and update a plan:
 
 ```bash
-dd-flow plan set PRT-HANDSHAKE-001 --file plan.json --json
-dd-flow plan item start PRT-HANDSHAKE-001 P1 --json
-dd-flow plan item done PRT-HANDSHAKE-001 P1 --summary "Implemented" --evidence "pnpm test" --json
+dd-flow plan set PRT-HANDSHAKE-001 --project-root "$PWD" --file plan.json --json
+dd-flow plan item start PRT-HANDSHAKE-001 P1 --project-root "$PWD" --json
+dd-flow plan item done PRT-HANDSHAKE-001 P1 --project-root "$PWD" --summary "Implemented" --evidence "pnpm test" --json
 ```
 
+Render a bounded prompt for one delegated plan item after its RUN stage is attached:
+
+```bash
+dd-flow prompt render \
+  --project-root "$PWD" \
+  --run RUN-001-example \
+  --stage code \
+  --plan-item P2 \
+  --profile code_implementation \
+  --json
+```
+
+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.
+
 Human help is available for the operator-facing command groups:
 
 ```bash
@@ -178,7 +194,7 @@ dd-flow lane lock release --project-root "$PROJECT_ROOT" --lane direct-main --wo
 Prompts enqueue protocols only after explicit readiness signals exist:
 
 ```bash
-dd-flow protocol ready-for-merge PRT-... --json
+dd-flow protocol ready-for-merge PRT-... --project-root "$PROJECT_ROOT" --json
 dd-flow merge-queue status --project-root "$PROJECT_ROOT" --json
 ```
 
@@ -203,8 +219,8 @@ Merge queue JSON uses `queue_item`, `protocol`, and `claim` as the primary queue
 Complete or fail the claimed job:
 
 ```bash
-dd-flow merge-queue complete PRT-... --worker-id "$WORKER_ID" --path "$MERGE_WORKSPACE" --summary "merged locally" --json
-dd-flow merge-queue fail PRT-... --worker-id "$WORKER_ID" --path "$MERGE_WORKSPACE" --reason "conflict requires owner" --requeue true --json
+dd-flow merge-queue complete PRT-... --project-root "$PROJECT_ROOT" --worker-id "$WORKER_ID" --path "$MERGE_WORKSPACE" --summary "merged locally" --json
+dd-flow merge-queue fail PRT-... --project-root "$PROJECT_ROOT" --worker-id "$WORKER_ID" --path "$MERGE_WORKSPACE" --reason "conflict requires owner" --requeue true --json
 ```
 
 Successful `merge-queue complete` is terminal for the protocol runtime: it writes `stage: closed`, `status: closed`, and `next_action: none`. Post-complete cleanup can still update the queue reason with `merge-queue note`, but dashboards must no longer show the protocol as active work.
@@ -212,8 +228,8 @@ Successful `merge-queue complete` is terminal for the protocol runtime: it write
 Cancel stale or intentionally abandoned queue work explicitly:
 
 ```bash
-dd-flow merge-queue cancel PRT-... --reason "abandoned rerun" --json
-dd-flow merge-queue cancel PRT-... --worker-id "$WORKER_ID" --path "$MERGE_WORKSPACE" --reason "owner cancelled claimed job" --json
+dd-flow merge-queue cancel PRT-... --project-root "$PROJECT_ROOT" --reason "abandoned rerun" --json
+dd-flow merge-queue cancel PRT-... --project-root "$PROJECT_ROOT" --worker-id "$WORKER_ID" --path "$MERGE_WORKSPACE" --reason "owner cancelled claimed job" --json
 ```
 
 Flow sessions are registered explicitly with `dd-flow session register`; merge queue commands use `--worker-id` only. Codex prompts should prefer a JSON payload file:

package/dist/build-info.json

@@ -1,11 +1,11 @@
 {
   "cli_package": "@deksden-com/dd-flow-cli",
-  "cli_version": "0.3.1",
-  "cli_commit": "b677e824e7d3b1e6553e7963eeceeb1db02e86db",
-  "built_at": "2026-07-03T20:02:54.356Z",
+  "cli_version": "0.4.1",
+  "cli_commit": "6f85c042645e0f779824ec71b9aef0a68830874d",
+  "built_at": "2026-08-08T21:51:37.203Z",
   "built_with_canon": {
-    "version": "2.9.0",
-    "commit": "7e8b51c1321e290d18df3572d6ab26ed32b85403",
+    "version": "2.17.0",
+    "commit": "bab97fce96dc6b240c577c38b9d69e17b08fd471",
     "flow_contract": "dd-flow-canonical-2026-06",
     "repo_root": "/Users/deksden/Documents/_Projects/dd-memorybank",
     "memorybank_root": "/Users/deksden/Documents/_Projects/dd-memorybank/.memory-bank",

package/dist/cli/help.js

@@ -18,13 +18,14 @@ Core commands:
   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 plan/report/verify  Prepare and verify mb-upgrade runtime migration evidence.
+  migration impact/plan/report/verify Assess release impact and prepare mb-upgrade migration evidence.
   cleanup scan/apply            Detect and repair stale local runtime state.
-  run start/status/list         Track concrete flow executions and stage artifacts.
+  run start/status/list/timeline/usage/flags Track concrete flow executions, timing, source-aware usage and RUN-local flow flags.
   id next                       Preview next typed ids for protocol or run allocation.
   plan set/status/item          Attach and update protocol plans.
+  prompt render                 Render one bounded, RUN-local worker launch prompt.
   lane workspace/lock/status    Manage shared workspace lanes and leases.
-  merge status/one-shot         Inspect or claim one merge job from the current session.
+  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.
   session register/status/stop  Register flow sessions and stop workers.
@@ -68,7 +69,7 @@ Usage:
   dd-flow version --json
   dd-flow --version
 
-version reports the installed dd-flow CLI package version from package metadata. Use status for richer canon/project compatibility diagnostics.
+version reports the installed dd-flow CLI package version from package metadata. Use status for richer canon/project compatibility diagnostics. Status remains read-only when a project flow contract is invalid and reports its exact error path plus a repair/upgrade validation command.
 
 Examples:
   dd-flow version
@@ -125,7 +126,7 @@ Usage:
 
 Discovery order is explicit --root, then DD_MEMORYBANK, then the globally registered runtime value in DD_FLOW_HOME, then known nearby dd-memorybank checkouts from the current working directory. Explicit --root is the only source considered for that command. If multiple different valid canonical checkouts are found, resolve fails closed with blockers so the caller chooses intentionally.
 
-A valid canonical root contains dd-flow/README.md, mbb/index.md, protocol/index.md, and canonical-only entrypoints such as dd-flow/mb-init.md, dd-flow/mb-upgrade.md, dd-flow/mb-upgrade-review.md, and dd-flow/mb-distill.md.
+A valid canonical root contains dd-flow/README.md, mbb/index.md, protocol/index.md, and canonical-only entrypoints such as dd-flow/mb-init.md, dd-flow/mb-upgrade.md, and dd-flow/mb-distill.md. Current canon runs mb-upgrade review as the 05-review stage inside mb-upgrade, not as a top-level mb-upgrade-review.md entrypoint.
 
 Examples:
   dd-flow canon register --root "$DD_MEMORYBANK" --json
@@ -137,15 +138,19 @@ Examples:
         `dd-flow run - track concrete flow executions
 
 Usage:
-  dd-flow run start --project-root <root> [--workspace-root <checkout>] --flow-kind <kind> --subject-type <type> --subject-id <id> --slug <slug> [--next-action <text>] --json
+  dd-flow run start --project-root <root> [--workspace-root <checkout>] --flow-kind <kind> --subject-type <type> --subject-id <id> --slug <slug> [--preset compact|normal|full] [--task-profile-file <file>] [--protocol-override-file <file>] [--flag key=value] [--next-action <text>] --json
   dd-flow id next --type protocol|run --project-root <root> --slug <slug> --json
-  dd-flow run status <RUN-ID|RUN-NNN> --project-root <root> --json
+  dd-flow run status <RUN-ID|RUN-short-id> --project-root <root> --json
   dd-flow run list --project-root <root> --json
-  dd-flow run attach-stage <RUN-ID|RUN-NNN> --project-root <root> --stage <name> --dir <NN-stage-slug> --status <status> [--data-schema-id <id>] --json
-  dd-flow run complete-stage <RUN-ID|RUN-NNN> --project-root <root> --stage <name> --status <status> [--stage-report <path>] [--data <path>] [--data-schema-id <id>] [--report <path>] [--alias <path>] --json
-  dd-flow run complete <RUN-ID|RUN-NNN> --project-root <root> --status done|blocked|cancelled|failed [--verdict <text>] [--next-action <text>] --json
+  dd-flow run timeline <RUN-ID|RUN-short-id> --project-root <root> [--hide stages|events|sessions|usage|artifacts] --json
+  dd-flow run usage <RUN-ID|RUN-short-id> --project-root <root> [--group-by session|role|stage|aspect|plan-item] --json
+  dd-flow run flags status <RUN-ID|RUN-short-id> --project-root <root> --json
+  dd-flow run flags revise <RUN-ID|RUN-short-id> --project-root <root> --expected-revision <n> --idempotency-key <key> [--preset <name>] [--flag key=value] [--flag key=value] [--allow-downgrade --reason <text>] --json
+  dd-flow run attach-stage <RUN-ID|RUN-short-id> --project-root <root> --stage <name> --dir <NN-stage-slug> --status <status> [--data-schema-id <id>] --json
+  dd-flow run complete-stage <RUN-ID|RUN-short-id> --project-root <root> --stage <name> --status <status> [--stage-report <path>] [--data <path>] [--data-schema-id <id>] [--report <path>] [--alias <path>] --json
+  dd-flow run complete <RUN-ID|RUN-short-id> --project-root <root> --status done|blocked|cancelled|failed [--verdict <text>] [--next-action <text>] --json
 
-RUN-* is the execution envelope for one concrete flow launch. Semantic truth remains in protocol, experiment, DEF, scenario, evidence, and Memory Bank documents. New run artifacts are stored under DD_FLOW_HOME/projects/<PRJ-ID-slug>/runs/<RUN-ID-slug>/ with run.json and run-index.json together. Legacy <workspace>/.tasks/dd-flow-runs/<RUN-ID-slug>/ indexes remain readable.
+RUN-* is the execution envelope for one concrete flow launch. Semantic truth remains in protocol, experiment, DEF, scenario, evidence, and Memory Bank documents. New run artifacts are stored under DD_FLOW_HOME/projects/<PRJ-ID-slug>/runs/<RUN-ID-slug>/ with run.json, run-index.json and an append-only timeline together. Timeline is the compact full run report: summary is always present, while --hide may suppress bulky sections. The run usage command reconciles registered local Codex transcript counters before reporting; unavailable data is explicit rather than zero.
 
 Examples:
   dd-flow run start --project-root "$PWD" --flow-kind mb_sdlc --subject-type protocol --subject-id PRT-001-demo --slug demo --json
@@ -160,7 +165,7 @@ Examples:
 Usage:
   dd-flow id next --type protocol|run --project-root <root> --slug <slug> --json
 
-id next is read-only: it scans runtime records and known project files, then returns the next available TYPE-NNN-slug without reserving it. Use run start or protocol register to create durable state.
+id next is read-only: RUN previews use control-plane runtime records for the selected project, while protocol previews also consider that project's protocol files. Legacy date-based protocol ids such as PRT-2026-05-25-example are historical names and do not participate in typed sequence allocation. The command returns the project-local monotonic max(TYPE-<sequence>)+1 without reusing sequence gaps. It does not reserve the id. Use run start or protocol register to create durable state. PRT and RUN ids are resolved by project plus id; ambiguous context-free protocol lookup fails closed with project candidates.
 
 Examples:
   dd-flow id next --type protocol --project-root "$PWD" --slug demo --json
@@ -172,26 +177,28 @@ Examples:
 
 Usage:
   dd-flow protocol register <handshake-id> --project-root <root> [--workspace-path <checkout>] --json
-  dd-flow protocol status <protocol-id> --json
+  dd-flow protocol status <protocol-id> [--project-root <root>] --json
+  dd-flow protocol branch-status <protocol-id> [--project-root <root>] --json
+  dd-flow protocol branch-status --project-root <root> --path <workspace> --json
   dd-flow protocol ready --project-root <root> --json
   dd-flow protocol blockers <protocol-id> --project-root <root> --json
   dd-flow protocol implement <protocol-id> --project-root <root> [--force --reason <text>] --json
-  dd-flow protocol transition <protocol-id> --to <stage> --payload-file <file> [--force --reason <text>] --json
-  dd-flow protocol sync-from-run <protocol-id> --run <RUN-ID|RUN-NNN> [--target auto|<stage>] --json
-  dd-flow protocol ready-for-merge <protocol-id> --json
-  dd-flow protocol cancel <protocol-id> --reason <text> [--close-sessions true|false] [--cancel-queue true|false] [--release-locks true|false] [--worktree keep|remove] [--force] --json
+  dd-flow protocol transition <protocol-id> [--project-root <root>] --to <stage> --payload-file <file> [--force --reason <text>] --json
+  dd-flow protocol sync-from-run <protocol-id> [--project-root <root>] --run <RUN-ID|RUN-short-id> [--target auto|<stage>] --json
+  dd-flow protocol ready-for-merge <protocol-id> [--project-root <root>] --json
+  dd-flow protocol cancel <protocol-id> [--project-root <root>] --reason <text> [--close-sessions true|false] [--cancel-queue true|false] [--release-locks true|false] [--worktree keep|remove] [--force] --json
 
-ready, blockers and implement read protocol markdown frontmatter plus runtime state. implement is a preflight/guidance command: it never performs implementation, refuses unresolved blocked_by_protocols unless --force --reason is supplied, refuses terminal protocols and reports the expected next prompt/stage. transition validates the snapshotted flow contract stored in protocol runtime state, writes an audit event and updates lifecycle fields from the payload. --json-file is accepted as a compatibility alias for --payload-file. sync-from-run repairs legacy protocol/run mismatch from concrete RUN evidence instead of requiring manual runtime JSON edits.
+ready, blockers and implement read protocol markdown frontmatter plus runtime state. branch-status is read-only and reports the current protocol/workspace branch context: sibling protocols in the same branch/worktree, queue status, active sessions and merge bundle eligibility. implement is a preflight/guidance command: it never performs implementation, refuses unresolved blocked_by_protocols unless --force --reason is supplied, refuses terminal protocols and reports the expected next prompt/stage. transition validates the snapshotted flow contract stored in protocol runtime state, writes an audit event and updates lifecycle fields from the payload. --json-file is accepted as a compatibility alias for --payload-file. sync-from-run repairs legacy protocol/run mismatch from concrete RUN evidence instead of requiring manual runtime JSON edits.
 
-The project_root is the stable project identity used for queues, sessions, lanes, and dashboards. Runtime state is stored under DD_FLOW_HOME/projects/<PRJ-ID-slug>/runtime so feature worktree removal does not break status, cancel, or merge finalization. The optional workspace_path records the concrete checkout where the agent works. With --worktree remove, cancel removes the disposable git worktree recorded in runtime state or worktree records; with --force it also force-deletes the local feature branch when present.`
+The project_root is the stable project identity used for queues, sessions, lanes, and dashboards. Runtime state is stored under DD_FLOW_HOME/projects/<PRJ-ID-slug>/runtime so feature worktree removal does not break status, cancel, or merge finalization. The optional workspace_path records the concrete checkout where the agent works. With --worktree remove, cancel removes the disposable git worktree recorded in runtime state or worktree records; with --force it also force-deletes the local feature branch when present. Rootless protocol-id calls remain compatible only when the id is unique across registered projects; duplicate ids fail closed with ambiguous_protocol.`
     ],
     [
         "transition",
         `dd-flow transition - compatibility alias for protocol transition
 
 Usage:
-  dd-flow transition <protocol-id> --to <stage> --payload-file <file> [--force --reason <text>] --json
-  dd-flow transition <protocol-id> --to <stage> --json-file <file> [--force --reason <text>] --json
+  dd-flow transition <protocol-id> [--project-root <root>] --to <stage> --payload-file <file> [--force --reason <text>] --json
+  dd-flow transition <protocol-id> [--project-root <root>] --to <stage> --json-file <file> [--force --reason <text>] --json
 
 Prefer dd-flow protocol transition in new prompts and scripts. This top-level alias remains for older canonical prompts and experiments.`
     ],
@@ -203,8 +210,8 @@ Usage:
   dd-flow project register --root <root> --json
   dd-flow project status --root <root> --json
   dd-flow project summary --project-root <root> [--write true|false] --json
-  dd-flow project resolve <PRJ-ID|PRJ-NNN> --json
-  dd-flow project archive <PRJ-ID|PRJ-NNN> --reason <text> --json
+  dd-flow project resolve <PRJ-ID|PRJ-short-id> --json
+  dd-flow project archive <PRJ-ID|PRJ-short-id> --reason <text> --json
   dd-flow project archive --root <previous-root-path> --reason <text> --json
   dd-flow project migrate-ids --root <root> [--apply] --json
 
@@ -293,16 +300,29 @@ Related lane commands:
   dd-flow lane lock wait-acquire --project-root "$PWD" --lane merge --worker-id worker-1 --path "$PWD" --timeout 300 --poll-interval 10 --reason "merge worker" --json
   dd-flow lane lock status --project-root "$PWD" --lane merge --json
   dd-flow lane waiter cancel --project-root "$PWD" --lane merge --worker-id worker-1 --reason "session stopped" --json`
+    ],
+    [
+        "prompt",
+        `dd-flow prompt - render auditable worker launch prompts
+
+Usage:
+  dd-flow prompt render --project-root <root> --run <RUN-ID> --stage <stage> (--plan-item <item-id> | --task-file <RUN-local-worker-task.json>) --profile <profile> [--workspace-root <checkout>] --json
+
+The renderer accepts only registered profiles: code_implementation, documentation, verification. A legacy plan item or a RUN-local dd-flow/worker-task@1 manifest supplies the task execution context and semantic spine. The renderer verifies the running RUN stage and workspace, then writes launch-prompt.md, prompt-stack.json and render-report.json under the RUN stage subagents directory. Project sources remain path references; unsafe .env paths and paths outside the project are rejected before artifact creation.`
     ],
     [
         "merge",
         `dd-flow merge - current-session merge entrypoint helpers
 
 Usage:
-  dd-flow merge status --project-root <root> --json
+  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
 
-merge status reports active merge worker, claimed protocols, active merge lane lock and queue state. merge one-shot is status-only when a long-lived worker, claimed protocol or active lock exists; otherwise it acquires the merge lane, claims at most one ready protocol, and returns queue_item/protocol/claim plus legacy job for the shared merge job prompt. If no protocol is ready, it releases the lock and returns queue_item: null and job: null.`
+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",
@@ -323,17 +343,21 @@ 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 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> --worker-id <id> [--path <workspace>] --summary <text> --json
-  dd-flow merge-queue note <protocol-id> --worker-id <id> --summary <text> --json
-  dd-flow merge-queue fail <protocol-id> --worker-id <id> [--path <workspace>] --reason <text> --requeue true|false --json
-  dd-flow merge-queue cancel <protocol-id> --reason <text> [--worker-id <id>] [--path <workspace>] [--force] --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.
 
+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 --worker-id merge-worker --path "$PWD" --summary "merged locally; cleanup follows" --json
-  dd-flow merge-queue note PRT-123 --worker-id merge-worker --summary "merged, pushed, checked, and cleanup completed" --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`
     ],
     [
         "cleanup",
@@ -365,6 +389,7 @@ Usage:
   dd-flow session register --payload-file <file> --json
   dd-flow session register --payload-base64 <payload> --json
   dd-flow session status --project-root <root> [--session-id <id>] [--worker-id <id>] --json
+  dd-flow session usage sync --project-root <root> --session-id <id> --json
   dd-flow session stop --project-root <root> --session-id <id> --reason <text> --json
   dd-flow session stop-worker --project-root <root> --worker-id <id> --reason <text> --json
 
@@ -440,7 +465,7 @@ Dashboards are rendered views of dd-flow state. Markdown remains the compatibili
 Usage:
   dd-flow schema validate --schema <name> --file <json-file> [--project-root <root>] [--schema-dir <dir>] --json
 
-Schema names resolve to <name>.schema.json. Lookup order is --schema-dir, then <project-root>/.memory-bank/dd-flow/schemas/, then <project-root>/dd-flow/schemas/ for canonical checkouts, then bundled CLI schemas. If --project-root is omitted, the current working directory is used. JSON mode writes valid results to stdout and structured validation/usage errors to stderr.`
+Schema names resolve to <name>.schema.json. Lookup order is --schema-dir, then <project-root>/.memory-bank/dd-flow/schemas/, then <project-root>/dd-flow/schemas/ for canonical checkouts, then bundled CLI schemas. Flow-contract validation runs structural checks first and the runtime's shared semantic normalizer second. If --project-root is omitted, the current working directory is used. JSON mode writes valid results to stdout and structured validation/usage errors to stderr.`
     ],
     [
         "schema validate",
@@ -454,6 +479,7 @@ Exit codes:
   2  usage, unknown schema, invalid JSON, or schema validation failure
 
 Examples:
+  dd-flow schema validate --schema flow-contract --file .memory-bank/dd-flow/flow-contract.json --project-root "$PWD" --json
   dd-flow schema validate --schema mb-upgrade-review-data --file .tasks/mb-upgrade-review-2026-06-04-hr-agent/review-data.json --project-root "$PWD" --json
   dd-flow schema validate --schema mb-upgrade-review-data --file review-data.json --schema-dir .memory-bank/dd-flow/schemas`
     ],