@chllming/wave-orchestration 0.8.4 → 0.8.5

package/docs/plans/migration.md

@@ -1,157 +1,287 @@
 # 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.5` 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.5` Changes
 
-There are no new CLI flags or wave-file section requirements in `0.8.4`.
+`0.8.5` ships a new authored and runtime surface, not just a patch-level hardening change.
+
+The biggest additions are:
+
+- the optional `design` worker role is now part of the published package surface
+- starter design bundles now ship in `docs/agents/wave-design-role.md`, `skills/role-design/`, and `skills/tui-design/`
+- design stewards are docs-first by default, but a wave may explicitly give one implementation ownership
+- hybrid design stewards now run in two phases:
+  - design packet first
+  - implementation follow-through second
+- gates, retry or resume planning, reducer state, prompts, local smoke execution, and result envelopes now all agree on that hybrid-design contract
+
+There are no new top-level CLI commands for `0.8.5`.
 
 ## 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/*`
+- `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
+
+If your repo never copied a starter file, do not invent migration work for it. The installed package already ships the runtime behavior.
 
-Use this flow before the version-specific sections below.
+## Safe Upgrade Flow For Any Existing Repo
 
-### 1. Upgrade When The Lane Is Idle
+### 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.5` 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/` when your repo wants the terminal or operator-surface design reference
 - `docs/context7/planner-agent/`
 - `docs/reference/wave-planning-lessons.md`
 - `docs/plans/current-state.md`
 - `docs/plans/end-state-architecture.md`
 - `docs/plans/wave-orchestrator.md`
 - `docs/plans/migration.md`
+- `docs/reference/skills.md`
+- `docs/reference/sample-waves.md`
+
+If your repo copied starter `wave.config.json` defaults, also sync the design-role entries:
 
-If your repo never copied those starter files, do not invent migration work. The installed package already carries the new runtime behavior.
+- `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
 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.5` Design-Steward Model
+
+This is the main new behavior in the current `0.8.5` surface.
+
+### Docs-first design stewards
+
+Default 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> ...`
+
+### Hybrid design stewards
+
+If the wave explicitly assigns non-packet ownership to a design agent, that agent becomes a hybrid design steward.
+
+The runtime now 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.
+
+### Planner note
+
+The interactive `wave draft` flow now 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:
+
+- edit the drafted wave manually
+- or use 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.3` To `0.8.5`
+
+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
+- 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, or planning docs.
+
+### Strongly recommended sync
+
+If the repo copied starter surface, sync:
+
+- `docs/agents/wave-design-role.md`
+- `skills/role-design/`
+- `skills/tui-design/`
+- `docs/guides/author-and-run-waves.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
+
+## Upgrading From `0.8.4` To `0.8.5`
 
-This is the smallest migration.
+This is the smallest upgrade that still changes authored behavior.
 
 ### 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`
+- the optional `design` worker role is now part of the published package surface
+- `role-design` and `tui-design` starter bundles now ship with the release
+- design stewards can now be docs-first or explicit hybrid design stewards
+- prompts, gates, retry or resume planning, reducer state, and local smoke execution now honor that hybrid-design contract consistently
 
 ### Required repo changes
 
-None for wave shape, config keys, or CLI usage.
+None if your repo does not use design stewards.
+
+### 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/`
+- `docs/guides/author-and-run-waves.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.
 
-### Recommended checks
+### Validation focus
+
+If the repo uses design stewards, dry-run at least one wave that proves:
 
-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.
+- 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
+- downstream implementation prompts read the same-wave design packet context
 
-## Upgrading From `0.8.0`-`0.8.2` To `0.8.4`
+## Upgrading From `0.8.0`-`0.8.4` To `0.8.5`
 
-Treat this as one upgrade to the current surface.
+Treat this as one move to the current `0.8.5` 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`
 
 ### 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
+- 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
 
-## 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.5`
 
 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
 
 ### 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 +290,8 @@ 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.
 
 ### Additional validation
 
@@ -172,9 +303,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.5`
 
 Do not treat this as a tiny patch bump.
 
@@ -183,7 +314,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.
+5. Re-run the full validation checklist before any live executor run.
 
 ### Why
 
@@ -200,8 +332,6 @@ Trying to jump directly with ad hoc edits usually leaves hidden drift in prompts
 
 ## 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`
