@chllming/wave-orchestration 0.6.3 → 0.7.1

package/docs/guides/terminal-surfaces.md

@@ -45,6 +45,17 @@ Use `tmux` when:
 
 By default the launcher can start per-wave dashboard sessions in tmux.
 
+Wave now maintains stable tmux attach targets for both the current-wave dashboard and the global dashboard on the lane socket.
+
+Use:
+
+```bash
+pnpm exec wave dashboard --lane main --attach current
+pnpm exec wave dashboard --lane main --attach global
+```
+
+Those commands work for both `tmux` and `vscode` terminal surfaces because the live sessions still run on the lane tmux socket.
+
 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.
 
 Important flags:
@@ -63,6 +74,7 @@ Important flags:
 - Use `vscode` for local interactive operator work when the temporary terminal registry is useful.
 - Use `tmux` for remote, CI-like, or editor-independent operation.
 - Use `none` only with `--dry-run`.
+- Prefer `wave dashboard --attach current|global` over manual `tmux -L <socket> attach ...` lookups.
 - Pair `--keep-sessions` with incident review or deep debugging, not as a default steady-state mode.
 - Pair `--no-dashboard` with scripted dry-runs or when the board and summaries are sufficient.
 

package/docs/plans/context7-wave-orchestrator.md

@@ -4,6 +4,11 @@ See also [concepts/context7-vs-skills.md](../concepts/context7-vs-skills.md) for
 
 Context7 is for external library truth. Repository docs and source are for repository truth.
 
+The one deliberate exception in this repo is the planner corpus under
+`docs/context7/planner-agent/`: it is a tracked export of selected local
+planning research that the operator can publish as a custom Context7 library for
+the agentic planner.
+
 ## Rules
 
 - Prefer a narrow bundle per agent or wave.
@@ -30,6 +35,21 @@ pnpm context7:api-check
 
 4. Review [docs/context7/bundles.json](../context7/bundles.json) and trim it to the external libraries your repository actually uses.
 
+## Planner Bundle
+
+The shipped bundle index includes `planner-agentic`, which expects a published
+Context7 library named `wave-planner-agentic`.
+
+The source files for that library live under `docs/context7/planner-agent/`.
+Refresh that folder from the ignored agent-context cache with:
+
+```bash
+pnpm research:sync-planner-context7
+```
+
+After you publish the folder to Context7, the agentic planner will prefetch that
+bundle through `planner.agentic.context7Bundle`.
+
 ## Resolution Order
 
 1. Agent `### Context7`

package/docs/plans/current-state.md

@@ -1,6 +1,6 @@
 # Current State
 
-- The starter workspace in this source repo reflects the `0.6.3` package release surface.
+- The starter workspace in this source repo reflects the `0.7.1` package release surface.
 - The repository contains the published `@chllming/wave-orchestration` package plus the starter scaffold used by `wave init`.
 - 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/`.
 - 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.
@@ -28,6 +28,7 @@
   - a canonical coordination JSONL log
   - a generated markdown board projection
   - compiled shared summaries and per-agent inboxes
+  - active live-wave orchestration refresh that keeps summaries, inboxes, clarification triage, and dashboard coordination metrics current while agents are still running
   - a per-wave ledger
   - docs queues
   - explicit integration summaries with actionable claim, interface, proof, docs, and deploy-risk evidence
@@ -36,7 +37,12 @@
   - hermetic `traceVersion: 2` per-attempt trace bundles with copied launched-agent summaries, copied component matrices for promoted waves, a hashed `outcome.json` replay baseline, run metadata, and cumulative quality metrics
   - an internal, read-only replay validator for trace bundles, with legacy `traceVersion: 1` bundles kept in best-effort warning mode
   - orchestrator-first clarification triage plus human escalation artifacts
+  - optional `--resident-orchestrator` support for a long-running, non-owning orchestrator session during live waves
   - persisted relaunch plans under `.tmp/<lane>-wave-launcher/status/` so targeted retry intent can survive a launcher restart
+  - a canonical control-plane event log under `.tmp/<lane>-wave-launcher/control-plane/` that records operator tasks, rerun requests, proof bundles, attempt lifecycle, and human-input events as append-only JSONL; `wave control` materializes state from this log
+  - operator-applied retry overrides projected to `.tmp/<lane>-wave-launcher/control/` for compatibility with selected reruns, explicit reuse selectors, reuse clearing or preservation, and explicit resume targets
+  - authoritative proof registries projected to `.tmp/<lane>-wave-launcher/proof/` for compatibility, while preserving proof bundle lifecycle state so revoked or superseded operator evidence cannot keep satisfying closure
+  - optional Wave Control telemetry under `.tmp/<lane>-wave-launcher/control-plane/telemetry/` for local-first, best-effort reporting to the Railway-hosted analysis plane
   - a thinner launcher entrypoint that now delegates session launch or wait and closure-sweep orchestration to dedicated modules while preserving the existing CLI surface
 - Runtime executor support now includes:
   - Codex `exec` profile, inline config, search, image, add-dir, JSON, and ephemeral flags
@@ -62,6 +68,7 @@
 - Live closure is strict: `cont-EVAL` must prove the declared eval contract with exact target and benchmark ids, and `cont-QA` must provide both final verdict and final gate artifacts. Legacy evaluator-era shapes remain replay-only compatibility inputs.
 - Proof-centric waves can now declare `### Proof artifacts`, and implementation proof validation can require those machine-visible local artifacts in addition to deliverables and structured proof markers.
 - Routed clarifications remain blocking until the linked follow-up request or escalation is fully resolved.
