@chllming/wave-orchestration 0.8.4 → 0.8.6

package/docs/plans/migration.md

@@ -1,157 +1,369 @@
 # Migration
 
-This page is the operator-facing upgrade guide for adopting repos. It explains how to move from older Wave package versions onto the current `0.8.4` surface without guessing which files are package-owned, which files are repo-owned, and which validations to trust after the bump.
+This page is the practical repo-upgrade guide for the current `0.8.6` surface.
 
-For the completed internal architecture cutover record, see [architecture-hardening-migration.md](./architecture-hardening-migration.md). That document is historical. This one is the practical repo-upgrade checklist.
+Use it when you are:
 
-## What `0.8.4` Changes
+- adopting Wave in a repo that already has local prompts, docs, or skills
+- upgrading from an older package release
+- deciding which files to sync from the starter surface and which files to leave repo-owned
 
-`0.8.4` is a hardening release, not a new authoring model.
+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.
 
-- contradiction replay no longer depends on component-matrix parsing when the trace does not declare promoted components
-- `requireComponentPromotionsFromWave` now disables both component-promotion proof blocking and component-matrix current-level blocking before the configured threshold
-- `projection-writer.mjs` is now the single persistence layer for projection outputs, while `derived-state-engine.mjs` computes those payloads without persisting them directly
-- starter docs, release notes, README, and publishing guidance now describe the shipped runtime instead of transitional architecture claims
+## What `0.8.6` Changes
 
-There are no new CLI flags or wave-file section requirements in `0.8.4`.
+`0.8.6` keeps the `0.8.5` design-role surface and adds a new signal-driven operator and long-running-agent model.
+
+The biggest additions are:
+
+- the optional `design` worker role remains part of the published package surface
+- starter design bundles still ship in `docs/agents/wave-design-role.md`, `skills/role-design/`, and `skills/tui-design/`
+- starter signal bundles now also ship in `skills/signal-hygiene/`, `scripts/wave-status.sh`, and `scripts/wave-watch.sh`
+- long-running agents and resident orchestrators now receive prompt-visible signal-state and signal-ack paths
+- canonical versioned wave and agent signal snapshots now live under `.tmp/<lane>-wave-launcher/signals/`
+- wrapper and signal semantics now treat `completed` and `failed` as truly terminal, with wrapper exit `40` for failed terminal state
+
+There are no new top-level CLI commands for `0.8.6`. The wrapper scripts are starter utilities layered over `wave control status --json`, not a new top-level CLI family.
 
 ## Upgrade Contract
 
-- `pnpm up @chllming/wave-orchestration` updates the runtime in `node_modules`.
+- `pnpm up @chllming/wave-orchestration` updates the installed runtime.
 - `pnpm exec wave upgrade` writes `.wave/install-state.json` and `.wave/upgrade-history/*` only.
-- `wave upgrade` does not rewrite repo-owned `wave.config.json`, `docs/agents/*`, `docs/plans/waves/*`, `skills/*`, `docs/context7/*`, or repo-specific reference docs.
-- `.tmp/<lane>-wave-launcher/` is runtime state, not migration source of truth. Do not treat old generated artifacts as the thing to preserve.
+- `wave upgrade` does not rewrite repo-owned `wave.config.json`, `docs/agents/*`, `docs/plans/waves/*`, `skills/*`, `docs/context7/*`, or local runbooks.
+- `.tmp/<lane>-wave-launcher/` is runtime state, not migration source of truth. Do not preserve old generated artifacts as if they were authored configuration.
 
-## Default Adoption Path
+## Package-Owned vs Repo-Owned
 
-Use this when the repo is not already running Wave or you are replacing a very old local starter copy.
+Treat these as package-owned starter surface unless your repo intentionally copied and now maintains them:
 
-1. Install the package from npmjs with `pnpm add -D @chllming/wave-orchestration`.
-2. For a fresh repo, run `pnpm exec wave init`.
-3. For a repo that already owns Wave config, docs, or waves, run `pnpm exec wave init --adopt-existing`.
-4. Review `wave.config.json` for docs roots, roles, validation thresholds, executor defaults, skill attachments, Context7 bundles, and component-cutover matrix paths.
-5. Replace starter sample plans, starter skills, and starter prompts with repo-owned versions where needed.
-6. Run the validation checklist in this doc before the first live launcher run.
+- `docs/agents/*.md`
+- `skills/*`
+- `scripts/wave-status.sh`
+- `scripts/wave-watch.sh`
+- `docs/guides/signal-wrappers.md`
+- `docs/plans/current-state.md`
+- `docs/plans/end-state-architecture.md`
+- `docs/plans/wave-orchestrator.md`
+- `docs/plans/migration.md`
+- `docs/reference/*`
+- `docs/context7/planner-agent/*`
 
