@chllming/wave-orchestration 0.8.4 → 0.8.6

package/docs/guides/signal-wrappers.md

@@ -0,0 +1,165 @@
+# Signal Wrappers And Long-Running Wake Loops
+
+Use this guide when you want shell-friendly monitoring, external automation hooks, or intentionally long-running agents that should wake only when the orchestrator publishes a new signal version.
+
+If you want the broader tmux or VS Code operator flow, read [terminal-surfaces.md](./terminal-surfaces.md). This page stays focused on the signal snapshots, wrapper scripts, and ack-loop contract.
+
+## What The Runtime Writes
+
+Wave now publishes versioned signal snapshots under:
+
+- `.tmp/<lane>-wave-launcher/signals/wave-<n>.json`
+  Wave-level signal for the whole wave.
+- `.tmp/<lane>-wave-launcher/signals/wave-<n>/<agentId>.json`
+  Per-agent signal state.
+- `.tmp/<lane>-wave-launcher/signals/wave-<n>/acks/<agentId>.json`
+  Per-agent acknowledgement file written by a long-running watcher after it observes a new signal version.
+
+The resident orchestrator uses the same pattern with `resident-orchestrator` as the agent id.
+
+Signal snapshots are derived projections, not canonical decision state. They are machine-friendly wake surfaces built from `wave control status --json`.
+
+## Signal Kinds
+
+The shipped signal vocabulary is:
+
+- `stable`
+- `waiting`
+- `feedback-requested`
+- `feedback-answered`
+- `coordination-action`
+- `resume-ready`
+- `completed`
+- `failed`
+
+`completed` and `failed` are terminal. Long-running watchers should stop waiting once either one appears.
+
+## Wrapper Scripts
+
+Starter repos now include two thin helper scripts:
+
+- `scripts/wave-status.sh`
+- `scripts/wave-watch.sh`
+
+They read `wave control status --json`. They do not recompute status independently.
+
+### `wave-status.sh`
+
+Examples:
+
+```bash
+scripts/wave-status.sh --lane main --wave 3
+scripts/wave-status.sh --lane main --wave 3 --agent A1
+scripts/wave-status.sh --lane main --wave 3 --agent A1 --json
+```
+
+Exit codes:
+
+- `0`
+  Terminal success (`signal=completed`)
+- `10`
+  Still active or waiting (`stable`, `waiting`, `feedback-answered`, `coordination-action`, `resume-ready`)
+- `20`
+  Input required (`signal=feedback-requested`)
+- `40`
+  Terminal failure (`signal=failed`)
+
+The printed machine line includes `signal`, `phase`, `status`, `version`, `blocking`, and `should_wake`.
+
+### `wave-watch.sh`
+
+Examples:
+
+```bash
+scripts/wave-watch.sh --lane main --wave 3 --agent A1 --follow
+scripts/wave-watch.sh --lane main --wave 3 --agent A1 --until-change --refresh-ms 500
+```
+
+Modes:
+
+- `--follow`
+  Keep polling until the signal becomes terminal or input-required.
+- `--until-change`
+  Exit as soon as the watched signal version changes.
+
+Exit codes:
+
+- `0`
+  Terminal success
+- `20`
+  Input required
+- `30`
+  The watched signal version changed, but the wave is still active
+- `40`
+  Terminal failure
+
+Use `--until-change` when an outer supervisor or CI job should re-enter only after a new signal is published.
+
+## Long-Running Agents
+
+For non-resident agents, opt in explicitly with:
+
+```md
+### Skills
+
+- signal-hygiene
+```
+
+That skill is only for intentionally long-running agents. Do not attach it to normal one-shot implementation agents.
+
+When `signal-hygiene` is active, the runtime injects two prompt-visible paths:
+
+- the signal-state JSON path
+- the signal-ack JSON path
+
+The watcher loop is:
+
+1. Read the signal state.
+2. Compare its `version` with the version already recorded in the ack file.
+3. If the version did not change, stay idle.
+4. If the version increased, write the ack file immediately.
+5. Re-read the inbox, shared summary, message board, and any referenced artifacts.
+6. Act once for that version.
+7. Stop entirely when the signal becomes `completed` or `failed`.
+
+Ack payload shape:
+
+```json
+{
+  "agentId": "A1",
+  "version": 4,
+  "signal": "coordination-action",
+  "observedAt": "2026-03-25T19:00:00.000Z"
+}
+```
+
+## Resident Orchestrator Behavior
+
+The resident orchestrator does not need the `signal-hygiene` skill. It always receives the same signal-state and ack-path contract when `--resident-orchestrator` is enabled.
+
+That lets the launcher know whether the resident monitor actually observed a reroute, feedback answer, or terminal state change.
+
+## External Automation Pattern
+
+Typical shell loop:
+
+```bash
+while true; do
+  scripts/wave-watch.sh --lane main --wave 3 --agent A1 --until-change --refresh-ms 500
+  code=$?
+  if [ "$code" -eq 0 ]; then
+    echo "wave completed"
+    break
+  fi
+  if [ "$code" -eq 20 ]; then
+    echo "human input required"
+    break
+  fi
+  if [ "$code" -eq 40 ]; then
+    echo "wave failed"
+    break
+  fi
+done
+```
+
+Use `wave control status --json` directly when you need the full structured payload. Use the wrapper scripts when you want stable exit codes and a single machine-readable line.

