@chllming/wave-orchestration 0.8.3 → 0.8.5

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 (59) hide show
  1. package/CHANGELOG.md +36 -1
  2. package/README.md +60 -11
  3. package/docs/README.md +8 -2
  4. package/docs/agents/wave-design-role.md +47 -0
  5. package/docs/concepts/what-is-a-wave.md +11 -7
  6. package/docs/guides/author-and-run-waves.md +24 -0
  7. package/docs/guides/planner.md +44 -0
  8. package/docs/plans/architecture-hardening-migration.md +8 -1
  9. package/docs/plans/current-state.md +19 -7
  10. package/docs/plans/end-state-architecture.md +88 -70
  11. package/docs/plans/examples/wave-example-design-handoff.md +262 -0
  12. package/docs/plans/examples/wave-example-live-proof.md +1 -1
  13. package/docs/plans/migration.md +370 -64
  14. package/docs/plans/wave-orchestrator.md +49 -13
  15. package/docs/reference/cli-reference.md +46 -14
  16. package/docs/reference/coordination-and-closure.md +19 -6
  17. package/docs/reference/npmjs-trusted-publishing.md +5 -4
  18. package/docs/reference/sample-waves.md +14 -7
  19. package/docs/reference/skills.md +10 -0
  20. package/package.json +1 -1
  21. package/releases/manifest.json +39 -0
  22. package/scripts/wave-orchestrator/agent-state.mjs +64 -491
  23. package/scripts/wave-orchestrator/autonomous.mjs +10 -6
  24. package/scripts/wave-orchestrator/{launcher-closure.mjs → closure-engine.mjs} +190 -74
  25. package/scripts/wave-orchestrator/config.mjs +5 -0
  26. package/scripts/wave-orchestrator/coordination.mjs +42 -1
  27. package/scripts/wave-orchestrator/{launcher-derived-state.mjs → derived-state-engine.mjs} +34 -146
  28. package/scripts/wave-orchestrator/{launcher-gates.mjs → gate-engine.mjs} +501 -141
  29. package/scripts/wave-orchestrator/human-input-resolution.mjs +14 -10
  30. package/scripts/wave-orchestrator/human-input-workflow.mjs +104 -0
  31. package/scripts/wave-orchestrator/implementation-engine.mjs +120 -0
  32. package/scripts/wave-orchestrator/install.mjs +3 -0
  33. package/scripts/wave-orchestrator/launcher-runtime.mjs +11 -6
  34. package/scripts/wave-orchestrator/launcher.mjs +324 -723
  35. package/scripts/wave-orchestrator/ledger.mjs +56 -27
  36. package/scripts/wave-orchestrator/local-executor.mjs +37 -0
  37. package/scripts/wave-orchestrator/planner.mjs +24 -4
  38. package/scripts/wave-orchestrator/projection-writer.mjs +256 -0
  39. package/scripts/wave-orchestrator/reconcile-format.mjs +32 -0
  40. package/scripts/wave-orchestrator/reducer-snapshot.mjs +297 -0
  41. package/scripts/wave-orchestrator/replay.mjs +3 -1
  42. package/scripts/wave-orchestrator/result-envelope.mjs +620 -0
  43. package/scripts/wave-orchestrator/retry-control.mjs +22 -2
  44. package/scripts/wave-orchestrator/{launcher-retry.mjs → retry-engine.mjs} +352 -18
  45. package/scripts/wave-orchestrator/role-helpers.mjs +124 -1
  46. package/scripts/wave-orchestrator/{launcher-supervisor.mjs → session-supervisor.mjs} +178 -103
  47. package/scripts/wave-orchestrator/shared.mjs +2 -0
  48. package/scripts/wave-orchestrator/skills.mjs +1 -0
  49. package/scripts/wave-orchestrator/task-entity.mjs +65 -45
  50. package/scripts/wave-orchestrator/traces.mjs +10 -1
  51. package/scripts/wave-orchestrator/wave-files.mjs +96 -10
  52. package/scripts/wave-orchestrator/wave-state-reducer.mjs +76 -12
  53. package/skills/README.md +7 -0
  54. package/skills/role-design/SKILL.md +50 -0
  55. package/skills/role-design/skill.json +36 -0
  56. package/skills/tui-design/SKILL.md +77 -0
  57. package/skills/tui-design/references/tui-design.md +259 -0
  58. package/skills/tui-design/skill.json +36 -0
  59. package/wave.config.json +15 -1
