@open-agent-toolkit/cli 0.3.12 → 0.3.14

package/assets/docs/workflows/projects/picking-up-projects.md

@@ -1,124 +0,0 @@
----
-title: Picking Up Projects
-description: Continue a synced OAT project on another machine or from another user through its dedicated Git ref.
----
-
-# Picking Up a Project on Another Machine or From Another User
-
-Synced projects travel through ordinary Git refs on `origin`. Their artifact
-history is independent from the implementation branch, so a teammate or a
-second machine can continue the project even before the branch carrying its
-record file merges.
-
-## Discover and adopt
-
-From any checkout with access to `origin`:
-
-```bash
-oat project list --remote
-oat project pull <project>
-```
-
-`list --remote` discovers `refs/oat/projects/*` directly. `pull` can adopt a
-remote project that has no local record yet: it writes the record and creates
-the nested checkout. When the selected project is a coordination parent, pull
-also discovers and pulls its child projects by default. Pass `--no-children`
-only when you intentionally want the selected project alone.
-
-Completed projects are not adoption candidates. Their authoritative ref is
-`refs/oat/completed/<project>`; both `pull` and `open` return a terminal
-diagnosis instead of recreating an archived checkout or record. A same-SHA
-active ref may remain as an inert alias and is ignored. Differing active and
-completed SHAs require repair before lifecycle work continues. The same guard
-applies to coordination children: a terminal child discovered while pulling
-its parent is reported and skipped rather than adopted.
-
-After adoption, set or open the project through the normal lifecycle command
-you are using. Arrival-aware project skills pull before reading its artifacts.
-
-An adopted quick-workflow project whose `plan.md` is not implementation-ready
-resumes through `oat-project-quick-start`, which continues it in place without
-re-scaffolding, rather than through `oat-project-implement`. `oat-project-plan`,
-`oat-project-progress`, and `oat-project-next` all route by the single **quick
-plan readiness** predicate that `oat-project-quick-start` defines; readiness is
-never inferred from the presence of tasks alone.
-
-`oat project status` and `oat project list` apply the same predicate. For a
-quick project at the `plan` phase they recommend `oat-project-quick-start`, with
-the unmet clause in the reason, until the plan carries ready frontmatter, a
-durable `## Reviews` disposition, and a substantive task; only then do they
-recommend `oat-project-implement`. Recommendations for lite, spec-driven, and
-import projects are unchanged, because the predicate is quick-workflow policy.
-
-## What travels
-
-- The project ref carries the complete active artifact tree and its history.
-- The tracked JSON record travels once the branch containing it is shared or
-  merged.
-- Coordination relationships travel in the artifacts and records pulled with
-  the project.
-
-## What does not travel automatically
-
-- `local` projects never leave their original machine.
-- GitHub forks copy branches and tags, but not the `refs/oat/*` namespace. A
-  fork collaborator needs access to the upstream remote or an explicit ref
-  transfer.
-- A normal `git clone` fetches branches and tags, not custom OAT refs. OAT
-  handles remote discovery with `ls-remote` and explicitly fetches the selected
-  project ref during sync operations such as `pull`; do not expect a generic
-  clone or `git fetch` to materialize the checkout.
-
-## Why completed refs remain durable
-
-`refs/oat/completed/<project>` is a real Git ref locally and on `origin`. The
-objects reachable from it remain garbage-collection roots even when no nested
-checkout exists. Branch pruning, remote-tracking-ref pruning, and
-`git worktree prune` do not delete the completed ref. Completion deliberately
-retains this terminal reachability root so pinned PR links remain valid.
-
-Only the explicit destructive operation `oat project prune` removes the
-completed ref and any matching active alias. Treat that as permanent Git
-project-history reachability deletion and review its warnings before using
-`--force`. Prune does not remove durable local or S3 archive snapshots, and it
-refuses to delete either ref when their SHAs differ.
-
-## Archive contents
-
-When archive is selected, completion copies a synced project into
-`.oat/projects/archived/<project>/` without the nested checkout's `.git`
-pointer or `reviews/`. S3 snapshots also omit `pr/`, following the existing
-archive policy. When archive is disabled or declined, the active synced
-checkout remains in place. Successful archived closeout instead uploads the S3
-snapshot first when configured, makes the completed ref authoritative, removes
-the checkout, and deletes the tracked JSON record. The local archive metadata
-retains the source-ref identity needed for recordless retries and later S3
-restore without recreating active state.
-
-If closeout is interrupted after terminal archive identity exists, rerun
-completion so it can resume from the completed ref and archive metadata. Do not
-use `pull` or `open` to recreate an active record or checkout.
-
-For a `shared` project, archive moves the project into
-`.oat/projects/archived/<project>/` and removes the source directory, while
-completion keeps the `activeProject` pointer until the receipt validates.
-Rerunning completion after an interruption between the archive and that clear
-recognizes exactly this state — the pointer names a source directory that no
-longer exists and the archive carries `oat_lifecycle: complete` plus the
-`Lifecycle complete; archived locally` phase marker — so it validates the
-discovered archive and clears the pointer without archiving a second time or
-sealing the project log again. An interruption before the archive leaves the
-source directory in place, so completion simply reruns from the start and skips
-the work it already finished.
-
-If the archive cannot be discovered — the source directory is gone and either
-no archived project or several match the name — completion stops and leaves the
-pointer untouched. Recover manually: locate the archive directory under
-`.oat/projects/archived/`, confirm `oat_lifecycle: complete` in its `state.md`,
-then clear the pointer with `oat config set activeProject ""`.
-
-## Related
-
-- [Reviewing OAT PRs](reviewing-oat-prs.md)
-- [Project Artifacts](artifacts.md)
-- [Implementation Execution](implementation-execution.md#synced-projects-in-worktrees)

package/assets/docs/workflows/projects/review-flavors.md

@@ -1,138 +0,0 @@
----
-title: Review Flavors
-description: 'The four OAT project review flavors, when each fires in the lifecycle, and who resolves its reviewer target.'
----
-
-# Review Flavors
-
-OAT projects run reviews at several different lifecycle points, and those points
-have different independence requirements. A self-review that checks a freshly
-written plan does not need the same producer isolation as a lifecycle gate that
-signs off on the final artifact. Rather than force one reviewer-selection rule
-onto every point, OAT recognizes **four review flavors**, each with its own
-target-resolution policy layered on the shared reviewer role class.
-
-The distinguishing question is always _"who resolves this review's target, and
-how independent must that target be from whatever produced the work?"_ The four
-flavors answer it differently while preserving one invariant: the reviewer runs
-**at or above the ceiling** (see [Dispatch Policy](dispatch-ceiling.md)). Gate
-independence is project policy layered on the generic reviewer role class
-described in the `oat-project-dispatch-subagents` lifecycle-role table; this page
-covers _which_ flavor fires _when_ and _who_ resolves its target, and links out
-for the deep review request/receive mechanics.
-
-## Quick Look
-
-- What it does: names the four review flavors and states who resolves each
-  one's reviewer target.
-- When to use it: when you need to know which review fires at a lifecycle point
-  and whether it inherits, pins the ceiling, or requires an independent gate.
-- Primary sources: `oat-project-implement` phase-execution mechanics, the
-  `oat-project-dispatch-subagents` lifecycle-role table, and project design
-  Decision #11.
-
-## Flow map
-
-```mermaid
-flowchart TD
-  subgraph Planning
-    PL["Planning-phase\nartifact self-review"] --> PLR["Inherit planning parent"]
-    PLR --> PLT["Parent model\n(root already at/above ceiling)"]
-  end
-
-  subgraph Implementation
-    IM["Root-owned phase\nself-review"] --> IMR["Resolve dispatch ceiling"]
-    IMR --> IMPIN["At-ceiling pin\n(ceiling final candidate)"]
-    IMR --> IMINH["Inherit\n(only if dispatcher known at/above ceiling)"]
-    IMR --> IMCLI["Exact CLI reviewer\n(selected pre-launch)"]
-  end
-
-  subgraph Gates
-    PG["Phase review gate\n(external)"] --> PGR["Configured cross-family\nexec target (gates.execTargets)"]
-    PGR --> PGT["Independent CLI/exec target\n(host-avoidance; fail closed)"]
-
-    LG["Lifecycle / final gate"] --> LGR["Cross-runtime CLI\nexec target"]
-    LGR --> LGT["Producer-independent target\n(fail closed, no self-review substitute)"]
-    LGT -. may spawn .-> LGN["Nested managed\nreviewer child inside gate"]
-  end
-```
-
-The dotted branch marks the only flavor that may **spawn a nested managed
-reviewer child** inside the gate exec target: the lifecycle/final gate.
-
-## The four flavors
-
-| Flavor                              | Lifecycle point                                                    | Target resolution                                                                                                                                                                                              |
-| ----------------------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Planning-phase artifact self-review | Auto artifact-review loop for plan/spec/design                     | Inherit the planning parent by default (root is already at/above ceiling)                                                                                                                                      |
-| Implementation-phase self-review    | Phase and final code reviews dispatched by `oat-project-implement` | Resolve the dispatch ceiling; pin the ceiling's final candidate (at-ceiling pin); inherit only when the review-owning dispatcher is known to be at/above ceiling; else select an exact CLI reviewer pre-launch |
-| Phase review gate (external)        | Optional non-pausing gate after a phase passes its self-review     | Independent configured cross-family CLI/exec target (`gates.execTargets`), host-avoidance, unconstrained by native catalog; fail closed if unavailable                                                         |
-| Lifecycle / final gate              | End-of-lifecycle sign-off                                          | Cross-runtime CLI exec target, independent of producer context; fails closed rather than substituting same-context self-review; may spawn a nested managed reviewer child inside the gate exec target          |
-
-The first two flavors are **self-reviews**. Planning review inherits its
-producing parent by default; implementation phase review is dispatched by the
-project root after the phase producer returns. The last two are **gates** — an
-external, configured, producer-independent target. Phase implementation may run
-_below_ the review ceiling for cost reasons, but review must never silently
-inherit the below-ceiling phase agent.
-
-Pre-plan inheritance has a narrow executable guard. When dispatch resolution
-reports `unresolvedReason: policy`, an artifact review of `discovery`, `design`,
-or `spec` deliberately inherits the current planning context and records
-`selection_reason: inherit (pre-plan; no project policy)`. An explicit project
-policy is still honored at those scopes. Missing or incomplete ladders
-(`unresolvedReason: ladder | both`) fail closed, as do plan-scope artifact
-reviews and every code review without a resolved policy. Gate exec-target
-selection is separate and unaffected.
-
-## Independence and fail-closed semantics
-
-The invariant across all four flavors is that the reviewer runs **at or above
-the ceiling**. What changes between flavors is the required _independence from
-the producer_, and that independence is enforced by failing closed rather than
-silently downgrading:
-
-- **Planning self-review** needs the least independence. The planning root
-  already runs at or above the review ceiling, so inheriting the parent model
-  satisfies the invariant without managed re-pinning. Pinning is _possible_
-  once the ceiling is resolved during planning, but it is not the default.
-- **Implementation self-review** needs ceiling-level capability but not
-  cross-family isolation. The root resolves the dispatch ceiling and pins the
-  tier's final candidate after the phase report. Inheritance is allowed only
-  when the root dispatcher is _known_ to be at or above the ceiling; otherwise
-  an exact provider CLI reviewer is selected before launch. Reviewer selection
-  is never delegated to the phase implementer.
-- **Phase review gate** adds cross-family independence. It uses a configured
-  independent exec target from `gates.execTargets` with host-avoidance,
-  unconstrained by the harness's native subagent catalog. If the required
-  independent target cannot be enforced, the gate **fails closed** — it does
-  not downgrade to producer-context review.
-- **Lifecycle / final gate** requires the strongest independence: a
-  cross-runtime CLI exec target chosen independently of the producer context.
-  It fails closed rather than substituting a same-context self-review, and it is
-  the one flavor permitted to spawn a nested managed reviewer child _inside_ the
-  gate exec target when the gate's own contract calls for it.
-
-Gate independence is not a property of the generic reviewer class; it is project
-policy layered on top of it. The dispatch adapter resolves the configured gate
-target before launch and passes it as exact selection input. Fail-closed
-behavior for both gate flavors is deliberate: an unavailable independent target
-blocks the gate instead of quietly reusing whatever produced the work. For the
-gate configuration keys and non-pausing behavior, see
-[Workflow gates](../../cli-utilities/workflow-gates.md) and the
-[phase review gate](reviews.md#phase-review-gate) section of the review doc.
-
-## Related
-
-- [Reviews](reviews.md) — the review request/receive flows and the deep review
-  contract these flavors plug into.
-- [Dispatch Policy](dispatch-ceiling.md) — named ceilings, at-ceiling reviewer
-  selection, and the Dispatch Report V1 / producer-provenance record.
-- [HiLL Checkpoints](hill-checkpoints.md) — how the non-pausing phase review gate
-  relates to pauseable lifecycle checkpoints.
-- [Orchestration Model](orchestration-model.md) — the native-first dispatch
-  topology these reviewer roles run inside.
-- [Workflow gates](../../cli-utilities/workflow-gates.md) — gate configuration
-  and exec-target selection.
-- [Smoke testing](../../contributing/smoke-testing.md) — how the fixture makes
-  these flavors observable and assertable.

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

@@ -1,184 +0,0 @@
----
-title: Skills
-description: 'User-facing guide to OAT skill families, recommended entry points, and where contributor-facing skill authoring docs live.'
----
-
-# Skills
-
-Use this section when you want to choose the right OAT skill for a task. If you are writing or changing skills, jump to the contributor docs instead.
-
-## Contents
-
-- [Writing Skills](../../contributing/skills.md) - Contributor guide to skill authoring, contracts, and governance.
-- [Docs Workflows](../../docs-tooling/workflows.md) - How docs CLI helpers and docs skills work together.
-- [Explainer Kit](explainer-kit.md) - Agent-authored generation flow, direct and lifecycle callers, verification ladder, run package, and outcomes.
-- [Repo Improve](repo-improve.md) - Source modes, external-plan boundaries, optional tracking, and OAT import handoff.
-- [Recon Evidence Packets](recon.md) - Approved worker profiles, validated claim states, packet layout, partial outcomes, and directory-only handoff.
-
-## Key Skills by Use Case
-
-- Start a new tracked project: `oat-project-new`, `oat-project-quick-start`, or `oat-project-lite` for a single-sitting change with one batched interview and one approval (quick start accepts a project name plus optional description; if you omit the description it should ask before discovery begins)
-- Resume an existing project: `oat-project-open` and `oat-project-progress`
-- Execute a ready plan: `oat-project-implement`
-- Import an existing plan: `oat-project-import-plan`
-- Split a broad discovery or brainstorm into child projects: `oat-project-split`
-- Retroactively capture existing work: `oat-project-capture`
-- Run or receive reviews: `oat-project-review-provide`, `oat-project-review-receive`, or the non-project review variants
-- Generate an evidence-grounded project retrospective, apply approved repo
-  improvements, or file tracker feedback: `oat-project-retro` and
-  `oat-project-retro-file`. See
-  [Project Retrospectives](../projects/retro.md).
-- Capture a scoped, shippable backlog item: `oat-pjm-add-backlog-item` directly when the work is already scoped, or `oat-brainstorm` when the thought hasn't converged yet — the brainstorm dispatcher's "scoped backlog item" destination pre-fills the title / description / acceptance criteria / scope estimate / priority from the conversation and then runs `oat-pjm-add-backlog-item` with confirmed inputs
-- Manage the repo backlog and reference docs: `oat-pjm-update-repo-reference`, `oat-pjm-review-backlog`
-- Operate an explicit GitHub, Linear, or Jira planning-record binding through a
-  live host capability: `oat-pjm-remote`. The OAT CLI retains policy, preview,
-  approval, journal, and verification authority; the skill discovers and
-  invokes only the exact host action emitted for one durable operation.
-- 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.
-- Choose what to delegate and route bounded work by task class across Codex, Claude, or Cursor: `subagent-orchestration`. It is self-contained and usable without OAT; live catalogs and current instructions take precedence over its dated provider examples.
-- Build visual project explainers and final project recaps: `oat-explainer-kit`, backed by the destination-neutral `explainer-kit` core. See [Explainer Kit](explainer-kit.md).
-- 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`
-- Acquire and validate bounded evidence for another workflow: `recon`
-- Analyze an artifact, codebase, or document: `analyze`
-- Compare options with domain-aware dimensions: `compare`
-- Verify a claim adversarially: `skeptic`
-- Merge multiple analysis artifacts: `synthesize`
-- Capture or refine ideas: `oat-idea-new` (capture a new idea), `oat-idea-ideate` (resume an existing tracked idea or expand a scratchpad seed — not for blank-slate brainstorms; use `oat-brainstorm` for those), `oat-idea-scratchpad`, `oat-idea-summarize`
-- Run a project-independent brainstorming conversation: `oat-brainstorm` — entry point with an explicit activation contract. Hard Activation fires only on the `brainstorm` verb ("let's brainstorm", "brainstorm this", "can we brainstorm X", "help me brainstorm X", or `/oat-brainstorm`); ambiguous exploratory phrasing answers conversationally without the banner and offers structured mode only after sustained exploration. Once entered, runs a structured design conversation (one question at a time, 2-3 approaches with a recommendation) and routes to inline / doc-to-path / idea / backlog item / project handoffs based on installed packs. See [Tool Packs](../../cli-utilities/tool-packs.md) for the brainstorm pack details.
-
-## Remote host execution loop
-
-Use `oat-pjm-remote` only for an explicit remote lifecycle request. Its loop is
-deliberately narrow:
-
-1. Before the first provider-contacting command, inspect currently granted MCP
-   or connector descriptions for a semantic and exact-context match.
-2. If no capable connector is available, inspect an already configured
-   provider CLI's live help before the first attempt. Do not install a tool,
-   retain its dialect, or switch execution surfaces mid-attempt.
-3. Construct only bounded provider-neutral capability evidence and pass it to
-   the requested command with `--capability-evidence-stdin`. Treat the CLI's
-   policy, preview, approval, safety, and durable state as authoritative.
-4. When the CLI returns `pending` with `externalAction`, execute that exact
-   semantic action at most once and submit one bounded,
-   sanitized observation with `oat pjm remote operation continue`.
-5. Continue only when the CLI emits another exact action for the same durable
-   operation. Stop on its terminal envelope.
-
-The skill cannot broaden the normalized projection, bypass effective policy,
-binding clamps, purpose field grants, hard approval floors, or caller-owned
-authority evidence, read credential values, persist native provider data, or
-declare remote success. A connector result, process exit, or visible remote
-change is only evidence. Success requires an OAT `ok` envelope after
-authoritative read-back.
-See [Remote Project Management](../../cli-utilities/remote-project-management.md)
-for policy, storage, approval, and recovery details.
-
-## If You Are Trying To...
-
-- choose the right skill for a task, stay in this guide page
-- write or update a skill, use [Writing Skills](../../contributing/skills.md)
-- understand how docs-specific skills fit with docs commands, use [Docs Workflows](../../docs-tooling/workflows.md)
-
-## Full Catalog
-
-=== "Project lifecycle"
-
-    - `oat-project-new`
-    - `oat-project-quick-start`
-    - `oat-project-lite`
-    - `oat-project-import-plan`
-    - `oat-project-promote-spec-driven`
-    - `oat-project-open`
-    - `oat-project-clear-active`
-    - `oat-project-discover`
-    - `oat-project-spec`
-    - `oat-project-design`
-    - `oat-project-plan`
-    - `oat-project-plan-writing`
-    - `oat-project-split`
-    - `oat-project-implement`
-    - `oat-project-progress`
-    - `oat-project-next`
-    - `oat-project-capture`
-    - `oat-project-reconcile`
-    - `oat-project-review-provide`
-    - `oat-project-review-provide-remote`
-    - `oat-project-review-receive`
-    - `oat-project-review-receive-remote`
-    - `oat-project-pr-progress`
-    - `oat-project-pr-final`
-    - `oat-project-document`
-    - `oat-project-retro`
-    - `oat-project-retro-file`
-    - `oat-explainer-kit`
-    - `oat-wrap-up`
-    - `oat-project-complete`
-    - `oat-wave-program`
-    - `oat-wave-execute`
-
-=== "Ideas"
-
-    - `oat-idea-new`
-    - `oat-idea-ideate`
-    - `oat-idea-scratchpad`
-    - `oat-idea-summarize`
-
-=== "Brainstorming"
-
-    - `oat-brainstorm`
-
-=== "Docs and instructions"
-
-    - `authoring-docs`
-    - `oat-docs-authoring`
-    - `oat-docs-bootstrap`
-    - `oat-docs-analyze`
-    - `oat-docs-apply`
-    - `oat-agent-instructions-analyze`
-    - `oat-agent-instructions-apply`
-
-=== "Review, backlog, and maintenance"
-
-    - `oat-review-provide`
-    - `oat-review-provide-remote`
-    - `oat-review-receive`
-    - `oat-review-receive-remote`
-    - `oat-repo-knowledge-index`
-    - `oat-repo-maintainability-review`
-    - `oat-repo-improve`
-    - `oat-pjm-add-backlog-item`
-    - `oat-pjm-update-repo-reference`
-    - `oat-pjm-review-backlog`
-    - `oat-pjm-remote`
-    - `docs-completed-projects-gap-review`
-
-=== "Research"
-
-    - `recon`
-    - `deep-research`
-    - `analyze`
-    - `compare`
-    - `skeptic`
-    - `synthesize`
-
-=== "Scaffolding and utility"
-
-    - `subagent-orchestration`
-    - `explainer-kit`
-    - `oat-worktree-bootstrap`
-    - `oat-worktree-bootstrap-auto`
-    - `create-oat-skill`
-    - `create-agnostic-skill`
-    - `create-pr-description`
-    - `create-ticket`
-    - `codex-skill`
-
-## Discovery Source
-
-`AGENTS.md` is the session-facing registry. It should stay aligned with skill frontmatter and the canonical skill directories under `.agents/skills/`.
-
-Legacy compatibility note: `review-backlog` and `update-repo-reference` may still exist in some environments, but prefer the `oat-pjm-*` family for the current file-backed backlog/reference workflow.

package/assets/docs/workflows/skills/repo-improve.md

@@ -1,89 +0,0 @@
----
-title: Repo Improve
-description: 'Turn repository audits, maintainability reviews, and backlog sources into standalone external implementation plans.'
----
-
-# Repo Improve
-
-Use `oat-repo-improve` when the desired output is an executable implementation plan rather than another analysis report. Every successful run writes one or more standalone plans under `.oat/repo/reference/external-plans/`.
-
-## Choose a source
-
-| Source                 | Use it when                                                                                                                                          |
-| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Repo audit             | You need fresh repository reconnaissance and vetted improvement findings.                                                                            |
-| Maintainability review | A file-backed `oat-repo-maintainability-review` already identifies candidates. Improve verifies selected evidence without repeating the broad audit. |
-| Backlog review         | A living backlog review and optional priority alignment already establish value, dependencies, and sequencing.                                       |
-| Backlog directory      | You want to start from active items. Substantive backlogs should pass through backlog review and alignment before plan generation.                   |
-| Backlog item           | One existing item needs enough repository investigation to become executable.                                                                        |
-
-With no source argument, the skill probes for available review and backlog artifacts, annotates all five options, and asks which source to use.
-
-## Set repo-audit boundaries
-
-Fresh repo audits exclude agent-configuration directories from findings and plan candidates by default. The canonical default directory names are `.agents/`, `.claude/`, `.codex/`, and `.cursor/` at any depth. These locations commonly contain provider configuration, generated views, or externally sourced skills rather than the product surfaces being reviewed.
-
-Before reconnaissance, improve shows that default and asks whether to:
-
-- Keep all four exclusions.
-- Include selected directory names.
-- Include all four directory names.
-
-It then asks whether any other repo-relative directories should be excluded and suggests other recognizable provider directories when present. The resolved scope is shown before work begins and is applied consistently to direct searches and delegated audit lanes.
-
-These are findings exclusions, not absolute read prohibitions. Improve may read bounded instruction, convention, or intent files inside an excluded directory to understand the repository, but it does not turn those files into findings or plan candidates unless the user includes or explicitly targets that directory. A file cited by an artifact-backed source can still be verified after scope confirmation; symlinked provider views are never followed outside the repository.
-
-## Output boundary
-
-External plans are not canonical OAT project `plan.md` files. They contain self-contained context, scope, steps, verification, done criteria, and STOP conditions, but no canonical OAT phase/task IDs or lifecycle bookkeeping. External execution-readiness metadata is a separate thing and is carried deliberately: it describes whether the plan's own prerequisites have merged, not how an OAT project is moving through phases.
-
-After generation, choose either execution path:
-
-- Execute a plan directly as a standalone handoff.
-- Run `oat-project-import-plan <external-plan-path>` to preserve and normalize one plan for tracked OAT execution.
-
-Project-sized candidates are split when possible. If inseparable work needs multiple design decisions or lacks one coherent verification boundary, improve recommends an OAT project workflow instead of emitting a mega-plan.
-
-## Plan readiness and execution readiness
-
-Improve scores candidates on two independent axes. A candidate is plan-ready when it is understood well enough to write a self-contained executable plan, and execution-ready when every hard dependency it names has already merged.
-
-A blocked candidate is still planned. Rather than dropping work whose prerequisite has not landed, improve writes the plan and records the block:
-
-- `oat_execution_status` is `READY` or `BLOCKED` in plan frontmatter.
-- A typed `## Dependencies` table marks each row `Hard`, `Soft`, or `Satisfied`, and every `Hard` row names the state that would unblock it.
-- `## Landing-event impact` records what to re-anchor when a named PR or project lands, and `## Revalidation Before Execution` records when the plan must be re-checked against live state.
-
-Plan provenance is recorded as two separate SHAs: `oat_external_plan_commit` is the full SHA of the `HEAD` whose content was actually inspected, and `oat_external_plan_main_commit` is the fetched `origin/main` or merge-base used only for comparison. They may differ, and normally do when planning happens on a branch.
-
-Plans written before this contract landed are read in legacy mode: a short SHA, a missing comparison SHA, missing sections, and a missing status (read as `READY`) are all accepted, and those plans are never rewritten.
-
-## Optional tracking
-
-Plans are always the primary output. Tracking is optional and source-aware:
-
-- `--backlog-items` creates missing PJM items for repo-audit or maintainability-review plans. Backlog-backed sources reuse their existing items and add `external_plans` reverse links.
-- `--issues` previews one GitHub issue per plan, checks repository visibility and sensitive content, and requires explicit confirmation before publication. It is useful as a fallback when PJM is not installed.
-- Request both modifiers explicitly to create both forms. Neither implies the other.
-
-Failure to publish a backlog item or issue does not invalidate a successfully written plan; the skill reports partial tracking results precisely.
-
-## Orchestration
-
-Full repository audits use bounded read-only reconnaissance while the root
-agent retains classification, vetting, prioritization, cross-lane synthesis,
-and plan writing. Plan writes never move below the caller's model class — a
-parallelized author runs on the caller's model and every plan is
-caller-reviewed before publication or wave composition; the
-`keeps external-plan writes on the caller's model class` case in
-`skills-bundled-docs-contract.test.ts` is the backstop. Before launch, the
-caller loads the durable task classes and model-selection principles from
-`subagent-orchestration` plus exactly one active-provider selection reference.
-
-The internal `oat-dispatch-subagents` skill then owns capability checks, live
-catalog intersection, exact route selection, launch acceptance, recovery, and
-dispatch records. It loads exactly one matching provider mechanics reference;
-selection and mechanics references are not merged into one universal provider
-contract. Dispatch is native-first. Configured project/workflow policy may
-authorize required CLI or cross-runtime routes; an agent-improvised alternate
-route requires explicit current-run approval.

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

@@ -1,77 +0,0 @@
----
-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)