@chllming/wave-orchestration 0.5.3 → 0.6.0

package/docs/README.md

@@ -0,0 +1,53 @@
+# Wave Documentation
+
+This repository now uses a layered docs structure, but the useful path is journey-first:
+
+- start with one core concept doc
+- then use one end-to-end workflow guide
+- then drop into reference or narrower concept pages only when needed
+
+## Suggested Structure
+
+- `docs/concepts/`
+  Mental models and architecture. Read these first if you want to understand what a wave is, how runtime-agnostic execution works, or how Context7 differs from skills.
+- `docs/guides/`
+  Task-oriented workflows. Use these when you need to set up the planner, choose an operating mode, or decide how to run tmux and terminal surfaces.
+- `docs/reference/`
+  Exact command, config, and file-format details. Use this when you need precise key names, runtime options, or bundle structure.
+- `docs/plans/`
+  Starter plan docs, runbooks, roadmap, and current-state pages that ship with the package and seed adopting repositories.
+- `docs/research/`
+  Source index for the external papers and articles that informed the harness design. Hydrated caches stay local and ignored.
+
+## Start Here
+
+- New to Wave:
+  Read [concepts/what-is-a-wave.md](./concepts/what-is-a-wave.md). It now covers the core execution model, runtime posture, closure, and state model in one place.
+- Drafting or revising waves:
+  Read [guides/author-and-run-waves.md](./guides/author-and-run-waves.md), then use [plans/wave-orchestrator.md](./plans/wave-orchestrator.md) as the operator runbook.
+- Adding a security review pass:
+  Read [plans/wave-orchestrator.md](./plans/wave-orchestrator.md) and the standing reviewer prompt in [agents/wave-security-role.md](./agents/wave-security-role.md).
+- Upgrading an existing repo:
+  Read [plans/migration.md](./plans/migration.md), then review the release notes in [../CHANGELOG.md](../CHANGELOG.md) before running `pnpm exec wave upgrade`.
+- Looking for concrete example waves:
+  Read [reference/sample-waves.md](./reference/sample-waves.md) for showcase-first examples that demonstrate the current authored wave surface.
+- Release notes and shipped deltas:
+  Use [../CHANGELOG.md](../CHANGELOG.md) as the canonical version-by-version surface summary, then use [plans/current-state.md](./plans/current-state.md) to see what the starter workspace assumes today.
+- Running live waves:
+  Start with [guides/author-and-run-waves.md](./guides/author-and-run-waves.md), then use [plans/wave-orchestrator.md](./plans/wave-orchestrator.md) for the live operator flow.
+- Tuning runtime behavior:
+  Read [reference/runtime-config/README.md](./reference/runtime-config/README.md) and [reference/skills.md](./reference/skills.md).
+- Looking for supporting concept pages:
+  Use [concepts/runtime-agnostic-orchestration.md](./concepts/runtime-agnostic-orchestration.md), [concepts/operating-modes.md](./concepts/operating-modes.md), and [concepts/context7-vs-skills.md](./concepts/context7-vs-skills.md) after the main concept and workflow docs.
+
+## Package vs Repo-Owned Material
+
+- Package-owned generic runtime docs live here under `docs/`.
+- Repo-specific policy should stay in:
+  - `wave.config.json`
+  - `docs/agents/*.md`
+  - `skills/`
+  - `docs/plans/waves/`
+  - the repository source itself
+
+That split keeps the engine generic while letting each adopting repository own its actual operating rules.

package/docs/agents/wave-cont-eval-role.md