@@ -7,6 +7,19 @@ summary: "Complete syntax reference for all wave CLI commands, flags, and operat
7
7
 
8
8
  Complete syntax for every `wave` command. All commands use `pnpm exec wave` as the entry point.
9
9
 
10
+ ## Command Families
11
+
12
+ - Runtime:
13
+ `wave launch`, `wave autonomous`, and `wave local` cover dry-run validation, live execution, and executor-specific prompt transport.
14
+ - Operator control:
15
+ `wave control` is the preferred surface for live status, tasks, reruns, proof bundles, and telemetry.
16
+ - Compatibility and inspection:
17
+ `wave coord`, `wave retry`, and `wave proof` remain available where older runbooks still depend on them.
18
+ - Planning and transient work:
19
+ `wave project`, `wave draft`, and `wave adhoc` cover defaults, authored waves, and operator-driven one-off runs.
20
+ - Setup and lifecycle:
21
+ `wave init`, `wave doctor`, `wave upgrade`, and `wave self-update` cover workspace adoption, validation, and package upgrades.
22
+
10
23
  ## wave launch
11
24
 
12
25
  Launch waves for execution.
@@ -15,6 +28,10 @@ Launch waves for execution.
15
28
  wave launch [options]
16
29
  ```
17
30
 
31
+ Defaults below reflect the starter workspace surface in this repo. Lane config can override executor, timeout, retry, and terminal defaults.
32
+
33
+ Closure-role bindings do not have a CLI override surface. When a wave file declares custom integration, documentation, `cont-QA`, `cont-EVAL`, or security-review role ids, launch, retry, reducer, and closure flows honor those wave-level bindings end to end.
34
+
18
35
  | Flag | Default | Description |
19
36
  |------|---------|-------------|
20
37
  | `--lane <name>` | `main` | Lane name |
@@ -22,20 +39,23 @@ wave launch [options]
22
39
  | `--end-wave <n>` | last available | Last wave to launch |
23
40
  | `--auto-next` | off | Start from next unfinished wave and continue |
24
41
  | `--resume-control-state` | off | Preserve the prior auto-generated relaunch plan instead of treating the launch as a fresh wave start |
25
- | `--executor <id>` | lane config | Default executor: `codex`, `claude`, `opencode`, `local` |
42
+ | `--executor <id>` | `codex` | Default executor: `codex`, `claude`, `opencode`, `local` |
26
43
  | `--codex-sandbox <mode>` | `danger-full-access` | Codex sandbox isolation level |
27
- | `--timeout-minutes <n>` | `60` | Max minutes to wait per wave |
28
- | `--max-retries-per-wave <n>` | `3` | Relaunch failed agents per wave |
29
- | `--agent-rate-limit-retries <n>` | `3` | Per-agent retries for 429 errors |
30
- | `--agent-rate-limit-base-delay-seconds <n>` | `1` | Base exponential backoff for 429 |
31
- | `--agent-rate-limit-max-delay-seconds <n>` | `60` | Max backoff delay for 429 |
32
- | `--agent-launch-stagger-ms <n>` | `250` | Delay between agent launches |
33
- | `--terminal-surface <mode>` | configured | `tmux`, `vscode`, or `none` |
44
+ | `--timeout-minutes <n>` | `240` | Max minutes to wait per wave |
45
+ | `--max-retries-per-wave <n>` | `1` | Relaunch failed agents per wave |
46
+ | `--agent-rate-limit-retries <n>` | `2` | Per-agent retries for 429 errors |
47
+ | `--agent-rate-limit-base-delay-seconds <n>` | `20` | Base exponential backoff for 429 |
48
+ | `--agent-rate-limit-max-delay-seconds <n>` | `180` | Max backoff delay for 429 |
49
+ | `--agent-launch-stagger-ms <n>` | `1200` | Delay between agent launches |
50
+ | `--terminal-surface <mode>` | `vscode` | `tmux`, `vscode`, or `none` |
34
51
  | `--no-dashboard` | off | Disable per-wave tmux dashboard |
35
52
  | `--cleanup-sessions` | on | Kill lane tmux sessions after each wave |
36
53
  | `--keep-sessions` | off | Keep lane tmux sessions |
37
54
  | `--keep-terminals` | off | Keep temporary terminal entries |
38
55
  | `--orchestrator-id <id>` | generated | Stable orchestrator identity |
56
+ | `--orchestrator-board <path>` | default board path | Write coordination-board updates to a specific shared board |
57
+ | `--no-orchestrator-board` | off | Disable shared orchestrator-board writes for this run |
58
+ | `--coordination-note <text>` | empty | Append a startup intent note to orchestrator-board updates |
39
59
  | `--resident-orchestrator` | off | Launch long-running non-owning orchestrator session |
40
60
  | `--no-telemetry` | off | Disable Wave Control event publication |
41
61
  | `--no-context7` | off | Disable Context7 prefetch |
@@ -57,13 +77,13 @@ wave autonomous [options]
57
77
  | `--lane <name>` | `main` | Lane name |
58
78
  | `--executor <id>` | lane config | `codex`, `claude`, or `opencode` (not `local`) |
59
79
  | `--codex-sandbox <mode>` | `danger-full-access` | Codex sandbox mode |
60
- | `--timeout-minutes <n>` | `60` | Per-wave timeout passed to launcher |
61
- | `--max-retries-per-wave <n>` | `3` | Per-wave relaunches inside launcher |
80
+ | `--timeout-minutes <n>` | `240` | Per-wave timeout passed to launcher |
81
+ | `--max-retries-per-wave <n>` | `1` | Per-wave relaunches inside launcher |
62
82
  | `--max-attempts-per-wave <n>` | `1` | External attempts per wave |
63
- | `--agent-rate-limit-retries <n>` | `3` | Per-agent 429 retries |
64
- | `--agent-rate-limit-base-delay-seconds <n>` | `1` | Base 429 backoff |
65
- | `--agent-rate-limit-max-delay-seconds <n>` | `60` | Max 429 backoff |
66
- | `--agent-launch-stagger-ms <n>` | `250` | Delay between agent launches |
83
+ | `--agent-rate-limit-retries <n>` | `2` | Per-agent 429 retries |
84
+ | `--agent-rate-limit-base-delay-seconds <n>` | `20` | Base 429 backoff |
85
+ | `--agent-rate-limit-max-delay-seconds <n>` | `180` | Max 429 backoff |
86
+ | `--agent-launch-stagger-ms <n>` | `1200` | Delay between agent launches |
67
87
  | `--orchestrator-id <id>` | `<lane>-autonomous` | Orchestrator identity |
68
88
  | `--resident-orchestrator` | off | Launch resident orchestrator for each wave |
69
89
  | `--dashboard` | off | Enable dashboards |
@@ -514,6 +534,18 @@ wave draft --show-run <run-id>
514
534
  wave draft --apply-run <run-id>
515
535
  ```
