@chllming/wave-orchestration 0.6.3 → 0.7.0

package/docs/reference/sample-waves.md

@@ -1,23 +1,29 @@
 ---
 title: "Sample Waves"
-summary: "A showcase-first sample wave that demonstrates the current 0.6.1 Wave surface."
+summary: "Showcase-first sample waves that demonstrate the current 0.7.0 Wave surface."
 ---
 
 # Sample Waves
 
-This guide points to one showcase-first sample wave that demonstrates the current `0.6.1` authored Wave surface.
+This guide points to showcase-first sample waves that demonstrate the current `0.7.0` authored Wave surface.
 
-The example is intentionally denser than a typical production wave. Its job is to teach the current authoring and runtime surface quickly, not to be the smallest possible launch-ready file.
+The examples are intentionally denser than typical production waves. Their job is to teach the current authoring and runtime surface quickly, not to be the smallest possible launch-ready files.
 
-## Canonical Example
+## Canonical Examples
+
+- [High-fidelity repo-landed rollout wave](../plans/examples/wave-example-rollout-fidelity.md)
+  Shows what a good `repo-landed` outcome looks like when one promoted component only closes honestly if desired-state records, reconcile-loop substrate, and cluster-view surfaces land together. It emphasizes maturity discipline, explicit deliverables, and shared-plan closure without drifting into `pilot-live` claims.
 
 - [Full modern sample wave](../plans/examples/wave-example-live-proof.md)
-  Shows the combined `0.6.1` authored surface in one file: closure roles, `E0`, optional security review, delegated and pinned benchmark targets, richer executor config, `### Skills`, `### Capabilities`, `### Deliverables`, `### Exit contract`, `### Proof artifacts`, sticky retry, deploy environments, and proof-first live-wave structure.
+  Shows the combined `0.7.0` authored surface in one file: closure roles, `E0`, optional security review, delegated and pinned benchmark targets, richer executor config, `### Skills`, `### Capabilities`, `### Deliverables`, `### Exit contract`, `### Proof artifacts`, sticky retry, deploy environments, and proof-first live-wave structure.
 
-## What This Example Teaches
+## What These Examples Teach
 
-- the standard closure-role structure with `A0`, `E0`, `A8`, and `A9`
-- wave-level `## Eval targets`
+- the standard closure-role structure with `A0`, `A8`, and `A9`
+- `E0` and wave-level `## Eval targets` in the full modern sample
+- honest `repo-landed` maturity framing without `pilot-live` drift
+- multi-slice component promotion where all sibling owners must land together
+- shared-plan and component-matrix closure as part of the architecture truth
 - delegated versus pinned benchmark selection
 - coordination benchmark families from `docs/evals/benchmark-catalog.json`
 - richer executor blocks, runtime budgets, and retry policy
@@ -32,8 +38,11 @@ The example is intentionally denser than a typical production wave. Its job is t
 
 ## Feature Coverage Map
 
-This sample covers the main surfaces added or hardened for `0.6.1`:
+Together these samples cover the main surfaces added or hardened for `0.7.0`:
 
+- repo-landed maturity discipline and anti-overclaim framing
+- explicit shared-plan closure for future-wave safety
+- coordinated component slices with per-agent deliverables
 - planner-era authored wave structure
 - cross-runtime `### Skills`
 - richer `### Executor` blocks and runtime budgets
@@ -53,6 +62,7 @@ This sample covers the main surfaces added or hardened for `0.6.1`:
 Copy more literally when:
 
 - you need the section layout
+- you want a concrete example of what good repo-landed wave fidelity looks like
 - you want concrete wording for delegated versus pinned benchmark targets
 - you want a proof-first owner example with local artifact bundles and sticky retry
 
@@ -65,23 +75,24 @@ Adapt more aggressively when:
 
 ## How This Example Maps To Other Docs
 
