@open-agent-toolkit/cli 0.1.76 → 0.2.0

package/assets/docs/cli-utilities/tool-packs.md

@@ -17,7 +17,7 @@ This page covers CLI commands that manage bundled OAT tool packs and installed O
 
 - `core` - foundational diagnostics and docs access (`oat-doctor`, `oat-docs`)
 - `docs` - docs and agent-instructions governance workflows
-- `workflows` - project lifecycle skills, the project subagent-dispatch adapter, wrap-up reporting, reviewer agents, and core project templates
+- `workflows` - project lifecycle skills, wave-program orchestration (`oat-wave-program`, `oat-wave-execute`), the project subagent-dispatch adapter, wrap-up reporting, reviewer agents, and core project templates
 - `ideas` - lightweight ideation and promotion flows
 - `utility` - review and repo-maintenance helpers plus the provider-neutral subagent-dispatch engine
 - `project-management` - file-backed backlog/reference skills plus backlog, roadmap, current-state, file-per-record decision, and AGENTS-guide templates

package/assets/docs/workflows/index.md

@@ -13,6 +13,7 @@ Use this section when you want explicit project artifacts, stable task IDs, revi
 
 - [Ideas Workflow](ideas/index.md) - Lightweight idea capture, brainstorming, and promotion into tracked projects when the work becomes concrete.
 - [Workflow & Projects](projects/index.md) - Lifecycle, artifacts, reviews, PR flow, and repository analysis.
+- [Wave Workflows](wave-workflows.md) - Program-level coordination for executing a corpus of external plans as ordered wrapper projects.
 - [Skills](skills/index.md) - Workflow-oriented skill discovery and use-case routing.
 
 ## What This Section Is

package/assets/docs/workflows/skills/index.md

@@ -27,6 +27,7 @@ Use this section when you want to choose the right OAT skill for a task. If you
 - Turn a repo audit, maintainability review, backlog review, backlog directory, or backlog item into standalone external implementation plans: `oat-repo-improve`. Plans land under `.oat/repo/reference/external-plans/`; execute them directly or optionally pass one to `oat-project-import-plan` for tracked OAT execution.
 - Work on docs surfaces: `authoring-docs` (general documentation baseline), `oat-docs-authoring` (targeted OAT/Fumadocs authoring), `oat-docs-bootstrap` (guided bootstrap of a new docs app), `oat-docs-analyze`, `oat-docs-apply`, and `oat-project-document`
 - Generate a shipping digest or scheduled recap: `oat-wrap-up`
+- Run a wave program over a corpus of external plans: `oat-wave-program` (durable program artifact: new/refresh/wave-close) and `oat-wave-execute` (one wave as a wrapper project) — see [Wave Workflows](../wave-workflows.md)
 - Research a topic in depth: `deep-research`
 - Analyze an artifact, codebase, or document: `analyze`
 - Compare options with domain-aware dimensions: `compare`
@@ -71,6 +72,8 @@ Use this section when you want to choose the right OAT skill for a task. If you
     - `oat-project-document`
     - `oat-wrap-up`
     - `oat-project-complete`
+    - `oat-wave-program`
+    - `oat-wave-execute`
 
 === "Ideas"
 

package/assets/docs/workflows/wave-workflows.md

@@ -0,0 +1,77 @@
+---
+title: Wave Workflows
+description: How OAT coordinates a corpus of external plans into waves while preserving project-lifecycle ownership and human judgment.
+---
+
+# Wave Workflows
+
+A wave is a program layer above the per-project OAT lifecycle. It groups external implementation plans into an ordered delivery unit, then runs that unit as a wrapper OAT project. The wrapper uses the normal project lifecycle rather than replacing it.
+
+Use wave workflows when a plan corpus is too large to execute as one project and needs durable sequencing across multiple projects, worktree groups, and merges.
+
+## The Two Wave Skills
+
+The workflow pack provides two complementary skills:
+
+- `oat-wave-program` 1.1.0 maintains the durable execution-program artifact over the full plan corpus. Its `new` mode inventories the corpus, verifies the coverage invariant, and records the orchestrator-composed, operator-approved first program; `refresh` adds newly landed plans to the artifact and records the orchestrator's re-composition of waves not yet started; and `wave-close` records a completed wave. Composing waves is the orchestrating agent's judgment; the skill records the result.
+- `oat-wave-execute` 1.5.0 runs one wave. It owns the repeatable mechanical layer: wrapper-project scaffolding, branch conventions, worktree bootstrap, briefs, gates, merge choreography, bookkeeping cadence, and closeout order.
+
+`oat-wave-program` records which plans belong to each wave. `oat-wave-execute` consumes that mapping and executes one wave through the project lifecycle.
+
+## Mechanical Work and Judgment
+
+The ownership split is load-bearing. The skills automate mechanics, but the orchestrator retains judgment.
+
+The skills own:
+
+- integration and phase branch naming
+- wrapper-project scaffolding
+- worktree bootstrap
+- merge choreography
+- artifact and ledger bookkeeping
+- repeatable verification and closeout sequencing
+
+The orchestrator owns:
+
+- wave and parallel-group composition
+- review-finding dispositions
+- verification of load-bearing worker claims
+- merge-order decisions under live drift
+- cross-lane and end-of-run synthesis
+- all user checkpoints
+
+Do not treat a generated grouping or a mechanically successful lane as a substitute for these decisions.
+
+## Composition With Project Implementation
+
+Each wave is scaffolded as a quick-mode wrapper project. Its plan points to the source plans while preserving their requirements, and `oat-project-implement` remains the lifecycle owner for phase execution, independent review, bounded fixes, checkpoints, and project state.
+
+For plan-declared parallel groups, `oat-wave-execute` invokes its bundled `scripts/bootstrap-group.sh` helper. The helper wraps the standard worktree bootstrap flow, creates phase worktrees at an explicit base, initializes each worktree, checks provider-view parity, and reports structured status. `oat-project-implement` then dispatches and verifies each phase in its assigned worktree. The wave layer owns the serialized fan-in and integration gates after those phases pass.
+
+This composition keeps the responsibilities separate:
+
+1. `oat-wave-program` records the program and wave membership.
+2. `oat-wave-execute` scaffolds and coordinates one wrapper project.
+3. `oat-project-implement` executes that project's phases.
+4. `oat-wave-program wave-close` updates the durable program after the wave merges.
+
+## Execution-Program Artifact Format
+
+The execution-program artifact is durable reference material under `.oat/repo/reference/external-plans/`. It is not an executable plan or an `oat-project-import-plan` target.
+
+The current format contains:
+
+- **Wave table:** one row per source plan, including its link, source index, assigned wave, ordering or dependency notes, and status (`pending`, `in-wave`, `done`, `deferred`, or `dropped`).
+- **Coverage invariant:** every plan in every source plan index appears in exactly one row. A deferred or dropped plan includes a reason and re-entry trigger; an omitted plan is an error.
+- **Wave sections:** the theme, lane list, intra-wave ordering, and cross-wave prerequisites for each wave.
+- **Status ledger:** each wave advances from composed to in-progress to merged, with the wrapper-project link, PR, merge SHA, and completion-record link recorded as they become available.
+
+> **Important:** This format is documented as a description, not a stable contract. Contract work is deferred in **BL-260718-document-execution-program — Document execution-program artifact as stable OAT contract**, grouped with **BL-260718-add-oat-wave-lifecycle-cli — Add oat wave lifecycle CLI command family**.
+
+Until that grouped work ships, consumers should follow the bundled skill and template rather than depending on an independently versioned schema.
+
+## Related
+
+- [Project lifecycle](projects/lifecycle.md)
+- [Implementation execution](projects/implementation-execution.md)
+- [Project artifacts](projects/artifacts.md)

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.1.76",
-  "docs-config": "0.1.76",
-  "docs-theme": "0.1.76",
-  "docs-transforms": "0.1.76"
+  "cli": "0.2.0",
+  "docs-config": "0.2.0",
+  "docs-theme": "0.2.0",
+  "docs-transforms": "0.2.0"
 }

package/assets/skills/oat-wave-execute/SKILL.md