516
536
 
537
+ Interactive draft currently offers worker role kinds:
538
+
539
+ - `design`
540
+ - `implementation`
541
+ - `qa`
542
+ - `infra`
543
+ - `deploy`
544
+ - `research`
545
+ - `security`
546
+
547
+ Agentic planner payloads also accept `workerAgents[].roleKind = "design"`. The shipped `0.8.5` 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.
548
+
517
549
  ## Ad-Hoc Task Commands
518
550
 
519
551
  **Plan and run ad-hoc tasks:**
@@ -25,6 +25,17 @@ Those are related, but they are not the same.
25
25
 
26
26
  An implementation agent can be locally complete and still leave the wave blocked if it created open helper work, unresolved clarification chains, or required dependencies.
27
27
 
28
+ At runtime, those distinctions map onto separate modules:
29
+
30
+ - `implementation-engine.mjs` selects implementation work
31
+ - `derived-state-engine.mjs` rebuilds the blackboard projections
32
+ - `gate-engine.mjs` evaluates closure and barrier state from envelopes plus canonical logs
33
+ - `retry-engine.mjs` decides what can safely resume
34
+ - `closure-engine.mjs` sequences the staged closeout
35
+ - `session-supervisor.mjs` only launches sessions and records observed facts
36
+
37
+ Closure roles are resolved from the wave definition first, then from starter defaults. In other words, integration, documentation, `cont-QA`, `cont-EVAL`, and security review keep the same semantics even when a wave overrides the default role ids such as `A8`, `A9`, `A0`, `E0`, or `A7`.
38
+
28
39
  ## Durable State Surfaces
29
40
 
30
41
  The runtime writes several different artifacts, but they do different jobs:
@@ -52,6 +63,8 @@ The runtime writes several different artifacts, but they do different jobs:
52
63
 
53
64
  The important rule is that decisions come from the canonical authority set: wave definitions, the coordination log, the control-plane log, and immutable result envelopes. The markdown board is a projection for humans. See [wave-orchestrator.md](../plans/wave-orchestrator.md).
54
65
 
66
+ That control-plane log also carries observed `wave_run`, `attempt`, and `agent_run` lifecycle facts from `session-supervisor.mjs`. When human feedback or escalation remains open, the reducer materializes the wave as `clarifying` with blocked `waveState` instead of flattening it into generic progress.
67
+
55
68
  Live waves now keep refreshing that derived state while agents are still running. Shared summaries, inboxes, dashboard coordination metrics, and clarification routing are not only recomputed at attempt boundaries; they are also refreshed during active wave execution so stale clarification and acknowledgement timing is machine-visible before the attempt ends.
56
69
 
57
70
  ## What Agents Should Use
@@ -61,7 +74,7 @@ Use the coordination log for conversational or workflow state:
61
74
  - `request`
62
75
  Use this when you need another agent or capability owner to do work. Target it explicitly. This is the kind that becomes a helper assignment.
63
76
  - `blocker`
64
- Use this when the wave is blocked, but not because the launcher needs to route work to a specific assignee.
77
+ Use this when the wave is blocked, but not because the runtime needs to route work to a specific assignee.
65
78
  - `handoff`
66
79
  Use this for continuity and context transfer. This is informative by itself; it is not the same as a blocking helper assignment.
67
80
  - `evidence`
@@ -164,7 +177,7 @@ pnpm exec wave control task create \
164
177
  What happens next:
165
178
 
166
179
  - the request lands in the canonical coordination log
167
- - the launcher derives a helper assignment for `agent:A8`
180
+ - the runtime derives a helper assignment for `agent:A8`
168
181
  - that assignment is written into the assignment snapshot
169
182
  - the shared summary and A8 inbox now show the open helper work
170
183
 
@@ -230,9 +243,9 @@ pnpm exec wave coord post \
230
243
 
231
244
  What happens next:
232
245
 
233
- 1. the launcher triages the clarification from repo policy, ownership, prior decisions, and routing context
246
+ 1. the orchestrator triages the clarification from repo policy, ownership, prior decisions, and routing context
234
247
  2. if it can answer inside the wave, it writes the resolution back into coordination state
235
- 3. if another owner can answer it, the launcher opens a targeted follow-up request and keeps the clarification chain blocking
248
+ 3. if another owner can answer it, the runtime opens a targeted follow-up request and keeps the clarification chain blocking
236
249
  4. only after policy and routed follow-up paths are exhausted does it create human feedback or escalation artifacts
237
250
  5. until that chain is resolved, clarification remains a closure barrier and any routed follow-up also remains blocking helper work
238
251
 
@@ -406,7 +419,7 @@ That gives Wave two useful properties:
406
419
 
407
420
  ## Targeted Retry Behavior
408
421
 
409
- When closure fails, the launcher does not always relaunch the entire wave.
422
+ When closure fails, the runtime does not always relaunch the entire wave.
410
423
 
411
424
  It tries to relaunch only the implicated owners:
412
425
 
@@ -425,7 +438,7 @@ pnpm exec wave control rerun get --lane main --wave 10 --json
425
438
  pnpm exec wave control rerun request --lane main --wave 10 --agent A2 --agent A7 --clear-reuse A2 --reason "Resume sibling-owned component closure"
426
439
  ```
427
440
 
428
- The canonical rerun request is written under `.tmp/<lane>-wave-launcher/control-plane/`, projected to `.tmp/<lane>-wave-launcher/control/` for compatibility, consumed by the launcher on the next retry decision, and then cleared by default after one application. This is the supported path for:
441
+ The canonical rerun request is written under `.tmp/<lane>-wave-launcher/control-plane/`, projected to `.tmp/<lane>-wave-launcher/control/` for compatibility, consumed by the retry engine on the next retry decision, and then cleared by default after one application. This is the supported path for:
429
442
 
430
443
  - rerunning only specific owners
431
444
  - preserving explicit reuse selectors such as attempt ids, proof bundle ids, derived-summary reuse, and invalidated component ids through the compatibility projection
@@ -2,7 +2,7 @@
2
2
 
3
3
  This repo now includes a dedicated npmjs publish workflow at [publish-npm.yml](../../.github/workflows/publish-npm.yml).
4
4
 
5
- The current `0.8.3` release procedure publishes through a repository Actions secret named `NPM_TOKEN`.
5
+ The current `0.8.5` release procedure publishes through a repository Actions secret named `NPM_TOKEN`.
6
6
 
7
7
  ## What This Repo Already Does
8
8
 
@@ -47,6 +47,7 @@ If this repo later needs private npm dependencies during CI, consider a separate
47
47
  1. Confirm [publish-npm.yml](../../.github/workflows/publish-npm.yml) is on the default branch.
48
48
  2. Confirm `NPM_TOKEN` exists in the GitHub repo secrets.
49
49
  3. Confirm the package version has been bumped and committed.
50
- 4. Push the release commit and release tag, for example `v0.8.3`.
51
- 5. Verify both `publish-npm.yml` and `publish-package.yml` start from the tag push.
52
- 6. Verify the npmjs publish completes successfully for the tagged source.
50
+ 4. Confirm `README.md`, `CHANGELOG.md`, `releases/manifest.json`, and `docs/plans/migration.md` all describe the same release surface.
51
+ 5. Push the release commit and release tag, for example `v0.8.5`.
52
+ 6. Verify both `publish-npm.yml` and `publish-package.yml` start from the tag push.
53
+ 7. Verify the npmjs publish completes successfully for the tagged source.
@@ -1,11 +1,11 @@
1
1
  ---
2
2
  title: "Sample Waves"
3
- summary: "Showcase-first sample waves that demonstrate the current 0.8.3 Wave surface."
3
+ summary: "Showcase-first sample waves that demonstrate the shipped 0.8.5 authored surface, including the optional design-role path."
4
4
  ---
5
5
 
6
6
  # Sample Waves
7
7
 
8
- This guide points to showcase-first sample waves that demonstrate the current `0.8.3` authored Wave surface.
8
+ This guide points to showcase-first sample waves that demonstrate the shipped `0.8.5` authored Wave surface.
9
9
 
10
10
  The examples are intentionally denser than typical production waves. Their job is to teach the current authoring and runtime surface quickly, not to be the smallest possible launch-ready files.
11
11
 
@@ -15,7 +15,10 @@ The examples are intentionally denser than typical production waves. Their job i
15
15
  Shows what a good `repo-landed` outcome looks like when one promoted component only closes honestly if desired-state records, reconcile-loop substrate, and cluster-view surfaces land together. It emphasizes maturity discipline, explicit deliverables, and shared-plan closure without drifting into `pilot-live` claims.
16
16
 
17
17
  - [Full modern sample wave](../plans/examples/wave-example-live-proof.md)
18
- Shows the combined `0.8.3` authored surface in one file: closure roles, `E0`, optional security review, delegated and pinned benchmark targets, richer executor config, `### Skills`, `### Capabilities`, `### Deliverables`, `### Exit contract`, `### Proof artifacts`, sticky retry, deploy environments, and proof-first live-wave structure.
18
+ Shows the combined `0.8.5` authored surface in one file: closure roles, `E0`, optional security review, delegated and pinned benchmark targets, richer executor config, `### Skills`, `### Capabilities`, `### Deliverables`, `### Exit contract`, `### Proof artifacts`, sticky retry, deploy environments, and proof-first live-wave structure.
19
+
20
+ - [Optional design-steward handoff wave](../plans/examples/wave-example-design-handoff.md)
21
+ Shows the shipped design-role surface: one pre-implementation design steward publishes a design packet, downstream implementation owners read that packet before coding, and normal closure roles still decide final completion. For terminal or operator-surface work, pair that shape with explicit `tui-design` in the design steward's `### Skills`. For the hybrid variant, explicitly give that same design agent implementation-owned paths and the normal implementation contract sections.
19
22
 