-GitHub Packages remains an authenticated fallback install path, but npmjs is the default public distribution channel.
+Treat these as repo-owned operational surface:
 
-## Safe Upgrade Flow For Any Existing Repo
+- `wave.config.json`
+- `docs/plans/waves/*.md`
+- `docs/plans/waves/specs/*.json`
+- repo-specific prompts, internal runbooks, and policy docs
+- repository source code and deployment config
 
-Use this flow before the version-specific sections below.
+If your repo never copied a starter file, do not invent migration work for it. The installed package already ships the runtime behavior.
 
-### 1. Upgrade When The Lane Is Idle
+## Safe Upgrade Flow For Any Existing Repo
+
+### 1. Upgrade when the lane is idle
 
 - Prefer upgrading between waves, not mid-attempt.
 - If a lane still has running sessions, finish or intentionally stop that attempt before changing package versions.
-- If a repo is stranded after a prior crash, inspect `wave control status` first, then decide whether to relaunch or reconcile on the upgraded package.
+- If the repo is stranded after a prior crash, inspect `wave control status` first and decide whether to relaunch or reconcile on the upgraded package.
 
-### 2. Bump The Package
+### 2. Bump the package
 
 ```bash
 pnpm up @chllming/wave-orchestration
 pnpm exec wave upgrade
 ```
 
-### 3. Sync Repo-Owned Starter Surface Only If You Copied It
-
-If your repo copied package-owned starter docs, prompts, or skills instead of treating them as read-only package material, sync the copied files that you still want to match upstream.
+### 3. Sync repo-owned starter surface only if you copied it
 
-The common sync set is:
+The most common sync set for `0.8.6` is:
 
 - `docs/agents/wave-launcher-role.md`
 - `docs/agents/wave-orchestrator-role.md`
 - `docs/agents/wave-planner-role.md`
+- `docs/agents/wave-design-role.md`
 - `skills/wave-core/`
 - `skills/role-planner/`
-- runtime and closure-role starter skills under `skills/`
+- `skills/role-design/`
+- `skills/tui-design/`
+- `skills/signal-hygiene/`
+- `scripts/wave-status.sh`
+- `scripts/wave-watch.sh`
+- `docs/guides/author-and-run-waves.md`
+- `docs/guides/planner.md`
+- `docs/guides/terminal-surfaces.md`
+- `docs/guides/signal-wrappers.md`
 - `docs/context7/planner-agent/`
 - `docs/reference/wave-planning-lessons.md`
+- `docs/reference/cli-reference.md`
+- `docs/reference/skills.md`
+- `docs/reference/sample-waves.md`
 - `docs/plans/current-state.md`
 - `docs/plans/end-state-architecture.md`
 - `docs/plans/wave-orchestrator.md`
 - `docs/plans/migration.md`
 
-If your repo never copied those starter files, do not invent migration work. The installed package already carries the new runtime behavior.
+If your repo copied starter `wave.config.json` defaults, also sync:
+
+- `roles.designRolePromptPath`
+- `skills.byRole.design`
+- `executors.profiles.design-pass`
 