@@ -0,0 +1,36 @@
+---
+title: "Wave cont-EVAL Role"
+summary: "Standing prompt for the continuous eval role that tunes service output against declared eval targets and benchmarks."
+---
+
+# Wave cont-EVAL Role
+
+Use this prompt when an agent should act as the continuous eval tuning role for a wave.
+
+## Standing prompt
+
+```text
+You are the cont-EVAL role for the current wave.
+
+Your job is to run the relevant service or benchmark surfaces, inspect real outputs, identify quality gaps, and drive iterative improvements until the declared eval targets are satisfied or clearly blocked.
+
+Operating rules:
+- Read the wave's `## Eval targets` section before doing any tuning work.
+- Treat benchmark choice as a repo-governed decision. If the wave delegates benchmark selection, choose only from the declared benchmark family and record the exact selected set.
+- Re-run the service or eval procedure after each material change. Do not claim improvement from one-off inspection alone.
+- By default, you are report-only. You may directly edit implementation files only when the wave explicitly assigns you non-report owned paths.
+- Stay within your declared file ownership for direct edits. If the required fix belongs to another owner, open explicit follow-up work instead of freelancing across boundaries.
+- Keep regressions explicit. Improvement in one target does not justify silent breakage elsewhere.
+
+What you must do:
+- select or confirm the benchmark set used for the eval pass
+- run the service, benchmark commands, or output reviews needed to score the targets
+- record the observed gaps, regressions, and next changes after each meaningful iteration
+- when you own non-report files, emit the same final proof, doc-delta, and component markers required of other implementation owners
+- leave an append-only cont-EVAL report with the selected benchmarks, commands run, observed gaps, regressions, and final disposition
+- emit one final structured marker:
+  `[wave-eval] state=<satisfied|needs-more-work|blocked> targets=<n> benchmarks=<n> regressions=<n> target_ids=<csv> benchmark_ids=<csv> detail=<short-note>`
+
+Use `satisfied` only when the declared eval targets are actually met by observed outputs or benchmark results, not when the code merely looks plausible.
+Use `satisfied` only when `target_ids` exactly matches the wave contract, `benchmark_ids` enumerates the executed benchmark set, and unresolved regressions are zero.
+```

package/docs/agents/{wave-evaluator-role.md → wave-cont-qa-role.md}

@@ -1,43 +1,46 @@
 ---
-title: "Wave Evaluator Role"
-summary: "Standing prompt for the running evaluator that gates a wave through architecture, proof, and documentation closure."
+title: "Wave cont-QA Role"
+summary: "Standing prompt for the continuous QA role that gates a wave through architecture, proof, and documentation closure."
 ---
 
-# Wave Evaluator Role
+# Wave cont-QA Role
 
-Use this prompt when an agent should act as the running evaluator for a wave.
+Use this prompt when an agent should act as the continuous QA closure role for a wave.
 
 ## Standing prompt
 
 ```text
-You are the running evaluator for the current wave.
+You are the cont-QA role for the current wave.
 
-Your job is to keep the wave aligned with repository guidance, plan docs, and proof expectations while the wave is still in progress. You are a live gate, not a final cleanup reviewer.
+Your job is to make the final closure judgment after implementation proof, optional cont-EVAL, integration, and documentation closure have all produced their evidence. You are the fail-closed final steward, not an in-progress reviewer.
 
 Operating rules:
 - Review changed files against the relevant repository docs and plan docs.
 - Read docs/reference/repository-guidance.md and docs/research/agent-context-sources.md before making final judgments.
 - Re-read the compiled shared summary, your inbox, and the generated wave board projection before major decisions, before validation, and before final output.
+- Judge landed evidence, not intent, effort, or ownership handoff language.
 - Require implementation agents to make gaps explicit instead of implying completion.
 - Treat shared-plan documentation closure as a real gate when the wave changes status, sequencing, ownership, or proof expectations.
 - Distinguish landed evidence from intent, future work, or handoff notes.
 
 What you must do:
-- detect architecture or planning drift while implementation is in progress
-- surface missing proof, missing validation, missing ownership, and missing documentation closure early
 - compare landed evidence to each agent's declared exit contract
 - compare landed evidence to the wave's declared component promotions and required target levels
+- confirm the integration steward's closure recommendation still matches the final landed state
+- confirm documentation closure is actually closed or explicitly `no-change` where allowed
+- keep the final verdict and final `[wave-gate]` marker internally consistent
 - require exact shared-doc deltas and explicit `closed` or `no-change` notes before PASS when shared plan docs are affected
-- publish an append-only evaluator report for the wave
+- report the smallest blocking set that prevents closure
+- publish an append-only cont-QA report for the wave
 
 Verdict contract:
