@chllming/wave-orchestration 0.9.4 → 0.9.6

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 0.9.6 - 2026-04-05
+
+### Fixed
+- Closure engine now respects `requireIntegrationStewardFromWave` and `requireDocumentationStewardFromWave` thresholds instead of unconditionally requiring integration/documentation closure runs.
+
+## 0.9.5 - 2026-04-05
+
+### Fixed
+- Pass `lanePaths` to `reconcileFailuresAgainstSharedComponentState` to fix `ReferenceError` crash on repos without Integration Steward (A8).
+
 ## 0.9.4 - 2026-04-05
 
 - Laddered gate modes: bootstrap/standard/strict per wave number

package/README.md

@@ -107,8 +107,8 @@ Wave is built to mitigate those failures with a canonical authority set, generat
 
 Current release:
 
-- `@chllming/wave-orchestration@0.9.4`
-- Release tag: [`v0.9.4`](https://github.com/chllming/agent-wave-orchestrator/releases/tag/v0.9.4)
+- `@chllming/wave-orchestration@0.9.6`
+- Release tag: [`v0.9.5`](https://github.com/chllming/agent-wave-orchestrator/releases/tag/v0.9.6)
 - Public install path: npmjs
 - Authenticated fallback: GitHub Packages
 

package/docs/README.md

@@ -54,7 +54,7 @@ The useful path is journey-first:
 - Publishing the package:
   Read [reference/package-publishing-flow.md](./reference/package-publishing-flow.md) for the end-to-end release path, the GitHub publish workflows, the lifecycle scripts, and the verification or repair flow.
 - Want the practical `0.9.3` operating stance:
-  Read [guides/recommendations-0.9.4.md](./guides/recommendations-0.9.4.md) for the recommended default around relaxed blocker states, advisory turn budgets, and targeted recovery.
+  Read [guides/recommendations-0.9.6.md](./guides/recommendations-0.9.6.md) for the recommended default around relaxed blocker states, advisory turn budgets, and targeted recovery.
 - 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:

package/docs/guides/recommendations-0.9.5.md

@@ -0,0 +1,191 @@
+---
+title: "0.9.4 Recommendations"
+summary: "How to use 0.9.4's softer blocker states, advisory turn budgets, and targeted recovery without weakening proof and closure."
+---
+
+# 0.9.4 Recommendations
+
+Use this guide when you are adopting `0.9.4` and want one practical operating stance for the softer blocker states, advisory turn-budget behavior, and targeted recovery flow that the current package line ships.
+
+## Recommended Default
+
+For most repos, the safest `0.9.4` default is:
+
+- bound work with `budget.minutes`
+- leave generic `budget.turns` as advisory metadata
+- author non-proof follow-up as `soft`, `stale`, or `advisory` instead of silently treating every open record as a hard blocker
+- use `resolve-policy` when the answer already exists in repo policy or shipped docs
+- prefer targeted rerun or resume after timeout, max-turn, rate-limit, or missing-status outcomes instead of relaunching the whole wave
+- in short-lived sandboxes, prefer `wave submit`, `wave supervise`, `wave status`, and `wave wait` instead of binding the full run to one client shell
+- when a wave-gate dimension has a documented gap that is not an actionable blocker, use `gap` instead of `pass` or `blocked` — the runtime treats it as a conditional pass
+
+That recommendation matches the runtime:
+
+- executor launch metadata only emits hard turn-limit flags from `claude.maxTurns` or `opencode.steps`
+- open `stale` and `advisory` coordination records stay visible without reopening the active blocking edge
+- recoverable launcher failures queue targeted retry state instead of immediately escalating to broad terminal wave failure
+
+## 1. Budgets
+
+Treat the two budget knobs differently:
+
+- `budget.minutes` is the primary attempt budget
+- generic `budget.turns` is only a planning hint
+- `claude.maxTurns` or `opencode.steps` are the hard runtime ceilings when you actually want deterministic turn stopping
+
+Recommended pattern for synthesis-heavy implementation or closure work:
+
+```json
+{
+  "executors": {
+    "profiles": {
+      "implementation-default": {
+        "id": "claude",
+        "model": "claude-sonnet-4-6",
+        "budget": {
+          "minutes": 35,
+          "turns": 12
+        }
+      }
+    }
+  }
+}
+```
+
+In that pattern, `35` minutes is real policy. `12` turns is only guidance for planning and preview metadata.
+
+Only set a hard runtime ceiling when you deliberately want the runtime itself to stop:
+
+```json
+{
+  "executors": {
+    "profiles": {
+      "bounded-closure": {
+        "id": "claude",
+        "model": "claude-sonnet-4-6",
+        "budget": {
+          "minutes": 20
+        },
+        "claude": {
+          "maxTurns": 6
+        }
+      }
+    }
+  }
+}
+```
+
+## 2. Softer Coordination States
+
+`0.9.2` keeps “still visible” separate from “still blocking”.
+
+Use these states intentionally:
+
+| State | Use it for | What the runtime does |
+| --- | --- | --- |
+| `soft` | follow-up that still matters but should not be treated like proof failure | remains visible and may still drive repair or retry targeting |
+| `stale` | outdated clarification or blocker context kept for history | visible in control state, but does not reopen blocking by itself |
+| `advisory` | known issue, note, or human context that should stay visible without blocking closure | visible in control state, but does not own the active blocking edge |
+
+Practical command paths:
+
+```bash
+pnpm exec wave control task act defer --lane main --wave 10 --id blocker-doc-follow-up
+pnpm exec wave control task act mark-stale --lane main --wave 10 --id clarify-a7-rollout
+pnpm exec wave control task act mark-advisory --lane main --wave 10 --id request-clarify-a7-rollout
+pnpm exec wave control task act resolve-policy --lane main --wave 10 --id clarify-a7-rollout --detail "Policy already covered in the rollout guide."
+```
+
+Use them when the repo already knows the answer, the remaining item is informational, or the follow-up should stay visible for the next wave without holding the current wave hostage.
+
+## 3. What Should Stay Hard
+
+Do not relax everything.
+
+Keep these hard or closure-critical unless you are intentionally changing wave policy:
+
+- missing proof or required deliverables
+- failed integration, documentation, or cont-QA closure gates
+- real human-feedback or escalation requirements that block safe continuation
+- requests or clarifications that still represent unresolved ownership or policy ambiguity for the current wave
+
+Use `gap` in wave-gate markers when a dimension has a documented gap that is not actionable in the current wave. For example, `live=gap` is appropriate when an infrastructure topology constraint prevents full live validation but the constraint is known, documented, and does not represent a regression. Do not use `gap` to hide actual failures or unreviewed work.
+
+If the current wave cannot truthfully close without the answer, keep it blocking.
+
+## 4. Recovery Recommendation
+
+My recommendation after reviewing the current `0.9.4` code path is:
+
+- let timeout, max-turn, rate-limit, and missing-status failures go through the built-in targeted recovery path first
+- inspect the queued rerun or resume request before manually relaunching the whole wave
+- preserve reusable proof from successful sibling owners whenever the reducer already identified it as reusable
+
+That is the shape the launcher now prefers. It only broadens failure when the remaining blockers are still proof-critical or otherwise non-recoverable.
+
+## 5. Suggested Operator Policy
+
+For most repo-owned runbooks:
+
+- teach authors to use `budget.minutes` first
+- teach operators to downgrade only non-proof follow-up
+- treat `resolve-policy` as the preferred path when the answer already exists in docs or repo policy
+- escalate to a full-wave rerun only after targeted recovery proves insufficient
+
+If you want a single sentence policy:
+
+> Keep proof and closure strict, keep generic turns advisory, and keep non-proof context visible without letting it accidentally own wave closure.
+
+
+## Laddered Gate Modes (new in 0.9.4)
+
+Waves now have three gate strictness tiers based on wave number:
+
+| Mode | Default waves | What's required to advance |
+|------|--------------|---------------------------|
+| **bootstrap** | 0-3 | Implementation agents exit 0 + deliverables exist |
+| **standard** | 4-9 | + A0 verdict required, doc closure recommended |
+| **strict** | 10+ | Full ceremony: all signals, all stewards, all proof |
+
+### Configuration
+
+```json
+{
+  "validation": {
+    "gateModeThresholds": {
+      "bootstrap": 0,
+      "standard": 4,
+      "strict": 10
+    },
+    "bootstrapPassConditions": {
+      "requireTestsPass": true,
+      "requireDeliverablesExist": true,
+      "requireExitCodeZero": true
+    },
+    "testCommand": "pnpm test:repo"
+  }
+}
+```
+
+### Steward threshold fix
+
+`requireDocumentationStewardFromWave` and `requireIntegrationStewardFromWave`
+are now strictly respected. Previously, the documentation steward was required
+whenever component promotions were active, regardless of the threshold setting.
+
+### Migration from 0.9.3
+
+No breaking changes. Existing repos get bootstrap mode for waves 0-3 by default.
+To keep the old strict behavior for all waves, set:
+
+```json
+{
+  "validation": {
+    "gateModeThresholds": {
+      "bootstrap": 0,
+      "standard": 0,
+      "strict": 0
+    }
+  }
+}
+```

package/docs/guides/recommendations-0.9.6.md

@@ -0,0 +1,191 @@
+---
+title: "0.9.4 Recommendations"
+summary: "How to use 0.9.4's softer blocker states, advisory turn budgets, and targeted recovery without weakening proof and closure."
+---
+
+# 0.9.4 Recommendations
+
+Use this guide when you are adopting `0.9.4` and want one practical operating stance for the softer blocker states, advisory turn-budget behavior, and targeted recovery flow that the current package line ships.
+
+## Recommended Default
+
+For most repos, the safest `0.9.4` default is:
+
+- bound work with `budget.minutes`
+- leave generic `budget.turns` as advisory metadata
+- author non-proof follow-up as `soft`, `stale`, or `advisory` instead of silently treating every open record as a hard blocker
+- use `resolve-policy` when the answer already exists in repo policy or shipped docs
+- prefer targeted rerun or resume after timeout, max-turn, rate-limit, or missing-status outcomes instead of relaunching the whole wave
+- in short-lived sandboxes, prefer `wave submit`, `wave supervise`, `wave status`, and `wave wait` instead of binding the full run to one client shell
+- when a wave-gate dimension has a documented gap that is not an actionable blocker, use `gap` instead of `pass` or `blocked` — the runtime treats it as a conditional pass
+
+That recommendation matches the runtime:
+
+- executor launch metadata only emits hard turn-limit flags from `claude.maxTurns` or `opencode.steps`
+- open `stale` and `advisory` coordination records stay visible without reopening the active blocking edge
+- recoverable launcher failures queue targeted retry state instead of immediately escalating to broad terminal wave failure
+
+## 1. Budgets
+
+Treat the two budget knobs differently:
+
+- `budget.minutes` is the primary attempt budget
+- generic `budget.turns` is only a planning hint
+- `claude.maxTurns` or `opencode.steps` are the hard runtime ceilings when you actually want deterministic turn stopping
+
+Recommended pattern for synthesis-heavy implementation or closure work:
+
+```json
+{
+  "executors": {
+    "profiles": {
+      "implementation-default": {
+        "id": "claude",
+        "model": "claude-sonnet-4-6",
+        "budget": {
+          "minutes": 35,
+          "turns": 12
+        }
+      }
+    }
+  }
+}
+```
+
+In that pattern, `35` minutes is real policy. `12` turns is only guidance for planning and preview metadata.
+
+Only set a hard runtime ceiling when you deliberately want the runtime itself to stop:
+
+```json
+{
+  "executors": {
+    "profiles": {
+      "bounded-closure": {
+        "id": "claude",
+        "model": "claude-sonnet-4-6",
+        "budget": {
+          "minutes": 20
+        },
+        "claude": {
+          "maxTurns": 6
+        }
+      }
+    }
+  }
+}
+```
+
+## 2. Softer Coordination States
+
+`0.9.2` keeps “still visible” separate from “still blocking”.
+
+Use these states intentionally:
+
+| State | Use it for | What the runtime does |
+| --- | --- | --- |
+| `soft` | follow-up that still matters but should not be treated like proof failure | remains visible and may still drive repair or retry targeting |
+| `stale` | outdated clarification or blocker context kept for history | visible in control state, but does not reopen blocking by itself |
+| `advisory` | known issue, note, or human context that should stay visible without blocking closure | visible in control state, but does not own the active blocking edge |
+
+Practical command paths:
+
+```bash
+pnpm exec wave control task act defer --lane main --wave 10 --id blocker-doc-follow-up
+pnpm exec wave control task act mark-stale --lane main --wave 10 --id clarify-a7-rollout
+pnpm exec wave control task act mark-advisory --lane main --wave 10 --id request-clarify-a7-rollout
+pnpm exec wave control task act resolve-policy --lane main --wave 10 --id clarify-a7-rollout --detail "Policy already covered in the rollout guide."
+```
+
+Use them when the repo already knows the answer, the remaining item is informational, or the follow-up should stay visible for the next wave without holding the current wave hostage.
+
+## 3. What Should Stay Hard
+
+Do not relax everything.
+
+Keep these hard or closure-critical unless you are intentionally changing wave policy:
+
+- missing proof or required deliverables
+- failed integration, documentation, or cont-QA closure gates
+- real human-feedback or escalation requirements that block safe continuation
+- requests or clarifications that still represent unresolved ownership or policy ambiguity for the current wave
+
+Use `gap` in wave-gate markers when a dimension has a documented gap that is not actionable in the current wave. For example, `live=gap` is appropriate when an infrastructure topology constraint prevents full live validation but the constraint is known, documented, and does not represent a regression. Do not use `gap` to hide actual failures or unreviewed work.
+
+If the current wave cannot truthfully close without the answer, keep it blocking.
+
+## 4. Recovery Recommendation
+
+My recommendation after reviewing the current `0.9.4` code path is:
+
+- let timeout, max-turn, rate-limit, and missing-status failures go through the built-in targeted recovery path first
+- inspect the queued rerun or resume request before manually relaunching the whole wave
+- preserve reusable proof from successful sibling owners whenever the reducer already identified it as reusable
+
+That is the shape the launcher now prefers. It only broadens failure when the remaining blockers are still proof-critical or otherwise non-recoverable.
+
+## 5. Suggested Operator Policy
+
+For most repo-owned runbooks:
+
+- teach authors to use `budget.minutes` first
+- teach operators to downgrade only non-proof follow-up
+- treat `resolve-policy` as the preferred path when the answer already exists in docs or repo policy
+- escalate to a full-wave rerun only after targeted recovery proves insufficient
+
+If you want a single sentence policy:
+
+> Keep proof and closure strict, keep generic turns advisory, and keep non-proof context visible without letting it accidentally own wave closure.
+
+
+## Laddered Gate Modes (new in 0.9.4)
+
+Waves now have three gate strictness tiers based on wave number:
+
+| Mode | Default waves | What's required to advance |
+|------|--------------|---------------------------|
+| **bootstrap** | 0-3 | Implementation agents exit 0 + deliverables exist |
+| **standard** | 4-9 | + A0 verdict required, doc closure recommended |
+| **strict** | 10+ | Full ceremony: all signals, all stewards, all proof |
+
+### Configuration
+
+```json
+{
+  "validation": {
+    "gateModeThresholds": {
+      "bootstrap": 0,
+      "standard": 4,
+      "strict": 10
+    },
+    "bootstrapPassConditions": {
+      "requireTestsPass": true,
+      "requireDeliverablesExist": true,
+      "requireExitCodeZero": true
+    },
+    "testCommand": "pnpm test:repo"
+  }
+}
+```
+
+### Steward threshold fix
+
+`requireDocumentationStewardFromWave` and `requireIntegrationStewardFromWave`
+are now strictly respected. Previously, the documentation steward was required
+whenever component promotions were active, regardless of the threshold setting.
+
+### Migration from 0.9.3
+
+No breaking changes. Existing repos get bootstrap mode for waves 0-3 by default.
+To keep the old strict behavior for all waves, set:
+
+```json
+{
+  "validation": {
+    "gateModeThresholds": {
+      "bootstrap": 0,
+      "standard": 0,
+      "strict": 0
+    }
+  }
+}
+```

package/docs/plans/migration.md

@@ -1,6 +1,6 @@
 # Migration
 
-This page is the practical repo-upgrade guide for the current `0.9.4` surface.
+This page is the practical repo-upgrade guide for the current `0.9.6` surface.
 
 Use it when you are:
 
@@ -24,7 +24,7 @@ The `0.9.4` surface adds laddered gate modes and fixes the steward threshold enf
 
 ## What `0.9.4` Changes
 
-The current `0.9.4` surface keeps everything from `0.9.2` and adds two focused improvements with no breaking changes.
+The current `0.9.6` surface keeps everything from `0.9.2` and adds two focused improvements with no breaking changes.
 
 The practical changes are:
 
@@ -182,7 +182,7 @@ Use `pnpm exec wave dashboard --lane <lane> --attach current` or `--attach globa
 
 ## `0.9.4` Release Model
 
-The current `0.9.4` surface combines these strands:
+The current `0.9.6` surface combines these strands:
 
 - the gap-value wave-gate fix and first-time setup UX improvements released in `0.9.4`
 - the detached process-runner and sandbox supervisor hardening released in `0.9.2`
@@ -367,7 +367,7 @@ If your repo copied starter config defaults, also sync the `designRolePromptPath
 - hybrid design stewards rejoin implementation when they explicitly own code
 - long-running prompts receive signal-state and ack paths when the repo uses the new waiting model
 
-## Upgrading From `0.8.3` To `0.9.4`
+## Upgrading From `0.8.3` To `0.9.6`
 
 Treat this as one move to the current `0.9.2` surface.
 
@@ -402,7 +402,7 @@ If your repo copied starter docs or skills, sync:
 - dry-run one design-steward wave if the repo wants the new authored surface
 - if the repo uses long-running watcher agents or shell automation, validate `scripts/wave-status.sh` and `scripts/wave-watch.sh` against a live or staged lane
 
-## Upgrading From `0.6.x` Or `0.7.x` To `0.9.4`
+## Upgrading From `0.6.x` Or `0.7.x` To `0.9.6`
 
 This is the main migration path for older adopted repos.
 
@@ -553,4 +553,4 @@ For repos that depend on replay parity, replay at least:
 
 ## Summary
 
-The current `0.9.4` surface keeps the same authority-set and phase-engine architecture, ships both the design-role starter surface and the signal-driven long-running-agent starter surface, keeps the `0.8.7` policy and routing hardening, and now also packages the practical operator recommendations guide inside the release line. For most repos already on `0.8.x`, the upgrade is package bump plus validation. For older adopted repos, the real work is syncing repo-owned prompts, skills, planner corpus, wrapper scripts, and runbooks so they describe the runtime the package now ships.
+The current `0.9.6` surface keeps the same authority-set and phase-engine architecture, ships both the design-role starter surface and the signal-driven long-running-agent starter surface, keeps the `0.8.7` policy and routing hardening, and now also packages the practical operator recommendations guide inside the release line. For most repos already on `0.8.x`, the upgrade is package bump plus validation. For older adopted repos, the real work is syncing repo-owned prompts, skills, planner corpus, wrapper scripts, and runbooks so they describe the runtime the package now ships.

package/package.json

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

package/releases/manifest.json

@@ -2,6 +2,28 @@
   "schemaVersion": 1,
   "packageName": "@chllming/wave-orchestration",
   "releases": [
+    {
+      "version": "0.9.6",
+      "date": "2026-04-05",
+      "summary": "Fix closure engine unconditionally requiring integration/documentation steward runs for waves that don't declare them.",
+      "features": [
+        "The closure engine's `stageRequiresRun` now respects `requireIntegrationStewardFromWave` and `requireDocumentationStewardFromWave` thresholds. When set to null, the stage is only required if the wave declares the corresponding agent.",
+        "planner-agentic bundle placeholder remains available for adopted repos."
+      ],
+      "manualSteps": [],
+      "breaking": false
+    },
+    {
+      "version": "0.9.5",
+      "date": "2026-04-05",
+      "summary": "Hotfix: pass lanePaths to reconcileFailuresAgainstSharedComponentState, fixing launcher crash on repos without Integration Steward.",
+      "features": [
+        "Fixed ReferenceError where `lanePaths` was used as a free variable in `reconcileFailuresAgainstSharedComponentState` instead of being passed as a parameter.",
+        "planner-agentic bundle placeholder remains available for adopted repos."
+      ],
+      "manualSteps": [],
+      "breaking": false
+    },
     {
       "version": "0.9.4",
       "date": "2026-03-30",
@@ -556,4 +578,4 @@
       "breaking": false
     }
   ]
-}
+}