-- Use [docs/guides/planner.md](../guides/planner.md) for the planner-generated baseline, then use this sample to see how a human would enrich the generated draft.
-- Use [docs/evals/README.md](../evals/README.md) with this sample when you need to see delegated and pinned benchmark targets in a real wave.
-- Use [docs/reference/live-proof-waves.md](./live-proof-waves.md) with this sample when you need proof-first authoring for `pilot-live` and above.
+- Use [docs/guides/planner.md](../guides/planner.md) for the planner-generated baseline, then use these samples to see how a human would enrich the generated draft for either repo-landed or proof-first work.
+- Use [docs/evals/README.md](../evals/README.md) with the full modern sample when you need to see delegated and pinned benchmark targets in a real wave.
+- Use [docs/reference/live-proof-waves.md](./live-proof-waves.md) with the full modern sample when you need proof-first authoring for `pilot-live` and above.
 - Use [docs/plans/wave-orchestrator.md](../plans/wave-orchestrator.md) for the operational runbook that explains how the launcher interprets these sections.
 
 ## Suggested Reading Order
 
-1. Start with [Full modern sample wave](../plans/examples/wave-example-live-proof.md).
-2. Read [docs/evals/README.md](../evals/README.md) if you want more background on benchmark target selection.
-3. Read [docs/reference/live-proof-waves.md](./live-proof-waves.md) if you want more detail on proof-first `pilot-live` authoring.
+1. Start with [High-fidelity repo-landed rollout wave](../plans/examples/wave-example-rollout-fidelity.md) if you want the clearest example of good closure-ready wave fidelity for a repo-only outcome.
+2. Read [Full modern sample wave](../plans/examples/wave-example-live-proof.md) if you want the denser proof-first and eval-heavy surface.
+3. Read [docs/evals/README.md](../evals/README.md) if you want more background on benchmark target selection.
+4. Read [docs/reference/live-proof-waves.md](./live-proof-waves.md) if you want more detail on proof-first `pilot-live` authoring.
 
-## Why This Example Lives In `docs/plans/examples/`
+## Why These Examples Live In `docs/plans/examples/`
 
-The example lives outside `docs/plans/waves/` on purpose.
+The examples live outside `docs/plans/waves/` on purpose.
 
 That keeps it:
 
 - easy to browse as teaching material
 - clearly separate from the repo's real launcher-facing wave sequence
-- safe to evolve as reference material without implying that it is part of the current lane's actual plan history
+- safe to evolve as reference material without implying that they are part of the current lane's actual plan history

package/docs/reference/wave-control.md