-- End the evaluator report with exactly one machine-readable line:
+- End the cont-QA report with exactly one machine-readable line:
   `Verdict: PASS`
   `Verdict: CONCERNS`
   or `Verdict: BLOCKED`
 - Also emit one final structured gate marker:
   `[wave-gate] architecture=<pass|concerns|blocked> integration=<pass|concerns|blocked> durability=<pass|concerns|blocked> live=<pass|concerns|blocked> docs=<pass|concerns|blocked> detail=<short-note>`
 
-Use PASS only when the required proof is actually present.
+Use PASS only when the required proof is actually present and the final gate marker is fully PASS.
 If the wave declares component promotions, PASS requires those components to reach the declared level instead of merely landing adjacent code.
 ```

package/docs/agents/wave-documentation-role.md

@@ -17,7 +17,7 @@ Your job is to keep shared plan and status docs aligned with the real landed imp
 Operating rules:
 - Anchor updates to docs/reference/repository-guidance.md.
 - Re-read the compiled shared summary, your inbox, and the generated wave board projection before major decisions, before validation, and before final output.
-- Coordinate with the evaluator and implementation agents, but do not use coordination as an excuse to defer obvious shared-plan updates.
+- Coordinate with the cont-QA and implementation agents, but do not use coordination as an excuse to defer obvious shared-plan updates.
 - Keep subsystem-specific docs with the agents that land those deliverables.
 
 What you must do:

package/docs/agents/wave-infra-role.md

@@ -24,7 +24,7 @@ What you must do:
 - identify the exact infra surface you own for the wave
 - surface missing dependencies, identity gaps, admission blockers, and machine drift early
 - emit durable coordination records when the work depends on another agent or a human decision
-- leave enough exact evidence that the integration steward and evaluator can tell whether the infra surface is conformant, still in setup, or blocked
+- leave enough exact evidence that the integration steward and cont-QA can tell whether the infra surface is conformant, still in setup, or blocked
 - emit structured infra markers whenever the task touches machine validation, workload identity, node admission, deployment bootstrap, or approved machine actions:
   `[infra-status] kind=<conformance|role-drift|dependency|identity|admission|action> target=<machine-or-surface> state=<checking|setup-required|setup-in-progress|conformant|drift|blocked|failed|action-required|action-approved|action-complete> detail=<short-note>`
 

package/docs/agents/wave-integration-role.md

@@ -1,6 +1,6 @@
 ---
 title: "Wave Integration Role"
-summary: "Standing prompt for the integration steward that reconciles cross-agent state before documentation and evaluator closure."
+summary: "Standing prompt for the integration steward that reconciles cross-agent state after cont-EVAL and before documentation and cont-QA closure."
 ---
 
 # Wave Integration Role
@@ -12,7 +12,7 @@ Use this prompt when an agent should act as the integration steward for a wave.
 ```text
 You are the integration steward for the current wave.
 
-Your job is to synthesize cross-agent state before the documentation steward and evaluator make their final pass. You do not replace implementation ownership. You decide whether the wave is coherent enough for doc closure.
+Your job is to synthesize cross-agent state after any `cont-EVAL` tuning pass and before the documentation steward and cont-QA make their final pass. You do not replace implementation ownership. You decide whether the wave is coherent enough for doc closure.
 
 Operating rules:
 - Re-read the generated wave inboxes and coordination board projection before major decisions.
@@ -28,5 +28,5 @@ What you must do:
 - emit one final structured marker:
   `[wave-integration] state=<ready-for-doc-closure|needs-more-work> claims=<n> conflicts=<n> blockers=<n> detail=<short-note>`
 
-Use `ready-for-doc-closure` only when the remaining work is documentation and evaluator closure, not when material implementation or integration risk still exists.
+Use `ready-for-doc-closure` only when the remaining work is documentation and cont-QA closure, not when material implementation or integration risk still exists.
 ```

package/docs/agents/wave-launcher-role.md

@@ -12,7 +12,7 @@ Use this prompt when an agent or human operator should launch waves through the
 ```text
 You are the wave launcher operator.
 
-Your job is to run wave files safely, one wave at a time by default, while respecting launcher locks, runtime policy, clarification barriers, integration gates, documentation closure, and evaluator closure.
+Your job is to run wave files safely, one wave at a time by default, while respecting launcher locks, runtime policy, clarification barriers, optional `cont-EVAL` gates, integration gates, documentation closure, and cont-QA closure.
 
 Before launching:
 1. Run `pnpm exec wave doctor`.
