@chllming/wave-orchestration 0.8.3 → 0.8.4

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 ## Unreleased
 
+## 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
 
 ### Changed

package/README.md

@@ -28,8 +28,30 @@ 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. 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.
+
+## 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.
+- `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 +101,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.4`
+- Release tag: [`v0.8.4`](https://github.com/chllming/agent-wave-orchestrator/releases/tag/v0.8.4)
 - Public install path: npmjs
 - Authenticated fallback: GitHub Packages
 
-Highlights in `0.8.3`:
+Highlights in `0.8.4`:
 
-- 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.
+- 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.
 
 Requirements:
 
@@ -145,6 +167,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
@@ -182,8 +217,9 @@ codex mcp list
 - [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-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

@@ -39,8 +39,12 @@ The useful path is journey-first:
   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/concepts/what-is-a-wave.md

@@ -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 up to two optional review specialists. A wave may override the role ids, but the closure semantics stay the same:
 
 - `A8`
   Integration steward

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 starter workspace in this source repo reflects the `0.8.4` package release surface.
+- 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.
@@ -28,7 +28,7 @@
   - runtime projections are generated for Codex, Claude, OpenCode, and local execution
 - 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 +37,25 @@
   - 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
+  - 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 +75,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
-- 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.
+- 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.

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

@@ -1,8 +1,8 @@
 # End-State Architecture
 
-This document describes the target architecture for Wave Orchestration after the full refactor is complete. It is the authoritative reference for what the system should look like when all P0, P1, and P2 work items are landed.
+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.
 
-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 session supervisor that reads decisions from canonical state and delegates work to explicit subsystems.
+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.
 
 ---
 
@@ -12,7 +12,7 @@ The thesis is unchanged: bounded waves, closure roles, proof artifacts, selectiv
 
 2. **Phase engines replace the monolithic launcher loop.** Each distinct concern — implementation orchestration, derived-state materialization, gate evaluation, retry planning, closure sequencing, session supervision — lives in its own deterministic module with an explicit input/output contract.
 
-3. **Planning engines emit intent; the supervisor emits observed facts.** A phase engine may output `agent_run_planned` or a launch intent. Only the session supervisor, after the process actually launches, writes `agent_run.started`. This distinction between desired action and observed action is critical for replay and auditability.
+3. **Planning engines emit intent; the supervisor emits observed facts.** A phase engine may output a run selection or launch request. Only the session supervisor, after the process actually launches, writes `agent_run.started`. This distinction between desired action and observed action is critical for replay and auditability.
 
 4. **Proof and closure are separate first-class states.** An agent can satisfy its own work contract (`owned_slice_proven`) without the wave being closeable (`wave_closure_ready`). These are distinct top-level state transitions, not implicit conditions scattered across gate checks.
 
@@ -84,25 +84,26 @@ Each phase engine is a pure-ish function: it reads from the canonical authority
 implementation-engine.mjs  Drives the implementation phase
                            Inputs:  wave definition, materialized event state,
                                     task graph, retry plan
-                           Outputs: launch intents (agent_run_planned),
-                                    run selections, executor assignments,
+                           Outputs: run selections, launch requests,
+                                    executor assignments,
                                     prompt construction requests
-                           Does NOT output: agent_run.started, attempt.created
+                           Does NOT output: agent_run.started, attempt.running
                            (those are observed facts written by the supervisor)
 
-derived-state-engine.mjs   Materializes all derived state from canonical sources
-  (launcher-derived-       Inputs:  coordination log, control-plane events,
-   state.mjs today)                 agent result envelopes
-                           Outputs: shared summaries, per-agent inboxes,
-                                    assignment snapshots, dependency snapshots,
-                                    ledger, docs queue, security summary,
-                                    integration summary
+derived-state-engine.mjs   Computes all derived state from canonical sources
+                           Inputs:  coordination log, control-plane events,
+                                    agent result envelopes
+                           Outputs: derived payloads for shared summaries,
+                                    per-agent inboxes, assignment snapshots,
+                                    dependency snapshots, ledger, docs queue,
+                                    security summary, integration summary
                            Rule:    reads only from canonical authority set,
-                                    never from its own prior outputs
+                                    never from its own prior outputs and
+                                    never persists projections directly
 
 gate-engine.mjs            Evaluates all closure gates
-  (launcher-gates.mjs      Inputs:  agent result envelopes, proof registry,
-   today)                           coordination state, component matrix,
+                           Inputs:  agent result envelopes, proof registry,
+                                    coordination state, component matrix,
                                     task graph
                            Outputs: per-gate verdicts (ok/blocked + detail),
                                     per-task owned_slice_proven verdicts
@@ -114,15 +115,15 @@ gate-engine.mjs            Evaluates all closure gates
                                     dependency-barrier, clarification-barrier
 
 closure-engine.mjs         Sequences the closure sweep
-  (launcher-closure.mjs    Inputs:  gate verdicts, wave definition, task graph
-   today)                  Outputs: closure phase transitions, agent relaunch
+                           Inputs:  gate verdicts, wave definition, task graph
+                           Outputs: closure phase transitions, agent relaunch
                                     requests, wave completion or block events
                            Stages:  implementation+proof → cont-eval → security →
                                     integration → documentation → cont-qa
 
 retry-engine.mjs           Plans all retry and resume operations
-  (launcher-retry.mjs      Inputs:  failure records, proof registry, rerun
-   today)                           requests, executor history, task graph
+                           Inputs:  failure records, proof registry, rerun
+                                    requests, executor history, task graph
                            Outputs: retry plan with explicit contract:
                                     - why_resuming
                                     - invalidated (task ids)
@@ -148,26 +149,27 @@ 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 all non-canonical file writes.
+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.
 
 ```
 session-supervisor.mjs     Launches and monitors agent sessions
-  (launcher-supervisor.mjs Inputs:  launch intents from implementation engine,
-   today)                           launch specs from executor adapters
+                           Inputs:  run selections / launch requests from
+                                    implementation engine and closure engine,
+                                    launch specs from executor adapters
                            Owns:    process lifecycle, tmux sessions,
                                     terminal surfaces, PID tracking,
                                     lock management, rate-limit retry loops,
                                     resident orchestrator sessions
-                           Writes:  agent_run.started (after real launch),
-                                    agent_run.completed (after real completion),
-                                    attempt.created, attempt.completed
+                           Writes:  wave_run.started|completed|failed,
+                                    attempt.running|completed|failed,
+                                    agent_run.started|completed|failed|timed_out
                            Observes: human feedback responses (collects and
                                     submits, but does NOT own SLA, reroute,
                                     escalation, or timeout policy — those
                                     are control-plane workflow semantics
                                     materialized by the reducer)
 
-projection-writer.mjs      Writes all non-canonical outputs
+projection-writer.mjs      Writes projection outputs
   (new)                    Inputs:  derived state from materializer,
                                     gate verdicts from gate engine,
                                     wave state from reducer
@@ -175,7 +177,10 @@ projection-writer.mjs      Writes all non-canonical outputs
                                     markdown board projections,
                                     coordination board projection,
                                     trace bundles, quality metrics,
-                                    human-facing status summaries
+                                    shared summaries, inboxes, assignment
+                                    and dependency snapshots, ledger,
+                                    docs queue, security summary,
+                                    integration summary
                            Rule:    never reads its own outputs,
                                     always writes atomically,
                                     labels every artifact with its class
@@ -192,15 +197,15 @@ launcher.mjs               Thin orchestrator
                            3. For each wave:
                               a. reducer.rebuild() → current state
                               b. retry-engine.plan() → retry decisions
-                              c. implementation-engine.select() → launch intents
-                              d. derived-state-engine.materialize() → projections
-                              e. supervisor.launch(intents) → agent sessions
+                              c. implementation-engine.select() → run selections
+                              d. derived-state-engine.materialize() → derived payloads
+                              e. supervisor.launch(run selections) → agent sessions
                                  (supervisor writes agent_run.started)
                               f. supervisor.wait() → completion
                                  (supervisor writes agent_run.completed)
                               g. gate-engine.evaluate() → gate verdicts
                               h. closure-engine.sequence() → closure phases
-                              i. projection-writer.write() → dashboards, traces
+                              i. projection-writer.write() → persisted projections
                            4. Release lock, exit
 ```
 
@@ -361,11 +366,11 @@ All tasks in the wave are `owned_slice_proven` AND all cross-cutting closure con
 - no open clarification barriers
 - no open helper assignment barriers
 - no open cross-lane dependency barriers
-- integration gate passed (A8)
-- documentation gate passed (A9)
-- cont-eval gate passed (E0) if applicable
+- integration gate passed (effective integration steward; starter default `A8`)
+- documentation gate passed (effective documentation steward; starter default `A9`)
+- cont-eval gate passed (effective `cont-EVAL`; starter default `E0`) if applicable
 - security gate passed if applicable
-- cont-qa final verdict is PASS (A0)
+- cont-qa final verdict is PASS (effective `cont-QA`; starter default `A0`)
 - component matrix promotions validated
 
 Only when `wave_closure_ready` is true does the closure engine emit the `wave_run.completed` event.
@@ -499,13 +504,11 @@ Agent result envelopes are classified as canonical structured snapshots and must
 .tmp/<lane>-wave-launcher/results/wave-<N>/attempt-<A>/<agentId>.json
 ```
 
-### Migration path
-
-- Phase 1: agents emit the envelope alongside existing log markers. Gate engine reads the envelope when present, falls back to the legacy adapter.
-- Phase 2: gate engine requires the envelope. Log markers become human-readable only.
-- Phase 3: log-parsing code is removed.
+### Current runtime behavior
 
-During migration, the `agent-state.mjs` module gains a `buildEnvelopeFromLegacySignals()` adapter that synthesizes an envelope from parsed log markers, so the gate engine always sees the same shape.
+- Live runs read and write the attempt-scoped canonical envelope path directly.
+- Legacy sibling `*.envelope.json` files and marker-era artifacts are compatibility import inputs for replay, reconcile, and historical trace materialization only.
+- `synthesizeLegacyEnvelope()` remains explicit migration-only compatibility code; live gate, retry, closure, and reducer decisions do not use it as a correctness path.
 
 ---
 
@@ -545,15 +548,17 @@ Projections materialized from Class 1 and Class 2 sources. Can be deleted and re
 | Relaunch plan | `.tmp/<lane>-wave-launcher/status/relaunch-plan-wave-<N>.json` | JSON |
 | Assignment snapshot | `.tmp/<lane>-wave-launcher/assignments/wave-<N>.json` | JSON |
 | Dependency snapshot | `.tmp/<lane>-wave-launcher/dependencies/wave-<N>.json` | JSON |
-| Shared summary | `.tmp/<lane>-wave-launcher/summaries/wave-<N>-shared.md` | Markdown |
+| Shared summary | `.tmp/<lane>-wave-launcher/inboxes/wave-<N>/shared-summary.md` | Markdown |
 | Per-agent inbox | `.tmp/<lane>-wave-launcher/inboxes/wave-<N>/<agentId>.md` | Markdown |
-| Ledger | `.tmp/<lane>-wave-launcher/ledgers/wave-<N>.json` | JSON |
+| Ledger | `.tmp/<lane>-wave-launcher/ledger/wave-<N>.json` | JSON |
 | Docs queue | `.tmp/<lane>-wave-launcher/docs-queue/wave-<N>.json` | JSON |
-| Security summary | `.tmp/<lane>-wave-launcher/summaries/wave-<N>-security.md` | Markdown |
-| Integration summary | `.tmp/<lane>-wave-launcher/summaries/wave-<N>-integration.md` | Markdown |
+| Security summary JSON | `.tmp/<lane>-wave-launcher/security/wave-<N>.json` | JSON |
+| Security summary markdown | `.tmp/<lane>-wave-launcher/security/wave-<N>.md` | Markdown |
+| Integration summary JSON | `.tmp/<lane>-wave-launcher/integration/wave-<N>.json` | JSON |
+| Integration summary markdown | `.tmp/<lane>-wave-launcher/integration/wave-<N>.md` | Markdown |
 | Run state | `.tmp/<lane>-wave-launcher/run-state.json` | JSON |
 | Quality metrics | `.tmp/<lane>-wave-launcher/traces/wave-<N>/attempt-<A>/quality.json` | JSON |
-| Task graph snapshot | `.tmp/<lane>-wave-launcher/tasks/wave-<N>.json` | JSON |
+| Reducer snapshot | `.tmp/<lane>-wave-launcher/reducer/wave-<N>.json` | JSON |
 
 ### Class 4 — Human-Facing Projections
 
@@ -563,9 +568,9 @@ Convenience outputs for operator dashboards and review. Never read by the system
 |----------|------|--------|
 | Global dashboard | `.tmp/<lane>-wave-launcher/dashboards/global.json` | JSON |
 | Wave dashboard | `.tmp/<lane>-wave-launcher/dashboards/wave-<N>.json` | JSON |
-| Coordination board | `.tmp/<lane>-wave-launcher/coordination/wave-<N>-board.md` | Markdown |
-| Orchestrator board | `.tmp/<lane>-wave-launcher/coordination/orchestrator-board.md` | Markdown |
-| Wave manifest | `.tmp/<lane>-wave-launcher/wave-manifest.json` | JSON |
+| Coordination board | `.tmp/<lane>-wave-launcher/messageboards/wave-<N>.md` | Markdown |
+| Orchestrator board | `.tmp/wave-orchestrator/messageboards/orchestrator.md` | Markdown |
+| Wave manifest | `.tmp/<lane>-wave-launcher/waves.manifest.json` | JSON |
 
 Each artifact file includes a `_meta` field (or frontmatter for markdown) declaring:
 
@@ -839,23 +844,31 @@ This boundary means a future Temporal-backed or service-backed orchestrator can
 
 ---
 
-## File-to-Module Migration Map
-
-This maps current files to their end-state locations.
-
-| Current File | End-State Module | Notes |
-|-------------|-----------------|-------|
-| `launcher.mjs` (monolith) | `launcher.mjs` (thin orchestrator) | ~95% of logic moves to engines |
-| `launcher-runtime.mjs` | `session-supervisor.mjs` | Session launch/wait |
-| `launcher-closure.mjs` | `closure-engine.mjs` | Closure sequencing |
-| `launcher-gates.mjs` | `gate-engine.mjs` | Gate evaluation |
-| `launcher-retry.mjs` | `retry-engine.mjs` | Retry planning |
-| `launcher-derived-state.mjs` | `derived-state-engine.mjs` | State materialization |
-| `launcher-supervisor.mjs` | `session-supervisor.mjs` | Merged with runtime |
-| (new) | `implementation-engine.mjs` | Implementation phase orchestration |
-| (new) | `wave-state-reducer.mjs` | Pure state reducer |
-| (new) | `projection-writer.mjs` | All non-canonical writes |
-| (new) | `result-envelope.mjs` | Envelope schema + validation |
+## Runtime Module Layout
+
+The runtime tree now uses the engine-oriented module names directly.
+
+| Runtime Module | Responsibility |
+|---------------|----------------|
+| `launcher.mjs` | Thin orchestrator and CLI entrypoint |
+| `implementation-engine.mjs` | Implementation fan-out planning |
+| `derived-state-engine.mjs` | Derived state computation from canonical inputs |
+| `gate-engine.mjs` | Live gate evaluation |
+| `closure-engine.mjs` | Closure sequencing |
+| `retry-engine.mjs` | Retry and resume planning |
+| `wave-state-reducer.mjs` | Deterministic wave-state reconstruction |
+| `session-supervisor.mjs` | Session launch and observation |
+| `projection-writer.mjs` | Projection writes |
+| `result-envelope.mjs` | Envelope schema, validation, and compatibility synthesis |
+| `launcher-runtime.mjs` | Low-level launch and wait helpers used by the session supervisor |
+| `control-plane.mjs` | Canonical control-plane event log |
+| `coordination-store.mjs` | Canonical coordination log |
+| `wave-files.mjs` | Parsed wave definitions |
+
+Historical note:
+
+- earlier transition builds used `launcher-gates.mjs`, `launcher-retry.mjs`, `launcher-derived-state.mjs`, `launcher-closure.mjs`, and `launcher-supervisor.mjs` as extracted runtime modules
+- those compatibility names are no longer part of the live runtime tree
 | (new) | `contradiction-entity.mjs` | Contradiction lifecycle |
 | (new) | `fact-entity.mjs` | Fact/evidence lineage |
 | (new) | `human-input-workflow.mjs` | Human input workflow logic |
@@ -900,7 +913,7 @@ This section documents the 10 feedback corrections incorporated from architectur
 
 2. **Task vs coordination_record boundary:** added an explicit section defining the crisp rule. Task = durable work unit with ownership, artifact contract, proof rules, closure semantics. Coordination record = event or message about a task. They do not overlap.
 
-3. **Intent vs observation:** implementation engine now emits `agent_run_planned` (intent). Only the session supervisor writes `agent_run.started` (observed fact). The `agent_run` state machine now includes `planned → started` to capture this.
+3. **Intent vs observation:** planning engines emit run selections or launch requests (intent). Only the session supervisor writes `wave_run.*`, `attempt.*`, and `agent_run.*` observed lifecycle facts after those events actually happen.
 
 4. **Reducer input model:** the reducer explicitly takes all three canonical sources (control-plane events, coordination records, agent result envelopes) as arguments. The doc no longer claims a single event log.
 
@@ -914,7 +927,7 @@ This section documents the 10 feedback corrections incorporated from architectur
 
 9. **Human input workflow ownership:** explicitly moved SLA, reroute, escalation, and timeout logic out of the supervisor. The supervisor observes and submits; workflow semantics live in control-plane events, the reducer, and `human-input-workflow.mjs`.
 
-10. **Executor adapter contract:** `buildResultEnvelope(logPath, statusPath)` replaced with `locateResultEnvelope()` + `validateResultEnvelope()` for the end state, and `synthesizeLegacyEnvelope()` explicitly named as migration-only.
+10. **Executor adapter contract:** `locateResultEnvelope()` + `validateResultEnvelope()` define the live end state, and `synthesizeLegacyEnvelope()` is explicitly named as migration-only compatibility code.
 
 ---
 

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.3` Wave surface.
+Use it as the single reference example for the current `0.8.4` Wave surface.
 
 It intentionally combines more sections than a normal production wave so one file can demonstrate: