@chllming/wave-orchestration 0.5.1

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

@@ -0,0 +1,43 @@
+---
+title: "Wave Evaluator Role"
+summary: "Standing prompt for the running evaluator that gates a wave through architecture, proof, and documentation closure."
+---
+
+# Wave Evaluator Role
+
+Use this prompt when an agent should act as the running evaluator for a wave.
+
+## Standing prompt
+
+```text
+You are the running evaluator 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.
+
+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.
+- 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
+- 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
+
+Verdict contract:
+- End the evaluator 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.
+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-infra-role.md

@@ -0,0 +1,34 @@
+---
+title: "Wave Infra Role"
+summary: "Standing prompt for an infra-focused wave agent that proves machine, identity, admission, or environment state."
+---
+
+# Wave Infra Role
+
+Use this prompt when an agent should own infra or environment proof for a wave.
+
+## Standing prompt
+
+```text
+You are the infra-focused agent for the current wave.
+
+Your job is to verify and, when explicitly assigned, implement the machine, identity, admission, dependency, or environment work needed for the wave. You are responsible for making infra state explicit instead of leaving it buried in shell output.
+
+Operating rules:
+- Re-read the compiled shared summary, your inbox, and the generated wave board projection before major decisions, before validation, and before final output.
+- Prefer explicit infra proof over vague notes like "looks good" or "seems configured".
+- Treat machine conformance, workload identity, service dependencies, node admission, and approved machine actions as first-class deliverables.
+- Keep repository guidance and lane safety rules authoritative. Do not improvise destructive machine changes.
+
+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
+- 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>`
+
+Use `conformant` only when the required infra proof is actually present.
+If the work is still waiting on a safe same-wave setup step, use `setup-required` or `setup-in-progress` instead of pretending the wave is blocked forever.
+Use `blocked`, `drift`, or `failed` only when the wave genuinely cannot claim that infra surface as healthy.
+```

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

@@ -0,0 +1,32 @@
+---
+title: "Wave Integration Role"
+summary: "Standing prompt for the integration steward that reconciles cross-agent state before documentation and evaluator closure."
+---
+
+# Wave Integration Role
+
+Use this prompt when an agent should act as the integration steward for a wave.
+
+## Standing prompt
+
+```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.
+
+Operating rules:
+- Re-read the generated wave inboxes and coordination board projection before major decisions.
+- Treat contradictions, unresolved blockers, interface drift, and unowned follow-up work as first-class integration failures.
+- Prefer explicit follow-up requests over vague warnings.
+- Keep the integration summary machine-readable and short enough to drive relaunch decisions.
+
+What you must do:
+- identify open claims that are still unsupported
+- identify conflicting claims or incompatible interface assumptions
+- identify unresolved blockers and cross-component impacts
+- identify proof gaps, doc gaps, and deploy or release risks that still block closure
+- 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.
+```

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

@@ -0,0 +1,37 @@
+---
+title: "Wave Launcher Role"
+summary: "Standing prompt for the operator that runs waves through the orchestrator."
+---
+
+# Wave Launcher Role
+
+Use this prompt when an agent or human operator should launch waves through the orchestrator.
+
+## Standing prompt
+
+```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.
+
+Before launching:
+1. Run `pnpm exec wave doctor`.
+2. Run `pnpm exec wave launch --lane main --dry-run --no-dashboard`.
+3. Run `pnpm exec wave coord show --lane main --wave 0 --dry-run --json` and `pnpm exec wave coord inbox --lane main --wave 0 --agent A1 --dry-run` when you need to inspect seeded state.
+4. Run `pnpm exec wave launch --lane main --reconcile-status`.
+5. Run `pnpm exec wave feedback list --lane main --pending`.
+6. Inspect `.tmp/main-wave-launcher/` state and dashboards when relevant.
+
+Completion requires:
+- all agents exit `0`
+- integration must be `ready-for-doc-closure` before documentation and evaluator closure run
+- evaluator 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
+- runtime mix targets and retry fallbacks remain within lane policy
+- live attempts write a hermetic `traceVersion: 2` trace bundle with `run-metadata.json`, `quality.json`, structured signals, copied launched-agent summaries, and recorded artifact hashes
+
+Dry-run rule:
+- `wave launch --dry-run` is pre-attempt only. It should seed derived state and leave `traces/` without `attempt-<k>` files.
+```

package/docs/context7/bundles.json

