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

package/CHANGELOG.md

@@ -0,0 +1,43 @@
+# @deksden-com/dd-flow-cli
+
+## 0.3.1
+
+### Patch Changes
+
+- 16f68a3: Add router-native engine snapshot commands and routed project-command dispatch.
+
+  Also include the runtime/dashboard compatibility wave needed by the current Memory Bank canon:
+  - target-based dashboard `open`/`refresh` commands and related-command help;
+  - persisted FIFO lane waiters and merge wait-acquire specialization;
+  - `migration plan/report/verify` evidence helpers for controlled `mb-upgrade` runtime migrations;
+  - `dd-flow/project-summary@1` publication and global dashboard aggregation from project summaries.
+  - active npm release runbook notes for Changesets-generated changelogs, strict Memory Bank canon build metadata, token-safe publish, local global link and post-publish compatibility verification.
+
+## 0.3.0
+
+### Minor Changes
+
+- Add CLI version preflight support with `dd-flow version`, `dd-flow --version`, `dd-flow version --json`, Memory Bank compatibility verdicts in `dd-flow status`, and an explicit cached npm registry check through `dd-flow status --check-registry`.
+- 565c601: Add static HTML dashboard rendering for global, project, and protocol dashboard pages.
+
+  The dashboard command family now supports `--format html`, a `dashboard data` command, adjacent JSON data files, protocol pages, bundled dashboard schemas, and compatibility with existing markdown dashboards.
+
+- Add `flow_guidance` to status-like protocol/run/project/merge outputs so agents can see current stage, allowed next stages, recommended prompt/action, guard status and missing predecessor evidence without moving semantic planning into the CLI.
+- Store new `RUN-*` artifacts in DD Flow home under `~/.dd-flow/projects/<PRJ-ID>/runs/<RUN-ID>/`, while keeping legacy project `.tasks/dd-flow-runs/<RUN-ID>/` readable as compatibility input.
+- Add protocol-set continuation support: protocol dependency blockers, `protocol ready`, safe `protocol-implement` guidance, blocked-protocol start guards and compact set status data for dashboards.
+- Add `mb-sdlc-review` / `review` flow-kind support, bundled `mb-sdlc-review-report` schema validation, semantic review-report checks and dashboard counters for review runs.
+- Extend dashboard data/rendering for protocol sets, review runs and home-run stage artifacts.
+
+### Patch Changes
+
+- Keep merge queue, protocol runtime and run status in sync when a merge job completes, so agents can verify `closed` protocol state, `merged` queue state and `done/merged` run state without stale `claimed` diagnostics.
+
+## 0.2.0
+
+### Minor Changes
+
+- Expose canonical Memory Bank version visibility in `dd-flow status`, including CLI build metadata, resolved canon metadata, project Memory Bank markers, project flow pack manifest state, drift diagnostics, and the `dd-flow/status-report@1` schema.
+
+### Patch Changes
+
+- 322cae9: Add canonical Memory Bank discovery commands and runtime status output.

package/README.md

@@ -97,6 +97,28 @@ dd-flow codex home --help
 dd-flow worktree --help
 ```
 
+## Engine Router
+
+`dd-flow` is the stable router command. The router keeps immutable engine snapshots in `DD_FLOW_HOME/engines` and selects the compatible engine for project-scoped commands.
+
+Router-native engine commands do not mutate project runtime:
+
+```bash
+dd-flow engine install --json
+dd-flow engine list --json
+dd-flow engine info --json
+dd-flow engine resolve --project-root "$PWD" --json
+dd-flow engine doctor --project-root "$PWD" --json
+```
+
+Old installable engines are installed from the matching published package version without replacing the global router:
+
+```bash
+npx @deksden-com/dd-flow-cli@<version> engine install
+```
+
+Project commands keep using `dd-flow ...`; agents should not call snapshot entrypoints directly.
+
 ## Lanes And Locks
 
 A lane is a named shared operational workspace inside a project. A lane lock is a time-bound ownership lease on that workspace. The CLI enforces one active non-expired lock per project/lane; prompts decide whether a task should use a feature worktree, `direct-main`, or `merge`.
@@ -121,10 +143,20 @@ Inspect lane state:
 ```bash
 dd-flow lane status --project-root "$PROJECT_ROOT" --json
 dd-flow lane lock status --project-root "$PROJECT_ROOT" --lane merge --json