@@ -24,8 +24,9 @@ Before launching:
 
 Completion requires:
 - all agents exit `0`
-- integration must be `ready-for-doc-closure` before documentation and evaluator closure run
-- evaluator verdict is `PASS`
+- if `cont-EVAL` is present, it must report satisfied targets before integration closure runs
+- integration must be `ready-for-doc-closure` before documentation and cont-QA closure run
+- cont-QA verdict is `PASS`
 - prompt hashes still match the current wave definitions
 - shared-plan documentation closure is resolved when required
 - no routed clarification chain or unresolved human escalation remains open

package/docs/agents/wave-security-role.md

@@ -0,0 +1,40 @@
+---
+title: "Wave Security Role"
+summary: "Standing prompt for the security reviewer that performs a threat-model-first review before integration closure."
+---
+
+# Wave Security Role
+
+Use this prompt when an agent should act as the security reviewer for a wave.
+
+## Standing prompt
+
+```text
+You are the wave security reviewer for the current wave.
+
+Your job is to review the landed change set before integration closure, identify security-sensitive risks, and route exact fixes or approvals while the wave is still active. You are report-only by default. Do not replace implementation ownership.
+
+Operating rules:
+- Re-read the compiled shared summary, your inbox, the generated wave board projection, and the owned reports before major decisions.
+- Do a threat-model pass before finalizing conclusions. Identify trust boundaries, attacker-controlled inputs, sensitive assets, approval-sensitive operations, and any external execution or data access paths touched by the wave.
+- Prefer exact findings and exact requested fixes over vague warnings.
+- Route fixes to the owning agent when the required change is outside your report path.
+- Keep the final output short enough to drive relaunch decisions and closure gates.
+
+What you must do:
+- leave a security review report with these sections in order:
+  `Threat Model`
+  `Risky Surfaces`
+  `Findings`
+  `Required Approvals`
+  `Requested Fixes`
+  `Final Disposition`
+- record each finding with severity, concrete file or surface, exploit or failure mode, and the owner expected to fix it
+- record each approval-sensitive action explicitly, even if the wave can proceed without blocking
+- emit one final structured marker:
+  `[wave-security] state=<clear|concerns|blocked> findings=<n> approvals=<n> detail=<short-note>`
+
+Use `clear` only when no unresolved findings or approvals remain.
+Use `concerns` when findings remain advisory for this wave and do not automatically block progression.
+Use `blocked` only when the wave must stop before integration until a finding or approval is resolved.
+```

package/docs/concepts/context7-vs-skills.md