@@ -0,0 +1,91 @@
+{
+  "version": 1,
+  "defaultBundle": "none",
+  "laneDefaults": {
+    "main": "none"
+  },
+  "bundles": {
+    "none": {
+      "description": "Disable Context7 prefetch for this run.",
+      "libraries": []
+    },
+    "node-typescript": {
+      "description": "Node.js and TypeScript runtime docs for JavaScript service and tooling work.",
+      "libraries": [
+        {
+          "libraryName": "nodejs",
+          "queryHint": "runtime APIs, child processes, streams, filesystem behavior, and process lifecycle"
+        },
+        {
+          "libraryName": "typescript",
+          "queryHint": "types, declarations, module resolution, tsconfig, and compiler behavior"
+        }
+      ]
+    },
+    "react-web": {
+      "description": "React and Next.js docs for frontend work.",
+      "libraries": [
+        {
+          "libraryName": "react",
+          "queryHint": "components, hooks, rendering, forms, and data flow"
+        },
+        {
+          "libraryName": "nextjs",
+          "queryHint": "routing, server components, data fetching, and app router behavior"
+        }
+      ]
+    },
+    "python-services": {
+      "description": "Python backend docs for API and worker services.",
+      "libraries": [
+        {
+          "libraryName": "python",
+          "queryHint": "language features, packaging, typing, and standard library behavior"
+        },
+        {
+          "libraryName": "fastapi",
+          "queryHint": "routing, request validation, dependency injection, and OpenAPI behavior"
+        }
+      ]
+    },
+    "go-services": {
+      "description": "Go service and workflow docs for backend work.",
+      "libraries": [
+        {
+          "libraryName": "golang",
+          "queryHint": "packages, testing, concurrency, errors, and module layout"
+        },
+        {
+          "libraryName": "temporal",
+          "queryHint": "workflow setup, activities, schedules, retries, and worker bootstrap"
+        }
+      ]
+    },
+    "persistence": {
+      "description": "Database and storage docs for persistence work.",
+      "libraries": [
+        {
+          "libraryName": "postgresql",
+          "queryHint": "schema changes, indexes, transactions, constraints, and query behavior"
+        },
+        {
+          "libraryName": "sqlite",
+          "queryHint": "local persistence, fts, schema migration, and durability patterns"
+        }
+      ]
+    },
+    "infra-ops": {
+      "description": "Infrastructure and service-manager docs for deployment and operations work.",
+      "libraries": [
+        {
+          "libraryName": "docker",
+          "queryHint": "images, builds, volumes, networking, and runtime configuration"
+        },
+        {
+          "libraryName": "systemd",
+          "queryHint": "units, dependencies, restart policies, readiness, and service management"
+        }
+      ]
+    }
+  }
+}

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

@@ -0,0 +1,112 @@
+{
+  "version": 1,
+  "levels": [
+    "inventoried",
+    "contract-frozen",
+    "repo-landed",
+    "baseline-proved",
+    "pilot-live",
+    "qa-proved",
+    "fleet-ready",
+    "cutover-ready",
+    "deprecation-ready"
+  ],
+  "components": {
+    "wave-parser-and-launcher": {
+      "title": "Wave parser and launcher",
+      "canonicalDocs": [
+        "README.md",
+        "docs/plans/wave-orchestrator.md"
+      ],
+      "currentLevel": "repo-landed",
+      "promotions": [
+        {
+          "wave": 0,
+          "target": "repo-landed"
+        }
+      ],
+      "proofSurfaces": [
+        "wave parsing",
+        "launcher dry-run",
+        "wave parser tests"
+      ]
+    },
+    "executor-abstraction-and-prompt-transport": {
+      "title": "Executor abstraction and prompt transport",
+      "canonicalDocs": [
+        "README.md",
+        "docs/plans/context7-wave-orchestrator.md"
+      ],
+      "currentLevel": "repo-landed",
+      "promotions": [],
+      "proofSurfaces": [
+        "executor launch specs",
+        "runtime overlays",
+        "executor tests"
+      ]
+    },
+    "closure-sweep-and-role-gates": {
+      "title": "Closure sweep and role gates",
+      "canonicalDocs": [
+        "docs/plans/wave-orchestrator.md",
+        "docs/agents/wave-evaluator-role.md",
+        "docs/agents/wave-documentation-role.md"
+      ],
+      "currentLevel": "repo-landed",
+      "promotions": [],
+      "proofSurfaces": [
+        "structured gate markers",
+        "closure sweep",
+        "launcher tests"
+      ]
+    },
+    "context7-scope-and-prefetch": {
+      "title": "Context7 scope and prefetch",
+      "canonicalDocs": [
+        "docs/plans/context7-wave-orchestrator.md",
+        "docs/context7/bundles.json"
+      ],
+      "currentLevel": "repo-landed",
+      "promotions": [],
+      "proofSurfaces": [
+        "bundle resolution",
+        "prefetch cache",
+        "prompt injection"
+      ]
+    },
+    "state-artifacts-and-feedback": {
+      "title": "State artifacts and feedback",
+      "canonicalDocs": [
+        "docs/plans/wave-orchestrator.md",
+        "docs/plans/current-state.md"
+      ],
+      "currentLevel": "repo-landed",
+      "promotions": [],
+      "proofSurfaces": [
+        "status summaries",
+        "dashboards",
+        "feedback queue"
+      ]
+    },
+    "starter-docs-and-adoption-guidance": {
+      "title": "Starter docs and adoption guidance",
+      "canonicalDocs": [
+        "README.md",
+        "docs/plans/master-plan.md",
+        "docs/plans/migration.md"
+      ],
+      "currentLevel": "repo-landed",
+      "promotions": [
+        {
+          "wave": 0,
+          "target": "repo-landed"
+        }
+      ],
+      "proofSurfaces": [
+        "starter wave docs",
+        "adoption guidance",
+        "shared-plan closure"
+      ]
+    }
+  }
+}

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

@@ -0,0 +1,49 @@
+# Component Cutover Matrix
+
+This matrix is the canonical place to answer which harness components are expected to be working at which maturity level.
+
+The starter entries reflect the snapshot shipped in this repository. Replace the component catalog and promotion map when you adapt the harness to a real product repo.
+
+## Levels
+
+- `inventoried`
+- `contract-frozen`
+- `repo-landed`
+- `baseline-proved`
+- `pilot-live`
+- `qa-proved`
+- `fleet-ready`
+- `cutover-ready`
+- `deprecation-ready`
+
+## Components
+
+- `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
+- `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
+
+## Current Starter Levels
+
+| Component | Current level | Proof surfaces |
+| --- | --- | --- |
+| `wave-parser-and-launcher` | `repo-landed` | wave parsing, launcher dry-run, wave parser tests |
+| `executor-abstraction-and-prompt-transport` | `repo-landed` | executor launch specs, runtime overlays, executor tests |
+| `closure-sweep-and-role-gates` | `repo-landed` | structured gate markers, closure sweep, launcher tests |
+| `context7-scope-and-prefetch` | `repo-landed` | bundle resolution, prefetch cache, prompt injection |
+| `state-artifacts-and-feedback` | `repo-landed` | status summaries, dashboards, feedback queue |
+| `starter-docs-and-adoption-guidance` | `repo-landed` | starter wave docs, adoption guidance, shared-plan closure |
+
+## Starter Wave Promotions
+
+- Wave 0 promotes `wave-parser-and-launcher` to `repo-landed`.
+- Wave 0 promotes `starter-docs-and-adoption-guidance` to `repo-landed`.
+
+## Usage
+
+- Keep architecture and repository guidance docs descriptive.
+- Keep wave-by-wave component maturity and promotion targets here.
+- `currentLevel` is the canonical post-wave state of the repo, not a future plan. When a wave promotes a component, update `currentLevel` to the promoted target before closure.
+- When component promotion gating is active, wave files must match this matrix exactly.

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

@@ -0,0 +1,130 @@
+# Context7 and Wave Orchestrator
+
+Context7 is for external library truth. Repository docs and source are for repository truth.
+
+## Rules
+
+- Prefer a narrow bundle per agent or wave.
+- Keep bundle defaults and agent overrides aligned with the components the wave is promoting.
+- Do not load broad external docs by default.
+- Treat prefetched Context7 text as non-canonical prompt context.
+- Keep Context7 bundle definitions in `docs/context7/bundles.json`.
+- Launcher-side prefetch writes only to ignored cache paths under `.tmp/`.
+
+## Setup
+
+1. Add `CONTEXT7_API_KEY` to `.env.local` at repo root.
+2. Export it before launching the wave runner or any executor directly:
+
+```bash
+source scripts/context7-export-env.sh
+```
+
+3. Verify the key:
+
+```bash
+pnpm context7:api-check
+```
+
+4. Review [docs/context7/bundles.json](../context7/bundles.json) and trim it to the external libraries your repository actually uses.
+
+## Resolution Order
+
+1. Agent `### Context7`
+2. Wave `## Context7 defaults`
+3. Lane default from `docs/context7/bundles.json`
+4. `none`
+
+## Bundle Authoring
+
+Each bundle should be small and task-shaped. A bundle entry can name libraries by `libraryName` and optionally add a `queryHint` to keep fetched docs focused.
+
+Example:
+
+```json
+{
+  "bundles": {
+    "node-typescript": {
+      "description": "Node.js and TypeScript runtime docs.",
+      "libraries": [
+        {
+          "libraryName": "nodejs",
+          "queryHint": "child processes, streams, filesystem, process lifecycle"
+        },
+        {
+          "libraryName": "typescript",
+          "queryHint": "module resolution, declarations, compiler behavior"
+        }
+      ]
+    }
+  }
+}
+```
+
+Keep the `none` bundle defined so agents and waves can opt out explicitly.
+
+## Wave Authoring
+
+Wave-level default:
+
+````md
+## Context7 defaults
+
+- bundle: node-typescript
+- query: "Node process spawning and test execution"
+````
+
+Agent-level override:
+
+````md
+### Context7
+
+- bundle: node-typescript
+- query: "TypeScript declarations and module resolution"
+````
+
+## Injection
+
+When a bundle is active, the launcher injects:
+
+- the resolved bundle id
+- the resolved query focus
+- the allowed library list
+- prefetched third-party snippets when available
+
+The injected block appears before the assigned implementation prompt and is labeled non-canonical. This injection is executor-agnostic.
+
+Wave coordination state is injected separately from Context7:
+
+- a compiled shared summary from `.tmp/<lane>-wave-launcher/inboxes/wave-<n>/shared-summary.md`
+- a compiled per-agent inbox from `.tmp/<lane>-wave-launcher/inboxes/wave-<n>/<agent-id>.md`
+
+Those inbox artifacts are repository-state summaries. Context7 stays reserved for third-party library truth.
+
+## Runtime Behavior
+
+- Prefetch happens in the launcher before the agent session starts.
+- Shared summary and per-agent inbox compilation also happen in the launcher before the executor is invoked.
+- Cache files are written under `.tmp/<lane>-wave-launcher/context7-cache/`.
+- Compiled inboxes are written under `.tmp/<lane>-wave-launcher/inboxes/`.
+- Executor runtime overlays are written under `.tmp/<lane>-wave-launcher/executors/`.
+- The resolved Context7 selection becomes part of the prompt fingerprint, so changing bundle or query invalidates prior success reuse.
+- If `CONTEXT7_API_KEY` is missing, prefetch is disabled with a warning and the wave continues.
+- If the Context7 API errors, the launcher fails open and starts the agent without the injected snippets.
+- Use `--no-context7` when you want to force repository-only context for a run.
+
+## Prompt Layering
+
+- `codex`
+  The generated task prompt already contains the compiled shared summary, the compiled agent inbox, and the injected Context7 block. It is piped directly into `codex exec`.
+- `claude`
+  The generated task prompt contains the compiled shared summary, the compiled agent inbox, and the injected Context7 block. The harness also writes a runtime system-prompt overlay and passes it with `--append-system-prompt-file` by default, or `--system-prompt-file` if `executors.claude.appendSystemPromptMode` is set to `replace`.
+- `opencode`
+  The generated task prompt contains the compiled shared summary, the compiled agent inbox, and the injected Context7 block. The harness writes a temporary `opencode.json` plus an agent prompt file under `.tmp/.../executors/`, points `OPENCODE_CONFIG` at that overlay, and launches `opencode run`.
+
+## Guidance
+
+- Use Context7 for external library truth, setup syntax, SDK details, and version-specific API behavior.
+- Do not use Context7 for repository architecture, plan decisions, ownership rules, or internal contracts.
+- Prefer one active backend family in a bundle instead of mixing competing frameworks.
+- Keep queries specific enough that the prefetched block stays small and useful.

package/docs/plans/current-state.md

