@chllming/wave-orchestration 0.9.14 → 0.9.15

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 (47) hide show
  1. package/CHANGELOG.md +27 -0
  2. package/README.md +7 -7
  3. package/docs/README.md +3 -3
  4. package/docs/concepts/operating-modes.md +1 -1
  5. package/docs/guides/author-and-run-waves.md +1 -1
  6. package/docs/guides/planner.md +2 -2
  7. package/docs/guides/recommendations-0.9.15.md +83 -0
  8. package/docs/guides/sandboxed-environments.md +2 -2
  9. package/docs/guides/signal-wrappers.md +10 -0
  10. package/docs/plans/agent-first-closure-hardening.md +612 -0
  11. package/docs/plans/current-state.md +3 -3
  12. package/docs/plans/end-state-architecture.md +1 -1
  13. package/docs/plans/examples/wave-example-design-handoff.md +1 -1
  14. package/docs/plans/examples/wave-example-live-proof.md +1 -1
  15. package/docs/plans/migration.md +75 -20
  16. package/docs/reference/cli-reference.md +34 -1
  17. package/docs/reference/coordination-and-closure.md +16 -1
  18. package/docs/reference/npmjs-token-publishing.md +3 -3
  19. package/docs/reference/package-publishing-flow.md +13 -11
  20. package/docs/reference/runtime-config/README.md +2 -2
  21. package/docs/reference/sample-waves.md +5 -5
  22. package/docs/reference/skills.md +1 -1
  23. package/docs/reference/wave-control.md +1 -1
  24. package/docs/roadmap.md +5 -3
  25. package/package.json +8 -9
  26. package/releases/manifest.json +35 -0
  27. package/scripts/context7-api-check.sh +0 -0
  28. package/scripts/context7-export-env.sh +0 -0
  29. package/scripts/wave-autonomous.mjs +0 -0
  30. package/scripts/wave-dashboard.mjs +0 -0
  31. package/scripts/wave-human-feedback.mjs +0 -0
  32. package/scripts/wave-launcher.mjs +0 -0
  33. package/scripts/wave-local-executor.mjs +0 -0
  34. package/scripts/wave-orchestrator/agent-state.mjs +200 -312
  35. package/scripts/wave-orchestrator/artifact-schemas.mjs +37 -2
  36. package/scripts/wave-orchestrator/closure-adjudicator.mjs +311 -0
  37. package/scripts/wave-orchestrator/control-cli.mjs +212 -18
  38. package/scripts/wave-orchestrator/dashboard-state.mjs +40 -0
  39. package/scripts/wave-orchestrator/derived-state-engine.mjs +3 -0
  40. package/scripts/wave-orchestrator/gate-engine.mjs +93 -1
  41. package/scripts/wave-orchestrator/install.mjs +1 -1
  42. package/scripts/wave-orchestrator/launcher.mjs +49 -10
  43. package/scripts/wave-orchestrator/signal-cli.mjs +271 -0
  44. package/scripts/wave-orchestrator/structured-signal-parser.mjs +499 -0
  45. package/scripts/wave-status.sh +0 -0
  46. package/scripts/wave-watch.sh +0 -0
  47. package/scripts/wave.mjs +9 -0
package/CHANGELOG.md CHANGED
@@ -1,5 +1,32 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.9.15 - 2026-04-10
4
+
5
+ ### Added
6
+ - Deterministic implementation-closure adjudication for transport-only failures, with persisted artifacts under `.tmp/<lane>-wave-launcher/closure/wave-<n>/attempt-<a>/<agent>.json`.
7
+ - `wave control adjudication get` for operator inspection of adjudication status, evidence, and synthesized canonical signals.
8
+ - `wave signal proof|doc-delta|component|integration|doc-closure` helper commands so orchestrators and wrappers can emit canonical markers without hand-typing syntax.
9
+ - Additive `executionState`, `closureState`, and `controllerState` projections in control and dashboard payloads, plus per-agent `executionState` and `closureState`.
10
+ - A new packaged operating guide at `docs/guides/recommendations-0.9.15.md`.
11
+
12
+ ### Changed
13
+ - Structured signal ingestion is now normalized behind one parser, preserving compatibility with wrapped, fenced, list-prefixed, and JSON-embedded marker output while surfacing richer diagnostics.
14
+ - Implementation validation still preserves legacy `statusCode` values, but now also classifies failures as `transport-failure`, `semantic-failure`, `artifact-failure`, or `state-failure`.
15
+ - Transport-only implementation failures with coherent exit state now pause in `awaiting-adjudication` instead of automatically becoming relaunch work.
16
+ - `wave control status` now separates live execution, closure, and controller intent, so stale relaunch plans or degraded supervisor state no longer look identical to active runtime work.
17
+ - README, current-state, migration, runtime-config, coordination, CLI, signal-wrapper, package-publishing, manifest, and tracked install-state docs now align on the `0.9.15` surface.
18
+
19
+ ### Fixed
20
+ - Proof, doc-delta, and component marker parsing now tolerates more real-world agent output shapes without weakening the required closure contract.
21
+ - Live and replayable implementation gates now share the same adjudication rules instead of diverging between runtime and pure projection paths.
22
+ - Retry handling no longer treats every missing or malformed closure marker as proof that the agent must rerun; true semantic or artifact failures still relaunch, but transport-only ambiguity stays inspectable first.
23
+
24
+ ## 0.9.14 - 2026-04-09
25
+
26
+ ### Changed
27
+ - Published a `0.9.14` package cut to npmjs after `0.9.13` so the public registry advanced, while keeping the effective shipped runtime and docs surface aligned with `0.9.13`.
28
+ - No intentional behavior change beyond the package-version publication itself; treat `0.9.14` as the registry-visible carry-forward of the `0.9.13` surface.
29
+
3
30
  ## 0.9.13 - 2026-04-09
