@chllming/wave-orchestration 0.5.3 → 0.6.0

package/docs/guides/author-and-run-waves.md

@@ -0,0 +1,135 @@
+# Authoring And Running Waves
+
+This is the shortest path from "I need a new wave" to "the launcher is ready to run it."
+
+Use this guide first. The narrower planner and terminal-surface pages remain useful when you need extra detail, but most operators should not need to assemble the workflow from multiple docs.
+
+## 1. Set Repo Defaults Once
+
+Start by teaching the planner how this repo usually works:
+
+```bash
+pnpm exec wave project setup
+pnpm exec wave project show --json
+```
+
+The saved project profile remembers:
+
+- default oversight mode
+- default terminal surface
+- default draft template
+- default lane
+- typed deploy environments
+
+That keeps later drafts consistent and removes repeated bootstrap questions.
+
+## 2. Draft The Wave
+
+Generate a structured draft:
+
+```bash
+pnpm exec wave draft --wave 1 --template implementation
+```
+
+The planner writes two artifacts:
+
+- `docs/plans/waves/specs/wave-<n>.json`
+- `docs/plans/waves/wave-<n>.md`
+
+The JSON spec is the planner-owned structured artifact. The markdown wave is still the launcher-owned execution surface.
+
+When you review the generated wave, tighten the parts the planner cannot fully infer:
+
+- file ownership
+- validation commands
+- proof artifacts
+- `cont-EVAL` targets when needed
+- security review expectations when needed
+- explicit `### Skills` only where defaults are not enough
+
+If you want examples of denser hand-authored waves, read [docs/reference/sample-waves.md](../reference/sample-waves.md).
+
+## 3. Choose The Execution Posture
+
+Every wave should be authored with an explicit operating posture in mind:
+
+- `oversight`
+  Best default. Use when a human may need to inspect progress, answer clarifications, or approve risky steps.
+- `dark-factory`
+  Use only when environments, validation, rollback, and closure evidence are already explicit enough for routine execution without human intervention.
+
+Human feedback is an escalation path, not the operating mode itself. The launcher still tries to resolve clarification inside the orchestration loop before creating a human ticket.
+
+## 4. Choose The Operator Surface
+
+Live runs always execute in `tmux`. The terminal surface only decides how you attach:
+
+- `vscode`
+  VS Code gets temporary attach entries for the live tmux sessions.
+- `tmux`
+  Terminal-native operation with no VS Code integration.
+- `none`
+  Dry-run only.
+
+Recommended defaults:
+
+- local interactive work: `vscode`
+- remote shell or devbox: `tmux`
+- CI or validation-only work: `none` with `--dry-run`
+
+## 5. Dry-Run Before Live Execution
+
+Treat dry-run as the quality gate for the authored wave:
+
+```bash
+pnpm exec wave launch --lane main --start-wave 1 --end-wave 1 --dry-run --no-dashboard
+```
+
+Check that the dry-run artifacts reflect the wave you meant to author:
+
+- resolved executors and overlays look correct
+- ownership is narrow and explicit
+- skills and Context7 inputs are attached where expected
+- proof and closure requirements match the actual task
+- no ambiguous prompts or missing deliverables remain
+
+## 6. Launch Live
+
+When the dry-run artifacts look correct, launch the wave with the operator surface you actually want:
+
+```bash
+pnpm exec wave launch --lane main --start-wave 1 --end-wave 1 --terminal-surface vscode
+pnpm exec wave launch --lane main --start-wave 1 --end-wave 1 --terminal-surface tmux --keep-sessions
+```
+
+Useful flags:
+
+- `--no-dashboard`
+  Skip the dashboard session.
+- `--keep-sessions`
+  Preserve tmux sessions for inspection after the wave completes.
+- `--keep-terminals`
+  Preserve temporary VS Code terminal entries.
+
+## 7. Understand Closure
+
+A wave is not done when an implementation agent says it is done. Closure depends on the combined runtime surfaces:
+
+- implementation contracts pass
+- required deliverables exist
+- proof artifacts exist when the wave requires them
+- dependencies and helper assignments are resolved
+- `cont-EVAL` satisfies declared targets when present
+- security review publishes its report and final marker when present
+- integration, docs, and `cont-QA` all pass
+
+For the detailed execution model, read [docs/concepts/what-is-a-wave.md](../concepts/what-is-a-wave.md).
+
+## Supporting Detail
+
+Use these pages when you need deeper detail rather than the main workflow:
+
+- [docs/guides/planner.md](./planner.md)
+- [docs/guides/terminal-surfaces.md](./terminal-surfaces.md)
+- [docs/concepts/operating-modes.md](../concepts/operating-modes.md)
+- [docs/reference/runtime-config/README.md](../reference/runtime-config/README.md)

package/docs/guides/planner.md

@@ -0,0 +1,118 @@
+# Planner Guide
+
+The planner foundation is the first structured authoring layer on top of the existing wave runtime.
+
+If you want the full author-to-launch workflow, start with [author-and-run-waves.md](./author-and-run-waves.md). This page stays focused on planner-specific behavior.
+
+It reduces repeated setup questions, stores project defaults, and generates wave specs plus markdown that already fit the launcher.
+
+## What Ships Today
+
+- `wave project setup`
+- `wave project show`
+- `wave draft`
+- persistent project memory in `.wave/project-profile.json`
+- JSON specs in `docs/plans/waves/specs/wave-<n>.json`
+- rendered markdown waves in `docs/plans/waves/wave-<n>.md`
+- component matrix updates for promoted components
+
+## What The Planner Does Not Yet Ship
+
+- ad hoc transient runs
+- forward replanning of later waves
+- separate runtime enforcement for oversight vs dark-factory
+
+Those remain roadmap work. The planner foundation is about better structured authoring, not a second execution engine.
+
+## Project Profile
+
+Run:
+
+```bash
+pnpm exec wave project setup
+pnpm exec wave project show --json
+```
+
+The saved profile remembers:
+
+- whether the repo is a new project
+- default oversight mode
+- default terminal surface for live runs (`vscode` or `tmux`; `none` remains dry-run only)
+- default draft template
+- default lane
+- typed deploy environments
+
+This lets later drafts inherit repo-specific defaults instead of asking the same bootstrap questions every time.
+
+## Drafting A Wave
+
+Run:
+
+```bash
+pnpm exec wave draft --wave 1 --template implementation
+```
+
+Supported templates today:
+
+- `implementation`
+- `qa`
+- `infra`
+- `release`
+
+The planner writes:
+
+- `docs/plans/waves/specs/wave-<n>.json`
+- `docs/plans/waves/wave-<n>.md`
+
+The JSON spec is the canonical planner artifact. The markdown wave remains the launcher-compatible execution surface.
+
+## What The Planner Asks For
+
+The draft flow asks for structured inputs such as:
+
+- wave title and commit message
+- sequencing notes and reference rules
+- oversight mode
+- deploy environments in scope
+- component promotions and target levels
+- worker count and worker roles
+- executor profiles
+- file ownership
+- Context7 defaults and per-agent bundles
+- validation commands
+- exit contracts
+
+That gives you a wave that is much closer to launch-ready than a blank markdown template.
+
+## Planner And Skills
+
+The planner does not auto-discover every possible skill bundle yet, but it supports explicit per-agent `### Skills` in the rendered output.
+
+The more important interaction is indirect:
+
+- project profile remembers deploy environments
+- planner-generated waves carry `## Deploy environments`
+- deploy-kind skill attachment uses the wave's default deploy environment kind
+
+So planner structure and skill resolution already reinforce each other.
+
+## Recommended Workflow
+
+1. Run `pnpm exec wave project setup` once for the repo.
+2. Use `pnpm exec wave draft --wave <n> --template <template>`.
+3. Review the generated JSON spec and markdown wave.
+4. Adjust repo-specific prompts, file ownership, skills, and validation commands.
+5. Run `pnpm exec wave launch --lane <lane> --start-wave <n> --end-wave <n> --dry-run --no-dashboard`.
+6. Only launch live once the dry-run artifacts look correct.
+
+If you want concrete authored examples after the planner baseline, see [docs/reference/sample-waves.md](../reference/sample-waves.md).
+
+## Best Practices
+
+- Treat the generated draft as a strong starting point, not untouchable output.
+- Tighten validation commands before launch.
+- Keep file ownership narrow and explicit.
+- Add explicit `### Skills` only when the lane, role, runtime, and deploy-kind defaults are not enough.
+- Use the component matrix as a planning contract, not just a reporting surface.
+- Prefer updating the project profile when the same answers recur across waves.
+- Use [docs/reference/sample-waves.md](../reference/sample-waves.md) when you want examples of denser human-authored waves that combine multiple modern surfaces such as `cont-EVAL`, delegated benchmark families, or proof-first live validation.

