@chllming/wave-orchestration 0.8.9 → 0.9.0

package/docs/plans/migration.md

@@ -1,6 +1,6 @@
 # Migration
 
-This page is the practical repo-upgrade guide for the current `0.8.9` surface.
+This page is the practical repo-upgrade guide for the current `0.9.0` surface.
 
 Use it when you are:
 
@@ -10,20 +10,21 @@ Use it when you are:
 
 For the completed internal architecture cutover record, see [architecture-hardening-migration.md](./architecture-hardening-migration.md). That document is historical. This one is the operator-facing upgrade checklist.
 
-## What `0.8.9` Changes
+## What `0.9.0` Changes
 
-The current `0.8.9` surface keeps the `0.8.8` packaged operator-guidance alignment and adds a focused repair for design-pass replay and post-design transition handling.
+The current `0.9.0` surface keeps the packaged operator-guidance alignment and adds first-class monorepo project support plus project-aware default telemetry.
 
 The practical changes are:
 
-- reducer snapshots now preserve design packet report paths when they rebuild summaries from result envelopes
-- blocked design passes now stop at the design gate instead of being surfaced later as downstream implementation envelope failures
-- trace bundle summary reconstruction now also resolves design packet report paths, so copied design summaries stay aligned when they are rebuilt from logs
-- the current release surface and tracked install-state fixtures now all move together on `0.8.9`
+- `wave.config.json` can now declare `defaultProject` and `projects.<projectId>`, so one repo can host multiple Wave projects without lane-name collisions
+- planner defaults, docs roots, ad-hoc runs, dependency tickets, launcher state, and benchmark identity are now scoped by project when you use explicit monorepo projects
+- lane-scoped commands now accept `--project`, so the CLI can target the right project without relying on lane names alone
+- Wave Control defaults to `https://wave-control.up.railway.app/api/v1` with `reportMode: "metadata-only"` and sends project, lane, and wave metadata unless you explicitly opt out
+- the current release surface and tracked install-state fixtures now all move together on `0.9.0`
 
-If your repo copied starter docs, shell automation, or operator runbooks, these are the areas most likely to need a sync before the `0.8.9` package cut.
+If your repo copied starter docs, shell automation, runbooks, or `wave.config.json` defaults, these are the areas most likely to need a sync before the `0.9.0` package cut.
 
-For a practical `0.8.9` operating stance after the upgrade, read [../guides/recommendations-0.8.9.md](../guides/recommendations-0.8.9.md).
+For a practical `0.9.0` operating stance after the upgrade, read [../guides/recommendations-0.9.0.md](../guides/recommendations-0.9.0.md).
 
 ## What `0.8.6` Changes
 
@@ -90,7 +91,7 @@ pnpm exec wave upgrade
 
 ### 3. Sync repo-owned starter surface only if you copied it
 
-The most common sync set for `0.8.6` is:
+The most common sync set for `0.9.0` is:
 
 - `docs/agents/wave-launcher-role.md`
 - `docs/agents/wave-orchestrator-role.md`
@@ -119,6 +120,8 @@ The most common sync set for `0.8.6` is:
 
 If your repo copied starter `wave.config.json` defaults, also sync:
 
+- `defaultProject`
+- `projects.<projectId>`
 - `roles.designRolePromptPath`
 - `skills.byRole.design`
 - `executors.profiles.design-pass`
@@ -138,14 +141,14 @@ pnpm exec wave coord inbox --lane main --wave 0 --agent A1 --dry-run
 
 Use `pnpm exec wave dashboard --lane <lane> --attach current` or `--attach global` when you need to reattach to a tmux-backed dashboard after the upgrade.
 
-## `0.8.9` Release Model
+## `0.9.0` Release Model
 
-The current `0.8.9` surface is three changes together:
+The current `0.9.0` surface is three changes together:
 
 - the shipped `design` worker role and hybrid design-steward flow introduced in `0.8.5`
 - the signal-driven long-running-agent and wrapper model introduced in `0.8.6`
 - the policy-consistency, targeted-recovery, capability-specific routing, and stable per-wave session reuse hardening introduced in `0.8.7`
-- the packaged recommendations guide and install-state alignment follow-up released in `0.8.9`
+- the packaged recommendations guide and install-state alignment follow-up released in `0.9.0`
 
 ### Signal-driven waiting and wrapper model
 