20
23
  ## What These Examples Teach
21
24
 
@@ -35,10 +38,11 @@ The examples are intentionally denser than typical production waves. Their job i
35
38
  - sticky retry for proof-bearing owners
36
39
  - deploy environments and provider-skill examples
37
40
  - infra and deploy-verifier specialist slices
41
+ - optional pre-implementation design packets and design-to-implementation handoff
38
42
 
39
43
  ## Feature Coverage Map
40
44
 
41
- Together these samples cover the main surfaces added or hardened for `0.8.3`:
45
+ Together these samples cover the main surfaces added or hardened through `0.8.5`:
42
46
 
43
47
  - repo-landed maturity discipline and anti-overclaim framing
44
48
  - explicit shared-plan closure for future-wave safety
@@ -56,6 +60,7 @@ Together these samples cover the main surfaces added or hardened for `0.8.3`:
56
60
  - proof-first live-wave prompts
57
61
  - deploy environments and deploy-kind-aware skills
58
62
  - integration, documentation, and cont-QA closure-role structure
63
+ - optional `design` worker role and `design-pass` executor profile
59
64
 
60
65
  ## When To Copy Literally Vs Adapt
61
66
 
@@ -76,6 +81,7 @@ Adapt more aggressively when:
76
81
  ## How This Example Maps To Other Docs
77
82
 
78
83
  - Use [docs/guides/planner.md](../guides/planner.md) for the planner-generated baseline, then use these samples to see how a human would enrich the generated draft for either repo-landed or proof-first work.
84
+ - Use [Optional design-steward handoff wave](../plans/examples/wave-example-design-handoff.md) when the wave should start with a reusable design packet before implementation begins.
79
85
  - Use [docs/evals/README.md](../evals/README.md) with the full modern sample when you need to see delegated and pinned benchmark targets in a real wave.
80
86
  - Use [docs/reference/live-proof-waves.md](./live-proof-waves.md) with the full modern sample when you need proof-first authoring for `pilot-live` and above.
81
87
  - Use [docs/plans/wave-orchestrator.md](../plans/wave-orchestrator.md) for the operational runbook that explains how the launcher interprets these sections.
@@ -83,9 +89,10 @@ Adapt more aggressively when:
83
89
  ## Suggested Reading Order
84
90
 
85
91
  1. Start with [High-fidelity repo-landed rollout wave](../plans/examples/wave-example-rollout-fidelity.md) if you want the clearest example of good closure-ready wave fidelity for a repo-only outcome.
