@chllming/wave-orchestration 0.9.10 → 0.9.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. package/CHANGELOG.md +27 -0
  2. package/README.md +7 -8
  3. package/docs/README.md +4 -10
  4. package/docs/architecture/README.md +12 -4
  5. package/docs/concepts/operating-modes.md +1 -1
  6. package/docs/guides/author-and-run-waves.md +3 -2
  7. package/docs/guides/planner.md +3 -3
  8. package/docs/guides/recommendations-0.9.11.md +44 -0
  9. package/docs/guides/recommendations-0.9.12.md +49 -0
  10. package/docs/guides/sandboxed-environments.md +2 -2
  11. package/docs/guides/terminal-surfaces.md +1 -1
  12. package/docs/plans/current-state.md +3 -3
  13. package/docs/plans/end-state-architecture.md +1 -1
  14. package/docs/plans/examples/wave-example-design-handoff.md +1 -1
  15. package/docs/plans/examples/wave-example-live-proof.md +1 -1
  16. package/docs/plans/migration.md +32 -28
  17. package/docs/plans/wave-orchestrator.md +1 -1
  18. package/docs/reference/cli-reference.md +2 -2
  19. package/docs/reference/coordination-and-closure.md +1 -1
  20. package/docs/reference/npmjs-token-publishing.md +2 -2
  21. package/docs/reference/package-publishing-flow.md +12 -12
  22. package/docs/reference/runtime-config/README.md +2 -2
  23. package/docs/reference/sample-waves.md +5 -5
  24. package/docs/reference/skills.md +1 -1
  25. package/docs/reference/wave-control.md +3 -1
  26. package/docs/roadmap.md +3 -3
  27. package/package.json +1 -1
  28. package/releases/manifest.json +32 -0
  29. package/scripts/wave-orchestrator/agent-state.mjs +3 -1
  30. package/scripts/wave-orchestrator/autonomous.mjs +2 -2
  31. package/scripts/wave-orchestrator/closure-engine.mjs +103 -6
  32. package/scripts/wave-orchestrator/closure-policy.mjs +319 -0
  33. package/scripts/wave-orchestrator/config.mjs +15 -0
  34. package/scripts/wave-orchestrator/derived-state-engine.mjs +52 -4
  35. package/scripts/wave-orchestrator/gate-engine.mjs +72 -4
  36. package/scripts/wave-orchestrator/install.mjs +1 -1
  37. package/scripts/wave-orchestrator/launcher.mjs +14 -4
  38. package/scripts/wave-orchestrator/planner.mjs +4 -3
  39. package/scripts/wave-orchestrator/shared.mjs +11 -12
  40. package/scripts/wave-orchestrator/swe-bench-pro-task.mjs +1 -1
  41. package/scripts/wave-orchestrator/traces.mjs +22 -1
  42. package/wave.config.json +13 -2
package/CHANGELOG.md CHANGED
@@ -1,5 +1,32 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.9.12 - 2026-04-08
4
+
5
+ ### Added
6
+ - `docs/guides/recommendations-0.9.12.md` with the current operating guidance for advisory turn budgets, targeted recovery, low-entropy closure, and optional TMUX operator surfaces.
7
+
8
+ ### Changed
9
+ - TMUX is now described consistently as an optional dashboard/projection layer across setup, launcher help, autonomous help, runbooks, and examples. Live agents remain process-backed, and `tmux + --no-dashboard` now emits an explicit informational note instead of implying TMUX is part of the execution backend.
10
+ - Wave Control's browser surface now uses a dashboard-first information architecture with `Dashboard`, `Operations`, `Access`, and `Account` views, cleaner section navigation, and richer summaries for runs, benchmarks, and access review work.
11
+ - Release docs, migration guidance, runtime-config references, package-publishing docs, the release manifest, and tracked install-state fixtures now align on the `0.9.12` surface.
12
+
13
+ ### Fixed
14
+ - Bootstrap closure no longer silently skips a missing `cont-QA` run after semantic closure stewards already ran. The low-entropy fast path now stays limited to genuinely lightweight closure attempts.
15
+ - `closureModeThresholds.bootstrap` now participates in runtime mode resolution instead of being normalized and then ignored.
16
+ - Derived `closureComplexity` now incorporates clarification, helper-assignment, dependency, and contradiction barriers so emitted closure metadata matches the real closure state machine.
17
+ - Wave Control benchmark and run projections now expose richer status, comparison-readiness, item, review, and verification rollups for both API consumers and the browser UI.
18
+ - `normalizeWaveVerdict()` now preserves `hold` as its own verdict instead of collapsing it into `concerns`, which brings the shared parser back in line with the shipped verdict grammar and tests.
19
+
20
+ ## 0.9.11 - 2026-04-07
21
+
22
+ ### Fixed
23
+ - **Verdict parsing: first-match-wins** — `parseVerdictFromText()` now returns the **first** regex match instead of the last. In append-only cont-QA report files, stale `Verdict: BLOCKED` entries from earlier attempts would linger at the bottom of the file while newer `Verdict: PASS` entries were written above them. The last-match-wins behavior caused the cont-QA gate to read the stale blocked verdict, creating an infinite retry loop. This was the root cause of 17 blocked waves in React Word Editor (DOCX W20+).
24
+ - **Log verdict priority over report verdict** — `buildAgentExecutionSummary()` now prefers the log-based `[wave-verdict]` marker over the report file `Verdict:` line. The log is authoritative for the current run, while report files may accumulate conflicting entries across retry attempts.
25
+ - **Integration steward closure is now sticky** — When the integration steward (A8) explicitly reports `state=ready-for-doc-closure` with zero blockers, synthesized proof gaps and doc gaps from implementation agent validation are cleared from the integration summary. Previously, `buildWaveIntegrationSummary()` would re-inject gaps derived from agent summaries on every `refreshDerivedState()` call, overriding the steward's explicit sign-off and causing unnecessary retry cycles (observed as 15+ loops in DOCX W20).
26
+
27
+ ### Added
28
+ - Test suite for `parseVerdictFromText` covering first-match behavior, null/empty inputs, multi-verdict report files, and `[wave-verdict]` marker parsing.
29
+
3
30
  ## 0.9.10 - 2026-04-07
