@chllming/wave-orchestration 0.6.3 → 0.7.0

package/docs/evals/external-command-config.swe-bench-pro.json

@@ -0,0 +1,8 @@
+{
+  "adapters": {
+    "swe-bench-pro": {
+      "single-agent": "node \"scripts/wave-orchestrator/swe-bench-pro-task.mjs\" run --instance \"{task_id}\" --arm \"{arm}\" --model \"{model_id}\" --reasoning-effort \"{reasoning_effort}\" --max-wall-clock-minutes \"{max_wall_clock_minutes}\" --max-turns \"{max_turns}\"",
+      "full-wave": "node \"scripts/wave-orchestrator/swe-bench-pro-task.mjs\" run --instance \"{task_id}\" --arm \"{arm}\" --model \"{model_id}\" --reasoning-effort \"{reasoning_effort}\" --max-wall-clock-minutes \"{max_wall_clock_minutes}\" --max-turns \"{max_turns}\""
+    }
+  }
+}

package/docs/evals/pilots/README.md

@@ -0,0 +1,47 @@
+---
+title: "External Benchmark Pilots"
+summary: "Frozen pilot manifests for the first honest direct benchmark runs."
+---
+
+# External Benchmark Pilots
+
+These manifests freeze the first-run task selections for direct external benchmarks.
+
+They exist to prevent:
+
+- ad hoc task picking
+- silent pilot drift between runs
+- unfair re-sampling after seeing results
+
+The current frozen direct pilot is:
+
+- `SWE-bench Pro`
+
+Each manifest records:
+
+- benchmark id
+- split assumptions
+- sample strategy
+- exact task ids
+- task-level metadata needed for later aggregation
+
+These manifests are benchmark inputs, not run history.
+
+If a smaller or narrower batch is needed after the canonical pilot is frozen, create a
+new derivative manifest rather than editing the original file in place.
+
+Derivative manifests must:
+
+- name the parent frozen manifest they were derived from
+- explain the deterministic subset rule they use
+- state whether they are review-only or comparison-ready
+
+Example:
+
+- `docs/evals/pilots/swe-bench-pro-public-full-wave-review-10.json`
+  is a review-only 10-task subset derived from the frozen 20-task SWE-bench Pro public pilot.
+  It exists for a multi-agent diagnostic sweep and does not replace the canonical
+  single-agent versus full-wave comparison.
+
+When a derivative review batch is run, inspect the generated `failure-review.md` before
+treating any aggregate score as capability evidence.

package/docs/evals/pilots/swe-bench-pro-public-full-wave-review-10.json

@@ -0,0 +1,64 @@
+{
+  "version": 1,
+  "id": "swe-bench-pro-public-full-wave-review-10",
+  "benchmarkId": "swe-bench-pro",
+  "title": "SWE-bench Pro Public Full-Wave Review 10",
+  "split": "public",
+  "sampleStrategy": "first-listed-per-repo-from-frozen-20-task-pilot",
+  "sampleSource": "Derived from docs/evals/pilots/swe-bench-pro-public-pilot.json by taking the first listed task for each repository pair in the frozen 20-task public pilot.",
+  "derivedFromManifestPath": "docs/evals/pilots/swe-bench-pro-public-pilot.json",
+  "reviewOnly": true,
+  "reviewScope": "multi-agent-only-diagnostic",
+  "tasks": [
+    {
+      "taskId": "instance_NodeBB__NodeBB-04998908ba6721d64eba79ae3b65a351dcfbc5b5-vnan",
+      "repo": "NodeBB/NodeBB",
+      "repoLanguage": "js"
+    },
+    {
+      "taskId": "instance_qutebrowser__qutebrowser-f91ace96223cac8161c16dd061907e138fe85111-v059c6fdc75567943479b23ebca7c07b5e9a7f34c",
+      "repo": "qutebrowser/qutebrowser",
+      "repoLanguage": "python"
+    },
+    {
+      "taskId": "instance_ansible__ansible-f327e65d11bb905ed9f15996024f857a95592629-vba6da65a0f3baefda7a058ebbd0a8dcafb8512f5",
+      "repo": "ansible/ansible",
+      "repoLanguage": "python"
+    },
+    {
+      "taskId": "instance_internetarchive__openlibrary-4a5d2a7d24c9e4c11d3069220c0685b736d5ecde-v13642507b4fc1f8d234172bf8129942da2c2ca26",
+      "repo": "internetarchive/openlibrary",
+      "repoLanguage": "python"
+    },
+    {
+      "taskId": "instance_gravitational__teleport-3fa6904377c006497169945428e8197158667910-v626ec2a48416b10a88641359a169d99e935ff037",
+      "repo": "gravitational/teleport",
+      "repoLanguage": "go"
+    },
+    {
+      "taskId": "instance_navidrome__navidrome-7073d18b54da7e53274d11c9e2baef1242e8769e",
+      "repo": "navidrome/navidrome",
+      "repoLanguage": "go"
+    },
+    {
+      "taskId": "instance_element-hq__element-web-33e8edb3d508d6eefb354819ca693b7accc695e7",
+      "repo": "element-hq/element-web",
+      "repoLanguage": "js"
+    },
+    {
+      "taskId": "instance_future-architect__vuls-407407d306e9431d6aa0ab566baa6e44e5ba2904",
+      "repo": "future-architect/vuls",
+      "repoLanguage": "go"
+    },
+    {
+      "taskId": "instance_flipt-io__flipt-e42da21a07a5ae35835ec54f74004ebd58713874",
+      "repo": "flipt-io/flipt",
+      "repoLanguage": "go"
+    },
+    {
+      "taskId": "instance_protonmail__webclients-2c3559cad02d1090985dba7e8eb5a129144d9811",
+      "repo": "protonmail/webclients",
+      "repoLanguage": "js"
+    }
+  ]
+}

