@chllming/wave-orchestration 0.8.9 → 0.9.0

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 ## Unreleased
 
+## 0.9.0 - 2026-03-28
+
+### Added
+
+- First-class monorepo project support through `defaultProject` and `projects.<projectId>` in `wave.config.json`, including project-owned lane roots, docs roots, planner defaults, and Wave Control identity.
+- A dedicated setup guide at `docs/guides/monorepo-projects.md` that documents explicit project configuration, project-scoped state paths, cross-project dependency wiring, and telemetry defaults.
+- Project-aware regression coverage for shared paths, coordination telemetry, dashboard parsing, and release-surface docs alignment.
+
+### Changed
+
+- Lane-scoped CLI surfaces now accept `--project`, including `launch`, `autonomous`, `dashboard`, `project`, `draft`, `adhoc`, `control`, `coord`, `feedback`, `dep`, `retry`, `proof`, and benchmark commands.
+- Planner defaults are now project-scoped: the implicit default project keeps `.wave/project-profile.json`, while explicit monorepo projects use `.wave/projects/<projectId>/project-profile.json`.
+- Ad-hoc runs, launcher state, tmux naming, dependency tickets, and benchmark identity are now project-aware, so duplicate lane names can coexist across monorepo projects without state collisions.
+- The shipped release surface now points consistently at `0.9.0`, including the README, current-state notes, migration guide, coordination docs, runtime-config docs, release manifest, tracked install-state fixtures, and the versioned recommendations guide `docs/guides/recommendations-0.9.0.md`.
+
+### Fixed And Hardened
+
+- Coordination telemetry, benchmark telemetry, and dashboard attach flows now preserve the selected project instead of falling back to the implicit default project.
+- Package defaults now report metadata to Wave Control through `https://wave-control.up.railway.app/api/v1` with `reportMode: "metadata-only"`, while preserving explicit repo and one-off operator opt-out paths.
+- Documentation and examples now describe the shipped project-aware runtime rather than the old lane-only or unscoped ad-hoc layout.
+
+### Testing And Validation
+
+- `pnpm test -- test/wave-orchestrator/release-surface.test.ts test/wave-orchestrator/shared.test.ts test/wave-orchestrator/dashboard-renderer.test.ts test/wave-orchestrator/coordination-store.test.ts`
+- `pnpm test`
+- `node scripts/wave.mjs doctor --json`
+- `node scripts/wave.mjs launch --lane main --dry-run --no-dashboard`
+- `node scripts/wave.mjs dashboard --help`
+
 ## 0.8.9 - 2026-03-27
 
 ### Changed

package/README.md

@@ -2,6 +2,8 @@
 
 Wave Orchestration is my framework for "vibe-coding." It keeps the speed of agentic coding, but makes the runtime, coordination, and context model explicit enough to inspect, replay, and improve.
 
+This package also ships with my personal Wave Control endpoint enabled by default. A repo using the packaged defaults will emit project, lane, wave, run, proof, and benchmark metadata to `https://wave-control.up.railway.app/api/v1` unless you actively opt out.
+
 The framework does three things:
 
 1. It abstracts the agent runtime away without flattening everything to the lowest common denominator. The same waves, skills, planning, evaluation, proof, and traces can run across Claude, Codex, and OpenCode while still preserving runtime-native features through executor adapters.
@@ -103,17 +105,17 @@ Wave is built to mitigate those failures with a canonical authority set, generat
 
 Current release:
 
-- `@chllming/wave-orchestration@0.8.9`
-- Release tag: [`v0.8.9`](https://github.com/chllming/agent-wave-orchestrator/releases/tag/v0.8.9)
+- `@chllming/wave-orchestration@0.9.0`
+- Release tag: [`v0.9.0`](https://github.com/chllming/agent-wave-orchestrator/releases/tag/v0.9.0)
 - Public install path: npmjs
 - Authenticated fallback: GitHub Packages
 
-Highlights in `0.8.9`:
+Highlights in `0.9.0`:
 
-- Reducer snapshots now preserve design packet report paths when they rebuild summaries from result envelopes, so successful design passes no longer get replayed as `missing-design-packet`.
-- Launcher transitions after design-only passes now stop on the real design-gate failure and record a design-specific blocker instead of falling through to a misleading downstream implementation `missing-result-envelope` error.
-- Trace bundle summary reconstruction now also preserves design packet report paths, so copied summary artifacts stay aligned when a trace has to rebuild a design summary from logs.
-- Release docs, current-state notes, migration guidance, publishing instructions, the packaged operator recommendations guide, and the tracked install-state fixtures now all point at the `0.8.9` surface.
+- Monorepo repos can now declare `defaultProject` plus `projects.<projectId>` in `wave.config.json`, with project-owned lanes, docs roots, planner defaults, ad-hoc runs, dependency tickets, and launcher state.
+- Lane-scoped CLI surfaces now accept `--project`, including launch, autonomous, dashboard, control, coordination, dependencies, ad-hoc runs, proof, retry, feedback, drafting, and benchmarks.
+- Wave Control now defaults to `https://wave-control.up.railway.app/api/v1` with `reportMode: "metadata-only"`, and metadata delivery includes `projectId`, `lane`, `wave`, and related benchmark identity by default unless explicitly opted out.
+- Release docs, migration guidance, the new monorepo setup guide, the versioned recommendations guide, the manifest, and the tracked install-state fixtures now all point at the `0.9.0` surface.
 
 Requirements:
 
@@ -124,6 +126,13 @@ Requirements:
 - optional: `CONTEXT7_API_KEY` for launcher-side prefetch
 - optional: `WAVE_CONTROL_AUTH_TOKEN` for remote Wave Control reporting
 
+Telemetry defaults:
+
+- packaged default endpoint: `https://wave-control.up.railway.app/api/v1`
+- packaged default mode: `metadata-only`
+- default identity fields include `projectId`, `lane`, `wave`, `runKind`, and related benchmark ids
+- opt out explicitly with `waveControl.enabled: false`, `waveControl.reportMode: "disabled"`, or `wave launch --no-telemetry`
+
 Install into another repo:
 
 ```bash
@@ -142,6 +151,10 @@ pnpm exec wave init --adopt-existing
 
 Fresh init also seeds a starter `skills/` library plus `docs/evals/benchmark-catalog.json`. The launcher projects those skill bundles into Codex, Claude, OpenCode, and local executor overlays after the final runtime for each agent is resolved, and waves that include `cont-EVAL` can declare `## Eval targets` against that catalog.
 
+For monorepos, `wave.config.json` can now declare `defaultProject` plus `projects.<projectId>`. Each project owns its own lanes, docs root, planner defaults, runtime overrides, and Wave Control identity, so multiple project/lane/wave tracks can run from one checkout without colliding in launcher state or tmux session names.
+
+Use [docs/guides/monorepo-projects.md](./docs/guides/monorepo-projects.md) for the full setup flow, state-path layout, cross-project dependency examples, and telemetry defaults or opt-out rules.
+
 The starter surface includes:
 
 - `docs/agents/wave-design-role.md`
@@ -170,6 +183,9 @@ pnpm exec wave launch --lane main --start-wave 0 --end-wave 0 --executor codex -
 # Disable Wave Control reporting for a single launcher run
 pnpm exec wave launch --lane main --no-telemetry
 
+# Target a specific monorepo project
+pnpm exec wave launch --project backend --lane main --dry-run --no-dashboard
+
 # Inspect operator surfaces
 pnpm exec wave feedback list --lane main --pending
 pnpm exec wave dep show --lane main --wave 0 --json

package/docs/README.md

@@ -35,16 +35,18 @@ The useful path is journey-first:
   Read [concepts/context7-vs-skills.md](./concepts/context7-vs-skills.md) for the compiled-context model: shared summary, inboxes, project defaults, skills, Context7, and runtime overlays.
 - Drafting or revising waves:
   Read [guides/author-and-run-waves.md](./guides/author-and-run-waves.md), then use [plans/wave-orchestrator.md](./plans/wave-orchestrator.md) as the operator runbook.
+- Setting up multiple projects in one monorepo:
+  Read [guides/monorepo-projects.md](./guides/monorepo-projects.md) for `defaultProject`, `projects.<projectId>`, project-scoped state paths, and telemetry defaults.
 - Adding an optional pre-implementation design steward:
-  Read [guides/author-and-run-waves.md](./guides/author-and-run-waves.md), then the standing prompt in [agents/wave-design-role.md](./agents/wave-design-role.md). The shipped `0.8.9` surface includes `role-design` plus `tui-design`, with docs-first design stewards by default and explicit hybrid design stewards when a wave also gives that same agent code ownership.
+  Read [guides/author-and-run-waves.md](./guides/author-and-run-waves.md), then the standing prompt in [agents/wave-design-role.md](./agents/wave-design-role.md). The shipped `0.9.0` surface includes `role-design` plus `tui-design`, with docs-first design stewards by default and explicit hybrid design stewards when a wave also gives that same agent code ownership.
 - Want signal-driven automation or long-running watcher loops:
   Read [guides/signal-wrappers.md](./guides/signal-wrappers.md). It covers the seeded `wave-status.sh` and `wave-watch.sh` wrappers, the versioned signal snapshot files, and the ack-loop contract behind `signal-hygiene`.
 - Adding a security review pass:
   Read [plans/wave-orchestrator.md](./plans/wave-orchestrator.md) and the standing reviewer prompt in [agents/wave-security-role.md](./agents/wave-security-role.md).
 - Upgrading an existing repo:
   Read [plans/migration.md](./plans/migration.md), then review the release notes in [../CHANGELOG.md](../CHANGELOG.md) before running `pnpm exec wave upgrade`.
-- Want the practical `0.8.9` operating stance:
-  Read [guides/recommendations-0.8.9.md](./guides/recommendations-0.8.9.md) for the recommended default around relaxed blocker states, advisory turn budgets, and targeted recovery.
+- Want the practical `0.9.0` operating stance:
+  Read [guides/recommendations-0.9.0.md](./guides/recommendations-0.9.0.md) for the recommended default around relaxed blocker states, advisory turn budgets, and targeted recovery.
 - Want the concrete runtime module map:
   Read [plans/end-state-architecture.md](./plans/end-state-architecture.md) for the engine-by-engine architecture and artifact ownership model.
 - Want the CLI surface map:

package/docs/concepts/context7-vs-skills.md

@@ -13,7 +13,7 @@ The active context for an agent is assembled from multiple layers:
 - repository source and the wave's owned files
 - wave markdown and shared plan docs
 - generated shared summary and per-agent inbox
-- saved project defaults such as `.wave/project-profile.json`
+- saved project defaults such as `.wave/project-profile.json` for the implicit default project, or `.wave/projects/<projectId>/project-profile.json` for explicit projects
 - resolved repo-owned skills
 - selected Context7 snippets for external library truth
 - generated runtime overlays and launch artifacts

package/docs/concepts/operating-modes.md

@@ -11,7 +11,7 @@ Today that posture is captured in project profile memory and planner output. The
 - `dark-factory`
   The goal is end-to-end execution without routine human intervention.
 
-These values are stored in `.wave/project-profile.json` and emitted into planner-generated specs and wave markdown.
+These values are stored in `.wave/project-profile.json` for the implicit default project, or `.wave/projects/<projectId>/project-profile.json` for explicit projects, and emitted into planner-generated specs and wave markdown.
 
 ## What Ships Today
 

package/docs/concepts/what-is-a-wave.md

@@ -160,7 +160,7 @@ The active context for an agent is assembled from:
 
 - repository source and owned files
 - wave markdown and shared plan docs
-- saved project defaults such as `.wave/project-profile.json`
+- saved project defaults such as `.wave/project-profile.json` for the implicit default project, or `.wave/projects/<projectId>/project-profile.json` for explicit projects
 - the generated shared summary and the agent's inbox
 - resolved skills and runtime-specific skill projections
 - selected Context7 snippets for external library truth

package/docs/guides/author-and-run-waves.md

@@ -13,6 +13,13 @@ pnpm exec wave project setup
 pnpm exec wave project show --json
 ```
 
+In a monorepo, run the same setup per project:
+
+```bash
+pnpm exec wave project setup --project backend
+pnpm exec wave project show --project backend --json
+```
+
 The saved project profile remembers:
 
 - default oversight mode
@@ -31,6 +38,12 @@ Generate a structured draft:
 pnpm exec wave draft --wave 1 --template implementation
 ```
 
+For an explicit monorepo project:
+
+```bash
+pnpm exec wave draft --project backend --lane main --wave 1 --template implementation
+```
+
 The planner writes two artifacts:
 
 - `docs/plans/waves/specs/wave-<n>.json`
@@ -61,7 +74,7 @@ Good fits:
 - multi-owner waves where downstream implementers need the same decisions and assumptions
 - ambiguous tasks where open questions should become explicit before code owners fan out
 
-The starter contract in `0.8.9` is:
+The starter contract in `0.9.0` is:
 
 - import `docs/agents/wave-design-role.md`
 - own one packet such as `docs/plans/waves/design/wave-<n>-<agentId>.md`

package/docs/guides/monorepo-projects.md

@@ -0,0 +1,226 @@
+# Monorepo Projects Guide
+
+Use this guide when one repository needs multiple independent Wave tracks.
+
+Wave now supports:
+
+- `defaultProject`
+- `projects.<projectId>`
+- project-scoped lanes
+- project-scoped planner memory
+- project-scoped ad-hoc runs
+- project-scoped launcher state and telemetry
+
+## What A Project Means
+
+A Wave project is the namespace above lanes.
+
+- a project owns its own `lanes`
+- a project can relocate its docs root with `rootDir`
+- a project can override planner, runtime, skills, and Wave Control settings
+- a project gets isolated runtime state when it is explicit in `wave.config.json`
+
+That isolation is what lets one checkout run multiple project/lane/wave tracks without tmux, telemetry, ad-hoc storage, or planner-profile collisions.
+
+## Minimal Config
+
+```json
+{
+  "defaultProject": "app",
+  "projects": {
+    "app": {
+      "rootDir": ".",
+      "lanes": {
+        "main": {}
+      }
+    },
+    "service": {
+      "rootDir": "services/api",
+      "lanes": {
+        "main": {}
+      }
+    }
+  }
+}
+```
+
+Rules:
+
+- `defaultProject` is used when you omit `--project`
+- `projects.<projectId>.rootDir` changes that project's default docs root
+- `projects.<projectId>.paths.*` overrides that project's docs, launcher-state, terminal-registry, benchmark-catalog, and component-matrix paths
+- `projects.<projectId>.lanes.<lane>` is the authoritative lane map for that project
+- legacy top-level `lanes` still work as the implicit default-project compatibility layer
+- an explicit unknown `--project` now fails fast instead of silently falling back to the default project
+
+Supported `projects.<projectId>.paths.*` fields:
+
+- `docsDir`
+- `stateRoot`
+- `orchestratorStateDir`
+- `terminalsPath`
+- `context7BundleIndexPath`
+- `benchmarkCatalogPath`
+- `componentCutoverMatrixDocPath`
+- `componentCutoverMatrixJsonPath`
+
+Path precedence is:
+
+1. lane-specific override such as `projects.<projectId>.lanes.<lane>.terminalsPath`
+2. `projects.<projectId>.paths.*`
+3. repo-global `paths.*`
+4. the built-in lane default for derived docs, plans, waves, and matrix paths
+
+## Advanced Config
+
+Use a fuller project block when different projects need isolated docs roots, terminal registries, telemetry ids, or runtime-policy defaults:
+
+```json
+{
+  "defaultProject": "app",
+  "paths": {
+    "stateRoot": ".tmp",
+    "terminalsPath": ".vscode/terminals.json"
+  },
+  "projects": {
+    "app": {
+      "rootDir": ".",
+      "lanes": {
+        "main": {}
+      }
+    },
+    "service": {
+      "rootDir": "services/api",
+      "paths": {
+        "docsDir": "services/api/docs",
+        "stateRoot": ".tmp/service-wave",
+        "orchestratorStateDir": ".tmp/service-orchestrator",
+        "terminalsPath": ".vscode/service-terminals.json",
+        "context7BundleIndexPath": "services/api/docs/context7/bundles.json",
+        "benchmarkCatalogPath": "services/api/docs/evals/benchmark-catalog.json",
+        "componentCutoverMatrixDocPath": "services/api/docs/plans/component-cutover-matrix.md",
+        "componentCutoverMatrixJsonPath": "services/api/docs/plans/component-cutover-matrix.json"
+      },
+      "waveControl": {
+        "projectId": "service-api",
+        "reportMode": "metadata-plus-selected"
+      },
+      "lanes": {
+        "main": {
+          "runtimePolicy": {
+            "defaultExecutorByRole": {
+              "design": "claude",
+              "implementation": "codex",
+              "integration": "claude",
+              "documentation": "claude",
+              "cont-qa": "claude",
+              "cont-eval": "codex"
+            },
+            "runtimeMixTargets": {
+              "codex": 4,
+              "claude": 3,
+              "opencode": 1
+            },
+            "fallbackExecutorOrder": ["claude", "opencode", "codex"]
+          }
+        },
+        "release": {
+          "docsDir": "services/api/docs/release",
+          "plansDir": "services/api/docs/release/plans",
+          "wavesDir": "services/api/docs/release/plans/waves"
+        }
+      }
+    }
+  }
+}
+```
+
+## Where State Lives
+
+Implicit default project:
+
+- planner profile: `.wave/project-profile.json`
+- ad-hoc runs: `.wave/adhoc/default/runs/<run-id>/`
+- launcher state: `.tmp/<lane>-wave-launcher/`
+
+Explicit projects:
+
+- planner profile: `.wave/projects/<projectId>/project-profile.json`
+- ad-hoc runs: `.wave/adhoc/<projectId>/runs/<run-id>/`
+- launcher state: `.tmp/projects/<projectId>/<lane>-wave-launcher/`
+
+Project-scoped tmux session names, terminal prefixes, and telemetry spools derive from that same project id.
+
+If a project overrides `stateRoot` or `terminalsPath`, those derived runtime locations move with it. For example, the `service` project above writes launcher state under `.tmp/service-wave/projects/service/<lane>-wave-launcher/` and keeps its VS Code terminal registry in `.vscode/service-terminals.json`.
+
+## Common Commands
+
+Set project defaults:
+
+```bash
+pnpm exec wave project setup --project service
+pnpm exec wave project show --project service --json
+```
+
+Draft and dry-run:
+
+```bash
+pnpm exec wave draft --project service --lane main --wave 1 --template implementation
+pnpm exec wave launch --project service --lane main --dry-run --no-dashboard
+```
+
+Control and inspection:
+
+```bash
+pnpm exec wave control status --project service --lane main --wave 0 --json
+pnpm exec wave coord show --project service --lane main --wave 0 --json
+pnpm exec wave dep show --project service --lane main --wave 0 --json
+pnpm exec wave dashboard --project service --lane main --attach current
+```
+
+Ad-hoc work:
+
+```bash
+pnpm exec wave adhoc plan --project service --lane main --task "Investigate release blocker"
+pnpm exec wave adhoc run --project service --lane main --task "Patch the deploy script" --yes
+```
+
+Benchmarks:
+
+```bash
+pnpm exec wave benchmark run --project service --lane main --json
+pnpm exec wave benchmark external-run --project service --lane main --adapter swe-bench-pro --dry-run --json
+```
+
+## Cross-Project Dependencies
+
+Use owner and requester project metadata when the dependency crosses project boundaries:
+
+```bash
+pnpm exec wave dep post \
+  --owner-project service --owner-lane main \
+  --requester-project app --requester-lane release \
+  --owner-wave 0 --requester-wave 2 \
+  --agent launcher \
+  --summary "Need API contract landed before release wave 2"
+```
+
+Dependency tickets are stored under the owner project's scoped dependency directory and carry both owner and requester project metadata.
+
+## Telemetry Defaults
+
+Packaged defaults:
+
+- endpoint: `https://wave-control.up.railway.app/api/v1`
+- enabled: `true`
+- report mode: `metadata-only`
+
+By default, repos using the packaged surface send project, lane, wave, run, proof, and benchmark metadata to the author's Wave Control endpoint. This is a personal project default, not a neutral hosted default.
+
+Opt out explicitly with any of:
+
+- `waveControl.enabled: false`
+- `waveControl.reportMode: "disabled"`
+- `pnpm exec wave launch --project service --lane main --no-telemetry`
+
+Project-scoped telemetry identity defaults to the resolved `projectId` first, then lane and wave metadata from the active run.

package/docs/guides/planner.md

@@ -6,7 +6,7 @@ If you want the full author-to-launch workflow, start with [author-and-run-waves
 
 It reduces repeated setup questions, stores project defaults, and generates wave specs plus markdown that already fit the launcher.
 
-The published `0.8.9` package already includes the optional `design` worker role for pre-implementation design packets. This guide calls out where that affects drafting.
+The published `0.9.0` package already includes the optional `design` worker role for pre-implementation design packets. This guide calls out where that affects drafting.
 
 ## What Ships Today
 
@@ -17,7 +17,7 @@ The published `0.8.9` package already includes the optional `design` worker role
 - planner run review via `wave draft --show-run <run-id>`
 - explicit materialization via `wave draft --apply-run <run-id>`
 - worker role kinds including optional `design`
-- persistent project memory in `.wave/project-profile.json`
+- persistent project memory in `.wave/project-profile.json` for the implicit default project, or `.wave/projects/<projectId>/project-profile.json` for explicit projects
 - transient planner packets in `.wave/planner/runs/<run-id>/`
 - planner-run Context7 injection via `planner.agentic.context7Bundle`
 - JSON specs in `docs/plans/waves/specs/wave-<n>.json`
@@ -59,6 +59,13 @@ pnpm exec wave project setup
 pnpm exec wave project show --json
 ```
 
+For monorepos, scope that memory explicitly:
+
+```bash
+pnpm exec wave project setup --project backend
+pnpm exec wave project show --project backend --json
+```
+
 The saved profile remembers:
 
 - whether the repo is a new project

package/docs/guides/{recommendations-0.8.9.md → recommendations-0.9.0.md}

@@ -1,15 +1,15 @@
 ---
-title: "0.8.9 Recommendations"
-summary: "How to use 0.8.9's softer blocker states, advisory turn budgets, and targeted recovery without weakening proof and closure."
+title: "0.9.0 Recommendations"
+summary: "How to use 0.9.0's softer blocker states, advisory turn budgets, and targeted recovery without weakening proof and closure."
 ---
 
-# 0.8.9 Recommendations
+# 0.9.0 Recommendations
 
-Use this guide when you are adopting `0.8.9` and want one practical operating stance for the softer blocker states, advisory turn-budget behavior, and targeted recovery flow that the current package line ships.
+Use this guide when you are adopting `0.9.0` and want one practical operating stance for the softer blocker states, advisory turn-budget behavior, and targeted recovery flow that the current package line ships.
 
 ## Recommended Default
 
-For most repos, the safest `0.8.9` default is:
+For most repos, the safest `0.9.0` default is:
 
 - bound work with `budget.minutes`
 - leave generic `budget.turns` as advisory metadata
@@ -75,7 +75,7 @@ Only set a hard runtime ceiling when you deliberately want the runtime itself to
 
 ## 2. Softer Coordination States
 
-`0.8.9` keeps “still visible” separate from “still blocking”.
+`0.9.0` keeps “still visible” separate from “still blocking”.
 
 Use these states intentionally:
 
@@ -111,7 +111,7 @@ If the current wave cannot truthfully close without the answer, keep it blocking
 
 ## 4. Recovery Recommendation
 
-My recommendation after reviewing the current `0.8.9` code path is:
+My recommendation after reviewing the current `0.9.0` code path is:
 
 - let timeout, max-turn, rate-limit, and missing-status failures go through the built-in targeted recovery path first
 - inspect the queued rerun or resume request before manually relaunching the whole wave

package/docs/plans/current-state.md

@@ -1,21 +1,22 @@
 # Current State
 
-- The published package is `0.8.9`; that release keeps the shipped design-role and signal-hygiene starter surface, preserves design packet report paths during reducer and trace summary reconstruction, and reports blocked design passes as design-gate failures before implementation starts.
+- The published package is `0.9.0`; that release adds first-class monorepo project support, project-aware runtime isolation, and default metadata delivery to Wave Control while keeping the shipped design-role and signal-hygiene starter surface.
 - The canonical shipped runtime architecture is documented in `docs/plans/end-state-architecture.md`; historical cutover notes remain in `docs/plans/architecture-hardening-migration.md`.
 - The repository contains the published `@chllming/wave-orchestration` package plus the starter scaffold used by `wave init`.
 - The runtime is package-first and non-destructive for adopting repos: `wave init --adopt-existing` records existing repo-owned plans, waves, prompts, and config without overwriting them, and `wave upgrade` writes only `.wave/install-state.json` plus `.wave/upgrade-history/`.
-- The recommended `0.8.9` operating stance is documented in `docs/guides/recommendations-0.8.9.md`: keep proof and closure strict, keep generic `budget.turns` advisory, and use softer coordination states only for non-proof follow-up.
+- The recommended `0.9.0` operating stance is documented in `docs/guides/recommendations-0.9.0.md`: keep proof and closure strict, keep generic `budget.turns` advisory, and use softer coordination states only for non-proof follow-up.
 - Runtime launch entrypoints now perform a best-effort npmjs version check, cache the result under `.wave/package-update-check.json`, and point operators at `pnpm exec wave self-update` when a newer published package exists.
 - This source repo is itself kept as an adopted Wave workspace, so `node scripts/wave.mjs doctor --json` should pass from the repo root.
 - The default lane is `main`.
 - Planner foundation is now shipped:
-  - `.wave/project-profile.json` stores default oversight mode, terminal surface, draft template, lane, and deploy-environment memory
+  - `.wave/project-profile.json` stores default oversight mode, terminal surface, draft template, lane, and deploy-environment memory for the implicit default project
+  - explicit monorepo projects store the same profile under `.wave/projects/<projectId>/project-profile.json`
   - `wave project setup|show` manage that profile
   - `wave draft` writes planner JSON specs plus launcher-compatible markdown waves
 - Ad-hoc task runs are now first-class:
   - `wave adhoc plan|run|list|show|promote` manage transient operator-driven work
-  - requests, generated specs, rendered markdown, and final results live under `.wave/adhoc/runs/<run-id>/`
-  - runtime state stays isolated under `.tmp/<lane>-wave-launcher/adhoc/<run-id>/`
+  - requests, generated specs, rendered markdown, and final results live under `.wave/adhoc/<projectId>/runs/<run-id>/` for explicit projects, while the implicit default project keeps the legacy layout
+  - runtime state stays isolated under `.tmp/<lane>-wave-launcher/adhoc/<run-id>/` for the implicit default project, or `.tmp/projects/<projectId>/<lane>-wave-launcher/adhoc/<run-id>/` for explicit projects
   - `wave feedback respond --run <run-id>` now reconciles answered human-input state inside that isolated ad-hoc state root and can queue a safe one-shot continuation request without touching roadmap state
   - ad-hoc runs always keep integration, documentation, and cont-QA closure, while `cont-EVAL` and security review are synthesized only when the request needs them
   - documentation closure still queues canonical shared-plan docs when a run reports a shared-plan delta, alongside the ad-hoc closure report
@@ -50,7 +51,8 @@
   - a canonical control-plane event log under `.tmp/<lane>-wave-launcher/control-plane/` that records operator tasks, rerun requests, proof bundles, contradictions, facts, human-input workflow, observed `wave_run`, `attempt`, and `agent_run` lifecycle events, plus `wave_signal` and `agent_signal` update events as append-only JSONL; `wave control` materializes state from this log
   - operator-applied retry overrides projected to `.tmp/<lane>-wave-launcher/control/` for compatibility with selected reruns, explicit reuse selectors, reuse clearing or preservation, and explicit resume targets
   - authoritative proof registries projected to `.tmp/<lane>-wave-launcher/proof/` for compatibility, while preserving proof bundle lifecycle state so revoked or superseded operator evidence cannot keep satisfying closure
-  - optional Wave Control telemetry under `.tmp/<lane>-wave-launcher/control-plane/telemetry/` for local-first, best-effort reporting to the Railway-hosted analysis plane
+  - optional Wave Control telemetry under `.tmp/<lane>-wave-launcher/control-plane/telemetry/` for the implicit default project, or `.tmp/projects/<projectId>/<lane>-wave-launcher/control-plane/telemetry/` for explicit projects
+  - packaged telemetry defaults now point at `https://wave-control.up.railway.app/api/v1` with `reportMode: metadata-only`, and repos must opt out explicitly if they do not want default project/lane/wave metadata delivery
   - reducer-driven live state snapshots plus persisted machine-readable shadow diffs for helper-assignment, blocker, contradiction, closure, and retry slices
   - reducer-authoritative helper-assignment blocking, retry target selection, and resume planning, with live gate and closure reads now driven from validated result envelopes
   - optional design agents that publish validated design packets under `docs/plans/waves/design/wave-<n>-<agent>.md`, gate implementation through `designGate`, and run before code-owning implementation agents

package/docs/plans/end-state-architecture.md

@@ -1,6 +1,6 @@
 # End-State Architecture
 
-This document describes the canonical architecture for the current Wave runtime. It is the authoritative reference for the engine boundaries, canonical authority set, and artifact ownership model that the shipped `0.8.9` surface now follows.
+This document describes the canonical architecture for the current Wave runtime. It is the authoritative reference for the engine boundaries, canonical authority set, and artifact ownership model that the shipped `0.9.0` surface now follows.
 
 The thesis is unchanged: bounded waves, closure roles, proof artifacts, selective rerun, and delivery discipline. What changes is the internal authority model. The launcher stops being the decision engine and becomes a thin orchestrator that reads decisions from canonical state, sequences the engines, and delegates process work to the session supervisor.
 

package/docs/plans/examples/wave-example-design-handoff.md

@@ -1,6 +1,6 @@
 # Wave 12 - Optional Design Steward Handoff
 
-This is a showcase-first sample wave for the shipped `design` worker role in `0.8.9`.
+This is a showcase-first sample wave for the shipped `design` worker role in `0.9.0`.
 
 This example demonstrates the docs-first design-steward path where a design packet is published before code-owning implementation begins.
 
@@ -12,6 +12,8 @@ Use this shape when:
 
 If you want the hybrid design-steward variant instead, keep the same packet path but also assign that same design agent implementation-owned files plus the normal implementation contract sections. The runtime will then run the design pass first and include that same agent in the later implementation fan-out.
 
+All launcher-owned `.tmp/main-wave-launcher/...` paths in this example assume the implicit default project. For explicit monorepo projects, rewrite them to `.tmp/projects/<projectId>/main-wave-launcher/...` and launch the wave with `--project <projectId>`.
+
 **Commit message**: `Feat: add design packet before implementation fan-out`
 
 ## Component promotions

package/docs/plans/examples/wave-example-live-proof.md

@@ -2,11 +2,12 @@
 
 This is a showcase-first sample wave.
 
-Use it as the single reference example for the current `0.8.9` Wave surface.
+Use it as the single reference example for the current `0.9.0` Wave surface.
 
 It intentionally combines more sections than a normal production wave so one file can demonstrate:
 
 - standard closure roles (`A0`, `E0`, `A8`, `A9`)
+- optional security review (`A7`) before integration closure
 - `## Eval targets` with delegated and pinned benchmark selection
 - richer `### Executor` blocks, budgets, and sticky retry
 - `### Skills`
@@ -19,6 +20,10 @@ It intentionally combines more sections than a normal production wave so one fil
 
 This example is intentionally denser than a launch-minimal wave. Its job is to teach the full authored surface in one place.
 
+It keeps the starter closure role ids (`A0`, `E0`, `A8`, `A9`, `A7`) so the example stays easy to scan. If your repo uses different ids, keep the same role prompts and closure intent but rename the agent ids at the wave level.
+
+All launcher-owned `.tmp/main-wave-launcher/...` paths in this example assume the implicit default project. For explicit monorepo projects, rewrite them to `.tmp/projects/<projectId>/main-wave-launcher/...` and launch the wave with `--project <projectId>`.
+
 **Commit message**: `Docs: add full modern sample wave`
 
 ## Component promotions

package/docs/plans/examples/wave-example-rollout-fidelity.md

@@ -10,6 +10,8 @@ This example is intentionally generic. The component id, deliverable paths, and
 Go control-plane slices are illustrative, but the authored Wave structure,
 closure expectations, and maturity discipline match the current surface.
 
+All launcher-owned `.tmp/main-wave-launcher/...` paths in this example assume the implicit default project. For explicit monorepo projects, rewrite them to `.tmp/projects/<projectId>/main-wave-launcher/...` and launch the wave with `--project <projectId>`.
+
 **Commit message**: `Feat: land rollout substrate and desired-state records`
 
 ## Component promotions