@chllming/wave-orchestration 0.8.4 → 0.8.5

package/CHANGELOG.md

@@ -1,6 +1,22 @@
 # 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
 

package/README.md

@@ -28,16 +28,18 @@ 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. Helper-assignment blocking, retry target selection, and resume planning read from reducer state during live runs.
-5. 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.
-6. 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.
+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 implementation fan-out for a wave or retry attempt.
+  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`
@@ -101,18 +103,18 @@ Wave is built to mitigate those failures with a canonical authority set, generat
 
 Current release:
 
-- `@chllming/wave-orchestration@0.8.4`
-- Release tag: [`v0.8.4`](https://github.com/chllming/agent-wave-orchestrator/releases/tag/v0.8.4)
+- `@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.4`:
+Highlights in `0.8.5`:
 
-- Hermetic contradiction replay no longer depends on component-matrix parsing when the trace does not declare promoted components.
-- `requireComponentPromotionsFromWave` now gates both component-promotion proof validation and component-matrix current-level validation consistently in live and replay paths.
-- Projection persistence is now centralized under `projection-writer.mjs`, while `derived-state-engine.mjs` stays compute-only.
-- The migration guide now includes explicit upgrade guidance for `0.8.3`, `0.8.0`-`0.8.2`, `0.6.x`-`0.7.x`, and older starter repos instead of only a narrow point upgrade.
-- Release docs, sample waves, current-state notes, and npm publishing instructions now point at the `0.8.4` surface.
+- 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:
 
@@ -141,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
@@ -213,8 +224,10 @@ 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

package/docs/README.md

@@ -35,6 +35,8 @@ 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:

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 ships with three default closure roles plus up to two optional review specialists. A wave may override the role ids, but the closure semantics stay the same:
+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 ships with three default closure roles plus up to two option
   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/current-state.md

@@ -1,6 +1,6 @@
 # Current State
 
-- The starter workspace in this source repo reflects the `0.8.4` package release surface.
+- 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/`.
@@ -26,6 +26,7 @@
   - 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 under `.tmp/<lane>-wave-launcher/results/wave-<n>/attempt-<a>/<agent>.json`
@@ -49,6 +50,8 @@
   - 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 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
@@ -75,6 +78,7 @@
   - 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
+- 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.

package/docs/plans/end-state-architecture.md

@@ -1,6 +1,6 @@
 # End-State Architecture
 
-This document describes the canonical architecture for the current Wave runtime. It is the authoritative reference for the engine boundaries, canonical authority set, and artifact ownership model that the shipped code now follows.
+This document describes the canonical architecture for the current Wave runtime. It is the authoritative reference for the engine boundaries, canonical authority set, and artifact ownership model that the shipped `0.8.5` surface now follows.
 
 The thesis is unchanged: bounded waves, closure roles, proof artifacts, selective rerun, and delivery discipline. What changes is the internal authority model. The launcher stops being the decision engine and becomes a thin orchestrator that reads decisions from canonical state, sequences the engines, and delegates process work to the session supervisor.
 
@@ -48,6 +48,8 @@ The system uses **Model B: canonical authority set**, not a single event log. Th
 
 The reducer consumes all three canonical sources plus result envelopes to rebuild state. No other input is read for decision-making.
 
+Optional design packets live in repo-owned docs, usually under `docs/plans/waves/design/`. They are not canonical runtime state by themselves, but the validated packet path and final `design` result are captured in summaries, envelopes, reducer state, and traces.
+
 ---
 
 ## Module Architecture
@@ -87,6 +89,8 @@ implementation-engine.mjs  Drives the implementation phase
                            Outputs: run selections, launch requests,
                                     executor assignments,
                                     prompt construction requests
+                           Rule:    optional design workers run before
+                                    code-owning implementation workers
                            Does NOT output: agent_run.started, attempt.running
                            (those are observed facts written by the supervisor)
 
@@ -109,7 +113,7 @@ gate-engine.mjs            Evaluates all closure gates
                                     per-task owned_slice_proven verdicts
                            Does NOT write: gate events to control-plane
                            (the caller writes gate events after receiving verdicts)
-                           Gates:   implementation-proof, cont-eval, security,
+                           Gates:   design, implementation-proof, cont-eval, security,
                                     integration, documentation, cont-qa,
                                     component-matrix, assignment-barrier,
                                     dependency-barrier, clarification-barrier
@@ -198,6 +202,7 @@ launcher.mjs               Thin orchestrator
                               a. reducer.rebuild() → current state
                               b. retry-engine.plan() → retry decisions
                               c. implementation-engine.select() → run selections
+                                 (design-first when the wave declares design workers)
                               d. derived-state-engine.materialize() → derived payloads
                               e. supervisor.launch(run selections) → agent sessions
                                  (supervisor writes agent_run.started)