4
31
 
5
32
  ### Added
package/README.md CHANGED
@@ -107,17 +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.13`
111
- - Release tag: [`v0.9.13`](https://github.com/chllming/agent-wave-orchestrator/releases/tag/v0.9.13)
110
+ - `@chllming/wave-orchestration@0.9.15`
111
+ - Release tag: [`v0.9.15`](https://github.com/chllming/agent-wave-orchestrator/releases/tag/v0.9.15)
112
112
  - Public install path: npmjs
113
113
  - Authenticated fallback: GitHub Packages
114
114
 
115
- Highlights in `0.9.13`:
115
+ Highlights in `0.9.15`:
116
116
 
117
- - Structured proof and component markers now accept `state=complete` as a `met` alias, so agents that emit the more natural completion wording no longer fail proof parsing.
118
- - Pre-launch wave validation now treats status-recoverable completed waves as already completed, which prevents stale component-matrix promotion checks from blocking restart or resumed launches.
119
- - Detached process runners now derive a per-agent broker sticky key by default and preserve explicit overrides, so concurrent agents on the same node can lease provider credentials safely.
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.13` surface.
117
+ - `wave signal ...` now emits canonical proof and closure markers for orchestrators, wrappers, and custom prompt scaffolds.
118
+ - Transport-only implementation closure failures can now pause in deterministic adjudication instead of always being turned into a rerun.
119
+ - `wave control status` now separates `executionState`, `closureState`, and `controllerState`, which makes active execution, blocked closure, and stale controller intent visible as different situations.
120
+ - `wave control adjudication get` exposes persisted adjudication artifacts so operators can inspect evidence before choosing rerun or follow-up work.
121
121
 
122
122
  Requirements:
123
123
 
package/docs/README.md CHANGED
@@ -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.13` 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.15` 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,8 +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.13` operating stance:
57
- Read [guides/recommendations-0.9.13.md](./guides/recommendations-0.9.13.md) for the recommended default around advisory turn budgets, targeted recovery, restart-safe validation, and optional TMUX operator surfaces.
56
+ - Want the practical `0.9.15` operating stance:
57
+ Read [guides/recommendations-0.9.15.md](./guides/recommendations-0.9.15.md) for the recommended default around advisory turn budgets, targeted recovery, closure adjudication, canonical signal helpers, and optional TMUX operator surfaces.
58
58
  - Want the concrete runtime module map:
59
59
  Read [plans/end-state-architecture.md](./plans/end-state-architecture.md) for the engine-by-engine architecture and artifact ownership model.
60
60
  - Want the CLI surface map:
@@ -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.13`.
91
+ The stricter execution semantics are still future work, not a hidden already-finished feature in `0.9.15`.
@@ -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.13` is:
77
+ The starter contract in `0.9.15` 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`
@@ -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.13` 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.15` 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.13` 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.15` release line. The planner foundation is about better structured authoring, not a second execution engine.
52
52
 
53
53
  ## Project Profile
54
54
 