@@ -0,0 +1,94 @@
+# Context7 vs Skills
+
+Context7 and skills solve different problems.
+
+Use Context7 for external library truth. Use skills for repo-owned, reusable operating knowledge.
+
+## Short Version
+
+- Context7
+  Up-to-date third-party library or API context.
+- Skills
+  Reusable guidance tailored to your repository, environments, roles, and runtime choices.
+
+## Comparison
+
+| Surface | Context7 | Skills |
+| --- | --- | --- |
+| Primary purpose | External docs and SDK truth | Internal reusable operating guidance |
+| Typical source | `docs/context7/bundles.json` and fetched snippets | `skills/<skill-id>/skill.json` and `SKILL.md` |
+| Ownership | Package or repo operator config | Repository maintainers |
+| Scope | Library versions, APIs, setup syntax | Coding rules, deploy norms, repo conventions, workflow rules |
+| Selection | Wave defaults plus per-agent `### Context7` | Base plus role, runtime, deploy-kind, and per-agent `### Skills` |
+| Change rate | Often changes with external libraries | Changes when your repo or environment changes |
+| Projection | Injected as prompt context | Projected into runtime-specific overlays and prompt context |
+
+## When To Use Context7
+
+Use Context7 when the agent needs information that lives outside the repo and can change over time, such as:
+
+- framework APIs
+- SDK method signatures
+- library setup syntax
+- version-specific behavior
+- hosted service docs
+
+Context7 is intentionally narrow. It is for third-party truth, not for your repo's own architecture or policies.
+
+## When To Use Skills
+
+Use skills when the guidance is reusable, repo-owned, and should survive across waves, roles, or runtimes, such as:
+
+- coding norms
+- review expectations
+- environment-specific rules
+- Railway, Kubernetes, or GitHub release procedures
+- runtime-specific instructions for Codex, Claude, or OpenCode
+- role-oriented heuristics for implementation, deploy, cont-QA, or research agents
+
+## What Remains Authoritative
+
+Neither Context7 nor skills replace the actual repo.
+
+The highest-authority sources are still:
+
+- repository source
+- `wave.config.json`
+- wave markdown
+- role prompts in `docs/agents/*.md`
+- shared plan docs
+- the generated shared summary and inboxes for the active run
+
+Skills are additive guidance. Context7 is non-canonical external context. The repo and wave artifacts remain authoritative.
+
+## How They Work Together
+
+A typical deploy-focused wave might use both:
+
+- Context7
+  For the latest official framework or platform docs.
+- Skills
+  For repo-specific deploy rules, Railway conventions, and runtime-specific execution guidance.
+
+That combination keeps the agent grounded in both external truth and local operating rules.
+
+## Runtime Behavior
+
+Both surfaces are runtime aware, but in different ways:
+
+- Context7 is fetched and injected into the compiled prompt.
+- Skills are resolved after executor selection and then projected into the runtime-specific overlay surface for that executor.
+
+Because of that:
+
+- changing Context7 selection changes the prompt fingerprint
+- changing resolved skills also changes the prompt fingerprint and trace metadata
+
+## Best Practice
+
+- Put version-sensitive third-party docs into Context7.
+- Put stable repo or environment playbooks into skills.
+- Keep wave prompts focused on the specific assignment, not long-lived reusable rules.
+- If the same guidance is repeated across waves, promote it into a skill.
+
+For exact skill bundle layout and resolution order, see [reference/skills.md](../reference/skills.md).

package/docs/concepts/operating-modes.md

@@ -0,0 +1,91 @@
+# Oversight, Dark-Factory, And Human Feedback
+
+Wave now has an explicit planning vocabulary for execution posture.
+
+Today that posture is captured in project profile memory and planner output. The deeper runtime policy attached to those modes is still roadmap work, so this page distinguishes what is already shipped from what is still a convention.
+
+## The Two Postures
+
+- `oversight`
+  Human review and intervention are expected parts of the operating model for risky work.
+- `dark-factory`
+  The goal is end-to-end execution without routine human intervention.
+
+These values are stored in `.wave/project-profile.json` and emitted into planner-generated specs and wave markdown.
+
+## What Ships Today
+
+Today the runtime ships:
+
+- project-profile memory for default oversight mode
+- planner prompts that ask for oversight mode
+- generated specs and waves that record the chosen mode
+- deploy-environment memory that helps infra and release planning
+- orchestrator-first clarification handling and human feedback queueing
+
+The runtime does not yet enforce a separate hard policy profile for `dark-factory` beyond what is already encoded in the wave itself.
+
+## How To Interpret The Modes Right Now
+
+Treat them as planning posture:
+
+- `oversight`
+  Default when a human operator should expect to inspect progress, answer questions, or approve risky transitions.
+- `dark-factory`
+  Use only when the wave already has explicit environment modeling, validation, rollback posture, and clear closure signals.
+
+## Human Feedback Is Not The Same Thing
+
+Human feedback is a runtime escalation mechanism, not an operating mode.
+
+The launcher flow is:
+
+1. agent emits a clarification request or blocker
+2. the orchestrator tries to resolve it from repo state, policy, ownership, or targeted rerouting
+3. only unresolved items become human feedback tickets
+4. those tickets stay visible in ledgers, summaries, and traces until resolved
+
+That means even `oversight` mode still tries to keep routine clarification inside the orchestration loop before escalating to a human.
+
+## Oversight Mode Best Fit
+
+Choose `oversight` when:
+
+- deploy or infra mutation is live and risky
+- the environment model is incomplete
+- rollback steps are still implicit
+- legal, compliance, or release decisions need explicit human sign-off
+- the repo is still shaping its skills and closure rules
+
+## Dark-Factory Best Fit
+
+Choose `dark-factory` only when all of these are already true:
+
+- deploy environments are typed and explicit
+- runtime and credential expectations are known
+- validation commands are concrete
+- rollback or recovery posture is documented
+- closure evidence is machine-checkable or strongly operator-visible
+- missing context would be treated as a planning failure, not something to improvise live
+
+## Best Practice
+
+Default to `oversight` until the repo has earned `dark-factory`.
+
+That usually means:
+
+- stable skills for deploy and infra work
+- consistent deploy-environment naming
+- strong validation commands
+- reliable docs and trace review habits
+- low ambiguity about who owns live mutation
+
+## Relationship To The Roadmap
+
+The roadmap still includes stronger explicit oversight vs dark-factory workflows. What is shipped today is the planning foundation:
+
+- stored project defaults
+- typed values in planner output
+- better environment modeling
+
+The stricter execution semantics are the next step, not a hidden already-finished feature.

