@deksden-com/dd-flow-cli 0.1.0

package/README.md

@@ -0,0 +1,274 @@
+# dd-flow-cli
+
+`dd-flow-cli` is the mechanical control layer for `dd-flow` workflows.
+
+It does not replace Memory Bank prompts and does not make product, design, merge, or verification judgments. Prompts own intent, route selection, planning depth, evidence meaning, and semantic readiness. The CLI owns explicit local state: projects, protocols, Codex session bindings, transitions, worktree records, lanes, locks, merge queue jobs, hook records, and audit events.
+
+## Runtime Model
+
+Root local database:
+
+```text
+~/.dd-flow/db.sqlite
+```
+
+New projects use typed full ids and aliases:
+
+```text
+PRJ-001-dd-flow-playground
+PRJ-001
+```
+
+Project-scoped runtime protocol state:
+
+```text
+~/.dd-flow/projects/<PRJ-ID-slug>/runtime/protocols/<protocol-id>/state.json
+~/.dd-flow/projects/<PRJ-ID-slug>/runtime/protocols/<protocol-id>/plan.json
+```
+
+Project Memory Bank files under `.memory-bank/protocol/PRT-.../` are durable documentation and evidence snapshots. Runtime commands such as status, transition, merge completion, cancel, and cleanup do not require a feature-worktree-local `state.json` to exist.
+
+Project flow contract:
+
+```text
+.memory-bank/dd-flow/flow-contract.json
+.memory-bank/dd-flow/flow-contract.yaml
+```
+
+The flow contract defines mechanical protocol stages, allowed transitions, the `ready-for-merge` gate, merge completion target stage, and the default first `next_action`. If no file exists, the built-in canonical contract is used. JSON takes precedence over YAML when both are present. The default canonical stages are `prime`, `readiness`, and `integration`; legacy `g0`, `m1`, and `m2` inputs are normalized as aliases for local migration safety.
+
+`project_root` is the stable repository identity in dd-flow state. `workspace_path` is the concrete checkout where an agent is about to work. They can be the same path, or different paths when a feature worktree, merge checkout, direct integration checkout, or temporary fixture workspace is used.
+
+## Basic Commands
+
+Register a project:
+
+```bash
+dd-flow project register --root "$PWD" --json
+dd-flow project status --root "$PWD" --json
+dd-flow project resolve PRJ-001 --json
+dd-flow project archive PRJ-001 --reason "old missing worktree root" --json
+dd-flow project archive --root /abs/old/deleted/root --reason "old missing worktree root" --json
+dd-flow project migrate-ids --root "$PWD" --json
+dd-flow project migrate-ids --root "$PWD" --apply --json
+```
+
+Use `project archive` for old registered roots that no longer exist, especially historical feature-worktree roots from earlier runtime layouts. Archiving does not delete protocols, queue rows, or audit history; it removes the project from active global dashboards and keeps it in the archived section for traceability. Re-registering the same existing root reactivates it.
+
+`migrate-ids` is explicit on purpose. It reports the old hash-based local id and the planned typed id in dry-run mode, then updates project references only with `--apply`.
+
+Register and inspect a protocol:
+
+```bash
+dd-flow protocol register HANDSHAKE-001 --project-root "$PWD" --json
+dd-flow protocol status PRT-HANDSHAKE-001 --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
+```
+
+Human help is available for the operator-facing command groups:
+
+```bash
+dd-flow --help
+dd-flow lane --help
+dd-flow lane workspace --help
+dd-flow lane lock --help
+dd-flow merge-queue --help
+dd-flow merge-queue wait-next --help
+dd-flow cleanup --help
+dd-flow codex home --help
+dd-flow worktree --help
+```
+
+## 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`.
+
+Register and check a lane workspace:
+
+```bash
+dd-flow lane workspace set --project-root "$PROJECT_ROOT" --lane merge --path "$WORKSPACE" --branch main --json
+dd-flow lane workspace check --project-root "$PROJECT_ROOT" --lane merge --path "$PWD" --json
+```
+
+Acquire, heartbeat, and release a lane lock:
+
+```bash
+dd-flow lane lock acquire --project-root "$PROJECT_ROOT" --lane merge --worker-id "$WORKER_ID" --path "$WORKSPACE" --ttl 300 --reason "merge worker" --json
+dd-flow lane lock heartbeat --project-root "$PROJECT_ROOT" --lane merge --worker-id "$WORKER_ID" --path "$WORKSPACE" --lease-token "$TOKEN" --json
+dd-flow lane lock release --project-root "$PROJECT_ROOT" --lane merge --worker-id "$WORKER_ID" --path "$WORKSPACE" --lease-token "$TOKEN" --reason done --json
+```
+
+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
+```
+
+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.
+
+## Direct Main Recipe
+
+Use `direct-main` only after the prompt or operator has chosen direct integration work for a small, low-risk task.
+
+```bash
+dd-flow lane workspace set --project-root "$PROJECT_ROOT" --lane direct-main --path "$PROJECT_ROOT" --branch main --json
+dd-flow lane workspace check --project-root "$PROJECT_ROOT" --lane direct-main --path "$PWD" --json
+dd-flow lane lock acquire --project-root "$PROJECT_ROOT" --lane direct-main --worker-id "$PROTOCOL_ID" --path "$PWD" --ttl 300 --reason "direct integration work" --json
+```
+
+When the task stops using the shared checkout:
+
+```bash
+dd-flow lane lock release --project-root "$PROJECT_ROOT" --lane direct-main --worker-id "$PROTOCOL_ID" --path "$PWD" --lease-token "$TOKEN" --reason done --json
+```
+
+## Merge Queue Recipe
+
+Prompts enqueue protocols only after explicit readiness signals exist:
+
+```bash
+dd-flow protocol ready-for-merge PRT-... --json
+dd-flow merge-queue status --project-root "$PROJECT_ROOT" --json
+```
+
+A merge worker must own the `merge` lane before claiming jobs:
+
+```bash
+dd-flow lane workspace set --project-root "$PROJECT_ROOT" --lane merge --path "$MERGE_WORKSPACE" --branch main --json
+dd-flow lane lock acquire --project-root "$PROJECT_ROOT" --lane merge --worker-id "$WORKER_ID" --path "$MERGE_WORKSPACE" --ttl 300 --reason "merge worker" --json
+dd-flow merge-queue next --project-root "$PROJECT_ROOT" --worker-id "$WORKER_ID" --path "$MERGE_WORKSPACE" --json
+```
+
+For supervisor-style waiting outside model tokens:
+
+```bash
+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.
+
+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
+```
+
+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.
+
+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
+```
+
+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:
+
+```bash
+dd-flow session register --payload-file ".tasks/dd-flow/session-payload.json" --json
+```
+
+`--payload-base64` remains supported for callers that can pass a literal value, but it must not use shell variables in Codex-hooked sessions because `PreToolUse` receives the raw command before shell expansion.
+
+For feature worktrees, keep the stable project identity separate from the checkout where the agent works:
+
+```bash
+dd-flow protocol register PRT-... --project-root "$PROJECT_ROOT" --workspace-path "$FEATURE_WORKTREE" --json
+```
+
+Codex hooks enforce merge-role boundaries mechanically. A normal planning or implementation session may mark a protocol ready for merge, but it may not claim merge queue jobs, mutate the merge lane lock, complete/fail a merge job, run `git merge`, or re-register itself as a merge worker/job. Hook guards also block removing the current Codex session worktree, because deleting the session `cwd` breaks later tool and hook calls.
+
+Cancel a full protocol runtime record by explicit operator intent:
+
+```bash
+dd-flow protocol cancel PRT-... --reason "replaced by fresh run" --close-sessions true --cancel-queue true --release-locks true --worktree keep --json
+```
+
+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.
+
+## 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.
+
+```bash
+dd-flow cleanup scan --project-root "$PROJECT_ROOT" --json > .tasks/dd-flow-cleanup-scan.json
+jq '.plan' .tasks/dd-flow-cleanup-scan.json > .tasks/dd-flow-cleanup-plan.json
+dd-flow cleanup apply --project-root "$PROJECT_ROOT" --plan-file .tasks/dd-flow-cleanup-plan.json --reason "clear stale local rerun state" --json
+```
+
+The CLI remains mechanical: it cancels or repairs explicit runtime rows, but it does not decide whether a protocol, experiment, merge, or verification was semantically good.
+
+## Dashboards
+
+Dashboard markdown is rendered state, not source of truth. Successful state-changing commands refresh project and global dashboards automatically when `dashboard.auto_refresh` is enabled. `dashboard refresh` also rewrites both the project dashboard and the global dashboard when they are enabled, so an already-open cmux markdown viewer receives live updates.
+
+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.
+
+Defaults:
+
+```text
+project dashboard: .tasks/dd-flow-dashboard.md
+global dashboard:  ~/.dd-flow/dashboard.md
+```
+
+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
+```
+
+Config keys:
+
+```bash
+dd-flow project config set --project-root "$PROJECT_ROOT" --key dashboard.auto_refresh --value true --json
+dd-flow project config set --project-root "$PROJECT_ROOT" --key dashboard.project --value true --json
+dd-flow project config set --project-root "$PROJECT_ROOT" --key dashboard.global --value true --json
+dd-flow project config set --project-root "$PROJECT_ROOT" --key integrations.cmux.mode --value auto --json
+```
+
+cmux is a viewer only. Ordinary auto-refresh writes markdown and does not open cmux.
+
+## Worktrunk And Codex
+
+`dd-flow-cli` records Worktrunk-backed worktree state but does not replace Worktrunk as the owner of worktree lifecycle.
+
+```bash
+dd-flow worktree plan --protocol-id PRT-... --json
+dd-flow worktree create --protocol-id PRT-... --branch feature/name --base main --path "$DD_FLOW_HOME/projects/PRJ-001-dd-flow-playground/checkouts/worktrees/PRT-.../repo" --json
+dd-flow worktree status --protocol-id PRT-... --json
+```
+
+`worktree plan` suggests project-scoped service checkout paths under `DD_FLOW_HOME/projects/<PRJ-ID-slug>/checkouts/`; it no longer points new work at project-local `.tasks/worktrees`.
+
+Codex integration is explicit and auditable. Managed Codex homes and hooks are local operational scaffolding; deterministic tests must not mutate the user's default `~/.codex` without an explicit target and confirmation.
+
+```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
+```
+
+## Verification
+
+Local verification for this repository:
+
+```bash
+pnpm test
+pnpm typecheck
+pnpm lint
+pnpm build
+```
+
+Manual smoke checks should use a temporary `DD_FLOW_HOME` when they do not intentionally inspect the operator's real local state.

package/dist/cli/help.js

@@ -0,0 +1,308 @@
+const helpPages = new Map([
+    [
+        "",
+        `dd-flow - mechanical control layer for dd-flow workflows
+
+Usage:
+  dd-flow <command> [options]
+  dd-flow <command> [options] --json
+  dd-flow <command> --help
+
+Core commands:
+  project register/status       Register a project and inspect runtime state.
+  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.
+  cleanup scan/apply            Detect and repair stale local runtime state.
+  run start/status/list         Track concrete flow executions and stage artifacts.
+  plan set/status/item          Attach and update protocol plans.
+  lane workspace/lock/status    Manage shared workspace lanes and leases.
+  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.
+  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.
+  codex home/hooks/hook         Manage Codex homes, hooks, and hook events.
+  worktree plan/create/status   Record Worktrunk-backed feature worktrees.
+
+Examples:
+  dd-flow project register --root "$PWD"
+  dd-flow project status --root "$PWD" --json
+  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 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
+
+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.`
+    ],
+    [
+        "run",
+        `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 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.
+
+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 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`
+    ],
+    [
+        "protocol",
+        `dd-flow protocol - register and inspect protocol state
+
+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-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
+
+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.`
+    ],
+    [
+        "project",
+        `dd-flow project - register and inspect typed project identity
+
+Usage:
+  dd-flow project register --root <root> --json
+  dd-flow project status --root <root> --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.`
+    ],
+    [
+        "lane",
+        `dd-flow lane - coordinate shared project workspaces
+
+Usage:
+  dd-flow lane status --project-root <root> --json
+  dd-flow lane workspace <action> [options] --json
+  dd-flow lane lock <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 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`
+    ],
+    [
+        "lane workspace",
+        `dd-flow lane workspace - register and check lane workspaces
+
+Usage:
+  dd-flow lane workspace set --project-root <root> --lane <name> --path <workspace> [--branch <name>] --json
+  dd-flow lane workspace check --project-root <root> --lane <name> --path <workspace> --json
+
+The project_root identifies the repository in dd-flow state. The workspace_path is the checkout where the worker is running. Branch checks are factual diagnostics, not semantic policy decisions.
+
+Examples:
+  dd-flow lane workspace set --project-root "$PWD" --lane merge --path "$PWD" --branch main --json
+  dd-flow lane workspace check --project-root "$PWD" --lane merge --path "$(pwd)" --json`
+    ],
+    [
+        "lane lock",
+        `dd-flow lane lock - acquire, heartbeat, wait for, and release lane leases
+
+Usage:
+  dd-flow lane lock acquire --project-root <root> --lane <name> --worker-id <id> [--path <workspace>] [--ttl 300] --reason <text> --json
+  dd-flow lane lock heartbeat --project-root <root> --lane <name> --worker-id <id> [--path <workspace>] [--lease-token <token>] [--ttl 300] --json
+  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
+
+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.
+
+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 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`
+    ],
+    [
+        "merge-queue",
+        `dd-flow merge-queue - inspect and process ready-for-merge protocols
+
+Usage:
+  dd-flow merge-queue status --project-root <root> --json
+  dd-flow merge-queue next --project-root <root> --worker-id <id> [--path <workspace>] --json
+  dd-flow merge-queue 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
+
+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.
+
+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`
+    ],
+    [
+        "cleanup",
+        `dd-flow cleanup - scan and apply explicit local runtime cleanup plans
+
+Usage:
+  dd-flow cleanup scan --project-root <root> --json
+  dd-flow cleanup apply --project-root <root> --plan-file <file> --reason <text> [--force] --json
+
+cleanup scan is read-only and returns deterministic findings plus plan.actions. cleanup apply validates project identity, action kinds, reason, and destructive force requirements before mutating runtime state, then reports requested/applied/changed/skipped action results. Worktree record cleanup marks a checkout removed only when its path is already absent; existing checkouts are kept instead of being silently deleted. Use this for stale queue jobs, missing protocol runtime snapshots, stale sessions, expired locks, and terminal-protocol worktree records.`
+    ],
+    [
+        "merge-queue wait-next",
+        `dd-flow merge-queue wait-next - wait for the next ready merge job
+
+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.
+
+Examples:
+  dd-flow merge-queue wait-next --project-root "$PWD" --worker-id supervisor --path "$PWD" --timeout 1200 --poll-interval 10 --acquire-lock true --json`
+    ],
+    [
+        "session",
+        `dd-flow session - register and stop explicit flow sessions
+
+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 stop --project-root <root> --session-id <id> --reason <text> --json
+  dd-flow session stop-worker --project-root <root> --worker-id <id> --reason <text> --json
+
+Session registration is the durable contract used by Stop hooks. Prompts register flow_kind, continuation_policy, protocol_id, worker_id, and workspace_path explicitly. Prefer --payload-file in Codex prompts because PreToolUse hooks see the raw shell command before variable expansion.`
+    ],
+    [
+        "project config",
+        `dd-flow project config - inspect and update project configuration
+
+Usage:
+  dd-flow project config status --project-root <root> --json
+  dd-flow project config set --project-root <root> --key <path> --value <value> --json
+
+Supported keys:
+  dashboard.auto_refresh = true|false
+  dashboard.project = true|false
+  dashboard.global = true|false
+  dashboard.open_on_session_start = true|false
+  dashboard.open_on_merge_worker_start = true|false
+  dashboard.markdown_path = <path>
+  dashboard.global_markdown_path = <path>
+  integrations.cmux.mode = off|auto|required`
+    ],
+    [
+        "integration cmux",
+        `dd-flow integration cmux - inspect optional cmux availability
+
+Usage:
+  dd-flow integration cmux status --project-root <root> --json`
+    ],
+    [
+        "dashboard",
+        `dd-flow dashboard - render or open markdown 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.`
+    ],
+    [
+        "schema",
+        `dd-flow schema - validate canonical dd-flow data contracts
+
+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 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 validate",
+        `dd-flow schema validate - validate a JSON artifact against a canonical schema
+
+Usage:
+  dd-flow schema validate --schema mb-upgrade-review-data --file review-data.json [--project-root <root>] [--schema-dir <dir>] --json
+
+Exit codes:
+  0  valid
+  2  usage, unknown schema, invalid JSON, or schema validation failure
+
+Examples:
+  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`
+    ],
+    [
+        "memory",
+        `dd-flow memory - Memory Bank runtime gates
+
+Usage:
+  dd-flow memory permissions preflight --root <project-root> --memory-bank <path> [--tasks <path>] --flow <flow> --mode <mode> --json
+
+permissions preflight checks project, Memory Bank, and optional .tasks read/write permissions before memory flows mutate files. It never runs privileged repair commands. A completed assessment returns JSON on stdout with exit_code 0 when the flow can continue and exit_code 1 when permission blockers are found. Runtime/configuration mistakes exit 2 as structured errors.`
+    ],
+    [
+        "memory permissions",
+        `dd-flow memory permissions - inspect Memory Bank filesystem access
+
+Usage:
+  dd-flow memory permissions preflight --root . --memory-bank .memory-bank --tasks .tasks --flow mb-upgrade --mode write --json
+
+Flows: mb-init, mb-upgrade, mb-audit, mb-fix, mb-upgrade-review, custom.
+Modes: read, write, repair, report_only.
+
+Use read mode before read-only audit analysis. Use write or report_only before creating or updating Memory Bank files, DEF records, dashboards, or .tasks artifacts. The command may create and remove temporary probe files in checked writable directories, but it does not persist files as part of diagnosis.`
+    ],
+    [
+        "codex home",
+        `dd-flow codex home - manage isolated Codex homes
+
+Usage:
+  dd-flow codex home plan --project-root <root> [--profile <name>] --json
+  dd-flow codex home init --project-root <root> [--profile <name>] [--source-home <path>] [--target-home <path>] --json
+  dd-flow codex home status --project-root <root> [--profile <name>] --json
+  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
+
+Managed homes isolate dd-flow hooks while sharing selected Codex state from the source home.`
+    ],
+    [
+        "worktree",
+        `dd-flow worktree - record Worktrunk-backed feature worktrees
+
+Usage:
+  dd-flow worktree plan --protocol-id <protocol-id> --json
+  dd-flow worktree create --protocol-id <protocol-id> --branch <name> --base <ref> --path <path> --json
+  dd-flow worktree status --protocol-id <protocol-id> --json
+  dd-flow worktree bootstrap --protocol-id <protocol-id> --json
+  dd-flow worktree close --protocol-id <protocol-id> --mode keep|remove --json
+
+worktree plan suggests a project-scoped service checkout under DD_FLOW_HOME/projects/<PRJ-ID-slug>/checkouts/. Worktrunk owns the actual worktree lifecycle. dd-flow records explicit state and structured degraded mode.`
+    ]
+]);
+export function helpForArgs(args) {
+    const helpIndex = args.findIndex((arg) => arg === "--help" || arg === "-h");
+    if (helpIndex === -1) {
+        return undefined;
+    }
+    const path = args.slice(0, helpIndex).filter((arg) => !arg.startsWith("--")).join(" ");
+    return helpPages.get(path) ?? helpPages.get(path.split(" ").slice(0, 2).join(" ")) ?? helpPages.get("");
+}