@@ -0,0 +1,44 @@
+# Current State
+
+- 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`.
+- The harness supports `codex`, `claude`, `opencode`, and `local` executors.
+- The runtime now includes:
+  - a canonical coordination JSONL log
+  - a generated markdown board projection
+  - compiled shared summaries and per-agent inboxes
+  - a per-wave ledger
+  - docs queues
+  - explicit integration summaries with actionable claim, interface, proof, docs, and deploy-risk 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
+- 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
+  - dry-run prompt and executor-preview materialization under `.tmp/<lane>-wave-launcher/dry-run/`
+- 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
+  - executor profiles
+  - hard runtime mix targets
+  - retry-time fallback order
+  - generic runtime budgets
+- 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.
+- 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:
+  - `wave dep post|show|resolve|render`
+  - per-wave inbound/outbound dependency snapshots under `.tmp/<lane>-wave-launcher/dependencies/`
+  - dependency-aware gating, inboxes, dashboards, and replay artifacts
+- Dry-run remains pre-attempt only: it seeds derived state under `.tmp/<lane>-wave-launcher/dry-run/` and leaves `traces/` file-empty.
+- Component maturity and starter wave promotions are tracked in `docs/plans/component-cutover-matrix.md` and `docs/plans/component-cutover-matrix.json`.
+- Context7 bundle selection and launcher-side prompt injection are enabled through `docs/context7/bundles.json`.
+- Research source links are committed in `docs/research/agent-context-sources.md`; hydrated caches stay local and ignored.

package/docs/plans/master-plan.md

@@ -0,0 +1,16 @@
+# Master Plan
+
+## Goals
+
+- Keep the orchestrator generic enough to reuse across repositories.
+- Preserve the working runtime features from the original implementation.
+- Keep repo-specific policy in config and docs, not in engine code.
+- Keep external-doc use narrow, explicit, and non-canonical.
+
+## Near-Term Work
+
+- Keep the starter wave, role prompts, and component cutover matrix aligned with the shipped launcher behavior.
+- Expand `wave doctor` and migration guidance around cross-repo adoption, executor availability, and future breaking config changes.
+- Add richer starter templates for additional repository shapes after the generic single-repo path is stable.
+- Extend replay and trace tooling from internal helpers and file-backed artifacts into easier operator workflows, larger historical fixtures, and a public replay surface if it proves stable.
+- Add the remaining roadmap items that are not yet shipped, especially richer capability routing and better operator workflows around cross-lane dependency tickets.

package/docs/plans/migration.md

@@ -0,0 +1,23 @@
+# Migration
+
+## Default Adoption Path
+
+1. Install from the current GitHub Packages path as described in [github-packages-setup.md](../reference/github-packages-setup.md).
+2. Install the package with `pnpm add -D @chllming/wave-orchestration`.
+3. For a fresh repo, run `pnpm exec wave init`.
+4. For a repo that already has Wave config, docs, or waves you want to preserve, run `pnpm exec wave init --adopt-existing`.
+5. Edit `wave.config.json` for the repo's docs, roles, validation rules, executor defaults, and component-cutover matrix paths.
+6. Replace the starter plan docs, sample waves, and component cutover matrix with repository-specific ones.
+7. Configure Context7 bundles for the external libraries that repo actually uses.
+8. Run `pnpm exec wave doctor` and `pnpm exec wave launch --lane main --dry-run --no-dashboard` until validation passes.
+9. Inspect seeded coordination and inbox artifacts with `pnpm exec wave coord show --lane main --wave 0 --dry-run --json` and `pnpm exec wave coord inbox --lane main --wave 0 --agent A1 --dry-run`.
+10. Upgrade later with `pnpm up @chllming/wave-orchestration` and `pnpm exec wave upgrade`.
+
+`wave-orchestration` also ships an npmjs trusted-publishing workflow for future zero-token installs, but that path is only active after the first npmjs release is published from this repo. Maintainer setup is documented in [npmjs-trusted-publishing.md](../reference/npmjs-trusted-publishing.md).
+
+## Upgrade Contract
+
+- Package upgrades change the runtime behavior in `node_modules`; they do not copy a new starter scaffold into the repo.
+- `wave upgrade` writes `.wave/install-state.json` and `.wave/upgrade-history/*` only.
+- Existing `wave.config.json`, role prompts, plan docs, Context7 bundles, and wave files are never overwritten by the upgrade flow.
+- The current runtime expects the post-roadmap model: typed coordination, compiled inboxes, `A8` integration, staged closure, orchestrator-first clarification, and operational runtime policy.