+dd-flow lane waiters --project-root "$PROJECT_ROOT" --lane merge --json
 ```
 
 Branch checks are factual diagnostics. Lock mutation and merge queue claiming validate the registered workspace path mechanically. A mismatch can help a prompt or operator notice the wrong checkout, but the CLI does not decide whether the route is semantically allowed.
 
+Persisted lane waiters let agents wait for exclusive lane ownership without token-level polling:
+
+```bash
+dd-flow lane lock wait-acquire --project-root "$PROJECT_ROOT" --lane merge --worker-id "$WORKER_ID" --path "$WORKSPACE" --timeout 300 --poll-interval 10 --ttl 300 --reason "merge worker" --json
+dd-flow lane waiter cancel --project-root "$PROJECT_ROOT" --lane merge --worker-id "$WORKER_ID" --reason "session stopped" --json
+```
+
+`wait-acquire` creates one queued waiter per `project/lane/worker-id`, preserves FIFO acquisition order, treats same-worker retries idempotently, returns `timed_out` for the command's own timeout, and leaves stale queued waiters for `cleanup scan/apply`.
+
 ## Direct Main Recipe
 
 Use `direct-main` only after the prompt or operator has chosen direct integration work for a small, low-risk task.
@@ -164,7 +196,9 @@ For supervisor-style waiting outside model tokens:
 dd-flow merge-queue wait-next --project-root "$PROJECT_ROOT" --worker-id "$WORKER_ID" --path "$MERGE_WORKSPACE" --timeout 1200 --poll-interval 10 --acquire-lock true --json
 ```
 
-With `--acquire-lock true`, `wait-next` heartbeats the merge lane lock while it waits and releases a lock it acquired itself when the wait times out. Live merge workers should prefer long waits, for example 1200 seconds / 20 minutes, so the agent sleeps inside the CLI process instead of spending model tokens on frequent polling.
+With `--acquire-lock true`, `wait-next` first uses the generic FIFO lane waiter path for `lane=merge`, then heartbeats the merge lane lock while it waits and releases a lock it acquired itself when the wait times out. Live merge workers should prefer long waits, for example 1200 seconds / 20 minutes, so the agent sleeps inside the CLI process instead of spending model tokens on frequent polling.
+
+Merge queue JSON uses `queue_item`, `protocol`, and `claim` as the primary queued/claimed protocol contract. The legacy `job` field remains as a compatibility alias during the migration window.
 
 Complete or fail the claimed job:
 
@@ -206,6 +240,32 @@ dd-flow protocol cancel PRT-... --reason "replaced by fresh run" --close-session
 
 For a stale disposable feature checkout, use `--worktree remove`. The command removes the git worktree recorded either in `worktree_records` or in stable runtime `state.workspace`; with `--force`, it also force-deletes the local feature branch when present. It refuses dirty worktrees without `--force` and refuses to remove the stable project root or the current process working directory.
 
+## mb-upgrade Runtime Migrations
+
+Normal `dd-flow` commands do not migrate project runtime or home data just because a newer router/engine can read an older project. Runtime/home data migrations belong to the explicit canonical `mb-upgrade` contour and need backup evidence, an adjacent migration chain, active-state handling and post-upgrade verification.
+
+Use migration evidence helpers from `mb-upgrade`:
+
+```bash
+dd-flow migration plan --project-root "$PROJECT_ROOT" --source-version "$OLD_MB" --target-version "$NEW_MB" --run "$RUN_ID" --backup-path "$BACKUP" --json
+dd-flow migration report --project-root "$PROJECT_ROOT" --source-version "$OLD_MB" --target-version "$NEW_MB" --run "$RUN_ID" --backup-path "$BACKUP" --json
+dd-flow migration verify --file "$RUN_HOME/03-upgrade/migration-report.json" --json
+```
+
+The report contract is `dd-flow/mb-upgrade-migration-report@1`. A blocked report is valid evidence that upgrade cannot safely mutate runtime yet; it is not permission to bypass active protocols, active runs, merge queue items or lane locks.
+
+## Project Summaries
+
+Global dashboard data should consume compact project summaries instead of scanning deep project runtime directly. Publish the current project's read model with:
+
+```bash
+dd-flow project summary --project-root "$PROJECT_ROOT" --json
+```
+
+The summary is written to `~/.dd-flow/projects/<project-id>/summary/project-summary.json` and uses `dd-flow/project-summary@1`. `dashboard refresh --project <project>` also publishes the summary before rendering dashboards. Use `--write false` to inspect the payload without writing it.
+
+Global dashboard data reads published project summaries and builds one prepared JSON model for the renderer. Compatible summaries become project cards; missing, unreadable or unsupported summaries are listed in `unsupported_projects` with a reason, summary path and install/refresh hint when available. The global dashboard also exposes `supported_summary_versions` and `summary_version_groups` so agents can see which local projects are represented by each summary contract version.
+
 ## Cleanup
 
 Use cleanup when local runtime state is stale after a crash, abandoned rerun, or removed feature worktree. `cleanup scan` is read-only. `cleanup apply` requires an explicit plan file and reason, reports requested/applied/changed/skipped action results, and dirty/destructive worktree actions require `--force --reason`. Worktree record cleanup marks a checkout `removed` only when the path is already absent; if the checkout still exists, the record is closed as `kept` rather than silently deleting files.
@@ -224,22 +284,33 @@ Dashboard markdown is rendered state, not source of truth. Successful state-chan
 
 The dashboard is intentionally compact: it shows the last update time, active protocols/sessions, merge queue summary, active locks, recent outcomes, and missing project roots without dumping full hook payloads into the main view.
 
+Dashboard JSON separates protocol lifecycle from resource coordination. New consumers should read `lifecycle`, `lifecycle_summary`, `resource_summary`, `queued_protocols`, `queue_item`, and `claim` when present. Legacy fields such as `current_stage`, `raw_stage`, `raw_status`, `merge_queue`, and `job` remain available as compatibility aliases or diagnostics during the migration window.
+
 Defaults:
 
 ```text
 project dashboard: .tasks/dd-flow-dashboard.md
 global dashboard:  ~/.dd-flow/dashboard.md
+project HTML:      ~/.dd-flow/projects/<PRJ-ID>/dashboard/project-dashboard.html
+protocol HTML:     ~/.dd-flow/projects/<PRJ-ID>/dashboard/protocols/<PRT-ID>.html
 ```
 
 Useful commands:
 
 ```bash
-dd-flow dashboard render --project-root "$PROJECT_ROOT" --json
-dd-flow dashboard render-global --json
-dd-flow dashboard refresh --project-root "$PROJECT_ROOT" --open false --json
-dd-flow dashboard open --project-root "$PROJECT_ROOT" --viewer cmux --json
+dd-flow dashboard open --json
+dd-flow dashboard refresh --json
+dd-flow dashboard refresh --all --json
+dd-flow dashboard refresh --project PRJ-001 --open false --json
+dd-flow dashboard open --project PRJ-001 --viewer cmux --json
+dd-flow dashboard data --project PRJ-001 --json
 ```
 