package/docs/guides/terminal-surfaces.md

@@ -0,0 +1,82 @@
+# Terminal Surfaces And Dashboards
+
+If you want the end-to-end drafting and live-run workflow, start with [author-and-run-waves.md](./author-and-run-waves.md). This page stays focused on terminal-surface details.
+
+Wave has separate concepts for execution substrate and operator surface.
+
+The important detail is:
+
+- live runs use `tmux` sessions
+- terminal surfaces control how operators attach to those sessions
+
+## The Three Terminal Surfaces
+
+- `vscode`
+  The launcher writes temporary entries to `.vscode/terminals.json` so VS Code can attach to the tmux sessions.
+- `tmux`
+  The launcher uses tmux only and never touches `.vscode/terminals.json`.
+- `none`
+  Dry-run only. No live terminal surface is allowed in this mode.
+
+## What `vscode` Really Means
+
+`vscode` is not a second process host. It is a convenience attachment surface.
+
+The actual live sessions still run in tmux. The VS Code terminal registry just exposes stable attach commands for those tmux sessions.
+
+Use `vscode` when:
+
+- your main operator flow is inside VS Code
+- you want one-click attach behavior for agent sessions and dashboards
+- touching `.vscode/terminals.json` is acceptable in the repo
+
+## What `tmux` Really Means
+
+`tmux` is the cleanest fully terminal-native operator surface.
+
+Use `tmux` when:
+
+- you are on a remote shell or devbox
+- you want zero VS Code coupling
+- you want a headless or low-friction terminal operator workflow
+- the repo should never be mutated with temporary VS Code terminal entries
+
+## Dashboard Behavior
+
+By default the launcher can start per-wave dashboard sessions in tmux.
+
+Important flags:
+
+- `--no-dashboard`
+  Disable the per-wave tmux dashboard session.
+- `--cleanup-sessions`
+  Kill lane tmux sessions after each wave. This is the default.
+- `--keep-sessions`
+  Preserve tmux sessions after the wave for inspection.
+- `--keep-terminals`
+  Keep temporary VS Code terminal entries instead of cleaning them up.
+
+## Best Practices
+
+- 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`.
+- 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.
+
+## Suggested Defaults
+
+- Local development:
+  `vscode`
+- Remote shell or devbox:
+  `tmux`
+- CI validation:
+  `none` with `--dry-run`
+
+## Example Commands
+
+```bash
+pnpm exec wave launch --lane main --start-wave 2 --end-wave 2 --terminal-surface vscode
+pnpm exec wave launch --lane main --start-wave 2 --end-wave 2 --terminal-surface tmux --keep-sessions
+pnpm exec wave launch --lane main --start-wave 2 --end-wave 2 --dry-run --no-dashboard --terminal-surface none
+```

package/docs/plans/component-cutover-matrix.json

@@ -49,7 +49,7 @@
       "title": "Closure sweep and role gates",
       "canonicalDocs": [
         "docs/plans/wave-orchestrator.md",
-        "docs/agents/wave-evaluator-role.md",
+        "docs/agents/wave-cont-qa-role.md",
         "docs/agents/wave-documentation-role.md"
       ],
       "currentLevel": "repo-landed",

package/docs/plans/component-cutover-matrix.md

@@ -20,7 +20,7 @@ The starter entries reflect the snapshot shipped in this repository. Replace the
 
 - `wave-parser-and-launcher`: parser, manifest, launcher, and dry-run execution flow
 - `executor-abstraction-and-prompt-transport`: executor selection, prompt overlays, and transport into `codex`, `claude`, `opencode`, or `local`
-- `closure-sweep-and-role-gates`: documentation steward, evaluator, and post-implementation closure logic
+- `closure-sweep-and-role-gates`: documentation steward, cont-QA, and post-implementation closure logic
 - `context7-scope-and-prefetch`: Context7 bundle resolution, prefetch, cache, and prompt injection
 - `state-artifacts-and-feedback`: status summaries, dashboards, logs, message boards, and human feedback queue
 - `starter-docs-and-adoption-guidance`: starter README, shared-plan docs, and adoption instructions

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

@@ -1,5 +1,7 @@
 # Context7 and Wave Orchestrator
 
+See also [concepts/context7-vs-skills.md](../concepts/context7-vs-skills.md) for how Context7 differs from the repo-owned skill system.
+
 Context7 is for external library truth. Repository docs and source are for repository truth.
 
 ## Rules

package/docs/plans/current-state.md

@@ -1,10 +1,28 @@
 # Current State
 
+- The starter workspace in this source repo reflects the `0.6.0` 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/`.
 - This source repo is itself kept as an adopted Wave workspace, so `node scripts/wave.mjs doctor --json` should pass from the repo root.
 - The default lane is `main`.
