@open-agent-toolkit/cli 0.3.13 → 0.3.15

package/assets/docs/workflows/{projects → advanced}/dispatch-ceiling.md

@@ -15,13 +15,59 @@ constraints:
 - A **phase target** is one exact configured candidate selected at invocation
   time at or below the named maximum. Optional nested work resolves separately.
 
+**In short:**
+
+- **What this page is for:** choosing the _dispatch policy_, the highest model
+  tier (Economy, Balanced, High, or Frontier) that OAT may use when it starts
+  agents to implement and review each phase, or no cap, or leaving model choice
+  to the provider; and deciding where the list of candidate models (the
+  _ladder_) is stored.
+- **Who needs it:** anyone starting a quick, spec-driven, lite, or imported
+  project, because planning asks you to choose a policy; and team leads who
+  manage model cost.
+- **Know first:** there is no default policy, and a policy set in any config
+  file overrides the one each project chose. A tier is a cap: phase agents may
+  run below it, but per-phase and final code reviews run on the last model
+  listed in the capped tier. Codex and Claude enforce the cap; Cursor pins the model
+  but cannot confirm which one ran; other providers treat it as a suggestion.
+- **Decide:** [Which tier for which work](#which-tier-for-which-work),
+  [How each provider applies the cap](#how-each-provider-applies-the-cap), and
+  [Where the ladder lives](#where-the-ladder-lives). Most other sections are
+  the detailed resolution contract.
+
 The CLI command remains `oat project dispatch-ceiling resolve` for compatibility.
 Legacy `workflow.dispatchCeiling.*` and `oat_dispatch_ceiling` values remain
 readable, but new projects use ordered candidates plus `oat_dispatch_policy`.
 
-For raw config keys, see [Configuration](../../cli-utilities/configuration.md).
+For raw config keys, see [Configuration](../../reference/configuration.md).
 For the root-owned phase-agent loop, see
-[Implementation Execution](implementation-execution.md).
+[Implementation Execution](../projects/execution/implementation-execution.md).
+
+To pick a tier for a project, start with
+[Which tier for which work](#which-tier-for-which-work) and the rest of
+[Choosing policy and ladder ownership](#choosing-policy-and-ladder-ownership)
+near the end of this page.
+
+## How each provider applies the cap
+
+The cap is the named ceiling: the highest tier a project or phase may use. A
+provider is the agent tool running OAT. How firmly the cap holds depends on
+the provider:
+
+- **Codex: enforced.** OAT launches each phase on an agent role that
+  `oat sync` generated, pinned to one model and effort.
+- **Claude: enforced.** OAT launches a generated role pinned to one model and
+  effort, or passes the exact model on each call.
+- **Cursor: pinned, not verified.** OAT launches a generated role pinned to
+  the mapped model, but Cursor can substitute a different model without an
+  error, for example when your plan or account cannot use the pinned one or
+  the pin has a typo. OAT records the model it requested, not the model that
+  ran.
+- **Other providers: advisory.** OAT has no way to pin a model there, so the
+  cap is only a suggestion.
+
+The full rules are in [Provider Enforcement](#provider-enforcement) and
+[Cursor evidence authority](#cursor-evidence-authority).
 
 ## Named Policy Choices
 
@@ -36,8 +82,11 @@ For the root-owned phase-agent loop, see
 
 A named `High` ceiling therefore keeps configured Economy, Balanced, and High
 candidates eligible and available. It does not pin Sol, `opus`, one Cursor
-string, or one effort value. The project root chooses one exact candidate it
-judges sufficient for the phase.
+string, or one effort value. (Model names on this page, such as Sol, Luna,
+Astra, Opus, Sonnet, and Fable, are provider models listed in the ladder that
+ships with OAT; they are examples, and your own ladder may list different
+models.) The project root, meaning the main agent session running the project,
+chooses one exact candidate it judges sufficient for the phase.
 
 `Uncapped` is explicit managed state. It is not represented by omitted policy
 state. `Unresolved` is a planning or preflight deferral and cannot begin
@@ -45,6 +94,18 @@ implementation.
 
 ## Ownership and Adoption
 
+**Who chose the bundled ladder.** OAT ships a recommended ladder, the bundled
+recommendation. OAT's maintainers choose which models go in each tier and in
+what order, using provider documentation, vendor benchmarks and their own
+model-selection guidance, and they refresh it as providers release new models
+(see [Updating Model Guidance](../../contributing/updating-model-guidance.md)).
+OAT has not compared these models on its own workloads, so treat the ladder as
+the maintainers' recommended starting point, not a measured ranking. Your team
+does not have to use it as shipped. You can adopt it and then edit any cell in
+the config file that owns it (see [Config Shapes](#config-shapes)), or write
+your own cells without adopting. Rerunning adoption later replaces edited cells
+unless you pass `--keep-existing`.
+
 Adopt the complete bundled recommendation into one explicit owning scope:
 
 ```bash
@@ -58,6 +119,10 @@ oat config adopt dispatch-matrix --local
 oat config adopt dispatch-matrix --user
 ```
 
+With no scope flag, `oat config adopt dispatch-matrix` writes repo-local config
+(`.oat/config.local.json`), the same as `--local`. The examples on this page
+pass a flag so the owning scope is always explicit.
+
 Adoption replaces populated cells from the bundled recommendation in the
 chosen scope, fills missing cells, and retains extra custom tiers when the
 bundled provider remains a tier map. A bundled provider-level scalar replaces
@@ -87,9 +152,10 @@ Run the same command without `--dry-run` to replace bundled cells. Use
 
 Version `2026-10-01.1` is the current bundled recommendation. It prefers
 GPT-6 Luna and GPT-6.1 Sol in Codex, then Sol 6.1 xhigh, Astra high, and Astra xhigh in
-Codex Frontier. Astra's task advantage has not been measured locally; this is
-an explicit user-directed preference, not acceptance by the separately
-maintained model-selection policy. Sonnet 5.5 medium replaces Sonnet 5 medium
+Codex Frontier. OAT's maintainers added the Astra entries as a preference:
+public benchmarks show task-dependent gains for Astra over GPT-6 Sol, but OAT
+has not tested Astra on its own workloads, and the maintainers' separate
+model-selection review has not yet confirmed the choice. Sonnet 5.5 medium replaces Sonnet 5 medium
 in Claude Economy; the older generation stays supported for explicit cells.
 Opus 5.5 low/medium/high remains in Claude High.
 The Claude low option suits bounded intelligent recon in Balanced or High;
@@ -100,9 +166,9 @@ Opus 5.5 low above Terra high, High orders Sol medium, Opus low, Sol high,
 Opus medium, then Opus high, and Frontier places Opus high and xhigh between
 Sol max and Fable 5.1. Grok 4.6 medium replaces Grok 4.5 high at the bottom of
 Balanced, and Fable 5.1 thinking high replaces Fable 5 as Frontier's terminal
-target. The ordering is an explicit user-directed preference informed by
-vendor benchmarks and the model-selection matrix, not a local workload
-comparison. Grok 4.5 and Fable 5 stay supported for explicit configurations.
+target. OAT's maintainers chose this ordering using vendor benchmarks and their
+model-selection guidance; it is not the result of comparing models on OAT's own
+workloads. Grok 4.5 and Fable 5 stay supported for explicit configurations.
 Rerunning adoption replaces the bundled cells in the chosen scope; use
 `--keep-existing` to preserve explicit older cells. For the complete
 maintenance procedure, see
@@ -455,9 +521,8 @@ defaults to `xhigh`. A typo in a pinned selector therefore ships a
 working-but-wrong model that silently tracks a vendor-controlled default, so
 capability can change with no corresponding change in the repository.
 
-OAT does not currently validate effort rungs at sync time; that is tracked as
-`BL-260726-validate-cursor-pin-effort`. Until it lands, the probe runbook is
-the only guard.
+OAT does not currently validate effort rungs at sync time; that check is
+planned but not yet built. Until it is, the probe runbook is the only guard.
 
 ## Phase and Optional-Worker Layers
 
@@ -476,7 +541,7 @@ tasks and do not own phase commits or review dispatch.
 Tasks run serially in the same worktree. Parallelism remains limited to
 plan-declared phase worktrees unless optional work has explicitly isolated
 write authority. See
-[Implementation Execution](implementation-execution.md) for the full loop.
+[Implementation Execution](../projects/execution/implementation-execution.md) for the full loop.
 
 ## Dispatch Report V1 and Producer Provenance
 
@@ -585,7 +650,87 @@ The following remain readable during migration:
 - project `oat_dispatch_ceiling`
 - `--preferred` resolver selection
 
-Legacy preset names map to managed named tiers: `cost-conscious` to Economy,
-`balanced` to Balanced, and `maximum` to High. Legacy values are migration
-inputs, not evidence that a new project should persist exact provider-family
-pins.
+Legacy presets (`cost-conscious`, `balanced`, `maximum`) compile to bare legacy
+provider ceilings, not complete named candidate tiers. Their values can resemble
+tier caps without supplying a ladder. They remain migration inputs, not evidence
+that a new project should persist exact provider-family pins.
+
+## Choosing policy and ladder ownership
+
+The dispatch policy decides how strong (and how expensive) the models that OAT
+starts for each phase and review may be. A **ladder** is the configured list of
+model and effort candidates for each provider, grouped into four tiers from
+Economy to Frontier. The policy sets the highest tier a project may use.
+Planning asks you for the policy and saves it in the project's `state.md`.
+
+> [!WARNING]
+> A dispatch policy set in any config file (`workflow.dispatchPolicy.*`, or a
+> legacy plain value in `workflow.dispatchCeiling.providers.<provider>`)
+> overrides the policy every project chose for itself in `state.md`. To let each
+> project choose its own policy, leave those keys unset. Adopting a ladder is a
+> separate step from setting a policy.
+
+| Policy             | Choose it when                                         | What you give up                                                           |
+| ------------------ | ------------------------------------------------------ | -------------------------------------------------------------------------- |
+| Economy / Balanced | Routine or normal work where cost matters              | The higher tiers                                                           |
+| High / Frontier    | Broad, security-sensitive, or consequential changes    | Cost: implementation code reviews run on the cap tier, which can cost more |
+| Uncapped           | You trust the main session to choose a model per phase | Any tier ceiling on cost. You must choose it explicitly                    |
+| Inherit            | The provider's own model settings must stay untouched  | All OAT model control: OAT passes no model or effort setting               |
+
+There is no default policy, and a missing policy never means Uncapped. If a
+project has none when implementation starts, an interactive run asks you and a
+non-interactive run stops. The agents that implement a phase may use a lower
+tier than the cap, but when a cap is set, the per-phase and final code reviews
+always use the last candidate listed in the cap tier. Planning-artifact reviews
+and gates choose their reviewers separately.
+
+- If you are trying OAT for the first time, choose Balanced for the project.
+- If cost matters most, choose Economy for routine work or Balanced for normal
+  work.
+- If the change is high-risk, choose High. Choose Frontier only if you want
+  every implementation code review to run on Frontier's last candidate. For a
+  reviewer from a different model family, add a
+  [gate](workflow-gates.md#choosing-gate-posture) instead.
+- If the provider's own settings must stay untouched, choose Inherit.
+
+### Which tier for which work
+
+The tier is a cap, not a target: for each phase the main session still picks
+one candidate at or below it. A Dispatch Profile row is an optional per-phase
+limit in `plan.md` that can lower the cap for one phase.
+
+| Work                                                                                              | Tier to start with                                                                                     | What the tier limits                                                                                                                                                                                          | Cost and speed direction                                      |
+| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| Routine, bounded work: one component and a clear outcome, such as a bug fix                       | Balanced, or Economy if cost matters most                                                              | Phase agents use only Economy and Balanced candidates. Per-phase and final code reviews run on the last Balanced candidate                                                                                    | Lower cost; usually faster                                    |
+| Ambiguous or cross-cutting work: a broad change across several components                         | High                                                                                                   | Economy through High candidates are eligible. Code reviews run on the last High candidate                                                                                                                     | Higher, because every implementation code review runs at High |
+| Consequential or high-risk change: security-sensitive, or a missed defect costs more than the run | High. Choose Frontier only if every implementation code review should run on Frontier's last candidate | At Frontier all four tiers are eligible, and its last candidate may need model access your account lacks. For a reviewer from a different model family, add a [gate](workflow-gates.md#choosing-gate-posture) | Higher at High; highest and usually slowest at Frontier       |
+| Cost-sensitive team                                                                               | Economy for routine work and Balanced for normal work, set per project                                 | Economy allows only Economy candidates. A Dispatch Profile row can lower one phase, but code reviews still run at the project cap                                                                             | Lowest of the managed tiers                                   |
+
+OAT sets no prices and does not measure cost or speed. What a run costs depends
+on your provider plan and on the models in your ladder. The directions above
+assume a ladder ordered like the bundled one, where higher tiers hold larger
+models or higher effort settings, which usually cost more per run and take
+longer.
+
+### Where the ladder lives
+
+`oat config adopt dispatch-matrix` writes the bundled ladder to the config scope
+you choose, and to repo-local config if you pass no flag. Without
+`--keep-existing` it replaces cells you already set, so preview with `--dry-run`
+first.
+
+- If you are rolling OAT out to a team, adopt the ladder with `--shared` so
+  everyone uses the same candidates and the change is reviewed in Git.
+- If you are trying OAT alone, run `oat config adopt dispatch-matrix --user
+--dry-run`, then rerun it without `--dry-run`. A shared or repo-local ladder
+  in a repository still overrides your user ladder there.
+- If you are testing candidates in one checkout, use `--local`. After
+  `oat sync`, the agent roles generated from it still appear in the tracked
+  `.codex`, `.claude`, and `.cursor` folders, so check `git status` before
+  committing.
+
+How firmly the cap holds depends on the provider. Codex and Claude enforce the
+model and effort that OAT selects. Cursor pins mapped candidates, but OAT
+cannot confirm at run time which model actually ran, so it records what it
+requested. Other providers treat the cap as a suggestion only. See
+[Provider Enforcement](#provider-enforcement).

package/assets/docs/workflows/{projects → advanced}/evidence-layers.md

@@ -19,21 +19,28 @@ never gates a conclusion on its own.
 
 ## Layer map
 
-```mermaid
-flowchart TD
-  L1["Layer 1 — Policy resolution\nnamed ceiling · candidates · capped/uncapped mode"]
-  L2["Layer 2 — Launcher-owned configured invocation\nroute · target/model/effort axes · selection reason ·\ncandidates considered · launch acceptance"]
-  L3["Layer 3 — Runtime-observed identity (optional)\nproducer + model, only under trusted provenance"]
+=== "Diagram"
 
-  L1 --> L2 --> L3
+    ![Three evidence layers: policy resolution, launcher-owned configured invocation, and optional runtime-observed identity; assertions check layers 1 and 2 and only record layer 3, which resolves to reported or not-reported](/diagrams/evidence-layers-light.svg)
+    ![Three evidence layers: policy resolution, launcher-owned configured invocation, and optional runtime-observed identity; assertions check layers 1 and 2 and only record layer 3, which resolves to reported or not-reported](/diagrams/evidence-layers-dark.svg)
 
-  A["Assertions"] -->|assert on| L1
-  A -->|assert on| L2
-  A -.->|record only| L3
+=== "Mermaid source"
 
-  L3 --> R["reported\n(both present + trusted provenance)"]
-  L3 --> NR["not-reported\n(anything else normalizes here)"]
-```
+    ```mermaid
+    flowchart TD
+      L1["Layer 1 — Policy resolution\nnamed ceiling · candidates · capped/uncapped mode"]
+      L2["Layer 2 — Launcher-owned configured invocation\nroute · target/model/effort axes · selection reason ·\ncandidates considered · launch acceptance"]
+      L3["Layer 3 — Runtime-observed identity (optional)\nproducer + model, only under trusted provenance"]
+
+      L1 --> L2 --> L3
+
+      A["Assertions"] -->|assert on| L1
+      A -->|assert on| L2
+      A -.->|record only| L3
+
+      L3 --> R["reported\n(both present + trusted provenance)"]
+      L3 --> NR["not-reported\n(anything else normalizes here)"]
+    ```
 
 Assertions bind to Layers 1 and 2. Layer 3 is recorded as `reported` or
 `not-reported`; its absence never invalidates Layer 2.
@@ -235,7 +242,7 @@ For how to run this end to end and when to refresh the fixture, see
   producer-provenance record that back Layers 1 and 2.
 - [Orchestration Model](orchestration-model.md) — the dispatch topology that
   produces these records.
-- [Review Flavors](review-flavors.md) — how the four review flavors are recorded
+- [Review Flavors](../projects/reviews/review-flavors.md) — how the four review flavors are recorded
   through the same launcher-owned evidence.
 - [Smoke testing](../../contributing/smoke-testing.md) — operating the evidence
   pipeline against real providers.

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

@@ -0,0 +1,19 @@
+---
+title: Advanced
+description: 'Dispatch, autonomy, execution surfaces, evidence layers and workflow gates.'
+---
+
+# Advanced
+
+Use these guides for advanced workflow execution and its safety boundaries.
+
+## Contents
+
+- [Worktree bootstrap](worktree-bootstrap.md) - Prepare an isolated checkout with repository-specific readiness checks.
+- [Workflow Gates](workflow-gates.md) - Completion-safe headless reviews, budgets, liveness evidence, and cross-runtime dispatch with `oat gate`.
+- [Autonomous Project Execution](autonomy.md) - Session-scoped autonomy signals, gate boundaries, review requirements, and execution learnings.
+- [OAT in Cursor Cloud](cursor-cloud.md) - Project-home, provisioning, asset-precedence, and execution-surface guidance for cloud agents.
+- [Dispatch Policy](dispatch-ceiling.md) - Managed capped tiers, managed Uncapped, Inherit Host Defaults, and provider-specific enforcement.
+- [Orchestration Model](orchestration-model.md) - The layered dispatch model: roles, selection flow, and per-harness topology.
+- [Evidence Layers](evidence-layers.md) - The three-layer dispatch evidence model behind records and smoke verification.
+- [Programmatic Execution](programmatic-execution.md) - Per-harness headless/CLI execution surfaces and where OAT uses them.

package/assets/docs/workflows/advanced/meta.json

@@ -0,0 +1,13 @@
+{
+  "title": "Advanced",
+  "pages": [
+    "worktree-bootstrap",
+    "workflow-gates",
+    "autonomy",
+    "cursor-cloud",
+    "dispatch-ceiling",
+    "orchestration-model",
+    "evidence-layers",
+    "programmatic-execution"
+  ]
+}

package/assets/docs/workflows/{projects → advanced}/orchestration-model.md

@@ -15,27 +15,46 @@ OAT separates lifecycle ownership from implementation ownership:
 This topology keeps model control at the meaningful phase boundary without
 making every task pay another dispatch and context-loading round.
 
+Terms used on this page:
+
+- **Phase:** one numbered section of a project's `plan.md` (for example `p02`)
+  that groups related tasks.
+- **Dispatch:** launching a worker or reviewer subagent on a chosen model and
+  route. The **dispatch policy** is the project's rule for which models those
+  subagents may use; see [Dispatch Policy](dispatch-ceiling.md).
+- **Worktree:** a separate Git checkout of the same repository on its own
+  branch, used so parallel phases do not overwrite each other's files.
+- **HiLL checkpoint:** a human-in-the-loop stop after a phase where an
+  interactive run waits for your approval.
+
 ## Default Topology
 
-```mermaid
-flowchart TD
-  Root["Project root\nlifecycle owner"]
-  Adapter["Project dispatch adapter"]
-  Engine["Provider-neutral dispatch engine"]
+=== "Diagram"
 
-  Root --> Adapter --> Engine
-  Engine --> P["Phase implementer\none per phase"]
-  P --> T1["Planned task commit"]
-  P --> T2["Planned task commit"]
-  P -. optional .-> Recon["Recon / specialist / isolated fanout"]
+    ![Default topology: the project root goes through the dispatch adapter and provider-neutral engine to one phase implementer per phase, which makes planned task commits and optionally a recon or specialist fanout; the engine routes an exact phase reviewer whose blocking findings return to the root, which resumes a bounded fix; dashed lanes show independent review and an external cross-runtime gate](/diagrams/orchestration-model-1-default-topology-light.svg)
+    ![Default topology: the project root goes through the dispatch adapter and provider-neutral engine to one phase implementer per phase, which makes planned task commits and optionally a recon or specialist fanout; the engine routes an exact phase reviewer whose blocking findings return to the root, which resumes a bounded fix; dashed lanes show independent review and an external cross-runtime gate](/diagrams/orchestration-model-1-default-topology-dark.svg)
 
-  Root -. independent review lane .-> Adapter
-  Engine -. exact reviewer route .-> R["Phase reviewer"]
-  R -->|blocking findings| Root
-  Root -->|resume bounded fix| P
+=== "Mermaid source"
 
-  Root -. external gate lane .-> G["Configured cross-runtime gate"]
-```
+    ```mermaid
+    flowchart TD
+      Root["Project root\nlifecycle owner"]
+      Adapter["Project dispatch adapter"]
+      Engine["Provider-neutral dispatch engine"]
+
+      Root --> Adapter --> Engine
+      Engine --> P["Phase implementer\none per phase"]
+      P --> T1["Planned task commit"]
+      P --> T2["Planned task commit"]
+      P -. optional .-> Recon["Recon / specialist / isolated fanout"]
+
+      Root -. independent review lane .-> Adapter
+      Engine -. exact reviewer route .-> R["Phase reviewer"]
+      R -->|blocking findings| Root
+      Root -->|resume bounded fix| P
+
+      Root -. external gate lane .-> G["Configured cross-runtime gate"]
+    ```
 
 The solid implementation lane is mandatory. The dotted nested lane is
 benefit-driven. A run does not fail merely because the phase agent cannot or
@@ -71,21 +90,28 @@ matrix. The lifecycle workflow remains authoritative for classification,
 selection judgment, synthesis, and state mutation. The dispatch engine does
 not edit `plan.md`, `implementation.md`, or project state.
 
-```mermaid
-sequenceDiagram
-  participant Root as Project root
-  participant Adapter as Project adapter
-  participant Engine as Dispatch engine
-  participant Record as Run record in implementation.md
-  participant Phase as Phase implementer
-
-  Root->>Adapter: Phase + lifecycle authority
-  Adapter->>Engine: Provider-neutral dispatch request
-  Engine-->>Root: Exact route + request ID
-  Root->>Phase: Phase Scope
-  Root->>Record: Accepted or blocked-before-start result
-  Phase-->>Root: Phase report + commits
-```
+=== "Diagram"
+
+    ![Dispatch layers sequence: the project root passes phase and lifecycle authority to the adapter, the adapter sends a provider-neutral request to the engine, the engine returns the exact route and request ID, the root sends the phase scope and records the accepted or blocked result in implementation.md, and the implementer returns its report and commits](/diagrams/orchestration-model-2-dispatch-layers-light.svg)
+    ![Dispatch layers sequence: the project root passes phase and lifecycle authority to the adapter, the adapter sends a provider-neutral request to the engine, the engine returns the exact route and request ID, the root sends the phase scope and records the accepted or blocked result in implementation.md, and the implementer returns its report and commits](/diagrams/orchestration-model-2-dispatch-layers-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    sequenceDiagram
+      participant Root as Project root
+      participant Adapter as Project adapter
+      participant Engine as Dispatch engine
+      participant Record as Run record in implementation.md
+      participant Phase as Phase implementer
+
+      Root->>Adapter: Phase + lifecycle authority
+      Adapter->>Engine: Provider-neutral dispatch request
+      Engine-->>Root: Exact route + request ID
+      Root->>Phase: Phase Scope
+      Root->>Record: Accepted or blocked-before-start result
+      Phase-->>Root: Phase report + commits
+    ```
 
 ## Phase Execution
 
@@ -103,7 +129,7 @@ The root verifies the report against Git rather than trusting child prose:
 - clean worktree; and
 - optional child records, if any.
 
-See [Implementation Execution](implementation-execution.md) for the executable
+See [Implementation Execution](../projects/execution/implementation-execution.md) for the executable
 contract.
 
 ## Independent Phase Review
@@ -172,7 +198,7 @@ terminated at its background-wait ceiling (600 seconds by default). Interactive
 Claude Code is unaffected. Headless gate children therefore do not follow the
 ordinary background preference; they use the gate's inline or synchronously
 awaited route and fail closed when neither is available. See
-[Workflow Gates](../../cli-utilities/workflow-gates.md#headless-completion-safety).
+[Workflow Gates](workflow-gates.md#headless-completion-safety).
 
 ## Catalogs and Exact Selection
 
@@ -229,9 +255,56 @@ optional child has explicitly isolated write authority.
 
 ## Related
 
-- [Implementation Execution](implementation-execution.md)
+- [Implementation Execution](../projects/execution/implementation-execution.md)
 - [Dispatch Policy](dispatch-ceiling.md)
-- [Review Flavors](review-flavors.md)
+- [Review Flavors](../projects/reviews/review-flavors.md)
 - [Programmatic Execution](programmatic-execution.md)
 - [Evidence Layers](evidence-layers.md)
 - [Workflow Smoke Testing](../../contributing/smoke-testing.md)
+
+## subagent-orchestration
+
+Use this skill to decide what to delegate and which capability class the task
+needs. It supplies model-selection guidance, not a command that launches workers.
+OAT's dispatch skills own capability checks, exact routes, acceptance records,
+and recovery.
+
+**Invocation:** Give the agent a bounded delegation decision. The slash form is
+a skill request, not a terminal command. Providers with `$` syntax use
+`$subagent-orchestration`.
+
+```text
+/subagent-orchestration
+Classify a read-only API-usage audit and a final approval-provenance review. Define their scopes, required evidence, and escalation conditions before selecting models.
+```
+
+**Prerequisites:** Needs an active OAT project: no. The guidance is
+self-contained and needs no OAT project or installation. You need the task's
+objective, authority, verification needs, and active provider context. Read
+exactly that provider's selection reference. Current catalogs and instructions
+outrank dated model examples.
+
+**What it does without asking:** nothing outside the conversation. The skill
+is guidance only: it writes no files, makes no commits, and launches no
+subagents. Any launch happens later, through the dispatch skills, under their
+own checks.
+
+**Example scenario:** A root agent needs an unfamiliar API audit and an
+independent review of approval handling. The audit needs intelligent
+reconnaissance because a missed usage could be silent. Approval provenance
+needs consequential review because a subtle miss could authorize unsafe work.
+The root keeps authorization and cross-scope judgment while defining each
+worker's output and evidence. Choosing a stronger model does not repair an
+over-broad assignment.
+
+**Expected output:** A routing decision states the task class, role, exact model
+selector, provider-native effort, service tier, route, and authority separately.
+It preserves each class's capability floor and names escalation conditions.
+Load-bearing worker claims require verified evidence before the root acts on
+them. File count or duration alone does not justify a higher reasoning class.
+
+**Next step:** Use the appropriate dispatch machinery only after the bounded
+scope and route are justified. Within OAT, follow the project adapter
+(`oat-project-dispatch-subagents`) and the dispatch engine
+(`oat-dispatch-subagents`). Guidance alone is not evidence that a worker launched or that
+its result passed review.

package/assets/docs/workflows/{projects → advanced}/programmatic-execution.md

@@ -77,14 +77,14 @@ independent of the harness's native subagent catalog — the point of a gate is
 route the producing context could not have selected for itself. The
 lifecycle/final gate is the one flavor that may spawn a **nested managed
 reviewer child inside the gate exec target**; see
-[Review Flavors](review-flavors.md) for which flavor fires when and how
+[Review Flavors](../projects/reviews/review-flavors.md) for which flavor fires when and how
 independent each must be.
 
 Gates **fail closed**. If no different-family target is available, OAT records
 the degraded achieved level rather than pretending diversity was achieved, and
 an unavailable required-independent target blocks the gate instead of quietly
 downgrading to a same-context self-review. Only summarize the execution-surface
-angle here — see [Workflow Gates](../../cli-utilities/workflow-gates.md) for the
+angle here — see [Workflow Gates](workflow-gates.md) for the
 gate envelope, exec-target configuration, receive-eligibility, and completion
 contract. The cross-runtime `gates.execTargets` design (host-avoidance and
 independence from native catalogs) is the smoke fixture's cross-runtime gate
@@ -126,13 +126,13 @@ require either capability.
 
 - [Orchestration Model](orchestration-model.md) — route tiers, native-first
   selection, and per-harness topology.
-- [Review Flavors](review-flavors.md) — the four review flavors and which one
+- [Review Flavors](../projects/reviews/review-flavors.md) — the four review flavors and which one
   may spawn a nested managed reviewer inside a gate.
 - [Evidence Layers](evidence-layers.md) — the three-layer dispatch evidence
   model these launches feed.
 - [Dispatch Policy](dispatch-ceiling.md) — candidate ladders, named ceilings,
   and the dispatch report.
-- [Workflow Gates](../../cli-utilities/workflow-gates.md) — gate envelope,
+- [Workflow Gates](workflow-gates.md) — gate envelope,
   exec-target configuration, and completion contract.
 - [Smoke Testing](../../contributing/smoke-testing.md) — per-harness drive
   protocols and live evidence.