package/docs/evals/pilots/swe-bench-pro-public-pilot.json

@@ -0,0 +1,111 @@
+{
+  "version": 1,
+  "id": "swe-bench-pro-public-pilot",
+  "benchmarkId": "swe-bench-pro",
+  "title": "SWE-bench Pro Public Pilot",
+  "split": "public",
+  "sampleStrategy": "fixed-stratified-public-slice",
+  "sampleSource": "First 100 public rows from the Hugging Face dataset viewer, stratified to two tasks per selected repository where available.",
+  "tasks": [
+    {
+      "taskId": "instance_NodeBB__NodeBB-04998908ba6721d64eba79ae3b65a351dcfbc5b5-vnan",
+      "repo": "NodeBB/NodeBB",
+      "repoLanguage": "js"
+    },
+    {
+      "taskId": "instance_NodeBB__NodeBB-51d8f3b195bddb13a13ddc0de110722774d9bb1b-vf2cf3cbd463b7ad942381f1c6d077626485a1e9e",
+      "repo": "NodeBB/NodeBB",
+      "repoLanguage": "js"
+    },
+    {
+      "taskId": "instance_qutebrowser__qutebrowser-f91ace96223cac8161c16dd061907e138fe85111-v059c6fdc75567943479b23ebca7c07b5e9a7f34c",
+      "repo": "qutebrowser/qutebrowser",
+      "repoLanguage": "python"
+    },
+    {
+      "taskId": "instance_qutebrowser__qutebrowser-c580ebf0801e5a3ecabc54f327498bb753c6d5f2-v2ef375ac784985212b1805e1d0431dc8f1b3c171",
+      "repo": "qutebrowser/qutebrowser",
+      "repoLanguage": "python"
+    },
+    {
+      "taskId": "instance_ansible__ansible-f327e65d11bb905ed9f15996024f857a95592629-vba6da65a0f3baefda7a058ebbd0a8dcafb8512f5",
+      "repo": "ansible/ansible",
+      "repoLanguage": "python"
+    },
+    {
+      "taskId": "instance_ansible__ansible-a26c325bd8f6e2822d9d7e62f77a424c1db4fbf6-v0f01c69f1e2528b935359cfe578530722bca2c59",
+      "repo": "ansible/ansible",
+      "repoLanguage": "python"
+    },
+    {
+      "taskId": "instance_internetarchive__openlibrary-4a5d2a7d24c9e4c11d3069220c0685b736d5ecde-v13642507b4fc1f8d234172bf8129942da2c2ca26",
+      "repo": "internetarchive/openlibrary",
+      "repoLanguage": "python"
+    },
+    {
+      "taskId": "instance_internetarchive__openlibrary-dbbd9d539c6d4fd45d5be9662aa19b6d664b5137-v08d8e8889ec945ab821fb156c04c7d2e2810debb",
+      "repo": "internetarchive/openlibrary",
+      "repoLanguage": "python"
+    },
+    {
+      "taskId": "instance_gravitational__teleport-3fa6904377c006497169945428e8197158667910-v626ec2a48416b10a88641359a169d99e935ff037",
+      "repo": "gravitational/teleport",
+      "repoLanguage": "go"
+    },
+    {
+      "taskId": "instance_gravitational__teleport-c782838c3a174fdff80cafd8cd3b1aa4dae8beb2",
+      "repo": "gravitational/teleport",
+      "repoLanguage": "go"
+    },
+    {
+      "taskId": "instance_navidrome__navidrome-7073d18b54da7e53274d11c9e2baef1242e8769e",
+      "repo": "navidrome/navidrome",
+      "repoLanguage": "go"
+    },
+    {
+      "taskId": "instance_navidrome__navidrome-b65e76293a917ee2dfc5d4b373b1c62e054d0dca",
+      "repo": "navidrome/navidrome",
+      "repoLanguage": "go"
+    },
+    {
+      "taskId": "instance_element-hq__element-web-33e8edb3d508d6eefb354819ca693b7accc695e7",
+      "repo": "element-hq/element-web",
+      "repoLanguage": "js"
+    },
+    {
+      "taskId": "instance_element-hq__element-web-5dfde12c1c1c0b6e48f17e3405468593e39d9492-vnan",
+      "repo": "element-hq/element-web",
+      "repoLanguage": "js"
+    },
+    {
+      "taskId": "instance_future-architect__vuls-407407d306e9431d6aa0ab566baa6e44e5ba2904",
+      "repo": "future-architect/vuls",
+      "repoLanguage": "go"
+    },
+    {
+      "taskId": "instance_future-architect__vuls-e6c0da61324a0c04026ffd1c031436ee2be9503a",
+      "repo": "future-architect/vuls",
+      "repoLanguage": "go"
+    },
+    {
+      "taskId": "instance_flipt-io__flipt-e42da21a07a5ae35835ec54f74004ebd58713874",
+      "repo": "flipt-io/flipt",
+      "repoLanguage": "go"
+    },
+    {
+      "taskId": "instance_flipt-io__flipt-3b2c25ee8a3ac247c3fad13ad8d64ace34ec8ee7",
+      "repo": "flipt-io/flipt",
+      "repoLanguage": "go"
+    },
+    {
+      "taskId": "instance_protonmail__webclients-2c3559cad02d1090985dba7e8eb5a129144d9811",
+      "repo": "protonmail/webclients",
+      "repoLanguage": "js"
+    },
+    {
+      "taskId": "instance_protonmail__webclients-6dcf0d0b0f7965ad94be3f84971afeb437f25b02",
+      "repo": "protonmail/webclients",
+      "repoLanguage": "js"
+    }
+  ]
+}