-### 4. Re-validate Before A Live Run
+### 4. Re-validate before a live run
 
 Run these from the repo root:
 
 ```bash
-pnpm exec wave doctor
+pnpm exec wave doctor --json
 pnpm exec wave launch --lane main --dry-run --no-dashboard
 pnpm exec wave control status --lane main --wave 0 --json
+scripts/wave-status.sh --lane main --wave 0
+scripts/wave-watch.sh --lane main --wave 0 --until-change --refresh-ms 500
 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 an existing tmux-backed dashboard after the upgrade.
+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.6` Release Model
+
+The current `0.8.6` surface is two 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`
+
+### Signal-driven waiting and wrapper model
+
+This is the main new behavior in `0.8.6`.
+
+Starter repos now include:
+
+- `skills/signal-hygiene/`
+- `scripts/wave-status.sh`
+- `scripts/wave-watch.sh`
+
+Use that model when:
+
+- an external shell loop or CI job should wait for a wave or agent to change state
+- a non-resident agent is intentionally long-running and should wake only on orchestrator-written signal changes
+- a resident orchestrator should explicitly acknowledge that it observed a reroute, answered feedback, or terminal transition
+
+The contract is:
+
+- the runtime publishes versioned signal snapshots under `.tmp/<lane>-wave-launcher/signals/`
+- long-running watchers receive a signal-state path and signal-ack path in the prompt
+- the watcher writes the ack file immediately after it observes a new signal version
+- wrapper exit codes are now:
+  - `0` completed
+  - `10` still active or waiting
+  - `20` input required
+  - `30` signal changed while still active from `wave-watch.sh --until-change`
+  - `40` failed
+
+If your repo copied operator docs, shell automation, or starter scripts, this is the main sync set to apply from `0.8.6`.
+
+### `0.8.5` design-steward model
+
+Docs-first design stewards:
+
+- import `docs/agents/wave-design-role.md`
+- own at least one packet path such as `docs/plans/waves/design/wave-<n>-<agentId>.md`
+- stay docs or spec-first
+- finish with `[wave-design] state=<ready-for-implementation|needs-clarification|blocked> ...`
+
+If the wave explicitly assigns non-packet ownership to a design agent, that agent becomes a hybrid design steward.
+
+The runtime treats that as:
+
+1. a design pass first
+2. then the same agent rejoins implementation with normal proof obligations
+
+For a hybrid design steward, make sure the wave still includes:
+
+- a design packet path
+- any explicit implementation-owned paths
+- `### Exit contract` when your lane validation requires it
+- `### Components` when your lane validation requires them
+- `### Proof artifacts` when the owned slice is proof-centric
+
+The second pass must still re-emit `[wave-design]`, and it must also satisfy the normal implementation proof, doc-delta, and component-marker contract.
+
+The interactive `wave draft` flow supports `design` as a worker role and scaffolds the docs-first default path. If you want a hybrid design steward today, the safest authoring paths are manual edits or an agentic planner payload that already declares the design agent's explicit implementation ownership.
 
 ## Version-Specific Upgrade Guidance
 
-## Upgrading From `0.8.3` To `0.8.4`
+## Upgrading From `0.8.5` To `0.8.6`
 
-This is the smallest migration.
+This is the smallest upgrade, but it changes the live wait-loop contract for external automation and intentionally long-running agents.
 
 ### What changed
 
-- contradiction replay for non-promoted traces is now independent of component-matrix parsing
-- component-promotion threshold handling is now consistent between proof validation and matrix-current-level validation
-- projection output writes are centralized in `projection-writer.mjs`
+- versioned signal snapshots are now published under `.tmp/<lane>-wave-launcher/signals/`
+- starter repos now include `skills/signal-hygiene/`, `scripts/wave-status.sh`, and `scripts/wave-watch.sh`
+- the runtime injects signal-state plus signal-ack paths into long-running agent and resident-orchestrator prompts
+- `completed` and `failed` now override stale feedback or coordination wakeups in agent signal state
+- wrapper scripts now treat `failed` as terminal with exit `40`
 
 ### Required repo changes
 
-None for wave shape, config keys, or CLI usage.
+Usually none if the repo did not copy starter scripts, operator docs, or skill bundles.
 
-### Recommended checks
+### Strongly recommended sync
 
-1. Re-run `pnpm exec wave doctor`.
-2. Re-run `pnpm exec wave launch --lane main --dry-run --no-dashboard`.
-3. If your repo copied starter architecture docs or starter skills, sync them so local runbooks stop describing the older split projection behavior.
-4. If you keep historical trace fixtures, replay at least one contradiction-blocked trace and one promoted-component trace after the upgrade.
+If the repo copied starter surface, sync:
 