+Compatibility forms remain available for older prompts and scripts: `refresh-global`,
+`render-global`, `--project-root`, and `data --global`. Prefer the target-based
+commands above for new automation. `--project` accepts a full project id, short
+id, slug, or registered project root path.
+
 Config keys:
 
 ```bash

package/dist/build-info.json

@@ -1,11 +1,15 @@
 {
   "cli_package": "@deksden-com/dd-flow-cli",
-  "cli_version": "0.2.0",
-  "cli_commit": "8351d94bdeaca22d2fff503fd2b08071c86205cd",
-  "built_at": "2026-06-15T14:46:55.550Z",
+  "cli_version": "0.3.1",
+  "cli_commit": "b677e824e7d3b1e6553e7963eeceeb1db02e86db",
+  "built_at": "2026-07-03T20:02:54.356Z",
   "built_with_canon": {
-    "version": "2.4.0",
-    "commit": "cf1f6d08e8d4775bf14334c6010b479d1c6fd73f",
-    "flow_contract": "dd-flow-canonical-2026-05"
+    "version": "2.9.0",
+    "commit": "7e8b51c1321e290d18df3572d6ab26ed32b85403",
+    "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",
+    "flow_root": "/Users/deksden/Documents/_Projects/dd-memorybank/.memory-bank/dd-flow",
+    "layout": "dot_memory_bank"
   }
 }

package/dist/cli/help.js

@@ -9,21 +9,26 @@ Usage:
   dd-flow <command> --help
 
 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.
   canon register/status/resolve Register and resolve the canonical Memory Bank.
-  project register/status       Register a project and inspect runtime state.
+  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      Register and inspect protocol state.
+  protocol register/status/transition Register, inspect, transition and repair protocol state.
+  migration plan/report/verify  Prepare and verify mb-upgrade runtime migration evidence.
   cleanup scan/apply            Detect and repair stale local runtime state.
   run start/status/list         Track concrete flow executions and stage artifacts.
+  id next                       Preview next typed ids for protocol or run allocation.
   plan set/status/item          Attach and update protocol plans.
   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-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.
-  dashboard render/open/refresh Render markdown project/global dashboards.
+  dashboard data/render/open/refresh Render, refresh, open, and inspect project/global dashboards.
   schema validate             Validate canonical dd-flow JSON data contracts.
   memory permissions preflight Check Memory Bank write/read permissions.
   integration cmux status       Inspect optional cmux integration.
@@ -32,6 +37,9 @@ Core commands:
 
 Examples:
   dd-flow project register --root "$PWD"
+  dd-flow version
+  dd-flow engine install --json
+  dd-flow engine resolve --project-root "$PWD" --json
   dd-flow status --project-root "$PWD" --json
   dd-flow canon register --root "$DD_MEMORYBANK" --json
   dd-flow canon resolve --json
@@ -39,7 +47,9 @@ Examples:
   dd-flow project resolve PRJ-001 --json
   dd-flow project archive PRJ-001 --reason "old missing worktree root" --json
   dd-flow project migrate-ids --root "$PWD" --apply --json
-  dd-flow run start --project-root "$PWD" --flow-kind coding --subject-type protocol --subject-id PRT-001-demo --slug demo --json
+  dd-flow run start --project-root "$PWD" --flow-kind mb_sdlc --subject-type protocol --subject-id PRT-001-demo --slug demo --json
+  dd-flow id next --type protocol --project-root "$PWD" --slug demo --json
+  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
@@ -48,6 +58,44 @@ Examples:
 Default output is human-readable. Use --json for hooks, prompts, scripts and other agent automation; JSON mode never mixes human progress text into stdout.
 
 project_root is the stable repository identity. workspace_path is the concrete checkout where an agent is about to work.`