package/docs/guides/terminal-surfaces.md

@@ -78,6 +78,19 @@ Important flags:
 - Pair `--keep-sessions` with incident review or deep debugging, not as a default steady-state mode.
 - Pair `--no-dashboard` with scripted dry-runs or when the board and summaries are sufficient.
 
+## Operator Wrappers
+
+Starter repos now include two thin helper scripts:
+
+- `scripts/wave-status.sh`
+  Reads `wave control status --json`, prints a single machine-friendly line, and exits `0` for completed, `10` for waiting/running, `20` for input-required, and `40` for failed.
+- `scripts/wave-watch.sh`
+  Polls the same status JSON until the watched signal version changes. `--until-change` exits `30` when the signal changed but the wave is still active, and both follow mode and until-change mode terminate immediately with `40` on failed terminal signals.
+
+Both wrappers are convenience readers only. The canonical surface is the versioned signal projection under `.tmp/<lane>-wave-launcher/signals/`.
+
+For the full wrapper contract, long-running-agent ack loop, and external automation patterns, read [signal-wrappers.md](./signal-wrappers.md).
+
 ## Suggested Defaults
 
 - Local development:

package/docs/plans/context7-wave-orchestrator.md

@@ -34,11 +34,12 @@ pnpm context7:api-check
 ```
 
 4. Review [docs/context7/bundles.json](../context7/bundles.json) and trim it to the external libraries your repository actually uses.
+5. Prefer exact `libraryId` values. Use `libraryName` only during one-off discovery, then replace it with the pinned id returned by Context7 before committing the bundle.
 
 ## Planner Bundle
 
-The shipped bundle index includes `planner-agentic`, which expects a published
-Context7 library named `wave-planner-agentic`.
+The shipped bundle index includes `planner-agentic`, but it is intentionally a
+local-only placeholder by default.
 
 The source files for that library live under `docs/context7/planner-agent/`.
 Refresh that folder from the ignored agent-context cache with:
@@ -47,8 +48,8 @@ Refresh that folder from the ignored agent-context cache with:
 pnpm research:sync-planner-context7
 ```
 
-After you publish the folder to Context7, the agentic planner will prefetch that
-bundle through `planner.agentic.context7Bundle`.
+After you publish the folder to Context7, replace the placeholder bundle entry
+with the exact published `libraryId`. Do not commit a guessed `libraryName`.
 
 ## Resolution Order
 
@@ -59,7 +60,8 @@ bundle through `planner.agentic.context7Bundle`.
 
 ## Bundle Authoring
 
-Each bundle should be small and task-shaped. A bundle entry can name libraries by `libraryName` and optionally add a `queryHint` to keep fetched docs focused.
+Each bundle should be small and task-shaped. Prefer exact `libraryId` values and
+add a `queryHint` to keep fetched docs focused.
 
 Example:
 
@@ -70,11 +72,11 @@ Example:
       "description": "Node.js and TypeScript runtime docs.",
       "libraries": [
         {
-          "libraryName": "nodejs",
+          "libraryId": "/nodejs/node",
           "queryHint": "child processes, streams, filesystem, process lifecycle"
         },
         {
-          "libraryName": "typescript",
+          "libraryId": "/microsoft/typescript",
           "queryHint": "module resolution, declarations, compiler behavior"
         }
       ]
@@ -105,6 +107,20 @@ Agent-level override:
 - query: "TypeScript declarations and module resolution"
 ````
 
