@deksden-com/dd-flow-cli 0.1.0 → 0.2.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

package/dist/build-info.json

@@ -0,0 +1,11 @@
+{
+  "cli_package": "@deksden-com/dd-flow-cli",
+  "cli_version": "0.2.0",
+  "cli_commit": "8351d94bdeaca22d2fff503fd2b08071c86205cd",
+  "built_at": "2026-06-15T14:46:55.550Z",
+  "built_with_canon": {
+    "version": "2.4.0",
+    "commit": "cf1f6d08e8d4775bf14334c6010b479d1c6fd73f",
+    "flow_contract": "dd-flow-canonical-2026-05"
+  }
+}

package/dist/cli/help.js

@@ -9,6 +9,8 @@ Usage:
   dd-flow <command> --help
 
 Core commands:
+  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.
@@ -17,6 +19,8 @@ Core commands:
   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 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.
@@ -28,6 +32,9 @@ Core commands:
 
 Examples:
   dd-flow project register --root "$PWD"
+  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
@@ -35,10 +42,44 @@ Examples:
   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
+  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.`
+    ],
+    [
+        "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
+
+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.
+
+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",
@@ -132,6 +173,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",
@@ -233,7 +295,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

@@ -6,11 +6,14 @@ import { archiveProject, getProjectStatus, migrateProjectIds, registerProject, r
 import { cancelProtocol, getProtocolStatus, readyForMerge, registerProtocol, requireProtocol, 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 { 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 { getFlowSessionStatus, registerFlowSession, stopFlowSession, stopMergeWorker } from "../services/sessions.js";
 import { attachFlowRunStage, completeFlowRun, completeFlowRunStage, getFlowRunStatus, listFlowRuns, startFlowRun } from "../services/runs.js";
@@ -91,6 +94,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 +149,9 @@ function renderHumanResult(args, result) {
         lines.push(`errors: ${errors.length}`);
         return `${lines.join("\n")}\n`;
     }
+    if (family === "status") {
+        return renderStatusHuman(record);
+    }
     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;
@@ -170,9 +178,47 @@ function renderHumanResult(args, result) {
     }
     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 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"}`);
+    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(`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)}`);
+    return `${lines.join("\n")}\n`;
+}
+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") });
+    }
+    if (family === "canon") {
+        return dispatchCanon(context, command, parsed);
+    }
     if (family === "project" && command === "register") {
         return registerProject(context, { root: requiredOption(parsed, "root") });
     }
@@ -252,6 +298,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);
     }
@@ -287,6 +339,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 +410,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") {
@@ -882,6 +980,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");
     }

package/dist/schemas/archived-flow-manifest.schema.json

@@ -0,0 +1,112 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "dd-flow/archived-flow-manifest@1",
+  "title": "Archived flow manifest",
+  "description": "Manifest for dd-flow files archived from an active project flow pack during Memory Bank upgrade.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_id",
+    "archive_id",
+    "created_at",
+    "target_project_root",
+    "source_flow_root",
+    "archive_root",
+    "items"
+  ],
+  "properties": {
+    "schema_id": {
+      "const": "dd-flow/archived-flow-manifest@1"
+    },
+    "archive_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "created_at": {
+      "type": "string",
+      "minLength": 1
+    },
+    "target_project_root": {
+      "type": "string",
+      "minLength": 1
+    },
+    "source_flow_root": {
+      "type": "string",
+      "minLength": 1
+    },
+    "archive_root": {
+      "type": "string",
+      "minLength": 1
+    },
+    "items": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/definitions/item"
+      }
+    },
+    "notes": {
+      "type": "string"
+    }
+  },
+  "definitions": {
+    "item": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "original_path",
+        "archive_path",
+        "classification",
+        "reason",
+        "manual_review_required",
+        "replacement"
+      ],
+      "properties": {
+        "original_path": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*//)[A-Za-z0-9._-]+(?:/[A-Za-z0-9._-]+)*$"
+        },
+        "archive_path": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*//)[A-Za-z0-9._-]+(?:/[A-Za-z0-9._-]+)*$"
+        },
+        "classification": {
+          "type": "string",
+          "enum": ["canonical_only_obsolete", "old_full_canonical_copy", "project_customization", "unknown_extra", "generated_or_runtime"]
+        },
+        "reason": {
+          "type": "string",
+          "minLength": 1
+        },
+        "manual_review_required": {
+          "type": "boolean"
+        },
+        "replacement": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind", "hint"],
+          "properties": {
+            "kind": {
+              "type": "string",
+              "enum": ["canonical_only_flow", "project_flow_pack_file", "removed", "needs_decision"]
+            },
+            "hint": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        },
+        "source_commit": {
+          "type": "string",
+          "minLength": 7
+        },
+        "source_hash": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    }
+  }
+}

package/dist/schemas/merge-stage-report.schema.json

@@ -11,7 +11,12 @@
     "project",
     "subject",
     "overall",
+    "invocation_mode",
     "breadcrumbs",
+    "worker",
+    "queue_context",
+    "lane_lock",
+    "integration",
     "merge_job",
     "git",
     "checks",
@@ -29,6 +34,61 @@
       "type": "array",
       "items": { "$ref": "#/definitions/breadcrumb" }
     },
+    "invocation_mode": {
+      "type": "string",
+      "enum": ["one_shot", "long_lived_worker"]
+    },
+    "worker": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["id", "session_kind", "status_before", "status_after"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "session_kind": { "type": "string", "enum": ["merge_job", "merge_worker"] },
+        "status_before": { "type": "string", "minLength": 1 },
+        "status_after": { "type": "string", "minLength": 1 },
+        "stop_flag": { "type": "string" }
+      }
+    },
+    "queue_context": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["before", "claimed_job", "after", "final_reason"],
+      "properties": {
+        "before": { "type": "string", "minLength": 1 },
+        "claimed_job": { "type": "string", "minLength": 1 },
+        "position_before": { "type": ["number", "null"] },
+        "pending_after": { "type": ["number", "null"] },
+        "after": { "type": "string", "minLength": 1 },
+        "final_reason": { "type": "string", "minLength": 1 }
+      }
+    },
+    "lane_lock": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["owner", "status_before", "status_after"],
+      "properties": {
+        "owner": { "type": "string", "minLength": 1 },
+        "lease_token": { "type": "string" },
+        "status_before": { "type": "string", "minLength": 1 },
+        "status_after": { "type": "string", "minLength": 1 },
+        "acquired_at": { "type": "string" },
+        "released_at": { "type": "string" }
+      }
+    },
+    "integration": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["source_branch", "target_branch", "result"],
+      "properties": {
+        "source_branch": { "type": "string", "minLength": 1 },
+        "source_commit": { "type": "string" },
+        "target_branch": { "type": "string", "minLength": 1 },
+        "result": { "type": "string", "enum": ["merged", "failed", "requeued", "blocked"] },
+        "result_commit": { "type": "string" },
+        "conflicts": { "type": "string" }
+      }
+    },
     "merge_job": {
       "type": "object",
       "additionalProperties": true,
@@ -96,7 +156,7 @@
       "additionalProperties": true,
       "required": ["verdict", "summary", "next_action"],
       "properties": {
-        "verdict": { "type": "string", "minLength": 1 },
+        "verdict": { "type": "string", "enum": ["merged", "failed", "requeued", "blocked"] },
         "summary": { "type": "string", "minLength": 1 },
         "next_action": { "type": "string", "minLength": 1 }
       }