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

package/README.md

@@ -229,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

@@ -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.0",
+  "cli_commit": "059594c2096e080548d470e789f594e20a1a8ebd",
+  "built_at": "2026-06-30T20:32:13.018Z",
   "built_with_canon": {
-    "version": "2.4.0",
-    "commit": "cf1f6d08e8d4775bf14334c6010b479d1c6fd73f",
-    "flow_contract": "dd-flow-canonical-2026-05"
+    "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,21 +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.
@@ -32,6 +34,7 @@ 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
@@ -39,7 +42,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 +53,21 @@ 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`
     ],
     [
         "status",
@@ -56,9 +76,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 +110,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 +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",
@@ -277,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",

package/dist/cli/run-cli.js

@@ -3,7 +3,7 @@ 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";
@@ -14,9 +14,11 @@ import { acquireLaneLock, checkLaneWorkspace, getLaneStatus, heartbeatLaneLock,
 import { getProjectConfigStatus, setProjectConfigValue } from "../services/config.js";
 import { getCanonStatus, registerCanonRoot, resolveCanonRoot } from "../services/canon.js";
 import { getRuntimeStatus } from "../services/status.js";
-import { autoRefreshDashboards, getCmuxStatus, openDashboard, refreshDashboard, refreshGlobalDashboard, renderDashboard, renderGlobalDashboard } from "../services/dashboard.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";
@@ -34,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`);
@@ -152,6 +162,10 @@ function renderHumanResult(args, result) {
     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;
@@ -176,6 +190,7 @@ 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) {
@@ -183,6 +198,8 @@ function renderStatusHuman(record) {
     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);
@@ -190,16 +207,48 @@ function renderStatusHuman(record) {
     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))}`);
+    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;
 }
@@ -214,7 +263,13 @@ async function dispatch(args, context, io) {
     const parsed = parseArgs(rest);
     if (family === "status") {
         const rootParsed = parseArgs([command ?? "", ...rest]);
-        return getRuntimeStatus(context, { projectRoot: optionalOption(rootParsed, "project-root") ?? optionalOption(rootParsed, "root") });
+        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);
@@ -255,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"),
@@ -275,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 } : {})
         });
@@ -313,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);
     }
@@ -579,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") {
@@ -587,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");
@@ -603,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);
 }
@@ -882,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);
 }

package/dist/schemas/compatibility.schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "dd-flow/compatibility@1",
+  "title": "dd-flow compatibility manifest",
+  "description": "Canonical compatibility map between a Memory Bank release and the dd-flow CLI package required by that release.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_id", "memory_bank_version", "dd_flow_cli"],
+  "properties": {
+    "schema_id": { "const": "dd-flow/compatibility@1" },
+    "memory_bank_version": { "type": "string", "minLength": 1 },
+    "dd_flow_cli": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["package_name", "min_version", "recommended_version", "status_contract", "version_contract", "flow_contract"],
+      "properties": {
+        "package_name": { "type": "string", "minLength": 1 },
+        "min_version": { "type": "string", "minLength": 1 },
+        "recommended_version": { "type": "string", "minLength": 1 },
+        "status_contract": { "type": "string", "minLength": 1 },
+        "version_contract": { "type": "string", "minLength": 1 },
+        "flow_contract": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,73 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "dd-flow/flow-guidance@1",
+  "title": "dd-flow CLI flow guidance block",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "current_stage",
+    "allowed_next_stages",
+    "recommended_next_action",
+    "recommended_prompt",
+    "required_predecessor_evidence",
+    "guards",
+    "blocked_if_missing"
+  ],
+  "properties": {
+    "current_stage": {
+      "type": "string",
+      "minLength": 1
+    },
+    "allowed_next_stages": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "recommended_next_action": {
+      "type": "string",
+      "minLength": 1
+    },
+    "recommended_prompt": {
+      "type": "string",
+      "minLength": 1
+    },
+    "required_predecessor_evidence": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "guards": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "status", "summary"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "status": {
+            "type": "string",
+            "enum": ["pass", "fail", "unknown", "not_applicable", "degraded"]
+          },
+          "summary": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "blocked_if_missing": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    }
+  }
+}

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

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "dd-flow/flow-run-index@1",
+  "$id": "dd-flow/flow-run-index@2",
   "title": "dd-flow run index",
   "description": "Navigation and artifact discovery contract for one concrete dd-flow execution.",
   "type": "object",
@@ -24,7 +24,7 @@
   ],
   "properties": {
     "schema_id": {
-      "const": "dd-flow/flow-run-index@1"
+      "enum": ["dd-flow/flow-run-index@1", "dd-flow/flow-run-index@2"]
     },
     "run_id": {
       "type": "string",
@@ -36,7 +36,7 @@
     },
     "flow_kind": {
       "type": "string",
-      "enum": ["coding", "experiment", "mb-init", "mb-upgrade", "mb-audit", "mb-distill", "mb-upgrade-review", "custom"]
+      "enum": ["mb_sdlc", "coding", "experiment", "mb-init", "mb-upgrade", "mb-audit", "mb-distill", "mb-upgrade-review", "mb-sdlc-review", "review", "custom"]
     },
     "subject": {
       "type": "object",
@@ -62,7 +62,33 @@
       "required": ["root", "run_dir"],
       "properties": {
         "root": { "type": "string", "minLength": 1 },
-        "run_dir": { "type": "string", "pattern": "^\\.tasks/dd-flow-runs/RUN-[0-9]{3}-[a-z0-9]+(?:-[a-z0-9]+)*$" }
+        "run_dir": { "type": "string", "minLength": 1 }
+      }
+    },
+    "run_home": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["storage", "path"],
+      "properties": {
+        "storage": { "type": "string", "enum": ["dd_flow_home", "workspace_tasks_legacy", "project_projection"] },
+        "path": { "type": "string", "minLength": 1 },
+        "relative_path": { "type": "string", "minLength": 1 }
+      }
+    },
+    "execution": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["project_root", "workspace_root"],
+      "properties": {
+        "project_root": { "type": "string", "minLength": 1 },
+        "workspace_root": { "type": "string", "minLength": 1 }
+      }
+    },
+    "legacy": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "project_tasks_run_dir": { "type": ["string", "null"] }
       }
     },
     "stage_runs": {