@chllming/wave-orchestration 0.8.8 → 0.9.0

package/docs/reference/runtime-config/README.md

@@ -5,6 +5,7 @@ This directory is the canonical reference for executor configuration in the pack
 Use it when you need the full supported surface for:
 
 - `wave.config.json`
+- `defaultProject` and `projects.<projectId>`
 - `lanes.<lane>.executors`
 - `waveControl`
 - `executors.profiles.<profile>`
@@ -55,6 +56,121 @@ Then Wave filters configured skills through each bundle's activation metadata. E
 
 When retry-time fallback changes the runtime, Wave recomputes the effective skill set and rewrites the executor overlay before relaunch.
 
+## Projects
+
+Wave can run multiple project tracks from one monorepo.
+
+- `defaultProject` selects the implicit project when a command does not pass `--project`
+- `projects.<projectId>.rootDir` relocates that project's default docs root under the repo
+- `projects.<projectId>.paths.*` can relocate that project's docs, launcher-state, terminal-registry, Context7 bundle index, benchmark catalog, and component-matrix surfaces
+- `projects.<projectId>.lanes.<lane>` owns lane-local runtime, planner, skill, and Wave Control overrides
+- legacy top-level `lanes` still work as the implicit default project for backwards compatibility
+- an explicit unknown `--project` is an error; Wave no longer falls back to `defaultProject` for typoed project ids
+
+Example:
+
+```json
+{
+  "defaultProject": "app",
+  "projects": {
+    "app": {
+      "rootDir": ".",
+      "lanes": {
+        "main": {}
+      }
+    },
+    "service": {
+      "rootDir": "services/api",
+      "lanes": {
+        "main": {}
+      }
+    }
+  }
+}
+```
+
+Supported `projects.<projectId>.paths.*` fields:
+
+| Key | Purpose |
+| --- | --- |
+| `docsDir` | Project-local docs root used as the default base for docs, plans, waves, and matrix defaults |
+| `stateRoot` | Base directory for launcher state, logs, overlays, telemetry, and projections |
+| `orchestratorStateDir` | Base directory for project-scoped orchestrator message boards, feedback, and dependency state |
+| `terminalsPath` | VS Code terminal registry written when `--terminal-surface vscode` is active |
+| `context7BundleIndexPath` | Project-specific Context7 bundle index |
+| `benchmarkCatalogPath` | Project-specific benchmark catalog for `cont-EVAL` and benchmark commands |
+| `componentCutoverMatrixDocPath` | Project-specific component cutover matrix markdown |
+| `componentCutoverMatrixJsonPath` | Project-specific component cutover matrix JSON |
+
+Path resolution order:
+
+1. lane-specific override such as `projects.<projectId>.lanes.<lane>.terminalsPath`
+2. `projects.<projectId>.paths.*`
+3. repo-global `paths.*`
+4. built-in derived defaults for `docsDir`, `plansDir`, `wavesDir`, and matrix paths
+
+Advanced monorepo example:
+
+```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"
+        }
+      }
+    }
+  }
+}
+```
+
 ## Common Fields
 
 These fields are shared across runtimes:
@@ -74,7 +190,7 @@ Practical guidance:
 - prefer `budget.minutes` for normal synthesis, integration, and closure work
 - use generic `budget.turns` as a planning hint, not a hard failure trigger
 - only set `claude.maxTurns` or `opencode.steps` when you deliberately want a hard ceiling for that runtime
-- see [../../guides/recommendations-0.8.8.md](../../guides/recommendations-0.8.8.md) for the recommended `0.8.8` operating stance that combines advisory turn budgets with softer non-proof coordination states
+- see [../../guides/recommendations-0.9.0.md](../../guides/recommendations-0.9.0.md) for the recommended `0.9.0` operating stance that combines advisory turn budgets with softer non-proof coordination states
 
 ## Runtime Pages
 
@@ -86,16 +202,25 @@ Practical guidance:
 
 `wave.config.json` may also declare a `waveControl` block for local-first telemetry delivery.
 
+Packaged defaults in `@chllming/wave-orchestration@0.9.0`:
+
+- `endpoint`: `https://wave-control.up.railway.app/api/v1`
+- `reportMode`: `metadata-only`
+- `enabled`: `true`
+- project-scoped telemetry identity defaults to the resolved `projectId`, then lane and wave metadata from the active run
+
+This package is distributed with the author's personal Wave Control endpoint enabled by default. Anyone who does not want telemetry delivered back to that endpoint must explicitly opt out in config or per run.
+
 Supported top-level fields:
 
 | Key | Type | Default | Purpose |
 | --- | --- | --- | --- |
 | `enabled` | boolean | `true` | Master switch for local queueing and remote delivery |
