@chllming/wave-orchestration 0.7.3 → 0.8.1

package/docs/plans/migration.md

@@ -1,5 +1,7 @@
 # Migration
 
+For the staged internal cutover from the legacy launcher-centric runtime to the authority-set / reducer / phase-engine architecture, see [architecture-hardening-migration.md](./architecture-hardening-migration.md). This page stays focused on package adoption and upgrade steps for repo operators.
+
 ## Default Adoption Path
 
 1. Install the package from npmjs with `pnpm add -D @chllming/wave-orchestration`.
@@ -22,13 +24,13 @@ GitHub Packages remains available as an authenticated fallback path, and maintai
 - Fresh `wave init` seeds the starter `skills/` library. `wave init --adopt-existing` records existing repo-owned skill bundles when they are already present, but does not replace or rewrite them.
 - The current runtime expects the post-roadmap model: typed coordination, compiled inboxes, `A8` integration, staged closure, orchestrator-first clarification, and operational runtime policy.
 
-## Upgrading From 0.6.x To 0.7.3
+## Upgrading From 0.6.x To 0.8.1
 
 Read `CHANGELOG.md` first, then treat this section as the repo-owned migration checklist for adopted `0.6.x` workspaces.
 
 `wave upgrade` updates the installed runtime only. It does not copy planner starter files into a repo that already owns its docs, skills, and Context7 bundles.
 
-`0.7.3` keeps the proof-centric closure hardening from `0.7.2` and closes the remaining parser hole: malformed unmatched end-of-tail fenced blocks no longer hide later final implementation markers, stale summaries rebuild when required proof/doc/component fields are still missing even if diagnostics already exist, malformed marker syntax still surfaces explicit parse errors, and incomplete implementation work should stay inside the required final markers with `state=gap` instead of trailing `[wave-gap]` lines.
+`0.8.1` carries forward the `0.8.0` architecture-hardening release surface and tightens helper-assignment closure handling: `resolved-by-policy` records now default to `resolved`, single-target helper requests can close from policy follow-up without mutating the original request, and multi-target helper requests only close from assignment-specific policy evidence so sibling assignments stay honest.
 
 ### Required Repo Changes
 
@@ -40,6 +42,14 @@ If the repo adopted Wave before the planner corpus became a tracked required sur
 - `docs/reference/wave-planning-lessons.md`
 - the `planner-agentic` bundle entry in `docs/context7/bundles.json`
 
+If the repo copied the shipped starter architecture docs or skills and wants the `0.8.1` authority-model language, also sync:
+
+- `docs/agents/wave-launcher-role.md`
+- `docs/agents/wave-orchestrator-role.md`
+- `skills/wave-core/`
+- the relevant runtime and closure-role starter skills under `skills/`
+- `docs/plans/architecture-hardening-migration.md`
+
 ### Recommended Upgrade Validation
 
 After syncing those repo-owned files:

package/docs/plans/wave-orchestrator.md

