@chllming/wave-orchestration 0.8.2 → 0.8.4

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

@@ -25,6 +25,17 @@ Those are related, but they are not the same.
 
 An implementation agent can be locally complete and still leave the wave blocked if it created open helper work, unresolved clarification chains, or required dependencies.
 
+At runtime, those distinctions map onto separate modules:
+
+- `implementation-engine.mjs` selects implementation work
+- `derived-state-engine.mjs` rebuilds the blackboard projections
+- `gate-engine.mjs` evaluates closure and barrier state from envelopes plus canonical logs
+- `retry-engine.mjs` decides what can safely resume
+- `closure-engine.mjs` sequences the staged closeout
+- `session-supervisor.mjs` only launches sessions and records observed facts
+
+Closure roles are resolved from the wave definition first, then from starter defaults. In other words, integration, documentation, `cont-QA`, `cont-EVAL`, and security review keep the same semantics even when a wave overrides the default role ids such as `A8`, `A9`, `A0`, `E0`, or `A7`.
+
 ## Durable State Surfaces
 
 The runtime writes several different artifacts, but they do different jobs:
@@ -52,6 +63,8 @@ The runtime writes several different artifacts, but they do different jobs:
 
 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).
 
+That control-plane log also carries observed `wave_run`, `attempt`, and `agent_run` lifecycle facts from `session-supervisor.mjs`. When human feedback or escalation remains open, the reducer materializes the wave as `clarifying` with blocked `waveState` instead of flattening it into generic progress.
+
 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
@@ -61,7 +74,7 @@ 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.
 - `blocker`
-  Use this when the wave is blocked, but not because the launcher needs to route work to a specific assignee.
+  Use this when the wave is blocked, but not because the runtime needs to route work to a specific assignee.
 - `handoff`
   Use this for continuity and context transfer. This is informative by itself; it is not the same as a blocking helper assignment.
 - `evidence`
@@ -164,7 +177,7 @@ pnpm exec wave control task create \
 What happens next:
 
 - the request lands in the canonical coordination log
-- the launcher derives a helper assignment for `agent:A8`
+- the runtime derives a helper assignment for `agent:A8`
 - that assignment is written into the assignment snapshot
 - the shared summary and A8 inbox now show the open helper work
 
@@ -230,9 +243,9 @@ pnpm exec wave coord post \
 
 What happens next:
 
-1. the launcher triages the clarification from repo policy, ownership, prior decisions, and routing context
+1. the orchestrator triages the clarification from repo policy, ownership, prior decisions, and routing context
 2. if it can answer inside the wave, it writes the resolution back into coordination state
-3. if another owner can answer it, the launcher opens a targeted follow-up request and keeps the clarification chain blocking
+3. if another owner can answer it, the runtime opens a targeted follow-up request and keeps the clarification chain blocking
 4. only after policy and routed follow-up paths are exhausted does it create human feedback or escalation artifacts
 5. until that chain is resolved, clarification remains a closure barrier and any routed follow-up also remains blocking helper work
 
@@ -250,6 +263,17 @@ pnpm exec wave control task act resolve --lane main --wave 10 --id escalation-cl
 
 That keeps clarification routing, dismissal, escalation, and human-answer handling inside the canonical coordination state instead of forcing ad hoc file edits.
 
+When the operator answers through the feedback queue directly, the answer path now repairs the same canonical state:
+
+```bash
+pnpm exec wave feedback respond \
+  --id 202603240000-main-w6-A3-abc123 \
+  --response "Use the 90-day compatibility window documented in docs/plans/migration.md." \
+  --operator ops-lead
+```
+
+For ad-hoc runs, include `--run <id>` on that command. The response path will reconcile the linked clarification or escalation chain, re-sync helper-assignment projections, and write a safe one-shot continuation request when the reducer can resume but no active attempt is still running.
+
 ## End-To-End Example: Required Dependency
 
 Assume the wave needs another lane to land a required API first.
@@ -395,7 +419,7 @@ That gives Wave two useful properties:
 
 ## Targeted Retry Behavior
 
-When closure fails, the launcher does not always relaunch the entire wave.
+When closure fails, the runtime does not always relaunch the entire wave.
 
 It tries to relaunch only the implicated owners:
 