@@ -0,0 +1,164 @@
+---
+title: "Wave Control"
+summary: "Canonical telemetry, artifact upload policy, and the local-first reporting contract for the Railway-hosted Wave control plane."
+---
+
+# Wave Control
+
+Wave Control is the telemetry and analysis plane for Wave runs.
+
+The design rule is:
+
+- local files stay authoritative
+- remote reporting is best-effort
+- dashboards and markdown remain projections over typed local state
+
+## What Gets Reported
+
+Wave Control normalizes these entity types:
+
+- `wave_run`
+- `agent_run`
+- `coordination_record`
+- `task`
+- `attempt`
+- `gate`
+- `proof_bundle`
+- `rerun_request`
+- `human_input`
+- `artifact`
+- `benchmark_run`
+- `benchmark_item`
+- `verification`
+- `review`
+
+This lets the control plane answer:
+
+- what happened in a run
+- which proof and benchmark artifacts back a claim
+- whether a benchmark result is comparison-valid or only diagnostic
+- which coordination failures blocked closure
+
+## Run Identity
+
+Every Wave Control event carries a normalized run identity.
+
+The key fields are:
+
+- `workspaceId`
+- `projectId`
+- `runKind`
+- `runId`
+- `lane`
+- `wave`
+- `attempt`
+- `agentId`
+- `orchestratorId`
+- `runtimeVersion`
+- `benchmarkRunId`
+- `benchmarkItemId`
+
+Why these fields matter:
+
+- `workspaceId` separates whole adopted workspaces
+- `projectId` separates product or repo identities inside one control plane
+- `orchestratorId` separates resident orchestrators or control-plane owners
+- `runtimeVersion` lets operators compare behavior across Wave releases without guessing from deploy timestamps
+
+These are first-class query dimensions in the service, not only free-form event payload fields.
+
+## Proof Signals
+
+Wave Control is intended to make the main README claims measurable.
+
+For the explicit README-failure-case-to-signal map, see [proof-metrics.md](./proof-metrics.md).
+
+Signals to preserve:
+
+- canonical-state fidelity:
+  `coordination_record`, `wave_run`, `attempt`, and `artifact` telemetry prove the scheduler truth came from JSON state, not only markdown boards
+- evidence pooling:
+  integration and closure telemetry should cite the proof artifacts and evidence refs they relied on
+- contradiction repair:
+  gate and review telemetry should show unresolved conflicts, repair creation, and repair resolution
+- expert routing:
+  targeted assignments, reroutes, and final recommendation ownership should remain visible
+- premature closure prevention:
+  gate snapshots, proof completeness, block reasons, reruns, and cont-QA reversal should be durable
+- benchmark trust:
+  every benchmark item should distinguish capability from validity
+
+## Artifact Contract
+
+Selected artifacts are described with typed descriptors:
+
+```json
+{
+  "path": ".tmp/main-wave-launcher/traces/wave-1/attempt-1/quality.json",
+  "kind": "trace-quality",
+  "required": true,
+  "present": true,
+  "sha256": "abc123...",
+  "bytes": 2048,
+  "contentType": "application/json",
+  "uploadPolicy": "selected"
+}
+```
+
+Upload policy meanings:
+
+- `local-only`: keep only the descriptor remotely
+- `metadata-only`: report path, hash, size, and presence only
+- `selected`: upload metadata plus the artifact body when the runtime is in `metadata-plus-selected`
+- `selected`: upload metadata plus the artifact body when the runtime is in `metadata-plus-selected` or `full-artifact-upload` **and** the artifact kind is allowed by `waveControl.uploadArtifactKinds`
+- `full`: upload the artifact body in `full-artifact-upload` flows; if `uploadArtifactKinds` is set, keep the kind allowlist aligned with that policy
+
+## Runtime Config
+
+`wave.config.json` can declare:
+
+```json
+{
+  "waveControl": {
+    "endpoint": "https://wave-control.up.railway.app/api/v1",
+    "workspaceId": "my-workspace",
+    "projectId": "wave-orchestration",
+    "authTokenEnvVar": "WAVE_CONTROL_AUTH_TOKEN",
+    "reportMode": "metadata-plus-selected",
+    "uploadArtifactKinds": [
+      "trace-run-metadata",
+      "trace-quality",
+      "benchmark-results"
+    ]
+  }
+}
+```
+
+Lane overrides may refine the same surface under `lanes.<lane>.waveControl`.
+
+For a single run, operators can disable Wave Control reporting entirely with:
+
+```bash
+pnpm exec wave launch --lane main --no-telemetry
+```
+
+That suppresses the local telemetry spool and remote delivery for that invocation, while leaving the canonical runtime artifacts and local control-plane state intact.
+
+## Delivery Model
+
+Wave Control reporting should:
+
+- append local telemetry first
+- queue pending uploads under `.tmp/<lane>-wave-launcher/control-plane/telemetry/`
+- respect `waveControl.uploadArtifactKinds` before uploading any selected artifact body
+- cap pending remote uploads with `waveControl.maxPendingEvents` by dropping the oldest queued remote-delivery files, while keeping the local `events.jsonl` stream intact
+- retry delivery with idempotency keys
+- never fail a live run, proof registration, or benchmark because the network is unavailable
+
+The Railway-hosted `services/wave-control` service is an analysis surface, not the scheduler of record.
+
+The service package lives under `services/wave-control/`.
+
+For durable telemetry retention, attach Railway Postgres to `wave-control` so the
+service receives `DATABASE_URL`. Without that variable, the service falls back to the
+in-memory store and only keeps data until the process restarts.

package/docs/reference/wave-planning-lessons.md

