@chllming/wave-orchestration 0.8.3 → 0.8.5

package/CHANGELOG.md

@@ -1,6 +1,41 @@
 # Changelog
 
-## Unreleased
+## 0.8.5 - 2026-03-25
+
+### Added
+
+- Shipped the optional `design` worker role as a first-class release surface instead of a main-branch-only addition, including the standing prompt in `docs/agents/wave-design-role.md`, the `role-design` skill bundle, and the `tui-design` reference bundle for terminal or operator-surface work.
+- Added support for hybrid design stewards: design agents stay docs-first by default, but waves can now explicitly give them implementation ownership so the same agent runs a design pass first and then rejoins the implementation fan-out with normal proof obligations.
+- Added regression coverage for hybrid design validation, prompt shaping, local-executor marker emission, reducer task splitting, and post-design implementation fan-out.
+
+### Changed
+
+- Updated README, current-state notes, planner and authoring guides, sample-wave docs, skills reference, and architecture docs so they all describe the shipped `0.8.5` surface instead of distinguishing `0.8.4` from unpublished main-branch behavior.
+- Rewrote the migration guide as a practical upgrade guide for fresh adoption plus upgrades from `0.8.4`, `0.8.0`-`0.8.4`, `0.6.x`-`0.7.x`, and `0.5.x` or earlier, with explicit repo-owned starter-surface sync guidance and concrete validation steps.
+
+### Fixed And Hardened
+
+- Design-aware validation, gates, retry or resume planning, reducer state, task materialization, and result-envelope projection now agree on the same hybrid-design contract instead of treating all design agents as permanently report-only.
+- Hybrid design prompts now switch cleanly between packet-first design work and implementation follow-through, and local-executor smoke behavior now emits both `[wave-design]` and implementation proof markers when that second pass is active.
+
+## 0.8.4 - 2026-03-25
+
+### Changed
+
+- Updated the shipped package metadata, release manifest, README, migration guide, current-state notes, sample-wave docs, and npm publishing runbook to advertise `0.8.4` as the current release surface.
+- Rewrote the operator migration guide so it now covers fresh adoption plus upgrades from `0.8.3`, `0.8.0`-`0.8.2`, `0.6.x`-`0.7.x`, and `0.5.x` or earlier with explicit repo-owned surface sync guidance.
+- Clarified the README and architecture docs so `derived-state-engine.mjs` is described as compute-only and `projection-writer.mjs` as the projection persistence boundary.
+
+### Fixed And Hardened
+
+- Hermetic contradiction replay no longer depends on component-matrix parsing when a trace does not declare promoted components.
+- `requireComponentPromotionsFromWave` now gates both component-promotion proof validation and component-matrix current-level validation consistently across live and replay paths.
+- Projection persistence is now centralized under `projection-writer.mjs`, including dashboards, traces, ledgers, docs queues, summaries, inboxes, assignment snapshots, dependency snapshots, and board projections.
+
+### Testing And Validation
+
+- Added regression coverage for the projection-writer persistence boundary and for component-matrix short-circuiting when no promotions are declared.
+- Re-ran the full Vitest suite, `wave doctor --json`, and `wave launch --lane main --dry-run --no-dashboard`.
 
 ## 0.8.3 - 2026-03-24
 

package/README.md

@@ -28,8 +28,32 @@ The framework does three things:
 1. Define shared docs plus `docs/plans/waves/wave-<n>.md` files, or generate them with `wave draft`.
 2. Run `wave launch --dry-run` to validate the wave and materialize prompts, shared summaries, inboxes, dashboards, and executor previews before any live execution.
 3. During live execution, implementation agents write claims, evidence, requests, and decisions into the canonical coordination log instead of relying on ad hoc terminal narration.
-4. The reducer and derived-state engines materialize blackboard projections from the canonical authority set: rolling board, shared summary, per-agent inboxes, ledger, docs queue, dependency views, and integration summaries.
-5. Closure runs only when the integrated state is ready: optional `cont-EVAL` (`E0`), optional security review, integration (`A8`), documentation (`A9`), and `cont-QA` (`A0`).
+4. Optional design workers can run before code-owning implementation workers. When present, they publish design packets under `docs/plans/waves/design/` and implementation does not start until those packets are `ready-for-implementation`.
+5. Design stewards are docs-first by default, but a wave may explicitly give one source-code ownership. That hybrid design steward runs a design pass first, then rejoins the implementation fan-out with normal proof obligations.
+6. The reducer and derived-state engines materialize blackboard projections from the canonical authority set: rolling board, shared summary, per-agent inboxes, ledger, docs queue, dependency views, and integration summaries. Helper-assignment blocking, retry target selection, and resume planning read from reducer state during live runs.
+7. The derived-state engine computes projection payloads and the projection writer persists them, so dashboards, traces, board projections, summaries, inboxes, ledgers, docs queues, and integration or security summaries all flow through one projection boundary.
+8. Live closure is result-envelope-first. Optional `cont-EVAL`, optional security review, integration, documentation, and `cont-QA` evaluate validated envelopes plus canonical state through the wave's effective closure-role bindings, with starter defaults (`E0`, security reviewer, `A8`, `A9`, `A0`) filling gaps only when a wave does not override them.
+
+## Runtime Modules
+
+- `launcher.mjs`
+  Thin orchestrator: parses args, acquires the launcher lock, and sequences the engines.
+- `implementation-engine.mjs`
+  Selects the design-first or implementation fan-out for a wave or retry attempt.
+- `derived-state-engine.mjs`
+  Computes shared summary, inboxes, assignments, dependency views, ledger, docs queue, and integration/security projection payloads from canonical state.
+- `gate-engine.mjs`
+  Evaluates implementation, component, assignment, dependency, clarification, `cont-EVAL`, security, integration, documentation, and `cont-QA` gates.
+- `retry-engine.mjs`
+  Plans reducer-driven resume and retry targets, reusable work, executor fallback changes, and blocking conditions.
+- `closure-engine.mjs`
+  Sequences the staged closure sweep from implementation proof through final `cont-QA`.
+- `wave-state-reducer.mjs`
+  Rebuilds deterministic wave state from canonical inputs for live queries and replay.
+- `session-supervisor.mjs`
+  Owns launches, waits, tmux sessions, lock handling, resident orchestrator sessions, and observed `wave_run`, `attempt`, and `agent_run` lifecycle facts.
+- `projection-writer.mjs`
+  Persists dashboards, traces, summaries, inboxes, board projections, assignment/dependency snapshots, ledgers, docs queues, and integration/security summaries.
 
 ## Architecture Surfaces
 
@@ -79,18 +103,18 @@ Wave is built to mitigate those failures with a canonical authority set, generat
 
 Current release:
 