4
31
 
5
32
  ### Fixed
package/README.md CHANGED
@@ -107,18 +107,17 @@ Wave is built to mitigate those failures with a canonical authority set, generat
107
107
 
108
108
  Current release:
109
109
 
110
- - `@chllming/wave-orchestration@0.9.7`
111
- - Release tag: [`v0.9.5`](https://github.com/chllming/agent-wave-orchestrator/releases/tag/v0.9.7)
110
+ - `@chllming/wave-orchestration@0.9.12`
111
+ - Release tag: [`v0.9.12`](https://github.com/chllming/agent-wave-orchestrator/releases/tag/v0.9.12)
112
112
  - Public install path: npmjs
113
113
  - Authenticated fallback: GitHub Packages
114
114
 
115
- Highlights in `0.9.4`:
115
+ Highlights in `0.9.12`:
116
116
 
117
- - Wave-gate markers now accept `gap` alongside `pass`, `concerns`, and `blocked` for all five gate dimensions. Agents that report a documented gap (e.g. `live=gap` for an infrastructure topology constraint) no longer have their marker rejected entirely, and `cont-QA` treats gap values as a conditional pass instead of a hard blocker.
118
- - First-time `wave launch` now auto-triggers `wave project setup` when no project profile exists, matching existing `wave draft` behavior. The interactive setup flow now shows descriptive help text, explains all template and posture options inline, and adds whitespace between question groups for readability.
119
- - `PromptSession` gains a `describe(text)` method for writing contextual help to stderr during interactive setup flows.
120
- - `parseArgs` now passes the loaded config object through to `runLauncherCli`, avoiding a redundant `loadWaveConfig()` call.
121
- - Release docs, migration guidance, runtime-config and closure references, the manifest, and the tracked install-state fixtures now all point at the `0.9.4` surface.
117
+ - Closure bootstrap mode now has a real low-entropy fast path: missing `cont-QA` runs are skipped only when semantic closure did not already escalate into the deeper steward path, and the closure-mode thresholds now apply consistently across launcher, closure, and derived-state logic.
118
+ - TMUX is now documented and surfaced consistently as an optional dashboard/projection layer. Live agents remain process-backed, and `tmux + --no-dashboard` now prints an explicit note instead of implying a mandatory tmux runtime.
119
+ - Wave Control's browser surface now defaults to a dashboard-first information architecture with clearer `Dashboard`, `Operations`, `Access`, and `Account` navigation, plus richer run and benchmark analytics summaries for operators.
120
+ - Release docs, migration guidance, runtime-config and closure references, the manifest, and the tracked install-state fixtures now all point at the `0.9.12` surface.
122
121
 
123
122
  Requirements:
124
123
 
package/docs/README.md CHANGED
@@ -17,7 +17,7 @@ The useful path is journey-first:
17
17
  - `docs/concepts/`
18
18
  Mental models and architecture. Read these first if you want to understand what a wave is, how runtime-agnostic execution works, or how Context7 differs from skills.
19
19
  - `docs/guides/`
20
- Task-oriented workflows. Use these when you need to set up the planner, choose an operating mode, or decide how to run tmux and terminal surfaces.
20
+ Task-oriented workflows. Use these when you need to set up the planner, choose an operating mode, or pick an operator terminal surface such as optional tmux-backed dashboards.
21
21
  - `docs/reference/`
22
22
  Exact command, config, and file-format details. Use this when you need precise key names, runtime options, or bundle structure.
23
23
  - `docs/plans/`
@@ -38,7 +38,7 @@ The useful path is journey-first:
38
38
  - Setting up multiple projects in one monorepo:
39
39
  Read [guides/monorepo-projects.md](./guides/monorepo-projects.md) for `defaultProject`, `projects.<projectId>`, project-scoped state paths, and telemetry defaults.
40
40
  - Adding an optional pre-implementation design steward:
41
- Read [guides/author-and-run-waves.md](./guides/author-and-run-waves.md), then the standing prompt in [agents/wave-design-role.md](./agents/wave-design-role.md). The shipped `0.9.3` surface includes `role-design` plus `tui-design`, with docs-first design stewards by default and explicit hybrid design stewards when a wave also gives that same agent code ownership.
41
+ Read [guides/author-and-run-waves.md](./guides/author-and-run-waves.md), then the standing prompt in [agents/wave-design-role.md](./agents/wave-design-role.md). The shipped `0.9.12` surface includes `role-design` plus `tui-design`, with docs-first design stewards by default and explicit hybrid design stewards when a wave also gives that same agent code ownership.
42
42
  - Running in LEAPclaw, OpenClaw, Nemoshell, Docker, or another short-lived sandbox:
43
43
  Read [guides/sandboxed-environments.md](./guides/sandboxed-environments.md) first for the submit or supervise pattern, persistent-state expectations, and dashboard guidance, then use [plans/sandbox-end-state-architecture.md](./plans/sandbox-end-state-architecture.md) for the deeper runtime design.
44
44
  - Want signal-driven automation or long-running watcher loops:
@@ -53,14 +53,8 @@ The useful path is journey-first:
53
53
  Read [plans/migration.md](./plans/migration.md), then review the release notes in [../CHANGELOG.md](../CHANGELOG.md) before running `pnpm exec wave upgrade`.
54
54
  - Publishing the package:
55
55
  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.
56
- - Want the practical `0.9.3` operating stance:
57
- Read [guides/recommendations-0.9.7
58
- - [0.9.8 Operating Recommendations](guides/recommendations-0.9.8.md
59
- - [0.9.9 Recommendations](guides/recommendations-0.9.9.md
60
- - [0.9.10 Recommendations](guides/recommendations-0.9.10.md))).md](./guides/recommendations-0.9.7
61
- - [0.9.8 Operating Recommendations](guides/recommendations-0.9.8.md
62
- - [0.9.9 Recommendations](guides/recommendations-0.9.9.md
63
- - [0.9.10 Recommendations](guides/recommendations-0.9.10.md))).md) for the recommended default around relaxed blocker states, advisory turn budgets, and targeted recovery.
56
+ - Want the practical `0.9.12` operating stance:
57
+ Read [guides/recommendations-0.9.12.md](./guides/recommendations-0.9.12.md) for the recommended default around advisory turn budgets, targeted recovery, low-entropy closure, and optional TMUX operator surfaces.
64
58
  - Want the concrete runtime module map:
65
59
  Read [plans/end-state-architecture.md](./plans/end-state-architecture.md) for the engine-by-engine architecture and artifact ownership model.
66
60
  - Want the CLI surface map:
@@ -137,7 +137,7 @@ Multi-agent coding systems fail in predictable ways documented in recent researc
137
137
  - `wave-state-reducer.mjs`: Rebuilds full deterministic wave state from canonical sources
138
138
 
139
139
  **Layer 3 -- Supervisor and Projection Writer** (side effects)
140
- - `session-supervisor.mjs`: Launches processes, manages tmux sessions, writes observed lifecycle events (`agent_run.started`, `agent_run.completed`)
140
+ - `session-supervisor.mjs`: Launches process-backed runs, manages optional tmux dashboard/projection sessions, writes observed lifecycle events (`agent_run.started`, `agent_run.completed`)
141
141
  - `projection-writer.mjs`: Persists all human-facing projections (dashboards, traces, boards, summaries, inboxes, ledgers)
142
142
  - `signals.mjs`: Writes versioned signal-state projections for long-running agents
143
143
 
@@ -307,7 +307,7 @@ For each wave in the selected range:
307
307
  then transition to implementation agents.
308
308
 
309
309
  6. For each selected agent run:
310
- a. launchAgentSession() -- build prompt, resolve skills, create tmux session
310
+ a. launchAgentSession() -- build prompt, resolve skills, launch the process-backed agent run
311
311
  b. recordAgentRunStarted() -- supervisor writes control-plane event
312
312
 
313
313
  7. waitForWaveCompletion()
@@ -342,7 +342,7 @@ For each wave in the selected range:
342
342
  ### Phase 3: Cleanup
343
343
 
344
344
  ```
345
- -> cleanupLaneTmuxSessions() -- kill tmux sessions (unless --keep-sessions)
345
+ -> cleanupLaneTmuxSessions() -- clean up tmux dashboard/projection sessions (unless --keep-sessions)
346
346
  -> removeLaneTemporaryTerminalEntries() -- clean terminal registry
347
347
  -> releaseLauncherLock() -- release lock for other launchers
348
348
  ```
@@ -521,7 +521,15 @@ This is enforced by the `closure-engine.mjs` module. The launcher cannot bypass
521
521
 
522
522
  ### How the Closure Sweep Executes
523
523
 
524
- The sweep is sequential and staged. Each stage launches a closure agent, waits for it to complete, evaluates the gate, and only proceeds to the next stage if the gate passes. This is implemented in `runClosureSweepPhase()`.
524
+ The sweep is sequential and staged for semantic closure work. Each required closure stage launches its steward, waits for it to complete, evaluates the gate, and only proceeds to the next stage if the gate passes. This is implemented in `runClosureSweepPhase()`.
525
+
526
+ Low-entropy waves now use a closure fast-path before any steward is launched:
527
+
528
+ - `closure-policy.mjs` can auto-satisfy integration from derived state when no contradictions, helper assignments, dependency barriers, security blockers, interface drift, or deploy risks remain.
529
+ - Documentation closure can auto-satisfy as `no-change` when no shared-plan or component-matrix delta remains, and can auto-close mechanical component-matrix reconciliation when the canonical matrix is already current.
530
+ - cont-QA can be skipped only in bootstrap closure mode, and only when no semantic closure steward had to run.
531
+
532
+ If the fast-path does not prove closure, the runtime falls back to the normal staged steward sequence below.
525
533
 
526
534
  ```
527
535
  ┌─────────────────────────────────────────────────────────────────────┐
@@ -88,4 +88,4 @@ The current roadmap is a release-direction document, not a backlog of planner ph
88
88
  - typed values in planner output
89
89
  - better environment modeling
90
90
 
91
- The stricter execution semantics are still future work, not a hidden already-finished feature in `0.9.2`.
91
+ The stricter execution semantics are still future work, not a hidden already-finished feature in `0.9.12`.
@@ -74,7 +74,7 @@ Good fits:
74
74
  - multi-owner waves where downstream implementers need the same decisions and assumptions
75
75
  - ambiguous tasks where open questions should become explicit before code owners fan out
76
76
 
77
- The starter contract in `0.9.2` is:
77
+ The starter contract in `0.9.12` is:
78
78
 
79
79
  - import `docs/agents/wave-design-role.md`
80
80
  - own one packet such as `docs/plans/waves/design/wave-<n>-<agentId>.md`
@@ -148,6 +148,7 @@ When the dry-run artifacts look correct, launch the wave with the operator surfa
148
148
 
149
149
  ```bash
150
150
  pnpm exec wave launch --lane main --start-wave 1 --end-wave 1 --terminal-surface vscode
151
+ pnpm exec wave launch --lane main --start-wave 1 --end-wave 1 --no-dashboard
151
152
  pnpm exec wave launch --lane main --start-wave 1 --end-wave 1 --terminal-surface tmux --keep-sessions
152
153
  ```
153
154
 
@@ -156,7 +157,7 @@ Useful flags:
156
157
  - `--no-dashboard`
157
158
  Skip the dashboard session.
158
159
  - `--keep-sessions`
159
- Preserve tmux sessions for inspection after the wave completes.
160
+ Preserve tmux dashboard and projection sessions for inspection after the wave completes.
160
161
  - `--keep-terminals`
161
162
  Preserve temporary VS Code terminal entries.
162
163
 
@@ -6,7 +6,7 @@ If you want the full author-to-launch workflow, start with [author-and-run-waves
6
6
 
7
7
  It reduces repeated setup questions, stores project defaults, and generates wave specs plus markdown that already fit the launcher.
8
8
 
9
- The published `0.9.2` package already includes the optional `design` worker role for pre-implementation design packets. This guide calls out where that affects drafting.
9
+ The published `0.9.12` package already includes the optional `design` worker role for pre-implementation design packets. This guide calls out where that affects drafting.
10
10
 
11
11
  ## What Ships Today
12
12
 
@@ -48,7 +48,7 @@ pnpm exec wave launch --lane main --dry-run --no-dashboard
48
48
  - forward replanning of later waves
49
49
  - separate runtime enforcement for oversight vs dark-factory
50
50
 
51
- Those remain future work outside the current `0.9.2` release line. The planner foundation is about better structured authoring, not a second execution engine.
51
+ Those remain future work outside the current `0.9.12` release line. The planner foundation is about better structured authoring, not a second execution engine.
52
52
 
53
53
  ## Project Profile
54
54
 
@@ -70,7 +70,7 @@ The saved profile remembers:
70
70
 
71
71
  - whether the repo is a new project
72
72
  - default oversight mode
73
- - default terminal surface for live runs (`vscode` or `tmux`; `none` remains dry-run only)
73
+ - default terminal surface for live runs (`vscode` or `tmux`; `none` remains dry-run only). This is an operator viewing preference, not the agent execution backend.
74
74
  - default draft template
75
75
  - default lane
76
76
  - typed deploy environments
@@ -0,0 +1,44 @@
1
+ # Recommendations for 0.9.11
2
+
3
+ ## Upgrade
4
+
5
+ ```bash
6
+ wave self-update
7
+ # or: npm install -g @chllming/wave-orchestration@0.9.11
8
+ ```
9
+
10
+ ## What changed
11
+
12
+ ### Verdict parsing (P0 fix)
13
+
14
+ The `parseVerdictFromText()` function now returns the **first** regex match instead of the last. This fixes a critical bug where append-only cont-QA report files accumulated `Verdict:` lines across retries, and the stale `Verdict: BLOCKED` at the bottom would override newer `Verdict: PASS` entries above it.
15
+
16
+ **If you have waves stuck in cont-QA retry loops**, upgrading to 0.9.11 should unblock them on the next attempt. No manual intervention needed — the runner will re-evaluate the gate with the fixed parser.
17
+
18
+ **For ongoing work**: the log-based `[wave-verdict]` marker is now preferred over the report file `Verdict:` line. Both still work, but if both are present, the log marker wins. This is more reliable because the log is per-run while report files persist across attempts.
19
+
20
+ ### Log verdict priority
21
+
22
+ `buildAgentExecutionSummary()` now reads verdicts in this order:
23
+ 1. `[wave-verdict]` from the agent's log (authoritative per-run)
24
+ 2. `Verdict:` from the cont-QA report file (fallback)
25
+
26
+ Previously the report file took priority. If your cont-QA role prompt instructs the agent to write `Verdict: PASS/BLOCKED` in the report, that still works — it just won't override a contradicting `[wave-verdict]` marker in the same run's log.
27
+
28
+ ### Integration steward sticky closure
29
+
30
+ When A8 (integration steward) explicitly reports `state=ready-for-doc-closure` with zero blockers, the orchestrator no longer re-injects synthesized proof/doc gaps on the next `refreshDerivedState()` cycle. This prevents the pattern where:
31
+
32
+ 1. A8 closes all gaps → integration summary says "ready-for-doc-closure"
33
+ 2. Launcher calls `refreshDerivedState()` on next attempt
34
+ 3. `buildIntegrationEvidence()` re-derives gaps from agent summaries
35
+ 4. Integration summary regresses to "needs-more-work"
36
+ 5. Retry → goto 1
37
+
38
+ **No action required** — the fix is automatic. If your waves were stuck in integration retry loops, they should resolve on the next attempt.
39
+
40
+ ## Recommendations
41
+
42
+ - **Stuck cont-QA waves**: Just upgrade and let the runner retry. The fixed verdict parser will read the correct verdict.
43
+ - **Stuck integration loops**: Same — upgrade and let the runner retry.
44
+ - **Report file hygiene**: Consider having your cont-QA role prompt write verdicts with a clear section header (e.g., `## Final Verdict`) to make the file structure unambiguous. The first-match-wins behavior rewards putting the definitive verdict early in the file.
@@ -0,0 +1,49 @@
1
+ # Recommendations for 0.9.12
2
+
3
+ ## Upgrade
4
+
5
+ ```bash
6
+ wave self-update
7
+ # or: npm install -g @chllming/wave-orchestration@0.9.12
8
+ ```
9
+
10
+ ## What changed
11
+
12
+ ### Low-entropy closure is now explicit
13
+
14
+ Bootstrap closure keeps its fast path, but it is now constrained to the cases where closure actually stayed lightweight. If semantic closure stewards already ran, the launcher no longer skips a missing `cont-QA` run as if nothing meaningful happened.
15
+
16
+ Practical effect:
17
+
18
+ - low-entropy bootstrap waves still avoid unnecessary closeout churn
19
+ - waves that escalated into real semantic closure work now keep the stronger closeout contract
20
+ - closure metadata and mode resolution now agree about when bootstrap behavior applies
21
+
22
+ ### TMUX is optional, not the execution backend
23
+
24
+ The packaged docs, setup flow, and launcher help now all say the same thing:
25
+
26
+ - live agents run as detached processes
27
+ - `vscode` and `tmux` only change the operator-facing dashboard or projection surface
28
+ - `tmux` matters only when you actually want terminal-native dashboard attach
29
+
30
+ If you launch with `--terminal-surface tmux --no-dashboard`, Wave now prints an explicit note that TMUX is optional in that shape.
31
+
32
+ ### Wave Control dashboard-first UI
33
+
34
+ The shipped `wave-control-web` surface is now organized around:
35
+
36
+ - `Dashboard`
37
+ - `Operations`
38
+ - `Access`
39
+ - `Account`
40
+
41
+ Operators get a cleaner summary-first landing page, better access-review routing, and richer benchmark or run analytics without hunting across flat tabs.
42
+
43
+ ## Recommendations
44
+
45
+ - **Closure policy**: keep the bootstrap fast path for genuinely low-entropy work, but do not treat it as a general excuse to skip `cont-QA` after integration or documentation stewards already had to intervene.
46
+ - **Operator surfaces**: choose `vscode` or `tmux` based on where you want to follow logs and dashboards. Do not encode TMUX as if it were required for live execution.
47
+ - **Budgets**: keep using `budget.minutes` as the main wall-clock budget. Keep generic `budget.turns` advisory unless you deliberately need a runtime-specific hard ceiling.
48
+ - **Coordination severity**: continue to use `mark-advisory`, `mark-stale`, and `resolve-policy` for follow-up that should stay visible without falsely reopening proof-critical closure.
49
+ - **Targeted recovery**: prefer targeted recovery when one slice regresses. The lower-entropy closure path is most useful when the remaining work is genuinely narrow and machine-visible.
@@ -8,7 +8,7 @@ Typical examples:
8
8
  - Nemoshell or similar hosted terminal sandboxes
9
9
  - Docker or devcontainer setups where the client process is disposable but the workspace and state volume persist
10
10
 
11
- The core rule in `0.9.3` is simple:
11
+ The core rule in `0.9.12` is simple:
12
12
 
13
13
  - clients should be short-lived
14
14
  - supervision should be long-lived
@@ -94,7 +94,7 @@ If the sandbox only gives you short exec windows, `wave autonomous` should not b
94
94
 
95
95
  ## Docker And Containerized Setups
96
96
 
97
- Docker works well with the `0.9.3` process-backed runner model, but only if the state directories survive container restarts.
97
+ Docker works well with the `0.9.12` process-backed runner model, but only if the state directories survive container restarts.
98
98
 
99
99
  Recommended container posture:
100
100
 
@@ -57,7 +57,7 @@ pnpm exec wave dashboard --lane main --attach current
57
57
  pnpm exec wave dashboard --lane main --attach global
58
58
  ```
59
59
 
60
- Those commands work for both `tmux` and `vscode` terminal surfaces because the live dashboard projections still run on the lane tmux socket. If no live dashboard session exists, the attach command falls back to the last written dashboard JSON instead of failing immediately.
60
+ Those commands work for both `tmux` and `vscode` terminal surfaces because live dashboard projection sessions currently use the lane tmux socket when dashboards are enabled. If no live dashboard session exists, the attach command falls back to the last written dashboard JSON instead of failing immediately.
61
61
 
62
62
  When `--terminal-surface vscode` is active, Wave also maintains a stable current-wave dashboard terminal entry instead of creating a new wave-numbered dashboard attach target for every wave transition.
63
63
 
@@ -1,15 +1,15 @@
1
1
  # Current State
2
2
 
3
- - The published package is `0.9.4`; that release keeps the shipped monorepo, design-role, signal-hygiene, detached process-runner, and sandbox supervisor surfaces, and now also accepts `gap` as a valid wave-gate dimension value (alongside `pass`, `concerns`, and `blocked`) so that agents reporting a documented gap no longer trigger missing-wave-gate failures. First-time `wave launch` now auto-triggers `wave project setup` when no project profile exists, and the interactive setup flow shows descriptive help text and inline option explanations. The current authenticated Wave Control plus Corridor-backed security surface continues to ship in this repo.
3
+ - The published package is `0.9.12`; that release keeps the shipped monorepo, design-role, signal-hygiene, detached process-runner, and sandbox supervisor surfaces, and adds a cleaner low-entropy closure fast path plus a release-surface sweep that makes TMUX explicitly optional across setup, launcher help, and operator docs. The current authenticated Wave Control plus Corridor-backed security surface continues to ship in this repo, with the browser UI now organized around dashboard-first navigation and richer run or benchmark analytics summaries.
4
4
  - The canonical shipped runtime architecture is documented in `docs/plans/end-state-architecture.md`; the sandbox-runtime companion is `docs/plans/sandbox-end-state-architecture.md`; historical cutover notes remain in `docs/plans/architecture-hardening-migration.md`.
5
5
  - The repository contains the published `@chllming/wave-orchestration` package plus the starter scaffold used by `wave init`.
6
6
  - The runtime is package-first and non-destructive for adopting repos: `wave init --adopt-existing` records existing repo-owned plans, waves, prompts, and config without overwriting them, and `wave upgrade` writes only `.wave/install-state.json` plus `.wave/upgrade-history/`.
7
- - The recommended `0.9.4` operating stance is documented in `docs/guides/recommendations-0.9.4.md`: keep proof and closure strict, keep generic `budget.turns` advisory, and use softer coordination states only for non-proof follow-up.
7
+ - The recommended `0.9.12` operating stance is documented in `docs/guides/recommendations-0.9.12.md`: keep proof and closure strict, keep generic `budget.turns` advisory, use targeted recovery for low-entropy closure work, and treat TMUX as an optional operator surface rather than a runtime requirement.
8
8
  - Sandbox-safe setup guidance now ships in `docs/guides/sandboxed-environments.md`: use `wave submit/supervise/status/wait/attach` for short-lived clients, keep `tmux` optional and dashboard-only, and preserve `.tmp/` plus `.wave/` when running inside Nemoshell or Docker.
9
9
  - Runtime launch entrypoints now perform a best-effort npmjs version check, cache the result under `.wave/package-update-check.json`, and point operators at `pnpm exec wave self-update` when a newer published package exists.
10
10
  - The companion control plane now ships in two packages:
11
11
  - `services/wave-control/` is the backend for typed telemetry, Stack-authenticated app users, Wave-managed approval states and provider grants, PATs, dedicated service tokens, encrypted per-user credential storage, runtime env leasing, and owned broker routes for Context7 or Corridor
12
- - `services/wave-control-web/` is the Vite/Lit browser frontend that signs in through Stack, persists the browser session, exposes overview/runs/benchmarks/tokens, and adds superuser-only user, provider-grant, and write-only credential management
12
+ - `services/wave-control-web/` is the Vite/Lit browser frontend that signs in through Stack, persists the browser session, exposes dashboard-first navigation across runs, benchmarks, tokens, and access review, and adds superuser-only user, provider-grant, and write-only credential management
13
13
  - This source repo is itself kept as an adopted Wave workspace, so `node scripts/wave.mjs doctor --json` should pass from the repo root.
14
14
  - The default lane is `main`.
15
15
  - Planner foundation is now shipped:
@@ -1,6 +1,6 @@
1
1
  # End-State Architecture
2
2
 
3
- This document describes the canonical architecture for the current Wave runtime. It is the authoritative reference for the engine boundaries, canonical authority set, and artifact ownership model that the shipped `0.9.2` surface now follows.
3
+ This document describes the canonical architecture for the current Wave runtime. It is the authoritative reference for the engine boundaries, canonical authority set, and artifact ownership model that the shipped `0.9.12` surface now follows.
4
4
 
5
5
  For the sandbox-specific execution model, including async supervisor ownership, daemon adoption goals, and forwarded closure-gap behavior, read [sandbox-end-state-architecture.md](./sandbox-end-state-architecture.md).
6
6
 
@@ -1,6 +1,6 @@
1
1
  # Wave 12 - Optional Design Steward Handoff
2
2
 
3
- This is a showcase-first sample wave for the shipped `design` worker role in `0.9.2`.
3
+ This is a showcase-first sample wave for the shipped `design` worker role in `0.9.12`.
4
4
 
5
5
  This example demonstrates the docs-first design-steward path where a design packet is published before code-owning implementation begins.
6
6
 
@@ -2,7 +2,7 @@
2
2
 
3
3
  This is a showcase-first sample wave.
4
4
 
5
- Use it as the single reference example for the current `0.9.2` Wave surface.
5
+ Use it as the single reference example for the current `0.9.12` Wave surface.
6
6
 
7
7
  It intentionally combines more sections than a normal production wave so one file can demonstrate:
8
8
 
@@ -1,6 +1,6 @@
1
1
  # Migration
2
2
 
3
- This page is the practical repo-upgrade guide for the current `0.9.10` surface.
3
+ This page is the practical repo-upgrade guide for the current `0.9.12` surface.
4
4
 
5
5
  Use it when you are:
6
6
 
@@ -13,18 +13,22 @@ For the completed internal architecture cutover record, see [architecture-harden
13
13
  For the sandbox-specific long-running execution target, including async `submit/status/wait` semantics and daemon ownership goals, see [sandbox-end-state-architecture.md](./sandbox-end-state-architecture.md).
14
14
 
15
15
 
16
- ## What `0.9.4` Changes
16
+ ## What `0.9.12` Changes
17
+
18
+ The `0.9.12` surface keeps the existing proof-first runtime and adds one focused closure fix plus a broad operator-surface cleanup.
19
+
20
+ - **Hybrid closure fast path**: bootstrap closure still supports low-entropy waves, but a wave no longer skips missing `cont-QA` once semantic closure stewards already ran.
21
+ - **Closure policy wiring**: `closureModeThresholds.bootstrap` now actually affects runtime mode resolution, and derived closure-complexity metadata now includes the real barrier set.
22
+ - **Optional TMUX language**: setup prompts, launcher help, docs, and canned commands now all describe TMUX as an optional dashboard/projection layer instead of a required execution backend.
23
+ - **Wave Control operator UI**: the browser surface is now dashboard-first and exposes richer run, benchmark, and access summaries.
17
24
 
18
- The `0.9.4` surface adds laddered gate modes and fixes the steward threshold enforcement.
25
+ There are no breaking changes. Existing repos can upgrade in place with `pnpm up @chllming/wave-orchestration` and `pnpm exec wave upgrade`.
19
26
 
20
- - **Laddered gate modes**: bootstrap (waves 0-3), standard (4-9), strict (10+). Bootstrap mode requires only implementation agent exit 0 and deliverables exist — no formal QA signals needed.
21
- - **Steward threshold fix**: `requireDocumentationStewardFromWave` is now strictly respected. Previously it was OR'd with `componentPromotionRuleActive`.
22
- - **New config fields**: `gateModeThresholds`, `bootstrapPassConditions`, `testCommand`, `testCommandTimeout`.
23
- - **No breaking changes**: existing repos get bootstrap mode for waves 0-3 by default.
27
+ For the practical `0.9.12` operating stance after the upgrade, read [../guides/recommendations-0.9.12.md](../guides/recommendations-0.9.12.md).
24
28
 
25
29
  ## What `0.9.4` Changes
26
30
 
27
- The current `0.9.10` surface keeps everything from `0.9.2` and adds two focused improvements with no breaking changes.
31
+ The current `0.9.12` surface keeps everything from `0.9.2` and adds two focused improvements with no breaking changes.
28
32
 
29
33
  The practical changes are:
30
34
 
@@ -40,11 +44,11 @@ There are no breaking changes. Just upgrade with `pnpm up @chllming/wave-orchest
40
44
 
41
45
  If your repo uses wave-gate markers, you can now use `gap` for dimensions where the gap is documented and not an actionable blocker.
42
46
 
43
- For the practical `0.9.4` operating stance after the upgrade, read [../guides/recommendations-0.9.4.md](../guides/recommendations-0.9.4.md).
47
+ For the practical `0.9.12` operating stance after the upgrade, read [../guides/recommendations-0.9.12.md](../guides/recommendations-0.9.12.md).
44
48
 
45
49
  ## What `0.9.2` Changes
46
50
 
47
- The current `0.9.2` surface keeps the packaged operator-guidance alignment, monorepo project support, and project-aware default telemetry from `0.9.0`, but adds a more sandbox-friendly execution model and lower-overhead live orchestration.
51
+ The `0.9.2` release established the packaged operator-guidance alignment, monorepo project support, and project-aware default telemetry from `0.9.0`, then added a more sandbox-friendly execution model and lower-overhead live orchestration.
48
52
 
49
53
  The practical changes are:
50
54
 
@@ -55,11 +59,11 @@ The practical changes are:
55
59
  - Corridor is now documented as a first-class security input, including direct versus broker versus hybrid mode, implementation-owned path matching, generated artifact paths, and the closure-gate interaction with the human security reviewer
56
60
  - a dedicated setup guide now ships for LEAPclaw, OpenClaw, Nemoshell, Docker, and similar constrained environments
57
61
  - the `0.9.0` monorepo and project-aware state layout remains part of the release surface, including `defaultProject`, `projects.<projectId>`, project-scoped state roots, and project-aware CLI routing
58
- - the current release surface and tracked install-state fixtures now all move together on `0.9.2`
62
+ - the current release surface and tracked install-state fixtures now move together on the active package version
59
63
 
60
- If your repo copied starter docs, shell automation, runbooks, or `wave.config.json` defaults, these are the areas most likely to need a sync before the `0.9.2` package cut.
64
+ If your repo copied starter docs, shell automation, runbooks, or `wave.config.json` defaults, these are the areas most likely to need a sync before the current package cut.
61
65
 
62
- For a practical `0.9.2` operating stance after the upgrade, read [../guides/recommendations-0.9.2.md](../guides/recommendations-0.9.2.md).
66
+ For a practical `0.9.12` operating stance after the upgrade, read [../guides/recommendations-0.9.12.md](../guides/recommendations-0.9.12.md).
63
67
  For the concrete operator setup in Nemoshell, Docker, and other sandboxed shells, also read [../guides/sandboxed-environments.md](../guides/sandboxed-environments.md).
64
68
 
65
69
  ## What `0.8.6` Changes
@@ -127,7 +131,7 @@ pnpm exec wave upgrade
127
131
 
128
132
  ### 3. Sync repo-owned starter surface only if you copied it
129
133
 
130
- The most common sync set for `0.9.2` is:
134
+ The most common sync set for the current release line is:
131
135
 
132
136
  - `docs/agents/wave-launcher-role.md`
133
137
  - `docs/agents/wave-orchestrator-role.md`
@@ -180,9 +184,9 @@ pnpm exec wave coord inbox --lane main --wave 0 --agent A1 --dry-run
180
184
 
181
185
  Use `pnpm exec wave dashboard --lane <lane> --attach current` or `--attach global` when you need to reattach to a tmux-backed dashboard after the upgrade.
182
186
 
183
- ## `0.9.4` Release Model
187
+ ## `0.9.12` Release Model
184
188
 
185
- The current `0.9.10` surface combines these strands:
189
+ The current `0.9.12` surface combines these strands:
186
190
 
187
191
  - the gap-value wave-gate fix and first-time setup UX improvements released in `0.9.4`
188
192
  - the detached process-runner and sandbox supervisor hardening released in `0.9.2`
@@ -196,7 +200,7 @@ The current `0.9.10` surface combines these strands:
196
200
 
197
201
  ### Sandbox-safe execution and lower-overhead live runs
198
202
 
199
- This is the main new behavior in `0.9.2`.
203
+ This remains the main execution-model shift introduced in `0.9.2`.
200
204
 
201
205
  The runtime now:
202
206
 
@@ -205,7 +209,7 @@ The runtime now:
205
209
  - keeps `wave attach --agent` usable through log-follow attach even when no live interactive terminal session exists
206
210
  - uses `wave submit/supervise/status/wait/attach` as the preferred sandbox-safe surface for short-lived clients
207
211
 
208
- If your repo copied sandbox, CI, or container runbooks, this is the main sync set to apply from `0.9.2`:
212
+ If your repo copied sandbox, CI, or container runbooks, this is the main sync set to apply from that `0.9.2` execution-model cut:
209
213
 
210
214
  - `README.md`
211
215
  - `docs/README.md`
@@ -216,14 +220,14 @@ If your repo copied sandbox, CI, or container runbooks, this is the main sync se
216
220
 
217
221
  ### Authenticated Wave Control and Corridor-backed security
218
222
 
219
- The same `0.9.2` doc surface also now describes the current control-plane and security model as shipped:
223
+ That same `0.9.2` doc surface also describes the current control-plane and security model as shipped:
220
224
 
221
225
  - owned Wave Control deployments use Stack for browser sign-in, then apply Wave-managed approval states and provider grants on top of that identity
222
226
  - approved users and superusers can issue PATs for scoped repo-runtime access, while dedicated service tokens keep machine-admin workflows separate from user-owned runtime credentials
223
227
  - arbitrary stored credentials are encrypted at rest and only returned through explicit runtime lease responses
224
228
  - `externalProviders.corridor` can run direct, brokered through an owned Wave Control deployment, or hybrid; the result is persisted as a normalized security artifact and can block closure before integration
225
229
 
226
- If your repo copied release docs, security runbooks, or Wave Control setup docs, this is the main sync set to apply from `0.9.2`:
230
+ If your repo copied release docs, security runbooks, or Wave Control setup docs, this is the main sync set to apply from that `0.9.2` security-surface cut:
227
231
 
228
232
  - `README.md`
229
233
  - `docs/README.md`
@@ -292,7 +296,7 @@ The interactive `wave draft` flow supports `design` as a worker role and scaffol
292
296
 
293
297
  ## Version-Specific Upgrade Guidance
294
298
 
295
- ## Upgrading From `0.8.5` To `0.9.4`
299
+ ## Upgrading From `0.8.5` To `0.9.12`
296
300
 
297
301
  This is the smallest upgrade, but it changes the live wait-loop contract for external automation and intentionally long-running agents.
298
302
 
@@ -329,7 +333,7 @@ If the repo copied starter surface, sync:
329
333
  - if the repo uses long-running watchers, confirm they can write the ack file where the prompt tells them to
330
334
  - reroute one targeted feedback or coordination request and confirm the resident signal version changes even when the signal kind stays the same
331
335
 
332
- ## Upgrading From `0.8.4` To `0.9.4`
336
+ ## Upgrading From `0.8.4` To `0.9.12`
333
337
 
334
338
  ### What changed
335
339
 
@@ -367,7 +371,7 @@ If your repo copied starter config defaults, also sync the `designRolePromptPath
367
371
  - hybrid design stewards rejoin implementation when they explicitly own code
368
372
  - long-running prompts receive signal-state and ack paths when the repo uses the new waiting model
369
373
 
370
- ## Upgrading From `0.9.9` To `0.9.10`
374
+ ## Upgrading From `0.9.9` To `0.9.12`
371
375
 
372
376
  Run-state history is now capped at 200 entries (20 per wave). Existing bloated run-state files will be automatically pruned on the next write. No config changes needed.
373
377
 
@@ -375,9 +379,9 @@ Run-state history is now capped at 200 entries (20 per wave). Existing bloated r
375
379
 
376
380
  Helper assignment barriers are now advisory in bootstrap gate mode. No config changes needed.
377
381
 
378
- ## Upgrading From `0.8.3` To `0.9.10`
382
+ ## Upgrading From `0.8.3` To `0.9.12`
379
383
 
380
- Treat this as one move to the current `0.9.2` surface.
384
+ Treat this as one move to the current `0.9.12` surface.
381
385
 
382
386
  ### What changed across that range
383
387
 
@@ -410,7 +414,7 @@ If your repo copied starter docs or skills, sync:
410
414
  - dry-run one design-steward wave if the repo wants the new authored surface
411
415
  - 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
412
416
 
413
- ## Upgrading From `0.6.x` Or `0.7.x` To `0.9.10`
417
+ ## Upgrading From `0.6.x` Or `0.7.x` To `0.9.12`
414
418
 
415
419
  This is the main migration path for older adopted repos.
416
420
 
@@ -451,7 +455,7 @@ pnpm exec wave control proof get --lane main --wave 0 --json
451
455
 
452
456
  If the repo carries proof-first waves, verify that required proof artifacts still exist locally and not only in historical summaries.
453
457
 
454
- ## Upgrading From `0.5.x` Or Earlier To `0.9.4`
458
+ ## Upgrading From `0.5.x` Or Earlier To `0.9.12`
455
459
 
456
460
  Do not treat this as a tiny patch bump.
457
461
 
@@ -561,4 +565,4 @@ For repos that depend on replay parity, replay at least:
561
565
 
562
566
  ## Summary
563
567
 
564
- The current `0.9.10` 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.
568
+ The current `0.9.12` 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, adds the hybrid closure fast-path fixes, and now 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.
@@ -126,7 +126,7 @@ The live runtime is organized around explicit modules:
126
126
  ## Setup
127
127
 
128
128
  1. Install the package with `pnpm add -D @chllming/wave-orchestration`.
129
- 2. Confirm `tmux` and at least one real executor (`codex`, `claude`, or `opencode`) are available if you want real wave execution.
129
+ 2. Confirm at least one real executor (`codex`, `claude`, or `opencode`) is available if you want live wave execution. Install `tmux` only if you want terminal-native dashboard or projection attach.
130
130
  3. Run `pnpm exec wave init` for a fresh repo, or `pnpm exec wave init --adopt-existing` for a repo with existing Wave files you want preserved.
131
131
  4. Review [wave.config.json](../../wave.config.json).
132
132
  5. Review the role prompts, starter `skills/` bundles, and docs you want the repo to own.
@@ -54,7 +54,7 @@ Closure-role bindings do not have a CLI override surface. When a wave file decla
54
54
  | `--agent-launch-stagger-ms <n>` | `1200` | Delay between agent launches |
55
55
  | `--terminal-surface <mode>` | `vscode` | `tmux`, `vscode`, or `none` |
56
56
  | `--no-dashboard` | off | Disable the per-wave dashboard projection session |
57
- | `--cleanup-sessions` | on | Kill lane tmux dashboard and projection sessions after each wave |
57
+ | `--cleanup-sessions` | on | Clean up lane tmux dashboard and projection sessions after each wave |
58
58
  | `--keep-sessions` | off | Keep lane tmux dashboard and projection sessions |
59
59
  | `--keep-terminals` | off | Keep temporary terminal entries |
60
60
  | `--orchestrator-id <id>` | generated | Stable orchestrator identity |
@@ -629,7 +629,7 @@ Interactive draft currently offers worker role kinds:
629
629
  - `research`
630
630
  - `security`
631
631
 
632
- Agentic planner payloads also accept `workerAgents[].roleKind = "design"`. The shipped `0.9.2` surface uses `design-pass` as the default executor profile for that role and typically assigns a packet path like `docs/plans/waves/design/wave-<n>-<agentId>.md`. Interactive draft scaffolds the docs-first default; hybrid design stewards are authored by explicitly adding implementation-owned paths and the normal implementation contract sections.
632
+ Agentic planner payloads also accept `workerAgents[].roleKind = "design"`. The shipped `0.9.12` surface uses `design-pass` as the default executor profile for that role and typically assigns a packet path like `docs/plans/waves/design/wave-<n>-<agentId>.md`. Interactive draft scaffolds the docs-first default; hybrid design stewards are authored by explicitly adding implementation-owned paths and the normal implementation contract sections.
633
633
 
634
634
  ## Ad-Hoc Task Commands
635
635
 
@@ -142,7 +142,7 @@ Practical rule:
142
142
 
143
143
  That means a targeted helper request only blocks while it remains open *and* still has blocking severity in coordination state.
144
144
 
145
- For the practical `0.9.2` recommendation on when to keep records blocking versus when to downgrade them to `soft`, `stale`, or `advisory`, see [../guides/recommendations-0.9.2.md](../guides/recommendations-0.9.2.md).
145
+ For the practical `0.9.12` recommendation on when to keep records blocking versus when to downgrade them to `soft`, `stale`, or `advisory`, see [../guides/recommendations-0.9.12.md](../guides/recommendations-0.9.12.md).
146
146
 
147
147
  This page is documenting runtime semantics first. The important contract is that closure follows the durable coordination state, not that a particular human or agent used one exact command path to mutate it.
148
148