@@ -0,0 +1,131 @@
+---
+summary: "Lessons from Waves 4-9 on what makes future waves succeed or fail."
+read_when:
+  - Drafting a new wave
+  - Splitting or renumbering future waves
+  - Deciding whether a wave should target repo-landed, pilot-live, or above
+title: "Wave Planning Lessons"
+---
+
+# Wave Planning Lessons
+
+This document captures the practical lessons from Waves 4-9. The main theme is
+simple: waves succeed when the declared maturity target, the owned slices, the
+runtime setup, and the closure artifacts all describe the same truth.
+
+## 1. One honest maturity jump per wave
+
+- Treat `repo-landed`, `pilot-live`, `qa-proved`, `fleet-ready`,
+  `cutover-ready`, and `deprecation-ready` as materially different bars.
+- A wave should promote a component by one honest maturity step, not silently
+  combine multiple levels of proof in one broad plan.
+- If a wave only lands code and tests, the target is usually `repo-landed`, not
+  `pilot-live`.
+- If a wave claims `pilot-live` or above, the wave must own real deploy/live
+  proof and rollback evidence.
+
+## 2. Live-proof waves are a different class of wave
+
+- `pilot-live` and above need an explicit live-proof owner, not just
+  implementation agents plus A8/A9/A0.
+- Live-proof waves need a canonical proof bundle under `.tmp/` and one owned
+  operations runbook under `docs/plans/operations/`.
+- The proof bundle must contain restart or rollback evidence, not only one-shot
+  success.
+- External operator commands and captured evidence must be part of the authored
+  wave, not improvised during execution.
+
+## 3. Component promotions must map to owned slices
+
+- Every promoted component needs one or more implementation owners and one
+  shared proof story.
+- If multiple agents contribute to one promoted component, their slices must be
+  obviously complementary, not overlapping guesses.
+- Shared components should not cause one agent to be retried just because a
+  sibling owner is still finishing; each agent must be able to complete its own
+  slice honestly.
+
+## 4. Deliverables must be explicit and machine-checkable
+
+- Every implementation agent should declare `### Deliverables`.
+- For live-proof waves, use `### Proof artifacts` in addition to deliverables.
+- Deliverables should be exact files or artifact manifests, not vague “test
+  coverage” or “docs updated” expectations.
+- Missing deliverables should fail the wave even if the code mostly landed.
+
+## 5. Closure must update the shared planning truth
+
+- A9 should always update `current-state`, `master-plan`, `migration`, and the
+  component cutover matrix when a wave changes what later waves may safely
+  assume.
+- The evaluator should reject a wave if the repo’s planning truth still implies
+  an older maturity level after the code has landed.
+- Shared-plan closure is not paperwork; it is part of architecture truth.
+
+## 6. Use A8 to reconcile reality before docs and evaluation
+
+- A8 is the place to detect contradictions between slices, missing ownership,
+  and proof gaps before A9 and A0 run.
+- A8 should judge `ready-for-doc-closure` versus `needs-more-work` based on the
+  landed artifact set, not on agent intent.
+- Waves were materially more reliable once A8 became a true closure gate rather
+  than optional synthesis.
+
+## 7. Runtime setup matters as much as wave prose
+
+- Do not use small fixed turn caps for synthesis-heavy or closure-heavy agents.
+  Bound them with `budget.minutes`, not `budget.turns`.
+- Pin exact model and reasoning settings for each runtime. Ambiguous profiles
+  create unclear failure modes.
+- Avoid cross-runtime fallback on live-proof or deploy-sensitive slices unless
+  there is a very good reason.
+- Context7 should be explicit and real; unresolved bundles create noise instead
+  of help.
+
+## 8. Repo-local proof and live proof are different
+
+- Repo-local tests and docs can justify `repo-landed`.
+- Live host validation, admitted runtime behavior, rollback drills, and operator
+  surfaces are what justify `pilot-live` and above.
+- Do not let “the code exists” be treated as “the deployment works.”
+
+## 9. Architecture-facing status surfaces must be future-safe
+
+- Status and projection code should be keyed to the real future topology, not
+  the smallest test case that passes today.
+- If a status model will later carry multiple runtime classes, providers, or
+  lanes, the substrate must preserve that identity now.
+- Closed enums and typed contracts should be validated as closed enums and typed
+  contracts, not accepted as arbitrary strings.
+
+## 10. The best waves are narrow, layered, and boring
+
+- Narrow waves close more reliably than broad waves.
+- A good wave answers:
+  - what exact maturity level is being claimed
+  - what exact artifacts prove it
+  - who owns repo implementation
+  - who owns live proof, if any
+  - what A9 must update
+  - what A0 must refuse to overclaim
+- If a wave still sounds ambitious and fuzzy after writing the deliverables,
+  split it again.
+
+## 11. Future-wave checklist
+
+- Does the component promotion match the real maturity level being claimed?
+- Does every promoted component have an implementation owner?
+- If the target is `pilot-live` or above, is there an explicit live-proof owner?
+- Are deliverables and proof artifacts exact and machine-checkable?
+- Are current-state and matrix updates part of A9 closure?
+- Are A8 and A0 told what would make the wave fail honestly?
+- Are runtime pins, Context7 bundles, and budgets specific enough to avoid
+  preventable execution failures?
+- Would a reviewer understand the difference between “code landed” and
+  “component promoted” just by reading the wave file?
+
+## Bottom line
+
+The successful waves were not the ones with the most code. They were the ones
+where the wave file, the runtime setup, the artifacts, and the planning docs all
+made the same claim at the same level of maturity.

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@chllming/wave-orchestration",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "license": "MIT",
   "description": "Generic wave-based multi-agent orchestration for repository work.",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/chllming/wave-orchestration.git"
+    "url": "git+https://github.com/chllming/agent-wave-orchestrator.git"
   },
-  "homepage": "https://github.com/chllming/wave-orchestration#readme",
+  "homepage": "https://github.com/chllming/agent-wave-orchestrator#readme",
   "bugs": {
-    "url": "https://github.com/chllming/wave-orchestration/issues"
+    "url": "https://github.com/chllming/agent-wave-orchestrator/issues"
   },
   "publishConfig": {
     "access": "public"
@@ -41,6 +41,7 @@
     "context7:api-check": "bash scripts/context7-export-env.sh run bash scripts/context7-api-check.sh",
     "research:import-agent-context": "node scripts/research/import-agent-context-archive.mjs scripts/research/manifests/agent-context-expanded-2026-03-22.mjs",
     "research:index-agent-context": "node scripts/research/generate-agent-context-indexes.mjs",
+    "research:sync-planner-context7": "node scripts/research/sync-planner-context7-bundle.mjs",
     "research:refresh-agent-context": "pnpm research:import-agent-context && pnpm research:index-agent-context",
     "test": "vitest run --config vitest.config.ts",
     "wave": "node scripts/wave.mjs",

package/releases/manifest.json

@@ -2,6 +2,24 @@
   "schemaVersion": 1,
   "packageName": "@chllming/wave-orchestration",
   "releases": [
+    {
+      "version": "0.7.0",
+      "date": "2026-03-23",
+      "summary": "Unified wave control operator CLI, canonical control-plane event log, Wave Control telemetry, live-wave orchestration refresh, and resident orchestrator support.",
+      "features": [
+        "Unified `wave control` CLI with `status`, `task`, `rerun`, `proof`, and `telemetry` sub-surfaces replacing `wave coord`/`wave retry`/`wave proof` as the preferred operator interface.",
+        "Canonical control-plane event log under `.tmp/<lane>-wave-launcher/control-plane/` with event-sourced materialization for proof bundles, rerun requests, operator tasks, and attempt lifecycle.",
+        "Wave Control telemetry: local-first event queueing with best-effort batch delivery, configurable report modes, selective artifact upload, and per-category capture toggles.",
+        "Live-wave orchestration refresh that keeps coordination surfaces, clarification triage, and dashboard metrics current during active execution.",
+        "Resident orchestrator support via `--resident-orchestrator` for long-running non-owning monitoring sessions.",
+        "Native and external benchmark telemetry with failure-review validity classification and config attestation hashing."
+      ],
+      "manualSteps": [
+        "Existing `wave coord`, `wave retry`, and `wave proof` commands remain available as compatibility surfaces. No migration required, but new operator docs prefer `wave control`.",
+        "To enable Wave Control telemetry, add a `waveControl` section to `wave.config.json` with at minimum an `endpoint` and `workspaceId`. Pass `--no-telemetry` to disable for a single run."
+      ],
+      "breaking": false
+    },
     {
       "version": "0.6.3",
       "date": "2026-03-22",

package/scripts/research/agent-context-archive.mjs

@@ -14,6 +14,12 @@ export const TOPIC_DEFINITIONS = [
     description:
       "Planning topology, verifier and replanner loops, protocol-driven coordination, and blackboard-aware orchestration patterns for multi-agent systems.",
   },
+  {
+    id: "agent-cooperation-and-coordination",
+    title: "Agent Cooperation and Coordination",
+    description:
+      "Benchmarks and failure analyses for inter-agent cooperation, commitment tracking, communication quality, negotiation, and teammate-style coordination.",
+  },
   {
     id: "long-running-agents-and-compaction",
     title: "Long-Running Agents and Compaction",
@@ -103,6 +109,15 @@ const SKILLS_TOPIC_OVERRIDE_SLUGS = new Set([
   "meta-context-engineering-via-agentic-skill-evolution",
 ]);
 
+const COOPERATION_TOPIC_OVERRIDE_SLUGS = new Set([
+  "cooperbench-why-coding-agents-cannot-be-your-teammates-yet",
+  "why-do-multi-agent-llm-systems-fail",
+  "systematic-failures-in-collective-reasoning-under-distributed-information-in-multi-agent-llms",
+  "silo-bench-a-scalable-environment-for-evaluating-distributed-coordination-in-multi-agent-llm-systems",
+  "dpbench-large-language-models-struggle-with-simultaneous-coordination",
+  "multi-agent-teams-hold-experts-back",
+]);
+
 function escapeInlinePipes(value) {
   return String(value ?? "").replaceAll("|", "\\|");
 }
@@ -252,6 +267,9 @@ export function inferTopics(entry, section = null) {
   if (SKILLS_TOPIC_OVERRIDE_SLUGS.has(entry.slug)) {
     topics.push("skills-and-procedural-memory");
   }
+  if (COOPERATION_TOPIC_OVERRIDE_SLUGS.has(entry.slug)) {
+    topics.push("agent-cooperation-and-coordination");
+  }
 
   if (hasDeclaredTopics) {
     return unique(topics);

package/scripts/research/manifests/agent-context-expanded-2026-03-22.mjs

@@ -3,6 +3,7 @@ import baseManifest from "./harness-and-blackboard-2026-03-21.mjs";
 const TOPICS = {
   HARNESS: "harnesses-and-practice",
   PLANNING: "planning-and-orchestration",
+  COOPERATION: "agent-cooperation-and-coordination",
   LONG_RUNNING: "long-running-agents-and-compaction",
   SKILLS: "skills-and-procedural-memory",
   BLACKBOARD: "blackboard-and-shared-workspaces",
@@ -521,6 +522,22 @@ const planningManifest = [
     fit: "Useful benchmark for testing whether coordination-heavy planning systems scale beyond serial reasoning.",
     topics: [TOPICS.PLANNING, TOPICS.REPO],
   }),
+  arxivPaper("2601.13295", {
+    title: "CooperBench: Why Coding Agents Cannot be Your Teammates Yet",
+    slug: "cooperbench-why-coding-agents-cannot-be-your-teammates-yet",
+    authors:
+      "Arpandeep Khatua, Hao Zhu, Peter Tran, Arya Prabhudesai, Frederic Sadrieh, Johann K. Lieberwirth, Xinkai Yu, Yicheng Fu, Michael J. Ryan, Jiaxin Pei, Diyi Yang",
+    year: 2026,
+    researchBucket: "P0 direct hits",
+    mapsTo:
+      "Collaborative coding benchmark for inter-agent cooperation, communication quality, commitment tracking, and coordination failures.",
+    fit: "Direct benchmark for whether coding agents behave like usable teammates instead of isolated solo solvers.",
+    additionalSource: "https://cooperbench.com",
+    additionalPdf: "https://cooperbench.com/static/pdfs/main.pdf",
+    notes:
+      "Project site hosts the same paper PDF plus leaderboard, dataset, and trajectory viewer for the benchmark.",
+    topics: [TOPICS.PLANNING, TOPICS.COOPERATION, TOPICS.REPO],
+  }),
   arxivPaper("2602.01011", {
     title: "Multi-Agent Teams Hold Experts Back",
     slug: "multi-agent-teams-hold-experts-back",

package/scripts/research/sync-planner-context7-bundle.mjs

@@ -0,0 +1,133 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { PACKAGE_ROOT } from "../wave-orchestrator/roots.mjs";
+import {
+  PLANNER_CONTEXT7_BUNDLE_ID,
+  PLANNER_CONTEXT7_DEFAULT_QUERY,
+  PLANNER_CONTEXT7_LIBRARY_NAME,
+  PLANNER_CONTEXT7_SOURCE_DIR,
+  PLANNER_CONTEXT7_SOURCE_FILES,
+} from "../wave-orchestrator/planner-context.mjs";
+
+function ensureDirectory(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+function sha256Text(text) {
+  return crypto.createHash("sha256").update(text, "utf8").digest("hex");
+}
+
+function extractFrontmatterValue(text, key) {
+  const match = String(text || "").match(new RegExp(`^${key}:\\s*['"]?(.+?)['"]?$`, "m"));
+  return match ? match[1].trim() : "";
+}
+
+function extractMarkdownHeading(text) {
+  const match = String(text || "").match(/^#\s+(.+)$/m);
+  return match ? match[1].trim() : "";
+}
+
+function renderPlannerTopicIndex(copiedFiles) {
+  const paperLines = copiedFiles
+    .filter((entry) => entry.kind === "paper")
+    .map((file) => {
+      return `- [${file.title || file.targetPath.split("/").pop()}](../papers/${path.basename(file.targetPath)})`;
+    });
+  return [
+    "---",
+    "summary: 'Curated planning and orchestration corpus exported for the agentic planner Context7 bundle.'",
+    "read_when:",
+    "  - You are publishing or refreshing the planner-agentic Context7 library",
+    "  - You need the exact planner research subset that Wave ships for agentic planning",
+    "title: 'Planner Agentic Context7 Corpus'",
+    "---",
+    "",
+    "# Planner Agentic Context7 Corpus",
+    "",
+    "This file is the tracked topic index for the planner-specific Context7 corpus.",
+    "It intentionally references only the copied files that ship under",
+    "`docs/context7/planner-agent/`.",
+    "",
+    "## Included papers",
+    "",
+    ...paperLines,
+    "",
+  ].join("\n");
+}
+
+function writePlannerContextFile(targetPath, text) {
+  ensureDirectory(path.dirname(targetPath));
+  fs.writeFileSync(targetPath, text, "utf8");
+  return {
+    bytes: Buffer.byteLength(text, "utf8"),
+    sha256: sha256Text(text),
+  };
+}
+
+function copyPlannerContextFile(entry, copiedFiles) {
+  const sourcePath = path.join(PACKAGE_ROOT, entry.sourcePath);
+  const targetPath = path.join(PACKAGE_ROOT, entry.targetPath);
+  if (!fs.existsSync(sourcePath)) {
+    throw new Error(`Planner Context7 source file is missing: ${entry.sourcePath}`);
+  }
+  ensureDirectory(path.dirname(targetPath));
+  const text = fs.readFileSync(sourcePath, "utf8");
+  const written =
+    entry.kind === "topic"
+      ? writePlannerContextFile(
+          targetPath,
+          renderPlannerTopicIndex(copiedFiles),
+        )
+      : writePlannerContextFile(targetPath, text);
+  return {
+    kind: entry.kind,
+    sourcePath: entry.sourcePath,
+    targetPath: entry.targetPath,
+    title:
+      entry.kind === "topic"
+        ? "Planner Agentic Context7 Corpus"
+        : extractFrontmatterValue(text, "title") || extractMarkdownHeading(text) || path.basename(entry.targetPath),
+    ...written,
+  };
+}
+
+function writeManifest(files) {
+  const manifestPath = path.join(PACKAGE_ROOT, PLANNER_CONTEXT7_SOURCE_DIR, "manifest.json");
+  ensureDirectory(path.dirname(manifestPath));
+  fs.writeFileSync(
+    manifestPath,
+    `${JSON.stringify(
+      {
+        version: 1,
+        generatedAt: new Date().toISOString(),
+        bundleId: PLANNER_CONTEXT7_BUNDLE_ID,
+        libraryName: PLANNER_CONTEXT7_LIBRARY_NAME,
+        defaultQuery: PLANNER_CONTEXT7_DEFAULT_QUERY,
+        sourceRoot: "docs/research/agent-context-cache",
+        targetRoot: PLANNER_CONTEXT7_SOURCE_DIR,
+        files,
+      },
+      null,
+      2,
+    )}\n`,
+    "utf8",
+  );
+}
+
+function main() {
+  const files = [];
+  const orderedEntries = [
+    ...PLANNER_CONTEXT7_SOURCE_FILES.filter((entry) => entry.kind !== "topic"),
+    ...PLANNER_CONTEXT7_SOURCE_FILES.filter((entry) => entry.kind === "topic"),
+  ];
+  for (const entry of orderedEntries) {
+    files.push(copyPlannerContextFile(entry, files));
+  }
+  writeManifest(files);
+  console.log(
+    `[planner-context7] synced ${files.length} files into ${PLANNER_CONTEXT7_SOURCE_DIR}`,
+  );
+}
+
+main();