86
- 2. Read [Full modern sample wave](../plans/examples/wave-example-live-proof.md) if you want the denser proof-first and eval-heavy surface.
87
- 3. Read [docs/evals/README.md](../evals/README.md) if you want more background on benchmark target selection.
88
- 4. Read [docs/reference/live-proof-waves.md](./live-proof-waves.md) if you want more detail on proof-first `pilot-live` authoring.
92
+ 2. Read [Full modern sample wave](../plans/examples/wave-example-live-proof.md) if you want the denser proof-first and eval-heavy `0.8.5` surface.
93
+ 3. Read [Optional design-steward handoff wave](../plans/examples/wave-example-design-handoff.md) if the task needs a design packet before implementation fan-out.
94
+ 4. Read [docs/evals/README.md](../evals/README.md) if you want more background on benchmark target selection.
95
+ 5. Read [docs/reference/live-proof-waves.md](./live-proof-waves.md) if you want more detail on proof-first `pilot-live` authoring.
89
96
 
90
97
  ## Why These Examples Live In `docs/plans/examples/`
91
98
 
@@ -109,6 +109,7 @@ Top-level and lane-local skill attachment use the same shape:
109
109
  "dir": "skills",
110
110
  "base": ["wave-core", "repo-coding-rules"],
111
111
  "byRole": {
112
+ "design": ["role-design"],
112
113
  "deploy": ["role-deploy"]
113
114
  },