@@ -414,7 +438,7 @@ pnpm exec wave control rerun get --lane main --wave 10 --json
 pnpm exec wave control rerun request --lane main --wave 10 --agent A2 --agent A7 --clear-reuse A2 --reason "Resume sibling-owned component closure"
 ```
 
-The canonical rerun request is written under `.tmp/<lane>-wave-launcher/control-plane/`, projected to `.tmp/<lane>-wave-launcher/control/` for compatibility, consumed by the launcher on the next retry decision, and then cleared by default after one application. This is the supported path for:
+The canonical rerun request is written under `.tmp/<lane>-wave-launcher/control-plane/`, projected to `.tmp/<lane>-wave-launcher/control/` for compatibility, consumed by the retry engine on the next retry decision, and then cleared by default after one application. This is the supported path for:
 
 - rerunning only specific owners
 - preserving explicit reuse selectors such as attempt ids, proof bundle ids, derived-summary reuse, and invalidated component ids through the compatibility projection

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.8.2` release procedure publishes through a repository Actions secret named `NPM_TOKEN`.
+The current `0.8.4` release procedure publishes through a repository Actions secret named `NPM_TOKEN`.
 
 ## What This Repo Already Does
 
@@ -47,6 +47,7 @@ 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.8.2`.
-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.
+4. Confirm `README.md`, `CHANGELOG.md`, `releases/manifest.json`, and `docs/plans/migration.md` all describe the same release surface.
+5. Push the release commit and release tag, for example `v0.8.4`.
+6. Verify both `publish-npm.yml` and `publish-package.yml` start from the tag push.
+7. 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.8.2 Wave surface."
+summary: "Showcase-first sample waves that demonstrate the current 0.8.4 Wave surface."
 ---
 
 # Sample Waves
 
-This guide points to showcase-first sample waves that demonstrate the current `0.8.2` authored Wave surface.
+This guide points to showcase-first sample waves that demonstrate the current `0.8.4` 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.8.2` 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.4` 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.8.2`:
+Together these samples cover the main surfaces added or hardened for `0.8.4`:
 
 - repo-landed maturity discipline and anti-overclaim framing
 - explicit shared-plan closure for future-wave safety

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chllming/wave-orchestration",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "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.4",
+      "date": "2026-03-25",
+      "summary": "Contradiction replay repair, consistent component-promotion thresholds, projection-writer persistence centralization, and 0.8.4 release-surface alignment.",
+      "features": [
+        "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 across live and replay paths.",
+        "Projection persistence is now centralized under `projection-writer.mjs`, while `derived-state-engine.mjs` computes projection payloads without writing them directly.",
+        "The operator migration guide 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.",
+        "Shipped package metadata, README, migration guidance, current-state notes, sample-wave docs, and npm publishing instructions now point at the `0.8.4` 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.4` replay, projection, and component-threshold behavior.",
+        "If your adopted repo uses planner workflows and copied the starter planner corpus, sync `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 in `docs/context7/bundles.json`.",
+        "If your repo copied the shipped starter docs or skills, sync the current operator runbook, architecture docs, launcher or orchestrator prompts, planner corpus, and relevant runtime or closure-role starter skills before relying on local runbooks.",
+        "If your repo keeps historical replay fixtures, replay at least one contradiction-blocked trace and one promoted-component trace after the upgrade so both code paths stay covered.",
+        "If an older adopted repo still carries legacy evaluator wording or pre-control-plane operator docs, complete the repo-owned prompt and runbook migration described in `docs/plans/migration.md` before cutting live waves on `0.8.4`."
+      ],
+      "breaking": false
+    },
+    {
+      "version": "0.8.3",
+      "date": "2026-03-24",
+      "summary": "Human-input reconciliation repair, ad-hoc feedback-run context hardening, and 0.8.3 release-surface alignment.",
+      "features": [
+        "Answered human-feedback requests now reconcile linked clarification, escalation, and helper-assignment state back into the canonical coordination log instead of only updating the feedback request JSON.",
+        "`wave feedback respond --run <id>` now preserves ad-hoc run context while writing reconciliation and safe continuation state, so ad-hoc answers stop mutating the roadmap lane state root.",
+        "When no attempt is still running and the reducer can safely continue, human-input reconciliation writes a one-shot continuation request instead of leaving the wave stranded after the operator answer arrives.",
+        "Regression coverage now exercises both direct feedback-response reconciliation and the ad-hoc `--run <id>` path.",
+        "Shipped package metadata, README, migration guidance, current-state notes, sample-wave docs, and npm publishing instructions now point at the `0.8.3` release surface."
+      ],
+      "manualSteps": [
+        "If your operators answer tickets through `wave feedback respond`, update any repo-local runbooks so ad-hoc runs always pass `--run <id>` when answering outside the main roadmap lane.",
+        "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.3` runtime and human-input reconciliation 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 copied the shipped starter architecture docs or skills and wants the `0.8.3` operator guidance, sync the updated launcher and orchestrator role prompts plus the relevant runtime and closure-role skill bundles."
+      ],
+      "breaking": false
+    },
     {
       "version": "0.8.2",
       "date": "2026-03-24",