Sign In

@chllming/wave-orchestration

Package Overview
Dependencies
Maintainers
1
Versions
38
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@chllming/wave-orchestration - npm Package Compare versions

Comparing version
0.9.8
 to
0.9.9
+137
docs/guides/recommendations-0.9.9.md
---
title: "0.9.9 Recommendations"
summary: "How to use 0.9.9's softer blocker states, advisory turn budgets, and targeted recovery without weakening proof and closure."
---
# 0.9.9 Recommendations
Use this guide when you are adopting `0.9.9` 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.9` 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.9` 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.
+45
-26
CHANGELOG.md
# Changelog
## Unreleased
## 0.9.9 - 2026-04-07
### Fixed
- Helper assignment barrier is now advisory (non-blocking) in bootstrap gate mode. Previously, open helper assignments blocked wave closure even when the assigned agent completed successfully with exit 0, causing unnecessary retries. In bootstrap mode, assigned-but-open helper requests are downgraded to advisory warnings with statusCode `helper-assignment-open-advisory`. Unresolved assignments (no assignee) remain blocking in all gate modes.
## 0.9.8 - 2026-04-06
### Added
- `wave self-update` command for in-place package upgrades with release notes display.
- Upgrade history tracking in `.wave/upgrade-history/` with per-upgrade reports including workspace impact analysis and follow-up actions.
- Bootstrap advisory gates: in bootstrap mode (waves 0–3), doc-closure, cont-QA, integration, and component gates are advisory (non-blocking) while implementation gates remain required. Advisory failures are tracked in the gate snapshot for visibility.
- `docs/guides/recommendations-0.9.8.md` recommendations guide.
### Fixed
- Integration barrier now short-circuits when no A8 steward is declared (`agentId: null`), fixing `missing-integration-summary` failures on waves without an integration agent.
- Default `claude.permissionMode` to `bypassPermissions` (fixes Docker container environments where interactive permission prompts hang).
- Removed `--search` flag from codex exec invocations (unsupported by `codex exec`).
- Relaxed release-surface test version checks while keeping changelog checks strict (#64).
- Updated executor test — `--search` not supported in codex exec (#63).
### Changed
- `wave upgrade` now records install-state transitions and generates upgrade reports.
## 0.9.7 - 2026-04-06
### Fixed
- Closure engine now skips missing-closure-run failures in bootstrap gate mode.
- `gateModeThresholds` is now exposed on the `lanePaths` object for downstream consumers.
- Closure engine now skips missing-closure-run failures when the resolved gate mode is `bootstrap`, allowing waves to pass when agents complete but tmux status reconciliation fails.
- `gateModeThresholds` is now exposed on the `lanePaths` object so downstream consumers (closure engine, derived state) can resolve the active gate mode.

@@ -14,3 +36,3 @@ ## 0.9.6 - 2026-04-05

### Fixed
- Closure engine now respects `requireIntegrationStewardFromWave` and `requireDocumentationStewardFromWave` thresholds instead of unconditionally requiring integration/documentation closure runs.
- Closure engine now respects `requireIntegrationStewardFromWave` and `requireDocumentationStewardFromWave` thresholds instead of unconditionally requiring integration/documentation steward runs for waves that don't declare them. When set to `null`, the stage is only required if the wave declares the corresponding agent.

@@ -20,34 +42,31 @@ ## 0.9.5 - 2026-04-05

### Fixed
- Pass `lanePaths` to `reconcileFailuresAgainstSharedComponentState` to fix `ReferenceError` crash on repos without Integration Steward (A8).
- Pass `lanePaths` to `reconcileFailuresAgainstSharedComponentState`, fixing `ReferenceError` crash on repos without Integration Steward (A8).
## 0.9.4 - 2026-04-05
- Laddered gate modes: bootstrap/standard/strict per wave number
- Bootstrap pass: exit 0 + deliverables exist = advance (no QA signals needed)
- Fix: requireDocumentationStewardFromWave threshold strictly respected
- New config: gateModeThresholds, bootstrapPassConditions, testCommand
- evaluateBootstrapGate() and resolveGateMode() functions
### Added
- Laddered gate modes: `bootstrap` (waves 0–3), `standard` (waves 4–9), `strict` (waves 10+) per wave number via `gateModeThresholds` config.
- Bootstrap pass conditions: `exit 0 + deliverables exist = advance` — no QA signals required in early waves.
- New config fields: `gateModeThresholds`, `bootstrapPassConditions`, `testCommand`.
- `evaluateBootstrapGate()` and `resolveGateMode()` functions for gate-mode resolution.
- `docs/guides/recommendations-0.9.4.md` recommendations guide.
### Fixed
- `requireDocumentationStewardFromWave` threshold now strictly respected during validation. Was previously OR'd with `componentPromotionRuleActive`, ignoring the threshold.
## 0.9.3 - 2026-03-30
### Fixed And Hardened
- `WAVE_GATE_REGEX` now accepts `gap` alongside `pass|concerns|blocked` for all five gate dimensions (architecture, integration, durability, live, docs). Previously, agents that reported a documented gap (e.g. `live=gap` for an infrastructure topology constraint) had their marker rejected entirely, causing missing-wave-gate failures that prevented wave closure.
- `validateContQaSummary` now treats gap dimension values as a conditional pass (`ok: true`, `statusCode: conditional-pass`) instead of a hard blocker, with detail text listing which dimensions have documented gaps.
- The cont-QA coordination prompt now documents `gap` as a valid dimension value alongside `pass|concerns|blocked`.
- Migration sections aligned and install seeding updated to target 0.9.3 correctly.
- Planner-agentic note added to 0.9.3 manifest entry.
- WAVE_GATE_REGEX now accepts gap alongside pass|concerns|blocked for all five gate dimensions (architecture, integration, durability, live, docs). Previously, agents that reported a documented gap (e.g. live=gap for an infrastructure topology constraint) had their marker rejected entirely, causing missing-wave-gate failures that prevented wave closure.
- validateContQaSummary now treats gap dimension values as a conditional pass (ok: true, statusCode: conditional-pass) instead of a hard blocker, with detail text listing which dimensions have documented gaps.
- The cont-QA coordination prompt now documents gap as a valid dimension value alongside pass|concerns|blocked.
### Added
- First-time wave launch now auto-triggers `wave project setup` when no project profile exists, matching existing `wave draft` behavior.
- `wave project setup` now shows descriptive help text before each prompt, explains all template and posture options inline, and adds whitespace between question groups for readability.
- `PromptSession` gains a `describe(text)` method for writing contextual help to stderr during interactive setup flows.
- `parseArgs` now passes the loaded config object through to `runLauncherCli`, avoiding a redundant `loadWaveConfig()` call.
- First-time wave launch now auto-triggers wave project setup when no project profile exists, matching existing wave draft behavior. (Contributed by @justanothernate in #54)
- wave project setup now shows descriptive help text before each prompt, explains all template and posture options inline, and adds whitespace between question groups for readability. (Contributed by @justanothernate in #54)
- PromptSession gains a describe(text) method for writing contextual help to stderr during interactive setup flows.
- parseArgs now passes the loaded config object through to runLauncherCli, avoiding a redundant loadWaveConfig() call.
### Testing And Validation
- `pnpm exec vitest run --config vitest.config.ts`
- `node scripts/wave.mjs doctor --json`
- `node scripts/wave.mjs launch --lane main --dry-run --no-dashboard`
- `pnpm test -- test/wave-orchestrator/release-surface.test.ts`
## 0.9.2 - 2026-03-29

@@ -54,0 +73,0 @@ 

+10
-6
docs/plans/migration.md
# Migration
This page is the practical repo-upgrade guide for the current `0.9.8` surface.
This page is the practical repo-upgrade guide for the current `0.9.9` surface.

@@ -27,3 +27,3 @@ Use it when you are:

The current `0.9.8` surface keeps everything from `0.9.2` and adds two focused improvements with no breaking changes.
The current `0.9.9` surface keeps everything from `0.9.2` and adds two focused improvements with no breaking changes.

@@ -186,3 +186,3 @@ The practical changes are:

The current `0.9.8` surface combines these strands:
The current `0.9.9` surface combines these strands:

@@ -372,4 +372,8 @@ - the gap-value wave-gate fix and first-time setup UX improvements released in `0.9.4`

## Upgrading From `0.8.3` To `0.9.8`
## Upgrading From `0.9.8` To `0.9.9`
Helper assignment barriers are now advisory in bootstrap gate mode. No config changes needed.
## Upgrading From `0.8.3` To `0.9.9`
Treat this as one move to the current `0.9.2` surface.

@@ -408,3 +412,3 @@

## Upgrading From `0.6.x` Or `0.7.x` To `0.9.8`
## Upgrading From `0.6.x` Or `0.7.x` To `0.9.9`

@@ -560,2 +564,2 @@ This is the main migration path for older adopted repos.

The current `0.9.8` 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.9` 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.
+4
-2
docs/README.md

@@ -58,4 +58,6 @@ # Wave Documentation

Read [guides/recommendations-0.9.7
- [0.9.8 Operating Recommendations](guides/recommendations-0.9.8.md).md](./guides/recommendations-0.9.7
- [0.9.8 Operating Recommendations](guides/recommendations-0.9.8.md).md) for the recommended default around relaxed blocker states, advisory turn budgets, and targeted recovery.
- [0.9.8 Operating Recommendations](guides/recommendations-0.9.8.md
- [0.9.9 Recommendations](guides/recommendations-0.9.9.md)).md](./guides/recommendations-0.9.7
- [0.9.8 Operating Recommendations](guides/recommendations-0.9.8.md
- [0.9.9 Recommendations](guides/recommendations-0.9.9.md)).md) for the recommended default around relaxed blocker states, advisory turn budgets, and targeted recovery.
- Want the concrete runtime module map:

@@ -62,0 +64,0 @@ Read [plans/end-state-architecture.md](./plans/end-state-architecture.md) for the engine-by-engine architecture and artifact ownership model.

+1
-1
package.json
{
"name": "@chllming/wave-orchestration",
"version": "0.9.8",
"version": "0.9.9",
"license": "MIT",

@@ -5,0 +5,0 @@ "description": "Generic wave-based multi-agent orchestration for repository work.",

+12
-1
releases/manifest.json

@@ -6,2 +6,13 @@ {

{
"version": "0.9.9",
"date": "2026-04-07",
"summary": "Helper assignment barrier is advisory in bootstrap gate mode; planner-agentic bundle remains available.",
"features": [
"Helper assignment barrier is now advisory (non-blocking) in bootstrap gate mode, preventing unnecessary retries when assigned agents complete successfully.",
"planner-agentic bundle placeholder remains available for adopted repos."
],
"manualSteps": [],
"breaking": false
},
{
"version": "0.9.7",

@@ -594,2 +605,2 @@ "date": "2026-04-06",

]
}
}
+9
-1
scripts/wave-orchestrator/gate-engine.mjs

@@ -1141,3 +1141,4 @@ import fs from "node:fs";

export function readWaveAssignmentBarrier(derivedState) {
export function readWaveAssignmentBarrier(derivedState, options) {
const gateMode = options?.gateMode || null;
const blockingAssignments = (derivedState?.capabilityAssignments || []).filter(

@@ -1161,2 +1162,9 @@ (assignment) => assignment.blocking,

}
if (gateMode === "bootstrap") {
return {
ok: true,
statusCode: "helper-assignment-open-advisory",
detail: `Helper assignments remain open but are advisory in bootstrap gate mode (${blockingAssignments.map((assignment) => assignment.requestId).join(", ")}).`,
};
}
return {

@@ -1163,0 +1171,0 @@ ok: false,

+4
-1
scripts/wave-orchestrator/wave-state-reducer.mjs

@@ -22,2 +22,3 @@ import { materializeControlPlaneState } from "./control-plane.mjs";

readWaveAssignmentBarrier,
resolveGateMode,
} from "./gate-engine.mjs";

@@ -717,3 +718,5 @@ import { buildHumanInputRequests } from "./human-input-workflow.mjs";

);
const helperAssignmentBarrier = readWaveAssignmentBarrier({ capabilityAssignments });
const _reducerGateThresholds = laneConfig?.gateModeThresholds || laneConfig?.validation?.gateModeThresholds || null;
const _reducerGateMode = resolveGateMode(waveDefinition?.wave || 0, _reducerGateThresholds);
const helperAssignmentBarrier = readWaveAssignmentBarrier({ capabilityAssignments }, { gateMode: _reducerGateMode });
const dependencyBarrier = (() => {

@@ -720,0 +723,0 @@ if (!dependencyTickets) {