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

package/dist/schemas/protocol-dashboard-data.schema.json

@@ -0,0 +1,112 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "dd-flow/protocol-dashboard-data@1",
+  "title": "dd-flow protocol dashboard data",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["schema_id", "generated_at", "target_language", "page", "project", "protocol", "resource", "primary_run_id", "run_history", "stage_pipeline", "metrics", "warnings"],
+  "properties": {
+    "schema_id": { "const": "dd-flow/protocol-dashboard-data@1" },
+    "generated_at": { "type": "string", "format": "date-time" },
+    "target_language": { "type": "string", "minLength": 2 },
+    "page": { "$ref": "#/definitions/page" },
+    "project": { "type": "object", "additionalProperties": true, "required": ["id", "title", "root"] },
+    "protocol": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["id", "short_id", "lifecycle", "raw_status", "raw_stage", "display_status", "action_level", "updated_at"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "short_id": { "type": "string", "minLength": 1 },
+        "raw_status": { "type": "string", "minLength": 1 },
+        "raw_stage": { "type": "string", "minLength": 1 },
+        "lifecycle": { "$ref": "#/definitions/lifecycle" },
+        "lifecycle_stage": { "type": "string" },
+        "lifecycle_status": { "type": "string" },
+        "display_status": { "type": "string", "minLength": 1 },
+        "action_level": { "type": "string", "enum": ["none", "watch", "actionable", "blocked"] },
+        "updated_at": { "type": "string", "minLength": 1 }
+      }
+    },
+    "resource": { "type": "object", "additionalProperties": true },
+    "queue_item": { "type": ["object", "null"], "additionalProperties": true },
+    "claim": { "type": ["object", "null"], "additionalProperties": true },
+    "links": { "type": "object", "additionalProperties": { "$ref": "#/definitions/link" } },
+    "primary_run_id": { "type": ["string", "null"] },
+    "primary_run_reason": { "type": "string" },
+    "run_history": { "type": "array", "items": { "$ref": "#/definitions/run" } },
+    "review_runs": { "type": "array", "items": { "$ref": "#/definitions/run" } },
+    "stage_pipeline": { "type": "array" },
+    "metrics": { "type": "array", "items": { "$ref": "#/definitions/metric" } },
+    "warnings": { "type": "array" }
+  },
+  "definitions": {
+    "page": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["kind", "screen_id", "title", "html_path", "json_path"],
+      "properties": {
+        "kind": { "const": "protocol" },
+        "screen_id": { "const": "SCR-DD-FLOW-PROTOCOL-PAGE" },
+        "title": { "type": "string", "minLength": 1 },
+        "html_path": { "type": "string", "minLength": 1 },
+        "json_path": { "type": "string", "minLength": 1 }
+      }
+    },
+    "metric": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["id", "label", "value", "status", "source"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "label": { "type": "string", "minLength": 1 },
+        "value": { "type": ["number", "null"] },
+        "status": { "type": "string", "enum": ["known", "unknown", "degraded", "not_applicable"] },
+        "source": { "type": "string", "minLength": 1 }
+      }
+    },
+    "link": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["label", "href", "path_kind", "status"],
+      "properties": {
+        "label": { "type": "string", "minLength": 1 },
+        "href": { "type": "string" },
+        "path_kind": { "type": "string", "enum": ["absolute", "relative"] },
+        "status": { "type": "string", "enum": ["available", "pending", "missing", "not_applicable"] },
+        "degraded_reason": { "type": "string" }
+      }
+    },
+    "run": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["id", "short_id", "flow_kind", "display_flow_kind", "status", "display_status", "stages"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "short_id": { "type": "string", "minLength": 1 },
+        "flow_kind": { "type": "string", "minLength": 1 },
+        "display_flow_kind": { "type": "string", "minLength": 1 },
+        "status": { "type": "string", "minLength": 1 },
+        "display_status": { "type": "string", "minLength": 1 },
+        "stages": { "type": "array" }
+      }
+    },
+    "lifecycle": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["flow", "stage", "status", "terminal", "raw_stage", "raw_status"],
+      "properties": {
+        "flow": { "type": "string", "minLength": 1 },
+        "stage": { "type": "string", "minLength": 1 },
+        "substage": { "type": ["string", "null"] },
+        "status": { "type": "string", "minLength": 1 },
+        "terminal": { "type": "boolean" },
+        "legacy_stage": { "type": ["string", "null"] },
+        "legacy_status": { "type": ["string", "null"] },
+        "raw_stage": { "type": "string", "minLength": 1 },
+        "raw_status": { "type": "string", "minLength": 1 },
+        "queue_status": { "type": ["string", "null"] }
+      }
+    }
+  }
+}

