@deksden-com/dd-flow-cli 0.7.0 → 0.8.0-beta.135

package/dist/cli/help.js

@@ -20,10 +20,12 @@ Core commands:
   protocol register/status/transition Register, inspect, transition and repair protocol state.
   migration impact/plan/report/verify/apply Assess release impact and explicitly apply mb-upgrade migration evidence.
   cleanup scan/apply            Detect and repair stale local runtime state.
-  run start/status/list/timeline/usage/flags Track concrete flow executions, timing, source-aware usage and RUN-local flow flags.
-  stage start/finish           Run the canonical two-command stage lifecycle and generate evidence.
+  run start/status/list/timeline/usage/flags/vars Track concrete flow executions, timing, source-aware usage and RUN context.
+  stat usage/run sessions ls      Refresh source-backed usage and reconcile settled Sessions, or list RUN Sessions.
+  stage start/pause/resume/finish Run a stage lifecycle, including in-stage user interaction.
+  work status|add-batch|ls|show|deps|delete|start|finish|fail|retry|cancel  Manage vNext Work.
   id next                       Preview next typed ids for protocol or run allocation.
-  plan status/item              Inspect canonical plans and update SQLite progress.
+  plan status/item/reviews      Inspect plans, update SQLite progress, or dispatch vNext grouped reviews.
   prompt render                 Render one bounded, RUN-local worker launch prompt.
   lane workspace/lock/status    Manage shared workspace lanes and leases.
   merge status/one-shot/bundle  Inspect, claim, or complete merge work from the current session.
@@ -35,6 +37,10 @@ Core commands:
   memory permissions preflight Check Memory Bank write/read permissions.
   integration cmux status       Inspect optional cmux integration.
   codex home/hooks/hook         Manage Codex homes, hooks, and hook events.
+  zcode event/usage             Ingest trusted zcode-acp lifecycle and usage evidence.
+  grok event/usage              Ingest trusted Grok Build lifecycle and usage evidence.
+  opencode event/usage          Ingest trusted OpenCode lifecycle and usage evidence.
+  agy event/usage               Ingest trusted Antigravity CLI lifecycle and usage evidence.
   worktree plan/create/status   Record Worktrunk-backed feature worktrees.
 
 Examples:
@@ -147,15 +153,23 @@ Usage:
   dd-flow id next --type protocol|run --project-root <root> --slug <slug> --json
   dd-flow run status <RUN-ID|RUN-short-id> --project-root <root> --json
   dd-flow run list --project-root <root> --json
+  dd-flow run prepare-vnext-specify --project-root <root> --slug <slug> --json
+  dd-flow run snapshot create <RUN-ID|RUN-short-id> (--stage-entry <stage>|--candidate) --project-root <root> --output <directory> --json
+  dd-flow run snapshot restore --snapshot <directory> --project-root <prepared-root> --json
+  dd-flow run snapshot bootstrap create --project-root <root> --output <directory> --json
+  dd-flow run snapshot bootstrap restore --snapshot <directory> --project-root <prepared-root> --json
   dd-flow run timeline <RUN-ID|RUN-short-id> --project-root <root> --json
-  dd-flow run usage <RUN-ID|RUN-short-id> --project-root <root> [--group-by session|role|stage|aspect|plan-item] --json
+  dd-flow stat usage --run <RUN-ID|RUN-short-id> --project-root <root> [--stage <stage[,stage...]>] [--session <session-id>] --json
+  dd-flow stat run sessions ls --run <RUN-ID|RUN-short-id> --project-root <root> --json
   dd-flow run flags status <RUN-ID|RUN-short-id> --project-root <root> --json
   dd-flow run flags revise <RUN-ID|RUN-short-id> --project-root <root> --expected-revision <n> --idempotency-key <key> [--preset <name>] [--flag key=value] [--flag key=value] [--allow-downgrade --reason <text>] --json
   dd-flow run attach-stage <RUN-ID|RUN-short-id> --project-root <root> --stage <name> --dir <NN-stage-slug> --status <status> [--data-schema-id <id>] --json
   dd-flow run complete-stage <RUN-ID|RUN-short-id> --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-short-id> --project-root <root> --status done|blocked|cancelled|failed [--verdict <text>] [--next-action <text>] --json
