New:Socket for Asana Is Now Available.Learn more →
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.7
 to
0.9.8
+137
docs/guides/recommendations-0.9.8.md
---
title: "0.9.8 Recommendations"
summary: "How to use 0.9.8's softer blocker states, advisory turn budgets, and targeted recovery without weakening proof and closure."
---
# 0.9.8 Recommendations
Use this guide when you are adopting `0.9.8` 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.8` 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.8` 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.
+9
-0
CHANGELOG.md

@@ -555,1 +555,10 @@ # Changelog

- Added Context7 bundle resolution and multi-executor support for Codex, Claude Code, and OpenCode.
## 0.9.8 - 2026-04-06
### Fixed
- Gate engine: bootstrap mode treats doc-closure, cont-QA, integration, and component gates as advisory (non-blocking) while impl gates remain required
- Gate engine: integration barrier short-circuits when no steward declared
- Claude executor defaults permissionMode to bypassPermissions (fixes Docker containers)
- Removed --search from codex exec invocations (unsupported by codex exec)
- Advisory failures tracked in gate snapshot for operator visibility
+6
-6
docs/plans/migration.md
# Migration
This page is the practical repo-upgrade guide for the current `0.9.7` surface.
This page is the practical repo-upgrade guide for the current `0.9.8` surface.

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

The current `0.9.7` surface keeps everything from `0.9.2` and adds two focused improvements with no breaking changes.
The current `0.9.8` 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.7` surface combines these strands:
The current `0.9.8` surface combines these strands:

@@ -372,3 +372,3 @@ - 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.7`
## Upgrading From `0.8.3` To `0.9.8`

@@ -408,3 +408,3 @@ Treat this as one move to the current `0.9.2` surface.

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

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

The current `0.9.7` 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.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.
+3
-1
docs/README.md

@@ -57,3 +57,5 @@ # Wave Documentation

- Want the practical `0.9.3` operating stance:
Read [guides/recommendations-0.9.7.md](./guides/recommendations-0.9.7.md) for the recommended default around relaxed blocker states, advisory turn budgets, and targeted recovery.
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.
- Want the concrete runtime module map:

@@ -60,0 +62,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.7",
"version": "0.9.8",
"license": "MIT",

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

+1
-1
scripts/wave-orchestrator/config.mjs

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

),
permissionMode: normalizeOptionalString(executors.claude?.permissionMode, null),
permissionMode: normalizeOptionalString(executors.claude?.permissionMode, "bypassPermissions"),
permissionPromptTool: normalizeOptionalString(

@@ -1086,0 +1086,0 @@ executors.claude?.permissionPromptTool,

+0
-1
scripts/wave-orchestrator/executors.mjs

@@ -196,3 +196,2 @@ import { spawnSync } from "node:child_process";

appendRepeatedFlag(tokens, "-c", options.config);
appendBooleanFlag(tokens, "--search", options.search);
appendRepeatedFlag(tokens, "--image", options.images);

@@ -199,0 +198,0 @@ appendRepeatedFlag(tokens, "--add-dir", options.addDirs);

+21
-2
scripts/wave-orchestrator/gate-engine.mjs

@@ -1555,2 +1555,4 @@ import fs from "node:fs";

if (!integrationMarkerGate.ok) { return integrationMarkerGate; }
// Short-circuit: no integration steward declared and not required
if (!integrationMarkerGate.agentId) { return integrationMarkerGate; }
const integrationSummary = derivedState?.integrationSummary || null;

@@ -1606,3 +1608,16 @@ if (!integrationSummary) {

];
const firstFailure = orderedGates.find(([, gate]) => gate?.ok === false);
const gateMode = laneConfig.gateMode || "strict";
// In bootstrap mode, these gates are advisory (non-blocking)
const bootstrapAdvisoryGates = new Set([
"documentationGate", "contQaGate", "integrationBarrier",
"componentMatrixGate", "componentGate",
]);
const firstFailure = orderedGates.find(([name, gate]) => {
if (!gate || gate.ok !== false) return false;
if (gateMode === "bootstrap" && bootstrapAdvisoryGates.has(name)) return false;
return true;
});
const advisoryFailures = gateMode === "bootstrap"
? orderedGates.filter(([name, gate]) => gate?.ok === false && bootstrapAdvisoryGates.has(name))
: [];
return {

@@ -1613,2 +1628,4 @@ designGate, implementationGate, componentGate, integrationGate: integrationMarkerGate,

clarificationBarrier, helperAssignmentBarrier, dependencyBarrier,
gateMode,
advisoryFailures: advisoryFailures.map(([name, gate]) => ({ gate: name, ...gate })),
overall: firstFailure

@@ -1618,4 +1635,6 @@ ? { ok: false, gate: firstFailure[0], statusCode: firstFailure[1].statusCode,

: { ok: true, gate: "pass", statusCode: "pass",
detail: "All replayed wave gates passed.", agentId: null },
detail: gateMode === "bootstrap"
? `Bootstrap pass: impl gates passed (${advisoryFailures.length} advisory).`
: "All replayed wave gates passed.", agentId: null },
};
}