+## Making Attachment Explicit
+
+If you want Context7 attachment to be reviewable instead of implied, make all of
+these explicit:
+
+1. The wave or agent selects a concrete bundle id in `## Context7 defaults` or
+   `### Context7`.
+2. `docs/context7/bundles.json` pins the bundle's libraries by exact
+   `libraryId`, not a guessed `libraryName`.
+3. Placeholder bundles stay empty until the real published `libraryId` exists.
+4. `pnpm context7:api-check` succeeds against the committed ids.
+5. The launcher log shows `Context7 bundle <bundle-id> attached (...)` for the
+   run, or a fail-open warning if the API was unavailable.
+
 ## Injection
 
 When a bundle is active, the launcher injects:
@@ -150,3 +166,4 @@ Those inbox artifacts are repository-state summaries. Context7 stays reserved fo
 - Do not use Context7 for repository architecture, plan decisions, ownership rules, or internal contracts.
 - Prefer one active backend family in a bundle instead of mixing competing frameworks.
 - Keep queries specific enough that the prefetched block stays small and useful.
+- Run `pnpm context7:api-check` after editing bundle ids to verify every pinned library still resolves and returns promptable context.

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.6`, and that release now includes the optional pre-implementation `design` worker role, the `role-design`, `tui-design`, and `signal-hygiene` starter bundles, plus the seeded signal-wrapper scripts for long-running-agent and operator wait loops.
 - The canonical shipped runtime architecture is documented in `docs/plans/end-state-architecture.md`; historical cutover notes remain in `docs/plans/architecture-hardening-migration.md`.
 - The repository contains the published `@chllming/wave-orchestration` package plus the starter scaffold used by `wave init`.
 - The runtime is package-first and non-destructive for adopting repos: `wave init --adopt-existing` records existing repo-owned plans, waves, prompts, and config without overwriting them, and `wave upgrade` writes only `.wave/install-state.json` plus `.wave/upgrade-history/`.
@@ -26,11 +26,13 @@
   - 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/`, `skills/signal-hygiene/`, `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`
   - a generated markdown board projection
   - compiled shared summaries and per-agent inboxes
+  - canonical versioned signal projections under `.tmp/<lane>-wave-launcher/signals/` for waves, per-agent wake state, and resident-orchestrator acknowledgement loops
   - active live-wave orchestration refresh that keeps summaries, inboxes, clarification triage, and dashboard coordination metrics current while agents are still running
   - a per-wave ledger
   - docs queues
@@ -42,13 +44,16 @@
   - 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
+  - seeded operator wrappers `scripts/wave-status.sh` and `scripts/wave-watch.sh` that expose machine-friendly wait, completion, failure, and input-required status by reading `wave control status --json`
   - 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, 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
+  - 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, observed `wave_run`, `attempt`, and `agent_run` lifecycle events, plus `wave_signal` and `agent_signal` update 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 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 +80,9 @@
   - 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`.
+- Long-running non-resident agents can opt into `signal-hygiene` through explicit `### Skills`; that skill makes them wait on signal-version changes, acknowledge a new version through an ack file, and only then resume work.
+- Terminal signal state now dominates stale answered feedback or coordination wakeups, so `completed` and `failed` actually stop long-running watcher loops instead of leaving them on a non-terminal signal.
 - 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.6` 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.
 
@@ -41,13 +41,15 @@ The system uses **Model B: canonical authority set**, not a single event log. Th
 | Source | Kind | Authority Over |
 |--------|------|----------------|
 | Wave definitions (`docs/plans/waves/`) | Parsed declarations, read-only after parse | Goals, agent roles, component promotions, exit contracts, proof artifact requirements, eval targets, skill bindings |
-| Control-plane event log (`.tmp/<lane>-wave-launcher/control-plane/wave-<N>.jsonl`) | Append-only JSONL | Lifecycle state: tasks, attempts, proof bundles, rerun requests, gates, contradictions, facts, human inputs, wave runs, agent runs, artifacts, benchmarks, verifications, reviews |
+| Control-plane event log (`.tmp/<lane>-wave-launcher/control-plane/wave-<N>.jsonl`) | Append-only JSONL | Lifecycle state: tasks, attempts, proof bundles, rerun requests, gates, contradictions, facts, human inputs, wave runs, agent runs, signal updates, artifacts, benchmarks, verifications, reviews |
 | Coordination log (`.tmp/<lane>-wave-launcher/coordination/wave-<N>.jsonl`) | Append-only JSONL | Conversational/workflow state: requests, acks, claims, evidence, decisions, blockers, handoffs, clarifications, human feedback, escalations, orchestrator guidance, integration summaries |
 
-**Everything else is a projection.** Shared summaries, dashboards, inboxes, proof registries, retry overrides, relaunch plans, assignment snapshots, dependency snapshots, ledgers, docs queues, security summaries, integration summaries, markdown boards, and trace bundles are all derived from these three canonical sources plus immutable agent result envelopes.
+**Everything else is a projection.** Shared summaries, dashboards, inboxes, signal snapshots, proof registries, retry overrides, relaunch plans, assignment snapshots, dependency snapshots, ledgers, docs queues, security summaries, integration summaries, markdown boards, and trace bundles are all derived from these three canonical sources plus immutable agent result envelopes.
 
 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
@@ -149,7 +153,7 @@ wave-state-reducer.mjs     Rebuilds full wave state from canonical authority set
 
 The supervisor is the only module that interacts with the outside world: launching processes, managing terminals, and monitoring sessions. It reads decisions from phase engines and executes them. It is the only module that writes observed lifecycle events.
 
-The projection writer is the single module responsible for projection writes. Workflow-owned compatibility state, clarification triage, and canonical coordination/control-plane mutations stay in their own modules.
+`projection-writer.mjs` owns the operator-facing projection writes family: dashboards, traces, summaries, inboxes, ledgers, docs queues, board projections, and assignment or dependency snapshots. `signals.mjs` owns the separate versioned signal projections used by long-running agents and operator wrappers. Workflow-owned compatibility state, clarification triage, and canonical coordination/control-plane mutations stay in their own modules.
 
 ```
 session-supervisor.mjs     Launches and monitors agent sessions