@@ -7,7 +7,7 @@ For the broader docs map, concept pages, and workflow guides, start at [docs/REA
 This runbook is the operational view of the architecture:
 
 - one wave contract defines goals, ownership, proof, and closure
-- one canonical coordination log acts as the shared blackboard state
+- one canonical authority set acts as the shared blackboard state: wave definitions, coordination records, control-plane events, and immutable result envelopes
 - generated board, shared summary, inboxes, ledger, and integration outputs are projections over that state
 - executor adapters preserve Claude, Codex, and OpenCode-specific runtime features at the edge
 - closure makes completion depend on integrated proof and shared state, not on free-form agent narration
@@ -145,11 +145,11 @@ Compatibility note:
 
 - `wave coord`, `wave retry`, and `wave proof` remain available as compatibility surfaces, but new operator docs and runbooks should prefer `wave control`.
 
-The canonical state is the JSONL log under `.tmp/<lane>-wave-launcher/coordination/`. The markdown board is a generated projection for humans, not the scheduler's source of truth.
+The canonical conversational state is the JSONL log under `.tmp/<lane>-wave-launcher/coordination/`. The markdown board is a generated projection for humans, not a decision input.
 
-Control-plane facts that drive reruns, proof, attempt state, and operator tasks are appended separately under `.tmp/<lane>-wave-launcher/control-plane/`. Legacy proof and retry files remain derived projections for compatibility, not the source of truth.
+Control-plane facts that drive reruns, proof, attempt state, contradictions, facts, and operator tasks are appended separately under `.tmp/<lane>-wave-launcher/control-plane/`. Result envelopes live under `.tmp/<lane>-wave-launcher/results/`. Legacy proof and retry files remain derived projections for compatibility, not decision inputs.
 
-Capability-targeted requests now become deterministic helper assignments. The launcher resolves the assignee from explicit targets, `capabilityRouting.preferredAgents`, then least-busy matching capability owners, writes that assignment into `.tmp/<lane>-wave-launcher/assignments/`, mirrors the decision into coordination state, and keeps the wave blocked until the linked follow-up resolves.
+Capability-targeted requests now become deterministic helper assignments. The runtime resolves the assignee from explicit targets, `capabilityRouting.preferredAgents`, then least-busy matching capability owners, writes that assignment into `.tmp/<lane>-wave-launcher/assignments/`, mirrors the decision into coordination state, and keeps the wave blocked until the linked follow-up resolves.
 
 Clarification flow is orchestrator-first:
 
@@ -159,9 +159,9 @@ Clarification flow is orchestrator-first:
 4. Routed clarification follow-up requests remain blocking until they resolve.
 5. Human escalations are written back into coordination state, the ledger, and trace artifacts.
 
-During live runs, the launcher now keeps an active orchestration loop while agents are still running. It refreshes the derived coordination surfaces on cadence, surfaces overdue acknowledgements and stale clarification chains in dashboards and traces, and can reroute clarification follow-up requests inside the same attempt when the routed owner never acknowledges them.
+During live runs, the orchestrator now keeps an active supervision and state-refresh loop while agents are still running. It refreshes the derived coordination surfaces on cadence, surfaces overdue acknowledgements and stale clarification chains in dashboards and traces, and can reroute clarification follow-up requests inside the same attempt when the routed owner never acknowledges them.
 
-If you opt into `--resident-orchestrator`, the launcher also starts a long-running non-owning orchestrator session for the wave. That session can inspect the same coordination artifacts and intervene through coordination records, but the launcher remains the scheduler truth and closure authority.
+If you opt into `--resident-orchestrator`, the launcher also starts a long-running non-owning orchestrator session for the wave. That session can inspect the same coordination artifacts and intervene through coordination records, but it does not override reducer, gate, or closure decisions.
 
 Retry intent, operator tasks, attempt lifecycle, and proof injection are now first-class control-plane artifacts rather than manual file surgery:
 
@@ -229,7 +229,9 @@ pnpm exec wave changelog --since-installed
 - docs queue: `.tmp/<lane>-wave-launcher/docs-queue/`
 - trace bundles: `.tmp/<lane>-wave-launcher/traces/`
 - control-plane events: `.tmp/<lane>-wave-launcher/control-plane/`
-  Canonical append-only JSONL log of operator tasks, rerun requests, proof bundles, attempt lifecycle, and human-input events. This is the source of truth for `wave control`. Telemetry queue lives under `control-plane/telemetry/`.
+  Canonical append-only JSONL log of operator tasks, rerun requests, proof bundles, attempt lifecycle, contradictions, facts, and human-input events. This is the canonical lifecycle state for `wave control`. Telemetry queue lives under `control-plane/telemetry/`.
+- result envelopes: `.tmp/<lane>-wave-launcher/results/`
+  Attempt-scoped immutable structured result snapshots used by reducer, gate, retry, and replay flows.
 - proof registries: `.tmp/<lane>-wave-launcher/proof/`
   Projected from control-plane state for compatibility. Operator-registered authoritative proof bundles that feed integration, cont-QA, and replay.
 - retry overrides: `.tmp/<lane>-wave-launcher/control/`
@@ -246,7 +248,7 @@ pnpm exec wave changelog --since-installed
 
 Ad-hoc runs mirror the same state shape under `.tmp/<lane>-wave-launcher/adhoc/<run-id>/`, including dry-run previews at `.tmp/<lane>-wave-launcher/adhoc/<run-id>/dry-run/`. Their docs queue can still point at canonical shared-plan docs when the run reports a shared-plan delta.
 
-The launcher entrypoint in `scripts/wave-orchestrator/launcher.mjs` now delegates session launch or wait mechanics to `launcher-runtime.mjs` and closure-sweep sequencing to `launcher-closure.mjs`. The CLI and `traceVersion: 2` replay contract stay unchanged.
+The launcher entrypoint in `scripts/wave-orchestrator/launcher.mjs` is being hardened toward a thin orchestrator over reducer, derived-state, retry, gate, closure, and supervision modules. The CLI and `traceVersion: 2` replay contract stay unchanged.
 
 ## Trace Contract
 

package/docs/reference/coordination-and-closure.md

@@ -31,6 +31,10 @@ The runtime writes several different artifacts, but they do different jobs:
 
 - canonical coordination log:
   `.tmp/<lane>-wave-launcher/coordination/wave-<n>.jsonl`
+- canonical control-plane log:
+  `.tmp/<lane>-wave-launcher/control-plane/wave-<n>.jsonl`
+- result envelopes:
+  `.tmp/<lane>-wave-launcher/results/wave-<n>/attempt-<a>/<agent>.json`
 - helper-assignment snapshot:
   `.tmp/<lane>-wave-launcher/assignments/wave-<n>.json`
 - dependency snapshot:
@@ -46,13 +50,13 @@ The runtime writes several different artifacts, but they do different jobs:
 - run-state:
   `.tmp/<lane>-wave-launcher/run-state.json`
 
-The important rule is that the JSONL coordination log is the scheduler truth. The markdown board is a projection for humans. See [wave-orchestrator.md](../plans/wave-orchestrator.md).
+The important rule is that decisions come from the canonical authority set: wave definitions, the coordination log, the control-plane log, and immutable result envelopes. The markdown board is a projection for humans. See [wave-orchestrator.md](../plans/wave-orchestrator.md).
 
 Live waves now keep refreshing that derived state while agents are still running. Shared summaries, inboxes, dashboard coordination metrics, and clarification routing are not only recomputed at attempt boundaries; they are also refreshed during active wave execution so stale clarification and acknowledgement timing is machine-visible before the attempt ends.
 
 ## What Agents Should Use
 
-Use the coordination log for durable state:
+Use the coordination log for conversational or workflow state:
 
 - `request`
   Use this when you need another agent or capability owner to do work. Target it explicitly. This is the kind that becomes a helper assignment.
@@ -173,7 +177,7 @@ This is the important distinction:
 - A1 may be done with A1's ownership
 - the wave is not done
 
-The launcher will still see:
+The reducer and gate engine will still see:
 
 - an open helper assignment for the request
 - an integration summary that is not yet ready for doc closure
@@ -197,7 +201,7 @@ That usually means:
 
 ### Step 5: Closure Can Continue
 
-Only after that does the launcher allow the wave to move on to:
+Only after that does the closure engine allow the wave to move on to:
 
 1. documentation closure
 2. cont-QA closure

package/docs/reference/npmjs-trusted-publishing.md

@@ -2,7 +2,7 @@
 
 This repo now includes a dedicated npmjs publish workflow at [publish-npm.yml](../../.github/workflows/publish-npm.yml).
 
-The current `0.7.3` release procedure publishes through a repository Actions secret named `NPM_TOKEN`.
+The current `0.8.1` release procedure publishes through a repository Actions secret named `NPM_TOKEN`.
 
 ## What This Repo Already Does
 
@@ -47,6 +47,6 @@ If this repo later needs private npm dependencies during CI, consider a separate
 1. Confirm [publish-npm.yml](../../.github/workflows/publish-npm.yml) is on the default branch.
 2. Confirm `NPM_TOKEN` exists in the GitHub repo secrets.
 3. Confirm the package version has been bumped and committed.
-4. Push the release commit and release tag, for example `v0.7.3`.
+4. Push the release commit and release tag, for example `v0.8.1`.
 5. Verify both `publish-npm.yml` and `publish-package.yml` start from the tag push.
 6. Verify the npmjs publish completes successfully for the tagged source.

package/docs/reference/sample-waves.md

@@ -1,11 +1,11 @@
 ---
 title: "Sample Waves"
-summary: "Showcase-first sample waves that demonstrate the current 0.7.3 Wave surface."
+summary: "Showcase-first sample waves that demonstrate the current 0.8.1 Wave surface."
 ---
 
 # Sample Waves
 
-This guide points to showcase-first sample waves that demonstrate the current `0.7.3` authored Wave surface.
+This guide points to showcase-first sample waves that demonstrate the current `0.8.1` authored Wave surface.
 
 The examples are intentionally denser than typical production waves. Their job is to teach the current authoring and runtime surface quickly, not to be the smallest possible launch-ready files.
 
@@ -15,7 +15,7 @@ The examples are intentionally denser than typical production waves. Their job i
   Shows what a good `repo-landed` outcome looks like when one promoted component only closes honestly if desired-state records, reconcile-loop substrate, and cluster-view surfaces land together. It emphasizes maturity discipline, explicit deliverables, and shared-plan closure without drifting into `pilot-live` claims.
 
 - [Full modern sample wave](../plans/examples/wave-example-live-proof.md)
-  Shows the combined `0.7.3` authored surface in one file: closure roles, `E0`, optional security review, delegated and pinned benchmark targets, richer executor config, `### Skills`, `### Capabilities`, `### Deliverables`, `### Exit contract`, `### Proof artifacts`, sticky retry, deploy environments, and proof-first live-wave structure.
+  Shows the combined `0.8.1` authored surface in one file: closure roles, `E0`, optional security review, delegated and pinned benchmark targets, richer executor config, `### Skills`, `### Capabilities`, `### Deliverables`, `### Exit contract`, `### Proof artifacts`, sticky retry, deploy environments, and proof-first live-wave structure.
 
 ## What These Examples Teach
 
@@ -38,7 +38,7 @@ The examples are intentionally denser than typical production waves. Their job i
 
 ## Feature Coverage Map
 
-Together these samples cover the main surfaces added or hardened for `0.7.3`:
+Together these samples cover the main surfaces added or hardened for `0.8.1`:
 
 - repo-landed maturity discipline and anti-overclaim framing
 - explicit shared-plan closure for future-wave safety

package/docs/reference/skills.md

@@ -1,6 +1,7 @@
 # Skills Reference
 
 Skills are repo-owned reusable instruction bundles. Wave resolves them by config layer, then filters them through each bundle's activation metadata before projecting them into the selected runtime.
+They shape runtime behavior, but they are not part of the canonical authority set.
 
 ## Canonical Bundle Layout
 
@@ -192,6 +193,8 @@ Runtime delivery:
 - Local
   The compact catalog stays prompt-only.
 
+These runtime projections are guidance surfaces. They should stay aligned with the canonical authority model, but they are not replay inputs or decision state on their own.
+
 ## Generated Artifacts
 
 Executor overlay directories can contain:

package/docs/reference/wave-control.md

@@ -9,7 +9,7 @@ Wave Control is the telemetry and analysis plane for Wave runs.
 
 The design rule is:
 
-- local files stay authoritative
+- local canonical state stays authoritative
 - remote reporting is best-effort
 - dashboards and markdown remain projections over typed local state
 
@@ -27,6 +27,8 @@ Wave Control normalizes these entity types:
 - `rerun_request`
 - `human_input`
 - `artifact`
+- `contradiction`
+- `fact`
 - `benchmark_run`
 - `benchmark_item`
 - `verification`
@@ -76,7 +78,7 @@ For the explicit README-failure-case-to-signal map, see [proof-metrics.md](./pro
 Signals to preserve:
 
 - canonical-state fidelity:
-  `coordination_record`, `wave_run`, `attempt`, and `artifact` telemetry prove the scheduler truth came from JSON state, not only markdown boards
+  `coordination_record`, `wave_run`, `attempt`, `artifact`, `contradiction`, and `fact` telemetry prove decisions came from canonical structured state, not only markdown boards or summaries
 - evidence pooling:
   integration and closure telemetry should cite the proof artifacts and evidence refs they relied on
 - contradiction repair:

package/docs/research/coordination-failure-review.md

@@ -9,7 +9,7 @@ summary: "Assessment of whether the Wave orchestrator constructively addresses c
 
 The Wave orchestrator addresses several coordination failure modes constructively in code, not just in prose. In particular, it has:
 
-- a canonical machine-readable coordination log
+- a canonical authority set with machine-readable coordination and control-plane state
 - compiled shared summaries plus per-agent inboxes
 - explicit clarification, helper-assignment, dependency, integration, documentation, and cont-QA barriers
 - structured proof and verdict validation
@@ -24,7 +24,7 @@ The main weakness is empirical, not architectural. The repo now carries coordina
 The research cited in this repo keeps returning to a fairly stable set of failure modes. In Wave language, the common ones are:
 
 - `Cosmetic board, no canonical state`
-  Agents appear coordinated because they share a board or chat, but there is no machine-trustable source of truth underneath. Wave responds with a canonical coordination log and treats the board as a projection.
+  Agents appear coordinated because they share a board or chat, but there is no machine-trustable authority set underneath. Wave responds with canonical state and treats the board as a projection.
 - `Hidden evidence never gets pooled`
   One agent has the decision-changing fact, but it never reaches the shared state before closure. Wave responds with shared summaries, per-agent inboxes, and integration gating, but this still needs stronger empirical validation.
 - `Communication without global-state reconstruction`
@@ -82,7 +82,7 @@ For this repo, the key question is whether the design relies on self-organizing
 
 #### 1. It uses a real canonical shared state, not a cosmetic board
 
-The strongest blackboard-like mechanism is the canonical JSONL coordination log plus materialized state in [scripts/wave-orchestrator/coordination-store.mjs](../../scripts/wave-orchestrator/coordination-store.mjs). The markdown board is explicitly a projection for humans, not the scheduler's source of truth, as stated in [docs/plans/wave-orchestrator.md](../plans/wave-orchestrator.md).
+The strongest blackboard-like mechanism is the canonical authority set: the coordination log, the control-plane event log, immutable result envelopes, and materialized state in [scripts/wave-orchestrator/coordination-store.mjs](../../scripts/wave-orchestrator/coordination-store.mjs). The markdown board is explicitly a projection for humans, not a decision input, as stated in [docs/plans/wave-orchestrator.md](../plans/wave-orchestrator.md).
 
 That state is then compiled into:
 
@@ -185,7 +185,7 @@ Assessment against the papers:
 
 The docs are not purely aspirational here. The main claims in [docs/plans/current-state.md](../plans/current-state.md) and [docs/plans/wave-orchestrator.md](../plans/wave-orchestrator.md) are broadly backed by the code:
 
-- canonical coordination log plus generated board
+- canonical authority-set state plus generated projections
 - compiled shared summaries and per-agent inboxes
 - orchestrator-first clarification triage
 - blocking helper assignments and cross-lane dependencies

package/docs/roadmap.md

@@ -182,7 +182,7 @@ Opt-in:
 
 The runtime already has strong coordination primitives, but the roadmap should still push these areas:
 
-- keep the canonical coordination store as the source of truth and the markdown board as a rendered view
+- keep the canonical authority set explicit and the markdown board as a rendered view
 - keep compiled per-agent inboxes and shared summaries central to prompt construction
 - strengthen the integration steward output as the single closure-ready synthesis artifact
 - add `wave lint` for ownership, component promotion, runtime mix, deploy environment, and closure completeness

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chllming/wave-orchestration",
-  "version": "0.7.3",
+  "version": "0.8.1",
   "license": "MIT",
   "description": "Generic wave-based multi-agent orchestration for repository work.",
   "repository": {

package/releases/manifest.json

@@ -2,6 +2,45 @@
   "schemaVersion": 1,
   "packageName": "@chllming/wave-orchestration",
   "releases": [
+    {
+      "version": "0.8.1",
+      "date": "2026-03-24",
+      "summary": "Helper-assignment policy-closure hardening, multi-target assignment-safety repair, and 0.8.1 release-surface alignment.",
+      "features": [
+        "`resolved-by-policy` follow-up now closes single-target helper assignments authoritatively without forcing the original request record itself to be rewritten.",
+        "Manual `wave coord post --kind resolved-by-policy` now defaults to `status=resolved`, so operator-entered policy closures stop behaving like fresh open coordination records.",
+        "Multi-target helper requests now require assignment-specific policy evidence before closure, which prevents a request-level policy note from accidentally closing sibling assignments that were not actually completed.",
+        "Regression coverage now exercises default `resolved-by-policy` status handling and the multi-target helper-assignment over-closure edge case directly.",
+        "Shipped package metadata, README, migration guidance, sample-wave docs, and npm publishing instructions now point at the `0.8.1` release surface."
+      ],
+      "manualSteps": [
+        "Run `pnpm exec wave doctor` and `pnpm exec wave launch --lane main --dry-run --no-dashboard` after upgrading so the repo validates against the `0.8.1` runtime and helper-assignment closure contract.",
+        "If an adopted repo fails `wave doctor` after the upgrade, sync the repo-owned planner starter surface (`docs/agents/wave-planner-role.md`, `skills/role-planner/`, `docs/context7/planner-agent/`, `docs/reference/wave-planning-lessons.md`, and the `planner-agentic` bundle entry) before relying on planner-aware validation.",
+        "If a repo carries custom operator docs for `wave coord post --kind resolved-by-policy`, update that guidance so policy-closure examples either omit `--status` or use `--status resolved` explicitly.",
+        "If an adopted repo copied the starter architecture docs or skill bundles, sync the updated role prompts, `skills/wave-core/`, runtime skills, and closure-role skills so local guidance matches the `0.8.1` authority model and helper-assignment behavior.",
+        "Review `docs/plans/architecture-hardening-migration.md` before continuing reducer-authoritative cutover work in repos that extend the shipped starter surface."
+      ],
+      "breaking": false
+    },
+    {
+      "version": "0.8.0",
+      "date": "2026-03-24",
+      "summary": "Architecture hardening foundations, envelope-first closure wiring, docs and skill alignment, and 0.8.0 release-surface alignment.",
+      "features": [
+        "Reducer and task replay hardening now keeps coordination-derived task identity deterministic and strengthens authoritative replay of live wave state.",
+        "Gate evaluation, contradiction or fact schema wiring, and resume planning are now aligned around control-plane state plus typed result-envelope reads instead of legacy summary-only behavior.",
+        "Live launcher evaluation now computes reducer snapshots during real runs, so the shadow or migration path exists in production execution as well as tests.",
+        "A dedicated architecture hardening migration plan now ships, and the active README, guides, role prompts, and starter skills now describe the canonical authority set, phase-engine model, and thin-launcher direction consistently.",
+        "Regression coverage now guards the docs and skill surface against stale launcher-truth wording while preserving shared `0.7.3` parity behavior in the overlapping release-era suites."
+      ],
+      "manualSteps": [
+        "Run `pnpm exec wave doctor` and `pnpm exec wave launch --lane main --dry-run --no-dashboard` after upgrading so the repo validates against the `0.8.0` runtime and starter-surface contract.",
+        "If an adopted repo fails `wave doctor` after the upgrade, sync the repo-owned planner starter surface (`docs/agents/wave-planner-role.md`, `skills/role-planner/`, `docs/context7/planner-agent/`, `docs/reference/wave-planning-lessons.md`, and the `planner-agentic` bundle entry) before relying on planner-aware validation.",
+        "If an adopted repo copied the starter architecture docs or skill bundles, sync the updated role prompts, `skills/wave-core/`, runtime skills, and closure-role skills so local guidance matches the `0.8.0` authority model.",
+        "Review `docs/plans/architecture-hardening-migration.md` before continuing the reducer-authoritative cutover work in repos that extend the shipped starter surface."
+      ],
+      "breaking": false
+    },
     {
       "version": "0.7.3",
       "date": "2026-03-23",