package/dist/schemas/status-report.schema.json

@@ -18,6 +18,8 @@
       "properties": {
         "version": { "type": "string", "minLength": 1 },
         "package_name": { "type": "string", "minLength": 1 },
+        "compatibility": { "$ref": "#/definitions/cliCompatibility" },
+        "registry": { "$ref": "#/definitions/registryStatus" },
         "build": {
           "type": "object",
           "additionalProperties": true,
@@ -85,6 +87,38 @@
     }
   },
   "definitions": {
+    "cliCompatibility": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["verdict", "reason", "package_name", "installed_version"],
+      "properties": {
+        "verdict": { "type": "string", "enum": ["ok", "outdated", "incompatible", "missing", "unknown"] },
+        "reason": { "type": "string", "minLength": 1 },
+        "package_name": { "type": "string", "minLength": 1 },
+        "expected_package_name": { "type": "string" },
+        "installed_version": { "type": "string", "minLength": 1 },
+        "memory_bank_version": { "type": ["string", "null"] },
+        "min_version": { "type": ["string", "null"] },
+        "recommended_version": { "type": ["string", "null"] },
+        "status_contract": { "type": ["string", "null"] },
+        "version_contract": { "type": ["string", "null"] },
+        "flow_contract": { "type": ["string", "null"] },
+        "update_command": { "type": ["string", "null"] }
+      }
+    },
+    "registryStatus": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["package_name", "latest", "checked_at", "source", "status"],
+      "properties": {
+        "package_name": { "type": "string", "minLength": 1 },
+        "latest": { "type": ["string", "null"] },
+        "checked_at": { "type": "string", "minLength": 1 },
+        "source": { "type": "string", "enum": ["npm", "npm_cache"] },
+        "status": { "type": "string", "enum": ["ok", "degraded"] },
+        "reason": { "type": "string" }
+      }
+    },
     "memoryBank": {
       "type": ["object", "null"],
       "additionalProperties": true,
@@ -101,13 +135,14 @@
     "flowPack": {
       "type": ["object", "null"],
       "additionalProperties": true,
-      "required": ["manifest_path", "schema_id", "pack_version", "source_commit", "canon_version_at_source_commit", "status", "canonical_only_files"],
+      "required": ["manifest_path", "schema_id", "pack_version", "source_commit", "canon_version_at_source_commit", "flow_contract", "status", "canonical_only_files"],
       "properties": {
         "manifest_path": { "type": ["string", "null"] },
         "schema_id": { "type": ["string", "null"] },
         "pack_version": { "type": ["string", "null"] },
         "source_commit": { "type": ["string", "null"] },
         "canon_version_at_source_commit": { "type": ["string", "null"] },
+        "flow_contract": { "type": ["string", "null"] },
         "status": { "type": "string", "enum": ["present", "missing", "invalid", "degraded"] },
         "reason": { "type": "string" },
         "canonical_only_files": {
@@ -119,10 +154,11 @@
     "drift": {
       "type": ["object", "null"],
       "additionalProperties": true,
-      "required": ["memory_bank_version", "flow_pack_commit", "overall", "next_action"],
+      "required": ["memory_bank_version", "flow_pack_commit", "flow_contract", "overall", "next_action"],
       "properties": {
         "memory_bank_version": { "$ref": "#/definitions/comparison" },
         "flow_pack_commit": { "$ref": "#/definitions/comparison" },
+        "flow_contract": { "$ref": "#/definitions/comparison" },
         "overall": {
           "type": "string",
           "enum": ["same", "behind", "ahead", "diverged", "missing", "invalid", "unknown", "not_applicable"]

package/dist/schemas/version-report.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "dd-flow/version-report@1",
+  "title": "dd-flow version report",
+  "description": "Small read-only JSON contract for dd-flow version --json.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["ok", "schema_id", "cli"],
+  "properties": {
+    "ok": { "const": true },
+    "schema_id": { "const": "dd-flow/version-report@1" },
+    "cli": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["package_name", "version"],
+      "properties": {
+        "package_name": { "type": "string", "minLength": 1 },
+        "version": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}

package/dist/services/build-info.js

@@ -21,6 +21,10 @@ export function getCliBuildInfo() {
                     version: null,
                     commit: null,
                     flow_contract: null,
+                    repo_root: null,
+                    memorybank_root: null,
+                    flow_root: null,
+                    layout: null,
                     status: "unknown",
                     reason: "build_info_missing"
                 }
@@ -31,10 +35,14 @@ export function getCliBuildInfo() {
     const canonVersion = stringOrNull(builtWithCanon?.version);
     const canonCommit = stringOrNull(builtWithCanon?.commit);
     const flowContract = stringOrNull(builtWithCanon?.flow_contract);
-    const canonStatus = canonVersion && canonCommit ? "present" : "degraded";
+    const repoRoot = stringOrNull(builtWithCanon?.repo_root);
+    const memorybankRoot = stringOrNull(builtWithCanon?.memorybank_root);
+    const flowRoot = stringOrNull(builtWithCanon?.flow_root);
+    const layout = stringOrNull(builtWithCanon?.layout);
+    const canonStatus = canonVersion && canonCommit && flowContract ? "present" : "degraded";
     return {
-        version: stringOr(buildInfo.cli_version, version),
-        package_name: stringOr(buildInfo.cli_package, packageName),
+        version,
+        package_name: packageName,
         build: {
             status: "present",
             built_at: stringOrNull(buildInfo.built_at),
@@ -43,12 +51,27 @@ export function getCliBuildInfo() {
                 version: canonVersion,
                 commit: canonCommit,
                 flow_contract: flowContract,
+                repo_root: repoRoot,
+                memorybank_root: memorybankRoot,
+                flow_root: flowRoot,
+                layout,
                 status: canonStatus,
                 ...(canonStatus === "degraded" ? { reason: "build_canon_metadata_incomplete" } : {})
             }
         }
     };
 }
+export function getCliVersionReport() {
+    const cli = getCliBuildInfo();
+    return {
+        ok: true,
+        schema_id: "dd-flow/version-report@1",
+        cli: {
+            package_name: cli.package_name,
+            version: cli.version
+        }
+    };
+}
 function findPackageRoot(start) {
     let current = path.resolve(start);
     while (true) {

package/dist/services/canon.js

@@ -46,14 +46,21 @@ export function resolveCanonRoot(context, input = {}) {
             throw new Error("Expected one canonical candidate.");
         }
         const root = candidate.realpath ?? candidate.root;
-        const metadata = readCanonMetadata(root);
+        const flowRoot = candidate.flow_root ?? path.join(root, "dd-flow");
+        const memorybankRoot = candidate.memorybank_root ?? root;
+        const mbbRoot = candidate.mbb_root ?? path.join(memorybankRoot, "mbb");
+        const layout = candidate.layout ?? "legacy_root";
+        const metadata = readCanonMetadata(root, flowRoot);
         return {
             ok: true,
             canon: {
                 root,
+                repo_root: root,
                 source: candidate.source,
-                flow_root: path.join(root, "dd-flow"),
-                memorybank_root: root,
+                layout,
+                flow_root: flowRoot,
+                mbb_root: mbbRoot,
+                memorybank_root: memorybankRoot,
                 version: metadata.version,
                 commit: metadata.commit,
                 flow_contract: metadata.flow_contract,
@@ -121,24 +128,28 @@ function validateCanonCandidate(source, root) {
     if (!fs.statSync(realpath).isDirectory()) {
         blockers.push(`${source} canonical root is not a directory: ${realpath}`);
     }
-    const requiredFiles = [
-        "dd-flow/README.md",
-        "mbb/index.md",
-        "protocol/index.md",
-        "dd-flow/mb-init.md",
-        "dd-flow/mb-upgrade.md",
-        "dd-flow/mb-upgrade-review.md",
-        "dd-flow/mb-distill.md"
-    ];
-    for (const relativePath of requiredFiles) {
-        const file = path.join(realpath, relativePath);
-        if (!fs.existsSync(file) || !fs.statSync(file).isFile()) {
-            blockers.push(`${source} canonical root is missing ${relativePath}: ${realpath}`);
-        }
+    if (path.basename(realpath) === ".memory-bank" && fs.existsSync(path.join(path.dirname(realpath), "VERSION"))) {
+        blockers.push(`${source} canonical root points to .memory-bank; use the dd-memorybank repository root instead: ${path.dirname(realpath)}`);
     }
-    return { source, root: absolute, realpath, valid: blockers.length === 0, blockers };
+    const layout = assessCanonLayout(realpath);
+    blockers.push(...layout.blockers.map((blocker) => `${source} ${blocker}`));
+    return {
+        source,
+        root: absolute,
+        realpath,
+        valid: blockers.length === 0 && layout.valid,
+        blockers,
+        ...(layout.valid
+            ? {
+                layout: layout.layout,
+                memorybank_root: layout.memorybankRoot,
+                flow_root: layout.flowRoot,
+                mbb_root: layout.mbbRoot
+            }
+            : {})
+    };
 }
-export function readCanonMetadata(root) {
+export function readCanonMetadata(root, flowRoot = path.join(root, "dd-flow")) {
     const diagnostics = [];
     const version = readTrimmed(path.join(root, "VERSION"));
     if (!version)
@@ -146,7 +157,7 @@ export function readCanonMetadata(root) {
     const commit = gitCommit(root);
     if (!commit)
         diagnostics.push("canon_commit_unknown");
-    const flowContract = readFlowContractId(root);
+    const flowContract = readFlowContractId(flowRoot);
     if (!flowContract)
         diagnostics.push("flow_contract_unknown");
     return {
@@ -166,9 +177,69 @@ function readTrimmed(file) {
         return null;
     }
 }
-function readFlowContractId(root) {
+export function resolveCanonLayout(root) {
+    return assessCanonLayout(path.resolve(root));
+}
+function assessCanonLayout(root) {
+    const legacy = assessLayout(root, "legacy_root", root);
+    const dot = assessLayout(root, "dot_memory_bank", path.join(root, ".memory-bank"));
+    if (dot.valid && !legacy.valid)
+        return dot;
+    if (legacy.valid && !dot.valid)
+        return legacy;
+    if (dot.valid && legacy.valid) {
+        if (dot.flowContract && legacy.flowContract && dot.flowContract !== legacy.flowContract) {
+            return {
+                ...dot,
+                valid: false,
+                blockers: [
+                    `canonical root has conflicting legacy_root and dot_memory_bank flow contracts: ${legacy.flowContract} vs ${dot.flowContract}`
+                ]
+            };
+        }
+        return dot;
+    }
+    return {
+        ...dot,
+        valid: false,
+        blockers: [
+            "canonical root does not match legacy_root or dot_memory_bank layout",
+            ...legacy.blockers.map((blocker) => `legacy_root: ${blocker}`),
+            ...dot.blockers.map((blocker) => `dot_memory_bank: ${blocker}`)
+        ]
+    };
+}
+function assessLayout(root, layout, memorybankRoot) {
+    const blockers = [];
+    const requiredFiles = [
+        "dd-flow/README.md",
+        "mbb/index.md",
+        "protocol/index.md",
+        "dd-flow/mb-init.md",
+        "dd-flow/mb-upgrade.md",
+        "dd-flow/mb-upgrade-review.md",
+        "dd-flow/mb-distill.md"
+    ];
+    for (const relativePath of requiredFiles) {
+        const file = path.join(memorybankRoot, relativePath);
+        if (!fs.existsSync(file) || !fs.statSync(file).isFile()) {
+            blockers.push(`canonical root is missing ${layout} ${relativePath}: ${root}`);
+        }
+    }
+    const flowRoot = path.join(memorybankRoot, "dd-flow");
+    return {
+        layout,
+        memorybankRoot,
+        flowRoot,
+        mbbRoot: path.join(memorybankRoot, "mbb"),
+        valid: blockers.length === 0,
+        blockers,
+        flowContract: readFlowContractId(flowRoot)
+    };
+}
+function readFlowContractId(flowRoot) {
     try {
-        const parsed = JSON.parse(fs.readFileSync(path.join(root, "dd-flow", "flow-contract.json"), "utf8"));
+        const parsed = JSON.parse(fs.readFileSync(path.join(flowRoot, "flow-contract.json"), "utf8"));
         if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
             const id = parsed.id;
             return typeof id === "string" && id.length > 0 ? id : null;

package/dist/services/cleanup.js

@@ -7,12 +7,13 @@ import { ensureReadableFile } from "../storage/database.js";
 import { projectCheckoutRoot, resolveProjectRoot } from "../storage/paths.js";
 import { appendAudit } from "./audit.js";
 import { requireProjectByRoot } from "./projects.js";
-import { readProtocolRuntimeState, requireProtocol } from "./protocols.js";
+import { protocolRunDiagnostics, readProtocolRuntimeState, requireProtocol } from "./protocols.js";
 const actionKinds = new Set([
     "repair_protocol_state",
     "cancel_queue_job",
     "close_flow_session",
     "expire_lane_lock",
+    "expire_lane_waiter",
     "close_worktree_record"
 ]);
 export function cleanupScan(context, input) {
@@ -39,6 +40,19 @@ export function cleanupScan(context, input) {
                 });
             }
         }
+        const fullProtocol = requireProtocol(context, protocol.id);
+        const state = readProtocolRuntimeState(context, fullProtocol).state;
+        const diagnostics = protocolRunDiagnostics(context, fullProtocol, state).diagnostics;
+        for (const diagnostic of diagnostics.filter((entry) => entry.code === "protocol_run_stage_mismatch")) {
+            findings.push({
+                code: "protocol_run_stage_mismatch",
+                severity: diagnostic.severity === "error" ? "warning" : "info",
+                protocol_id: protocol.id,
+                protocol_stage: state.stage,
+                latest_run: diagnostic.latest_run,
+                recommended_commands: diagnostic.recommended_commands
+            });
+        }
     }
     const orphanQueueJobs = context.db.all(`SELECT mq.protocol_id, mq.status FROM merge_queue mq
      LEFT JOIN protocols p ON p.id = mq.protocol_id
@@ -85,6 +99,18 @@ export function cleanupScan(context, input) {
             action: { kind: "expire_lane_lock", project_id: project.id, lock_id: lock.id }
         });
     }
+    const expiredWaiters = context.db.all(`SELECT id, lane, worker_id, expires_at FROM lane_waiters
+     WHERE project_id = ? AND status = 'queued' AND expires_at IS NOT NULL AND expires_at <= ?
+     ORDER BY id ASC`, [project.id, now]);
+    for (const waiter of expiredWaiters) {
+        pushFinding(findings, actions, "expired_lane_waiter", "warning", {
+            waiter_id: waiter.id,
+            lane: waiter.lane,
+            worker_id: waiter.worker_id,
+            expires_at: waiter.expires_at,
+            action: { kind: "expire_lane_waiter", project_id: project.id, waiter_id: waiter.id }
+        });
+    }
     const staleWorktrees = context.db.all(`SELECT wr.protocol_id, wr.worktree_path FROM worktree_records wr
      JOIN protocols p ON p.id = wr.protocol_id
      WHERE wr.project_id = ?
@@ -272,6 +298,24 @@ function applyAction(context, action, reason, force, now) {
             lock_id: action.lock_id
         };
     }
+    if (action.kind === "expire_lane_waiter" && typeof action.waiter_id === "number") {
+        const result = context.db.run("UPDATE lane_waiters SET status = 'expired', reason = ?, updated_at = ? WHERE project_id = ? AND id = ? AND status = 'queued'", [reason, now, action.project_id, action.waiter_id]);
+        if (result.changes === 1) {
+            appendAudit(context, {
+                projectId: action.project_id,
+                eventType: "lane_waiter.expired",
+                reason,
+                forced: force,
+                payload: { waiter_id: action.waiter_id, source: "cleanup.apply" }
+            });
+        }
+        return {
+            kind: action.kind,
+            changed: result.changes === 1,
+            ...(result.changes === 1 ? {} : { skipped: true, reason: "already_inactive" }),
+            waiter_id: action.waiter_id
+        };
+    }
     if (action.kind === "close_worktree_record" && action.protocol_id) {
         const worktreePath = action.worktree_path ?? context.db.get("SELECT worktree_path FROM worktree_records WHERE project_id = ? AND protocol_id = ?", [action.project_id, action.protocol_id])?.worktree_path;
         const status = worktreePath && fs.existsSync(worktreePath) ? "kept" : "removed";

package/dist/services/cli-operation-classifier.js

@@ -0,0 +1,104 @@
+export function classifyCliOperation(args, env = process.env) {
+    const positional = positionalArgs(args);
+    const [family = null, command = null, action = null] = positional;
+    const operation = [family, command, action].filter(Boolean).join(".") || "help";
+    if (isMbUpgradeMode(args, env)) {
+        return { mode: "mb_upgrade", operation, family, command, action };
+    }
+    if (isRouterNative(args)) {
+        return { mode: "router_native", operation, family, command, action };
+    }
+    if (isReadOnlyDiagnostic(family, command, action)) {
+        return { mode: "read_only_diagnostics", operation, family, command, action };
+    }
+    return { mode: "normal_write", operation, family, command, action };
+}
+function positionalArgs(args) {
+    const positional = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const value = args[index];
+        if (!value)
+            continue;
+        if (value.startsWith("--")) {
+            if (!value.includes("=") && args[index + 1] && !args[index + 1]?.startsWith("--"))
+                index += 1;
+            continue;
+        }
+        positional.push(value);
+    }
+    return positional;
+}
+export function isReadOnlyCliOperation(args, env = process.env) {
+    return classifyCliOperation(args, env).mode === "read_only_diagnostics";
+}
+export function isMbUpgradeCliOperation(args, env = process.env) {
+    return classifyCliOperation(args, env).mode === "mb_upgrade";
+}
+function isMbUpgradeMode(args, env) {
+    if (env.DD_FLOW_COMPATIBILITY_MODE === "mb-upgrade" || env.DD_FLOW_MB_UPGRADE_MODE === "1") {
+        return true;
+    }
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--compatibility-mode" && args[index + 1] === "mb-upgrade")
+            return true;
+        if (arg === "--mb-upgrade-mode")
+            return true;
+        if (arg?.startsWith("--compatibility-mode="))
+            return arg.slice("--compatibility-mode=".length) === "mb-upgrade";
+    }
+    return false;
+}
+function isRouterNative(args) {
+    const first = args[0];
+    if (!first || first === "--version")
+        return true;
+    if (first === "--help" || first === "-h")
+        return true;
+    if (args.includes("--help") || args.includes("-h"))
+        return true;
+    return ["engine", "version", "schema"].includes(first);
+}
+function isReadOnlyDiagnostic(family, command, action) {
+    if (!family)
+        return true;
+    if (family === "status" || family === "version" || family === "id" || family === "integration")
+        return true;
+    if (family === "canon")
+        return command === "status" || command === "resolve";
+    if (family === "project")
+        return command === "status" || command === "resolve";
+    if (family === "protocol")
+        return ["status", "ready", "blockers", "implement"].includes(command ?? "");
+    if (family === "plan")
+        return command === "status";
+    if (family === "run")
+        return command === "status" || command === "list";
+    if (family === "lane") {
+        return (command === "status" ||
+            command === "waiters" ||
+            (command === "lock" && action === "status") ||
+            (command === "workspace" && action === "check"));
+    }
+    if (family === "merge")
+        return command === "status";
+    if (family === "merge-worker")
+        return command === "status";
+    if (family === "merge-queue")
+        return command === "status";
+    if (family === "migration")
+        return ["plan", "report", "verify"].includes(command ?? "");
+    if (family === "session")
+        return command === "status";
+    if (family === "dashboard")
+        return command === "data" || command === "open";
+    if (family === "memory")
+        return command === "permissions" && action === "preflight";
+    if (family === "codex" && command === "hooks")
+        return action === "print" || action === "status";
+    if (family === "codex" && command === "home")
+        return ["plan", "status", "print-env"].includes(action ?? "");
+    if (family === "worktree")
+        return command === "plan" || command === "status";
+    return false;
+}