package/scripts/wave-orchestrator/closure-engine.mjs

@@ -95,8 +95,20 @@ function forwardedClosureGapRecord({
 
 function stageRequiresRun(stage, wave, lanePaths) {
   switch (stage.key) {
-    case "integration":
-    case "documentation":
+    case "integration": {
+      const threshold = lanePaths?.requireIntegrationStewardFromWave;
+      if (threshold === null || threshold === undefined) {
+        return Array.isArray(wave?.agents) && wave.agents.some((agent) => agent?.agentId === stage.agentId);
+      }
+      return wave.wave >= threshold;
+    }
+    case "documentation": {
+      const docThreshold = lanePaths?.requireDocumentationStewardFromWave;
+      if (docThreshold === null || docThreshold === undefined) {
+        return Array.isArray(wave?.agents) && wave.agents.some((agent) => agent?.agentId === stage.agentId);
+      }
+      return wave.wave >= docThreshold;
+    }
     case "cont-qa":
       return true;
     case "cont-eval":

package/scripts/wave-orchestrator/install.mjs

@@ -69,7 +69,7 @@ export const STARTER_TEMPLATE_PATHS = [
   "docs/guides/author-and-run-waves.md",
   "docs/guides/monorepo-projects.md",
   "docs/guides/planner.md",
-  "docs/guides/recommendations-0.9.4.md",
+  "docs/guides/recommendations-0.9.6.md",
   "docs/guides/sandboxed-environments.md",
   "docs/guides/signal-wrappers.md",
   "docs/guides/terminal-surfaces.md",

package/scripts/wave-orchestrator/launcher.mjs

@@ -1787,7 +1787,7 @@ export async function runLauncherCli(argv) {
           syncWaveSignals();
           lastLiveCoordinationRefreshAt = Date.now();
           emitCoordinationAlertEvents(derivedState);
-          failures = reconcileFailuresAgainstSharedComponentState(wave, agentRuns, failures);
+          failures = reconcileFailuresAgainstSharedComponentState(wave, agentRuns, failures, lanePaths);
           for (const failure of failures) {
             if (failure.statusCode === "shared-component-sibling-pending") {
               applySharedComponentWaitStateToDashboard(failure, dashboardState);

package/scripts/wave-orchestrator/retry-engine.mjs

@@ -276,7 +276,7 @@ export function applySharedComponentWaitStateToDashboard(componentGate, dashboar
   }
 }
 
-export function reconcileFailuresAgainstSharedComponentState(wave, agentRuns, failures) {
+export function reconcileFailuresAgainstSharedComponentState(wave, agentRuns, failures, lanePaths) {
   if (!Array.isArray(failures) || failures.length === 0) {
     return failures;
   }