package/docs/evals/wave-benchmark-program.md

@@ -0,0 +1,302 @@
+---
+title: "Wave Benchmark Program"
+summary: "Locked benchmark spec for Wave-native coordination evaluations, baseline arms, scoring rules, and external benchmark positioning."
+---
+
+# Wave Benchmark Program
+
+This document is the implementation-side contract for Wave benchmarking.
+
+It complements:
+
+- `docs/evals/benchmark-catalog.json` for benchmark vocabulary
+- `docs/evals/cases/` for the deterministic local corpus
+- `docs/evals/external-benchmarks.json` for external adapters and positioning
+- `scripts/wave-orchestrator/benchmark.mjs` for execution and reporting
+
+## First Public Claim
+
+The first claim this benchmark program is designed to support is:
+
+> Under equal executor assumptions, the full Wave orchestration surface improves distributed-state reconstruction, inbox targeting, routing quality, and premature-closure resistance relative to stripped-down baselines.
+
+This is intentionally narrower than "Wave is better than all coding agents."
+
+## Benchmark Arms
+
+The benchmark runner supports these arms:
+
+- `single-agent`
+  One primary owner operates from a local view of records they authored. No inbound targeted coordination is compiled into that arm, and there is no compiled shared summary, no targeted inboxes, no capability routing, and no explicit closure guard simulation.
+- `multi-agent-minimal`
+  Multiple agents exist, but they only share a minimal global summary. There is no targeted inbox routing and no benchmark-aware closure discipline.
+- `full-wave`
+  The current Wave projection and routing surfaces are used: canonical coordination state, compiled shared summary, targeted inboxes, request assignments, and closure-guard simulation.
+- `full-wave-plus-improvement`
+  Reserved for later benchmark-improvement loops after a baseline is established. The runner supports the arm id, but the initial local corpus focuses on the first three arms.
+
+## Shipped Native Families
+
+The first shipped deterministic corpus covers one case in each of the core coordination families:
+
+- `hidden-profile-pooling`
+- `silo-escape`
+- `blackboard-fidelity`
+- `contradiction-recovery`
+- `simultaneous-coordination`
+- `expertise-leverage`
+
+It also includes a cross-cutting premature-closure guard case under `hidden-profile-pooling / premature-consensus-guard`.
+
+## Scoring Rules
+
+Each benchmark case defines:
+
+- `familyId`
+- `benchmarkId`
+- `supportedArms`
+- `fixture`
+- `expectations`
+- `scoring.kind`
+- `scoring.primaryMetric`
+- `scoring.thresholds`
+
+The runner computes case-level metrics from deterministic coordination fixtures using current Wave machinery where possible:
+
+- `compileSharedSummary()`
+- `compileAgentInbox()`
+- `buildRequestAssignments()`
+- `openClarificationLinkedRequests()`
+
+The primary metric determines case pass/fail. Directionality comes from the benchmark catalog, not from the case file.
+
+For reporting above the case level, the runner also computes a direction-aligned score:
+
+- `higher-is-better` metrics keep their raw score
+- `lower-is-better` metrics are flipped to `100 - rawScore`
+
+That rule applies to:
+
+- family `meanScore`
+- overall and family `meanDelta`
+- the `statisticallyConfident` comparison flag
+
+This keeps a positive delta semantically stable: positive always means "better than baseline" even when a case's raw primary metric is lower-is-better.
+
+## Significance And Comparative Reporting
+
+Comparative reporting uses:
+
+- mean score delta versus the `single-agent` baseline
+- bootstrap confidence intervals over case deltas
+- a confidence rule: only report a statistically confident win when the lower bound of the confidence interval is above zero
+
+The initial implementation reports the practical delta directly and leaves final publication thresholds to operator judgment. The runner still records the per-case practical win threshold in the case definition so later work can harden claim logic without changing the corpus format.
+
+## Corpus Design Rules
+
+The local case corpus follows these constraints:
+
+- deterministic and file-backed
+- cheap enough to run in ordinary repo CI or local development
+- focused on Wave-native surfaces, not generic model capability
+- auditable by inspecting the case JSON, generated summaries, inboxes, and assignments
+- extensible to live-run and trace-backed variants later
+
+The first corpus deliberately exercises projection, routing, and closure logic before attempting expensive live multi-executor runs.
+
+## Native Benchmarking Mode
+
+`wave benchmark run` is the native deterministic benchmarking mode.
+
+This mode is intentionally narrow:
+
+- it tests the Wave substrate, not generic model capability
+- it holds the coordination fixture constant and varies only the arm behavior
+- it uses current Wave machinery to compile summaries, inboxes, assignments, and closure guards
+- it is cheap and reproducible enough to run in local development and CI
+
+What it is meant to prove:
+
+- the blackboard projections preserve decision-changing state
+- targeted inboxes reduce silos instead of creating them
+- capability routing sends the right work to the right owner
+- contradiction handling becomes explicit repair work
+- closure guards resist premature PASS
+
+What it does not prove by itself:
+
+- raw coding ability on live repos
+- leaderboard-ready external benchmark performance
+- runtime-specific agent behavior under real tool pressure
+
+That separation is intentional. Native mode is the first honest proof layer for a MAS tool whose core claim is about shared state, routing, synthesis, and closure discipline.
+
+## Native Metric Contract
+
+For each case and arm, the native runner records:
+
+- `score`
+  The case's primary metric value.
+- `alignedScore`
+  The direction-aligned case score used for family summaries and deltas.
+- `passed`
+  Whether the primary metric satisfied the case threshold.
+- `direction`
+  Whether the metric is `higher-is-better` or `lower-is-better`.
+- `threshold`
+  The configured case threshold for the primary metric.
+- `metrics`
+  The full metric map computed from the deterministic fixture.
+- `details`
+  Supporting breakdowns such as matched global facts, summary facts, targeted inbox recall, assignment precision, distinct assigned agents, and whether the blocking guard tripped.
+- `artifacts`
+  The generated `sharedSummary`, `inboxes`, `assignments`, and `blockingGuard` state used to score the arm.
+
+The runner also records:
+
+- `familySummary`
+  Direction-aligned mean score and pass rate per family and arm.
+- `comparisons`
+  Direction-aligned mean delta versus `single-agent`, bootstrap confidence intervals, and a conservative `statisticallyConfident` flag.
+
+When `waveControl` reporting is enabled, native runs also publish:
+
+- `benchmark_run`
+  Suite-level metadata, selected arms, family summary, and comparison summary.
+- `benchmark_item`
+  Full per-case, per-arm payloads including `score`, `alignedScore`, `passed`, `metrics`, `details`, and generated artifacts.
+
+Native mode does **not** emit `verification` or `review` events, because there is no external verifier and no benchmark-validity split to interpret. Those are reserved for `wave benchmark external-run`.
+
+## Native Metric Set
+
+The current deterministic runner logs the following metrics:
+
+| Metric | Native signal used today | Why it matters for the MAS claim |
+| --- | --- | --- |
+| `distributed-info-accuracy` | Percent of expected global facts visible in the integration-visible state: shared summary, integration-owner view when present, and structured assignment artifacts | Proves the team pooled distributed evidence rather than leaving it siloed |
+| `latent-asymmetry-surfacing-rate` | Clarification recall by explicit record id when a case expects missing-fact surfacing, otherwise targeted inbox recall | Proves the system notices that important evidence is still missing before closure |
+| `premature-convergence-rate` | `100` when a case required a blocking guard and the arm failed to keep it active, else `0` | Proves whether closure discipline resists converging on incomplete state |
+| `global-state-reconstruction-rate` | Percent of required cross-agent facts reconstructed in the integration-visible state rather than only in owner-private inboxes | Proves communication turned into a correct shared picture, not only message traffic |
+| `summary-fact-retention-rate` | Percent of required summary facts preserved in the shared summary | Proves summary compression is trustworthy enough to support downstream synthesis |
+| `communication-reasoning-gap` | `100 - global-state-reconstruction-rate` | Makes failure explicit when agents talk but still fail to integrate correctly |
+| `projection-consistency-rate` | Same summary-fidelity signal, framed for projection integrity | Proves the blackboard projections remain semantically aligned with canonical state |
+| `targeted-inbox-recall` | Percent of expected owner-specific facts present in the right inboxes | Proves targeted context actually reaches the agents who own the work |
+| `integration-coherence-rate` | Global-fact recall used as a proxy for integration fidelity in the deterministic corpus | Proves the synthesis layer reflects the underlying coordination state |
+| `contradiction-detection-rate` | Targeted-fact recall on contradiction-oriented fixtures | Proves conflicting claims become visible instead of being smoothed away |
+| `repair-closure-rate` | Assignment precision for required repair or follow-up work | Proves contradictions and blockers turn into owner-bound resolution work |
+| `false-consensus-rate` | `100` when a contradiction/premature-close guard should have held and did not, else `0` | Proves whether the system is narrating consensus where the state is still unresolved |
+| `deadlock-rate` | `100` when the arm failed to reach the required number of distinct owners in simultaneous-coordination cases, else `0` | Proves whether the team collapses under concurrent coordination pressure |
+| `contention-resolution-rate` | Assignment precision in concurrent blocker cases | Proves simultaneous work can resolve rather than stall |
+| `symmetry-breaking-rate` | Percent of the required distinct owners/choices achieved | Proves the team can break lockstep and avoid same-plan collapse |
+| `expert-preservation-rate` | Targeted-fact recall used on expert-preservation fixtures | Proves the strongest specialist signal survives into the visible decision path |
+| `capability-routing-precision` | Correct assignment rate for capability-routed requests | Proves the routing layer is steering work to the intended owner |
+| `expert-performance-gap` | `100 - expert-preservation-rate` | Makes expert-signal dilution explicit as a failure measure rather than an anecdote |
+
+Several of these metrics intentionally reuse the same deterministic signals under different benchmark families. That is not accidental. The goal is not to create an unnecessarily large metric vocabulary; it is to ask the same core question from multiple MAS failure angles:
+
+- did the right facts reach shared state
+- did the right owners receive the right context
+- did conflicts become explicit repair work
+- did closure wait for integrated proof
+
+The important constraint is that "shared state" here does **not** mean "the union of every owner inbox." The native runner scores global reconstruction from the integration-visible artifacts, so facts that remain split across private owner views do not count as reconstructed.
+
+## Why These Metrics Matter
+
+The first public claim is not "Wave is a better model." It is that Wave is a better multi-agent coordination substrate.
+
+That means the most valuable native metrics are the ones that expose the failure cases from the README:
+
+- distributed-evidence metrics matter because a MAS that cannot pool private facts has no credible shared-state claim
+- summary and inbox metrics matter because a blackboard is only useful if the projections stay faithful and owner-relevant
+- routing metrics matter because specialist structure only helps if work actually lands on the right owner
+- contradiction and repair metrics matter because visible disagreement without repair is still coordination failure
+- premature-closure metrics matter because a MAS that can always narrate PASS is not proving anything
+- simultaneous-coordination metrics matter because many systems look fine in serial but collapse under concurrent blockers
+
+In other words, these metrics matter because they test the *coordination mechanism itself*, which is the actual product claim of Wave.
+
+## External Benchmark Positioning
+
+The external benchmark registry is split into two modes:
+
+- `direct`
+  The benchmark is treated as a runnable external suite with a command template or adapter recipe. The current direct target is `SWE-bench Pro`.
+- `adapted`
+  The benchmark is treated as a design reference whose failure mode should be mirrored with repo-local Wave cases. Current adapted targets are `SkillsBench`, `EvoClaw`, `HiddenBench`, `Silo-Bench`, and `DPBench`.
+
+This keeps the first milestone honest:
+
+- prove the Wave-specific substrate first
+- then layer in broader external reality checks
+
+## Current Direct Benchmark
+
+The current direct external benchmark is:
+
+- `SWE-bench Pro`
+
+Why this benchmark now:
+
+- it is contamination-resistant relative to older SWE-bench variants
+- it has a public executable harness
+- it exercises real repository bug-fix work without changing the Wave coordination claim into a generic terminal benchmark claim
+
+The second direct benchmark slot is intentionally deferred until a later `CooperBench` pass.
+
+The first direct comparison should compare only:
+
+- `single-agent`
+- `full-wave`
+
+And both arms must keep the following fixed:
+
+- model id
+- executor id and command
+- tool permissions
+- temperature and reasoning settings
+- wall-clock budget
+- turn budget
+- retry limit
+- verification harness
+- dataset version or task manifest
+
+Execution should be driven through explicit command templates for the official benchmark harnesses rather than ad hoc shell invocation. The config shape lives at `docs/evals/external-command-config.sample.json`, and the local SWE-bench Pro harness is wired through `docs/evals/external-command-config.swe-bench-pro.json`.
+
+## Review-Only External Subsets
+
+After the canonical SWE-bench Pro pilot is frozen, narrower review batches may be derived for
+diagnostic work such as a `full-wave`-only sweep.
+
+Those runs are allowed only when they:
+
+- derive from an already-frozen pilot manifest instead of re-sampling freely
+- keep the review scope explicit in the manifest and report
+- avoid presenting the result as a matched `single-agent` versus `full-wave` claim
+
+Example:
+
+- `docs/evals/pilots/swe-bench-pro-public-full-wave-review-10.json`
+  is a 10-task diagnostic subset derived from the frozen 20-task SWE-bench Pro pilot.
+  It is suitable for multi-agent review work before a later pairwise rerun, but it does
+  not replace the canonical direct comparison.
+
+## Output Contract
+
+`wave benchmark run` writes results under `.tmp/wave-benchmarks/latest/` by default:
+
+- `results.json`
+- `results.md`
+
+`wave benchmark external-run` writes the same pair in its selected output directory plus:
+
+- `failure-review.json`
+- `failure-review.md`
+
+The failure review is the first artifact to inspect for review-only subsets because it
+separates verifier invalidation, setup or harness failures, dry-run planning output, and
+trustworthy patch-quality failures.
+
+These artifacts are local and reproducible. They are not intended to be committed as run history.

package/docs/guides/planner.md

@@ -10,15 +10,19 @@ It reduces repeated setup questions, stores project defaults, and generates wave
 
 - `wave project setup`
 - `wave project show`
-- `wave draft`
+- interactive `wave draft --wave <n>`
+- agentic `wave draft --agentic --task "..."`
+- planner run review via `wave draft --show-run <run-id>`
+- explicit materialization via `wave draft --apply-run <run-id>`
 - persistent project memory in `.wave/project-profile.json`
+- transient planner packets in `.wave/planner/runs/<run-id>/`
+- planner-run Context7 injection via `planner.agentic.context7Bundle`
 - 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
+- candidate matrix previews plus canonical component matrix updates on apply
 
 ## What The Planner Does Not Yet Ship
 
-- ad hoc transient runs
 - forward replanning of later waves
 - separate runtime enforcement for oversight vs dark-factory
 
@@ -46,12 +50,25 @@ This lets later drafts inherit repo-specific defaults instead of asking the same
 
 ## Drafting A Wave
 
-Run:
+Interactive draft:
 
 ```bash
 pnpm exec wave draft --wave 1 --template implementation
 ```
 
+Agentic draft:
+
+```bash
+pnpm exec wave draft --agentic --task "Add X according to the current architecture" --from-wave 3 --max-waves 2
+pnpm exec wave draft --show-run <run-id> --json
+pnpm exec wave draft --apply-run <run-id> --waves all
+```
+
+The planner agent reads repo-local planning sources directly, and it can also
+prefetch a planner-specific Context7 bundle when
+`planner.agentic.context7Bundle` points at a published library. The tracked
+source corpus for that library lives under `docs/context7/planner-agent/`.
+
 Supported templates today:
 
 - `implementation`
@@ -59,12 +76,25 @@ Supported templates today:
 - `infra`
 - `release`
 
-The planner writes:
+Interactive draft writes canonical waves immediately:
 
 - `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.
+Agentic draft writes a transient review packet first:
+
+- `.wave/planner/runs/<run-id>/request.json`
+- `.wave/planner/runs/<run-id>/sources.json`
+- `.wave/planner/runs/<run-id>/plan.json`
+- `.wave/planner/runs/<run-id>/verification.json`
+- `.wave/planner/runs/<run-id>/candidate/specs/wave-<n>.json`
+- `.wave/planner/runs/<run-id>/candidate/waves/wave-<n>.md`
+
+Canonical `docs/plans/waves/` files are only written by `--apply-run`.
+
+The transient packet also includes the exact planner prompt and the resolved
+planner Context7 selection, so review can see which external planning corpus was
+attached before the planner drafted waves.
 
 ## What The Planner Asks For
 
@@ -88,6 +118,10 @@ That gives you a wave that is much closer to launch-ready than a blank markdown
 
 The planner does not auto-discover every possible skill bundle yet, but it supports explicit per-agent `### Skills` in the rendered output.
 
+Interactive `wave draft --wave <n>` now resolves bundle names from
+`docs/context7/bundles.json`, so wave-level and per-agent Context7 selections
+can use any configured bundle instead of only `none`.
+
 The more important interaction is indirect:
 
 - project profile remembers deploy environments
@@ -99,11 +133,12 @@ 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.
+2. Use either `pnpm exec wave draft --wave <n> --template <template>` or `pnpm exec wave draft --agentic --task "..." --from-wave <n>`.
+3. Review the generated JSON spec, markdown wave, or agentic run packet.
+4. Adjust repo-specific prompts, file ownership, deliverables, proof artifacts, skills, and validation commands.
+5. If you used agentic draft, materialize only the accepted waves with `pnpm exec wave draft --apply-run <run-id>`.
+6. Run `pnpm exec wave launch --lane <lane> --start-wave <n> --end-wave <n> --dry-run --no-dashboard`.
+7. 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).
 
@@ -112,6 +147,8 @@ If you want concrete authored examples after the planner baseline, see [docs/ref
 - Treat the generated draft as a strong starting point, not untouchable output.
 - Tighten validation commands before launch.
 - Keep file ownership narrow and explicit.
+- Treat `### Deliverables` and `### Proof artifacts` as part of the plan contract, not optional polish.
+- Keep `docs/context7/planner-agent/` in sync with the selected planning cache slice before publishing the planner bundle to Context7.
 - 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.