@@ -329,9 +332,9 @@ If the repo copied starter `wave.config.json` defaults, also sync:
 - if the repo uses hybrid design stewards, confirm the same agent rejoins implementation only when the authored wave explicitly gives it code ownership
 - if the repo uses long-running agents or shell automation, confirm the new wrapper exit contract and ack-loop semantics before relying on an older polling script
 
-## Upgrading From `0.8.3` To `0.8.9`
+## Upgrading From `0.8.3` To `0.9.0`
 
-Treat this as one move to the current `0.8.9` surface.
+Treat this as one move to the current `0.9.0` surface.
 
 ### What changed across that range
 
@@ -364,7 +367,7 @@ If your repo copied starter docs or skills, sync:
 - dry-run one design-steward wave if the repo wants the new authored surface
 - if the repo uses long-running watcher agents or shell automation, validate `scripts/wave-status.sh` and `scripts/wave-watch.sh` against a live or staged lane
 
-## Upgrading From `0.6.x` Or `0.7.x` To `0.8.9`
+## Upgrading From `0.6.x` Or `0.7.x` To `0.9.0`
 
 This is the main migration path for older adopted repos.
 
@@ -405,7 +408,7 @@ pnpm exec wave control proof get --lane main --wave 0 --json
 
 If the repo carries proof-first waves, verify that required proof artifacts still exist locally and not only in historical summaries.
 
-## Upgrading From `0.5.x` Or Earlier To `0.8.9`
+## Upgrading From `0.5.x` Or Earlier To `0.9.0`
 
 Do not treat this as a tiny patch bump.
 
@@ -515,4 +518,4 @@ For repos that depend on replay parity, replay at least:
 
 ## Summary
 
-The current `0.8.9` surface keeps the same authority-set and phase-engine architecture, ships both the design-role starter surface and the signal-driven long-running-agent starter surface, keeps the `0.8.7` policy and routing hardening, and now also packages the practical operator recommendations guide inside the release line. For most repos already on `0.8.x`, the upgrade is package bump plus validation. For older adopted repos, the real work is syncing repo-owned prompts, skills, planner corpus, wrapper scripts, and runbooks so they describe the runtime the package now ships.
+The current `0.9.0` surface keeps the same authority-set and phase-engine architecture, ships both the design-role starter surface and the signal-driven long-running-agent starter surface, keeps the `0.8.7` policy and routing hardening, and now also packages the practical operator recommendations guide inside the release line. For most repos already on `0.8.x`, the upgrade is package bump plus validation. For older adopted repos, the real work is syncing repo-owned prompts, skills, planner corpus, wrapper scripts, and runbooks so they describe the runtime the package now ships.

package/docs/plans/wave-orchestrator.md

@@ -38,7 +38,7 @@ The live runtime is organized around explicit modules:
 ## What It Does
 
 - parses wave plans from `docs/plans/waves/`
-- supports transient ad-hoc runs from `.wave/adhoc/runs/` on the same runtime substrate
+- supports transient ad-hoc runs from project-scoped `.wave/adhoc/<projectId>/runs/` storage on the same runtime substrate, with the implicit default project keeping the legacy layout
 - fans a wave out into one session per `## Agent ...` section
 - supports standing role imports from `docs/agents/*.md`
 - supports optional pre-implementation design stewards that publish design packets before code-owning implementation starts
@@ -103,9 +103,9 @@ The live runtime is organized around explicit modules:
 - `docs/reference/wave-control.md` documents the Wave Control telemetry and analysis plane, including entity types, artifact upload policies, and the local-first reporting contract.
 - `docs/plans/component-cutover-matrix.json` is the canonical machine-readable source for component maturity and per-wave promotion targets.
 - `.wave/install-state.json` records how the workspace was initialized and which package version is installed.