-| `endpoint` | string | unset | Base URL for the Railway-hosted `services/wave-control` API |
+| `endpoint` | string | `https://wave-control.up.railway.app/api/v1` | Base URL for the Railway-hosted `services/wave-control` API |
 | `workspaceId` | string | derived from repo path | Stable workspace identity used across runs |
-| `projectId` | string | derived from `projectName` | Stable project/repo identity used for cross-workspace reporting and filtering |
+| `projectId` | string | resolved project id | Stable project identity used for cross-workspace reporting and filtering |
 | `authTokenEnvVar` | string | `WAVE_CONTROL_AUTH_TOKEN` | Environment variable name holding the bearer token |
-| `reportMode` | string | `metadata-plus-selected` | `disabled`, `metadata-only`, `metadata-plus-selected`, or `full-artifact-upload` |
+| `reportMode` | string | `metadata-only` | `disabled`, `metadata-only`, `metadata-plus-selected`, or `full-artifact-upload` |
 | `uploadArtifactKinds` | string[] | selected proof/trace/benchmark kinds | Artifact classes eligible for body upload when an artifact's upload policy requests a body |
 | `requestTimeoutMs` | integer | `5000` | Per-batch network timeout |
 | `flushBatchSize` | integer | `25` | Max queued telemetry events flushed per batch |
@@ -105,11 +230,13 @@ Supported top-level fields:
 | `captureTraceBundles` | boolean | `true` | Emit finalized trace-bundle artifacts and gate snapshots |
 | `captureBenchmarkRuns` | boolean | `true` | Emit `benchmark_run`, `benchmark_item`, `verification`, and `review` events |
 
-Lane overrides may refine the same keys under `lanes.<lane>.waveControl`.
+Lane overrides may refine the same keys under `lanes.<lane>.waveControl` or `projects.<projectId>.lanes.<lane>.waveControl`.
 
 One-run override:
 
 - `wave launch --no-telemetry` disables Wave Control queueing and remote delivery for that launcher invocation without changing the repo config.
+- `waveControl.enabled: false` disables queueing and remote delivery for the repo or project.
+- `waveControl.reportMode: "disabled"` disables remote reporting while leaving the config surface explicit.
 
 Example:
 