+- Operators can now use `wave control status`, `wave control task`, `wave control rerun`, and `wave control proof` as the preferred supported control surfaces during a live wave instead of editing runtime files by hand. Legacy `wave coord`, `wave retry`, and `wave proof` commands remain as compatibility paths.
 - Required inbound cross-lane dependency tickets under `.tmp/wave-orchestrator/dependencies/` block both autonomous wave launch and lane finalization while they remain unresolved.
 - Cross-lane dependency workflows now include:
   - `wave dep post|show|resolve|render`

package/docs/plans/examples/wave-benchmark-improvement.md

@@ -0,0 +1,108 @@
+# Wave 99 - Benchmark Improvement Loop
+
+This example shows how to author a Wave whose job is to improve benchmark outcomes after a baseline already exists.
+
+## Eval targets
+
+- id: hidden-profile-pooling | selection: pinned | benchmarks: private-evidence-integration,premature-consensus-guard | objective: Improve distributed evidence pooling without allowing premature closure | threshold: Full-wave benchmark scores improve without regressing closure discipline
+- id: routing-quality | selection: pinned | benchmarks: expert-routing-preservation,lockstep-resolution | objective: Improve capability routing and simultaneous coordination | threshold: Routing benchmarks improve and no new deadlock-like regressions appear
+
+## Agent A0: cont-QA
+
+### Prompt
+
+```text
+Primary goal:
+- Block any claimed improvement that is not backed by rerun benchmark output.
+
+Specific expectations:
+- require benchmark reruns after each material change
+- do not PASS on inspection-only claims
+- treat benchmark regressions as blocking until they are resolved or explicitly accepted
+
+File ownership (only touch these paths):
+- docs/plans/waves/reviews/wave-99-cont-qa.md
+```
+
+## Agent E0: cont-EVAL
+
+### Prompt
+
+```text
+Primary goal:
+- Run the benchmark loop, identify the narrowest failing coordination surfaces, and keep benchmark ids explicit in every iteration.
+
+Specific expectations:
+- choose the smallest benchmark subset that still proves the claimed improvement
+- record baseline, current score, regressions, and exact benchmark ids
+- stay report-only unless this wave explicitly grants implementation ownership
+
+File ownership (only touch these paths):
+- docs/plans/waves/reviews/wave-99-cont-eval.md
+```
+
+## Agent A8: Integration Steward
+
+### Prompt
+
+```text
+Primary goal:
+- Synthesize benchmark evidence, implementation deltas, and regression risk into one integrated recommendation.
+
+Specific expectations:
+- call out any contradiction between benchmark wins and runtime or docs regressions
+- prefer explicit follow-up requests over vague risk notes
+
+File ownership (only touch these paths):
+- .tmp/main-wave-launcher/integration/wave-99.md
+```
+
+## Agent A1: Coordination Store Hardening
+
+### Deliverables
+
+- scripts/wave-orchestrator/coordination-store.mjs
+- test/wave-orchestrator/coordination-store.test.ts
+
+### Prompt
+
+```text
+Primary goal:
+- Improve targeted inbox recall or summary fidelity for the benchmark cases that E0 reports as failing.
+
+Specific expectations:
+- keep changes tightly scoped to the failing benchmark signals
+- add regression coverage for any changed behavior
+- coordinate doc-impact with A9 if the benchmark semantics or operator surfaces change
+
+File ownership (only touch these paths):
+- scripts/wave-orchestrator/coordination-store.mjs
+- test/wave-orchestrator/coordination-store.test.ts
+```
+
+## Agent A2: Routing And Closure Hardening
+
+### Deliverables
+
+- scripts/wave-orchestrator/routing-state.mjs
+- scripts/wave-orchestrator/benchmark.mjs
+- test/wave-orchestrator/routing-state.test.ts
+- test/wave-orchestrator/benchmark.test.ts
+
+### Prompt
+
+```text
+Primary goal:
+- Improve routing or closure benchmark outcomes without weakening evidence requirements.
+
+Specific expectations:
+- preserve deterministic benchmark behavior
+- prefer narrow routing and guard changes over broad orchestration rewrites
+- rerun the affected benchmark cases after each material change
+
+File ownership (only touch these paths):
+- scripts/wave-orchestrator/routing-state.mjs
+- scripts/wave-orchestrator/benchmark.mjs
+- test/wave-orchestrator/routing-state.test.ts
+- test/wave-orchestrator/benchmark.test.ts
+```

package/docs/plans/examples/wave-example-live-proof.md

@@ -2,7 +2,7 @@
 
 This is a showcase-first sample wave.
 
-Use it as the single reference example for the current `0.6.1` Wave surface.
+Use it as the single reference example for the current `0.7.1` Wave surface.
 
 It intentionally combines more sections than a normal production wave so one file can demonstrate:
 

package/docs/plans/examples/wave-example-rollout-fidelity.md

@@ -0,0 +1,340 @@
+# Wave 9 - Rollout Substrate + Desired-State Records
+
+This is a showcase-first sample wave for a high-fidelity `repo-landed` outcome.
+
+Use it when you want a concrete example of what "good" looks like for a wave
+that lands one cohesive substrate across multiple implementation slices without
+over-claiming `pilot-live` or `fleet-ready` proof.
+
+This example is intentionally generic. The component id, deliverable paths, and
+Go control-plane slices are illustrative, but the authored Wave structure,
+closure expectations, and maturity discipline match the current surface.
+
+**Commit message**: `Feat: land rollout substrate and desired-state records`
+
+## Component promotions
+
+- rollout-cores-and-cluster-view: repo-landed
+
+## Deploy environments
+
+- repo-local: custom default (repo-local rollout substrate work; no live host mutation)
+
+## Context7 defaults
+
+- bundle: go-services
+- query: "Desired state, reconcile loops, rollout metadata, and cluster-view surfaces for Go control-plane rollout work"
+
+## Agent A0: cont-QA
+
+### Role prompts
+
+- docs/agents/wave-cont-qa-role.md
+
+### Executor
+
+- profile: deep-review
+- claude.permission_mode: plan
+- claude.settings: .claude/settings.json
+- claude.output_format: text
+
+### Context7
+
+- bundle: none
+- query: "Repository docs remain canonical for cont-QA"
+
+### Prompt
+
+```text
+Primary goal:
+- Judge whether Wave 9 honestly lands rollout-cores-and-cluster-view at repo-landed without implying pilot-live or fleet-ready proof.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/plans/master-plan.md, docs/plans/current-state.md, and docs/plans/migration.md.
+- Read docs/plans/component-cutover-matrix.md and docs/reference/wave-planning-lessons.md.
+
+Specific expectations:
+- do not PASS unless desired-state records, reconcile-loop substrate, and cluster-view surfaces all land together
+- treat repo-landed as a lower bar than pilot-live and fleet-ready
+- require shared-plan updates when the future-wave baseline changes
+- emit the final `[wave-gate] ...` marker as a plain last line before `Verdict: ...`
+
+File ownership (only touch these paths):
+- docs/plans/waves/reviews/wave-9-cont-qa.md
+```
+
+## Agent A8: Integration Steward
+
+### Role prompts
+
+- docs/agents/wave-integration-role.md
+
+### Executor
+
+- profile: deep-review
+- claude.permission_mode: plan
+- claude.settings: .claude/settings.json
+- claude.output_format: text
+
+### Context7
+
+- bundle: none
+- query: "Repository docs remain canonical for integration"
+
+### Prompt
+
+```text
+Primary goal:
+- Reconcile desired-state, cluster-view, and reconcile-loop slices into one closure-ready repo-landed verdict.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/plans/master-plan.md and docs/plans/current-state.md.
+- Read docs/plans/component-cutover-matrix.md and docs/reference/wave-planning-lessons.md.
+
+Specific expectations:
+- treat missing rollout substrate pieces as integration failures
+- decide `ready-for-doc-closure` vs `needs-more-work` based on the landed substrate, not intent
+- emit the final `[wave-integration] ...` marker as a plain last line
+
+File ownership (only touch these paths):
+- .tmp/main-wave-launcher/integration/wave-9.md
+- .tmp/main-wave-launcher/integration/wave-9.json
+```
+
+## Agent A9: Documentation Steward
+
+### Role prompts
+
+- docs/agents/wave-documentation-role.md
+
+### Executor
+
+- profile: docs-pass
+- claude.settings: .claude/settings.json
+- claude.output_format: text
+
+### Context7
+
+- bundle: none
+- query: "Shared-plan documentation only"
+
+### Prompt
+
+```text
+Primary goal:
+- Keep shared plan docs and the component matrix aligned with the real Wave 9 rollout-substrate outcome.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/plans/master-plan.md, docs/plans/current-state.md, and docs/plans/migration.md.
+- Read docs/plans/component-cutover-matrix.md and docs/reference/wave-planning-lessons.md.
+
+Specific expectations:
+- update shared plan docs when Wave 9 changes what later waves may safely assume
+- leave an exact `closed` or `no-change` note for A0
+- emit the final `[wave-doc-closure] ...` marker as a plain last line
+
+File ownership (only touch these paths):
+- docs/plans/master-plan.md
+- docs/plans/current-state.md
+- docs/plans/migration.md
+- docs/plans/component-cutover-matrix.md
+- docs/plans/component-cutover-matrix.json
+```
+
+## Agent A1: Desired-State Records And Rollout Store
+
+### Executor
+
+- profile: implement-fast
+- model: gpt-5.4
+- codex.config: model_reasoning_effort=xhigh,model_verbosity=low
+
+### Context7
+
+- bundle: go-services
+- query: "Desired-state persistence, rollout records, and authoritative state transitions"
+
+### Skills
+
+- role-implementation
+- runtime-codex
+- repo-coding-rules
+
+### Components
+
+- rollout-cores-and-cluster-view
+
+### Capabilities
+
+- rollout-authority
+- desired-state
+
+### Exit contract
+
+- completion: integrated
+- durability: durable
+- proof: integration
+- doc-impact: owned
+
+### Deliverables
+
+- go/internal/rollout/desiredstate/store.go
+- go/internal/rollout/desiredstate/store_test.go
+- docs/plans/operations/wave-9-rollout-state-model.md
+
+### Prompt
+
+```text
+Primary goal:
+- Land the durable desired-state store and revision model for rollout ownership inside the Go control plane.
+
+Specific expectations:
+- Emit the final `[wave-proof]`, `[wave-doc-delta]`, and `[wave-component]`
+  markers as plain lines by themselves at the end of the output. Do not wrap
+  them in backticks, quotes, or code fences.
+- Do not stop after code or tests alone. Treat the missing final marker lines
+  as an incomplete attempt even if the deliverables already exist on disk.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/plans/migration.md and docs/reference/wave-planning-lessons.md.
+
+File ownership (only touch these paths):
+- go/internal/rollout/desiredstate/
+- docs/plans/operations/wave-9-rollout-state-model.md
+```
+
+## Agent A2: Cluster View And Observed-State Projections
+
+### Executor
+
+- profile: implement-fast
+- model: gpt-5.4
+- codex.config: model_reasoning_effort=xhigh,model_verbosity=low
+
+### Context7
+
+- bundle: go-services
+- query: "Cluster-view, observed-state projections, and rollout-facing status surfaces"
+
+### Skills
+
+- role-implementation
+- runtime-codex
+- repo-coding-rules
+
+### Components
+
+- rollout-cores-and-cluster-view
+
+### Capabilities
+
+- cluster-view
+- observed-state
+
+### Exit contract
+
+- completion: integrated
+- durability: durable
+- proof: integration
+- doc-impact: owned
+
+### Deliverables
+
+- go/internal/cluster/view/status.go
+- go/internal/cluster/view/status_test.go
+- docs/plans/qa/wave-9-cluster-view-projections.md
+
+### Prompt
+
+```text
+Primary goal:
+- Land repo-visible cluster-view and observed-state projections that later rollout and cutover waves can trust.
+
+Specific expectations:
+- Emit the final `[wave-proof]`, `[wave-doc-delta]`, and `[wave-component]`
+  markers as plain lines by themselves at the end of the output. Do not wrap
+  them in backticks, quotes, or code fences.
+- Do not stop after code or tests alone. Treat the missing final marker lines
+  as an incomplete attempt even if the deliverables already exist on disk.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/plans/migration.md and docs/reference/wave-planning-lessons.md.
+
+File ownership (only touch these paths):
+- go/internal/cluster/view/
+- docs/plans/qa/wave-9-cluster-view-projections.md
+```
+
+## Agent A3: Task Plane And Reconcile Loop Skeleton
+
+### Executor
+
+- profile: implement-fast
+- model: gpt-5.4
+- codex.config: model_reasoning_effort=xhigh,model_verbosity=low
+
+### Context7
+
+- bundle: go-services
+- query: "Worker task planes, reconcile loops, and rollout-safe execution boundaries"
+
+### Skills
+
+- role-implementation
+- runtime-codex
+- repo-coding-rules
+
+### Components
+
+- rollout-cores-and-cluster-view
+
+### Capabilities
+
+- reconcile-loop
+- task-plane
+
+### Exit contract
+
+- completion: integrated
+- durability: durable
+- proof: integration
+- doc-impact: owned
+
+### Deliverables
+
+- go/internal/rollout/reconcile/worker.go
+- go/internal/rollout/reconcile/worker_test.go
+- docs/plans/operations/wave-9-reconcile-loop.md
+
+### Prompt
+
+```text
+Primary goal:
+- Land the narrow task-plane and reconcile-loop substrate without turning workers into peer control planes.
+
+Specific expectations:
+- Emit the final `[wave-proof]`, `[wave-doc-delta]`, and `[wave-component]`
+  markers as plain lines by themselves at the end of the output. Do not wrap
+  them in backticks, quotes, or code fences.
+- Do not stop after code or tests alone. Treat the missing final marker lines
+  as an incomplete attempt even if the deliverables already exist on disk.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/plans/migration.md and docs/reference/wave-planning-lessons.md.
+
+File ownership (only touch these paths):
+- go/internal/rollout/reconcile/
+- docs/plans/operations/wave-9-reconcile-loop.md
+```