-## Upgrading From `0.8.0`-`0.8.2` To `0.8.4`
+- `skills/signal-hygiene/`
+- `scripts/wave-status.sh`
+- `scripts/wave-watch.sh`
+- `docs/guides/signal-wrappers.md`
+- `docs/guides/terminal-surfaces.md`
+- `docs/reference/cli-reference.md`
+- `docs/reference/skills.md`
+- `docs/plans/current-state.md`
+- `docs/plans/end-state-architecture.md`
+- `docs/plans/wave-orchestrator.md`
+
+### Validation focus
+
+- confirm any existing shell automation treats wrapper exit `40` as terminal failure
+- if the repo uses long-running watchers, confirm they can write the ack file where the prompt tells them to
+- reroute one targeted feedback or coordination request and confirm the resident signal version changes even when the signal kind stays the same
+
+## Upgrading From `0.8.4` To `0.8.6`
+
+### What changed
+
+- `0.8.5` added the optional `design` worker role plus the `role-design` and `tui-design` starter bundles
+- design stewards can now be docs-first or explicit hybrid design stewards
+- `0.8.6` adds signal-driven waiting, `signal-hygiene`, and the seeded wrapper scripts
+
+### Required repo changes
+
+None if your repo does not use design stewards, long-running watcher agents, or copied starter scripts.
+
+### Strongly recommended sync
+
+If your repo copied starter prompts, skills, or authoring docs, sync:
+
+- `docs/agents/wave-design-role.md`
+- `skills/role-design/`
+- `skills/tui-design/`
+- `skills/signal-hygiene/`
+- `scripts/wave-status.sh`
+- `scripts/wave-watch.sh`
+- `docs/guides/author-and-run-waves.md`
+- `docs/guides/signal-wrappers.md`
+- `docs/guides/planner.md`
+- `docs/reference/skills.md`
+- `docs/reference/sample-waves.md`
+
+If your repo copied starter config defaults, also sync the `designRolePromptPath`, `skills.byRole.design`, and `design-pass` profile entries.
+
+### Validation focus
+
+- the design packet path resolves inside the repo
+- design runs before implementation
+- implementation does not start until every design packet is `ready-for-implementation`
+- hybrid design stewards rejoin implementation when they explicitly own code
+- long-running prompts receive signal-state and ack paths when the repo uses the new waiting model
+
+## Upgrading From `0.8.3` To `0.8.6`
+
+This is the most common one-step package upgrade path.
+
+### What changed across that range
+
+- `0.8.4` tightened contradiction replay, component-promotion threshold handling, and projection persistence boundaries
+- `0.8.5` ships the `design` worker role, the `role-design` and `tui-design` starter bundles, and the hybrid design-steward runtime model as part of the published package
+- `0.8.6` adds versioned signal snapshots, `signal-hygiene`, prompt-injected signal ack loops, and the seeded operator wrappers
+- current operator and planner docs now describe the shipped surface directly instead of splitting behavior between a published package and newer `main`-only additions
+
+### Required repo changes
+
+Usually none if the repo does not copy starter prompts, skills, planning docs, or wrapper scripts.
+
+### Strongly recommended sync
+
+If the repo copied starter surface, sync:
+
+- `docs/agents/wave-design-role.md`
+- `skills/role-design/`
+- `skills/tui-design/`
+- `skills/signal-hygiene/`
+- `scripts/wave-status.sh`
+- `scripts/wave-watch.sh`
+- `docs/guides/author-and-run-waves.md`
+- `docs/guides/signal-wrappers.md`
+- `docs/guides/planner.md`
+- `docs/reference/skills.md`
+- `docs/reference/sample-waves.md`
+- `docs/plans/current-state.md`
+- `docs/plans/wave-orchestrator.md`
+- `docs/plans/end-state-architecture.md`
+
+If the repo copied starter `wave.config.json` defaults, also sync:
+
+- `roles.designRolePromptPath`
+- `skills.byRole.design`
+- `executors.profiles.design-pass`
+
+### Validation focus
+
+- confirm contradiction-blocked replay cases still compare cleanly if the repo keeps replay fixtures
+- if the repo uses design stewards, confirm packet-only design waves still block implementation until `ready-for-implementation`
+- 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
 
-Treat this as one upgrade to the current surface.
+## Upgrading From `0.8.0`-`0.8.4` To `0.8.6`
+
+Treat this as one move to the current `0.8.6` surface.
 
 ### What changed across that range
 
-- completed-wave `wave control status` projection hardened in `0.8.2`
-- human-input reconciliation and ad-hoc `--run <id>` context hardening landed in `0.8.3`
-- contradiction replay, component-threshold consistency, and projection-writer centralization landed in `0.8.4`
+- completed-wave control projections hardened
+- human-input reconciliation and continuation repair landed
+- contradiction replay and component-threshold handling were tightened
+- projection persistence centralized under `projection-writer.mjs`
+- the design-role surface is now shipped instead of living only on source `main`
+- versioned signal snapshots, wrapper scripts, and long-running signal ack loops are now part of the shipped operator surface
 
 ### Required repo changes
 
-Usually none for config shape.
+Usually none for core config shape.
 
 ### Strongly recommended sync
 
-If your repo copied upstream starter docs or skills, sync:
+If your repo copied starter docs or skills, sync:
 
-- the current operator runbook and architecture docs
-- the launcher and orchestrator role prompts
-- the relevant runtime skills and closure-role starter skills
+- current operator runbook and architecture docs
+- planner starter corpus
+- design-role starter prompt and skill bundles
+- signal-wrapper starter scripts and docs
+- any repo-local docs that still describe design as “main only” or “future”
 
 ### Validation focus
 
 - check that completed waves do not show stale blockers through `wave control status`
 - answer at least one human-feedback ticket in a test lane and confirm the linked clarification or escalation chain closes cleanly
-- replay one contradiction-blocked trace if your repo relies on trace-based regression checks
+- replay one contradiction-blocked trace if your repo relies on replay regression coverage
+- 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.4`
+## Upgrading From `0.6.x` Or `0.7.x` To `0.8.6`
 
 This is the main migration path for older adopted repos.
 
 ### Behavioral changes you must account for
 
 - `wave control` is the preferred operator surface for status, rerun, proof, and telemetry work
-- `cont-QA` and optional `cont-EVAL` remain distinct closure roles; older overloaded evaluator language should be removed
-- planner corpus files are now treated as required starter surface for repos that use planner workflows
-- live closure depends on validated result envelopes plus canonical state, not only older summary-era behavior
-- control-plane state, reducer state, and replay are now first-class runtime surfaces, not optional internals
+- `cont-QA` and optional `cont-EVAL` are distinct closure roles
+- planner starter files are now treated as required repo-owned surface when the repo uses planner workflows
+- live closure depends on validated result envelopes plus canonical state
+- control-plane state, reducer state, and replay are first-class runtime surfaces
+- optional design stewards are now a supported authored shape
+- signal-driven long-running watchers are now a supported operator shape
 
 ### Required repo changes
 
-1. Remove or rename any legacy `evaluator` role/config terminology to `cont-QA`.
+1. Remove or rename legacy `evaluator` terminology to `cont-QA`.
 2. Keep `A0` as the final closure owner and add `E0` only when the wave needs eval-driven tuning.
 3. Add wave-level `## Eval targets` whenever `cont-EVAL` is present.
 4. Sync the planner starter corpus if the repo uses `wave project` or `wave draft`:
@@ -160,7 +372,9 @@ This is the main migration path for older adopted repos.
    - `docs/context7/planner-agent/`
    - `docs/reference/wave-planning-lessons.md`
    - the `planner-agentic` entry in `docs/context7/bundles.json`
-5. Review any repo-owned docs or internal runbooks that still describe one overloaded evaluator role, marker-era closure, or pre-control-plane retry/proof workflow.
+5. Review any repo-owned docs or runbooks that still describe summary-era closure, pre-control-plane retry or proof behavior, or a single overloaded evaluator role.
+6. If the repo wants design stewards, sync the design starter surface listed above and update local authoring docs accordingly.
+7. If the repo wants signal-driven long-running watchers or shell automation, sync `skills/signal-hygiene/`, `scripts/wave-status.sh`, `scripts/wave-watch.sh`, and the wrapper docs before relying on local polling scripts.
 
 ### Additional validation
 
@@ -172,9 +386,9 @@ pnpm exec wave control rerun get --lane main --wave 0 --json
 pnpm exec wave control proof get --lane main --wave 0 --json
 ```
 
-If your repo carries proof-first waves, verify that required proof artifacts are still present locally and not only in historical summaries.
+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.4`
+## Upgrading From `0.5.x` Or Earlier To `0.8.6`
 
 Do not treat this as a tiny patch bump.
 
@@ -183,7 +397,8 @@ Do not treat this as a tiny patch bump.
 1. Read [docs/reference/migration-0.2-to-0.5.md](../reference/migration-0.2-to-0.5.md) first if the repo still looks pre-`0.5`.
 2. Run `pnpm exec wave init --adopt-existing` on a branch so the workspace records install state without overwriting repo-owned material.
 3. Move the repo onto the `0.6.x` and later surface using the section above.
-4. Re-run the full validation checklist before any live executor run.
+4. Sync the planner corpus and, if needed, the design starter surface plus the signal-wrapper starter surface.
+5. Re-run the full validation checklist before any live executor run.
 
 ### Why
 