@@ -0,0 +1,317 @@
+---
+name: oat-wave-execute
+version: 1.5.0
+description: Use when executing a wave of external implementation plans as a wrapper OAT project — scaffolding, drift refresh, parallel worktree groups, briefs, gates, merge choreography, and closeout.
+argument-hint: '<wave-id> [plan-names...] (e.g. wave-2 http-listener-before-indexing ...)'
+disable-model-invocation: false
+user-invocable: true
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob, Task
+---
+
+# Execute a Wave of External Plans
+
+Run one **wave** of the external-plan program as a wrapper OAT project. This skill
+owns the **mechanical layer** — everything that waves 0–1 proved stable and that
+hand-re-derivation repeatedly broke. It deliberately does NOT own judgment.
+
+Provenance: extracted per `DR-260713-extract-oat-wave-execute` after the source
+program's waves 0–1 and hardened across its waves 2–5.
+
+Log every friction/deviation to the project's `orchestration-log.md` so later
+waves inherit evidence, not anecdotes.
+
+Historical `DR-*` and `BL-*` slugs in this skill (including the provenance
+record above) are evidence citations in the source program's repository; they
+are not required artifacts in the consuming repo.
+
+## Ownership Boundary
+
+**This skill owns (mechanical):** integration/phase branch naming, worktree
+bootstrap, wave-boundary drift refresh, wrapper-project scaffold (from the bundled
+templates), brief templates, gate-prompt template + scaling, merge choreography,
+bookkeeping cadence, closeout sequence.
+
+**The orchestrator owns (judgment — never delegate to this skill or to workers):**
+parallel-group composition from live recon evidence, review-finding dispositions,
+verification of load-bearing worker claims, merge-order decisions under live drift,
+cross-lane synthesis, the end-of-run synthesis, and all user checkpoints.
+
+## Standing Rules (violations caused every wave-1 incident)
+
+1. **Branch naming:** integration branch `wave-N-execution`; phase branches
+   `wave-N/pNN`. Phase branches MUST NOT nest under the integration branch name
+   (git refs cannot be both leaf and directory).
+2. **Merge commits use a conventional type:** `chore(pNN): merge wave-N/pNN — <lane> (review passed)`.
+   Bare `merge(...)` fails commitlint. Keep headers ≤ 100 chars.
+3. **Clean orchestrator tree before group merges** — a dirty unrelated file leaves
+   `git merge --no-ff` uncommitted and drags the full hook chain into recovery.
+   Gate reviewers now COMMIT their own artifacts (waves 2–3 evidence): keep the
+   tree clean around gate runs and expect a gate-authored commit on return.
+4. **Pre-declare CUMULATIVE churn in every brief:** declarations cover everything
+   landed since each source plan's AUTHORED COMMIT (drift checks compare against
+   that commit, not the group base), naming files + rough regions. Zero false
+   drift-STOPs across 32 consecutive briefed lanes through wave 4
+   (DR-260715-cumulative-churn-manifests).
+5. **Resolve full SHAs with `git rev-parse`** — never hand-expand short SHAs.
+6. **Gate scope must fit the timeout:** bound wrapper-plan gate reviewers to the
+   wrapper artifacts + the drift-refresh record (not all N source plans), or raise
+   the gate timeout. On a gate timeout, check the project `reviews/` directory for
+   a completed artifact carrying the gate `runId` BEFORE re-running. For larger
+   waves (~6+ lanes), prefer per-phase gates over one monolithic final gate; if a
+   final gate must cover the whole wave, scope its prompt to the integration
+   diff plus the review-chain artifacts, not a re-review of every lane.
+7. **Guard every formatter-ignored-file × staged-glob interaction:** a
+   single-glob staged-file task can fail when every matched file is ignored by
+   the repo's formatter. Audit every glob task and pair canonical-file
+   exclusions with the staged-task's matching ignore filter (source-program
+   example: oxfmt exited non-zero for ignored `*.md`/`*.json`, requiring both
+   `.oxfmtrc.json` `ignorePatterns` and `.lintstagedrc.mjs` filtering).
+8. **Gate timeout diagnostics** (the upstream stdin-hang fix landed in oat
+   0.1.65 — gate children now get `stdin: 'ignore'`; the historical
+   `< /dev/null` workaround is retired and harmless if still present):
+   timeout + ZERO output bytes = launch defect (do not spend remediation
+   attempts re-running unchanged); timeout + a complete artifact = late
+   completion (recover the artifact by `runId` per rule 6). Verify the CLI is
+   ≥0.1.65 (`oat --version`) before dropping the workaround on a new host.
+9. **Verified bookkeeping edits** (`DR-260713-bookkeeping-table-mutations`):
+   never mutate plan/implementation status tables with exact-string replacement —
+   oxfmt re-padding makes it silently no-op. Use anchored regex + a substitution
+   count assertion + a post-state grep, every time. This discipline caught its
+   own subsequent no-ops twice in wave 2; treat an assert failure as normal
+   operation, not an incident.
+10. **Integration gates after every fan-in:** they are the only detector for
+    cumulative-timing defect classes. Never skip them because every lane passed
+    independently; the wave-5 embed-teardown defect was caught only after fan-in.
+
+Plus inherited invariants: commit-verification via `git log` before retrying after
+any ambiguous hook outcome; every agent runs the repo's formatter on markdown it
+writes; follow the repo's runtime/environment setup before package commands;
+repair native-dependency ABI mismatches using the repo's documented rebuild
+procedure; rebuild edited workspace-package output before running consumer tests
+(stale output mimics real failures). Source-program examples were `pnpm
+format:fix`, `nvm use`, and `pnpm rebuild -r better-sqlite3` on
+`NODE_MODULE_VERSION` errors.
+
+## Inputs
+
+- `<wave-id>` — e.g. `wave-2`. Derives project `wave-N-execution`, branches per
+  rule 1.
+- Lane list: resolve from the live execution-program artifact
+  (`.oat/repo/reference/external-plans/*-execution-program.md`, owned by
+  `oat-wave-program`); fall back to the plan indexes' wave hints only when no
+  program artifact exists. Verify every named plan file exists before
+  scaffolding; a missing file is a STOP (report, don't guess).
+- Concurrency ceiling: default **3** worktrees (operator-set; revisit per wave).
+
+## Process
+
+### Step 1: Preflight
+
+1. From the repo root on up-to-date `main`: `git checkout -b wave-N-execution`.
+2. Follow the repo's runtime/environment setup, install dependencies, and run
+   its build/type baseline gates (source-program example: `nvm use && pnpm
+install --frozen-lockfile`, rebuild `better-sqlite3` if Node changed, then
+   `pnpm build && pnpm type-check`).
+3. Record `BASE_SHA=$(git rev-parse HEAD)`.
+
+### Step 2: Wave-boundary drift refresh (recon dispatch)
+
+Dispatch ONE economical recon subagent (read-only) over all wave plans:
+
+- Re-run each plan's `## Drift check` against `BASE_SHA`; classify
+  PASS / MINOR-DRIFT (describe) / STOP (quote the plan's own condition + evidence).
+- AUDIT each plan's drift-check FILE COVERAGE against its stated scope: a plan
+  whose implementation surface includes files its drift-check command omits gets
+  a wrapper rule-1 addendum (wave-2 p07 precedent — the gap became a mandatory
+  in-worktree extension and the anticipated conflict never materialized).
+- Extract each plan's COMPLETE write-surface list and mechanically intersect
+  every pair — flag every file written by 2+ plans, however minor (this feeds
+  group composition; include generated files like `apps/documentation/index.md`
+  when plans run docs gates, and CLI/help/parity files that many lanes touch).
+- Return a compact per-plan table + shared-surfaces section. Conclusions only.
+
+A tripped STOP parks that lane at plan time (recorded in the wrapper plan; lane
+excluded from groups) — never mid-run. **Reconciliation contract:** when recon
+reveals a stale plan premise, the reconciliation must be NON-NARROWING (WHERE
+the work happens may change; WHAT must be true may not), recorded exactly once
+in the Drift Refresh Record with pointer-only references elsewhere — a
+reconciliation that waives a source-plan requirement is a plan-gate Important
+(wave-4 evidence).
+
+### Step 3: Scaffold the wrapper project
+
+1. `oat project new wave-N-execution --mode quick --no-commit`.
+2. **Verify scaffold substitution AND advance the lifecycle** in `state.md`.
+   On oat ≥0.1.65, verify that the basic scaffold placeholders
+   (`{ OAT_HILL_CHECKPOINTS }`, `{ OAT_PHASE }`, `{ OAT_WORKFLOW_MODE }`) were
+   already substituted; fix them only if unexpected survivors remain. The
+   lifecycle advance and wave-specific values remain orchestrator-owned:
+   `oat_dispatch_policy` (managed/high unless the operator says otherwise),
+   `associated_issues` (the wave's backlog items),
+   **`oat_parallel_execution: true`**, and — once plan.md is written —
+   **`oat_phase: plan` + `oat_phase_status: complete`**. Also refresh the
+   state.md BODY prose (Status/Current Phase/Artifacts/Progress/Next Milestone)
+   — frontmatter alone is not enough; two waves hit body-drift findings.
+3. Write `plan.md` from `assets/wrapper-plan-template.md` — pointer-only tasks,
+   the wrapper execution contract verbatim, drift-refresh record marked
+   **non-authoritative recon evidence**, HiLL at the final phase (confirm against
+   `workflow.hillCheckpointDefault`). **Template directive hygiene:** the
+   templates' `{ curly-brace }` placeholders AND their authoring directives
+   (e.g. "Keep both code + artifact rows below") are instantiation instructions —
+   substitute/apply them and REMOVE them from the instantiated artifact; a
+   surviving directive is reviewer-visible noise (sol wave-2 finding class).
+4. Write `discovery.md` (inherited contract + this wave's decisions) and
+   `orchestration-log.md` from `assets/orchestration-log-template.md` (day one).
+5. **[JUDGMENT] Compose parallel groups** from the recon write surfaces: groups of
+   ≤ ceiling, write-disjoint within a group; shared-file plans in different groups.
+   A lane that must run alone (merges-first, or a solo finale) stays UNGROUPED —
+   ungrouped phases execute sequentially in plan order, and `validate-plan`
+   REJECTS singleton groups. Cross-model review steps on
+   locking/security/containment/dependency lanes. Recon must intersect ALL
+   per-plan write surfaces mechanically, not just headline files (wave-3 g1
+   missed a two-lane CLI-file overlap that merged conflict-free only by region
+   luck).
+6. `oat project validate-plan --project-path <path>`, run the repo's formatter
+   over the project dir (source-program example: `pnpm format:fix`), and commit
+   the scaffold.
+
+### Step 4: Plan gate
+
+Run the cross-runtime artifact gate with a **bounded** prompt (rule 6): review the
+wrapper artifacts for plan invariants, contract consistency, frontmatter validity,
+and whether any task restates/narrows its source plan — the external plans are
+immutable inputs, NOT review targets. Disposition findings in-artifact
+(gate-invoked artifact review), commit, and proceed at `fixes_completed` per
+wave-0/1 precedent.
+
+### Step 5: Execute via `oat-project-implement`
+
+The lifecycle skill owns execution. This skill contributes the templates it uses:
+
+- **Worktree bootstrap:** run
+  `scripts/bootstrap-group.sh <wave-prefix> <BASE_SHA> pNN...` — e.g.
+  `scripts/bootstrap-group.sh wave-2 $(git rev-parse HEAD) p01 p02 p03`
+  (wraps the `oat-worktree-bootstrap-auto` contract: create at explicit base,
+  propagate local config, verify base ancestry, repo bootstrap and
+  proportionate baseline via the `OAT_WAVE_BOOTSTRAP_CMD` /
+  `OAT_WAVE_BASELINE_CMD` env hooks — a pnpm-shaped repo defaults to
+  `pnpm run worktree:init` / `pnpm type-check`, any other repo skips the step
+  with a STATUS line — verify provider-view parity with the root checkout,
+  structured STATUS lines; as of 1.3.0 the script relocates its
+  `.bootstrap-*.log` files into `$TMPDIR` itself).
+  When lanes carry provider review steps that require worktree trust, pre-trust
+  the new paths using that provider's configuration (for Codex, the
+  source-program example is `~/.codex/config.toml`).
+- **Implementer briefs:** self-contained Phase Scope (resolver-stamped dispatch
+  fields), the contract pointer ("your ENTIRE contract is <external plan>; nothing
+  in the wrapper narrows it"), **region-level expected-churn pre-declaration**
+  (rule 4: name the churned file AND the region vs the lane's target region —
+  three-for-three effective in wave-2 group 2), env rules, DoD gates before
+  commit, one commit per task with the plan's message, bundle STOP semantics
+  where applicable (`DR-260713-bundle-stop-semantics-park`), the bookkeeping
+  boundary (workers never touch `.oat/projects/`), and the structured PHASE
+  REPORT format. Cross-model review steps in briefs name the RUNTIME-RESOLVED
+  reviewer (the plan stays provider-neutral; dispatch resolves — currently
+  Codex per the source repo's config). Adapt lane-type addenda to the consuming
+  repo. Worked source-program examples: "background a previously-inline step"
+  lanes budget a full direct-caller audit; new shell scripts honor the repo's
+  oldest supported shell; disposal/wiring prefers the framework teardown seam
+  (Fastify `onClose` in one lane) over a concurrently restructured file; a
+  defaulted schema field (Zod in one lane) budgets type-surface consumer fixes;
+  an MCP tool rename moves its expected-tool list, additive snapshot, tool-list
+  tests, and version-pin tests together; and time-driven HTTP tests avoid a fake
+  clock that freezes the request event loop. These are briefing patterns, not
+  requirements for Fastify, vitest, Zod, or MCP.
+- **Reviewer briefs:** read-only, per-phase; checklist = source plan
+  `## Review focus`; implementer claims are inputs to VERIFY, not trust.
+  Lanes with embedded cross-model reviews get DISPOSITION-VERIFICATION briefs:
+  verify each fix and each rejection's parity claim against the cited siblings
+  instead of re-reviewing (wave-3 caught a partially-false rejection claim this
+  way). Every fix disposition, including a root-verified bounded fix, must
+  produce a minimal stored verification record stating what was verified, how
+  it was verified, and where the evidence is recorded; the wave-5 final gate
+  blocked on exactly this audit gap. For a fix continuation, prefer resuming the
+  original implementer handle while it is alive: this is cheaper and retains
+  design context. Launch a fresh same-target agent only when that handle is
+  gone. Rename/refactor-class revision reviews get a PURITY BAR: diff the
+  changed handler bodies against the ORIGINAL at base — tests alone are silent
+  on migrated-behavior drift (wave-3 p-rev1 Critical was caught only by this).
+  LOGIC-BEARING lanes' reviewers must design ≥1 adversarial probe of their own
+  beyond the implementer's pins (DR-260715-adversarial-probe-reviewer: the
+  wave-4 overlap-corruption Critical was found ONLY by a reviewer probe —
+  every gate and pinned test was green); runtime-
+  probe ambiguous behavioral claims; on containment/security surfaces require a
+  weaker-anywhere analysis (any input previously rejected that is now accepted is
+  Critical). Adapt contract-propagation checks to the lane type; the
+  source-program example required a new `DoctorJsonResponse` field to travel with
+  diagnostics docs and exact-match doctor JSON tests. Write the artifact to the
+  ROOT checkout `reviews/` and run the repo's formatter over it (source-program
+  example: `pnpm format:fix`).
+- **Merge choreography:** after all group verdicts — serialized `git merge
+--no-ff` in plan order, rebasing each phase branch on the updated tip first
+  (rules 2–3). Immediately before EVERY `git merge`, run `pwd` and
+  `git branch --show-current` and assert that they identify the intended repo
+  root and integration branch; stop on either mismatch. This closes the
+  cwd-persistence wrong-branch failure observed in wave 5. Integration DoD gates
+  after fan-in run TO COMPLETION BEFORE any group bookkeeping edits start
+  (DR-260714-integration-gates-run-before);
+  then the group bookkeeping commit. Before dispatch, inspect every worktree's
+  sync commit content and stop on provider-view deletions or unrelated managed
+  path churn. This is a **regression guard for the named stale-local-binary
+  failure class**: a stale locally resolved `node_modules/.bin/oat` can shadow
+  the global CLI and make two desired-state sync versions thrash managed files.
+  On any parity mismatch, compare `node_modules/.bin/oat --version` with
+  `oat --version`; do not treat it as unexplained toolkit corruption.
+  **Conflict-resolution contract
+  (DR-260715-conflict-resolution-contract):** on rebase/merge conflicts —
+  keep-both where lanes appended to shared surfaces; then in-worktree BUILD +
+  touched-package suites BEFORE amending (mechanical splices break seams:
+  braces, stacked branches, duplicated keys — wave-4 evidence); then inspect
+  the amended commit's file stat against the expected list; NEVER `git add -A`
+  in a worktree (stale synced local state gets swept). At every
+  merge/bookkeeping boundary, run a standing config-integrity check that tracked
+  `.oat/config.json` keys remain present; this check originated with
+  `BL-260715-investigate-oat-config-json` in the source program's repo. Update
+  canonical sections in place, the run-entry table, review rows, and state;
+  remove worktrees + branches after merge.
+
+### Step 6: Closeout
+
+Follow `oat-project-implement`'s completion route, plus the wave-specific order.
+Run these steps strictly in this numbered sequence. The load-bearing constraint:
+the end-of-run synthesis and its `summary.md` roll-up MUST come before backlog
+archival and before the project-archive seal (`oat-project-complete`) — never
+archive anything first.
+
+1. **Final verification** — integration DoD gates green on the integration branch.
+2. **End-of-run synthesis in `orchestration-log.md`, then roll it up into
+   `summary.md`** (this is the "before any archive step" gate): convention
+   verdicts with evidence, adjustments-as-rules for later waves, graduated-entries
+   ledger, rolled into `summary.md` `## Workflow Observations`.
+3. **Serialized backlog archival** — `oat backlog archive` with real summaries,
+   one commit.
+4. **Root final review.**
+5. **Cross-runtime final gate** — judgment-sweep dispositions; watch for the known
+   gate row-stomp on the final Reviews row (restore `passed` if regressed).
+6. **Pre-approval sequence** per `workflow.postImplementSequence`, then a single
+   HiLL. File follow-up-ledger backlog items at closeout (on main post-merge, or
+   pre-gate if the operator prefers them in the PR).
+7. **`oat-project-complete` BEFORE merge** (standing order: review → complete →
+   merge; an open PR is expected, not a blocker — the archive-aware PR body sync
+   handles it).
+8. **After the operator merges:** reconcile (squash-merge means content-diff the
+   branch vs main; cherry-pick stragglers), reset the working branch, clean stale
+   phase branches, and run `oat-wave-program` `wave-close <wave-id>` so the
+   program ledger records the merge (PR, SHA, completion-record link) and flips
+   the wave's plan rows to `done`.
+
+## Success Criteria
+
+- Zero convention re-derivation errors (branch naming, merge types, SHAs, gate
+  scoping — the wave-1 incident class).
+- Every lane: drift check honored, one verified commit per task, review round
+  dispositioned, DoD + integration gates green.
+- Orchestration log current at every group boundary; synthesis written before
+  archive; follow-up ledger graduated.
+- Deviations from THIS skill logged with a skill-abstraction tag — that is the
+  evidence signal for future skill revisions.

package/assets/skills/oat-wave-execute/assets/orchestration-log-template.md

@@ -0,0 +1,54 @@
+---
+oat_generated: false
+purpose: orchestration-observations
+oat_last_updated: { YYYY-MM-DD }
+---
+
+# Orchestration Log: wave-N-execution
+
+Running log of orchestration and subagent observations for this project. Two
+audiences: (1) evaluating this wave's execution specifically, and (2) collecting
+general feedback on OAT orchestration/tooling and on the `oat-wave-execute` skill
+itself — bugs, friction, and things that worked well.
+
+**Logging contract (for the orchestrator and any lifecycle skill touching this
+project):** append an entry whenever something breaks, surprises, requires a
+workaround, or works notably well. Structural entries (dispatch stamps, gate
+results, STOP/park events, bootstrap statuses, disposition maps) are appended as
+one-liners referencing artifacts by path; judgment entries are agent-authored.
+Never delete entries; strike through with a correction note if one turns out
+wrong. Version-stamp tool-related observations. Keep entries short and factual.
+Run { repo formatter write command } (source-program example: `pnpm format:fix`)
+on this file after writing. Tag entries that bear on the
+wave-skill's design with a **Skill signal (strengthens/contradicts/gap):** line —
+those drive the upstream implementation.
+
+**Entry format:**
+
+    ### YYYY-MM-DD · [project | general] · [bug | friction | worked-well | feedback] · <area>
+    What happened (1-3 sentences). Impact/workaround. Follow-up (backlog / upstream / none).
+
+**Structural entry format (skill-appended):**
+
+    ### YYYY-MM-DD · structural · <skill> · <scope>
+    One-line mirror of the skill's structured output. Reference artifacts by path.
+
+---
+
+## Entries
+
+{ appended chronologically, append-only }
+
+---
+
+## End-of-run synthesis (pending — do not skip at project completion)
+
+At project completion, BEFORE any archive step, the orchestrator writes:
+(1) verdicts on the conventions this wave exercised, with evidence entries cited;
+(2) a ruling on every "Skill signal"-tagged entry — what the `oat-wave-execute`
+skill should change; (3) adjustments adopted for later waves, stated as rules;
+(4) a graduated-entries ledger (backlog IDs / upstream refs / closed-with-evidence
+/ open-with-owner).
+
+Roll-up ordering (critical): `summary.md` `## Workflow Observations` and any
+repo-level ledger updates happen BEFORE `oat-project-complete` archives this file.

package/assets/skills/oat-wave-execute/assets/wrapper-plan-template.md

@@ -0,0 +1,157 @@
+---
+oat_status: complete
+oat_ready_for: oat-project-implement
+oat_blockers: []
+oat_last_updated: { YYYY-MM-DD }
+oat_phase: plan
+oat_phase_status: complete
+oat_plan_hill_phases: ['{ final-phase-id }']
+oat_auto_review_at_hill_checkpoints: true
+oat_plan_parallel_groups: [{ groups of <= ceiling, write-disjoint, from recon }]
+oat_plan_source: quick
+oat_import_reference: null
+oat_import_source_path: null
+oat_import_provider: null
+oat_generated: false
+oat_template: false
+---
+
+# Implementation Plan: wave-N-execution (Wave N external-plan wrapper)
+
+> Execute this plan using `oat-project-implement` — groups per
+> `oat_plan_parallel_groups`. Concurrency ceiling: { N } worktrees (operator
+> decision).
+
+**Goal:** Execute the { count } Wave N external plans ({ short lane list }) through
+the wave→project wrapper pattern (DR-260713-wave-project-wrapper-over).
+
+**Architecture:** Thin wrapper. Each task's **entire and only implementation
+contract** is its external plan under `.oat/repo/reference/external-plans/`. Tasks
+below carry wrapper-owned metadata exclusively: the source-plan path,
+ordering/dependencies, wrapper-level verification gates, the commit convention, and
+review mapping. Nothing in this file restates, narrows, or overrides a source plan.
+
+**Commit Convention:** `{type}(p{NN}-t{NN}): {description}` — the external plan
+governs commit content and granularity; the wrapper adds the `pNN-tNN` scope.
+
+**Wrapper execution contract (applies to every task):**
+
+1. **Drift check first.** Run the source plan's `## Drift check` against current
+   HEAD. A material mismatch (per that plan's own definition) is a STOP. The
+   wave-boundary drift refresh (see record below) does not replace the in-worktree
+   re-check — the integration tip advances as groups merge.
+2. **Execute the source plan's `## Implementation steps`** in order with each
+   step's embedded Verify gate; honor its `## STOP conditions` verbatim.
+3. **Confirm the source plan's `## Done criteria`**, then run the full DoD gates:
+   { repo env setup commands, then repo test/lint/format/type gates }
+   (source-program example: `nvm use` first; `pnpm rebuild -r better-sqlite3` if
+   Node changed; `pnpm test && pnpm lint && pnpm format && pnpm type-check`).
+4. **STOP → BLOCKED at phase level (bundle exception).** A source-plan STOP parks
+   the phase (record in `state.md` `oat_blockers` + `implementation.md`); sibling
+   phases continue. **Bundle phases:** a STOP parks only the stopped task; the
+   implementer records the blocker and continues remaining independent tasks; the
+   phase is terminal when every task is completed or parked
+   (DR-260713-bundle-stop-semantics-park).
+5. **Group-dependency rule:** a group starts when every phase of the previous
+   group is terminal — merged, or parked with completed commits merged. A park
+   never blocks the next group.
+6. **Merge serialization:** within a group, merge phase branches one at a time in
+   plan order, rebasing each on the updated tip first. Name the deliberately
+   sequenced shared files here: { shared-file list from recon }.
+7. **Backlog archival is NOT part of any task** — once, serialized on the
+   integration branch after all merges (DR-260713-shared-tracked-surfaces).
+8. **Phase review checklist = the source plan's `## Review focus`.**
+9. **Artifact hygiene:** every agent runs { repo formatter write command }
+   (source-program example: `pnpm format:fix`) on markdown it writes and reports
+   observations for `orchestration-log.md` (workers report; the root appends).
+10. **Commit verification after ambiguous results:** inspect `git log`/HEAD before
+    retrying; record the SHA in `implementation.md`.
+
+## Parallelism
+
+{ Group composition + rationale. Prefix the recon observations with: }
+
+> The recon observations below are **non-authoritative grouping evidence only** —
+> they justify group composition but never constrain a source plan: each source
+> plan's own live location/condition checks govern at execution time.
+
+## Dispatch Profile
+
+_No per-phase overrides. Runtime selection applies, capped by the project's named
+dispatch policy in `state.md`; provider-specific model/effort selection is owned by
+runtime resolution, not this plan. Cross-model review requirements are embedded in
+{ lanes touching locking/security/containment/dependency surfaces }._
+
+## Drift Refresh Record ({ date }, vs `{ BASE_SHA }`)
+
+{ Recon results: N PASS / N MINOR-DRIFT / N STOP + one line each. State explicitly
+that this record is non-authoritative recon evidence. }
+
+---
+
+## Phase { NN }: { lane-name } (group { G })
+
+**Milestone:** the source plan's `## Done criteria` fully satisfied.
+
+### Task p{NN}-t01: Execute external plan — { lane title }
+
+**Source plan (the contract):**
+`.oat/repo/reference/external-plans/{ plan-file }.md`
+
+**Ordering:** group { G }; own worktree, parallel with { siblings }. { Grouping
+notes, marked non-authoritative where recon-derived. }
+
+**Step 1: Drift check** — per the source plan's `## Drift check`.
+
+**Step 2: Execute** the source plan in full.
+
+**Step 3: Verify (wrapper gate)**
+
+Run: the source plan's `## Done criteria` checks, then the full DoD gates from
+the wrapper execution contract
+Expected: all green.
+
+{ **Step 4: Cross-model review** — include for locking/security/containment/
+dependency/lifecycle surfaces: before committing, obtain an independent
+cross-model review of the uncommitted diff via the runtime-configured reviewer
+(provider/model/effort owned by dispatch configuration, not this plan);
+disposition every finding in the phase report. }
+
+**Step { N }: Commit**
+
+```bash
+git commit -m "{type}(p{NN}-t01): { description }"
+```
+
+---
+
+## Reviews
+
+{Keep both code + artifact rows below. Add additional code rows as needed, but do not delete `spec`/`design`.}
+
+| Scope  | Type     | Status  | Date | Artifact |
+| ------ | -------- | ------- | ---- | -------- |
+| p01    | code     | pending | -    | -        |
+| final  | code     | pending | -    | -        |
+| plan   | artifact | pending | -    | -        |
+| spec   | artifact | pending | -    | -        |
+| design | artifact | pending | -    | -        |
+
+**Status values:** `pending` → `received` → `fixes_added` → `fixes_completed` → `passed`
+
+## Implementation Complete
+
+- [ ] { N }/{ N } phases, { M }/{ M } tasks complete
+- [ ] Every source plan's `## Done criteria` confirmed (recorded in `implementation.md`)
+- [ ] **Serialized backlog bookkeeping** (integration branch, after all merges):
+      `oat backlog archive` with real outcome summaries for { backlog IDs }, one commit
+- [ ] Orchestration-log end-of-run synthesis written; roll-up into `summary.md`
+      before any archive step
+- [ ] Full DoD gates green on the integration branch
+
+## References
+
+- Source plans: the { N } `.oat/repo/reference/external-plans/*.md` files named above
+- Program indexes: `.oat/repo/reference/external-plans/*-plan-index.md`
+- Pattern: `DR-260713-wave-project-wrapper-over`, prior wave summaries in
+  `.oat/repo/reference/project-summaries/`

package/assets/skills/oat-wave-execute/scripts/bootstrap-group.sh

@@ -0,0 +1,195 @@
+#!/bin/bash
+# oat-wave-execute: parallel-group worktree bootstrap.
+# Wraps the oat-worktree-bootstrap-auto contract (normal mode, strict policy).
+# Usage: bootstrap-group.sh <wave-prefix> <base-sha> <phase>...
+#   e.g. bootstrap-group.sh wave-2 <full-sha> p01 p02 p03
+# Emits one terminal "STATUS <phase>: status=..." line per phase (plus optional
+# "STATUS <phase>: <step>=skipped ..." informational lines); caller parses those.
+# Repo hooks (repo-neutral): OAT_WAVE_BOOTSTRAP_CMD runs repository bootstrap in
+# each worktree; OAT_WAVE_BASELINE_CMD runs the proportionate baseline check.
+# When unset, a pnpm-shaped repo (pnpm-lock.yaml + matching package.json script)
+# defaults to `pnpm run worktree:init` / `pnpm type-check`; otherwise the step
+# is skipped with a STATUS line.
+set -u
+
+usage() {
+  echo "Usage: bootstrap-group.sh <wave-prefix> <base-sha> <phase>..." >&2
+  echo "  e.g. bootstrap-group.sh wave-2 <full-40-hex-sha> p01 p02 p03" >&2
+}
+
+provider_view_list() {
+  local checkout="$1"
+  node - "$checkout/.oat/sync/manifest.json" <<'NODE'
+const fs = require("fs");
+const manifestPath = process.argv[2];
+const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+const paths = manifest.entries.map((entry) => entry.providerPath).sort();
+process.stdout.write(`${paths.join("\n")}\n`);
+NODE
+}
+
+verify_view_parity() {
+  local root_checkout="$1"
+  local worktree_checkout="$2"
+  local root_list
+  local worktree_list
+  local local_version
+  local global_version
+
+  root_list="$(mktemp "${TMPDIR:-/tmp}/oat-root-views.XXXXXX")" || return 1
+  worktree_list="$(mktemp "${TMPDIR:-/tmp}/oat-worktree-views.XXXXXX")" || {
+    rm -f "$root_list"
+    return 1
+  }
+
+  if ! provider_view_list "$root_checkout" >"$root_list" ||
+     ! provider_view_list "$worktree_checkout" >"$worktree_list"; then
+    echo "STATUS view-parity=MISMATCH"
+    echo "  diagnostic: unable to read provider-view lists from sync manifests"
+    rm -f "$root_list" "$worktree_list"
+    return 1
+  fi
+
+  if cmp -s "$root_list" "$worktree_list"; then
+    echo "STATUS view-parity=ok"
+    rm -f "$root_list" "$worktree_list"
+    return 0
+  fi
+
+  echo "STATUS view-parity=MISMATCH"
+  echo "  root-only provider views:"
+  comm -23 "$root_list" "$worktree_list"
+  echo "  worktree-only provider views:"
+  comm -13 "$root_list" "$worktree_list"
+  if [[ -x "$worktree_checkout/node_modules/.bin/oat" ]]; then
+    local_version="$("$worktree_checkout/node_modules/.bin/oat" --version 2>&1)"
+  else
+    local_version="missing"
+  fi
+  global_version="$(cd "$worktree_checkout" && oat --version 2>&1)"
+  echo "  node_modules/.bin/oat --version: $local_version"
+  echo "  oat --version: $global_version"
+  rm -f "$root_list" "$worktree_list"
+  return 1
+}
+
+# Guard: require wave-prefix, base-sha, and at least one phase (3+ args)
+if [[ $# -lt 3 ]]; then
+  echo "FATAL: expected <wave-prefix> <base-sha> <phase>... (got $# arg(s))" >&2
+  usage
+  exit 2
+fi
+
+WAVE_PREFIX="$1"; shift
+BASE_SHA="$1"; shift
+PHASES=("$@")
+
+# Guard: base must be a full 40-hex commit ID (standing rule 5 — no short SHAs)
+if [[ ! "$BASE_SHA" =~ ^[0-9a-f]{40}$ ]]; then
+  echo "FATAL: base '$BASE_SHA' is not a full 40-hex commit ID (use git rev-parse HEAD)" >&2
+  usage
+  exit 1
+fi
+REPO="$(git rev-parse --show-toplevel)"
+ROOT_CFG="$(cd "$REPO" && oat config get worktrees.root 2>/dev/null || true)"
+ROOT="$REPO/${ROOT_CFG:-.worktrees}"
+# Optional node env setup: source nvm only when present; otherwise honor the
+# already-configured node environment (nvm is a repo convention, not required).
+if [[ -s "$HOME/.nvm/nvm.sh" ]]; then
+  source "$HOME/.nvm/nvm.sh" >/dev/null 2>&1
+  cd "$REPO" && nvm use >/dev/null 2>&1
+fi
+
+# Repo-hook resolution: explicit env hooks win; a pnpm-shaped repo (lockfile +
+# matching package.json script) falls back to its conventional commands;
+# anything else skips the step with a STATUS line.
+has_pnpm_script() {
+  [[ -f "$REPO/pnpm-lock.yaml" ]] || return 1
+  grep -q "\"$1\"" "$REPO/package.json" 2>/dev/null
+}
+BOOTSTRAP_CMD="${OAT_WAVE_BOOTSTRAP_CMD:-}"
+if [[ -z "$BOOTSTRAP_CMD" ]] && has_pnpm_script "worktree:init"; then
+  BOOTSTRAP_CMD="pnpm run worktree:init"
+fi
+BASELINE_CMD="${OAT_WAVE_BASELINE_CMD:-}"
+if [[ -z "$BASELINE_CMD" ]] && has_pnpm_script "type-check"; then
+  BASELINE_CMD="pnpm type-check"
+fi
+GROUP_STATUS=0
+
+# Guard: the full SHA must resolve to an actual commit in this repo
+if ! git -C "$REPO" cat-file -e "${BASE_SHA}^{commit}" 2>/dev/null; then
+  echo "FATAL: base '$BASE_SHA' does not resolve to a commit (use git rev-parse HEAD)"; exit 1
+fi
+# Guard: phase branches must not nest under an existing leaf ref (standing rule 1)
+if git -C "$REPO" show-ref --verify --quiet "refs/heads/$WAVE_PREFIX"; then
+  echo "FATAL: branch '$WAVE_PREFIX' exists as a leaf ref; phase branches '$WAVE_PREFIX/pNN' cannot be created"; exit 1
+fi
+# Smoke detection (bootstrap-auto step 1.5)
+if [[ -n "$(git -C "$REPO" ls-tree "$BASE_SHA" -- .oat/smoke-bootstrap.json)" ]]; then
+  echo "FATAL: smoke marker present at base; refusing normal bootstrap"; exit 1
+fi
+
+for P in "${PHASES[@]}"; do
+  BR="$WAVE_PREFIX/$P"
+  TP="$ROOT/$BR"
+  echo "=== [$P] bootstrap → $TP (base $BASE_SHA) ==="
+  if ! git -C "$REPO" worktree add "$TP" -b "$BR" "$BASE_SHA" >/dev/null 2>&1; then
+    echo "STATUS $P: status=error reason=worktree-create-failed"; continue
+  fi
+  # Local-only config propagation (bootstrap-auto step 2.5; the bootstrap hook
+  # may also cover these, but propagate first so its tooling sees them). Other
+  # repo-local files belong in a consuming repo's own wrapper around this script.
+  [[ -f "$REPO/.oat/config.local.json" && ! -f "$TP/.oat/config.local.json" ]] && cp "$REPO/.oat/config.local.json" "$TP/.oat/config.local.json"
+  (cd "$TP" && oat local sync "$TP" >/dev/null 2>&1) || true
+  # Base verification (bootstrap-auto step 2.7)
+  OBS=$(git -C "$TP" rev-parse HEAD)
+  if ! git -C "$TP" merge-base --is-ancestor "$BASE_SHA" "$OBS"; then
+    echo "STATUS $P: status=failed reason=base-mismatch expected=$BASE_SHA observed=$OBS"; continue
+  fi
+  # Repository bootstrap (hook-resolved) + proportionate baseline
+  if [[ -n "$BOOTSTRAP_CMD" ]]; then
+    if ! (cd "$TP" && /bin/bash -c "$BOOTSTRAP_CMD" >"$TP/.bootstrap-init.log" 2>&1); then
+      echo "STATUS $P: status=error reason=repository-bootstrap-failed (see $TP/.bootstrap-init.log)"; tail -5 "$TP/.bootstrap-init.log"; continue
+    fi
+  else
+    echo "STATUS $P: bootstrap=skipped reason=no-bootstrap-hook (set OAT_WAVE_BOOTSTRAP_CMD)"
+  fi
+  if ! verify_view_parity "$REPO" "$TP"; then
+    echo "STATUS $P: status=error reason=provider-view-parity-mismatch"; continue
+  fi
+  if [[ -n "$BASELINE_CMD" ]]; then
+    if ! (cd "$TP" && /bin/bash -c "$BASELINE_CMD" >"$TP/.bootstrap-baseline.log" 2>&1); then
+      echo "STATUS $P: status=error reason=baseline-verification-failed (see $TP/.bootstrap-baseline.log)"; continue
+    fi
+  else
+    echo "STATUS $P: baseline=skipped reason=no-baseline-hook (set OAT_WAVE_BASELINE_CMD)"
+  fi
+  # Sync-commit if scoped paths dirty (bootstrap-auto step 4)
+  if ! (
+    cd "$TP" && git add -A -- .oat/sync/manifest.json .claude .cursor .codex 2>/dev/null
+    if ! git diff --cached --quiet 2>/dev/null; then
+      if git -c core.hooksPath=/dev/null commit -q -m "chore: run sync"; then
+        echo "  sync_commit: committed"
+      else
+        echo "  sync_commit: FAILED"
+        exit 1
+      fi
+    else
+      echo "  sync_commit: skip"
+    fi
+  ); then
+    echo "STATUS $P: status=failed reason=sync-commit"
+    GROUP_STATUS=1
+    continue
+  fi
+  # Relocate bootstrap logs out of the worktree (1.3.0: script-owned; callers
+  # previously forgot this step)
+  LOGDIR="${TMPDIR:-/tmp}/oat-bootstrap-logs/$WAVE_PREFIX-$P"
+  mkdir -p "$LOGDIR" && mv "$TP"/.bootstrap-*.log "$LOGDIR"/ 2>/dev/null
+  echo "  bootstrap_logs: $LOGDIR"
+  DIRTY=$(cd "$TP" && git status --porcelain | wc -l | tr -d ' ')
+  echo "STATUS $P: status=success worktree=$TP branch=$BR base=$BASE_SHA observed=$OBS git_clean=$([[ $DIRTY == 0 ]] && echo pass || echo "fail($DIRTY)")"
+done
+echo "=== group bootstrap done ==="
+exit "$GROUP_STATUS"

package/assets/skills/oat-wave-program/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: oat-wave-program
+version: 1.1.0
+description: Use when decomposing a corpus of external implementation plans into an ordered wave program — coverage inventory, dependency mapping, wave composition, and the durable execution-program artifact that oat-wave-execute consumes and updates.
+argument-hint: '[new|refresh|wave-close <wave-id>] (default: refresh against the current artifact)'
+disable-model-invocation: false
+user-invocable: true
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob, Task
+---
+
+# Program a Corpus of External Plans into Waves
+
+Maintain the **program layer** above `oat-wave-execute`: record how N external
+plans (from one or more plan-generation runs) map into an ordered sequence of
+waves, and keep that mapping durable and current as waves complete.
+`oat-wave-execute` runs ONE wave; this skill records and maintains the
+orchestrator-composed, operator-approved mapping of WHICH plans form each wave.
+
+## Ownership Boundary
+
+**This skill owns (mechanical):** the execution-program artifact contract and its
+durable home, the plan-coverage inventory (every plan mapped exactly once or
+explicitly deferred), the wave-status ledger and its update procedure at wave
+boundaries, and the refresh procedure when a new plan batch lands.
+
+**The orchestrator owns (judgment — never delegate to this skill or to workers):**
+wave composition itself — theme coherence, dependency ordering, risk balancing
+(don't stack all high-churn lanes in one wave), wave sizing against the operator's
+concurrency ceiling, and the call on when a deferred plan re-enters the program.
+
+## The Artifact
+
+**Home:** `.oat/repo/reference/external-plans/<YYYY-MM-DD>-execution-program.md`
+(created from `assets/execution-program-template.md`). One live program artifact
+at a time; a superseding program links its predecessor. It is index-adjacent
+reference material — NOT an executable plan and NOT an `oat-project-import-plan`
+target (same disclaimer as the plan indexes).
+
+**Contract:**
+
+- **Wave table:** one row per plan — plan link, source index, wave, ordering
+  notes (merge-first/solo, hard/soft dependencies), status
+  (`pending | in-wave | done | deferred | dropped`).
+- **Coverage invariant (load-bearing):** every plan listed in every
+  `*-plan-index.md` appears in exactly one row. Plans deliberately not scheduled
+  get `deferred`/`dropped` WITH the reason and re-entry trigger — silence is a
+  bug. Verify mechanically (count plans in indexes vs rows) before committing.
+- **Wave sections:** per wave — theme, lane list, intra-wave dependency notes
+  (which lane merges first and why), and cross-wave prerequisites ("W4
+  token-cost requires W3 permission-policy").
+- **Status ledger:** per wave — composed → in-progress (project link) → merged
+  (PR + merge SHA + completion record link). Updated by this skill's
+  `wave-close` mode, invoked from `oat-wave-execute` closeout step 8.
+
+## Process
+
+### Mode: `new` (first program for a plan corpus)
+
+1. **Inventory:** read every `*-plan-index.md` under
+   `.oat/repo/reference/external-plans/`; extract each plan, its dependency
+   notes, and any wave hints the index already records. Verify each plan file
+   exists (a dangling index row is a STOP — report, don't guess).
+2. **Shared-surface scan:** from the indexes' dependency notes (NOT fresh recon —
+   the wave-boundary drift refresh in `oat-wave-execute` owns live evidence),
+   collect hard orderings (e.g. a tool-family chain), soft orderings (same-file
+   churn), and cross-batch seams (shared new modules; first-executed builds).
+3. **[JUDGMENT] Compose waves:** group by theme + dependency layer, sized so a
+   wave's write-disjoint groups fit the operator's concurrency ceiling in 2–3
+   dispatch groups. Honor index wave hints unless evidence contradicts them —
+   and record the contradiction when it does.
+4. **Write the artifact** from the template; run the coverage check; present the
+   wave map to the operator for approval BEFORE the first wave kicks off
+   (program composition is an operator checkpoint, not a silent default).
+5. Run the repo's formatter over the artifact and commit it (source-program
+   examples: `pnpm format:fix`; `docs(pjm): add execution program <date>`).
+
+### Mode: `refresh` (new plan batch, or drift in a pending wave)
+
+1. Diff current indexes against the artifact's rows; add new plans as rows
+   (initially `pending`, wave `TBD` unless an index hints placement).
+2. [JUDGMENT] Re-compose only waves not yet started. Never reshuffle a wave
+   that is `in-progress`; a merged wave's row set is frozen history.
+3. Re-run the coverage check; commit.
+
+### Mode: `wave-close <wave-id>` (called at wave closeout)
+
+1. Flip the wave's plan rows to `done` (or back to `deferred` with reason, for
+   lanes parked by a STOP — a parked lane re-enters a later wave explicitly).
+2. Update the status ledger row: PR, merge SHA, completion-record link.
+3. Note next-wave unblocks ("W3 merged → W4 token-cost unblocked").
+4. Commit with the wave's closeout bookkeeping.
+
+## Integration with `oat-wave-execute`
+
+- `oat-wave-execute` **Inputs** resolves its lane list from this artifact (falling
+  back to index wave hints only when no program artifact exists).
+- `oat-wave-execute` closeout step 8 invokes `wave-close` here.
+- A lane parked mid-wave (source-plan STOP) surfaces in BOTH artifacts: the
+  wave project's blocker record and this ledger's `deferred` row.
+
+## Success Criteria
+
+- Coverage invariant holds on every commit of the artifact (no silently
+  unmapped plan).
+- The program survives session loss: a fresh session can resume wave kickoff
+  from the artifact alone, without reconstructing composition from index notes.
+- Wave status ledger is current within one commit of each wave's closeout.
+- Composition changes are recorded with reasons — the artifact shows why a plan
+  moved waves, not just that it did.

package/assets/skills/oat-wave-program/assets/execution-program-template.md

@@ -0,0 +1,40 @@
+---
+oat_generated: true
+oat_external_plan_index: false
+oat_execution_program: true
+oat_program_supersedes: { null | path to predecessor program artifact }
+oat_program_indexes:
+  - { '.oat/repo/reference/external-plans/<index-file>.md' }
+created: '{ ISO timestamp }'
+---
+
+# Execution Program: { date } ({ corpus description })
+
+This artifact is the durable program map for the external-plan corpus listed in
+`oat_program_indexes`. It records wave composition and status. It is not an
+executable plan and is not an `oat-project-import-plan` target — each wave runs
+as a wrapper OAT project via `oat-wave-execute`, and each plan's implementation
+contract remains its immutable plan file.
+
+## Status Ledger
+
+| Wave | Theme     | Lanes | Status                              | Record                                |
+| ---- | --------- | ----- | ----------------------------------- | ------------------------------------- |
+| W{N} | { theme } | { n } | { composed / in-progress / merged } | { project / PR + SHA / summary link } |
+
+## Wave Table (coverage: { N } plans = { N } index rows; verified { date })
+
+| Plan                      | Index      | Wave | Ordering notes                | Status                                            |
+| ------------------------- | ---------- | ---- | ----------------------------- | ------------------------------------------------- |
+| [{ plan }](./{ file }.md) | { source } | W{N} | { merge-first / after X / — } | { pending / in-wave / done / deferred / dropped } |
+
+{ Deferred/dropped rows MUST carry reason + re-entry trigger in the notes column. }
+
+## Wave { N }: { theme }
+
+- **Lanes:** { list }
+- **Intra-wave ordering:** { which lane merges first/solo and why }
+- **Cross-wave prerequisites:** { what this wave needed from earlier waves; what
+  it unblocks later }
+- **Composition rationale:** { theme/risk/sizing judgment, including any index
+  wave-hint overridden and why }

package/dist/commands/init/tools/shared/skill-manifest.d.ts

@@ -11,7 +11,7 @@ export interface PackMetadata {
 }
 export declare const PACK_METADATA: Record<string, PackMetadata>;
 export declare function resolvePackDefaultScope(packName: string): 'user' | 'project';
-export declare const WORKFLOW_SKILLS: readonly ["oat-cursor-cloud-projects", "oat-project-autonomous", "oat-project-capture", "oat-project-clear-active", "oat-project-complete", "oat-project-design", "oat-project-dispatch-subagents", "oat-project-discover", "oat-project-document", "oat-project-implement", "oat-project-import-plan", "oat-project-new", "oat-project-next", "oat-project-open", "oat-project-plan", "oat-project-plan-writing", "oat-project-pr-final", "oat-project-pr-progress", "oat-project-progress", "oat-project-promote-spec-driven", "oat-project-quick-start", "oat-project-reconcile", "oat-project-revise", "oat-project-review-provide", "oat-project-review-provide-remote", "oat-project-review-receive", "oat-project-review-receive-remote", "oat-project-spec", "oat-project-split", "oat-project-summary", "oat-repo-knowledge-index", "oat-worktree-bootstrap", "oat-worktree-bootstrap-auto", "oat-wrap-up"];
+export declare const WORKFLOW_SKILLS: readonly ["oat-cursor-cloud-projects", "oat-project-autonomous", "oat-project-capture", "oat-project-clear-active", "oat-project-complete", "oat-project-design", "oat-project-dispatch-subagents", "oat-project-discover", "oat-project-document", "oat-project-implement", "oat-project-import-plan", "oat-project-new", "oat-project-next", "oat-project-open", "oat-project-plan", "oat-project-plan-writing", "oat-project-pr-final", "oat-project-pr-progress", "oat-project-progress", "oat-project-promote-spec-driven", "oat-project-quick-start", "oat-project-reconcile", "oat-project-revise", "oat-project-review-provide", "oat-project-review-provide-remote", "oat-project-review-receive", "oat-project-review-receive-remote", "oat-project-spec", "oat-project-split", "oat-project-summary", "oat-repo-knowledge-index", "oat-worktree-bootstrap", "oat-worktree-bootstrap-auto", "oat-wave-execute", "oat-wave-program", "oat-wrap-up"];
 export declare const WORKFLOW_AGENTS: readonly ["oat-codebase-mapper.md", "oat-phase-implementer.md", "oat-reviewer.md"];
 export declare const WORKFLOW_TEMPLATES: readonly ["state.md", "discovery.md", "spec.md", "design.md", "plan.md", "implementation.md", "summary.md", "project-log.md"];
 export declare const WORKFLOW_SCRIPTS: readonly ["generate-oat-state.sh", "generate-thin-index.sh", "resolve-tracking.sh"];

package/dist/commands/init/tools/shared/skill-manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skill-manifest.d.ts","sourceRoot":"","sources":["../../../../../src/commands/init/tools/shared/skill-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAgBH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC;AAED,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAKtD,CAAC;AAEF,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE5E;AAID,eAAO,MAAM,eAAe,s3BAmClB,CAAC;AAEX,eAAO,MAAM,eAAe,oFAIlB,CAAC;AAEX,eAAO,MAAM,kBAAkB,+HASrB,CAAC;AAEX,eAAO,MAAM,gBAAgB,qFAInB,CAAC;AAIX,eAAO,MAAM,WAAW,2FAKd,CAAC;AAIX,eAAO,MAAM,WAAW,qCAAsC,CAAC;AAI/D,eAAO,MAAM,WAAW,iLAQd,CAAC;AAEX,eAAO,MAAM,YAAY,kCAAmC,CAAC;AAI7D,eAAO,MAAM,cAAc,2NASjB,CAAC;AAIX,eAAO,MAAM,yBAAyB,sHAK5B,CAAC;AAEX,eAAO,MAAM,4BAA4B,yIAQ/B,CAAC;AAEX,eAAO,MAAM,0BAA0B,aAAc,CAAC;AAItD,eAAO,MAAM,iBAAiB,6BAA8B,CAAC;AAI7D,eAAO,MAAM,eAAe,2EAMlB,CAAC;AAEX,eAAO,MAAM,eAAe,qCAAsC,CAAC"}
+{"version":3,"file":"skill-manifest.d.ts","sourceRoot":"","sources":["../../../../../src/commands/init/tools/shared/skill-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAgBH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC;AAED,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAKtD,CAAC;AAEF,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE5E;AAID,eAAO,MAAM,eAAe,85BAqClB,CAAC;AAEX,eAAO,MAAM,eAAe,oFAIlB,CAAC;AAEX,eAAO,MAAM,kBAAkB,+HASrB,CAAC;AAEX,eAAO,MAAM,gBAAgB,qFAInB,CAAC;AAIX,eAAO,MAAM,WAAW,2FAKd,CAAC;AAIX,eAAO,MAAM,WAAW,qCAAsC,CAAC;AAI/D,eAAO,MAAM,WAAW,iLAQd,CAAC;AAEX,eAAO,MAAM,YAAY,kCAAmC,CAAC;AAI7D,eAAO,MAAM,cAAc,2NASjB,CAAC;AAIX,eAAO,MAAM,yBAAyB,sHAK5B,CAAC;AAEX,eAAO,MAAM,4BAA4B,yIAQ/B,CAAC;AAEX,eAAO,MAAM,0BAA0B,aAAc,CAAC;AAItD,eAAO,MAAM,iBAAiB,6BAA8B,CAAC;AAI7D,eAAO,MAAM,eAAe,2EAMlB,CAAC;AAEX,eAAO,MAAM,eAAe,qCAAsC,CAAC"}

package/dist/commands/init/tools/shared/skill-manifest.js

@@ -49,6 +49,8 @@ export const WORKFLOW_SKILLS = [
     'oat-repo-knowledge-index',
     'oat-worktree-bootstrap',
     'oat-worktree-bootstrap-auto',
+    'oat-wave-execute',
+    'oat-wave-program',
     'oat-wrap-up',
 ];
 export const WORKFLOW_AGENTS = [

package/dist/commands/project/validate-plan/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/validate-plan/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC,UAAU,+BAA+B;IACvC,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;CACjE;AAMD,wBAAgB,gCAAgC,CAC9C,SAAS,GAAE,OAAO,CAAC,+BAA+B,CAAM,GACvD,OAAO,CAuET"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/validate-plan/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC,UAAU,+BAA+B;IACvC,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;CACjE;AAMD,wBAAgB,gCAAgC,CAC9C,SAAS,GAAE,OAAO,CAAC,+BAA+B,CAAM,GACvD,OAAO,CA0ET"}

package/dist/commands/project/validate-plan/index.js

@@ -10,7 +10,8 @@ const DEFAULT_DEPENDENCIES = {
 export function createProjectValidatePlanCommand(overrides = {}) {
     const dependencies = { ...DEFAULT_DEPENDENCIES, ...overrides };
     return new Command('validate-plan')
-        .description('Validate plan.md parallelism metadata against the plan phase list')
+        .description('Validate plan.md parallelism metadata against the plan phase list; singleton groups are not allowed — run a solo lane as an ungrouped phase (ungrouped phases execute sequentially in plan order)')
+        .summary('Validate plan.md parallelism metadata against the plan phase list')
         .option('--project-path <path>', 'project directory containing plan.md', process.cwd())
         .action((options, command) => {
         const context = dependencies.buildCommandContext(readGlobalOptions(command));

package/dist/commands/project/validate-plan/validate-plan.js

@@ -49,7 +49,7 @@ export function validateParallelGroups(groups, phaseIds) {
             continue;
         }
         if (group.length < 2) {
-            errors.push(`group[${i}] must contain at least 2 phase IDs (singleton groups are not allowed)`);
+            errors.push(`group[${i}] must contain at least 2 phase IDs (singleton groups are not allowed — run a solo lane as an ungrouped phase (ungrouped phases execute sequentially in plan order))`);
         }
         for (const phaseId of group) {
             if (typeof phaseId !== 'string') {

package/dist/fs/io.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"io.d.ts","sourceRoot":"","sources":["../../src/fs/io.ts"],"names":[],"mappings":"AAYA,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO/D;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO9D;AAED,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,MAAM,CAAC;AAE9C,wBAAsB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE9D;AAED,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAkB5E;AAED,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAI7E;AAED,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,EACrC,MAAM,CAAC,EAAE,OAAO,GACf,OAAO,CAAC,YAAY,CAAC,CAuBvB;AAED,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,OAAO,GACZ,OAAO,CAAC,IAAI,CAAC,CAKf"}
+{"version":3,"file":"io.d.ts","sourceRoot":"","sources":["../../src/fs/io.ts"],"names":[],"mappings":"AAaA,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO/D;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO9D;AAED,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,MAAM,CAAC;AAE9C,wBAAsB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE9D;AAED,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAsB5E;AAED,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAI7E;AAED,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,EACrC,MAAM,CAAC,EAAE,OAAO,GACf,OAAO,CAAC,YAAY,CAAC,CAuBvB;AAED,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,OAAO,GACZ,OAAO,CAAC,IAAI,CAAC,CAKf"}

package/dist/fs/io.js

@@ -1,4 +1,4 @@
-import { mkdir, readdir, readFile, rename, rm, stat, symlink, writeFile, } from 'node:fs/promises';
+import { chmod, mkdir, readdir, readFile, rename, rm, stat, symlink, writeFile, } from 'node:fs/promises';
 import { dirname, isAbsolute, join, relative } from 'node:path';
 export async function fileExists(path) {
     try {
@@ -32,8 +32,12 @@ export async function copyDirectory(src, dest) {
             continue;
         }
         if (entry.isFile()) {
+            const sourceStat = await stat(sourcePath);
             const content = await readFile(sourcePath);
-            await writeFile(destPath, content);
+            await writeFile(destPath, content, { mode: sourceStat.mode });
+            // writeFile's mode applies only on creation; chmod covers
+            // pre-existing destination files so modes stay in sync.
+            await chmod(destPath, sourceStat.mode);
         }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/cli",
-  "version": "0.1.76",
+  "version": "0.2.0",
   "private": false,
   "description": "Open Agent Toolkit CLI",
   "homepage": "https://github.com/voxmedia/open-agent-toolkit/tree/main/packages/cli",
@@ -34,7 +34,7 @@
     "ora": "^9.0.0",
     "yaml": "2.8.2",
     "zod": "^3.25.76",
-    "@open-agent-toolkit/control-plane": "0.1.76"
+    "@open-agent-toolkit/control-plane": "0.2.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",