-- `.wave/project-profile.json` (created by `wave project setup`) records planner defaults such as oversight mode, terminal surface, and deploy-environment memory.
-- `.wave/adhoc/runs/<run-id>/` stores transient ad-hoc request, spec, rendered markdown, and result artifacts.
-- ad-hoc documentation closure always writes `.wave/adhoc/runs/<run-id>/reports/`, but shared-plan deltas still queue the canonical lane shared-plan docs.
+- `.wave/project-profile.json` (created by `wave project setup`) records planner defaults for the implicit default project; explicit projects use `.wave/projects/<projectId>/project-profile.json`.
+- `.wave/adhoc/<projectId>/runs/<run-id>/` stores transient ad-hoc request, spec, rendered markdown, and result artifacts for explicit projects, while the implicit default project keeps the legacy layout.
+- ad-hoc documentation closure writes project-scoped report paths under the run directory, but shared-plan deltas still queue the canonical lane shared-plan docs.
 - ad-hoc task ownership inference only accepts repo-local paths; URLs and other external references are ignored.
 - `wave adhoc promote` promotes the stored ad-hoc spec into `docs/plans/waves/` instead of re-reading the current project profile.
 

package/docs/reference/cli-reference.md

@@ -7,6 +7,8 @@ summary: "Complete syntax reference for all wave CLI commands, flags, and operat
 
 Complete syntax for every `wave` command. All commands use `pnpm exec wave` as the entry point.
 
+When a command targets lane-scoped runtime state, it also accepts `--project <id>`. Omit it to use `defaultProject` from `wave.config.json`.
+
 ## Command Families
 
 - Runtime:
@@ -34,6 +36,7 @@ Closure-role bindings do not have a CLI override surface. When a wave file decla
 
 | Flag | Default | Description |
 |------|---------|-------------|
+| `--project <id>` | config default | Project id |
 | `--lane <name>` | `main` | Lane name |
 | `--start-wave <n>` | `0` | First wave to launch |
 | `--end-wave <n>` | last available | Last wave to launch |
@@ -74,6 +77,7 @@ wave autonomous [options]
 
 | Flag | Default | Description |
 |------|---------|-------------|
+| `--project <id>` | config default | Project id |
 | `--lane <name>` | `main` | Lane name |
 | `--executor <id>` | lane config | `codex`, `claude`, or `opencode` (not `local`) |
 | `--codex-sandbox <mode>` | `danger-full-access` | Codex sandbox mode |
@@ -101,7 +105,7 @@ Read-only view: blocking edges, logical agent state, tasks, dependencies, rerun
 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]
+wave control status --project <id> --lane <lane> --wave <n> [--agent <id>] [--run <id>] [--json]
 ```
 
 The JSON payload now includes:
@@ -118,8 +122,8 @@ Starter repos also include `scripts/wave-status.sh` and `scripts/wave-watch.sh`
 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 telemetry status --project <id> --lane <lane> [--run <id>] [--json]
+wave control telemetry flush  --project <id> --lane <lane> [--run <id>] [--json]
 ```
 
 ### wave control task
@@ -130,7 +134,7 @@ Operator task surface for coordination records.
 
 ```
 wave control task create \
-  --lane <lane> --wave <n> --agent <id> \
+  --project <id> --lane <lane> --wave <n> --agent <id> \
   --kind <kind> --summary "<text>" \
   [--detail "<text>"] [--target <agent-or-capability>] \
   [--priority normal|high] [--blocking true|false] \
@@ -146,20 +150,20 @@ Valid `--kind` values: `request`, `blocker`, `clarification`, `handoff`, `eviden
 **List tasks:**
 
 ```
-wave control task list --lane <lane> --wave <n> [--agent <id>] [--json]
+wave control task list --project <id> --lane <lane> --wave <n> [--agent <id>] [--json]
 ```
 
 **Get a single task:**
 
 ```
-wave control task get --lane <lane> --wave <n> --id <task-id> [--json]
+wave control task get --project <id> --lane <lane> --wave <n> --id <task-id> [--json]
 ```
 
 **Act on a task:**
 
 ```
 wave control task act <action> \
-  --lane <lane> --wave <n> --id <task-id> \
+  --project <id> --lane <lane> --wave <n> --id <task-id> \
   [--detail "<text>"] [--operator <name>] [--json]
 ```
 
@@ -183,7 +187,7 @@ Actions:
 
 ```bash
 pnpm exec wave control task act answer \
-  --lane main --wave 4 --id escalation-clarify-a7-rollout \
+  --project app --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
 ```
@@ -196,7 +200,7 @@ Targeted rerun intent with agent selection, reuse control, and component invalid
 
 ```
 wave control rerun request \
-  --lane <lane> --wave <n> \
+  --project <id> --lane <lane> --wave <n> \
   [--agent <id> ...] \
   [--clear-reuse <id> ...] [--preserve-reuse <id> ...] \
   [--invalidate-component <id> ...] \
@@ -213,13 +217,13 @@ The launcher may also write a rerun request automatically after recoverable fail
 **Get active rerun request:**
 
 ```
-wave control rerun get --lane <lane> --wave <n> [--json]
+wave control rerun get --project <id> --lane <lane> --wave <n> [--json]
 ```
 
 **Clear rerun request:**
 
 ```
-wave control rerun clear --lane <lane> --wave <n>
+wave control rerun clear --project <id> --lane <lane> --wave <n>
 ```
 
 ### wave control proof
@@ -230,7 +234,7 @@ Authoritative proof bundle lifecycle (active → superseded → revoked).
 
 ```
 wave control proof register \
-  --lane <lane> --wave <n> --agent <id> \
+  --project <id> --lane <lane> --wave <n> --agent <id> \
   --artifact <path> [--artifact <path> ...] \
   [--component <id[:level]> ...] \
   [--authoritative] [--satisfy-owned-components] \
@@ -241,14 +245,14 @@ wave control proof register \
 **Get proof bundles:**
 
 ```
-wave control proof get --lane <lane> --wave <n> [--agent <id>] [--id <bundle-id>] [--json]
+wave control proof get --project <id> --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> \
+  --project <id> --lane <lane> --wave <n> --id <old-bundle-id> \
   --agent <id> --artifact <path> [--artifact <path> ...] \
   [same options as register] [--json]
 ```
@@ -257,7 +261,7 @@ wave control proof supersede \
 
 ```
 wave control proof revoke \
-  --lane <lane> --wave <n> --id <bundle-id> \
+  --project <id> --lane <lane> --wave <n> --id <bundle-id> \
   [--operator <name>] [--detail "<text>"] [--json]
 ```
 
@@ -269,7 +273,7 @@ Coordination log access. Legacy surface; prefer `wave control task` for new work
 
 ```
 wave coord post \
-  --lane <lane> --wave <n> --agent <id> \
+  --project <id> --lane <lane> --wave <n> --agent <id> \
   --kind <kind> --summary "<text>" \
   [--detail "<text>"] [--target <agent>] \
   [--priority normal|high] [--depends-on <id>] \
@@ -279,31 +283,31 @@ wave coord post \
 **Show materialized coordination state:**
 
 ```
-wave coord show --lane <lane> --wave <n> [--dry-run] [--json]
+wave coord show --project <id> --lane <lane> --wave <n> [--dry-run] [--json]
 ```
 
 **Render markdown board from JSONL log:**
 
 ```
-wave coord render --lane <lane> --wave <n> [--dry-run]
+wave coord render --project <id> --lane <lane> --wave <n> [--dry-run]
 ```
 
 **Compile shared summary and agent inbox:**
 
 ```
-wave coord inbox --lane <lane> --wave <n> --agent <id> [--dry-run]
+wave coord inbox --project <id> --lane <lane> --wave <n> --agent <id> [--dry-run]
 ```
 
 **Explain why blocked or retrying:**
 
 ```
-wave coord explain --lane <lane> --wave <n> [--agent <id>] [--json]
+wave coord explain --project <id> --lane <lane> --wave <n> [--agent <id>] [--json]
 ```
 
 **Act on a coordination record:**
 
 ```
-wave coord act <operation> --lane <lane> --wave <n> --id <id> [options]
+wave coord act <operation> --project <id> --lane <lane> --wave <n> --id <id> [options]
 ```
 
 | Operation | Extra flags | Effect |
@@ -325,7 +329,7 @@ Human feedback request queue. Final escalation layer after orchestrator-first tr
 
 ```
 wave feedback ask \