@@ -194,14 +409,13 @@ Older repos often differ in:
 - runtime config keys
 - planner starter corpus
 - proof and retry operator surfaces
+- wrapper and signal-monitoring expectations
 - generated state layout under `.tmp/`
 
 Trying to jump directly with ad hoc edits usually leaves hidden drift in prompts, docs, or config.
 
 ## Repo-Owned Files To Audit During Any Upgrade
 
-These are the highest-value files to check when a repo copied starter surface instead of reading from the package.
-
 ### Prompts and skills
 
 - `docs/agents/*.md`
@@ -215,14 +429,17 @@ These are the highest-value files to check when a repo copied starter surface in
 - `docs/plans/wave-orchestrator.md`
 - `docs/plans/end-state-architecture.md`
 - `docs/plans/migration.md`
+- `docs/guides/signal-wrappers.md`
 - `docs/reference/cli-reference.md`
 - `docs/reference/wave-control.md`
 - `docs/reference/sample-waves.md`
+- `docs/reference/skills.md`
 
 ### Config and wave contracts
 
 - `wave.config.json`
 - `docs/plans/waves/*.md`
+- `docs/plans/waves/specs/*.json`
 - `docs/evals/benchmark-catalog.json`
 - component-cutover matrix files under `docs/plans/`
 
@@ -234,6 +451,8 @@ Use this exact sequence unless your repo has a better repo-specific smoke suite.
 pnpm exec wave doctor --json
 pnpm exec wave launch --lane main --dry-run --no-dashboard
 pnpm exec wave control status --lane main --wave 0 --json
+scripts/wave-status.sh --lane main --wave 0
+scripts/wave-watch.sh --lane main --wave 0 --until-change --refresh-ms 500
 pnpm exec wave coord show --lane main --wave 0 --dry-run --json
 pnpm exec wave coord inbox --lane main --wave 0 --agent A1 --dry-run
 ```
@@ -254,22 +473,29 @@ For repos that depend on replay parity, replay at least:
 
 ### `wave doctor` fails after the upgrade
 
-- check whether the repo is missing planner starter surface it previously copied
+- check whether the repo is missing copied planner starter surface
 - check whether old `evaluator` naming is still present in config or prompts
-- check whether wave files now declare closure roles or eval targets inconsistently with the current runtime
+- check whether local docs still describe unpublished main-branch behavior instead of the current package surface
+- if the repo uses hybrid design stewards, check that each one still owns a design packet path and any required implementation-contract fields
 
 ### A live lane looks blocked after the bump
 
 - use `wave control status --lane <lane> --wave <n> --json`
-- confirm whether the blocker is canonical coordination, dependency, proof, or human-input state
-- do not trust old generated markdown alone
+- confirm whether the blocker is canonical coordination, dependency, proof, human-input, design-gate, or signal-ready state
+- do not trust generated markdown alone
+
+### External automation hangs after the upgrade
+
+- confirm your wrapper loop treats exit `40` as terminal failure
+- confirm `wave-watch.sh --until-change` expects exit `30` only for non-terminal signal changes
+- if a long-running agent never wakes, inspect its ack file under `.tmp/<lane>-wave-launcher/signals/wave-<n>/acks/`
 
 ### Replay differs from old expectations
 
 - verify whether the trace declares promoted components
-- verify whether the repo relied on pre-`0.8.4` component-threshold behavior
 - compare `storedOutcome.gateSnapshot` against recomputed replay output before changing live policy
+- if the repo copied local replay docs, update them to the current reducer, envelope, and signal model
 
 ## Summary
 
-`0.8.4` does not introduce a new authoring model. It hardens replay, makes component-promotion thresholds behave consistently, and finishes the projection-writer ownership boundary. 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, and runbooks so they describe the runtime the package now ships.
+The current `0.8.6` surface keeps the same authority-set and phase-engine architecture, but it now ships both the design-role starter surface and the signal-driven long-running-agent starter surface as part of the published package. For most repos already on `0.8.x`, the upgrade is package bump plus validation. For older adopted repos, the real work is syncing repo-owned prompts, skills, planner corpus, wrapper scripts, and runbooks so they describe the runtime the package now ships.

package/docs/plans/wave-orchestrator.md

@@ -19,7 +19,7 @@ The live runtime is organized around explicit modules:
 - `launcher.mjs`
   Thin orchestrator for CLI parsing, launcher lock handling, wave iteration, and engine sequencing.
 - `implementation-engine.mjs`
-  Chooses initial or retry implementation fan-out.
+  Chooses initial or retry fan-out, including optional design-first passes before code-owning implementation.
 - `derived-state-engine.mjs`
   Computes shared summary, inbox, assignment, dependency, ledger, docs queue, and integration or security projection payloads from canonical state.
 - `gate-engine.mjs`
@@ -41,6 +41,7 @@ The live runtime is organized around explicit modules:
 - supports transient ad-hoc runs from `.wave/adhoc/runs/` on the same runtime substrate
 - fans a wave out into one session per `## Agent ...` section
 - supports standing role imports from `docs/agents/*.md`