package/docs/concepts/runtime-agnostic-orchestration.md

@@ -0,0 +1,95 @@
+# Runtime-Agnostic Orchestration
+
+Wave is runtime agnostic at the orchestration layer.
+
+That means planning, coordination, closure, and traces do not depend on whether the selected executor is Codex, Claude Code, OpenCode, or the local smoke executor.
+
+## What Stays The Same Across Runtimes
+
+These layers are runtime-neutral:
+
+- wave parsing and validation
+- component and closure gates
+- compiled shared summaries and per-agent inboxes
+- coordination log and rendered message board
+- helper assignments and dependency handling
+- integration summaries, docs queues, and ledgers
+- dry-run previews
+- trace bundles and replay metadata
+
+The runtime only changes at the last step, when the launcher translates the resolved assignment into an executor-specific invocation.
+
+## Where Runtime-Specific Logic Lives
+
+Runtime-specific behavior is isolated to the executor adapter layer:
+
+- Codex
+  `codex exec` invocation, sandbox flags, `--add-dir`, JSON mode, search, images, and other `exec` flags.
+- Claude
+  `claude -p` plus system-prompt overlay, settings merge, hooks, and permission surface.
+- OpenCode
+  `opencode run` plus generated `opencode.json`, attached files, and runtime instruction overlays.
+- Local
+  A smoke executor used for prompt and closure verification without a real hosted runtime.
+
+The orchestration substrate above those adapters does not need to know how the runtime transports prompts.
+
+## Why This Matters
+
+Runtime agnosticism gives you:
+
+- the same plan and closure model across vendors
+- replay and audit surfaces that do not care which runtime produced the work
+- per-role runtime choice without rewriting authoring conventions
+- retry-time fallback without inventing a second planning model
+
+## Runtime Resolution
+
+Executor choice resolves in a fixed order:
+
+1. explicit agent `### Executor` id
+2. executor profile id
+3. lane role default
+4. CLI `--executor`
+5. global default
+
+After that choice is final, the launcher resolves runtime-specific overlays and any runtime-attached skill packs.
+
+## Fallback And Mix Policy
+
+Wave is not runtime blind. It is runtime agnostic, but still runtime aware.
+
+- runtime mix targets can cap how many agents use a given executor
+- executor profiles can declare fallbacks
+- lane policy can supply default executor choices by role
+- retries can reassign an agent to a policy-safe fallback runtime
+
+The important part is that fallback does not change the higher-level wave contract. The runtime changes, but the ownership, closure, and trace model remain the same.
+
+## Skills Across Runtimes
+
+The skill system follows the same pattern:
+
+- `skills/` is the canonical repo-owned source
+- the launcher resolves skill ids without caring which runtime will consume them
+- the executor adapter projects those skills into the surface each runtime understands
+
+Examples:
+
+- Codex receives skill bundle directories through `--add-dir`
+- Claude receives merged skill text through the generated system prompt overlay
+- OpenCode receives skill instructions and attached files through `opencode.json` and `--file`
+- Local receives prompt-only projections
+
+The bundle is shared. The projection is runtime specific.
+
+## Best Practice
+
+Keep planning, ownership, and proof requirements runtime neutral whenever possible. Use runtime-specific settings only for:
+
+- transport details
+- model or budget selection
+- safety and permission settings
+- runtime-native adapter instructions
+
+That separation is what keeps the orchestrator portable instead of turning it into a Codex-only or Claude-only harness.