+- Planner foundation is now shipped:
+  - `.wave/project-profile.json` stores default oversight mode, terminal surface, draft template, lane, and deploy-environment memory
+  - `wave project setup|show` manage that profile
+  - `wave draft` writes planner JSON specs plus launcher-compatible markdown waves
+- Ad-hoc task runs are now first-class:
+  - `wave adhoc plan|run|list|show|promote` manage transient operator-driven work
+  - requests, generated specs, rendered markdown, and final results live under `.wave/adhoc/runs/<run-id>/`
+  - runtime state stays isolated under `.tmp/<lane>-wave-launcher/adhoc/<run-id>/`
+  - ad-hoc runs always keep integration, documentation, and cont-QA closure, while `cont-EVAL` and security review are synthesized only when the request needs them
+  - documentation closure still queues canonical shared-plan docs when a run reports a shared-plan delta, alongside the ad-hoc closure report
+  - `wave adhoc promote` copies the stored ad-hoc spec into numbered roadmap artifacts instead of re-deriving it from the current project profile
+  - repo-local path hints become owned paths; external references such as URLs are ignored
 - The harness supports `codex`, `claude`, `opencode`, and `local` executors.
+- Cross-runtime skills are now first-class:
+  - canonical bundles live under `skills/`
+  - lane config can attach skills by base, role, runtime, and deploy kind
+  - wave agents can add explicit `### Skills`
+  - runtime projections are generated for Codex, Claude, OpenCode, and local execution
 - The runtime now includes:
   - a canonical coordination JSONL log
   - a generated markdown board projection
@@ -12,14 +30,20 @@
   - a per-wave ledger
   - docs queues
   - explicit integration summaries with actionable claim, interface, proof, docs, and deploy-risk evidence
+  - versioned runtime artifact contracts for manifests, dashboards, relaunch plans, helper-assignment snapshots, dependency snapshots, and run-state
+  - append-only `run-state.json` history with per-wave current state, compatibility `completedWaves`, and causal completion or blocker evidence
   - 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
+  - persisted relaunch plans under `.tmp/<lane>-wave-launcher/status/` so targeted retry intent can survive a launcher restart
+  - 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
   - Claude settings overlay merging for inline settings and hooks
   - OpenCode merged config overlays plus multi-file attachments
+  - per-agent 429/rate-limit retries for Codex, Claude Code, and OpenCode via `--agent-rate-limit-*`
   - dry-run prompt and executor-preview materialization under `.tmp/<lane>-wave-launcher/dry-run/`
+  - operator-selectable terminal surfaces: `vscode`, `tmux`, or `none` for dry-run only
 - Full runtime configuration reference pages now ship under `docs/reference/runtime-config/`.
 - Lane runtime policy is active through `wave.config.json`:
   - role-based default executors
@@ -27,11 +51,15 @@
   - hard runtime mix targets
   - retry-time fallback order
   - generic runtime budgets
+  - sticky retry policy for proof-centric owners unless fallback is explicitly enabled
 - Capability routing is now first-class:
   - open capability-targeted requests become explicit helper assignments
   - helper assignments are written into coordination state, the ledger, summaries, and traces
   - helper assignments remain blocking until the linked follow-up resolves
-- Closure now runs in staged order: implementation and proof, then `A8` integration, then `A9` documentation, then `A0` evaluator.
+- Closure now runs in staged order: implementation and proof, then optional `E0` cont-EVAL, then optional security review, then `A8` integration, then `A9` documentation, then `A0` cont-QA.
+- `E0` is hybrid: planner-generated waves keep it report-only, while hand-authored waves may assign explicit tuning files and thereby make `E0` participate in implementation proof gating.
+- 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.
 - 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: