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

package/dist/cli/run-cli.js

@@ -1,3 +1,4 @@
+import fs from "node:fs";
 import { createContext } from "../runtime/context.js";
 import { helpForArgs } from "./help.js";
 import { AppError, isAppError } from "../shared/errors.js";
@@ -5,7 +6,7 @@ import { writeJson } from "../shared/json.js";
 import { archiveProject, getProjectStatus, migrateProjectIds, registerProject, resolveProject } from "../services/projects.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 { cancelMergeQueueJob, claimNextMergeJob, claimMergeBundle, completeMergeBundle, completeMergeJob, failMergeBundle, failMergeJob, getMergeBundleStatus, 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";
@@ -17,17 +18,19 @@ import { getRuntimeStatus } from "../services/status.js";
 import { getCliVersionReport } from "../services/build-info.js";
 import { autoRefreshDashboards, dashboardData, getCmuxStatus, openDashboard, openGlobalDashboard, openProtocolDashboard, refreshAllDashboards, refreshDashboard, refreshGlobalDashboard, renderDashboard, renderGlobalDashboard } from "../services/dashboard.js";
 import { dashboardTargetSummary, preferredDashboardCommand, relatedDashboardCommands, resolveDashboardTarget } from "../services/dashboard-targets.js";
-import { getFlowSessionStatus, registerFlowSession, stopFlowSession, stopMergeWorker } from "../services/sessions.js";
-import { attachFlowRunStage, completeFlowRun, completeFlowRunStage, getFlowRunStatus, listFlowRuns, startFlowRun } from "../services/runs.js";
+import { getFlowSessionStatus, registerFlowSession, stopFlowSession, stopMergeWorker, syncFlowSessionUsage } from "../services/sessions.js";
+import { getProtocolBranchContext } from "../services/branch-context.js";
+import { attachFlowRunStage, completeFlowRun, completeFlowRunStage, getFlowRunTimeline, getFlowRunUsage, getFlowRunFlagsStatus, getFlowRunStatus, listFlowRuns, reviseFlowRunFlags, 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 { planMigration, verifyMigrationReport } from "../services/migrations.js";
+import { assessMigrationImpact, planMigration, verifyMigrationReport } from "../services/migrations.js";
 import { publishProjectSummary } from "../services/project-summary.js";
 import { requireProjectByRoot } from "../services/projects.js";
 import { resolveProjectRoot } from "../storage/paths.js";
-import { doctorEngines, engineInfo, installCurrentEngine, listEngines, resolveEngine, routeArgsThroughEngine } from "../services/engines.js";
+import { doctorEngines, engineInfo, installCurrentEngine, listEngines, resolveEngine, resolveOperationProjectRoot, routeArgsThroughEngine } from "../services/engines.js";
 import { preflightCliCompatibility } from "../services/compatibility-preflight.js";
+import { renderWorkerPrompt } from "../services/prompts.js";
 const defaultIo = {
     stdout: process.stdout,
     stderr: process.stderr,
@@ -56,7 +59,8 @@ export async function runCli(args, io = defaultIo, env = process.env) {
         }
         const context = createContext(env);
         emitHumanProgress(io, output, progress, "start");
-        const routed = await routeArgsThroughEngine(context, output.args, io, io.stdin, env);
+        const scopeProjectRoot = resolveOperationProjectRoot(context, output.args);
+        const routed = await routeArgsThroughEngine(context, output.args, io, io.stdin, env, scopeProjectRoot);
         if (routed?.routed && !routed.inProcess) {
             emitHumanProgress(io, output, progress, "done");
             return routed.exitCode;
@@ -64,11 +68,12 @@ export async function runCli(args, io = defaultIo, env = process.env) {
         const dispatchContext = routed?.inProcess
             ? createContext({ ...env, DD_FLOW_ENGINE_MODE: "1", DD_FLOW_ENGINE_HOME: "in-process", DD_FLOW_ROUTED_FROM: getCliVersionReport().cli.version })
             : context;
-        preflightCliCompatibility(dispatchContext, output.args, env);
-        const result = await dispatch(output.args, dispatchContext, io);
-        refreshDashboardsAfterMutation(context, output.args, result);
+        preflightCliCompatibility(dispatchContext, output.args, env, scopeProjectRoot);
+        const result = await dispatch(output.args, dispatchContext, io, scopeProjectRoot);
+        const refreshWarnings = refreshDashboardsAfterMutation(context, output.args, result, scopeProjectRoot);
+        const resultWithWarnings = addWarnings(result, refreshWarnings);
         emitHumanProgress(io, output, progress, "done");
-        const payload = attachProgress(result, progress, output);
+        const payload = attachProgress(resultWithWarnings, progress, output);
         if (output.json)
             writeJson(io.stdout, payload);
         else
@@ -223,6 +228,18 @@ function renderHumanResult(args, result) {
         const job = record.job;
         lines.push(`job: ${String(job.protocol_id ?? "none")} ${String(job.status ?? "")}`.trim());
     }
+    const branchContext = recordObject(record.branch_context);
+    const mergeBundle = recordObject(branchContext?.merge_bundle);
+    if (branchContext) {
+        lines.push(`branch: ${String(branchContext.feature_branch ?? branchContext.grouping_key ?? "unknown")}`);
+        const protocols = Array.isArray(branchContext.protocols) ? branchContext.protocols.length : 0;
+        lines.push(`branch_protocols: ${protocols}`);
+        if (mergeBundle) {
+            const eligible = Array.isArray(mergeBundle.eligible_protocols) ? mergeBundle.eligible_protocols.length : 0;
+            const notReady = Array.isArray(mergeBundle.not_ready_protocols) ? mergeBundle.not_ready_protocols.length : 0;
+            lines.push(`bundle: ${String(mergeBundle.reason ?? "unknown")} ready=${eligible} not_ready=${notReady}`);
+        }
+    }
     if (record.stopped)
         lines.push(`stopped: ${String(record.reason ?? "true")}`);
     if (record.timed_out)
@@ -361,7 +378,7 @@ function stringValue(value) {
 function shortSha(value) {
     return value ? value.slice(0, 12) : "unknown";
 }
-async function dispatch(args, context, io) {
+async function dispatch(args, context, io, scopeProjectRoot = null) {
     const [family, command, ...rest] = args;
     const parsed = parseArgs(rest);
     if (family === "engine") {
@@ -420,7 +437,16 @@ async function dispatch(args, context, io) {
         });
     }
     if (family === "protocol" && command === "status") {
-        return getProtocolStatus(context, { protocolId: requiredPosition(parsed, 0, "protocol-id") });
+        const protocolId = requiredPosition(parsed, 0, "protocol-id");
+        return getProtocolStatus(context, { protocolId, projectRoot: requiredScopeProjectRoot(scopeProjectRoot, "protocol status") });
+    }
+    if (family === "protocol" && command === "branch-status") {
+        const protocolId = parsed.positional[0];
+        return getProtocolBranchContext(context, {
+            ...(protocolId ? { protocolId } : {}),
+            projectRoot: scopeProjectRoot ?? optionalOption(parsed, "project-root"),
+            workspacePath: optionalOption(parsed, "path")
+        });
     }
     if (family === "protocol" && command === "ready") {
         return getReadyProtocols(context, { projectRoot: requiredOption(parsed, "project-root") });
@@ -432,21 +458,25 @@ async function dispatch(args, context, io) {
         });
     }
     if (family === "protocol" && command === "implement") {
+        const protocolId = requiredPosition(parsed, 0, "protocol-id");
         const reason = optionalOption(parsed, "reason");
         return implementProtocol(context, {
-            protocolId: requiredPosition(parsed, 0, "protocol-id"),
-            projectRoot: requiredOption(parsed, "project-root"),
+            protocolId,
+            projectRoot: requiredScopeProjectRoot(scopeProjectRoot, "protocol implement"),
             force: hasOption(parsed, "force"),
             ...(reason ? { reason } : {})
         });
     }
     if (family === "protocol" && command === "ready-for-merge") {
-        return readyForMerge(context, { protocolId: requiredPosition(parsed, 0, "protocol-id") });
+        const protocolId = requiredPosition(parsed, 0, "protocol-id");
+        return readyForMerge(context, { protocolId, projectRoot: requiredScopeProjectRoot(scopeProjectRoot, "protocol ready-for-merge") });
     }
     if (family === "protocol" && command === "transition") {
+        const protocolId = requiredPosition(parsed, 0, "protocol-id");
         const reason = optionalOption(parsed, "reason");
         return transitionProtocol(context, {
-            protocolId: requiredPosition(parsed, 0, "protocol-id"),
+            protocolId,
+            projectRoot: requiredScopeProjectRoot(scopeProjectRoot, "protocol transition"),
             to: requiredOption(parsed, "to"),
             jsonFile: requiredOptionAlias(parsed, ["payload-file", "json-file"]),
             force: hasOption(parsed, "force"),
@@ -454,15 +484,19 @@ async function dispatch(args, context, io) {
         });
     }
     if (family === "protocol" && command === "sync-from-run") {
+        const protocolId = requiredPosition(parsed, 0, "protocol-id");
         return syncProtocolFromRun(context, {
-            protocolId: requiredPosition(parsed, 0, "protocol-id"),
+            protocolId,
+            projectRoot: requiredScopeProjectRoot(scopeProjectRoot, "protocol sync-from-run"),
             runId: requiredOption(parsed, "run"),
             target: optionalOption(parsed, "target") ?? "auto"
         });
     }
     if (family === "protocol" && command === "cancel") {
+        const protocolId = requiredPosition(parsed, 0, "protocol-id");
         return cancelProtocol(context, {
-            protocolId: requiredPosition(parsed, 0, "protocol-id"),
+            protocolId,
+            projectRoot: requiredScopeProjectRoot(scopeProjectRoot, "protocol cancel"),
             reason: requiredOption(parsed, "reason"),
             closeSessions: parseOptionalBoolean(optionalOption(parsed, "close-sessions"), "close-sessions") ?? false,
             cancelQueue: parseOptionalBoolean(optionalOption(parsed, "cancel-queue"), "cancel-queue") ?? false,
@@ -473,9 +507,11 @@ async function dispatch(args, context, io) {
     }
     if (family === "transition") {
         const transitionParsed = parseArgs([command ?? "", ...rest]);
+        const protocolId = requiredPosition(transitionParsed, 0, "protocol-id");
         const reason = optionalOption(transitionParsed, "reason");
         return transitionProtocol(context, {
-            protocolId: requiredPosition(transitionParsed, 0, "protocol-id"),
+            protocolId,
+            projectRoot: requiredScopeProjectRoot(scopeProjectRoot, "transition"),
             to: requiredOption(transitionParsed, "to"),
             jsonFile: requiredOptionAlias(transitionParsed, ["payload-file", "json-file"]),
             force: hasOption(transitionParsed, "force"),
@@ -483,22 +519,37 @@ async function dispatch(args, context, io) {
         });
     }
     if (family === "plan" && command === "set") {
+        const protocolId = requiredPosition(parsed, 0, "protocol-id");
         return setProtocolPlan(context, {
-            protocolId: requiredPosition(parsed, 0, "protocol-id"),
+            protocolId,
+            projectRoot: requiredScopeProjectRoot(scopeProjectRoot, "plan set"),
             file: requiredOption(parsed, "file")
         });
     }
     if (family === "plan" && command === "status") {
-        return getPlanStatus(context, { protocolId: requiredPosition(parsed, 0, "protocol-id") });
+        const protocolId = requiredPosition(parsed, 0, "protocol-id");
+        return getPlanStatus(context, { protocolId, projectRoot: requiredScopeProjectRoot(scopeProjectRoot, "plan status") });
     }
     if (family === "plan" && command === "item") {
-        return dispatchPlanItem(context, parsed);
+        return dispatchPlanItem(context, parsed, requiredScopeProjectRoot(scopeProjectRoot, "plan item"));
+    }
+    if (family === "prompt" && command === "render") {
+        const workspaceRoot = optionalOption(parsed, "workspace-root");
+        const taskFile = optionalOption(parsed, "task-file");
+        return renderWorkerPrompt(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            runId: requiredOption(parsed, "run"),
+            stage: requiredOption(parsed, "stage"),
+            profile: requiredOption(parsed, "profile"),
+            ...(taskFile ? { taskFile } : { planItemId: requiredOption(parsed, "plan-item") }),
+            ...(workspaceRoot ? { workspaceRoot } : {})
+        });
     }
     if (family === "lane") {
         return dispatchLane(context, command, parsed);
     }
     if (family === "merge-queue") {
-        return dispatchMergeQueue(context, command, parsed);
+        return dispatchMergeQueue(context, command, parsed, requiredScopeProjectRootForOptional(scopeProjectRoot, command, parsed));
     }
     if (family === "merge") {
         return dispatchMerge(context, command, parsed);
@@ -543,7 +594,7 @@ async function dispatch(args, context, io) {
         return dispatchCodexHook(context, parsed, await readStdin(io.stdin));
     }
     if (family === "worktree") {
-        return dispatchWorktree(context, command, parsed);
+        return dispatchWorktree(context, command, parsed, requiredScopeProjectRoot(scopeProjectRoot, `worktree ${command ?? ""}`));
     }
     throw new AppError("usage", `Unknown command: ${args.join(" ") || "<empty>"}`, 2);
 }
@@ -566,6 +617,8 @@ function dispatchEngine(context, command, parsed) {
     throw new AppError("usage", `Unknown engine command: ${command ?? "<empty>"}`, 2);
 }
 function dispatchMigration(context, command, parsed) {
+    if (command === "impact")
+        return assessMigrationImpact(context, { projectRoot: requiredOption(parsed, "project-root"), ...(optionalOption(parsed, "target-version") ? { targetVersion: optionalOption(parsed, "target-version") } : {}), ...(optionalOption(parsed, "mode") ? { mode: optionalOption(parsed, "mode") } : {}) });
     if (command === "plan" || command === "report") {
         return planMigration(context, {
             projectRoot: requiredOption(parsed, "project-root"),
@@ -594,23 +647,23 @@ function dispatchCanon(context, command, parsed) {
     }
     throw new AppError("usage", `Unknown canon command: ${command ?? "<empty>"}`, 2);
 }
-function dispatchMergeQueue(context, command, parsed) {
+function dispatchMergeQueue(context, command, parsed, scopeProjectRoot) {
     if (hasOption(parsed, "session-id")) {
         throw new AppError("usage", "--session-id is no longer accepted on merge-queue commands; use --worker-id", 2);
     }
     if (command === "status") {
-        return getMergeQueueStatus(context, { projectRoot: requiredOption(parsed, "project-root") });
+        return getMergeQueueStatus(context, { projectRoot: requiredOptionOrScope(parsed, scopeProjectRoot, "project-root") });
     }
     if (command === "next") {
         return claimNextMergeJob(context, {
-            projectRoot: requiredOption(parsed, "project-root"),
+            projectRoot: requiredOptionOrScope(parsed, scopeProjectRoot, "project-root"),
             workerId: requiredWorkerId(parsed),
             workspacePath: workspacePathOption(parsed)
         });
     }
     if (command === "wait-next") {
         return waitNextMergeJob(context, {
-            projectRoot: requiredOption(parsed, "project-root"),
+            projectRoot: requiredOptionOrScope(parsed, scopeProjectRoot, "project-root"),
             workerId: requiredWorkerId(parsed),
             timeoutSeconds: optionalNumber(parsed, "timeout"),
             pollIntervalSeconds: optionalNumber(parsed, "poll-interval"),
@@ -619,16 +672,20 @@ function dispatchMergeQueue(context, command, parsed) {
         });
     }
     if (command === "complete") {
+        const protocolId = requiredPosition(parsed, 0, "protocol-id");
         return completeMergeJob(context, {
-            protocolId: requiredPosition(parsed, 0, "protocol-id"),
+            protocolId,
+            projectRoot: requiredScopeProjectRoot(scopeProjectRoot, "merge-queue complete"),
             workerId: requiredWorkerId(parsed),
             workspacePath: workspacePathOption(parsed),
             summary: requiredOption(parsed, "summary")
         });
     }
     if (command === "fail") {
+        const protocolId = requiredPosition(parsed, 0, "protocol-id");
         return failMergeJob(context, {
-            protocolId: requiredPosition(parsed, 0, "protocol-id"),
+            protocolId,
+            projectRoot: requiredScopeProjectRoot(scopeProjectRoot, "merge-queue fail"),
             workerId: requiredWorkerId(parsed),
             workspacePath: workspacePathOption(parsed),
             reason: requiredOption(parsed, "reason"),
@@ -636,15 +693,19 @@ function dispatchMergeQueue(context, command, parsed) {
         });
     }
     if (command === "note") {
+        const protocolId = requiredPosition(parsed, 0, "protocol-id");
         return noteMergeJob(context, {
-            protocolId: requiredPosition(parsed, 0, "protocol-id"),
+            protocolId,
+            projectRoot: requiredScopeProjectRoot(scopeProjectRoot, "merge-queue note"),
             workerId: requiredWorkerId(parsed),
             summary: requiredOption(parsed, "summary")
         });
     }
     if (command === "cancel") {
+        const protocolId = requiredPosition(parsed, 0, "protocol-id");
         return cancelMergeQueueJob(context, {
-            protocolId: requiredPosition(parsed, 0, "protocol-id"),
+            protocolId,
+            projectRoot: requiredScopeProjectRoot(scopeProjectRoot, "merge-queue cancel"),
             reason: requiredOption(parsed, "reason"),
             workerId: optionalOption(parsed, "worker-id"),
             workspacePath: optionalOption(parsed, "path"),
@@ -655,7 +716,38 @@ function dispatchMergeQueue(context, command, parsed) {
 }
 function dispatchMerge(context, command, parsed) {
     if (command === "status") {
-        return getMergeWorkerStatus(context, { projectRoot: requiredOption(parsed, "project-root") });
+        return getMergeWorkerStatus(context, { projectRoot: requiredOption(parsed, "project-root"), workspacePath: optionalOption(parsed, "path") });
+    }
+    if (command === "bundle") {
+        const action = requiredPosition(parsed, 0, "bundle action");
+        if (action === "status") {
+            return getMergeBundleStatus(context, { projectRoot: requiredOption(parsed, "project-root"), workspacePath: workspacePathOption(parsed) });
+        }
+        if (action === "claim") {
+            return claimMergeBundle(context, {
+                projectRoot: requiredOption(parsed, "project-root"),
+                workerId: requiredWorkerId(parsed),
+                workspacePath: workspacePathOption(parsed)
+            });
+        }
+        if (action === "complete") {
+            return completeMergeBundle(context, {
+                projectRoot: requiredOption(parsed, "project-root"),
+                workerId: requiredWorkerId(parsed),
+                workspacePath: workspacePathOption(parsed),
+                summary: requiredOption(parsed, "summary")
+            });
+        }
+        if (action === "fail") {
+            return failMergeBundle(context, {
+                projectRoot: requiredOption(parsed, "project-root"),
+                workerId: requiredWorkerId(parsed),
+                workspacePath: workspacePathOption(parsed),
+                reason: requiredOption(parsed, "reason"),
+                requeue: parseBoolean(requiredOption(parsed, "requeue"), "requeue")
+            });
+        }
+        throw new AppError("usage", `Unknown merge bundle action: ${action}`, 2);
     }
     if (command === "one-shot") {
         return oneShotMergeClaim(context, {
@@ -764,10 +856,17 @@ function dispatchSession(context, command, parsed) {
             reason: requiredOption(parsed, "reason")
         });
     }
+    if (command === "usage" && requiredPosition(parsed, 0, "session usage action") === "sync") {
+        return syncFlowSessionUsage(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            sessionId: requiredOption(parsed, "session-id")
+        });
+    }
     throw new AppError("usage", `Unknown session command: ${command ?? "<empty>"}`, 2);
 }
 function dispatchRun(context, command, parsed) {
     if (command === "start") {
+        const protocolOverrides = readOptionalJsonFile(optionalOption(parsed, "protocol-override-file"));
         return startFlowRun(context, {
             projectRoot: requiredOption(parsed, "project-root"),
             workspaceRoot: optionalOption(parsed, "workspace-root"),
@@ -775,7 +874,11 @@ function dispatchRun(context, command, parsed) {
             subjectType: requiredOption(parsed, "subject-type"),
             subjectId: requiredOption(parsed, "subject-id"),
             slug: requiredOption(parsed, "slug"),
-            nextAction: optionalOption(parsed, "next-action")
+            nextAction: optionalOption(parsed, "next-action"),
+            preset: optionalOption(parsed, "preset"),
+            taskProfile: readOptionalJsonFile(optionalOption(parsed, "task-profile-file")),
+            ...(protocolOverrides ? { protocolOverrides } : {}),
+            runOverrides: parseFlowFlagOverrides(allOptions(parsed, "flag"))
         });
     }
     if (command === "status") {
@@ -787,6 +890,43 @@ function dispatchRun(context, command, parsed) {
     if (command === "list") {
         return listFlowRuns(context, { projectRoot: requiredOption(parsed, "project-root") });
     }
+    if (command === "timeline") {
+        return getFlowRunTimeline(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            runId: requiredPosition(parsed, 0, "run-id"),
+            hiddenSections: allOptions(parsed, "hide")
+        });
+    }
+    if (command === "usage") {
+        return getFlowRunUsage(context, {
+            projectRoot: requiredOption(parsed, "project-root"),
+            runId: requiredPosition(parsed, 0, "run-id"),
+            groupBy: optionalOption(parsed, "group-by")
+        });
+    }
+    if (command === "flags") {
+        const action = requiredPosition(parsed, 0, "flow flags action");
+        const runId = requiredPosition(parsed, 1, "run-id");
+        if (action === "status") {
+            return getFlowRunFlagsStatus(context, {
+                projectRoot: requiredOption(parsed, "project-root"),
+                runId
+            });
+        }
+        if (action === "revise") {
+            return reviseFlowRunFlags(context, {
+                projectRoot: requiredOption(parsed, "project-root"),
+                runId,
+                expectedRevision: Number.parseInt(requiredOption(parsed, "expected-revision"), 10),
+                idempotencyKey: requiredOption(parsed, "idempotency-key"),
+                flags: parseFlowFlagOverrides(allOptions(parsed, "flag")),
+                preset: optionalOption(parsed, "preset"),
+                reason: optionalOption(parsed, "reason"),
+                allowDowngrade: hasOption(parsed, "allow-downgrade")
+            });
+        }
+        throw new AppError("usage", `Unknown run flags command: ${action}`, 2);
+    }
     if (command === "attach-stage") {
         return attachFlowRunStage(context, {
             projectRoot: requiredOption(parsed, "project-root"),
@@ -1179,42 +1319,45 @@ function dispatchCodexHook(context, parsed, stdin) {
     }
     throw new AppError("usage", `Unknown codex hook action: ${action}`, 2);
 }
-function dispatchWorktree(context, command, parsed) {
+function dispatchWorktree(context, command, parsed, scopeProjectRoot) {
     if (command === "plan") {
-        return planWorktree(context, { protocolId: requiredOption(parsed, "protocol-id") });
+        return planWorktree(context, { protocolId: requiredOption(parsed, "protocol-id"), projectRoot: scopeProjectRoot });
     }
     if (command === "create") {
         return createWorktreeRecord(context, {
             protocolId: requiredOption(parsed, "protocol-id"),
+            projectRoot: scopeProjectRoot,
             branch: requiredOption(parsed, "branch"),
             base: requiredOption(parsed, "base"),
             path: requiredOption(parsed, "path")
         });
     }
     if (command === "status") {
-        return getWorktreeStatus(context, { protocolId: requiredOption(parsed, "protocol-id") });
+        return getWorktreeStatus(context, { protocolId: requiredOption(parsed, "protocol-id"), projectRoot: scopeProjectRoot });
     }
     if (command === "bootstrap") {
-        return bootstrapWorktree(context, { protocolId: requiredOption(parsed, "protocol-id") });
+        return bootstrapWorktree(context, { protocolId: requiredOption(parsed, "protocol-id"), projectRoot: scopeProjectRoot });
     }
     if (command === "close") {
         return closeWorktree(context, {
             protocolId: requiredOption(parsed, "protocol-id"),
+            projectRoot: scopeProjectRoot,
             mode: requiredOption(parsed, "mode")
         });
     }
     throw new AppError("usage", `Unknown worktree command: ${command ?? "<empty>"}`, 2);
 }
-function dispatchPlanItem(context, parsed) {
+function dispatchPlanItem(context, parsed, projectRoot) {
     const action = requiredPosition(parsed, 0, "plan item action");
     const protocolId = requiredPosition(parsed, 1, "protocol-id");
     const itemId = requiredPosition(parsed, 2, "item-id");
     if (action === "start") {
-        return startPlanItem(context, { protocolId, itemId });
+        return startPlanItem(context, { protocolId, projectRoot, itemId });
     }
     if (action === "done") {
         return completePlanItem(context, {
             protocolId,
+            projectRoot,
             itemId,
             summary: requiredOption(parsed, "summary"),
             evidence: parsed.options.get("evidence") ?? []
@@ -1223,6 +1366,7 @@ function dispatchPlanItem(context, parsed) {
     if (action === "block") {
         return blockPlanItem(context, {
             protocolId,
+            projectRoot,
             itemId,
             reason: requiredOption(parsed, "reason"),
             userRequired: parseBoolean(requiredOption(parsed, "user-required"), "user-required")
@@ -1231,12 +1375,46 @@ function dispatchPlanItem(context, parsed) {
     if (action === "skip") {
         return skipPlanItem(context, {
             protocolId,
+            projectRoot,
             itemId,
             reason: requiredOption(parsed, "reason")
         });
     }
     throw new AppError("usage", `Unknown plan item action: ${action}`, 2);
 }
+function readOptionalJsonFile(file) {
+    if (!file)
+        return undefined;
+    if (!fs.existsSync(file)) {
+        throw new AppError("not_found", `JSON file does not exist: ${file}`, 1);
+    }
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        throw new AppError("validation", `JSON file is malformed: ${file}`, 2);
+    }
+}
+function parseFlowFlagOverrides(values) {
+    const result = {};
+    for (const item of values) {
+        const separator = item.indexOf("=");
+        if (separator <= 0) {
+            throw new AppError("usage", "--flag must use key=value", 2, { value: item });
+        }
+        const key = item.slice(0, separator).trim();
+        const raw = item.slice(separator + 1).trim();
+        if (!key || !raw)
+            throw new AppError("usage", "--flag must use non-empty key and value", 2, { value: item });
+        try {
+            result[key] = JSON.parse(raw);
+        }
+        catch {
+            result[key] = raw;
+        }
+    }
+    return result;
+}
 function parseArgs(args) {
     const positional = [];
     const options = new Map();
@@ -1281,6 +1459,22 @@ function requiredOption(parsed, key) {
     }
     return value;
 }
+function requiredScopeProjectRoot(root, operation) {
+    if (root)
+        return root;
+    throw new AppError("usage", `${operation} requires --project-root or a unique protocol context`, 2);
+}
+function requiredOptionOrScope(parsed, root, key) {
+    return root ?? requiredOption(parsed, key);
+}
+function requiredScopeProjectRootForOptional(root, command, parsed) {
+    if (root)
+        return root;
+    if (["complete", "note", "fail", "cancel"].includes(command ?? "")) {
+        return requiredScopeProjectRoot(root, `merge-queue ${command ?? ""}`);
+    }
+    return optionalOption(parsed, "project-root") ?? optionalOption(parsed, "root") ?? null;
+}
 function requiredOptionAlias(parsed, keys) {
     for (const key of keys) {
         const value = optionalOption(parsed, key);
@@ -1339,20 +1533,42 @@ async function readStdin(stream) {
     }
     return data;
 }
-function refreshDashboardsAfterMutation(context, args, result) {
-    if (args[0] === "project" && args[1] === "archive") {
-        refreshGlobalDashboard(context, {});
-        return;
+function refreshDashboardsAfterMutation(context, args, result, resolvedScope) {
+    try {
+        if (args[0] === "project" && args[1] === "archive") {
+            refreshGlobalDashboard(context, {});
+            return [];
+        }
+        const projectRoot = projectRootForMutation(context, args, result, resolvedScope);
+        if (!projectRoot)
+            return [];
+        autoRefreshDashboards(context, { projectRoot });
+        return [];
     }
-    const projectRoot = projectRootForMutation(context, args, result);
-    if (!projectRoot) {
-        return;
+    catch (error) {
+        return [{
+                code: "dashboard_refresh_failed",
+                message: error instanceof Error ? error.message : String(error),
+                project_root: resolvedScope
+            }];
+    }
+}
+function addWarnings(result, warnings) {
+    if (warnings.length === 0)
+        return result;
+    if (result && typeof result === "object" && !Array.isArray(result)) {
+        const record = result;
+        const existing = Array.isArray(record.warnings) ? record.warnings : [];
+        return { ...record, ok: record.ok === false ? record.ok : true, warnings: [...existing, ...warnings] };
     }
-    autoRefreshDashboards(context, { projectRoot });
+    return { ok: true, result, warnings };
 }
-function projectRootForMutation(context, args, result) {
+function projectRootForMutation(context, args, result, resolvedScope) {
     const [family, command, ...rest] = args;
     const parsed = parseArgs(rest);
+    if (isScopedProtocolMutation(family, command)) {
+        return resolvedScope ?? resolveOperationProjectRoot(context, args) ?? undefined;
+    }
     if (family === "dashboard" || family === "integration") {
         return undefined;
     }
@@ -1381,6 +1597,9 @@ function projectRootForMutation(context, args, result) {
     if (family === "plan" && command === "item") {
         return protocolProjectRoot(context, requiredPosition(parsed, 1, "protocol-id"));
     }
+    if (family === "prompt" && command === "render") {
+        return requiredOption(parsed, "project-root");
+    }
     if (family === "lane") {
         return projectRootForLaneMutation(command, parsed);
     }
@@ -1402,7 +1621,7 @@ function projectRootForMutation(context, args, result) {
         }
         return ["stop", "stop-worker"].includes(command ?? "") ? requiredOption(parsed, "project-root") : undefined;
     }
-    if (family === "run" && ["start", "attach-stage", "complete-stage", "complete"].includes(command ?? "")) {
+    if (family === "run" && ["start", "attach-stage", "complete-stage", "complete", "flags"].includes(command ?? "")) {
         return requiredOption(parsed, "project-root");
     }
     if (family === "worktree" && ["create", "bootstrap", "close"].includes(command ?? "")) {
@@ -1446,6 +1665,19 @@ function projectRootForMergeQueueMutation(context, command, parsed) {
 function protocolProjectRoot(context, protocolId) {
     return requireProtocol(context, protocolId).project_root;
 }
+function isScopedProtocolMutation(family, command) {
+    if (family === "transition")
+        return true;
+    if (family === "protocol")
+        return ["transition", "sync-from-run", "ready-for-merge", "cancel"].includes(command ?? "");
+    if (family === "plan")
+        return command === "set" || command === "item";
+    if (family === "worktree")
+        return ["create", "bootstrap", "close"].includes(command ?? "");
+    if (family === "merge-queue")
+        return ["complete", "note", "fail", "cancel"].includes(command ?? "");
+    return false;
+}
 function projectRootFromResult(result) {
     if (!result || typeof result !== "object") {
         return undefined;

package/dist/domain/entity-ids.js

@@ -1,12 +1,12 @@
 import path from "node:path";
 import { AppError } from "../shared/errors.js";
-const fullIdPattern = /^([A-Z]{2,4})-(\d{3})-([a-z0-9]+(?:-[a-z0-9]+)*)$/;
-const shortIdPattern = /^([A-Z]{2,4})-\d{3}$/;
+const fullIdPattern = /^([A-Z]{2,4})-(\d{3,})-([a-z0-9]+(?:-[a-z0-9]+)*)$/;
+const shortIdPattern = /^([A-Z]{2,4})-\d{3,}$/;
 export function parseFullEntityId(id) {
     const match = fullIdPattern.exec(id);
     if (!match?.[1] || !match[2] || !match[3]) {
         throw new AppError("validation", `Invalid typed entity id: ${id}`, 2, {
-            expected: "TYPE-NNN-slug"
+            expected: "TYPE-<decimal-sequence>-slug (at least three digits)"
         });
     }
     return {
@@ -37,7 +37,7 @@ export function formatFullId(type, sequence, slug) {
     if (!/^[A-Z]{2,4}$/.test(type)) {
         throw new AppError("validation", `Invalid entity type: ${type}`, 2);
     }
-    if (sequence < 1 || sequence > 999) {
+    if (!Number.isSafeInteger(sequence) || sequence < 1) {
         throw new AppError("validation", `Entity sequence is out of range: ${sequence}`, 2);
     }
     return `${type}-${String(sequence).padStart(3, "0")}-${slug}`;