package/docs/plans/migration.md

@@ -22,6 +22,32 @@ GitHub Packages remains available as an authenticated fallback path, and maintai
 - Fresh `wave init` seeds the starter `skills/` library. `wave init --adopt-existing` records existing repo-owned skill bundles when they are already present, but does not replace or rewrite them.
 - The current runtime expects the post-roadmap model: typed coordination, compiled inboxes, `A8` integration, staged closure, orchestrator-first clarification, and operational runtime policy.
 
+## Upgrading From 0.6.x To 0.7.1
+
+Read `CHANGELOG.md` first, then treat this section as the repo-owned migration checklist for adopted `0.6.x` workspaces.
+
+`wave upgrade` updates the installed runtime only. It does not copy planner starter files into a repo that already owns its docs, skills, and Context7 bundles.
+
+`0.7.1` also hardens run-control behavior for manual relaunches: fresh live starts clear stale auto-generated relaunch plans by default unless `--resume-control-state` is passed, and `wave control status` now treats the active attempt as the authoritative live fan-out while that attempt is running.
+
+### Required Repo Changes
+
+If the repo adopted Wave before the planner corpus became a tracked required surface, sync:
+
+- `docs/agents/wave-planner-role.md`
+- `skills/role-planner/`
+- `docs/context7/planner-agent/`
+- `docs/reference/wave-planning-lessons.md`
+- the `planner-agentic` bundle entry in `docs/context7/bundles.json`
+
+### Recommended Upgrade Validation
+
+After syncing those repo-owned files:
+
+1. Run `pnpm exec wave doctor`.
+2. Run `pnpm exec wave launch --lane main --dry-run --no-dashboard`.
+3. Use `pnpm exec wave dashboard --lane <lane> --attach current` or `--attach global` when you need to reattach to a live tmux-backed dashboard without reverse-engineering the socket or session name.
+
 ## Upgrading From 0.5.4 To 0.6.1
 
 Read `CHANGELOG.md` first, then treat the rest of this page as the manual repo-owned migration checklist for the `0.6.1` release. `wave upgrade` will update package-owned runtime code only; it will not rewrite the docs, prompts, config, or wave files that your repo already owns.