114
115
  "byRuntime": {
@@ -123,6 +124,8 @@ Top-level and lane-local skill attachment use the same shape:
123
124
 
124
125
  Lane-local `lanes.<lane>.skills` extends the global config instead of replacing it.
125
126
 
127
+ Optional design workers in the shipped `0.8.5` surface normally attach `role-design`. That bundle is intended for docs/spec-first design packets and explicit implementation handoff work before implementation starts. When the design packet covers terminal UX, dashboards, or other operator surfaces, add `tui-design` explicitly in the wave's `### Skills`.
128
+
126
129
  ## Resolution Order
127
130
 
128
131
  Resolved skills are gathered in this order:
@@ -195,6 +198,12 @@ Runtime delivery:
195
198
 
196
199
  These runtime projections are guidance surfaces. They should stay aligned with the canonical authority model, but they are not replay inputs or decision state on their own.
197
200
 
201
+ For the optional `design` worker role, the default pattern is:
202
+
203
+ - `role-design` for the design packet contract
204
+ - `tui-design` only when the packet covers terminal UX, dashboards, or other operator surfaces
205
+ - no runtime-specific coding bundle unless the wave explicitly gives the design steward code ownership and makes it a hybrid design steward
206
+
198
207
  ## Generated Artifacts
199
208
 
200
209
  Executor overlay directories can contain:
@@ -225,3 +234,4 @@ Missing or malformed bundles are configuration errors, not silent no-ops.
225
234
  - Use explicit per-agent `### Skills` for true exceptions, not as a substitute for missing activation metadata.
226
235
  - Keep provider skills role-scoped unless every role genuinely needs the provider context.
227
236
  - Keep bundle ids stable so traces and prompt fingerprints remain intelligible across runs.
237
+ - Keep `role-design` docs/spec-first by default; add `tui-design` when terminal or operator-surface work is in scope, and only attach broader coding bundles when the wave explicitly assigns code ownership and expects the same design steward to return for implementation.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@chllming/wave-orchestration",
3
- "version": "0.8.3",
3
+ "version": "0.8.5",
4
4
  "license": "MIT",
5
5
  "description": "Generic wave-based multi-agent orchestration for repository work.",
6
6
  "repository": {
@@ -2,6 +2,45 @@
2
2
  "schemaVersion": 1,
3
3
  "packageName": "@chllming/wave-orchestration",
4
4
  "releases": [
5
+ {
6
+ "version": "0.8.5",
7
+ "date": "2026-03-25",
8
+ "summary": "Shipped design-role support, hybrid design-steward execution, release-surface alignment, and a practical migration guide.",
9
+ "features": [
10
+ "The optional `design` worker role is now part of the published release surface, including the standing design prompt, `role-design`, and `tui-design` starter bundles.",
11
+ "Design stewards are docs-first by default, but waves can now explicitly give them implementation ownership so the same agent runs a design pass first and then rejoins implementation with normal proof obligations.",
12
+ "Design-aware validation, prompts, gates, retry or resume planning, reducer state, local-executor smoke behavior, and result-envelope projection now all agree on the same hybrid-design contract.",
13
+ "The migration guide now covers fresh adoption plus upgrades from `0.8.4`, `0.8.0`-`0.8.4`, `0.6.x`-`0.7.x`, and `0.5.x` or earlier, including repo-owned starter-surface sync guidance and `planner-agentic` corpus notes.",
14
+ "Shipped package metadata, README, current-state notes, sample-wave docs, and publishing guidance now point at the `0.8.5` release surface."
15
+ ],
16
+ "manualSteps": [
17
+ "Run `pnpm exec wave doctor` and `pnpm exec wave launch --lane main --dry-run --no-dashboard` after upgrading so the repo validates against the `0.8.5` design-role and hybrid-design behavior.",
18
+ "If your repo copied starter prompts, skills, or authoring docs, sync `docs/agents/wave-design-role.md`, `skills/role-design/`, `skills/tui-design/`, `wave.config.json` design-role keys, and any local planner or runbook pages that should describe the new design-steward model.",
19
+ "If a repo uses hybrid design stewards, make sure each one still owns a design packet path and that any explicit implementation ownership also carries the expected exit contract, deliverables, proof artifacts, and component declarations where your lane validation requires them.",
20
+ "If your repo uses planner workflows and copied the planner starter corpus, keep `docs/agents/wave-planner-role.md`, `skills/role-planner/`, `docs/context7/planner-agent/`, `docs/reference/wave-planning-lessons.md`, and the `planner-agentic` bundle entry in sync before relying on local planner docs."
21
+ ],
22
+ "breaking": false
23
+ },
24
+ {
25
+ "version": "0.8.4",
26
+ "date": "2026-03-25",
27
+ "summary": "Contradiction replay repair, consistent component-promotion thresholds, projection-writer persistence centralization, and 0.8.4 release-surface alignment.",
28
+ "features": [
29
+ "Hermetic contradiction replay no longer depends on component-matrix parsing when the trace does not declare promoted components.",
30
+ "`requireComponentPromotionsFromWave` now gates both component-promotion proof validation and component-matrix current-level validation consistently across live and replay paths.",
31
+ "Projection persistence is now centralized under `projection-writer.mjs`, while `derived-state-engine.mjs` computes projection payloads without writing them directly.",
32
+ "The operator migration guide now covers fresh adoption plus upgrades from `0.8.3`, `0.8.0`-`0.8.2`, `0.6.x`-`0.7.x`, and `0.5.x` or earlier with explicit repo-owned surface sync guidance.",
33
+ "Shipped package metadata, README, migration guidance, current-state notes, sample-wave docs, and npm publishing instructions now point at the `0.8.4` release surface."
34
+ ],
35
+ "manualSteps": [
36
+ "Run `pnpm exec wave doctor` and `pnpm exec wave launch --lane main --dry-run --no-dashboard` after upgrading so the repo validates against the `0.8.4` replay, projection, and component-threshold behavior.",
37
+ "If your adopted repo uses planner workflows and copied the starter planner corpus, sync `docs/agents/wave-planner-role.md`, `skills/role-planner/`, `docs/context7/planner-agent/`, `docs/reference/wave-planning-lessons.md`, and the `planner-agentic` bundle entry in `docs/context7/bundles.json`.",
38
+ "If your repo copied the shipped starter docs or skills, sync the current operator runbook, architecture docs, launcher or orchestrator prompts, planner corpus, and relevant runtime or closure-role starter skills before relying on local runbooks.",
39
+ "If your repo keeps historical replay fixtures, replay at least one contradiction-blocked trace and one promoted-component trace after the upgrade so both code paths stay covered.",
40
+ "If an older adopted repo still carries legacy evaluator wording or pre-control-plane operator docs, complete the repo-owned prompt and runbook migration described in `docs/plans/migration.md` before cutting live waves on `0.8.4`."
41
+ ],
42
+ "breaking": false
43
+ },
5
44
  {
6
45
  "version": "0.8.3",
7
46
  "date": "2026-03-24",