@@ -184,6 +188,16 @@ projection-writer.mjs      Writes projection outputs
                            Rule:    never reads its own outputs,
                                     always writes atomically,
                                     labels every artifact with its class
+
+signals.mjs                Writes versioned signal projections
+                           Inputs:  materialized control status for a wave,
+                                    logical-agent state, feedback state
+                           Outputs: wave-level signal snapshot,
+                                    per-agent signal snapshots,
+                                    resident-orchestrator signal snapshot
+                           Rule:    versions snapshots only when the normalized
+                                    wake payload changes and tracks ack state
+                                    for long-running watcher loops
 ```
 
 ### Layer 4 — Launcher Orchestrator
@@ -198,6 +212,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)
@@ -559,6 +574,8 @@ Projections materialized from Class 1 and Class 2 sources. Can be deleted and re
 | Run state | `.tmp/<lane>-wave-launcher/run-state.json` | JSON |
 | Quality metrics | `.tmp/<lane>-wave-launcher/traces/wave-<N>/attempt-<A>/quality.json` | JSON |
 | Reducer snapshot | `.tmp/<lane>-wave-launcher/reducer/wave-<N>.json` | JSON |
+| Wave signal snapshot | `.tmp/<lane>-wave-launcher/signals/wave-<N>.json` | JSON |
+| Agent signal snapshot | `.tmp/<lane>-wave-launcher/signals/wave-<N>/<agentId>.json` | JSON |
 
 ### Class 4 — Human-Facing Projections
 

package/docs/plans/examples/wave-example-design-handoff.md

@@ -0,0 +1,262 @@
+# Wave 12 - Optional Design Steward Handoff
+
+This is a showcase-first sample wave for the shipped `design` worker role in `0.8.6`.
+
+This example demonstrates the docs-first design-steward path where a design packet is published before code-owning implementation begins.
+
+Use this shape when:
+
+- the task has interface or architecture ambiguity
+- multiple implementation owners need the same decisions and assumptions
+- you want explicit design lineage instead of re-deriving the same plan in each coding prompt
+
+If you want the hybrid design-steward variant instead, keep the same packet path but also assign that same design agent implementation-owned files plus the normal implementation contract sections. The runtime will then run the design pass first and include that same agent in the later implementation fan-out.
+
+**Commit message**: `Feat: add design packet before implementation fan-out`
+
+## Component promotions
+
+- api-boundary: repo-landed
+- runtime-integration: repo-landed
+
+## Context7 defaults
+
+- bundle: node-typescript
+- query: "Interface boundaries, migration sequencing, and implementation handoff patterns for repository work"
+
+## Agent A0: cont-QA
+
+### Role prompts
+
+- docs/agents/wave-cont-qa-role.md
+
+### Executor
+
+- profile: deep-review
+
+### Context7
+
+- bundle: none
+
+### Prompt
+
+```text
+Primary goal:
+- Judge whether the design packet, implementation slices, and closure evidence line up without hidden architectural drift.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/plans/current-state.md and docs/plans/migration.md.
+- Read docs/plans/waves/design/wave-12-D1.md.
+
+File ownership (only touch these paths):
+- docs/plans/waves/reviews/wave-12-cont-qa.md
+```
+
+## Agent A8: Integration Steward
+
+### Role prompts
+
+- docs/agents/wave-integration-role.md
+
+### Executor
+
+- profile: deep-review
+
+### Context7
+
+- bundle: none
+
+### Prompt
+
+```text
+Primary goal:
+- Reconcile the landed implementation against the design packet and the actual repo changes.
+
+Required context before coding:
+- Read docs/plans/current-state.md.
+- Read docs/plans/waves/design/wave-12-D1.md.
+
+File ownership (only touch these paths):
+- .tmp/main-wave-launcher/integration/wave-12.md
+- .tmp/main-wave-launcher/integration/wave-12.json
+```
+
+## Agent A9: Documentation Steward
+
+### Role prompts
+
+- docs/agents/wave-documentation-role.md
+
+### Executor
+
+- profile: docs-pass
+
+### Context7
+
+- bundle: none
+
+### Prompt
+
+```text
+Primary goal:
+- Keep the shared docs and migration notes aligned with the design packet and final implementation outcome.
+
+Required context before coding:
+- Read docs/plans/current-state.md.
+- Read docs/plans/migration.md.
+- Read docs/plans/waves/design/wave-12-D1.md.
+
+File ownership (only touch these paths):
+- docs/plans/current-state.md
+- docs/plans/migration.md
+```
+
+## Agent D1: Design Steward
+
+### Role prompts
+
+- docs/agents/wave-design-role.md
+
+### Executor
+
+- profile: design-pass
+
+### Context7
+
+- bundle: none
+
+### Skills
+
+- role-design
+
+Add `tui-design` here too when the design packet owns terminal UX, dashboards, or other operator-surface behavior. Omit it for generic API or migration design.
+
+### Capabilities
+
+- design
+- interface-handoff
+- decision-lineage
+
+### Prompt
+
+```text
+Primary goal:
+- Produce the implementation-ready design packet for the Wave 12 slice before coding starts.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/plans/current-state.md.
+- Read docs/plans/migration.md.
+
+Specific expectations:
+- make the implementation handoff concrete enough that A1 and A2 can start without re-deriving the same architecture
+- keep assumptions and open questions explicit
+- do not silently expand into source-code changes
+
+File ownership (only touch these paths):
+- docs/plans/waves/design/wave-12-D1.md
+```
+
+## Agent A1: API Boundary Update
+
+### Executor
+
+- profile: implement-fast
+
+### Context7
+
+- bundle: node-typescript
+- query: "API boundary refactors and compatibility-safe migration sequencing"
+
+### Skills
+
+- role-implementation
+- runtime-codex
+- repo-coding-rules
+
+### Components
+
+- api-boundary
+
+### Deliverables
+
+- scripts/wave-orchestrator/api-boundary.mjs
+- test/wave-orchestrator/api-boundary.test.ts
+
+### Exit contract
+
+- completion: integrated
+- durability: durable
+- proof: integration
+- doc-impact: none
+
+### Prompt
+
+```text
+Primary goal:
+- Land the API-boundary changes described in the Wave 12 design packet.
+
+Required context before coding:
+- Read docs/plans/waves/design/wave-12-D1.md before changing code.
+
+File ownership (only touch these paths):
+- scripts/wave-orchestrator/api-boundary.mjs
+- test/wave-orchestrator/api-boundary.test.ts
+```
+
+## Agent A2: Runtime Integration Update
+
+### Executor
+
+- profile: implement-fast
+
+### Context7
+
+- bundle: node-typescript
+- query: "Runtime integration updates and handoff-safe staged migration"
+
+### Skills
+
+- role-implementation
+- runtime-codex
+- repo-coding-rules
+
+### Components
+
+- runtime-integration
+
+### Deliverables
+
+- scripts/wave-orchestrator/runtime-integration.mjs
+- test/wave-orchestrator/runtime-integration.test.ts
+
+### Exit contract
+
+- completion: integrated
+- durability: durable
+- proof: integration
+- doc-impact: none
+
+### Prompt
+
+```text
+Primary goal:
+- Land the runtime integration changes described in the Wave 12 design packet.
+
+Required context before coding:
+- Read docs/plans/waves/design/wave-12-D1.md before changing code.
+
+File ownership (only touch these paths):
+- scripts/wave-orchestrator/runtime-integration.mjs
+- test/wave-orchestrator/runtime-integration.test.ts
+```
+
+## Why This Example Exists
+
+This example demonstrates the intended boundary:
+
+- the design steward is report-first and docs/spec-owned
+- implementation owners still own code changes and proof
+- closure roles stay the same
+- the design packet becomes an explicit handoff artifact instead of hidden reasoning inside one agent transcript

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

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