@@ -118,8 +245,8 @@ Example:
   "waveControl": {
     "endpoint": "https://wave-control.up.railway.app/api/v1",
     "workspaceId": "wave-main",
-    "projectId": "wave-orchestration",
-    "reportMode": "metadata-plus-selected",
+    "projectId": "app",
+    "reportMode": "metadata-only",
     "uploadArtifactKinds": [
       "trace-run-metadata",
       "trace-quality",
@@ -143,8 +270,8 @@ See [../wave-control.md](../wave-control.md) for the event contract and upload-p
 
 Wave writes runtime artifacts here:
 
-- live runs: `.tmp/<lane>-wave-launcher/executors/wave-<n>/<agent-slug>/`
-- dry-run previews: `.tmp/<lane>-wave-launcher/dry-run/executors/wave-<n>/<agent-slug>/`
+- live runs: `.tmp/<lane>-wave-launcher/executors/wave-<n>/<agent-slug>/` for the implicit default project, or `.tmp/projects/<projectId>/<lane>-wave-launcher/executors/wave-<n>/<agent-slug>/` for explicit projects
+- dry-run previews: `.tmp/<lane>-wave-launcher/dry-run/executors/wave-<n>/<agent-slug>/` for the implicit default project, or `.tmp/projects/<projectId>/<lane>-wave-launcher/dry-run/executors/wave-<n>/<agent-slug>/` for explicit projects
 
 Common files:
 
@@ -157,9 +284,10 @@ Common files:
 - `claude-settings.json`: generated Claude settings overlay when inline settings data is present
 - `opencode-agent-prompt.txt`: generated OpenCode harness prompt overlay
 - `opencode.json`: generated OpenCode runtime config overlay
-- `.tmp/<lane>-wave-launcher/control-plane/telemetry/events.jsonl`: local-first Wave Control event stream
-- `.tmp/<lane>-wave-launcher/control-plane/telemetry/pending/`: queued event batches awaiting remote delivery
-- `.tmp/<lane>-wave-launcher/control-plane/telemetry/delivery-state.json`: remote-delivery counters and last-error state
+- `.tmp/<lane>-wave-launcher/control-plane/telemetry/events.jsonl`: local-first Wave Control event stream for the implicit default project
+- `.tmp/projects/<projectId>/<lane>-wave-launcher/control-plane/telemetry/events.jsonl`: same stream for explicit projects
+- `.tmp/.../control-plane/telemetry/pending/`: queued event batches awaiting remote delivery
+- `.tmp/.../control-plane/telemetry/delivery-state.json`: remote-delivery counters and last-error state
 
 Runtime-specific delivery:
 

package/docs/reference/sample-waves.md

@@ -1,21 +1,23 @@
 ---
 title: "Sample Waves"
-summary: "Showcase-first sample waves that demonstrate the shipped 0.8.8 authored surface, including the optional design-role path."
+summary: "Showcase-first sample waves that demonstrate the shipped 0.9.0 authored surface, including the optional design-role path."
 ---
 
 # Sample Waves
 
-This guide points to showcase-first sample waves that demonstrate the shipped `0.8.8` authored Wave surface.
+This guide points to showcase-first sample waves that demonstrate the shipped `0.9.0` authored Wave surface.
 
 The examples are intentionally denser than typical production waves. Their job is to teach the current authoring and runtime surface quickly, not to be the smallest possible launch-ready files.
 
+All example `.tmp/main-wave-launcher/...` paths assume the implicit default project. For explicit monorepo projects, rewrite those to `.tmp/projects/<projectId>/main-wave-launcher/...` and run the matching commands with `--project <projectId>`.
+
 ## Canonical Examples
 
 - [High-fidelity repo-landed rollout wave](../plans/examples/wave-example-rollout-fidelity.md)
   Shows what a good `repo-landed` outcome looks like when one promoted component only closes honestly if desired-state records, reconcile-loop substrate, and cluster-view surfaces land together. It emphasizes maturity discipline, explicit deliverables, and shared-plan closure without drifting into `pilot-live` claims.
 
 - [Full modern sample wave](../plans/examples/wave-example-live-proof.md)
-  Shows the combined `0.8.8` authored surface in one file: closure roles, `E0`, optional security review, delegated and pinned benchmark targets, richer executor config, `### Skills`, `### Capabilities`, `### Deliverables`, `### Exit contract`, `### Proof artifacts`, sticky retry, deploy environments, and proof-first live-wave structure.
+  Shows the combined `0.9.0` authored surface in one file: closure roles, `E0`, optional security review, delegated and pinned benchmark targets, richer executor config, `### Skills`, `### Capabilities`, `### Deliverables`, `### Exit contract`, `### Proof artifacts`, sticky retry, deploy environments, and proof-first live-wave structure.
 
 - [Optional design-steward handoff wave](../plans/examples/wave-example-design-handoff.md)
   Shows the shipped design-role surface: one pre-implementation design steward publishes a design packet, downstream implementation owners read that packet before coding, and normal closure roles still decide final completion. For terminal or operator-surface work, pair that shape with explicit `tui-design` in the design steward's `### Skills`. For the hybrid variant, explicitly give that same design agent implementation-owned paths and the normal implementation contract sections.
@@ -39,10 +41,12 @@ The examples are intentionally denser than typical production waves. Their job i
 - deploy environments and provider-skill examples
 - infra and deploy-verifier specialist slices
 - optional pre-implementation design packets and design-to-implementation handoff
+- security review before integration closure
+- project-aware adaptation for launcher-owned `.tmp/...` paths
 
 ## Feature Coverage Map
 
-Together these samples cover the main surfaces added or hardened through `0.8.8`:
+Together these samples cover the main surfaces added or hardened through `0.9.0`:
 
 - repo-landed maturity discipline and anti-overclaim framing
 - explicit shared-plan closure for future-wave safety
@@ -59,9 +63,100 @@ Together these samples cover the main surfaces added or hardened through `0.8.8`
 - sticky retry for proof-bearing owners
 - proof-first live-wave prompts
 - deploy environments and deploy-kind-aware skills
+- optional security review before integration closure
+- custom closure-role ids when a repo does not want the starter `A0`/`E0`/`A8`/`A9`/`A7` names
+- signal-driven long-running watcher agents through `signal-hygiene`
+- explicit-project launcher-state path rewrites for monorepos
 - integration, documentation, and cont-QA closure-role structure
 - optional `design` worker role and `design-pass` executor profile
 
+## Targeted Snippets For Narrower Surfaces
+
+Some current features are real parts of the authored surface, but they do not belong in every full-length teaching wave. Use these snippets when you need those narrower shapes.
+
+### Custom Closure Role Ids
+
+Wave resolves closure roles from the wave definition first, then from starter defaults. You can keep the same closure semantics while changing the ids:
+
+```md
+## Agent Q4: cont-QA
+
+### Role prompts
+
+- docs/agents/wave-cont-qa-role.md
+
+## Agent V2: cont-EVAL
+
+### Role prompts
+
+- docs/agents/wave-cont-eval-role.md
+
+## Agent I6: Integration Steward
+
+### Role prompts
+
+- docs/agents/wave-integration-role.md
+
+## Agent D8: Documentation Steward
+
+### Role prompts
+
+- docs/agents/wave-documentation-role.md
+
+## Agent S3: Security Review
+
+### Role prompts
+
+- docs/agents/wave-security-role.md
+```
+
+Keep the role prompt and closure meaning aligned even when the ids change. Launch, retry, derived state, and closure sequencing will honor the wave-level bindings.
+
+### Long-Running Watchers With `signal-hygiene`
+
+Use `signal-hygiene` only for intentionally long-running non-resident agents that should wait on orchestrator-written signal changes instead of inventing their own polling protocol.
+
+````md
+## Agent R5: Runtime Watcher
+
+### Executor
+
+- id: codex
+- retry-policy: sticky
+
+### Skills
+
+- role-research
+- runtime-codex
+- signal-hygiene
+
+### Prompt
+
+```text
+Primary goal:
+- Stay alive between orchestrator signal changes and only resume work after acknowledging the next visible signal version.
+
+Specific expectations:
+- use the prompt-visible signal state path and ack path exactly as provided
+- do not create a second polling file or custom wakeup loop
+- emit normal structured coordination records when new evidence or blockers appear
+```
+````
+
+Pair that snippet with [signal-wrappers.md](../guides/signal-wrappers.md) when shell automation or external wait loops also need to observe the same signal surface.
+
+### Project-Aware Launcher-Owned Paths
+
+When copying a proof-first example into an explicit monorepo project, update launcher-owned file paths as well as the runtime command:
+
+```md
+File ownership (only touch these paths):
+- .tmp/projects/service/main-wave-launcher/integration/wave-14.md
+- .tmp/projects/service/main-wave-launcher/integration/wave-14.json
+```
+
+The same rewrite applies to proof bundles, logs, dashboards, coordination state, and telemetry spools under `.tmp/<lane>-wave-launcher/...`.
+
 ## When To Copy Literally Vs Adapt
 
 Copy more literally when:
@@ -89,7 +184,7 @@ Adapt more aggressively when:
 ## Suggested Reading Order
 
 1. Start with [High-fidelity repo-landed rollout wave](../plans/examples/wave-example-rollout-fidelity.md) if you want the clearest example of good closure-ready wave fidelity for a repo-only outcome.
-2. Read [Full modern sample wave](../plans/examples/wave-example-live-proof.md) if you want the denser proof-first and eval-heavy `0.8.8` surface.
+2. Read [Full modern sample wave](../plans/examples/wave-example-live-proof.md) if you want the denser proof-first and eval-heavy `0.9.0` surface.
 3. Read [Optional design-steward handoff wave](../plans/examples/wave-example-design-handoff.md) if the task needs a design packet before implementation fan-out.
 4. Read [docs/evals/README.md](../evals/README.md) if you want more background on benchmark target selection.
 5. Read [docs/reference/live-proof-waves.md](./live-proof-waves.md) if you want more detail on proof-first `pilot-live` authoring.

package/docs/reference/skills.md

@@ -124,7 +124,7 @@ Top-level and lane-local skill attachment use the same shape:
 
 Lane-local `lanes.<lane>.skills` extends the global config instead of replacing it.
 
-Optional design workers in the shipped `0.8.8` surface normally attach `role-design`. That bundle is intended for docs/spec-first design packets and explicit implementation handoff work before implementation starts. When the design packet covers terminal UX, dashboards, or other operator surfaces, add `tui-design` explicitly in the wave's `### Skills`.
+Optional design workers in the shipped `0.9.0` surface normally attach `role-design`. That bundle is intended for docs/spec-first design packets and explicit implementation handoff work before implementation starts. When the design packet covers terminal UX, dashboards, or other operator surfaces, add `tui-design` explicitly in the wave's `### Skills`.
 
 Long-running agents that should stay resident and react only to orchestrator signal changes can add `signal-hygiene` explicitly in `### Skills`. That bundle is not auto-attached and is not meant for normal one-shot implementation agents.
 

package/docs/reference/wave-control.md

@@ -129,7 +129,6 @@ Upload policy meanings:
 
 - `local-only`: keep only the descriptor remotely
 - `metadata-only`: report path, hash, size, and presence only
-- `selected`: upload metadata plus the artifact body when the runtime is in `metadata-plus-selected`
 - `selected`: upload metadata plus the artifact body when the runtime is in `metadata-plus-selected` or `full-artifact-upload` **and** the artifact kind is allowed by `waveControl.uploadArtifactKinds`
 - `full`: upload the artifact body in `full-artifact-upload` flows; if `uploadArtifactKinds` is set, keep the kind allowlist aligned with that policy
 
@@ -142,9 +141,9 @@ Upload policy meanings:
   "waveControl": {
     "endpoint": "https://wave-control.up.railway.app/api/v1",
     "workspaceId": "my-workspace",
-    "projectId": "wave-orchestration",
+    "projectId": "app",
     "authTokenEnvVar": "WAVE_CONTROL_AUTH_TOKEN",
-    "reportMode": "metadata-plus-selected",
+    "reportMode": "metadata-only",
     "uploadArtifactKinds": [
       "trace-run-metadata",
       "trace-quality",
@@ -154,7 +153,16 @@ Upload policy meanings:
 }
 ```
 
-Lane overrides may refine the same surface under `lanes.<lane>.waveControl`.
+Packaged defaults:
+
+- endpoint: `https://wave-control.up.railway.app/api/v1`
+- enabled: `true`
+- report mode: `metadata-only`
+- identity defaults to the resolved project, lane, wave, run kind, and run id
+
+This package is distributed with the author's personal Wave Control endpoint enabled by default. Repos that do not want telemetry delivered there must explicitly opt out.
+
+Lane overrides may refine the same surface under `lanes.<lane>.waveControl` or `projects.<projectId>.lanes.<lane>.waveControl`.
 
 For a single run, operators can disable Wave Control reporting entirely with:
 
@@ -162,6 +170,16 @@ For a single run, operators can disable Wave Control reporting entirely with:
 pnpm exec wave launch --lane main --no-telemetry
 ```
 
+Repo or project config may also opt out with:
+
+```json
+{
+  "waveControl": {
+    "enabled": false
+  }
+}
+```
+
 That suppresses the local telemetry spool and remote delivery for that invocation, while leaving the canonical runtime artifacts and local control-plane state intact.
 
 ## Delivery Model
@@ -169,7 +187,7 @@ That suppresses the local telemetry spool and remote delivery for that invocatio
 Wave Control reporting should:
 
 - append local telemetry first
-- queue pending uploads under `.tmp/<lane>-wave-launcher/control-plane/telemetry/`
+- queue pending uploads 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
 - respect `waveControl.uploadArtifactKinds` before uploading any selected artifact body
 - cap pending remote uploads with `waveControl.maxPendingEvents` by dropping the oldest queued remote-delivery files, while keeping the local `events.jsonl` stream intact
 - retry delivery with idempotency keys

package/docs/roadmap.md

@@ -49,7 +49,7 @@ Generated waves and transient ad-hoc runs should default to these sections when
 
 Status: shipped in `0.5.4`.
 
-- Add saved project bootstrap memory in `.wave/project-profile.json`.
+- Add saved project bootstrap memory in `.wave/project-profile.json` for the implicit default project, with project-scoped profiles under `.wave/projects/<projectId>/project-profile.json` for explicit monorepo projects.
 - Ask once whether the repo is a new project and keep that answer for future drafts.
 - Add `wave project setup` and `wave project show`.
 - Add interactive `wave draft` that writes:
@@ -91,7 +91,7 @@ Behavior:
 Storage model:
 
 - do not write ad-hoc runs into the canonical numbered wave sequence under `docs/plans/waves/`
-- store the original request, generated spec, rendered markdown, and final result under `.wave/adhoc/runs/<run-id>/`
+- store the original request, generated spec, rendered markdown, and final result under `.wave/adhoc/<projectId>/runs/<run-id>/` for explicit projects, while the implicit default project keeps the legacy layout
 - keep runtime state isolated under `.tmp/<lane>-wave-launcher/adhoc/<run-id>/`
 - extend trace metadata with `runKind: adhoc` and `runId`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chllming/wave-orchestration",
-  "version": "0.8.8",
+  "version": "0.9.0",
   "license": "MIT",
   "description": "Generic wave-based multi-agent orchestration for repository work.",
   "repository": {

package/releases/manifest.json

@@ -2,6 +2,43 @@
   "schemaVersion": 1,
   "packageName": "@chllming/wave-orchestration",
   "releases": [
+    {
+      "version": "0.9.0",
+      "date": "2026-03-28",
+      "summary": "First-class monorepo project support, project-aware runtime isolation, default Wave Control metadata delivery, and 0.9.0 release-surface alignment.",
+      "features": [
+        "Wave configs can now declare `defaultProject` and `projects.<projectId>`, so one repo can host multiple projects with isolated lane roots, docs roots, planner defaults, and runtime state.",
+        "Lane-scoped CLI surfaces now accept `--project`, including launch, autonomous, dashboard, control, coordination, dependencies, ad-hoc work, proof, retry, feedback, drafting, and benchmarks.",
+        "Planner defaults, ad-hoc runs, dependency tickets, tmux naming, launcher state, and benchmark identity are now project-aware, which prevents same-lane-name collisions in monorepos.",
+        "Wave Control now defaults to `https://wave-control.up.railway.app/api/v1` with `reportMode: \"metadata-only\"`, and benchmark plus runtime metadata now include project, lane, and wave identity unless explicitly opted out.",
+        "Planner migration guidance and the `planner-agentic` bundle placeholder remain part of the shipped current-surface docs so adopted repos still have one aligned upgrade target.",
+        "README, current-state notes, migration guidance, runtime-config docs, coordination docs, the new monorepo guide, the versioned recommendations guide, release manifest, and tracked install-state fixtures now all point at the `0.9.0` package surface."
+      ],
+      "manualSteps": [
+        "Run `pnpm exec wave doctor` and `pnpm exec wave launch --lane main --dry-run --no-dashboard` after upgrading so the repo validates against the `0.9.0` release surface.",
+        "If your repo copied starter docs or runbooks, sync `README.md`, `docs/README.md`, `docs/plans/current-state.md`, `docs/plans/migration.md`, `docs/reference/coordination-and-closure.md`, `docs/reference/runtime-config/README.md`, `docs/guides/monorepo-projects.md`, and `docs/guides/recommendations-0.9.0.md` so local guidance matches the packaged release.",
+        "If your repo copied starter `wave.config.json` defaults or automation around lane-only state paths, update them for `defaultProject`, `projects.<projectId>`, project-scoped `.wave/projects/<projectId>/project-profile.json`, project-scoped ad-hoc storage, and explicit telemetry opt-out controls before relying on monorepo behavior."
+      ],
+      "breaking": false
+    },
+    {
+      "version": "0.8.9",
+      "date": "2026-03-27",
+      "summary": "Design-gate report-path preservation, accurate post-design failure reporting, trace-summary alignment, and 0.8.9 release-surface sync.",
+      "features": [
+        "Reducer snapshots now preserve design packet report paths when rebuilding summaries from result envelopes, so `designGate` no longer reopens as `missing-design-packet` after a successful design pass.",
+        "Launcher transitions after design-only passes now stop on the actual design-gate blocker 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 resolves design packet report paths, so copied trace summaries stay aligned when design summaries are rebuilt from logs.",
+        "README, current-state notes, migration guidance, release manifest, tracked install-state fixtures, and the versioned recommendations guide now all point at the `0.8.9` package surface.",
+        "Planner migration guidance and the `planner-agentic` bundle placeholder remain part of the shipped current-surface docs so adopted repos still have one aligned upgrade target."
+      ],
+      "manualSteps": [
+        "Run `pnpm exec wave doctor` and `pnpm exec wave launch --lane main --dry-run --no-dashboard` after upgrading so the repo validates against the `0.8.9` release surface.",
+        "If your repo copied current-surface docs or runbooks, sync `README.md`, `docs/README.md`, `docs/plans/current-state.md`, `docs/plans/migration.md`, `docs/reference/coordination-and-closure.md`, `docs/reference/runtime-config/README.md`, and `docs/guides/recommendations-0.8.9.md` so local guidance matches the packaged release.",
+        "If your repo copied trace or replay helpers around design packets, sync the updated reducer, launcher, and trace-summary reconstruction behavior before relying on rebuilt design summaries in replay tooling."
+      ],
+      "breaking": false
+    },
     {
       "version": "0.8.8",
       "date": "2026-03-27",