@beyondwork/docx-react-component 1.0.0

package/docs/reference/cli-reference.md

@@ -0,0 +1,600 @@
+---
+title: "CLI Reference"
+summary: "Complete syntax reference for all wave CLI commands, flags, and operator surfaces."
+---
+
+# CLI Reference
+
+Complete syntax for every `wave` command. All commands use `pnpm exec wave` as the entry point.
+
+## Command Families
+
+- Runtime:
+  `wave launch`, `wave autonomous`, and `wave local` cover dry-run validation, live execution, and executor-specific prompt transport.
+- Operator control:
+  `wave control` is the preferred surface for live status, tasks, reruns, proof bundles, and telemetry.
+- Compatibility and inspection:
+  `wave coord`, `wave retry`, and `wave proof` remain available where older runbooks still depend on them.
+- Planning and transient work:
+  `wave project`, `wave draft`, and `wave adhoc` cover defaults, authored waves, and operator-driven one-off runs.
+- Setup and lifecycle:
+  `wave init`, `wave doctor`, `wave upgrade`, and `wave self-update` cover workspace adoption, validation, and package upgrades.
+
+## wave launch
+
+Launch waves for execution.
+
+```
+wave launch [options]
+```
+
+Defaults below reflect the starter workspace surface in this repo. Lane config can override executor, timeout, retry, and terminal defaults.
+
+Closure-role bindings do not have a CLI override surface. When a wave file declares custom integration, documentation, `cont-QA`, `cont-EVAL`, or security-review role ids, launch, retry, reducer, and closure flows honor those wave-level bindings end to end.
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--lane <name>` | `main` | Lane name |
+| `--start-wave <n>` | `0` | First wave to launch |
+| `--end-wave <n>` | last available | Last wave to launch |
+| `--auto-next` | off | Start from next unfinished wave and continue |
+| `--resume-control-state` | off | Preserve the prior auto-generated relaunch plan instead of treating the launch as a fresh wave start |
+| `--executor <id>` | `codex` | Default executor: `codex`, `claude`, `opencode`, `local` |
+| `--codex-sandbox <mode>` | `danger-full-access` | Codex sandbox isolation level |
+| `--timeout-minutes <n>` | `240` | Max minutes to wait per wave |
+| `--max-retries-per-wave <n>` | `1` | Relaunch failed agents per wave |
+| `--agent-rate-limit-retries <n>` | `2` | Per-agent retries for 429 errors |
+| `--agent-rate-limit-base-delay-seconds <n>` | `20` | Base exponential backoff for 429 |
+| `--agent-rate-limit-max-delay-seconds <n>` | `180` | Max backoff delay for 429 |
+| `--agent-launch-stagger-ms <n>` | `1200` | Delay between agent launches |
+| `--terminal-surface <mode>` | `vscode` | `tmux`, `vscode`, or `none` |
+| `--no-dashboard` | off | Disable per-wave tmux dashboard |
+| `--cleanup-sessions` | on | Kill lane tmux sessions after each wave |
+| `--keep-sessions` | off | Keep lane tmux sessions |
+| `--keep-terminals` | off | Keep temporary terminal entries |
+| `--orchestrator-id <id>` | generated | Stable orchestrator identity |
+| `--orchestrator-board <path>` | default board path | Write coordination-board updates to a specific shared board |
+| `--no-orchestrator-board` | off | Disable shared orchestrator-board writes for this run |
+| `--coordination-note <text>` | empty | Append a startup intent note to orchestrator-board updates |
+| `--resident-orchestrator` | off | Launch long-running non-owning orchestrator session |
+| `--no-telemetry` | off | Disable Wave Control event publication |
+| `--no-context7` | off | Disable Context7 prefetch |
+| `--dry-run` | off | Parse and validate only; do not execute |
+| `--reconcile-status` | off | Reconcile run-state from status files and exit |
+| `--state-file <path>` | default | Path to run-state JSON |
+| `--manifest-out <path>` | default | Write parsed manifest JSON |
+
+## wave autonomous
+
+Continuous wave execution without manual wave-by-wave invocation.
+
+```
+wave autonomous [options]
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--lane <name>` | `main` | Lane name |
+| `--executor <id>` | lane config | `codex`, `claude`, or `opencode` (not `local`) |
+| `--codex-sandbox <mode>` | `danger-full-access` | Codex sandbox mode |
+| `--timeout-minutes <n>` | `240` | Per-wave timeout passed to launcher |
+| `--max-retries-per-wave <n>` | `1` | Per-wave relaunches inside launcher |
+| `--max-attempts-per-wave <n>` | `1` | External attempts per wave |
+| `--agent-rate-limit-retries <n>` | `2` | Per-agent 429 retries |
+| `--agent-rate-limit-base-delay-seconds <n>` | `20` | Base 429 backoff |
+| `--agent-rate-limit-max-delay-seconds <n>` | `180` | Max 429 backoff |
+| `--agent-launch-stagger-ms <n>` | `1200` | Delay between agent launches |
+| `--orchestrator-id <id>` | `<lane>-autonomous` | Orchestrator identity |
+| `--resident-orchestrator` | off | Launch resident orchestrator for each wave |
+| `--dashboard` | off | Enable dashboards |
+| `--keep-sessions` | off | Keep tmux sessions between waves |
+| `--keep-terminals` | off | Keep terminal entries between waves |
+
+## wave control
+
+Unified operator control surface. Preferred over legacy `wave coord`, `wave retry`, and `wave proof`.
+
+### wave control status
+
+Read-only view: blocking edges, logical agent state, tasks, dependencies, rerun intent, proof bundles, next timers, and derived wave or agent signal snapshots.
+
+When a launcher attempt is already running, `wave control status` treats that active attempt as the authoritative current fan-out. Older relaunch plans or unrelated closure blockers remain visible in the payload, but they do not override the live attempt view.
+
+```
+wave control status --lane <lane> --wave <n> [--agent <id>] [--run <id>] [--json]
+```
+
+The JSON payload now includes:
+
+- `signals.wave`
+  Versioned wave-level signal state for wrappers and external operators.
+- `signals.agents`
+  Versioned per-agent signal state, including `shouldWake` plus any observed ack metadata.
+
+Starter repos also include `scripts/wave-status.sh` and `scripts/wave-watch.sh` as thin readers over this JSON payload. They use exit `0` for completed, `20` for input-required, `40` for failed, and `30` from `wave-watch.sh --until-change` when the signal changed but the wave stayed active. For the full wrapper contract, read [../guides/signal-wrappers.md](../guides/signal-wrappers.md).
+
+### wave control telemetry
+
+Inspect and deliver the local Wave Control event queue.
+
+```
+wave control telemetry status --lane <lane> [--run <id>] [--json]
+wave control telemetry flush  --lane <lane> [--run <id>] [--json]
+```
+
+### wave control task
+
+Operator task surface for coordination records.
+
+**Create a task:**
+
+```
+wave control task create \
+  --lane <lane> --wave <n> --agent <id> \
+  --kind <kind> --summary "<text>" \
+  [--detail "<text>"] [--target <agent-or-capability>] \
+  [--priority normal|high] [--blocking true|false] \
+  [--severity hard|soft|stale|advisory|proof-critical|closure-critical] \
+  [--depends-on <id>] \
+  [--artifact <ref>] [--operator <name>] [--json]
+```
+
+Valid `--kind` values: `request`, `blocker`, `clarification`, `handoff`, `evidence`, `claim`, `decision`, `human-input`.
+
+`wave control status` only treats `request`, `blocker`, `clarification`, `human-input`, and `escalation` as potentially blocking. Tasks of those kinds can still be downgraded with `blocking=false` or non-blocking severities such as `advisory` and `stale`, so they remain visible without owning the active blocking edge.
+
+**List tasks:**
+
+```
+wave control task list --lane <lane> --wave <n> [--agent <id>] [--json]
+```
+
+**Get a single task:**
+
+```
+wave control task get --lane <lane> --wave <n> --id <task-id> [--json]
+```
+
+**Act on a task:**
+
+```
+wave control task act <action> \
+  --lane <lane> --wave <n> --id <task-id> \
+  [--detail "<text>"] [--operator <name>] [--json]
+```
+
+Actions:
+
+| Action | Extra flags | Effect |
+|--------|------------|--------|
+| `start` | — | Mark task in-progress |
+| `resolve` | `[--detail]` | Close the task as resolved |
+| `dismiss` | `[--detail]` | Close the task as not applicable |
+| `cancel` | `[--detail]` | Cancel the task |
+| `reassign` | `--to <agent>` | Supersede the original, reroute to a new agent |
+| `answer` | `--response "<text>"` | Answer a human-input or escalation task |
+| `escalate` | `[--detail]` | Escalate to human feedback queue |
+| `defer` | `[--detail]` | Keep the task open but mark it non-blocking soft work |
+| `mark-advisory` | `[--detail]` | Keep the task visible but non-blocking with advisory severity |
+| `mark-stale` | `[--detail]` | Keep the task as historical context without blocking closure |
+| `resolve-policy` | `[--detail]` | Close the task by operator policy and downgrade linked clarification follow-up when applicable |
+
+**Operator answer example** (responding to a human-input escalation):
+
+```bash
+pnpm exec wave control task act answer \
+  --lane main --wave 4 --id escalation-clarify-a7-rollout \
+  --response "The rollout strategy is canary-then-full. Use the Railway MCP health endpoint." \
+  --operator ops-lead
+```
+
+### wave control rerun
+
+Targeted rerun intent with agent selection, reuse control, and component invalidation.
+
+**Request a rerun:**
+
+```
+wave control rerun request \
+  --lane <lane> --wave <n> \
+  [--agent <id> ...] \
+  [--clear-reuse <id> ...] [--preserve-reuse <id> ...] \
+  [--invalidate-component <id> ...] \
+  [--resume-cursor <cursor>] \
+  [--reuse-attempt <id> ...] [--reuse-proof <id> ...] \
+  [--reuse-derived-summaries true|false] \
+  [--requested-by <name>] [--reason "<text>"] [--json]
+```
+
+`--agent` is repeatable or comma-separated. At least one of `--agent` or `--resume-cursor` is required.
+
+The launcher may also write a rerun request automatically after recoverable failures such as timeout, max-turn, rate-limit, or missing-status outcomes. Those requests still appear through `wave control rerun get`, so operators can inspect or replace the targeted recovery plan before the next attempt.
+
+**Get active rerun request:**
+
+```
+wave control rerun get --lane <lane> --wave <n> [--json]
+```
+
+**Clear rerun request:**
+
+```
+wave control rerun clear --lane <lane> --wave <n>
+```
+
+### wave control proof
+
+Authoritative proof bundle lifecycle (active → superseded → revoked).
+
+**Register a proof bundle:**
+
+```
+wave control proof register \
+  --lane <lane> --wave <n> --agent <id> \
+  --artifact <path> [--artifact <path> ...] \
+  [--component <id[:level]> ...] \
+  [--authoritative] [--satisfy-owned-components] \
+  [--completion <level>] [--durability <level>] [--proof-level <level>] \
+  [--doc-delta <state>] [--operator <name>] [--detail "<text>"] [--json]
+```
+
+**Get proof bundles:**
+
+```
+wave control proof get --lane <lane> --wave <n> [--agent <id>] [--id <bundle-id>] [--json]
+```
+
+**Supersede a bundle** (register new evidence and mark the old bundle superseded):
+
+```
+wave control proof supersede \
+  --lane <lane> --wave <n> --id <old-bundle-id> \
+  --agent <id> --artifact <path> [--artifact <path> ...] \
+  [same options as register] [--json]
+```
+
+**Revoke a bundle:**
+
+```
+wave control proof revoke \
+  --lane <lane> --wave <n> --id <bundle-id> \
+  [--operator <name>] [--detail "<text>"] [--json]
+```
+
+## wave coord
+
+Coordination log access. Legacy surface; prefer `wave control task` for new work.
+
+**Post a coordination record:**
+
+```
+wave coord post \
+  --lane <lane> --wave <n> --agent <id> \
+  --kind <kind> --summary "<text>" \
+  [--detail "<text>"] [--target <agent>] \
+  [--priority normal|high] [--depends-on <id>] \
+  [--artifact <ref>] [--status <status>] [--dry-run]
+```
+
+**Show materialized coordination state:**
+
+```
+wave coord show --lane <lane> --wave <n> [--dry-run] [--json]
+```
+
+**Render markdown board from JSONL log:**
+
+```
+wave coord render --lane <lane> --wave <n> [--dry-run]
+```
+
+**Compile shared summary and agent inbox:**
+
+```
+wave coord inbox --lane <lane> --wave <n> --agent <id> [--dry-run]
+```
+
+**Explain why blocked or retrying:**
+
+```
+wave coord explain --lane <lane> --wave <n> [--agent <id>] [--json]
+```
+
+**Act on a coordination record:**
+
+```
+wave coord act <operation> --lane <lane> --wave <n> --id <id> [options]
+```
+
+| Operation | Extra flags | Effect |
+|-----------|------------|--------|
+| `resolve` | `[--detail]` | Resolve the record |
+| `dismiss` | `[--detail]` | Dismiss the record |
+| `reroute` | `--to <agent>` | Reroute to another agent |
+| `reassign` | `--to <agent>` | Reassign to another agent |
+| `escalate` | `[--detail]` | Escalate to human feedback |
+| `answer-human` | `--response "<text>"` | Answer a human feedback request |
+
+All `wave coord` subcommands accept `--run <id>` as a shorthand that sets the lane and wave to 0 for ad-hoc runs.
+
+## wave feedback
+
+Human feedback request queue. Final escalation layer after orchestrator-first triage.
+
+**Create a feedback request:**
+
+```
+wave feedback ask \
+  --lane <lane> --wave <n> --agent <id> \
+  --question "<text>" [--context "<text>"] \
+  [--orchestrator-id <id>] [--wait] [--timeout-seconds <n>]
+```
+
+**Respond to a feedback request:**
+
+```
+wave feedback respond \
+  [--run <id>] --id <request-id> --response "<text>" \
+  [--operator <name>] [--force]
+```
+
+`--force` overrides a previously answered request.
+
+When the answered request belongs to a live wave or ad-hoc run, `wave feedback respond` also reconciles the linked clarification, escalation, and helper-assignment state in canonical coordination. If no attempt is still running and the reducer can safely continue, it writes a one-shot continuation request instead of relaunching directly. Use `--run <id>` when answering an ad-hoc request so reconciliation targets the isolated ad-hoc state root.
+
+**List feedback requests:**
+
+```
+wave feedback list [--lane <lane>] [--wave <n>] [--agent <id>] [--pending] [--json]
+```
+
+**Watch for new requests:**
+
+```
+wave feedback watch [--lane <lane>] [--wave <n>] [--agent <id>] [--pending] [--refresh-ms <n>]
+```
+
+**Show a single request:**
+
+```
+wave feedback show --id <request-id>
+```
+
+All `wave feedback` subcommands accept `--run <id>` for ad-hoc runs.
+
+## wave dep
+
+Cross-lane dependency management.
+
+**Post a dependency ticket:**
+
+```
+wave dep post \
+  --owner-lane <lane> --requester-lane <lane> \
+  --owner-wave <n> --requester-wave <n> \
+  --agent <id> --summary "<text>" \
+  [--detail "<text>"] [--target <agent>] \
+  [--artifact <ref>] [--priority normal|high] \
+  [--closure-condition "<text>"] [--required] [--json]
+```
+
+`--required` means the dependency blocks autonomous launch and lane finalization.
+
+**Show dependencies:**
+
+```
+wave dep show --lane <lane> [--wave <n>] [--json]
+```
+
+**Resolve a dependency:**
+
+```
+wave dep resolve --lane <lane> --id <id> --agent <id> [--detail "<text>"] [--status resolved|closed]
+```
+
+**Render dependency snapshot:**
+
+```
+wave dep render --lane <lane> [--wave <n>] [--json]
+```
+
+## wave benchmark
+
+Local and external benchmark execution.
+
+**List local cases:**
+
+```
+wave benchmark list [--json]
+```
+
+**Show a case definition:**
+
+```
+wave benchmark show --case <id> [--json]
+```
+
+**Run local benchmark cases:**
+
+```
+wave benchmark run [--case <id>] [--family <id>] [--benchmark <id>] [--arm <id>] [--output-dir <path>] [--json]
+```
+
+**List external adapters:**
+
+```
+wave benchmark adapters [--json]
+```
+
+**External benchmark commands:**
+
+```
+wave benchmark external-list [--adapter <id>] [--json]
+wave benchmark external-show --adapter <id> --manifest <path> [--json]
+wave benchmark external-run --adapter <id> --manifest <path> [--arm <id>] [--model <id>] [options]
+wave benchmark external-pilots --adapter <id> [--json]
+```
+
+## wave retry
+
+Legacy retry control. Prefer `wave control rerun`.
+
+**Show active retry override:**
+
+```
+wave retry show --lane <lane> --wave <n> [--json]
+```
+
+**Apply a retry override:**
+
+```
+wave retry apply --lane <lane> --wave <n> \
+  [--agent <id> ...] \
+  [--clear-reuse <id> ...] [--preserve-reuse <id> ...] \
+  [--resume-phase <phase>] \
+  [--requested-by <name>] [--reason "<text>"] [--json]
+```
+
+Requires either `--agent` or `--resume-phase`.
+
+**Clear retry override:**
+
+```
+wave retry clear --lane <lane> --wave <n>
+```
+
+## wave proof
+
+Legacy proof registration. Prefer `wave control proof`.
+
+**Show proof registry:**
+
+```
+wave proof show --lane <lane> --wave <n> [--agent <id>] [--json]
+```
+
+**Register proof:**
+
+```
+wave proof register --lane <lane> --wave <n> --agent <id> \
+  --artifact <path> [--artifact <path> ...] \
+  [--component <id[:level]> ...] \
+  [--authoritative] [--satisfy-owned-components] \
+  [--completion <level>] [--durability <level>] [--proof-level <level>] \
+  [--doc-delta <state>] [--operator <name>] [--detail "<text>"] [--json]
+```
+
+## wave local
+
+Smoke executor for testing prompt generation and closure signal extraction.
+
+```
+wave local --prompt <path> [--log <path>] [--status <path>]
+```
+
+## wave dashboard
+
+Live dashboard viewer.
+
+```
+wave dashboard --dashboard-file <path> [--lane <lane>] [--message-board <path>] [--watch] [--refresh-ms <n>]
+wave dashboard --lane <lane> --attach current|global
+```
+
+## Workspace Commands
+
+**Initialize workspace:**
+
+```
+wave init [--adopt-existing]
+```
+
+**Upgrade workspace after package update:**
+
+```
+wave upgrade
+```
+
+**One-command package update:**
+
+```
+wave self-update
+```
+
+**Show changelog since installed version:**
+
+```
+wave changelog [--since-installed]
+```
+
+**Health check:**
+
+```
+wave doctor [--json]
+```
+
+## Planner Commands
+
+**Setup project profile:**
+
+```
+wave project setup
+wave project show [--json]
+```
+
+**Draft waves:**
+
+```
+wave draft --wave <n> [--template implementation|qa|infra|release]
+wave draft --agentic --task "<description>" --from-wave <n>
+wave draft --show-run <run-id>
+wave draft --apply-run <run-id>
+```
+
+Interactive draft currently offers worker role kinds:
+
+- `design`
+- `implementation`
+- `qa`
+- `infra`
+- `deploy`
+- `research`
+- `security`
+
+Agentic planner payloads also accept `workerAgents[].roleKind = "design"`. The shipped `0.8.9` surface uses `design-pass` as the default executor profile for that role and typically assigns a packet path like `docs/plans/waves/design/wave-<n>-<agentId>.md`. Interactive draft scaffolds the docs-first default; hybrid design stewards are authored by explicitly adding implementation-owned paths and the normal implementation contract sections.
+
+## Ad-Hoc Task Commands
+
+**Plan and run ad-hoc tasks:**
+
+```
+wave adhoc plan --task "<description>"
+wave adhoc run --task "<description>" [--yes] [--executor <id>]
+wave adhoc list [--json]
+wave adhoc show --run <id> [--json]
+wave adhoc promote --run <id> --wave <n>
+```
+
+## Common Patterns
+
+### Lane and wave targeting
+
+Most coordination commands accept `--lane` (default: `main`) and `--wave` (required). For ad-hoc runs, use `--run <id>` which sets the lane and defaults wave to 0.
+
+### JSON output
+
+Most commands accept `--json` for machine-readable output.
+
+### Operator attribution
+
+Commands that modify state accept `--operator <name>` (default: `human-operator`) for audit trails.
+
+### Repeatable flags
+
+Flags like `--agent`, `--artifact`, `--component`, `--target`, and `--depends-on` can be repeated or comma-separated:
+
+```bash
+# These are equivalent:
+wave control rerun request --lane main --wave 0 --agent A2 --agent A7
+wave control rerun request --lane main --wave 0 --agent A2,A7
+```