-  --lane <lane> --wave <n> --agent <id> \
+  --project <id> --lane <lane> --wave <n> --agent <id> \
   --question "<text>" [--context "<text>"] \
   [--orchestrator-id <id>] [--wait] [--timeout-seconds <n>]
 ```
@@ -345,13 +349,13 @@ When the answered request belongs to a live wave or ad-hoc run, `wave feedback r
 **List feedback requests:**
 
 ```
-wave feedback list [--lane <lane>] [--wave <n>] [--agent <id>] [--pending] [--json]
+wave feedback list [--project <id>] [--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>]
+wave feedback watch [--project <id>] [--lane <lane>] [--wave <n>] [--agent <id>] [--pending] [--refresh-ms <n>]
 ```
 
 **Show a single request:**
@@ -370,7 +374,7 @@ Cross-lane dependency management.
 
 ```
 wave dep post \
-  --owner-lane <lane> --requester-lane <lane> \
+  --owner-project <id> --owner-lane <lane> --requester-project <id> --requester-lane <lane> \
   --owner-wave <n> --requester-wave <n> \
   --agent <id> --summary "<text>" \
   [--detail "<text>"] [--target <agent>] \
@@ -383,19 +387,19 @@ wave dep post \
 **Show dependencies:**
 
 ```
-wave dep show --lane <lane> [--wave <n>] [--json]
+wave dep show --project <id> --lane <lane> [--wave <n>] [--json]
 ```
 
 **Resolve a dependency:**
 
 ```
-wave dep resolve --lane <lane> --id <id> --agent <id> [--detail "<text>"] [--status resolved|closed]
+wave dep resolve --project <id> --lane <lane> --id <id> --agent <id> [--detail "<text>"] [--status resolved|closed]
 ```
 
 **Render dependency snapshot:**
 
 ```
-wave dep render --lane <lane> [--wave <n>] [--json]
+wave dep render --project <id> --lane <lane> [--wave <n>] [--json]
 ```
 
 ## wave benchmark
@@ -417,7 +421,7 @@ 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]
+wave benchmark run [--project <id>] [--lane <lane>] [--case <id>] [--family <id>] [--benchmark <id>] [--arm <id>] [--output-dir <path>] [--json]
 ```
 
 **List external adapters:**
@@ -431,8 +435,8 @@ wave benchmark adapters [--json]
 ```
 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 benchmark external-run --adapter <id> [--project <id>] [--lane <lane>] --manifest <path> [--arm <id>] [--model <id>] [options]
+wave benchmark external-pilots [--project <id>] [--lane <lane>] [--json]
 ```
 
 ## wave retry
@@ -442,13 +446,13 @@ Legacy retry control. Prefer `wave control rerun`.
 **Show active retry override:**
 
 ```
-wave retry show --lane <lane> --wave <n> [--json]
+wave retry show --project <id> --lane <lane> --wave <n> [--json]
 ```
 
 **Apply a retry override:**
 
 ```
-wave retry apply --lane <lane> --wave <n> \
+wave retry apply --project <id> --lane <lane> --wave <n> \
   [--agent <id> ...] \
   [--clear-reuse <id> ...] [--preserve-reuse <id> ...] \
   [--resume-phase <phase>] \
@@ -460,7 +464,7 @@ Requires either `--agent` or `--resume-phase`.
 **Clear retry override:**
 
 ```
-wave retry clear --lane <lane> --wave <n>
+wave retry clear --project <id> --lane <lane> --wave <n>
 ```
 
 ## wave proof
@@ -470,13 +474,13 @@ Legacy proof registration. Prefer `wave control proof`.
 **Show proof registry:**
 
 ```
-wave proof show --lane <lane> --wave <n> [--agent <id>] [--json]
+wave proof show --project <id> --lane <lane> --wave <n> [--agent <id>] [--json]
 ```
 
 **Register proof:**
 
 ```
-wave proof register --lane <lane> --wave <n> --agent <id> \
+wave proof register --project <id> --lane <lane> --wave <n> --agent <id> \
   --artifact <path> [--artifact <path> ...] \
   [--component <id[:level]> ...] \
   [--authoritative] [--satisfy-owned-components] \
@@ -497,8 +501,8 @@ wave local --prompt <path> [--log <path>] [--status <path>]
 Live dashboard viewer.
 
 ```
-wave dashboard --dashboard-file <path> [--lane <lane>] [--message-board <path>] [--watch] [--refresh-ms <n>]
-wave dashboard --lane <lane> --attach current|global
+wave dashboard --dashboard-file <path> [--project <id>] [--lane <lane>] [--message-board <path>] [--watch] [--refresh-ms <n>]
+wave dashboard --project <id> --lane <lane> --attach current|global
 ```
 
 ## Workspace Commands
