@deksden-com/dd-flow-cli 0.1.0 → 0.3.0

package/README.md

@@ -41,6 +41,17 @@ The flow contract defines mechanical protocol stages, allowed transitions, the `
 
 ## Basic Commands
 
+Inspect runtime and canonical Memory Bank discovery:
+
+```bash
+dd-flow status --project-root "$PWD" --json
+dd-flow canon resolve --json
+dd-flow canon register --root "$DD_MEMORYBANK" --json
+dd-flow canon status --json
+```
+
+`canon resolve` checks explicit `--root`, then `DD_MEMORYBANK`, then the globally registered value in `DD_FLOW_HOME`, then known nearby `dd-memorybank` checkouts from the current working directory. If two different valid canonical roots are discovered, it fails closed with structured blockers and bootstrap hints. Use `DD_MEMORYBANK` for the local canonical `dd-memorybank` checkout.
+
 Register a project:
 
 ```bash
@@ -218,6 +229,8 @@ 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:

package/dist/build-info.json

@@ -0,0 +1,15 @@
+{
+  "cli_package": "@deksden-com/dd-flow-cli",
+  "cli_version": "0.3.0",
+  "cli_commit": "059594c2096e080548d470e789f594e20a1a8ebd",
+  "built_at": "2026-06-30T20:32:13.018Z",
+  "built_with_canon": {
+    "version": "2.8.0",
+    "commit": "f549c33bd73d8d18b5cb07d9737b02fe638e61b8",
+    "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,17 +9,23 @@ 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.
+  canon register/status/resolve Register and resolve the canonical Memory Bank.
   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.
+  protocol register/status/transition Register, inspect, transition and repair protocol state.
   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 markdown or HTML 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.
@@ -28,17 +34,75 @@ Core commands:
 
 Examples:
   dd-flow project register --root "$PWD"
+  dd-flow version
+  dd-flow status --project-root "$PWD" --json
+  dd-flow canon register --root "$DD_MEMORYBANK" --json
+  dd-flow canon resolve --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 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
+  dd-flow merge-worker start --project-root "$PWD" --worker-id merge-worker --path "$PWD" --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.`
+    ],
+    [
+        "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`
+    ],
+    [
+        "status",
+        `dd-flow status - inspect runtime roots and active discovery state
+
+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`
+    ],
+    [
+        "canon",
+        `dd-flow canon - register and resolve the canonical Memory Bank checkout
+
+Usage:
+  dd-flow canon register --root <canonical-dd-memorybank-root> --json
+  dd-flow canon status [--root <canonical-dd-memorybank-root>] --json
+  dd-flow canon resolve [--root <canonical-dd-memorybank-root>] --json
+
+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.
+
+Examples:
+  dd-flow canon register --root "$DD_MEMORYBANK" --json
+  dd-flow canon resolve --json
+  dd-flow canon status --json`
     ],
     [
         "run",
@@ -46,18 +110,33 @@ project_root is the stable repository identity. workspace_path is the concrete c
 
 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",
@@ -66,10 +145,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",
@@ -132,6 +228,27 @@ 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",
+        `dd-flow merge - current-session merge entrypoint helpers
+
+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-worker",
+        `dd-flow merge-worker - manage long-lived project merge workers
+
+Usage:
+  dd-flow merge-worker status --project-root <root> --json
+  dd-flow merge-worker start --project-root <root> --worker-id <id> [--path <workspace>] [--branch <branch>] --json
+  dd-flow merge-worker stop --project-root <root> [--worker-id <id>] --reason <text> --json
+
+start is idempotent: if a worker, claimed job, or active merge lock already exists it returns status instead of creating a duplicate worker. stop is no-op/status when no worker exists, refuses ambiguous multiple workers unless --worker-id is provided, stops idle workers immediately, and marks busy workers as stop-after-current while preserving the claimed job and lock.`
     ],
     [
         "merge-queue",
@@ -215,16 +332,18 @@ Usage:
     ],
     [
         "dashboard",
-        `dd-flow dashboard - render or open markdown dashboards
+        `dd-flow dashboard - render or open markdown and 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 data --project-root <root> [--protocol <PRT-ID>] --json
+  dd-flow dashboard data --global --json
+  dd-flow dashboard render --project-root <root> [--format markdown|html] [--protocol <PRT-ID>] [--output <path>] --json
+  dd-flow dashboard render-global [--format markdown|html] [--output <path>] --json
+  dd-flow dashboard open --project-root <root> [--format markdown|html] [--viewer cmux] --json
+  dd-flow dashboard refresh --project-root <root> [--format markdown|html] [--protocol <PRT-ID>] [--open auto|true|false] --json
+  dd-flow dashboard refresh-global [--format markdown|html] [--output <path>] --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/. 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.`
     ],
     [
         "schema",
@@ -233,7 +352,7 @@ Dashboards are rendered views of dd-flow state. State-changing commands refresh
 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 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 validate",

package/dist/cli/run-cli.js

@@ -3,17 +3,22 @@ import { helpForArgs } from "./help.js";
 import { AppError, isAppError } from "../shared/errors.js";
 import { writeJson } from "../shared/json.js";
 import { archiveProject, getProjectStatus, migrateProjectIds, registerProject, resolveProject } from "../services/projects.js";
-import { cancelProtocol, getProtocolStatus, readyForMerge, registerProtocol, requireProtocol, transitionProtocol } from "../services/protocols.js";
+import { cancelProtocol, getProtocolBlockers, getProtocolStatus, getReadyProtocols, implementProtocol, readyForMerge, registerProtocol, requireProtocol, syncProtocolFromRun, transitionProtocol } from "../services/protocols.js";
 import { blockPlanItem, completePlanItem, getPlanStatus, setProtocolPlan, skipPlanItem, startPlanItem } from "../services/plans.js";
 import { cancelMergeQueueJob, claimNextMergeJob, completeMergeJob, failMergeJob, getMergeQueueStatus, noteMergeJob, waitNextMergeJob } from "../services/merge-queue.js";
+import { getMergeWorkerStatus, oneShotMergeClaim, startMergeWorker, stopProjectMergeWorker } from "../services/merge-worker.js";
 import { cleanupApply, cleanupScan } from "../services/cleanup.js";
 import { getCodexHomeStatus, getCodexHooksStatus, handleCodexHook, initCodexHome, installCodexHooks, planCodexHome, printCodexHomeEnv, printCodexHooks, removeCodexHome, removeCodexHooks } from "../services/hooks.js";
 import { bootstrapWorktree, closeWorktree, createWorktreeRecord, getWorktreeStatus, planWorktree } from "../services/worktrees.js";
 import { acquireLaneLock, checkLaneWorkspace, getLaneStatus, heartbeatLaneLock, releaseLaneLock, setLaneWorkspace, waitForLaneLock } from "../services/lanes.js";
 import { getProjectConfigStatus, setProjectConfigValue } from "../services/config.js";
-import { autoRefreshDashboards, getCmuxStatus, openDashboard, refreshDashboard, refreshGlobalDashboard, renderDashboard, renderGlobalDashboard } from "../services/dashboard.js";
+import { getCanonStatus, registerCanonRoot, resolveCanonRoot } from "../services/canon.js";
+import { getRuntimeStatus } from "../services/status.js";
+import { getCliVersionReport } from "../services/build-info.js";
+import { autoRefreshDashboards, dashboardData, getCmuxStatus, openDashboard, refreshDashboard, refreshGlobalDashboard, renderDashboard, renderGlobalDashboard } from "../services/dashboard.js";
 import { getFlowSessionStatus, registerFlowSession, stopFlowSession, stopMergeWorker } from "../services/sessions.js";
 import { attachFlowRunStage, completeFlowRun, completeFlowRunStage, getFlowRunStatus, listFlowRuns, startFlowRun } from "../services/runs.js";
+import { previewNextEntityId } from "../services/ids.js";
 import { validateSchema } from "../services/schema-validation.js";
 import { preflightMemoryPermissions } from "../services/memory-permissions.js";
 import { requireProjectByRoot } from "../services/projects.js";
@@ -31,6 +36,14 @@ export async function runCli(args, io = defaultIo, env = process.env) {
         if (args.includes("--progress-jsonl")) {
             throw new AppError("usage", "--progress-jsonl is not implemented yet; use --json for final structured progress", 2);
         }
+        if (output.args.length === 1 && output.args[0] === "--version") {
+            const payload = getCliVersionReport();
+            if (output.json)
+                writeJson(io.stdout, payload);
+            else
+                io.stdout.write(`dd-flow ${payload.cli.version}\n`);
+            return 0;
+        }
         const help = helpForArgs(output.args);
         if (help) {
             io.stdout.write(`${help}\n`);
@@ -91,6 +104,8 @@ function progressForCommand(args) {
         ];
     }
     if ((family === "cleanup" && command === "apply") ||
+        (family === "merge" && command === "one-shot") ||
+        family === "merge-worker" ||
         (family === "protocol" && command === "cancel") ||
         (family === "project" && command === "archive") ||
         family === "run") {
@@ -144,6 +159,13 @@ function renderHumanResult(args, result) {
         lines.push(`errors: ${errors.length}`);
         return `${lines.join("\n")}\n`;
     }
+    if (family === "status") {
+        return renderStatusHuman(record);
+    }
+    if (family === "version") {
+        const cli = recordObject(record.cli);
+        return `dd-flow ${stringValue(cli?.version) ?? "unknown"}\n`;
+    }
     const lines = [`dd-flow ${family ?? ""}${command ? ` ${command}` : ""}: ${ok}`.trim()];
     const project = record.project && typeof record.project === "object" ? record.project : null;
     const protocol = record.protocol && typeof record.protocol === "object" ? record.protocol : null;
@@ -168,11 +190,90 @@ function renderHumanResult(args, result) {
         if (run.run_index_path)
             lines.push(`run_index: ${String(run.run_index_path)}`);
     }
+    appendFlowGuidanceHuman(lines, record);
+    return `${lines.join("\n")}\n`;
+}
+function renderStatusHuman(record) {
+    const lines = [`dd-flow status: ${record.ok === false ? "failed" : "ok"}`];
+    const cli = recordObject(record.cli);
+    const cliBuild = recordObject(cli?.build);
+    const builtWithCanon = recordObject(cliBuild?.built_with_canon);
+    const cliCompatibility = recordObject(cli?.compatibility);
+    const registry = recordObject(cli?.registry);
+    const canon = recordObject(record.canon);
+    const resolvedCanon = recordObject(canon?.resolved);
+    const project = recordObject(record.project);
+    const memoryBank = recordObject(project?.memory_bank);
+    const flowPack = recordObject(project?.flow_pack);
+    const drift = recordObject(project?.drift);
+    lines.push(`CLI package: ${stringValue(cli?.package_name) ?? "unknown"} ${stringValue(cli?.version) ?? "unknown"}`);
+    if (cliCompatibility) {
+        lines.push(`CLI compatibility: ${stringValue(cliCompatibility.verdict) ?? "unknown"} (${stringValue(cliCompatibility.reason) ?? "no_reason"})`);
+        if (cliCompatibility.update_command)
+            lines.push(`CLI update: ${String(cliCompatibility.update_command)}`);
+    }
+    if (registry) {
+        lines.push(`CLI registry: ${stringValue(registry.latest) ?? "unknown"} (${stringValue(registry.status) ?? "unknown"})`);
+    }
+    lines.push(`CLI tested with canon: ${stringValue(builtWithCanon?.version) ?? "unknown"} @ ${shortSha(stringValue(builtWithCanon?.commit))}`);
+    lines.push(`Active local canon: ${stringValue(resolvedCanon?.root) ?? "unresolved"} ${stringValue(resolvedCanon?.version) ?? "unknown"} @ ${shortSha(stringValue(resolvedCanon?.commit))} (${stringValue(resolvedCanon?.layout) ?? "unknown"})`);
+    if (resolvedCanon?.memorybank_root)
+        lines.push(`Canon Memory Bank: ${String(resolvedCanon.memorybank_root)}`);
+    if (resolvedCanon?.flow_root)
+        lines.push(`Canon flow root: ${String(resolvedCanon.flow_root)}`);
+    lines.push(`Project: ${stringValue(project?.root) ?? "unknown"}${project?.registered === true ? " (registered)" : " (unregistered)"}`);
+    lines.push(`Project Memory Bank: ${stringValue(memoryBank?.version) ?? stringValue(memoryBank?.status) ?? "unknown"}`);
+    lines.push(`Project flow pack: ${stringValue(flowPack?.pack_version) ?? stringValue(flowPack?.status) ?? "unknown"} @ ${shortSha(stringValue(flowPack?.source_commit))}`);
+    lines.push(`Drift: ${stringValue(drift?.overall) ?? "unknown"}`);
+    if (drift?.next_action)
+        lines.push(`Next action: ${String(drift.next_action)}`);
+    appendFlowGuidanceHuman(lines, record);
     return `${lines.join("\n")}\n`;
 }
+function appendFlowGuidanceHuman(lines, record) {
+    const guidance = recordObject(record.flow_guidance);
+    if (!guidance)
+        return;
+    const currentStage = stringValue(guidance.current_stage);
+    const nextAction = stringValue(guidance.recommended_next_action);
+    const prompt = stringValue(guidance.recommended_prompt);
+    if (currentStage)
+        lines.push(`stage: ${currentStage}`);
+    if (nextAction)
+        lines.push(`next: ${nextAction}${prompt && prompt !== "none" ? ` (${prompt})` : ""}`);
+    const guards = Array.isArray(guidance.guards) ? guidance.guards : [];
+    const firstGuard = guards.find((item) => item && typeof item === "object" && !Array.isArray(item));
+    if (firstGuard?.id)
+        lines.push(`guard: ${String(firstGuard.id)} ${String(firstGuard.status ?? "unknown")}`);
+    const missing = Array.isArray(guidance.blocked_if_missing) ? guidance.blocked_if_missing : [];
+    if (missing.length > 0)
+        lines.push(`missing: ${missing.map(String).join(", ")}`);
+}
+function recordObject(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function stringValue(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function shortSha(value) {
+    return value ? value.slice(0, 12) : "unknown";
+}
 async function dispatch(args, context, io) {
     const [family, command, ...rest] = args;
     const parsed = parseArgs(rest);
+    if (family === "status") {
+        const rootParsed = parseArgs([command ?? "", ...rest]);
+        return getRuntimeStatus(context, {
+            projectRoot: optionalOption(rootParsed, "project-root") ?? optionalOption(rootParsed, "root"),
+            checkRegistry: hasOption(rootParsed, "check-registry")
+        });
+    }
+    if (family === "version") {
+        return getCliVersionReport();
+    }
+    if (family === "canon") {
+        return dispatchCanon(context, command, parsed);
+    }
     if (family === "project" && command === "register") {
         return registerProject(context, { root: requiredOption(parsed, "root") });
     }
@@ -209,9 +310,44 @@ async function dispatch(args, context, io) {
     if (family === "protocol" && command === "status") {
         return getProtocolStatus(context, { protocolId: requiredPosition(parsed, 0, "protocol-id") });
     }
+    if (family === "protocol" && command === "ready") {
+        return getReadyProtocols(context, { projectRoot: requiredOption(parsed, "project-root") });
+    }
+    if (family === "protocol" && command === "blockers") {
+        return getProtocolBlockers(context, {
+            protocolId: requiredPosition(parsed, 0, "protocol-id"),
+            projectRoot: requiredOption(parsed, "project-root")
+        });
+    }
+    if (family === "protocol" && command === "implement") {
+        const reason = optionalOption(parsed, "reason");
+        return implementProtocol(context, {
+            protocolId: requiredPosition(parsed, 0, "protocol-id"),
+            projectRoot: requiredOption(parsed, "project-root"),
+            force: hasOption(parsed, "force"),
+            ...(reason ? { reason } : {})
+        });
+    }
     if (family === "protocol" && command === "ready-for-merge") {
         return readyForMerge(context, { protocolId: requiredPosition(parsed, 0, "protocol-id") });
     }
+    if (family === "protocol" && command === "transition") {
+        const reason = optionalOption(parsed, "reason");
+        return transitionProtocol(context, {
+            protocolId: requiredPosition(parsed, 0, "protocol-id"),
+            to: requiredOption(parsed, "to"),
+            jsonFile: requiredOptionAlias(parsed, ["payload-file", "json-file"]),
+            force: hasOption(parsed, "force"),
+            ...(reason ? { reason } : {})
+        });
+    }
+    if (family === "protocol" && command === "sync-from-run") {
+        return syncProtocolFromRun(context, {
+            protocolId: requiredPosition(parsed, 0, "protocol-id"),
+            runId: requiredOption(parsed, "run"),
+            target: optionalOption(parsed, "target") ?? "auto"
+        });
+    }
     if (family === "protocol" && command === "cancel") {
         return cancelProtocol(context, {
             protocolId: requiredPosition(parsed, 0, "protocol-id"),
@@ -229,7 +365,7 @@ async function dispatch(args, context, io) {
         return transitionProtocol(context, {
             protocolId: requiredPosition(transitionParsed, 0, "protocol-id"),
             to: requiredOption(transitionParsed, "to"),
-            jsonFile: requiredOption(transitionParsed, "json-file"),
+            jsonFile: requiredOptionAlias(transitionParsed, ["payload-file", "json-file"]),
             force: hasOption(transitionParsed, "force"),
             ...(reason ? { reason } : {})
         });
@@ -252,6 +388,12 @@ async function dispatch(args, context, io) {
     if (family === "merge-queue") {
         return dispatchMergeQueue(context, command, parsed);
     }
+    if (family === "merge") {
+        return dispatchMerge(context, command, parsed);
+    }
+    if (family === "merge-worker") {
+        return dispatchMergeWorker(context, command, parsed);
+    }
     if (family === "cleanup") {
         return dispatchCleanup(context, command, parsed);
     }
@@ -261,6 +403,9 @@ async function dispatch(args, context, io) {
     if (family === "run") {
         return dispatchRun(context, command, parsed);
     }
+    if (family === "id") {
+        return dispatchId(context, command, parsed);
+    }
     if (family === "integration" && command === "cmux") {
         return dispatchCmux(context, parsed);
     }
@@ -287,6 +432,18 @@ async function dispatch(args, context, io) {
     }
     throw new AppError("usage", `Unknown command: ${args.join(" ") || "<empty>"}`, 2);
 }
+function dispatchCanon(context, command, parsed) {
+    if (command === "register") {
+        return registerCanonRoot(context, { root: requiredOption(parsed, "root") });
+    }
+    if (command === "status") {
+        return getCanonStatus(context, { root: optionalOption(parsed, "root") });
+    }
+    if (command === "resolve") {
+        return resolveCanonRoot(context, { explicitRoot: optionalOption(parsed, "root") });
+    }
+    throw new AppError("usage", `Unknown canon command: ${command ?? "<empty>"}`, 2);
+}
 function dispatchMergeQueue(context, command, parsed) {
     if (hasOption(parsed, "session-id")) {
         throw new AppError("usage", "--session-id is no longer accepted on merge-queue commands; use --worker-id", 2);
@@ -346,6 +503,40 @@ function dispatchMergeQueue(context, command, parsed) {
     }
     throw new AppError("usage", `Unknown merge-queue command: ${command ?? "<empty>"}`, 2);
 }
+function dispatchMerge(context, command, parsed) {
+    if (command === "status") {
+        return getMergeWorkerStatus(context, { projectRoot: requiredOption(parsed, "project-root") });
+    }
+    if (command === "one-shot") {
+        return oneShotMergeClaim(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            workerId: requiredWorkerId(parsed),
+            workspacePath: workspacePathOption(parsed)
+        });
+    }
+    throw new AppError("usage", `Unknown merge command: ${command ?? "<empty>"}`, 2);
+}
+function dispatchMergeWorker(context, command, parsed) {
+    if (command === "status") {
+        return getMergeWorkerStatus(context, { projectRoot: requiredOption(parsed, "project-root") });
+    }
+    if (command === "start") {
+        return startMergeWorker(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            workerId: requiredWorkerId(parsed),
+            workspacePath: workspacePathOption(parsed),
+            branch: optionalOption(parsed, "branch")
+        });
+    }
+    if (command === "stop") {
+        return stopProjectMergeWorker(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            workerId: optionalOption(parsed, "worker-id"),
+            reason: requiredOption(parsed, "reason")
+        });
+    }
+    throw new AppError("usage", `Unknown merge-worker command: ${command ?? "<empty>"}`, 2);
+}
 function dispatchMemory(command, parsed) {
     const subcommand = requiredPosition(parsed, 0, "memory subcommand");
     if (command === "permissions" && subcommand === "preflight") {
@@ -481,6 +672,16 @@ function dispatchRun(context, command, parsed) {
     }
     throw new AppError("usage", `Unknown run command: ${command ?? "<empty>"}`, 2);
 }
+function dispatchId(context, command, parsed) {
+    if (command === "next") {
+        return previewNextEntityId(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            type: requiredOption(parsed, "type"),
+            slug: requiredOption(parsed, "slug")
+        });
+    }
+    throw new AppError("usage", `Unknown id command: ${command ?? "<empty>"}`, 2);
+}
 function dispatchCmux(context, parsed) {
     const action = requiredPosition(parsed, 0, "integration cmux action");
     if (action === "status") {
@@ -489,14 +690,31 @@ function dispatchCmux(context, parsed) {
     throw new AppError("usage", `Unknown integration cmux action: ${action}`, 2);
 }
 function dispatchDashboard(context, command, parsed) {
+    if (command === "data") {
+        const global = hasOption(parsed, "global");
+        return dashboardData(context, {
+            global,
+            projectRoot: global ? undefined : requiredOption(parsed, "project-root"),
+            protocol: optionalOption(parsed, "protocol")
+        });
+    }
     if (command === "render") {
-        return renderDashboard(context, { projectRoot: requiredOption(parsed, "project-root"), output: optionalOption(parsed, "output") });
+        return renderDashboard(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            output: optionalOption(parsed, "output"),
+            format: optionalOption(parsed, "format"),
+            protocol: optionalOption(parsed, "protocol")
+        });
     }
     if (command === "render-global") {
-        return renderGlobalDashboard(context, { output: optionalOption(parsed, "output") });
+        return renderGlobalDashboard(context, { output: optionalOption(parsed, "output"), format: optionalOption(parsed, "format") });
     }
     if (command === "open") {
-        return openDashboard(context, { projectRoot: requiredOption(parsed, "project-root"), viewer: optionalOption(parsed, "viewer") });
+        return openDashboard(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            viewer: optionalOption(parsed, "viewer"),
+            format: optionalOption(parsed, "format")
+        });
     }
     if (command === "refresh") {
         const open = optionalOption(parsed, "open");
@@ -505,11 +723,13 @@ function dispatchDashboard(context, command, parsed) {
         }
         return refreshDashboard(context, {
             projectRoot: requiredOption(parsed, "project-root"),
-            open: open
+            open: open,
+            format: optionalOption(parsed, "format"),
+            protocol: optionalOption(parsed, "protocol")
         });
     }
     if (command === "refresh-global") {
-        return refreshGlobalDashboard(context, { output: optionalOption(parsed, "output") });
+        return refreshGlobalDashboard(context, { output: optionalOption(parsed, "output"), format: optionalOption(parsed, "format") });
     }
     throw new AppError("usage", `Unknown dashboard command: ${command ?? "<empty>"}`, 2);
 }
@@ -784,6 +1004,14 @@ function requiredOption(parsed, key) {
     }
     return value;
 }
+function requiredOptionAlias(parsed, keys) {
+    for (const key of keys) {
+        const value = optionalOption(parsed, key);
+        if (value)
+            return value;
+    }
+    throw new AppError("usage", `Missing required option: ${keys.map((key) => `--${key}`).join(" or ")}`, 2);
+}
 function hasOption(parsed, key) {
     return parsed.options.has(key);
 }
@@ -882,6 +1110,12 @@ function projectRootForMutation(context, args, result) {
     if (family === "merge-queue") {
         return projectRootForMergeQueueMutation(context, command, parsed);
     }
+    if (family === "merge" && command === "one-shot") {
+        return requiredOption(parsed, "project-root");
+    }
+    if (family === "merge-worker" && ["start", "stop"].includes(command ?? "")) {
+        return requiredOption(parsed, "project-root");
+    }
     if (family === "cleanup" && command === "apply") {
         return requiredOption(parsed, "project-root");
     }