@chllming/wave-orchestration 0.8.7 → 0.8.8

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## Unreleased
 
+## 0.8.8 - 2026-03-27
+
+### Changed
+
+- The current release surface now ships the practical operating recommendations guide as `docs/guides/recommendations-0.8.8.md`, and the README, current-state notes, migration guide, coordination docs, and runtime-config docs now all point at the same `0.8.8` package surface.
+- The tracked install-state fixture and upgrade-history records now advance to `0.8.8`, so repo-owned validation no longer lags the published package version after the follow-up docs cut.
+
+### Fixed And Hardened
+
+- Release-surface regression coverage now derives the recommendations-guide path from the current package version instead of a hard-coded `0.8.7` file name, which prevents the same drift on the next release.
+
+### Testing And Validation
+
+- `node scripts/wave.mjs doctor --json`
+- `pnpm test -- test/wave-orchestrator/release-surface.test.ts`
+
 ## 0.8.7 - 2026-03-27
 
 ### Changed

package/README.md

@@ -103,18 +103,18 @@ Wave is built to mitigate those failures with a canonical authority set, generat
 
 Current release:
 
-- `@chllming/wave-orchestration@0.8.7`
-- Release tag: [`v0.8.7`](https://github.com/chllming/agent-wave-orchestrator/releases/tag/v0.8.7)
+- `@chllming/wave-orchestration@0.8.8`
+- Release tag: [`v0.8.8`](https://github.com/chllming/agent-wave-orchestrator/releases/tag/v0.8.8)
 - Public install path: npmjs
 - Authenticated fallback: GitHub Packages
 
-Highlights in `0.8.7`:
+Highlights in `0.8.8`:
 
 - The shipped starter surface now includes `skills/signal-hygiene/` plus seeded `scripts/wave-status.sh` and `scripts/wave-watch.sh` wrappers for long-running-agent and operator wait loops.
 - Long-running agents and resident orchestrators now get prompt-level signal-state and signal-ack paths, so wakeups are edge-triggered by versioned signal changes instead of relying on terminal injection.
 - Versioned wave or agent signal snapshots are now a first-class operator surface under `.tmp/<lane>-wave-launcher/signals/`, with failure treated as terminal in both the runtime and the wrapper exit contract.
-- `0.8.5` design-role and hybrid design-steward behavior remains part of the shipped release surface, and `0.8.7` adds capability-specific same-wave helper routing, blocker-severity consistency across reducer state, and stable per-wave tmux session reuse.
-- Release docs, current-state notes, migration guidance, and publishing instructions now point at the `0.8.7` surface.
+- `0.8.5` design-role and hybrid design-steward behavior remains part of the shipped release surface, and the current release line keeps the `0.8.7` capability-specific same-wave helper routing, blocker-severity consistency, and stable per-wave tmux session reuse hardening.
+- Release docs, current-state notes, migration guidance, publishing instructions, and the packaged operator recommendations guide now point at the `0.8.8` surface.
 
 Requirements:
 

package/docs/README.md

@@ -36,13 +36,15 @@ The useful path is journey-first:
 - 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.
 - 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.7` 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.8.8` 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.8` operating stance:
+  Read [guides/recommendations-0.8.8.md](./guides/recommendations-0.8.8.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/guides/author-and-run-waves.md

@@ -61,7 +61,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.7` is:
+The starter contract in `0.8.8` is:
 
 - import `docs/agents/wave-design-role.md`
 - own one packet such as `docs/plans/waves/design/wave-<n>-<agentId>.md`

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.7` package already includes the optional `design` worker role for pre-implementation design packets. This guide calls out where that affects drafting.
+The published `0.8.8` package already includes the optional `design` worker role for pre-implementation design packets. This guide calls out where that affects drafting.
 
 ## What Ships Today
 

package/docs/guides/recommendations-0.8.8.md

@@ -0,0 +1,133 @@
+---
+title: "0.8.8 Recommendations"
+summary: "How to use 0.8.8's softer blocker states, advisory turn budgets, and targeted recovery without weakening proof and closure."
+---
+
+# 0.8.8 Recommendations
+
+Use this guide when you are adopting `0.8.8` 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.8` default is:
+
+- bound work with `budget.minutes`
+- leave generic `budget.turns` as advisory metadata
+- author non-proof follow-up as `soft`, `stale`, or `advisory` instead of silently treating every open record as a hard blocker
+- use `resolve-policy` when the answer already exists in repo policy or shipped docs
+- prefer targeted rerun or resume after timeout, max-turn, rate-limit, or missing-status outcomes instead of relaunching the whole wave
+
+That recommendation matches the runtime:
+
+- executor launch metadata only emits hard turn-limit flags from `claude.maxTurns` or `opencode.steps`
+- open `stale` and `advisory` coordination records stay visible without reopening the active blocking edge
+- recoverable launcher failures queue targeted retry state instead of immediately escalating to broad terminal wave failure
+
+## 1. Budgets
+
+Treat the two budget knobs differently:
+
+- `budget.minutes` is the primary attempt budget
+- generic `budget.turns` is only a planning hint
+- `claude.maxTurns` or `opencode.steps` are the hard runtime ceilings when you actually want deterministic turn stopping
+
+Recommended pattern for synthesis-heavy implementation or closure work:
+
+```json
+{
+  "executors": {
+    "profiles": {
+      "implementation-default": {
+        "id": "claude",
+        "model": "claude-sonnet-4-6",
+        "budget": {
+          "minutes": 35,
+          "turns": 12
+        }
+      }
+    }
+  }
+}
+```
+
+In that pattern, `35` minutes is real policy. `12` turns is only guidance for planning and preview metadata.
+
+Only set a hard runtime ceiling when you deliberately want the runtime itself to stop:
+
+```json
+{
+  "executors": {
+    "profiles": {
+      "bounded-closure": {
+        "id": "claude",
+        "model": "claude-sonnet-4-6",
+        "budget": {
+          "minutes": 20
+        },
+        "claude": {
+          "maxTurns": 6
+        }
+      }
+    }
+  }
+}
+```
+
+## 2. Softer Coordination States
+
+`0.8.8` keeps “still visible” separate from “still blocking”.
+
+Use these states intentionally:
+
+| State | Use it for | What the runtime does |
+| --- | --- | --- |
+| `soft` | follow-up that still matters but should not be treated like proof failure | remains visible and may still drive repair or retry targeting |
+| `stale` | outdated clarification or blocker context kept for history | visible in control state, but does not reopen blocking by itself |
+| `advisory` | known issue, note, or human context that should stay visible without blocking closure | visible in control state, but does not own the active blocking edge |
+
+Practical command paths:
+
+```bash
+pnpm exec wave control task act defer --lane main --wave 10 --id blocker-doc-follow-up
+pnpm exec wave control task act mark-stale --lane main --wave 10 --id clarify-a7-rollout
+pnpm exec wave control task act mark-advisory --lane main --wave 10 --id request-clarify-a7-rollout
+pnpm exec wave control task act resolve-policy --lane main --wave 10 --id clarify-a7-rollout --detail "Policy already covered in the rollout guide."
+```
+
+Use them when the repo already knows the answer, the remaining item is informational, or the follow-up should stay visible for the next wave without holding the current wave hostage.
+
+## 3. What Should Stay Hard
+
+Do not relax everything.
+
+Keep these hard or closure-critical unless you are intentionally changing wave policy:
+
+- missing proof or required deliverables
+- failed integration, documentation, or cont-QA closure gates
+- real human-feedback or escalation requirements that block safe continuation
+- requests or clarifications that still represent unresolved ownership or policy ambiguity for the current wave
+
+If the current wave cannot truthfully close without the answer, keep it blocking.
+
+## 4. Recovery Recommendation
+
+My recommendation after reviewing the current `0.8.8` 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
+- preserve reusable proof from successful sibling owners whenever the reducer already identified it as reusable
+
+That is the shape the launcher now prefers. It only broadens failure when the remaining blockers are still proof-critical or otherwise non-recoverable.
+
+## 5. Suggested Operator Policy
+
+For most repo-owned runbooks:
+
+- teach authors to use `budget.minutes` first
+- teach operators to downgrade only non-proof follow-up
+- treat `resolve-policy` as the preferred path when the answer already exists in docs or repo policy
+- escalate to a full-wave rerun only after targeted recovery proves insufficient
+
+If you want a single sentence policy:
+
+> Keep proof and closure strict, keep generic turns advisory, and keep non-proof context visible without letting it accidentally own wave closure.

package/docs/plans/current-state.md

@@ -1,9 +1,10 @@
 # Current State
 
-- The published package is `0.8.7`, and that release now includes the optional pre-implementation `design` worker role, the `role-design`, `tui-design`, and `signal-hygiene` starter bundles, plus the seeded signal-wrapper scripts for long-running-agent and operator wait loops.
+- The published package is `0.8.8`, and that release now includes the optional pre-implementation `design` worker role, the `role-design`, `tui-design`, and `signal-hygiene` starter bundles, plus the seeded signal-wrapper scripts for long-running-agent and operator wait loops.
 - 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.8` operating stance is documented in `docs/guides/recommendations-0.8.8.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`.

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.7` 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.8.8` 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.7`.
+This is a showcase-first sample wave for the shipped `design` worker role in `0.8.8`.
 
 This example demonstrates the docs-first design-steward path where a design packet is published before code-owning implementation begins.
 

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

@@ -2,7 +2,7 @@
 
 This is a showcase-first sample wave.
 
-Use it as the single reference example for the current `0.8.7` Wave surface.
+Use it as the single reference example for the current `0.8.8` Wave surface.
 
 It intentionally combines more sections than a normal production wave so one file can demonstrate:
 

package/docs/plans/migration.md

@@ -1,6 +1,6 @@
 # Migration
 
-This page is the practical repo-upgrade guide for the current `0.8.7` surface.
+This page is the practical repo-upgrade guide for the current `0.8.8` surface.
 
 Use it when you are:
 
@@ -10,9 +10,9 @@ 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.7` Changes
+## What `0.8.8` Changes
 
-The current `0.8.7` surface adds policy consistency and stable per-wave session reuse on top of the `0.8.6` signal-driven operator model.
+The current `0.8.8` surface keeps the `0.8.7` policy-consistency and stable per-wave session reuse hardening, and now also packages the operator recommendations guide and install-state alignment follow-up in the release itself.
 
 The practical changes are:
 
@@ -21,7 +21,9 @@ The practical changes are:
 - advisory or stale clarification and human-input records remain visible in coordination history and reducer blocker views, but they no longer reopen `clarifying` or blocked reducer state by themselves
 - wave-agent and resident-orchestrator tmux sessions now reuse stable per-wave session names, so relaunches and stale launcher exits stop accumulating extra tmux sessions for the same wave
 
-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.7` package cut.
+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.8` package cut.
+
+For a practical `0.8.8` operating stance after the upgrade, read [../guides/recommendations-0.8.8.md](../guides/recommendations-0.8.8.md).
 
 ## What `0.8.6` Changes
 
@@ -136,13 +138,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.7` Release Model
+## `0.8.8` Release Model
 
-The current `0.8.7` surface is three changes together:
+The current `0.8.8` 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.8`
 
 ### Signal-driven waiting and wrapper model
 
@@ -326,9 +329,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.7`
+## Upgrading From `0.8.3` To `0.8.8`
 
-Treat this as one move to the current `0.8.7` surface.
+Treat this as one move to the current `0.8.8` surface.
 
 ### What changed across that range
 
@@ -361,7 +364,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.7`
+## Upgrading From `0.6.x` Or `0.7.x` To `0.8.8`
 
 This is the main migration path for older adopted repos.
 
@@ -402,7 +405,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.7`
+## Upgrading From `0.5.x` Or Earlier To `0.8.8`
 
 Do not treat this as a tiny patch bump.
 
@@ -512,4 +515,4 @@ For repos that depend on replay parity, replay at least:
 
 ## Summary
 
-The current `0.8.7` 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, and now also hardens policy consistency, targeted recovery, capability-specific routing, and stable per-wave tmux session reuse. 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.8.8` 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/reference/cli-reference.md

@@ -561,7 +561,7 @@ Interactive draft currently offers worker role kinds:
 - `research`
 - `security`
 
-Agentic planner payloads also accept `workerAgents[].roleKind = "design"`. The shipped `0.8.7` 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.8.8` 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
 

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

@@ -134,6 +134,8 @@ 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.8` recommendation on when to keep records blocking versus when to downgrade them to `soft`, `stale`, or `advisory`, see [../guides/recommendations-0.8.8.md](../guides/recommendations-0.8.8.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.
 
 ## Deliverables Versus Helper Work

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.7` release procedure publishes through a repository Actions secret named `NPM_TOKEN`.
+The current `0.8.8` 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.7`.
+5. Push the release commit and release tag, for example `v0.8.8`.
 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.

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

@@ -74,6 +74,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
 
 ## Runtime Pages
 

package/docs/reference/sample-waves.md

@@ -1,11 +1,11 @@
 ---
 title: "Sample Waves"
-summary: "Showcase-first sample waves that demonstrate the shipped 0.8.7 authored surface, including the optional design-role path."
+summary: "Showcase-first sample waves that demonstrate the shipped 0.8.8 authored surface, including the optional design-role path."
 ---
 
 # Sample Waves
 
-This guide points to showcase-first sample waves that demonstrate the shipped `0.8.7` authored Wave surface.
+This guide points to showcase-first sample waves that demonstrate the shipped `0.8.8` 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.
 
@@ -15,7 +15,7 @@ The examples are intentionally denser than typical production waves. Their job i
   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.7` 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.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.
 
 - [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.
@@ -42,7 +42,7 @@ The examples are intentionally denser than typical production waves. Their job i
 
 ## Feature Coverage Map
 
-Together these samples cover the main surfaces added or hardened through `0.8.7`:
+Together these samples cover the main surfaces added or hardened through `0.8.8`:
 
 - repo-landed maturity discipline and anti-overclaim framing
 - explicit shared-plan closure for future-wave safety
@@ -89,7 +89,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.7` 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.8.8` 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.7` 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.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`.
 
 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/package.json

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

package/releases/manifest.json

@@ -2,6 +2,23 @@
   "schemaVersion": 1,
   "packageName": "@chllming/wave-orchestration",
   "releases": [
+    {
+      "version": "0.8.8",
+      "date": "2026-03-27",
+      "summary": "0.8.8 release-surface alignment, packaged operating recommendations, and install-state fixture refresh.",
+      "features": [
+        "The practical operating recommendations guide now ships as `docs/guides/recommendations-0.8.8.md`, and the README, migration, coordination, and runtime-config docs now point at the same current package surface.",
+        "The tracked `.wave/install-state.json` fixture and upgrade-history metadata now align with the `0.8.8` package version so `wave doctor --json` no longer reports stale install-state versioning after the follow-up docs release.",
+        "Release-surface regression coverage now derives the recommendations-guide path from `package.json` instead of a hard-coded `0.8.7` filename, which hardens future release cuts against the same doc-link drift.",
+        "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.8` 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.8.md` so local guidance matches the packaged release.",
+        "If your repo tracks the install-state fixture in source control, refresh `.wave/install-state.json` and the matching upgrade-history report so repo-owned validation stays aligned with the installed package."
+      ],
+      "breaking": false
+    },
     {
       "version": "0.8.7",
       "date": "2026-03-27",