@@ -538,17 +542,17 @@ wave doctor [--json]
 **Setup project profile:**
 
 ```
-wave project setup
-wave project show [--json]
+wave project setup [--project <id>] [--json]
+wave project show [--project <id>] [--json]
 ```
 
 **Draft waves:**
 
 ```
-wave draft --wave <n> [--template implementation|qa|infra|release]
-wave draft --agentic --task "<description>" --from-wave <n>
+wave draft --wave <n> [--project <id>] [--lane <lane>] [--template implementation|qa|infra|release]
+wave draft --agentic --task "<description>" --from-wave <n> [--project <id>] [--lane <lane>]
 wave draft --show-run <run-id>
-wave draft --apply-run <run-id>
+wave draft --apply-run <run-id> [--project <id>]
 ```
 
 Interactive draft currently offers worker role kinds:
@@ -561,25 +565,25 @@ Interactive draft currently offers worker role kinds:
 - `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.
+Agentic planner payloads also accept `workerAgents[].roleKind = "design"`. The shipped `0.9.0` 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 plan --task "<description>" [--project <id>] [--lane <lane>]
+wave adhoc run --task "<description>" [--project <id>] [--lane <lane>] [--yes] [--executor <id>]
+wave adhoc list [--project <id>] [--lane <lane>] [--json]
 wave adhoc show --run <id> [--json]
-wave adhoc promote --run <id> --wave <n>
+wave adhoc promote --run <id> [--project <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.
+Most coordination commands accept `--project` plus `--lane` (default lane: `main`) and `--wave` (required). For ad-hoc runs, use `--run <id>` which resolves the matching project and lane and defaults wave to 0.
 
 ### JSON output
 
@@ -595,6 +599,6 @@ Flags like `--agent`, `--artifact`, `--component`, `--target`, and `--depends-on
 
 ```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
+wave control rerun request --project app --lane main --wave 0 --agent A2 --agent A7
+wave control rerun request --project app --lane main --wave 0 --agent A2,A7
 ```

package/docs/reference/coordination-and-closure.md

@@ -134,7 +134,7 @@ Practical rule:
 
 That means a targeted helper request only blocks while it remains open *and* still has blocking severity in coordination state.
 
-For the practical `0.8.9` recommendation on when to keep records blocking versus when to downgrade them to `soft`, `stale`, or `advisory`, see [../guides/recommendations-0.8.9.md](../guides/recommendations-0.8.9.md).
+For the practical `0.9.0` recommendation on when to keep records blocking versus when to downgrade them to `soft`, `stale`, or `advisory`, see [../guides/recommendations-0.9.0.md](../guides/recommendations-0.9.0.md).
 
 This page is documenting runtime semantics first. The important contract is that closure follows the durable coordination state, not that a particular human or agent used one exact command path to mutate it.
 

package/docs/reference/npmjs-trusted-publishing.md

@@ -2,7 +2,7 @@
 
 This repo now includes a dedicated npmjs publish workflow at [publish-npm.yml](../../.github/workflows/publish-npm.yml).
 
-The current `0.8.9` release procedure publishes through a repository Actions secret named `NPM_TOKEN`.
+The current `0.9.0` release procedure publishes through a repository Actions secret named `NPM_TOKEN`.
 
 ## What This Repo Already Does
 
@@ -48,6 +48,6 @@ If this repo later needs private npm dependencies during CI, consider a separate
 2. Confirm `NPM_TOKEN` exists in the GitHub repo secrets.
 3. Confirm the package version has been bumped and committed.
 4. Confirm `README.md`, `CHANGELOG.md`, `releases/manifest.json`, and `docs/plans/migration.md` all describe the same release surface.
-5. Push the release commit and release tag, for example `v0.8.9`.
+5. Push the release commit and release tag, for example `v0.9.0`.
 6. Verify both `publish-npm.yml` and `publish-package.yml` start from the tag push.
 7. Verify the npmjs publish completes successfully for the tagged source.