@@ -218,11 +348,13 @@ These are the highest-value files to check when a repo copied starter surface in
 - `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/`
 
@@ -254,22 +386,23 @@ 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, or design-gate state
+- do not trust generated markdown alone
 
 ### 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 and envelope 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.5` surface keeps the same authority-set and phase-engine architecture, but it now ships the design-role starter surface and the hybrid design-steward runtime model 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, 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
@@ -89,7 +91,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 +115,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
 
@@ -257,6 +259,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 +324,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.

package/docs/reference/cli-reference.md

@@ -534,6 +534,18 @@ wave draft --show-run <run-id>
 wave draft --apply-run <run-id>
 ```
 
+Interactive draft currently offers worker role kinds:
+
+- `design`
+- `implementation`
+- `qa`
+- `infra`
+- `deploy`
+- `research`
+- `security`
+
+Agentic planner payloads also accept `workerAgents[].roleKind = "design"`. The shipped `0.8.5` surface uses `design-pass` as the default executor profile for that role and typically assigns a packet path like `docs/plans/waves/design/wave-<n>-<agentId>.md`. Interactive draft scaffolds the docs-first default; hybrid design stewards are authored by explicitly adding implementation-owned paths and the normal implementation contract sections.
+
 ## Ad-Hoc Task Commands
 
 **Plan and run ad-hoc tasks:**

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.4` release procedure publishes through a repository Actions secret named `NPM_TOKEN`.
+The current `0.8.5` 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.4`.
+5. Push the release commit and release tag, for example `v0.8.5`.
 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/sample-waves.md

@@ -1,11 +1,11 @@
 ---
 title: "Sample Waves"
-summary: "Showcase-first sample waves that demonstrate the current 0.8.4 Wave surface."
+summary: "Showcase-first sample waves that demonstrate the shipped 0.8.5 authored surface, including the optional design-role path."
 ---
 
 # Sample Waves
 
-This guide points to showcase-first sample waves that demonstrate the current `0.8.4` authored Wave surface.
+This guide points to showcase-first sample waves that demonstrate the shipped `0.8.5` 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,10 @@ 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.4` 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.5` 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.
 
 ## What These Examples Teach
 
@@ -35,10 +38,11 @@ The examples are intentionally denser than typical production waves. Their job i
 - sticky retry for proof-bearing owners
 - deploy environments and provider-skill examples
 - infra and deploy-verifier specialist slices
+- optional pre-implementation design packets and design-to-implementation handoff
 
 ## Feature Coverage Map
 
-Together these samples cover the main surfaces added or hardened for `0.8.4`:
+Together these samples cover the main surfaces added or hardened through `0.8.5`:
 
 - repo-landed maturity discipline and anti-overclaim framing
 - explicit shared-plan closure for future-wave safety
@@ -56,6 +60,7 @@ Together these samples cover the main surfaces added or hardened for `0.8.4`:
 - proof-first live-wave prompts
 - deploy environments and deploy-kind-aware skills
 - integration, documentation, and cont-QA closure-role structure
+- optional `design` worker role and `design-pass` executor profile
 
 ## When To Copy Literally Vs Adapt
 
@@ -76,6 +81,7 @@ Adapt more aggressively when:
 ## How This Example Maps To Other Docs
 
 - Use [docs/guides/planner.md](../guides/planner.md) for the planner-generated baseline, then use these samples to see how a human would enrich the generated draft for either repo-landed or proof-first work.
+- Use [Optional design-steward handoff wave](../plans/examples/wave-example-design-handoff.md) when the wave should start with a reusable design packet before implementation begins.
 - Use [docs/evals/README.md](../evals/README.md) with the full modern sample when you need to see delegated and pinned benchmark targets in a real wave.
 - Use [docs/reference/live-proof-waves.md](./live-proof-waves.md) with the full modern sample when you need proof-first authoring for `pilot-live` and above.
 - Use [docs/plans/wave-orchestrator.md](../plans/wave-orchestrator.md) for the operational runbook that explains how the launcher interprets these sections.
@@ -83,9 +89,10 @@ 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 surface.
-3. Read [docs/evals/README.md](../evals/README.md) if you want more background on benchmark target selection.
-4. Read [docs/reference/live-proof-waves.md](./live-proof-waves.md) if you want more detail on proof-first `pilot-live` authoring.
+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.5` 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.
 
 ## Why These Examples Live In `docs/plans/examples/`