+    ],
+    [
+        "version",
+        `dd-flow version - print CLI package version
+
+Usage:
+  dd-flow version
+  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.
+
+Examples:
+  dd-flow version
+  dd-flow version --json`
+    ],
+    [
+        "engine",
+        `dd-flow engine - manage router-installed engine snapshots
+
+Usage:
+  dd-flow engine install [--force] --json
+  dd-flow engine list --json
+  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
+
+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:
+
+  npx @deksden-com/dd-flow-cli@<version> engine install
+
+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.
+
+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`
     ],
     [
         "status",
@@ -56,9 +104,12 @@ project_root is the stable repository identity. workspace_path is the concrete c
 Usage:
   dd-flow status [--project-root <root>] --json
   dd-flow status [--root <root>] --json
+  dd-flow status [--project-root <root>] [--check-registry] --json
 
 status reports DD_FLOW_HOME, the requested or current project root, registered project identity when available, and canonical Memory Bank discovery. It does not require the project to be registered and does not mutate state. In JSON mode canon discovery is embedded as a structured assessment so agents can detect missing or ambiguous canon roots without parsing stderr.
 
+By default status does not call the network. Use --check-registry for an explicit cached npm latest check.
+
 Examples:
   dd-flow status --project-root "$PWD" --json
   dd-flow status --json`
@@ -87,18 +138,33 @@ Examples:
 
 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 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 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
 
-RUN-* is the execution envelope for one concrete flow launch. Semantic truth remains in protocol, experiment, DEF, scenario, evidence, and Memory Bank documents. Runtime state is stored under DD_FLOW_HOME/projects/<PRJ-ID-slug>/runtime/runs/<RUN-ID-slug>/, while human-facing artifacts are indexed through <workspace>/.tasks/dd-flow-runs/<RUN-ID-slug>/run-index.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.
 
 Examples:
-  dd-flow run start --project-root "$PWD" --flow-kind coding --subject-type protocol --subject-id PRT-001-demo --slug demo --json
+  dd-flow run start --project-root "$PWD" --flow-kind mb_sdlc --subject-type protocol --subject-id PRT-001-demo --slug demo --json
+  dd-flow id next --type run --project-root "$PWD" --slug demo --json
   dd-flow run attach-stage RUN-001 --project-root "$PWD" --stage plan --dir 01-plan --status running --json
   dd-flow run complete-stage RUN-001 --project-root "$PWD" --stage plan --status done --data 01-plan/stage-report.json --stage-report 01-plan/stage-report.html --report 01-plan/report.md --json`
+    ],
+    [
+        "id",
+        `dd-flow id - preview next typed ids
+
+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.
+
+Examples:
+  dd-flow id next --type protocol --project-root "$PWD" --slug demo --json
+  dd-flow id next --type run --project-root "$PWD" --slug demo --json`
     ],
     [
         "protocol",
@@ -107,10 +173,27 @@ 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 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
 
+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.
+
 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.`
+    ],
+    [
+        "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
+
+Prefer dd-flow protocol transition in new prompts and scripts. This top-level alias remains for older canonical prompts and experiments.`
     ],
     [
         "project",
@@ -119,12 +202,29 @@ The project_root is the stable project identity used for queues, sessions, lanes
 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 archive --root <previous-root-path> --reason <text> --json
   dd-flow project migrate-ids --root <root> [--apply] --json
 
-New registrations use full typed ids such as PRJ-001-dd-flow-playground and short aliases such as PRJ-001. project resolve accepts full id or unique short alias. project archive removes stale or deleted project roots from active dashboards without deleting history. Re-registering an existing root reactivates it. migrate-ids is the explicit transition path for old hash-based local project ids; without --apply it returns a dry-run plan.`
+New registrations use full typed ids such as PRJ-001-dd-flow-playground and short aliases such as PRJ-001. project resolve accepts full id or unique short alias. project summary writes dd-flow/project-summary@1 to the project's home summary directory by default; use --write false to inspect the payload without writing. project archive removes stale or deleted project roots from active dashboards without deleting history. Re-registering an existing root reactivates it. migrate-ids is the explicit transition path for old hash-based local project ids; without --apply it returns a dry-run plan.`
+    ],
+    [
+        "migration",
+        `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 verify --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.
+
+Related commands:
+  dd-flow status --project-root <root> --json
+  dd-flow memory permissions preflight --root <root> --memory-bank .memory-bank --flow mb-upgrade --mode write --json
+  dd-flow dashboard refresh --project <project> --json`
     ],
     [
         "lane",
@@ -132,13 +232,16 @@ New registrations use full typed ids such as PRJ-001-dd-flow-playground and shor
 
 Usage:
   dd-flow lane status --project-root <root> --json
+  dd-flow lane waiters --project-root <root> [--lane <name>] --json
   dd-flow lane workspace <action> [options] --json
   dd-flow lane lock <action> [options] --json
+  dd-flow lane waiter <action> [options] --json
 
 Use lanes when multiple agents might edit or merge through the same workspace. The CLI enforces mechanical ownership only; prompts decide whether a route should use merge, direct-main, or a feature worktree.
 
 Examples:
   dd-flow lane status --project-root "$PWD" --json
+  dd-flow lane waiters --project-root "$PWD" --lane merge --json
   dd-flow lane workspace set --project-root "$PWD" --lane direct-main --path "$PWD" --branch main --json
   dd-flow lane lock status --project-root "$PWD" --lane direct-main --json`
     ],
@@ -166,13 +269,30 @@ Usage:
   dd-flow lane lock release --project-root <root> --lane <name> --worker-id <id> [--path <workspace>] [--lease-token <token>] --reason <text> --json
   dd-flow lane lock status --project-root <root> --lane <name> --json
   dd-flow lane lock wait --project-root <root> --lane <name> --worker-id <id> [--path <workspace>] --timeout <seconds> --poll-interval <seconds> --json
+  dd-flow lane lock wait-acquire --project-root <root> --lane <name> --worker-id <id> [--path <workspace>] --timeout <seconds> --poll-interval <seconds> [--ttl 300] --reason <text> --json
 
-Lock mutation commands validate that --path, or the current working directory when --path is omitted, matches the registered lane workspace. Only the owner can heartbeat or release an active lease. Expired leases can be taken over mechanically and are recorded in audit.
+Lock mutation commands validate that --path, or the current working directory when --path is omitted, matches the registered lane workspace. Only the owner can heartbeat or release an active lease. wait-acquire creates a persisted FIFO waiter before acquiring the lock. Expired leases and stale waiters are recorded in audit.
 
 Examples:
   dd-flow lane lock acquire --project-root "$PWD" --lane merge --worker-id worker-1 --path "$PWD" --ttl 300 --reason "merge worker" --json
+  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 heartbeat --project-root "$PWD" --lane merge --worker-id worker-1 --path "$PWD" --lease-token "$TOKEN" --json
   dd-flow lane lock release --project-root "$PWD" --lane merge --worker-id worker-1 --path "$PWD" --lease-token "$TOKEN" --reason done --json`
+    ],
+    [
+        "lane waiter",
+        `dd-flow lane waiter - inspect and cancel persisted lane waiters
+
+Usage:
+  dd-flow lane waiters --project-root <root> [--lane <name>] --json
+  dd-flow lane waiter cancel --project-root <root> --lane <name> --worker-id <id> --reason <text> --json
+
+Waiters are runtime coordination records, not protocols or domain jobs. Use waiters to coordinate fair access to exclusive lanes before a worker owns the lane lock.
+
+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`
     ],
     [
         "merge",
@@ -182,7 +302,7 @@ Usage:
   dd-flow merge status --project-root <root> --json
   dd-flow merge one-shot --project-root <root> --worker-id <id> [--path <workspace>] --json
 
-merge status reports active merge worker, claimed jobs, active merge lane lock and queue state. merge one-shot is status-only when a long-lived worker, claimed job or active lock exists; otherwise it acquires the merge lane, claims at most one ready job, and returns that job for the shared merge job prompt. If no job is ready, it releases the lock and returns job: null.`
+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-worker",
@@ -208,7 +328,7 @@ Usage:
   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
 
-The worker must own the merge lane from the registered merge workspace before claiming, completing, or failing jobs. 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. 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.
 
 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
@@ -227,12 +347,12 @@ cleanup scan is read-only and returns deterministic findings plus plan.actions.
     ],
     [
         "merge-queue wait-next",
-        `dd-flow merge-queue wait-next - wait for the next ready merge job
+        `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, the merge lock is heartbeated while waiting and a lock acquired by this command is released on timeout. If a job is ready, it is claimed atomically. If no job appears before the timeout, the command returns a structured timeout result.
+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`
@@ -277,16 +397,41 @@ Usage:
     ],
     [
         "dashboard",
-        `dd-flow dashboard - render or open markdown dashboards
+        `dd-flow dashboard - render, refresh, open, and inspect markdown/HTML dashboards
 
 Usage:
-  dd-flow dashboard render --project-root <root> [--output <path>] --json
-  dd-flow dashboard render-global [--output <path>] --json
-  dd-flow dashboard open --project-root <root> [--viewer cmux] --json
-  dd-flow dashboard refresh --project-root <root> [--open auto|true|false] --json
-  dd-flow dashboard refresh-global [--output <path>] --json
-
-Dashboards are rendered views of dd-flow state. State-changing commands refresh markdown automatically when dashboard.auto_refresh is enabled. dashboard refresh rewrites project and global markdown when enabled. cmux is used only by explicit open/refresh commands and only according to project config.`
+  dd-flow dashboard open [--viewer cmux] [--format html|markdown] --json
+  dd-flow dashboard refresh [--format html|markdown] --json
+  dd-flow dashboard refresh --all [--format html|markdown] --json
+  dd-flow dashboard refresh --project <project> [--format html|markdown] [--protocol <PRT-ID>] [--open auto|true|false] --json
+  dd-flow dashboard open --project <project> [--protocol <PRT-ID>] [--viewer cmux] [--format html] --json
+  dd-flow dashboard data [--project <project>] [--protocol <PRT-ID>] --json
+  dd-flow dashboard render [--project <project>] [--format html|markdown] [--protocol <PRT-ID>] [--output <path>] --json
+
+Compatibility aliases and explicit low-level forms:
+  dd-flow dashboard refresh-global [--format markdown|html] [--output <path>] --json
+    Preferred: dd-flow dashboard refresh
+  dd-flow dashboard render-global [--format markdown|html] [--output <path>] --json
+    Preferred: dd-flow dashboard render
+  dd-flow dashboard refresh --project-root <root> [--format markdown|html] [--protocol <PRT-ID>] [--open auto|true|false] --json
+    Preferred: dd-flow dashboard refresh --project <project>
+  dd-flow dashboard open --project-root <root> [--format markdown|html] [--viewer cmux] --json
+    Preferred: dd-flow dashboard open --project <project>
+  dd-flow dashboard render --project-root <root> [--format markdown|html] [--protocol <PRT-ID>] [--output <path>] --json
+    Preferred: dd-flow dashboard render --project <project>
+  dd-flow dashboard data --global --json
+    Preferred: dd-flow dashboard data
+
+Project accepts full id, short id, slug, or registered project root path.
+
+Related dashboard commands:
+  dd-flow dashboard open
+  dd-flow dashboard refresh
+  dd-flow dashboard refresh --all
+  dd-flow dashboard open --project <project>
+  dd-flow dashboard data --project <project> --json
+
+Dashboards are rendered views of dd-flow state. Markdown remains the compatibility fallback. HTML dashboards write JSON next to self-contained local HTML: global under DD_FLOW_HOME/dashboard/ and project/protocol pages under DD_FLOW_HOME/projects/<PRJ-ID-slug>/dashboard/. Dashboard JSON uses lifecycle/resource/claim fields as the primary contract when present; current_stage/raw_stage/raw_status/merge_queue/job are compatibility or diagnostic fields. Global dashboard data consumes published project summaries, exposes supported_summary_versions and summary_version_groups, and lists missing/unreadable/unsupported project summaries under unsupported_projects instead of silently hiding those projects. State-changing commands still auto-refresh markdown during the transition. cmux is used only by explicit open/refresh commands and only according to project config. JSON mode writes machine-readable output only.`
     ],
     [
         "schema",