@chllming/wave-orchestration 0.5.4 → 0.6.0

package/docs/plans/migration.md

@@ -21,3 +21,45 @@ GitHub Packages remains available as an authenticated fallback path, and maintai
 - Existing `wave.config.json`, role prompts, plan docs, `skills/` bundles, Context7 bundles, and wave files are never overwritten by the upgrade flow.
 - 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.5.4 To 0.6.0
+
+Read `CHANGELOG.md` first, then treat the rest of this page as the manual repo-owned migration checklist for the `0.6.0` 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.
+
+### Required Repo Changes
+
+1. Rename legacy `evaluator` config and prompt terminology to `cont-QA`.
+2. Keep `A0` as the final closure owner that emits both the final verdict and `[wave-gate]`.
+3. Add `E0` only when the wave needs benchmark-driven tuning or service-output evaluation.
+4. Add wave-level `## Eval targets` whenever `cont-EVAL` is present.
+5. Update any starter docs or examples that still describe the pre-`0.6.0` evaluator model.
+
+In practice that means checking:
+
+- `wave.config.json`
+  Remove or rename `roles.evaluator*`, `skills.byRole.evaluator`, and `runtimePolicy.defaultExecutorByRole.evaluator`.
+- `docs/agents/*.md`
+  Rename or replace any legacy evaluator prompt files so the repo clearly distinguishes `cont-QA`, `cont-EVAL`, and optional security review.
+- `docs/plans/waves/*.md`
+  Update wave agent headings, role prompts, and closure expectations to use `A0` for `cont-QA`, optional `E0` for eval tuning, and optional security review before integration.
+- `docs/reference/` and other operator docs
+  Refresh any examples or internal runbooks that still describe one overloaded evaluator role.
+
+### Closure And Marker Changes
+
+Live `0.6.0` closure is stricter than `0.5.4`.
+
+- `cont-EVAL` must leave a report plus a final `[wave-eval]` marker whose `target_ids` exactly matches the wave contract and whose `benchmark_ids` stays within the benchmark catalog.
+- Security review, when present, must leave a report plus a final `[wave-security]` marker.
+- `cont-QA` must leave both the final `Verdict:` line and the final `[wave-gate]` marker.
+- Older evaluator-era or verdict-only artifacts remain replay-readable, but they do not satisfy live completion anymore.
+
+### Recommended Upgrade Validation
+
+After updating 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 coord show --lane main --wave 0 --dry-run --json` as a read-only inspection path for the coordination state.
+4. Use `pnpm exec wave coord inbox --lane main --wave 0 --agent A1 --dry-run` when you want the launcher to materialize shared-summary and inbox artifacts for review.
+5. If the repo adopts `cont-EVAL`, verify that every live eval wave declares `## Eval targets` and that the benchmark ids exist in `docs/evals/benchmark-catalog.json`.

package/docs/plans/wave-orchestrator.md

@@ -7,23 +7,30 @@ For the broader docs map, concept pages, and workflow guides, start at [docs/REA
 ## What It Does
 
 - parses wave plans from `docs/plans/waves/`
+- supports transient ad-hoc runs from `.wave/adhoc/runs/` on the same launcher substrate
 - fans a wave out into one session per `## Agent ...` section
 - supports standing role imports from `docs/agents/*.md`
 - seeds a coordination log, generated board, compiled shared summary, and per-agent inboxes
-- derives a per-wave ledger, docs queue, integration summary, and versioned per-attempt trace bundle
+- derives a per-wave ledger, security summary, docs queue, integration summary, and versioned per-attempt trace bundle
+- versions the runtime JSON surfaces that operators and replay tooling consume, including manifests, dashboards, relaunch plans, assignment snapshots, dependency snapshots, and run-state
 - validates Context7 declarations and exit contracts from configurable wave thresholds
 - validates component promotions and component-owned proof from configurable wave thresholds
 - writes prompts, logs, dashboards, coordination state, and status summaries under `.tmp/`
 - supports launcher-side Context7 prefetch and injection for headless runs
 - supports headless execution through `codex`, `claude`, `opencode`, and the local smoke executor
+- can retry rate-limited `codex`, `claude`, and `opencode` launches with per-agent exponential backoff via `--agent-rate-limit-*`
 - supports a file-backed human feedback queue
-- performs a closure sweep so integration, documentation, and evaluator gates reflect final landed state
+- performs a closure sweep so optional `cont-EVAL`, optional security review, integration, documentation, and cont-QA gates reflect final landed state
 
 ## Main Commands
 
 - `pnpm exec wave project setup`
 - `pnpm exec wave project show --json`
 - `pnpm exec wave draft --wave 1 --template implementation`
+- `pnpm exec wave adhoc plan --task "patch the planner output"`
+- `pnpm exec wave adhoc run --task "patch the planner output" --yes`
+- `pnpm exec wave adhoc show --run <id>`
+- `pnpm exec wave adhoc promote --run <id> --wave 4`
 - `pnpm exec wave init`
 - `pnpm exec wave init --adopt-existing`
 - `pnpm exec wave doctor`
@@ -42,11 +49,18 @@ For the broader docs map, concept pages, and workflow guides, start at [docs/REA
 
 ## Configuration
 
-- `wave.config.json` controls docs roots, shared plan docs, role prompts, validation thresholds, executor defaults, executor profiles, per-lane runtime policy, skill attachment policy, component-cutover matrix paths, capability-routing preferences, and Context7 bundle-index location.
+- `wave.config.json` controls docs roots, shared plan docs, role prompts, validation thresholds, executor defaults, executor profiles, per-lane runtime policy, skill attachment policy, component-cutover matrix paths, capability-routing preferences, and Context7 bundle-index location. The starter config also wires the optional security reviewer prompt at `docs/agents/wave-security-role.md` and the `security-review` executor profile.
 - `docs/context7/bundles.json` controls allowed external library bundles and lane defaults.
+- `docs/evals/README.md` explains how to author delegated versus pinned `## Eval targets`, including the coordination-oriented benchmark families.
+- `docs/reference/live-proof-waves.md` explains how to author proof-first `pilot-live` and higher-maturity waves with `### Proof artifacts`, sticky executors, and operator command capture.
+- `docs/reference/sample-waves.md` points to showcase-first sample waves that combine the modern authored wave surface in concrete examples.
 - `docs/plans/component-cutover-matrix.json` is the canonical machine-readable source for component maturity and per-wave promotion targets.
 - `.wave/install-state.json` records how the workspace was initialized and which package version is installed.
 - `.wave/project-profile.json` records planner defaults such as oversight mode, terminal surface, and deploy-environment memory.
+- `.wave/adhoc/runs/<run-id>/` stores transient ad-hoc request, spec, rendered markdown, and result artifacts.
+- ad-hoc documentation closure always writes `.wave/adhoc/runs/<run-id>/reports/`, but shared-plan deltas still queue the canonical lane shared-plan docs.
+- ad-hoc task ownership inference only accepts repo-local paths; URLs and other external references are ignored.
+- `wave adhoc promote` promotes the stored ad-hoc spec into `docs/plans/waves/` instead of re-reading the current project profile.
 
 ## Skill Packs
 
@@ -58,7 +72,7 @@ For the broader docs map, concept pages, and workflow guides, start at [docs/REA
 - Starter bundles in this repo cover:
   - core Wave coordination and repo coding rules
   - runtime packs for Codex, Claude, OpenCode, and local execution
-  - role packs for implementation, integration, documentation, evaluator, infra, deploy, and research work
+  - role packs for implementation, `cont-EVAL`, security review, integration, documentation, cont-QA, infra, deploy, and research work
   - deploy and environment packs for Railway, Docker Compose, Kubernetes, SSH/manual rollout, and generic custom deploys
   - explicit provider packs for GitHub release flow and AWS norms when a wave or lane wants to attach them
 
@@ -101,7 +115,7 @@ pnpm exec wave launch --lane main --start-wave 0 --end-wave 0 --executor codex -
 
 ## Coordination Surfaces
 
-- `wave coord show` reads the materialized coordination state for a wave.
+- `wave coord show` is a read-only view of the materialized coordination state for a wave.
 - `wave coord render` regenerates the markdown board projection from the canonical coordination log.
 - `wave coord inbox` writes the compiled shared summary plus the selected agent inbox.
 - `wave coord post` appends a structured record to the coordination log. This is the machine-readable path for blockers, handoffs, evidence, targeted requests, and clarification requests.
@@ -149,11 +163,14 @@ pnpm exec wave changelog --since-installed
 - prompts: `.tmp/<lane>-wave-launcher/prompts/`
 - logs: `.tmp/<lane>-wave-launcher/logs/`
 - status summaries: `.tmp/<lane>-wave-launcher/status/`
+  `run-state.json` keeps compatibility `completedWaves`, but now also stores per-wave current state plus append-only transition history and completion or blocker evidence. Relaunch plans in this directory are schema-versioned.
 - coordination logs: `.tmp/<lane>-wave-launcher/coordination/`
 - helper-assignment snapshots: `.tmp/<lane>-wave-launcher/assignments/`
 - message boards: `.tmp/<lane>-wave-launcher/messageboards/`
 - compiled inboxes: `.tmp/<lane>-wave-launcher/inboxes/`
 - ledger: `.tmp/<lane>-wave-launcher/ledger/`
+- security summaries: `.tmp/<lane>-wave-launcher/security/`
+  The launcher writes `wave-<n>.json` and `wave-<n>.md` summaries here, and the starter planner also places the reviewer-owned security report in this directory.
 - integration summaries: `.tmp/<lane>-wave-launcher/integration/`
   These summaries now carry actionable evidence for conflicting claims, changed interfaces, cross-component impacts, proof gaps, documentation gaps, and deploy or ops risk.
 - dependency snapshots: `.tmp/<lane>-wave-launcher/dependencies/`
@@ -161,6 +178,7 @@ pnpm exec wave changelog --since-installed
 - trace bundles: `.tmp/<lane>-wave-launcher/traces/`
 - clarification triage: `.tmp/<lane>-wave-launcher/feedback/triage/`
 - dashboards: `.tmp/<lane>-wave-launcher/dashboards/`
+  Dashboard JSON is a versioned contract. `global.json` and `wave-<n>.json` now carry explicit `schemaVersion` and `kind` fields.
 - Context7 cache: `.tmp/<lane>-wave-launcher/context7-cache/`
 - executor overlays: `.tmp/<lane>-wave-launcher/executors/`
   Each agent overlay can include `skills.resolved.md`, `skills.metadata.json`, and `<runtime>-skills.txt` in addition to the runtime-specific executor files.
@@ -168,6 +186,10 @@ pnpm exec wave changelog --since-installed
   Required inbound tickets in this directory block both autonomous wave launch and lane finalization until they resolve.
 - cross-wave orchestration board: `.tmp/wave-orchestrator/messageboards/orchestrator.md`
 
+Ad-hoc runs mirror the same state shape under `.tmp/<lane>-wave-launcher/adhoc/<run-id>/`, including dry-run previews at `.tmp/<lane>-wave-launcher/adhoc/<run-id>/dry-run/`. Their docs queue can still point at canonical shared-plan docs when the run reports a shared-plan delta.
+
+The launcher entrypoint in `scripts/wave-orchestrator/launcher.mjs` now delegates session launch or wait mechanics to `launcher-runtime.mjs` and closure-sweep sequencing to `launcher-closure.mjs`. The CLI and `traceVersion: 2` replay contract stay unchanged.
+
 ## Trace Contract
 
 - Dry-run is pre-attempt only. It writes manifest, coordination, board projection, inboxes, ledger, docs queue, and integration state under `.tmp/<lane>-wave-launcher/dry-run/`.
@@ -178,6 +200,7 @@ pnpm exec wave changelog --since-installed
   - `coordination.materialized.json`
   - `ledger.json`
   - `docs-queue.json`
+  - `security.json`
   - `integration.json`
   - `outcome.json`
   - `shared-summary.md`
@@ -188,6 +211,7 @@ pnpm exec wave changelog --since-installed
 - `run-metadata.json` is the canonical trace index. It records attempt settings, artifact presence, executor history, prompt hashes, Context7 snippet hashes, resolved skill ids and bundle metadata, the gate snapshot, `replayContext`, and the cumulative `historySnapshot` for that attempt.
 - `outcome.json` is the stored replay baseline. Replay compares recomputed gates and quality against it instead of trusting only inline metadata.
 - For `traceVersion: 2`, launched agents must have copied prompt/log/status/inbox/summary artifacts, and promoted-component waves must include the copied component matrix JSON.
+- `security.json` stores the derived per-wave security state that feeds integration summaries, gate snapshots, and replay.
 - `quality.json` is cumulative through the current attempt. It is intended for regression comparison, not only for one-shot pass/fail reporting.
 - `quality.json` also reports capability-assignment and dependency-resolution metrics in addition to the Phase 2/3 communication, fallback, and closure metrics.
 - Replay support is internal. The source tree contains helpers to load, validate, and replay trace bundles against the same gate logic the launcher uses, but there is no public replay CLI yet.
@@ -195,7 +219,7 @@ pnpm exec wave changelog --since-installed
 
 ## Authoring Rules
 
-- Every wave must include the configured evaluator agent.
+- Every wave must include the configured cont-QA agent.
 - Under the starter config, every wave must also include the configured integration steward and documentation steward.
 - From the configured thresholds onward, declare `## Component promotions` and keep them aligned with the component cutover matrix.
 - From the configured thresholds onward, every non-A0/A8/A9 agent must declare `### Components` and emit `[wave-component]` markers for those components.
@@ -203,12 +227,19 @@ pnpm exec wave changelog --since-installed
 - `### Deliverables` is optional and lets a wave declare exact repo-relative file outputs that must exist, and that stay within the agent's declared file ownership, before an implementation agent can satisfy its exit contract.
 - `### Skills` is optional and adds explicit skill ids from `skills/` on top of the lane, role, runtime, and deploy-kind defaults.
 - `### Executor` can declare `profile`, `fallbacks`, `tags`, and runtime budgets in addition to vendor-specific overrides.
+- `### Proof artifacts` is optional for repo-only waves and recommended for `pilot-live` and above; use it to declare machine-visible local evidence required for closure.
 - `## Deploy environments` lets the wave declare named deployment targets. The default deploy environment kind is also used for deploy-kind skill attachment.
 - Lane runtime policy can assign a default executor by role even when the wave omits `### Executor`.
 - Use `### Role prompts` for standing-role imports from `docs/agents/*.md`.
+- Optional security review is declared by importing `docs/agents/wave-security-role.md` on a report-owning reviewer agent. The starter planner uses a report path under `.tmp/<lane>-wave-launcher/security/` and the `security-review` executor profile.
+- A security reviewer must own at least one security report path. Any owned `.md` or `.txt` path containing `security` is accepted by the validator.
+- Security reviewers are report-only by default. They should route fixes to the owning implementation agent instead of taking over product-code ownership.
+- Security closure requires one final structured marker: `[wave-security] state=<clear|concerns|blocked> findings=<n> approvals=<n> detail=<short-note>`.
 - Optional standing roles available in this repo include `docs/agents/wave-infra-role.md` for infra proof and `docs/agents/wave-deploy-verifier-role.md` for rollout verification.
 - Keep file ownership explicit inside each `### Prompt`.
 - From the configured thresholds onward, declare `## Context7 defaults`, per-agent `### Context7`, and per-agent `### Exit contract`.
+- For benchmark-family guidance and delegated-versus-pinned eval examples, see [docs/evals/README.md](../evals/README.md).
+- For proof-first live-wave patterns, sticky retry guidance, and `### Proof artifacts` examples, see [docs/reference/live-proof-waves.md](../reference/live-proof-waves.md).
 - Agents should use `wave coord post` for durable blockers, handoffs, evidence, and requests instead of relying on ad hoc board edits.
 - Keep shared plan docs and the component cutover matrix owned by the configured documentation steward once that rule becomes active.
 - Use the runtime reference pages for the full executor surface instead of relying on this runbook to enumerate every key:
@@ -225,6 +256,7 @@ pnpm exec wave changelog --since-installed
 - `--executor local` exists only for smoke-testing prompt and closure behavior.
 - `--codex-sandbox danger-full-access` is the default because it avoids host bubblewrap assumptions.
 - Resolution order is: per-agent explicit executor id, executor profile id, lane role default, CLI `--executor`, then `executors.default`.
+- The starter config includes a `security-review` profile for the optional security reviewer. It is intended for read-heavy closure passes and pairs with `docs/agents/wave-security-role.md`.
 - Skills resolve only after that executor choice is known. Runtime-specific skill overlays are regenerated whenever retry-time fallback changes the selected executor.
 - Runtime mix targets are enforced before launch and again before any retry-time fallback reassignment.
 - Fallbacks are declared in profiles or lane policy, can be applied automatically on retry when the next executor is available and still satisfies mix targets, and are recorded in the ledger, integration summary, and traces when used.
@@ -276,4 +308,11 @@ pnpm exec wave feedback respond --id <request-id> --response "..."
 
 ## Closure Sweep
 
-If implementation agents ran, the launcher does not stop at `exit 0`. It checks implementation exit contracts, promoted component proof, helper assignments, required dependencies, and the integration recommendation first. Documentation and evaluator closure only run after integration is explicitly ready for doc closure; if integration reports `needs-more-work`, or if helper assignments or required dependency tickets remain open, the wave stops there and retries only the implicated owners plus the integration steward.
+If implementation agents ran, the launcher does not stop at `exit 0`. It checks implementation exit contracts, promoted component proof, helper assignments, required dependencies, and the integration recommendation first. When present, `cont-EVAL` must satisfy its declared eval targets before integration can close. Optional security review then runs before integration so the reviewer can publish findings and approval-sensitive actions while the wave is still active. In the default planner shape `E0` is report-only; if a wave explicitly assigns `E0` non-report files, the launcher also applies the normal implementation proof gates to that role. Security reviewers stay report-only by default. Documentation and cont-QA closure only run after integration is explicitly ready for doc closure; if `cont-EVAL`, security review, or integration reports more work, or if helper assignments or required dependency tickets remain open, the wave stops there and retries only the implicated owners plus the relevant closure steward.
+
+Live closure is fail-closed:
+
+- `cont-EVAL` PASS requires a report artifact plus a structured `[wave-eval]` marker whose `target_ids` exactly matches the wave contract and whose `benchmark_ids` stays within the declared benchmark catalog surface.
+- Security review requires a report artifact plus a structured `[wave-security]` marker. `state=blocked` stops the wave before integration, while `state=concerns` is preserved in summaries and traces without automatically failing closure.
+- `cont-QA` PASS requires both the final verdict and the final `[wave-gate]` marker.
+- Legacy evaluator-era or underspecified closure artifacts are still readable in replay and trace analysis, but they no longer satisfy live completion.

package/docs/plans/waves/wave-0.md

@@ -12,11 +12,11 @@
 - bundle: node-typescript
 - query: "Node.js and TypeScript basics for orchestrator maintenance"
 
-## Agent A0: Running Evaluator
+## Agent A0: cont-QA
 
 ### Role prompts
 
-- docs/agents/wave-evaluator-role.md
+- docs/agents/wave-cont-qa-role.md
 
 ### Executor
 
@@ -42,7 +42,7 @@ Required context before coding:
 - Read docs/plans/master-plan.md, docs/plans/current-state.md, and docs/plans/migration.md.
 
 File ownership (only touch these paths):
-- docs/plans/waves/reviews/wave-0-evaluator.md
+- docs/plans/waves/reviews/wave-0-cont-qa.md
 ```
 
 ## Agent A8: Integration Steward
@@ -70,7 +70,7 @@ File ownership (only touch these paths):
 ### Prompt
 
 ```text
-Synthesize the wave before documentation and evaluator closure.
+Synthesize the wave before documentation and cont-QA closure.
 
 Required context before coding:
 - Read docs/reference/repository-guidance.md.

package/docs/reference/live-proof-waves.md

@@ -0,0 +1,177 @@
+---
+title: "Live Proof Waves"
+summary: "How to author proof-first `pilot-live` and higher-maturity waves with explicit proof artifacts, sticky executors, and operator-visible closure evidence."
+---
+
+# Live Proof Waves
+
+`pilot-live`, `fleet-ready`, `cutover-ready`, and `deprecation-ready` waves are not normal repo-only implementation waves.
+
+For these waves:
+
+- operator-run commands are part of closure
+- local proof artifacts are part of closure
+- stale success is dangerous
+- sticky executors are safer than loose retry fallback
+- targeted reruns after new proof arrives are normal
+
+## Core Rule
+
+Repo-landed waves can stay repo-centric.
+
+`pilot-live` and above should be proof-centric.
+
+That means the wave should declare:
+
+- the exact proof owner
+- the exact operator command sequence
+- the exact artifact bundle written locally
+- the exact proof surfaces that closure should trust
+
+For a full authored example wave that uses this pattern, see [docs/reference/sample-waves.md](./sample-waves.md) and the linked proof-first live-wave sample.
+
+## Recommended Authoring Pattern
+
+For live-proof owners:
+
+- declare `### Deliverables` for the review/report surface
+- declare `### Proof artifacts` for machine-visible local evidence
+- keep the executor sticky unless fallback is explicitly required
+- prefer wall-clock budgets over tiny hard turn caps
+
+Example:
+
+````md
+## Agent A6: Learning Plane Live Validation
+
+### Executor
+
+- id: codex
+- retry-policy: sticky
+- budget.minutes: 30
+
+### Exit contract
+
+- completion: live
+- durability: durable
+- proof: live
+- doc-impact: owned
+
+### Deliverables
+
+- docs/plans/waves/reviews/wave-8-live-proof.md
+
+### Proof artifacts
+
+- path: .tmp/wave-8-learning-proof/learning-plane-before-restart.json | kind: live-status | required-for: pilot-live
+- path: .tmp/wave-8-learning-proof/learning-plane-after-restart.json | kind: restart-check | required-for: pilot-live
+- path: .tmp/wave-8-learning-proof/learning-vector-manifest.json | kind: manifest | required-for: pilot-live
+
+### Prompt
+```text
+Operator command sequence:
+- leapctl learning status --json > .tmp/wave-8-learning-proof/learning-plane-before-restart.json
+- leapctl learning restart ...
+- leapctl learning status --json > .tmp/wave-8-learning-proof/learning-plane-after-restart.json
+
+Closure only counts when the declared proof artifacts exist locally and match the claimed live state.
+
+File ownership (only touch these paths):
+- .tmp/wave-8-learning-proof/
+- docs/plans/waves/reviews/wave-8-live-proof.md
+```
+````
+
+## `### Proof artifacts`
+
+Use `### Proof artifacts` for the local machine-visible evidence that must exist before closure can trust a live claim.
+
+Supported shape:
+
+```md
+### Proof artifacts
+
+- path: .tmp/example/live-status.json | kind: live-status | required-for: pilot-live
+- path: .tmp/example/after-restart.json | kind: restart-check | required-for: pilot-live
+```
+
+Guidance:
+
+- keep artifact paths repo-relative
+- keep artifact paths inside the agent's owned paths
+- use one file per important proof surface
+- prefer canonical JSON or markdown artifacts over ad hoc screenshots or ephemeral terminal output
+
+## Retry And Executor Guidance
+
+For proof-bearing owners, default to sticky retry:
+
+```md
+### Executor
+
+- id: codex
+- retry-policy: sticky
+- budget.minutes: 45
+```
+
+Only enable cross-executor retry when there is a deliberate reason to do so.
+
+If you do allow fallback, declare it explicitly:
+
+```md
+### Executor
+
+- id: codex
+- retry-policy: fallback-allowed
+- fallbacks: claude
+```
+
+## What Closure Should Trust
+
+Closure roles should trust:
+
+- declared proof artifacts that exist locally
+- structured markers
+- integration summaries grounded in current artifacts
+
+Closure roles should not trust:
+
+- implied host state
+- stale cached snapshots
+- repo-local inference when the wave claims live proof
+- old `status=0` results that no longer match the current proof surface
+
+## Targeted Reruns
+
+When new proof artifacts arrive after an earlier failed attempt, the right response is usually a targeted rerun, not a full implementation replay.
+
+Typical pattern:
+
+1. operator captures the missing proof bundle locally
+2. the proof owner reruns on the same executor
+3. any stale synthesis or integration owner reruns if needed
+4. already-valid implementation slices stay reused
+
+## Suggested Eval Targets For Live-Proof Waves
+
+Good live-proof waves often pair the proof owner with `cont-EVAL` targets that check coordination quality as well as service behavior.
+
+Useful examples:
+
+```md
+## Eval targets
+
+- id: blackboard-fidelity | selection: delegated | benchmark-family: blackboard-fidelity | objective: Preserve machine-visible proof through summaries and integration | threshold: Critical live proof facts remain visible through closure
+- id: contradiction-recovery | selection: pinned | benchmarks: claim-conflict-detection,evidence-based-repair | objective: Surface and repair conflicting live claims before PASS | threshold: Material contradictions become explicit repair work before final closure
+```
+
+## Promotion-Level Guidance
+
+- `pilot-live`
+  Require explicit proof artifacts and prefer sticky executors for proof owners.
+- `fleet-ready`
+  Require the `pilot-live` discipline plus stronger infra/deploy readiness evidence.
+- `cutover-ready`
+  Require the `fleet-ready` discipline plus explicit rollback or cutover evidence.
+
+The important principle is that higher maturity should mean stronger machine-visible proof, not just more prose.

package/docs/reference/migration-0.2-to-0.5.md

@@ -8,6 +8,13 @@ summary: "How to migrate a repository from the earlier 0.2 wave baseline to the
 This guide explains how to migrate a repository from the earlier Wave
 Orchestration 0.2 baseline to the current post-roadmap Wave model.
 
+Current mainline note:
+
+- legacy `evaluator` terminology has been retired in favor of `cont-QA`
+- waves can now add optional `cont-EVAL` plus `## Eval targets` for iterative benchmark or output tuning
+- live closure is stricter than replay compatibility: current waves must emit structured cont-QA and cont-EVAL artifacts even though replay can still read older evaluator-era traces
+- the benchmark catalog lives in `docs/evals/benchmark-catalog.json`
+
 It uses two concrete references:
 
 - the 0.2-style baseline in the sibling `~/slowfast.ai` repo
@@ -35,8 +42,8 @@ The migration is intentionally evolutionary:
 - keep wave markdown as the authored plan surface
 - keep lanes
 - keep multi-role agents
-- keep A0 evaluator and A9 documentation stewardship
-- add stronger runtime planning, typed coordination, A8 integration, and
+- keep A0 cont-QA and A9 documentation stewardship
+- add stronger runtime planning, typed coordination, optional E0 cont-EVAL, A8 integration, and
   orchestrator-first clarification handling
 
 ## What Changes
@@ -45,7 +52,7 @@ The migration is intentionally evolutionary:
 | --- | --- | --- | --- |
 | Shared coordination | markdown message board plus status files | canonical coordination JSONL plus rendered board projection | Treat the markdown board as a view, not the source of truth |
 | Agent context | raw board snapshots in prompts | compiled shared summary plus per-agent inbox | Switch operator review and agent recovery to inbox artifacts |
-| Closure flow | implementation -> A9 -> A0 | implementation -> A8 integration -> A9 -> A0 | Add and require an integration steward |
+| Closure flow | implementation -> A9 -> A0 | implementation -> optional E0 cont-EVAL -> A8 integration -> A9 -> A0 | Add the integration steward and use cont-EVAL when the outcome needs iterative eval tuning |
 | Runtime selection | lane default plus limited per-agent overrides | runtime profiles, role defaults, mix targets, fallbacks, budgets | Expand `wave.config.json` and deliberate `### Executor` planning |
 | Clarification flow | file-backed human feedback queue | `clarification-request` -> orchestrator triage -> human escalation only if needed | Move humans to the end of the escalation ladder |
 | Derived state | status summaries and dashboards | ledger, docs queue, integration summary, traces, triage logs | Update operator workflow and acceptance checks |
@@ -62,7 +69,7 @@ do otherwise:
 - Fallback executors are allowed on retry after unavailability, timeout, or
   failed attempt when policy permits.
 - Automatic fallback must stay within the declared runtime mix.
-- Documentation and evaluator closure must not run until the integration
+- Documentation and cont-QA closure must not run until the integration
   steward reports `ready-for-doc-closure`.
 
 These defaults match the intended 0.5 operating model and keep the runtime
@@ -119,7 +126,7 @@ The migration assumes you preserve existing plans and waves. Do not wipe
 The most obvious config difference between the `slowfast.ai` baseline and the
 0.5 target is that 0.2 only models:
 
-- A0 evaluator
+- A0 cont-QA
 - A9 documentation steward
 - global executor defaults
 - validation thresholds
@@ -140,9 +147,9 @@ look like:
 ```json
 {
   "roles": {
-    "evaluatorAgentId": "A0",
+    "contQaAgentId": "A0",
     "documentationAgentId": "A9",
-    "evaluatorRolePromptPath": "docs/agents/wave-evaluator-role.md",
+    "contQaRolePromptPath": "docs/agents/wave-cont-qa-role.md",
     "documentationRolePromptPath": "docs/agents/wave-documentation-role.md"
   },
   "executors": {
@@ -169,10 +176,10 @@ adds the missing surfaces:
 ```json
 {
   "roles": {
-    "evaluatorAgentId": "A0",
+    "contQaAgentId": "A0",
     "integrationAgentId": "A8",
     "documentationAgentId": "A9",
-    "evaluatorRolePromptPath": "docs/agents/wave-evaluator-role.md",
+    "contQaRolePromptPath": "docs/agents/wave-cont-qa-role.md",
     "integrationRolePromptPath": "docs/agents/wave-integration-role.md",
     "documentationRolePromptPath": "docs/agents/wave-documentation-role.md"
   },
@@ -199,7 +206,7 @@ adds the missing surfaces:
           "implementation": "codex",
           "integration": "claude",
           "documentation": "claude",
-          "evaluator": "claude",
+          "cont-qa": "claude",
           "research": "opencode",
           "infra": "opencode",
           "deploy": "opencode"
@@ -227,7 +234,7 @@ adds the missing surfaces:
 Use four profiles first:
 
 - `implement-fast`: default implementation work
-- `deep-review`: integration, evaluator, and review-heavy work
+- `deep-review`: integration, cont-QA, and review-heavy work
 - `docs-pass`: documentation steward work
 - `ops-triage`: research, infra, and deployment triage work
 
@@ -253,16 +260,16 @@ What A8 does not own:
 
 - feature implementation
 - documentation closure
-- evaluator verdict
+- cont-QA verdict
 
-If your 0.2 repo used evaluator prose to absorb integration work implicitly,
+If your 0.2 repo used cont-QA prose to absorb integration work implicitly,
 move that responsibility out of A0 and into A8.
 
 ## Step 4: Migrate Wave Files
 
 The baseline `slowfast.ai` waves already have several good habits:
 
-- explicit A0 evaluator
+- explicit A0 cont-QA
 - explicit A9 documentation steward
 - Context7 declarations
 - component promotions
@@ -321,7 +328,7 @@ A minimal 0.5 upgrade looks like this:
 
 ### Prompt
 ```text
-Synthesize cross-agent state before documentation and evaluator closure.
+Synthesize cross-agent state before documentation and cont-QA closure.
 
 File ownership (only touch these paths):
 - .tmp/<lane>-wave-launcher/integration/wave-<n>.md
@@ -339,7 +346,7 @@ sections instead of relying on lane defaults:
 - fallbacks: claude, opencode
 ````
 
-For documentation or evaluator roles:
+For documentation or cont-QA roles:
 
 ````md
 ### Executor
@@ -358,7 +365,7 @@ Recommended first mapping:
 - implementation and test-fix roles: `codex`
 - integration steward: `claude`
 - documentation steward: `claude`
-- evaluator: `claude`
+- cont-QA: `claude`
 - infra or deploy roles: `opencode` or `codex`, chosen deliberately
 - research helpers: `opencode`
 
@@ -522,7 +529,7 @@ The 0.5 target adds more explicit acceptance state:
 - no unresolved high-priority blocker
 - runtime plan is within policy
 - documentation closure is explicit
-- evaluator verdict is explicit
+- cont-QA verdict is explicit
 - the ledger says the wave is actually complete
 - traces capture the final state for replay
 
@@ -537,7 +544,7 @@ Use this acceptance checklist after the migration:
 7. No resolved executor count exceeds lane mix targets.
 8. Clarification triage works without immediately creating human tickets for
    obvious ownership questions.
-9. Documentation and evaluator closure run only after the integration steward
+9. Documentation and cont-QA closure run only after the integration steward
    is ready.
 10. A live attempt writes a trace bundle with coordination, inbox, ledger,
     integration, structured signals, `run-metadata.json`, and cumulative

package/docs/reference/npmjs-trusted-publishing.md

@@ -2,7 +2,7 @@
 
 This repo now includes a dedicated npmjs publish workflow at [publish-npm.yml](../../.github/workflows/publish-npm.yml).
 
-It currently publishes through a repository Actions secret named `NPM_TOKEN`.
+The current `0.6.0` release procedure publishes through a repository Actions secret named `NPM_TOKEN`.
 
 ## What This Repo Already Does
 
@@ -10,6 +10,7 @@ It currently publishes through a repository Actions secret named `NPM_TOKEN`.
 - `publish-npm.yml` publishes tagged releases to `https://registry.npmjs.org`.
 - `publish-package.yml` still publishes to GitHub Packages explicitly, so both registries can coexist.
 - `publish-npm.yml` expects `NPM_TOKEN` in GitHub Actions secrets.
+- The public install path is already npmjs; GitHub Packages remains the authenticated fallback path.
 
 ## One-Time npm Setup
 
@@ -41,11 +42,11 @@ After a successful npm publish:
 
 If this repo later needs private npm dependencies during CI, consider a separate read-only install token rather than reusing the publish token.
 
-## First Release Checklist
+## Release Checklist
 
 1. Confirm [publish-npm.yml](../../.github/workflows/publish-npm.yml) is on the default branch.
 2. Confirm `NPM_TOKEN` exists in the GitHub repo secrets.
 3. Confirm the package version has been bumped and committed.
-4. Push the release tag, for example `v0.4.1`.
-5. Verify the GitHub Actions run publishes successfully to npmjs.
-6. After the publish is visible on npmjs, update README install guidance if npmjs should become the primary documented install path.
+4. Push the release commit and release tag, for example `v0.6.0`.
+5. Verify both `publish-npm.yml` and `publish-package.yml` start from the tag push.
+6. Verify the npmjs publish completes successfully for the tagged source.

package/docs/reference/runtime-config/README.md

@@ -50,6 +50,8 @@ Skill settings resolve after executor selection, because runtime and deploy-kind
 8. `lanes.<lane>.skills.byDeployKind[defaultDeployEnvironmentKind]`
 9. agent `### Skills`
 
+Then Wave filters configured skills through each bundle's activation metadata. Explicit per-agent `### Skills` still force attachment even when activation metadata would not auto-match.
+
 When retry-time fallback changes the runtime, Wave recomputes the effective skill set and rewrites the executor overlay before relaunch.
 
 ## Common Fields
@@ -82,14 +84,22 @@ Wave writes runtime artifacts here:
 Common files:
 
 - `launch-preview.json`: resolved invocation lines, env vars, and retry mode
-- `skills.resolved.md`: canonical merged skill payload for the selected agent and runtime
-- `skills.metadata.json`: resolved skill ids, bundle metadata, hashes, and generated artifact paths
-- `<runtime>-skills.txt`: runtime-projected skill text used by the selected executor
+- `skills.resolved.md`: compact metadata-first skill catalog for the selected agent and runtime
+- `skills.expanded.md`: full canonical/debug skill payload with `SKILL.md` bodies and adapters
+- `skills.metadata.json`: resolved skill ids, activation metadata, permissions, hashes, and generated artifact paths
+- `<runtime>-skills.txt`: runtime-projected compact skill text used by the selected executor
 - `claude-system-prompt.txt`: generated Claude harness prompt overlay
 - `claude-settings.json`: generated Claude settings overlay when inline settings data is present
 - `opencode-agent-prompt.txt`: generated OpenCode harness prompt overlay
 - `opencode.json`: generated OpenCode runtime config overlay
 
+Runtime-specific delivery:
+
+- Codex uses the compact catalog in the compiled prompt and attaches bundle directories through `--add-dir`.
+- Claude appends the compact catalog to the generated system-prompt overlay.
+- OpenCode injects the compact catalog into `opencode.json` and attaches `skill.json`, `SKILL.md`, the selected adapter, and recursive `references/**` files through `--file`.
+- Local keeps skills prompt-only.
+
 `launch-preview.json` also records the resolved skill metadata so dry-run can verify the exact runtime plus skill combination before any live launch.
 
 ## Recommended Validation Path