+  dd-flow run override <RUN-ID|RUN-short-id> --project-root <root> --status cancelled|failed --reason <text> [--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. New run artifacts are stored under DD_FLOW_HOME/projects/<PRJ-ID-slug>/runs/<RUN-ID-slug>/ with one run.json projection and an append-only timeline.jsonl. Timeline is the compact full run report: summary is always present, while --hide may suppress bulky sections. The run usage command reconciles registered local Codex transcript counters before reporting; unavailable data is explicit rather than zero.
+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 one run.json projection and an append-only timeline.jsonl. Timeline is the compact full run report: summary is always present, while --hide may suppress bulky sections. Use \`dd-flow stat usage --run …\` to reread registered local Codex transcript counters and tool-call facts and refresh the current usage projection; unavailable data is explicit rather than zero.
+
+run prepare-vnext-specify allocates an otherwise unstarted vNext RUN for the canonical SPECIFY entry checkpoint. run snapshot is the eval-only checkpoint boundary: it snapshots one quiescent RUN, its dedicated DD_FLOW_HOME, and the exact project tree including its Git repository, then restores them into a fresh dedicated runtime. It is not a general runtime backup command and fails closed for a shared runtime.
 
 Examples:
   dd-flow run start --project-root "$PWD" --flow-kind mb_sdlc --subject-type protocol --subject-id PRT-001-demo --slug demo --json
@@ -168,11 +182,31 @@ Examples:
         `dd-flow stage - execute one bounded stage lifecycle
 
 Usage:
-  dd-flow stage start <RUN-ID|RUN-short-id> --project-root <root> --stage <name> [--dir <NN-stage-slug>] --json
-  dd-flow stage start --bootstrap --project-root <root> --stage specify --subject <safe-subject> [--intake-file <path>] --json
-  dd-flow stage finish <RUN-ID|RUN-short-id> --project-root <root> --stage <name> [--outcome done|blocked|failed] [--semantic-file <RUN-local-json>] --json
+  dd-flow stage start <RUN-ID|RUN-short-id> --project-root <root> --stage <name> [--dir <NN-stage-slug>] [--require-session-binding] --json
+  dd-flow stage start --bootstrap --project-root <root> --stage specify --subject <safe-subject> (--intake-file <path>|--intake-stdin) [--require-session-binding] --json
+  dd-flow stage pause <RUN-ID|RUN-short-id> --project-root <root> --stage <name> --work <WORK-ID> --question-stdin --json
+  dd-flow stage resume <RUN-ID|RUN-short-id> --project-root <root> --stage <name> --work <WORK-ID> --answer-stdin --json
+  dd-flow stage block <RUN-ID|RUN-short-id> --project-root <root> --stage <name> --work <WORK-ID> --kind engine|harness|environment --code <code> --summary-stdin [--retryable] --json
+  dd-flow stage unblock <RUN-ID|RUN-short-id> --project-root <root> --stage <name> --work <WORK-ID> --json
+  dd-flow stage fanout status <RUN-ID|RUN-short-id> --project-root <root> --stage <name> --json
+  dd-flow stage fanout dispatch <RUN-ID|RUN-short-id> --project-root <root> --stage <name> --json
+  dd-flow stage finish <RUN-ID|RUN-short-id> --project-root <root> --stage <name> [--semantic-file <RUN-local-json>] --json
+  dd-flow stage finish <RUN-ID|RUN-short-id> --project-root <root> --stage specify (--result-file <RUN-local-specify.json>|--result-stdin) --outcome <specified|failed|cancelled> --json
 
-stage start is the worker's first practical flow command. It performs deterministic setup and returns a ready-to-use, stage-specific work packet with trusted runtime facts, compatibility and permission preflight, aliases, write boundary and exact finish command. The same packet is written to RUN-local stage-prompt.md and stage-prompt.json. --bootstrap creates the initial protocol/RUN envelope and copies the supplied intake into the RUN home before starting specify. stage finish defaults to @stage/stage-input.json, accepts semantic --outcome and always generates validated JSON, Markdown, template-backed HTML and a durable protocol-summary projection. Raw intake and telemetry remain RUN-local.`
+stage start is the worker's first practical flow command. It performs deterministic setup and returns a ready-to-use, stage-specific work packet with trusted runtime facts, compatibility and permission preflight, aliases, write boundary and exact lifecycle commands. A material user question uses stage pause, not stage finish: pause leaves the same stage, Work, Session and attempt open and returns the exact resume command. Engine, harness and environment failures use stage block and never create HITL. On the next Turn, pass a complete user answer to stage resume, or repair an external blocker and call its returned stage unblock command. stage fanout is read-only orchestration state plus the stage's deterministic Work materialization action for an external runner; it never makes product decisions. stage finish is reserved for actual stage completion and generates the final deterministic reports. Generated lifecycle commands include DD_FLOW_HOME when the RUN uses a non-default runtime.`
+    ],
+    [
+        "work",
+        `dd-flow work - inspect or advance a beta vNext Work
+
+Usage:
+  dd-flow work ls (--run <RUN-ID>|--parent <WORK-ID>) [--ready] --json
+  dd-flow work show <WORK-ID> --json
+  dd-flow work start <WORK-ID> --project-root <root> --json
+  dd-flow work finish <WORK-ID> (--result-file <path>|--result-stdin) --project-root <root> --json
+  dd-flow work repair add --run <RUN-ID> --from-check <CHECK-ID> --origin-work <WORK-ID>... [--write-scope <path>...] --task-stdin --project-root <root> --json
+
+CODE workers receive their full accepted packet from work start. work finish validates the result and executes the packet's focused checks before completion. A failed aggregate CODE gate returns the exact failed receipt and repair command; repair add creates a new Work from the selected completed origin context plus that failure evidence. Exact existing project files named by the retained receipt output are added to its repair scope deterministically; repeat --write-scope only for an additional path not named there.`
     ],
     [
         "id",
@@ -412,6 +446,16 @@ Usage:
   dd-flow session stop-worker --project-root <root> --worker-id <id> --reason <text> --json
 
 Session registration is the durable contract used by Stop hooks. Prompts register flow_kind, continuation_policy, protocol_id, worker_id, and workspace_path explicitly. Prefer --payload-file in Codex prompts because PreToolUse hooks see the raw shell command before variable expansion.`
+    ],
+    [
+        "run config",
+        `dd-flow run config - inspect and set RUN-scoped flow choices
+
+Usage:
+  dd-flow run config status <RUN-ID> --project-root <root> --json
+  dd-flow run config set <RUN-ID> --project-root <root> --key plan_review.mode --value auto|off|standard|deep --reason <text> --json
+
+PLAN review policy belongs to the RUN. It defaults to auto and is frozen once PLAN-REVIEW starts. The CLI never infers this choice from intake prose.`
     ],
     [
         "project config",
@@ -540,6 +584,40 @@ handler resolves the registered project from cwd. The option is only a manual
 override.
 
 Managed homes isolate dd-flow hooks while sharing selected Codex state from the source home.`
+    ],
+    [
+        "zcode event",
+        `dd-flow zcode event - ingest a zcode-acp session/update notification
+
+Usage:
+  dd-flow zcode event handle --project-root <root> --json
+  dd-flow zcode usage ingest --project-root <root> --json
+
+Both payloads are read from stdin. The event adapter retains lifecycle identity;
+the usage adapter retains cumulative provider counters for RUN accounting.`
+    ],
+    [
+        "opencode event",
+        `dd-flow opencode event - ingest a controlled OpenCode tool hook
+
+Usage:
+  dd-flow opencode event handle --project-root <root> --json
+  dd-flow opencode usage ingest --project-root <root> --json
+
+Both payloads are read from stdin. The event adapter reuses the trusted
+lifecycle receipt; the usage adapter retains cumulative OpenCode Session and
+tool counters for RUN accounting.`
+    ],
+    [
+        "agy event",
+        `dd-flow agy event - ingest a controlled Antigravity CLI tool hook
+
+Usage:
+  dd-flow agy event handle --project-root <root> --json
+  dd-flow agy usage ingest --project-root <root> --json
+
+Both payloads are read from stdin. The event adapter records lifecycle identity;
+the usage adapter retains cumulative conversation and tool counters.`
     ],
     [
         "worktree",