-- `@chllming/wave-orchestration@0.8.3`
-- Release tag: [`v0.8.3`](https://github.com/chllming/agent-wave-orchestrator/releases/tag/v0.8.3)
+- `@chllming/wave-orchestration@0.8.5`
+- Release tag: [`v0.8.5`](https://github.com/chllming/agent-wave-orchestrator/releases/tag/v0.8.5)
 - Public install path: npmjs
 - Authenticated fallback: GitHub Packages
 
-Highlights in `0.8.3`:
+Highlights in `0.8.5`:
 
-- Answering a human-feedback request now reconciles linked clarification, escalation, and helper-assignment state back into the canonical coordination log instead of only updating the feedback JSON.
-- `wave feedback respond --run <id>` now applies that same reconciliation and safe continuation flow to ad-hoc runs instead of writing into the roadmap lane state root.
-- When a stranded wave can safely continue after the answer arrives and no attempt is still running, Wave writes a one-shot continuation request automatically.
-- The completed-wave control-status hardening from `0.8.2` remains intact.
-- Upgrade and operator docs now cover the full `0.8.3` package surface end to end.
+- The optional `design` worker role is now part of the shipped release surface, including `docs/agents/wave-design-role.md`, `skills/role-design/`, and `skills/tui-design/`.
+- Design stewards are docs-first by default, but waves can now explicitly assign code ownership and get a hybrid two-pass flow: design packet first, implementation follow-through second.
+- Gates, retry or resume planning, reducer state, prompts, local-executor smoke behavior, and result envelopes now all agree on that hybrid design-steward contract.
+- The migration guide is now a practical upgrade document for fresh adoption plus upgrades from `0.8.3`, `0.8.4`, `0.8.0`-`0.8.4`, `0.6.x`-`0.7.x`, and `0.5.x` or earlier.
+- Release docs, sample waves, current-state notes, and publishing instructions now point at the `0.8.5` surface.
 
 Requirements:
 
@@ -119,6 +143,15 @@ pnpm exec wave init --adopt-existing
 
 Fresh init also seeds a starter `skills/` library plus `docs/evals/benchmark-catalog.json`. The launcher projects those skill bundles into Codex, Claude, OpenCode, and local executor overlays after the final runtime for each agent is resolved, and waves that include `cont-EVAL` can declare `## Eval targets` against that catalog.
 
+The starter surface includes:
+
+- `docs/agents/wave-design-role.md`
+- `skills/role-design/`
+- `skills/tui-design/` for terminal and operator-surface design work
+- `wave.config.json` defaults for `roles.designRolePromptPath`, `skills.byRole.design`, and the `design-pass` executor profile
+
+Interactive `wave draft` scaffolds the docs-first design-steward path. If you want a hybrid design steward, author that wave explicitly or use an agentic planner payload that gives the same design agent implementation-owned paths plus the normal implementation contract sections.
+
 When runtime launch commands detect a newer npmjs release, Wave prints a non-blocking update notice on stderr. The fast path is `pnpm exec wave self-update`, which updates the dependency, prints the changelog delta, and then records the workspace upgrade report.
 
 ## Common Commands
@@ -145,6 +178,19 @@ pnpm exec wave autonomous --lane main --executor codex --codex-sandbox danger-fu
 pnpm exec wave self-update
 ```
 
+## CLI Surfaces
+
+- `wave launch` and `wave autonomous`
+  Live execution, dry-run validation, retry cadence, terminal surfaces, and orchestrator options.
+- `wave control`
+  Read-only live status plus operator task, rerun, proof, and telemetry control surfaces.
+- `wave coord` and `wave dep`
+  Coordination-log and cross-lane dependency utilities. `wave control` is the preferred operator surface; `wave coord` remains useful for direct log inspection and rendering.
+- `wave project`, `wave draft`, and `wave adhoc`
+  Planner defaults, authored wave generation, and transient operator-driven runs on the same runtime.
+- `wave init`, `wave doctor`, `wave upgrade`, and `wave self-update`
+  Workspace setup, validation, adoption, and package lifecycle.
+
 ## Develop This Package
 
 ```bash
@@ -178,12 +224,15 @@ codex mcp list
 - [docs/concepts/runtime-agnostic-orchestration.md](./docs/concepts/runtime-agnostic-orchestration.md): how one orchestration substrate spans Claude, Codex, OpenCode, and local execution
 - [docs/concepts/context7-vs-skills.md](./docs/concepts/context7-vs-skills.md): compiled context, external truth, and repo-owned operating knowledge
 - [docs/guides/planner.md](./docs/guides/planner.md): `wave project` and `wave draft` workflow
+- [docs/agents/wave-design-role.md](./docs/agents/wave-design-role.md): standing prompt for the optional pre-implementation design steward
 - [docs/guides/terminal-surfaces.md](./docs/guides/terminal-surfaces.md): tmux, VS Code terminal registry, and dry-run surfaces
 - [docs/reference/sample-waves.md](./docs/reference/sample-waves.md): showcase-first authored waves, including a high-fidelity repo-landed rollout example
+- [docs/plans/examples/wave-example-design-handoff.md](./docs/plans/examples/wave-example-design-handoff.md): optional design-steward example that hands a validated design packet to downstream implementation owners
 - [docs/plans/examples/wave-example-rollout-fidelity.md](./docs/plans/examples/wave-example-rollout-fidelity.md): concrete example of what good wave fidelity looks like for a narrow, closure-ready outcome
 - [docs/reference/cli-reference.md](./docs/reference/cli-reference.md): complete CLI syntax for all commands and flags
+- [docs/plans/end-state-architecture.md](./docs/plans/end-state-architecture.md): canonical runtime architecture, engine boundaries, and artifact ownership
 - [docs/plans/wave-orchestrator.md](./docs/plans/wave-orchestrator.md): operator runbook
-- [docs/plans/architecture-hardening-migration.md](./docs/plans/architecture-hardening-migration.md): staged cutover from the transitional launcher-centric runtime to the authority-set / reducer / phase-engine architecture
+- [docs/plans/architecture-hardening-migration.md](./docs/plans/architecture-hardening-migration.md): historical record of the completed architecture hardening stages
 - [docs/plans/context7-wave-orchestrator.md](./docs/plans/context7-wave-orchestrator.md): Context7 setup and bundle authoring
 - [docs/reference/runtime-config/README.md](./docs/reference/runtime-config/README.md): executor, runtime, and skill-projection configuration
 - [docs/reference/wave-control.md](./docs/reference/wave-control.md): local-first telemetry contract and Railway control-plane model

package/docs/README.md

@@ -35,12 +35,18 @@ The useful path is journey-first:
   Read [concepts/context7-vs-skills.md](./concepts/context7-vs-skills.md) for the compiled-context model: shared summary, inboxes, project defaults, skills, Context7, and runtime overlays.
 - Drafting or revising waves:
   Read [guides/author-and-run-waves.md](./guides/author-and-run-waves.md), then use [plans/wave-orchestrator.md](./plans/wave-orchestrator.md) as the operator runbook.
+- 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.5` 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.
 - 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`.
-- Tracking the architecture hardening cutover:
-  Read [plans/architecture-hardening-migration.md](./plans/architecture-hardening-migration.md) for the staged migration from launcher-centric decisions to reducer and phase-engine ownership.
+- 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:
+  Read [reference/cli-reference.md](./reference/cli-reference.md) for the shipped commands, flags, and compatibility surfaces.
+- Want the historical architecture migration notes:
+  Read [plans/architecture-hardening-migration.md](./plans/architecture-hardening-migration.md) for the completed cutover record.
 - Looking for concrete example waves:
   Read [reference/sample-waves.md](./reference/sample-waves.md) for showcase-first examples that demonstrate the current authored wave surface.
 - Release notes and shipped deltas:

package/docs/agents/wave-design-role.md

@@ -0,0 +1,47 @@
+---
+title: "Wave Design Role"
+summary: "Standing prompt for an optional pre-implementation design steward that produces a design packet and explicit implementation handoff."
+---
+
+# Wave Design Role
+
+Use this prompt when an agent should act as the design steward for a wave.
+
+## Standing prompt
+
+```text
+You are the wave design steward for the current wave.
+
+Your job is to produce an implementation-ready design packet before code-owning implementation work begins. You are report-first and docs/spec-owned by default. Do not silently expand into broad coding work unless the wave explicitly assigns it.
+If the wave explicitly gives you source-code ownership, expect a hybrid two-pass contract: design packet first, then a later implementation pass for those owned files.
+
+Operating rules:
+- Re-read the compiled shared summary, your inbox, the generated wave board projection, and any earlier packets before major decisions.
+- Turn ambiguity into explicit decisions, assumptions, and exact open questions.
+- Keep interface impacts concrete: name exact files, APIs, schema fields, CLI flags, contracts, and ownership changes.
+- If the wave touches terminal UX, dashboards, or other operator surfaces, use `skills/tui-design/references/tui-design.md` as the deep heuristic reference.
+- Keep operator surfaces thin by design: ask for reducer or projection truth instead of inventing UI-local state or hiding system uncertainty behind polish.
+- Prefer exact observations tied to concrete surfaces, state transitions, interaction paths, and missing projection-backed affordances over generic design commentary.
+- Prefer a narrow, actionable handoff over a long architecture essay.
+- If the wave needs a human choice or unresolved upstream answer before coding, fail closed and say so directly.
+- Route code changes back to implementation owners unless the wave explicitly gives you source-code ownership.
+
+What you must do:
+- leave one design packet with these sections in order:
+  `Problem`
+  `Constraints`
+  `Decisions`
+  `Assumptions`
+  `Open Questions`
+  `Interface Impacts`
+  `Validation Plan`
+  `Implementation Handoff`
+- make the `Implementation Handoff` section concrete enough that implementation owners can start without re-deriving the same design
+- emit one final structured marker:
+  `[wave-design] state=<ready-for-implementation|needs-clarification|blocked> decisions=<n> assumptions=<n> open_questions=<n> detail=<short-note>`
+- when you later rejoin implementation as a hybrid design steward, keep the design packet current and re-emit `[wave-design]` alongside the normal implementation proof markers
+
+Use `ready-for-implementation` only when the design packet is sufficient for downstream implementation owners to proceed.
+Use `needs-clarification` when a specific unresolved question should stop implementation until it is answered.
+Use `blocked` only when the wave cannot safely continue because the design packet found a fundamental blocker.
+```

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

@@ -20,7 +20,7 @@ It is not just a prompt file. A wave is a bounded slice of repository work with:
 - Wave
   One numbered work package inside a lane, usually stored as `docs/plans/waves/wave-<n>.md`.
 - Agent
-  One role inside the wave, such as implementation, `cont-EVAL`, security review, integration, documentation, cont-QA, infra, or deploy.
+  One role inside the wave, such as design, implementation, `cont-EVAL`, security review, integration, documentation, cont-QA, infra, or deploy.
 - Attempt
   One execution pass of a wave. A wave can have multiple attempts due to retries or fallback.
 - Closure
@@ -89,7 +89,7 @@ Inside each agent block, the important sections are:
 
 ## Standard Roles
 
-The starter runtime expects three standard closure roles plus up to two optional review specialists:
+The starter runtime ships with three default closure roles plus optional specialists. A wave may override the role ids, but the closure semantics stay the same:
 
 - `A8`
   Integration steward
@@ -101,6 +101,8 @@ The starter runtime expects three standard closure roles plus up to two optional
   Optional `cont-EVAL` for iterative benchmark or output tuning; report-only by default, implementation-owning only when explicitly assigned non-report files
 - `A7`
   Optional security reviewer; report-only by default and used to publish a threat-model-first security review before integration closure
+- `D1` or another custom id
+  Optional design steward; report-first and docs/spec-owned by default, used to publish a design packet before code-owning implementation fans out. If the wave explicitly gives that same agent source-code ownership, it becomes a hybrid design steward that rejoins the later implementation fan-out.
 
 Implementation or specialist agents own the actual work slices. Closure roles do not replace implementation ownership; they decide whether the combined result is closure-ready. `cont-EVAL` is the one hybrid role: most waves keep it report-only, but human-authored waves may assign explicit tuning files to `E0`, in which case it must satisfy both implementation proof and eval proof.
 
@@ -109,11 +111,12 @@ Implementation or specialist agents own the actual work slices. Closure roles do
 1. Author or draft the wave.
 2. Run `wave launch --dry-run --no-dashboard`.
 3. The launcher parses the wave, resolves executors and skills, rebuilds reducer state, and materializes operator surfaces.
-4. A live run launches implementation agents first when implementation work remains.
-5. Agents write structured coordination events instead of relying on ad hoc terminal output.
-6. The reducer, gate engine, and retry or closure engines evaluate implementation contracts, promoted-component proof, helper assignments, dependencies, contradictions, and clarification state.
-7. If implementation is ready, closure runs in order: optional `cont-EVAL`, optional security review, integration, documentation, then cont-QA.
-8. The attempt is captured in per-wave traces, ledgers, inboxes, summaries, and copied artifacts.
+4. A live run launches design agents first when the wave declares them.
+5. Code-owning implementation agents start only after every design packet is `ready-for-implementation`; hybrid design stewards rejoin that implementation fan-out once the design gate clears.
+6. Agents write structured coordination events instead of relying on ad hoc terminal output.
+7. The reducer, gate engine, and retry or closure engines evaluate design readiness, implementation contracts, promoted-component proof, helper assignments, dependencies, contradictions, and clarification state.
+8. If implementation is ready, closure runs in order: optional `cont-EVAL`, optional security review, integration, documentation, then cont-QA.
+9. The attempt is captured in per-wave traces, ledgers, inboxes, summaries, and copied artifacts.
 
 ## Runtime And Operating Posture
 
@@ -170,6 +173,7 @@ That is why switching an agent between Codex, Claude, or OpenCode does not requi
 A wave is not done because an agent said so. It is done only when the runtime surfaces agree:
 
 - implementation exit contracts pass
+- if present, design packets are complete and every design worker reports `ready-for-implementation`
 - required deliverables exist and stay within ownership boundaries
 - required proof artifacts exist when the wave declares proof-first live evidence
 - required component proof and promotions pass

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

@@ -43,12 +43,35 @@ When you review the generated wave, tighten the parts the planner cannot fully i
 - file ownership
 - validation commands
 - proof artifacts
+- whether the wave needs an optional pre-implementation design steward
 - `cont-EVAL` targets when needed
 - security review expectations when needed
 - explicit `### Skills` only where defaults are not enough
 
 If you want examples of denser hand-authored waves, read [docs/reference/sample-waves.md](../reference/sample-waves.md).
 
+## 2a. Add A Design Steward Only When It Actually Helps
+
+Use the optional `design` role when the wave needs a concrete handoff packet before coding starts, not just more prose.
+
+Good fits:
+
+- architecture-heavy or interface-heavy changes
+- 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.5` is:
+
+- import `docs/agents/wave-design-role.md`
+- own one packet such as `docs/plans/waves/design/wave-<n>-<agentId>.md`
+- keep that agent docs/spec-only by default
+- add explicit `### Skills` such as `tui-design` when the packet covers terminal UX, dashboards, or other operator surfaces
+- end with `[wave-design] state=<ready-for-implementation|needs-clarification|blocked> decisions=<n> assumptions=<n> open_questions=<n> detail=<short-note>`
+
+When a wave includes one or more design agents, the runtime runs them before code-owning implementation agents. Implementation does not start until every design packet is `ready-for-implementation`. `needs-clarification` and `blocked` behave like normal wave blockers.
+
+If a wave explicitly gives a design steward source-code ownership, that agent becomes a hybrid design steward. The runtime still runs its design pass first, then includes the same agent in the later implementation fan-out with normal proof obligations. Interactive `wave draft` scaffolds the docs-first default; use manual edits or an agentic planner payload when you want the hybrid path.
+
 ## 3. Choose The Execution Posture
 
 Every wave should be authored with an explicit operating posture in mind:
@@ -115,6 +138,7 @@ Useful flags:
 
 A wave is not done when an implementation agent says it is done. Closure depends on the canonical authority set, typed result state, and the combined runtime projections:
 
+- if present, design packets are complete and `ready-for-implementation` before code-owning work starts
 - implementation contracts pass
 - required deliverables exist
 - proof artifacts exist when the wave requires them

package/docs/guides/planner.md

@@ -6,6 +6,8 @@ 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.5` package already includes the optional `design` worker role for pre-implementation design packets. This guide calls out where that affects drafting.
+
 ## What Ships Today
 
 - `wave project setup`
@@ -14,6 +16,7 @@ It reduces repeated setup questions, stores project defaults, and generates wave
 - agentic `wave draft --agentic --task "..."`
 - planner run review via `wave draft --show-run <run-id>`
 - explicit materialization via `wave draft --apply-run <run-id>`
+- worker role kinds including optional `design`
 - persistent project memory in `.wave/project-profile.json`
 - transient planner packets in `.wave/planner/runs/<run-id>/`
 - planner-run Context7 injection via `planner.agentic.context7Bundle`
@@ -95,6 +98,24 @@ Supported templates today:
 - `infra`
 - `release`
 
+Supported worker role kinds today:
+
+- `design`
+- `implementation`
+- `qa`
+- `infra`
+- `deploy`
+- `research`
+- `security`
+
+The interactive draft flow now offers `design` as a first-class worker role. Agentic planner payloads also accept `workerAgents[].roleKind = "design"`.
+
+`design` uses the `design-pass` executor profile by default and scaffolds the docs-first packet path before coding starts. The normal starter packet path is:
+
+- `docs/plans/waves/design/wave-<n>-<agentId>.md`
+
+If you want a hybrid design steward, keep the same design packet path but explicitly add implementation-owned paths and the normal implementation contract sections in the authored wave or agentic planner payload. Interactive draft does not ask a separate hybrid-design question yet; it stays on the docs-first default.
+
 Interactive draft writes canonical waves immediately:
 
 - `docs/plans/waves/specs/wave-<n>.json`
@@ -125,6 +146,7 @@ The draft flow asks for structured inputs such as:
 - deploy environments in scope
 - component promotions and target levels
 - worker count and worker roles
+- whether a wave needs a pre-implementation design steward
 - executor profiles
 - file ownership
 - Context7 defaults and per-agent bundles
@@ -133,6 +155,27 @@ The draft flow asks for structured inputs such as:
 
 That gives you a wave that is much closer to launch-ready than a blank markdown template.
 
+## When To Use `design`
+
+Use a design worker when the wave is heavy on:
+
+- architecture or sequencing decisions
+- interface or contract changes across multiple owners
+- ambiguous requirements that should become explicit assumptions and open questions
+- decision-lineage that downstream implementers should not have to rediscover
+
+Do not use a design worker just because the wave is large. If the task is straightforward code change plus validation, normal implementation agents are enough.
+
+A design worker should usually:
+
+- import `docs/agents/wave-design-role.md`
+- own one design packet under `docs/plans/waves/design/`
+- stay docs/spec-only unless the wave explicitly assigns code ownership
+- add `tui-design` in `### Skills` when the packet owns terminal UX, dashboards, or other operator surfaces
+- emit a final `[wave-design] state=<ready-for-implementation|needs-clarification|blocked> ...` marker
+
+If the wave does explicitly assign code ownership, the same design agent becomes a hybrid design steward: it runs the design pass first, then rejoins implementation with the normal implementation proof contract while still keeping the packet current and re-emitting `[wave-design]`.
+
 ## Planner And Skills
 
 The planner does not auto-discover every possible skill bundle yet, but it supports explicit per-agent `### Skills` in the rendered output.
@@ -169,6 +212,7 @@ If you want concrete authored examples after the planner baseline, see [docs/ref
 - Treat `### Deliverables` and `### Proof artifacts` as part of the plan contract, not optional polish.
 - Keep `docs/context7/planner-agent/` in sync with the selected planning cache slice before publishing the planner bundle to Context7.
 - Add explicit `### Skills` only when the lane, role, runtime, and deploy-kind defaults are not enough.
+- Use `design` when you need a reusable handoff packet; keep straightforward implementation slices on `implementation`.
 - Use the component matrix as a planning contract, not just a reporting surface.
 - Prefer updating the project profile when the same answers recur across waves.
 - Use [docs/reference/sample-waves.md](../reference/sample-waves.md) when you want examples of denser human-authored waves that combine multiple modern surfaces such as `cont-EVAL`, delegated benchmark families, or proof-first live validation.

package/docs/plans/architecture-hardening-migration.md

@@ -1,6 +1,13 @@
 # Architecture Hardening Migration
 
-This document is the staged cutover plan from the legacy launcher-centric runtime to the end-state architecture described in [end-state-architecture.md](./end-state-architecture.md).
+This document is the historical record of the completed cutover from the legacy launcher-centric runtime to the architecture described in [end-state-architecture.md](./end-state-architecture.md).
+
+Current status at this head:
+
+- Stage 1 is complete: reducer snapshots persist machine-readable shadow diffs for high-value decision slices.
+- Stage 2 is complete: live helper-assignment blocking, retry target selection, and resume planning consume reducer state.
+- Stage 3 and Stage 4 are complete in runtime behavior: live gate and closure decisions are envelope-authoritative, and the launcher sequences explicit engine surfaces instead of recomputing those policies inline.
+- Stage 5 is complete for live runtime behavior: compatibility parsing remains only for replay, reconcile, and historical trace materialization, and the old `launcher-*` engine module names have been removed from the live runtime tree.
 
 The target model is fixed:
 

package/docs/plans/current-state.md

@@ -1,7 +1,7 @@
 # Current State
 
-- The starter workspace in this source repo reflects the `0.8.3` package release surface.
-- The staged architecture cutover from launcher-centric decisions to reducer and phase-engine ownership is tracked in `docs/plans/architecture-hardening-migration.md`.
+- The published package is `0.8.5`, and that release now includes the optional pre-implementation `design` worker role plus the `role-design` and `tui-design` starter bundles.
+- 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/`.
 - 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.
@@ -26,9 +26,10 @@
   - lane config can attach skills by base, role, runtime, and deploy kind
   - wave agents can add explicit `### Skills`
   - runtime projections are generated for Codex, Claude, OpenCode, and local execution
+  - the starter surface includes `skills/role-design/`, `skills/tui-design/`, `roles.designRolePromptPath`, and `executors.profiles.design-pass`
 - The runtime now includes:
   - a canonical authority set built from wave definitions, coordination JSONL logs, and control-plane JSONL events
-  - immutable attempt-scoped result envelopes for structured role outcomes
+  - immutable attempt-scoped result envelopes for structured role outcomes under `.tmp/<lane>-wave-launcher/results/wave-<n>/attempt-<a>/<agent>.json`
   - a generated markdown board projection
   - compiled shared summaries and per-agent inboxes
   - active live-wave orchestration refresh that keeps summaries, inboxes, clarification triage, and dashboard coordination metrics current while agents are still running
@@ -37,17 +38,27 @@
   - explicit integration summaries with actionable claim, interface, proof, docs, and deploy-risk evidence
   - versioned runtime artifact contracts for manifests, dashboards, relaunch plans, helper-assignment snapshots, dependency snapshots, and run-state
   - append-only `run-state.json` history with per-wave current state, compatibility `completedWaves`, and causal completion or blocker evidence
-  - hermetic `traceVersion: 2` per-attempt trace bundles with copied launched-agent summaries, copied component matrices for promoted waves, a hashed `outcome.json` replay baseline, run metadata, and cumulative quality metrics
+  - hermetic `traceVersion: 2` per-attempt trace bundles with copied launched-agent summaries, copied component matrices for promoted waves only, a hashed `outcome.json` replay baseline, run metadata, and cumulative quality metrics
   - an internal, read-only replay validator for trace bundles, with legacy `traceVersion: 1` bundles kept in best-effort warning mode
   - orchestrator-first clarification triage plus human escalation artifacts
   - answered human-feedback responses that reconcile canonical coordination state, helper assignments, and safe continuation intent even when the launcher is no longer active
   - optional `--resident-orchestrator` support for a long-running, non-owning orchestrator session during live waves
   - persisted relaunch plans under `.tmp/<lane>-wave-launcher/status/` so targeted retry intent can survive a launcher restart
-  - a canonical control-plane event log under `.tmp/<lane>-wave-launcher/control-plane/` that records operator tasks, rerun requests, proof bundles, attempt lifecycle, and human-input events as append-only JSONL; `wave control` materializes state from this log
+  - a canonical control-plane event log under `.tmp/<lane>-wave-launcher/control-plane/` that records operator tasks, rerun requests, proof bundles, contradictions, facts, human-input workflow, and observed `wave_run`, `attempt`, and `agent_run` lifecycle events as append-only JSONL; `wave control` materializes state from this log
   - operator-applied retry overrides projected to `.tmp/<lane>-wave-launcher/control/` for compatibility with selected reruns, explicit reuse selectors, reuse clearing or preservation, and explicit resume targets
   - authoritative proof registries projected to `.tmp/<lane>-wave-launcher/proof/` for compatibility, while preserving proof bundle lifecycle state so revoked or superseded operator evidence cannot keep satisfying closure
   - optional Wave Control telemetry under `.tmp/<lane>-wave-launcher/control-plane/telemetry/` for local-first, best-effort reporting to the Railway-hosted analysis plane
-  - reducer-driven live state snapshots plus a launcher entrypoint that is being hardened toward thin orchestration while preserving the existing CLI surface
+  - reducer-driven live state snapshots plus persisted machine-readable shadow diffs for helper-assignment, blocker, contradiction, closure, and retry slices
+  - reducer-authoritative helper-assignment blocking, retry target selection, and resume planning, with live gate and closure reads now driven from validated result envelopes
+  - optional design agents that publish validated design packets under `docs/plans/waves/design/wave-<n>-<agent>.md`, gate implementation through `designGate`, and run before code-owning implementation agents
+  - hybrid design stewards that stay docs-first by default but can explicitly own source-code slices, rejoin the implementation fan-out after the design pass, and satisfy both the design packet contract and normal implementation proof
+  - hermetic replay that reconstructs contradiction-driven blockers from bundled control-plane events
+  - contradiction replay for non-promoted traces that no longer depends on copied component-matrix parsing
+  - consistent `requireComponentPromotionsFromWave` threshold handling across both component-promotion proof validation and component-matrix current-level validation
+  - `projection-writer.mjs` as the single persistence layer for projection outputs such as dashboards, traces, generated board projections, compiled summaries and inboxes, helper-assignment and dependency snapshots, docs queues, ledgers, and integration or security summaries; clarification-triage workflow artifacts remain workflow-owned
+  - reducer phases that materialize open human-feedback and escalation barriers as `clarifying` with blocked `waveState`, instead of flattening them into generic `running`
+  - replay, reconcile, and trace materialization compatibility adapters that can still synthesize envelopes from legacy summaries or marker-era artifacts without deciding live correctness
+  - a launcher entrypoint that now sequences explicit engine modules plus the session supervisor, with the old `launcher-*` engine module names removed from the live runtime tree
 - Runtime executor support now includes:
   - Codex `exec` profile, inline config, search, image, add-dir, JSON, and ephemeral flags
   - Claude settings overlay merging for inline settings and hooks
@@ -67,7 +78,8 @@
   - open capability-targeted requests become explicit helper assignments
   - helper assignments are written into coordination state, the ledger, summaries, and traces
   - helper assignments remain blocking until the linked follow-up resolves
-- Closure now runs in staged order: implementation and proof, then optional `E0` cont-EVAL, then optional security review, then `A8` integration, then `A9` documentation, then `A0` cont-QA.
+- Waves with a `design` worker role now run that design pass before code-owning implementation starts; implementation resumes only after every design packet is `ready-for-implementation`.
+- Closure now runs in staged order through the wave's effective closure roles: implementation and proof, then optional `cont-EVAL`, then optional security review, then integration, then documentation, then `cont-QA`. Starter defaults remain `E0`, security reviewer, `A8`, `A9`, and `A0` when a wave does not override them.
 - `E0` is hybrid: planner-generated waves keep it report-only, while hand-authored waves may assign explicit tuning files and thereby make `E0` participate in implementation proof gating.
 - Live closure is strict: `cont-EVAL` must prove the declared eval contract with exact target and benchmark ids, and `cont-QA` must provide both final verdict and final gate artifacts. Legacy evaluator-era shapes remain replay-only compatibility inputs.
 - Proof-centric waves can now declare `### Proof artifacts`, and implementation proof validation can require those machine-visible local artifacts in addition to deliverables and structured proof markers.