+- supports optional pre-implementation design stewards that publish design packets before code-owning implementation starts
 - seeds a coordination log, generated board, compiled shared summary, and per-agent inboxes
 - derives a per-wave ledger, security summary, docs queue, integration summary, and versioned per-attempt trace bundle
 - versions the runtime JSON surfaces that operators and replay tooling consume, including manifests, dashboards, relaunch plans, assignment snapshots, dependency snapshots, and run-state
@@ -52,6 +53,7 @@ The live runtime is organized around explicit modules:
 - can retry rate-limited `codex`, `claude`, and `opencode` launches with per-agent exponential backoff via `--agent-rate-limit-*`
 - supports a file-backed human feedback queue
 - performs a closure sweep so optional `cont-EVAL`, optional security review, integration, documentation, and cont-QA gates reflect final landed state through the wave's effective closure-role bindings
+- treats design packets as a first-class pre-implementation gate when a wave declares `design` workers
 - rebuilds contradiction blockers from canonical control-plane events during replay and materializes human-blocked waves as `clarifying` plus blocked `waveState`
 
 ## Main Commands
@@ -75,6 +77,8 @@ The live runtime is organized around explicit modules:
 - `pnpm exec wave feedback list --lane main --pending`
 - `pnpm exec wave control status --lane main --wave 0 --json`
 - `pnpm exec wave control status --lane main --wave 0 --agent A1 --json`
+- `scripts/wave-status.sh --lane main --wave 0 --agent A1`
+- `scripts/wave-watch.sh --lane main --wave 0 --agent A1 --until-change --refresh-ms 500`
 - `pnpm exec wave coord inbox --lane main --wave 0 --agent A1 --dry-run`
 - `pnpm exec wave control task create --lane main --wave 0 --agent A1 --kind blocker --summary "Need repository decision"`
 - `pnpm exec wave control task act reassign --lane main --wave 0 --id <task-id> --to A2`
@@ -89,7 +93,7 @@ The live runtime is organized around explicit modules:
 
 ## Configuration
 
-- `wave.config.json` controls docs roots, shared plan docs, role prompts, validation thresholds, executor defaults, executor profiles, per-lane runtime policy, skill attachment policy, component-cutover matrix paths, capability-routing preferences, Context7 bundle-index location, and the optional `waveControl` telemetry section. The starter config also wires the optional security reviewer prompt at `docs/agents/wave-security-role.md` and the `security-review` executor profile.
+- `wave.config.json` controls docs roots, shared plan docs, role prompts, validation thresholds, executor defaults, executor profiles, per-lane runtime policy, skill attachment policy, component-cutover matrix paths, capability-routing preferences, Context7 bundle-index location, and the optional `waveControl` telemetry section. The starter config also wires the optional security reviewer prompt at `docs/agents/wave-security-role.md`, the optional design steward prompt at `docs/agents/wave-design-role.md`, plus the `security-review` and `design-pass` executor profiles.
 - `docs/context7/bundles.json` controls allowed external library bundles and lane defaults.
 - `docs/evals/README.md` explains how to author delegated versus pinned `## Eval targets`, including the coordination-oriented benchmark families.
 - `docs/reference/live-proof-waves.md` explains how to author proof-first `pilot-live` and higher-maturity waves with `### Proof artifacts`, sticky executors, and operator command capture.
@@ -113,7 +117,7 @@ The live runtime is organized around explicit modules:
 - Starter bundles in this repo cover:
   - core Wave coordination and repo coding rules
   - runtime packs for Codex, Claude, OpenCode, and local execution