@@ -0,0 +1,83 @@
1
+ # Recommendations for 0.9.15
2
+
3
+ ## Upgrade
4
+
5
+ ```bash
6
+ wave self-update
7
+ # or: npm install -g @chllming/wave-orchestration@0.9.15
8
+ ```
9
+
10
+ ## What changed
11
+
12
+ ### Marker parsing is more forgiving, proof standards are not
13
+
14
+ Agents sometimes emit `state=complete` instead of `state=met` in `[wave-proof]` and `[wave-component]` markers. Wave now accepts that alias and normalizes it to the existing `met` semantics.
15
+
16
+ Practical effect:
17
+
18
+ - natural completion phrasing no longer breaks proof parsing
19
+ - proof standards stay the same because the normalized state still means `met`
20
+ - operators can keep asking for machine-visible final markers without retraining every agent prompt immediately
21
+
22
+ ### Signal parsing is now normalized behind one path
23
+
24
+ Implementation closure now normalizes wrapped, fenced, list-prefixed, and JSON-embedded marker output through one parser instead of relying on a narrower mix of ad hoc extraction paths.
25
+
26
+ Practical effect:
27
+
28
+ - wrappers and coding agents have more room to emit markers in realistic output shapes
29
+ - diagnostics are better when markers are seen but rejected
30
+ - the closure contract is still strict because missing or malformed markers remain visible as machine-classified failures
31
+
32
+ ### Restart-safe validation matters more than stale matrices
33
+
34
+ Historical completed waves can promote a component to an older level than the matrix's current level after later waves advanced it further. On restart, the launcher now consults both `run-state.json` and status-recoverable completions before stale promotion checks.
35
+
36
+ Practical effect:
37
+
38
+ - resumed launches stop reopening already completed historical waves
39
+ - component-matrix validation stays strict for active or genuinely incomplete work
40
+ - targeted recovery remains the right tool when only one later slice actually needs attention
41
+
42
+ ### Concurrent detached runners need unique broker identity
43
+
44
+ When detached runners broker provider credentials, each agent now gets a unique default `LPM_AUTH_STICKY_KEY`. Explicit overrides still win.
45
+
46
+ Practical effect:
47
+
48
+ - same-node agents can lease credentials concurrently without trampling one shared sticky key
49
+ - local policy can still provide an explicit sticky key when a deployment needs custom routing
50
+ - retry or resume flows stay deterministic because the default key now scopes down to one agent attempt
51
+
52
+ ### Transport-only closure failures can pause for adjudication before rerun
53
+
54
+ When implementation closure has exit `0`, landed artifacts, and a valid result envelope but the final machine markers are malformed, Wave can now hold the slice in deterministic adjudication instead of immediately relaunching it. Fully missing required markers still fail closure until the agent emits them or a narrower rerun lands them.
55
+
56
+ Practical effect:
57
+
58
+ - transport-only proof failures stop looking identical to real semantic regressions
59
+ - operators can inspect the recorded adjudication artifact with `wave control adjudication get`
60
+ - targeted rerun stays reserved for semantic, artifact, or runtime-state failures that actually need more work
61
+
62
+ ### Control status is now split into execution, closure, and controller intent
63
+
64
+ `wave control status --json` now reports additive `executionState`, `closureState`, and `controllerState` fields, with matching per-agent execution and closure projections.
65
+
66
+ Practical effect:
67
+
68
+ - live execution is no longer conflated with blocked closure
69
+ - stale relaunch plans are visible without masquerading as active runtime work
70
+ - operators can make better decisions about whether to wait, adjudicate, or rerun
71
+
72
+ ## Recommendations
73
+
74
+ - **Proof markers**: keep requiring explicit final markers, but accept `complete` as an operationally harmless alias while normalizing downstream state to `met`.
75
+ - **Signal helpers**: prefer `wave signal ...` instead of hand-typing marker syntax in orchestrator prompts, shell wrappers, or local helper scripts. The helper now fails fast when a value would not round-trip through the shipped parser.
76
+ - **Restart recovery**: prefer status-backed restart and targeted recovery over reauthoring older completed waves just because the component matrix has since moved on.
77
+ - **Credential brokering**: let the detached runner use its per-agent sticky-key default unless you have a clear external reason to override it.
78
+ - **Status interpretation**: read `executionState`, `closureState`, and `controllerState` together when deciding whether a wave is actively running, blocked only in closure, or merely carrying stale controller intent.
79
+ - **Closure adjudication**: treat `awaiting-adjudication` as distinct from both success and rerun-needed. Inspect the persisted evidence first; do not auto-relaunch transport-only failures by habit.
80
+ - **Canonical signals**: prefer `wave signal ...` when wrappers or custom prompts need to emit final markers. It keeps marker syntax canonical and avoids accidental format drift.
81
+ - **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.
82
+ - **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.
83
+ - **Targeted recovery**: prefer targeted recovery when one slice regresses or a restart left run-state behind. The most useful recovery work is still 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.13` is simple:
11
+ The core rule in `0.9.15` 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.13` process-backed runner model, but only if the state directories survive container restarts.
97
+ Docker works well with the `0.9.15` process-backed runner model, but only if the state directories survive container restarts.
98
98
 
99
99
  Recommended container posture:
100
100
 
@@ -19,6 +19,14 @@ The resident orchestrator uses the same pattern with `resident-orchestrator` as
19
19
 
20
20
  Signal snapshots are derived projections, not canonical decision state. They are machine-friendly wake surfaces built from `wave control status --json`.
21
21
 
22
+ The underlying control payload now also separates:
23
+
24
+ - `executionState`
25
+ - `closureState`
26
+ - `controllerState`
27
+
28
+ Use the signal files for wake loops and thin shell automation. Use the status triplet when you need to distinguish active runtime work from closure-only blocking or stale persisted controller intent.
29
+
22
30
  ## Signal Kinds
23
31
 
24
32
  The shipped signal vocabulary is:
@@ -163,3 +171,5 @@ done
163
171
  ```
164
172
 
165
173
  Use `wave control status --json` directly when you need the full structured payload. Use the wrapper scripts when you want stable exit codes and a single machine-readable line.
174
+
175
+ If an agent or wrapper needs to emit canonical closure markers itself, prefer `wave signal ...` over hand-typing marker syntax. That helper prints the canonical line, supports `--append-file`, and normalizes compatible aliases such as `state=complete` to the existing `met` semantics.