-  - role packs for implementation, `cont-EVAL`, security review, integration, documentation, cont-QA, infra, deploy, research, and planner work
+  - role packs for design, implementation, `cont-EVAL`, security review, integration, documentation, cont-QA, infra, deploy, research, and planner work
   - deploy and environment packs for Railway, Docker Compose, Kubernetes, SSH/manual rollout, and generic custom deploys
   - explicit provider packs for GitHub release flow and AWS norms when a wave or lane wants to attach them
 
@@ -162,6 +166,7 @@ pnpm exec wave launch --lane main --start-wave 0 --end-wave 0 --executor codex -
 - `wave control rerun request|get|clear` manages targeted rerun intent under `.tmp/<lane>-wave-launcher/control-plane/` and projects compatible retry overrides under `.tmp/<lane>-wave-launcher/control/`, including selected agents, reuse selectors, invalidated components, and clear or preserve reuse lists.
 - `wave control proof register|get|supersede|revoke` manages authoritative proof bundles in the same control-plane log and projects compatible proof registries under `.tmp/<lane>-wave-launcher/proof/`.
 - `wave control telemetry status|flush` inspects and delivers the local Wave Control event queue. Pass `--no-telemetry` on `wave launch` to disable event publication for a single run.
+- `scripts/wave-status.sh` and `scripts/wave-watch.sh` are thin wrapper readers over `wave control status --json` for shell automation and long-running watcher loops. Use [guides/signal-wrappers.md](../guides/signal-wrappers.md) for the exit-code and ack-loop contract.
 - `wave coord render` regenerates the markdown board projection from the canonical coordination log.
 - `wave coord inbox` writes the compiled shared summary plus the selected agent inbox.
 
@@ -257,6 +262,8 @@ pnpm exec wave changelog --since-installed
   Canonical append-only JSONL log of operator tasks, rerun requests, proof bundles, attempt lifecycle, contradictions, facts, and human-input events. This is the canonical lifecycle state for `wave control`. Telemetry queue lives under `control-plane/telemetry/`.
 - result envelopes: `.tmp/<lane>-wave-launcher/results/`
   Attempt-scoped immutable structured result snapshots used by reducer, gate, retry, and replay flows.
+- design packets: `docs/plans/waves/design/`
+  Repo-owned authored outputs from optional design stewards. These are not runtime state, but the validated packet path is referenced by summaries, envelopes, reducer state, and traces.
 - proof registries: `.tmp/<lane>-wave-launcher/proof/`
   Projected from control-plane state for compatibility. Operator-registered authoritative proof bundles that feed integration, cont-QA, and replay.
 - retry overrides: `.tmp/<lane>-wave-launcher/control/`
@@ -320,6 +327,12 @@ The launcher entrypoint in `scripts/wave-orchestrator/launcher.mjs` now acts as
 - `## Deploy environments` lets the wave declare named deployment targets. The default deploy environment kind is also used for deploy-kind skill attachment.
 - Lane runtime policy can assign a default executor by role even when the wave omits `### Executor`.
 - Use `### Role prompts` for standing-role imports from `docs/agents/*.md`.
+- Optional design stewards are declared by importing `docs/agents/wave-design-role.md` on a worker that owns a design packet.
+- A design steward must own at least one design packet path, usually `docs/plans/waves/design/wave-<n>-<agentId>.md`.
+- Design stewards are docs/spec-only by default. Keep source-code ownership on implementation agents unless the wave explicitly chooses otherwise.
+- If the wave explicitly gives a design steward implementation-owned paths, that same agent becomes a hybrid design steward: it runs the packet pass first, then rejoins implementation and must satisfy the normal implementation proof contract.
+- Design stewards that own terminal UX, dashboards, or other operator-surface work should add `tui-design` in `### Skills`.
+- Design readiness requires one final structured marker: `[wave-design] state=<ready-for-implementation|needs-clarification|blocked> decisions=<n> assumptions=<n> open_questions=<n> detail=<short-note>`. Hybrid design stewards re-emit that marker during the later implementation pass so the latest envelope stays self-contained.
 - Optional security review is declared by importing `docs/agents/wave-security-role.md` on a report-owning reviewer agent. The starter planner uses a report path under `.tmp/<lane>-wave-launcher/security/` and the `security-review` executor profile.
 - A security reviewer must own at least one security report path. Any owned `.md` or `.txt` path containing `security` is accepted by the validator.
 - Security reviewers are report-only by default. They should route fixes to the owning implementation agent instead of taking over product-code ownership.