@open-agent-toolkit/cli 0.1.41 → 0.1.43

package/assets/docs/workflows/projects/dispatch-ceiling.md

@@ -1,134 +1,177 @@
 ---
-title: Dispatch Ceiling
-description: "How OAT's provider-neutral dispatch ceiling works — presets, the compile/resolve flow, and how enforcement differs for Codex, Claude, and unsupported providers."
+title: Dispatch Policy
+description: 'How OAT dispatch policy works: managed capped tiers, managed Uncapped, Inherit Host Defaults, legacy dispatch-ceiling compatibility, and provider-specific enforcement.'
 ---
 
-# Dispatch Ceiling
+# Dispatch Policy
 
-The **dispatch ceiling** is the most capable tier OAT is allowed to use when it dispatches subagents (phase implementers and reviewers) during `oat-project-implement`. It is a **provider-neutral OAT intent** — your declaration of "don't go above this," decoupled from which provider you happen to be running. OAT then applies that intent through whatever mechanism each provider actually exposes.
+OAT dispatch policy controls how `oat-project-implement` selects model or
+effort controls for phase implementers, fix loops, and reviewers. The current
+contract separates two ideas that used to be conflated:
 
-This page explains the model, the why, and — most importantly — how enforcement differs across providers. For the raw config keys see [Configuration](../../cli-utilities/configuration.md); for how dispatch runs at execution time see [Implementation Execution](implementation-execution.md).
+- **Managed policies** keep OAT responsible for selecting model/effort controls.
+- **Inherit Host Defaults** tells OAT not to select model/effort controls and to
+  let the executing host/provider decide.
 
-## Two principles
+The CLI command is still named `oat project dispatch-ceiling resolve` for
+compatibility, and legacy `workflow.dispatchCeiling.*` / `oat_dispatch_ceiling`
+state is still readable as capped managed input. New configuration should use
+dispatch policy terminology.
 
-1. **Presets are convenience only — they compile to concrete values at _write_ time.** A fuzzy label like `balanced` is never read at dispatch; it is expanded into concrete per-provider values the moment you set it.
-2. **Enforcement capability is computed at dispatch, never stored.** Whether a ceiling is _enforced_, _advisory_, or _unsupported_ is a property of the provider × runtime, so OAT recomputes it on every run rather than persisting a value that would go stale.
+For raw config keys see [Configuration](../../cli-utilities/configuration.md);
+for execution-time behavior see [Implementation Execution](implementation-execution.md).
 
-## Setting a ceiling
+## Policy Choices
 
-Set it via `oat config set` (repo / user / local) or answer the planning/implementation preflight prompt. Three shapes:
+| Policy                  | Mode    | Codex target | Claude target | Meaning                                      |
+| ----------------------- | ------- | ------------ | ------------- | -------------------------------------------- |
+| `Economy`               | managed | `medium`     | `sonnet`      | Lower-cost managed cap                       |
+| `Balanced`              | managed | `high`       | `sonnet`      | Default managed cap                          |
+| `High`                  | managed | `xhigh`      | `opus`        | High-capability managed cap                  |
+| `Frontier`              | managed | `xhigh`      | `fable`       | Top managed tier currently exposed by OAT    |
+| `Uncapped`              | managed | none         | none          | OAT selects preferred controls without a cap |
+| `Inherit Host Defaults` | inherit | none         | none          | OAT does not select model/effort controls    |
 
-| Choice                                                 | What gets written                                                      |
-| ------------------------------------------------------ | ---------------------------------------------------------------------- |
-| **Preset** — `balanced` / `maximum` / `cost-conscious` | The preset label (provenance) **and** the compiled per-provider values |
-| **Advanced** — set providers directly                  | `providers.*` only (no `preset` key)                                   |
-| **No ceiling**                                         | Nothing — each provider runs at its normal/inherited behavior          |
+`Uncapped` is explicit managed state. It is not represented by omitting policy
+state. Existing projects with absent legacy ceiling state remain unresolved or
+legacy-compatible; they do not silently become managed `Uncapped`.
 
-The fixed preset table:
+## Config Shapes
 
-| Preset         | Codex    | Claude   |
-| -------------- | -------- | -------- |
-| Balanced       | `high`   | `sonnet` |
-| Maximum        | `xhigh`  | `opus`   |
-| Cost-conscious | `medium` | `sonnet` |
+Preferred managed policy config:
 
-`cost-conscious` deliberately keeps Claude at `sonnet` (no `haiku` reviewers by default) so review quality stays trustworthy.
+```bash
+oat config set workflow.dispatchPolicy.policy balanced --shared
+oat config set workflow.dispatchPolicy.policy frontier --shared
+oat config set workflow.dispatchPolicy.policy uncapped --shared
+```
 
-Config keys:
-
-- `workflow.dispatchCeiling.preset`
-- `workflow.dispatchCeiling.providers.codex` (`low` \| `medium` \| `high` \| `xhigh`)
-- `workflow.dispatchCeiling.providers.claude` (`haiku` \| `sonnet` \| `opus`)
+`workflow.dispatchPolicy.policy` writes `workflow.dispatchPolicy.mode=managed`.
+To request host defaults:
 
 ```bash
-# A preset compiles immediately to concrete per-provider values:
-oat config set workflow.dispatchCeiling.preset balanced --shared
-# → stores preset: balanced AND providers: { codex: high, claude: sonnet }
+oat config set workflow.dispatchPolicy.mode inherit --shared
+```
 
-# Or set providers directly (advanced — no preset key stored):
-oat config set workflow.dispatchCeiling.providers.codex high --shared
+Project state uses the same shape:
+
+```yaml
+oat_dispatch_policy:
+  mode: managed
+  policy: balanced
+  providers:
+    codex: high
+    claude: sonnet
+  source: project-state
 ```
 
-Project state can persist the compiled answer as `oat_dispatch_ceiling` (`preset?` + `providers` + `source`) so a planning/preflight choice carries into implementation.
+For `Uncapped`, omit provider caps:
+
+```yaml
+oat_dispatch_policy:
+  mode: managed
+  policy: uncapped
+  source: project-state
+```
 
-> The earlier flat `workflow.dispatchCeiling.codex` / `.claude` keys were removed. This was a clean break with no migration — set the new keys above.
+For host defaults:
+
+```yaml
+oat_dispatch_policy:
+  mode: inherit
+  source: project-state
+```
 
-## How it resolves at dispatch
+Legacy compatibility keys remain readable:
+
+- `workflow.dispatchCeiling.preset`
+- `workflow.dispatchCeiling.providers.codex`
+- `workflow.dispatchCeiling.providers.claude`
+- `oat_dispatch_ceiling`
+
+Legacy preset names map into the managed ladder: `cost-conscious` maps to
+`Economy`, `balanced` maps to `Balanced`, and `maximum` maps to `High`.
+
+## How Resolution Works
 
 Before dispatching a subagent, the orchestrator calls:
 
 ```bash
-oat project dispatch-ceiling resolve --provider <provider> --role <implementer|reviewer> --preflight --json
+oat project dispatch-ceiling resolve --provider <provider> --role <implementer|reviewer> --json
 ```
 
-For implementer or fix dispatch, pass the runtime classification too. In Codex
-this is the preferred effort; in Claude it is the preferred model tier:
+For implementer or fix dispatch, pass the preferred runtime control:
 
 ```bash
-oat project dispatch-ceiling resolve --provider codex --role implementer --preferred medium --json
-oat project dispatch-ceiling resolve --provider claude --role implementer --preferred sonnet --json
+oat project dispatch-ceiling resolve --provider codex --role implementer --preferred high --json
+oat project dispatch-ceiling resolve --provider claude --role implementer --preferred opus --json
 ```
 
-The resolver:
-
-1. reads the concrete `providers.<provider>` value (config precedence, then project state) — **never the preset label**;
-2. looks up that provider's **adapter** in the provider ceiling registry;
-3. applies `--preferred` for implementer/fix dispatch, capping it against the ceiling;
-4. returns a per-provider result: `{ value, mode, mechanism, dispatchArgs, selection }`.
+The resolver returns the resolved policy, optional cap, source, provider default
+effort where applicable, and provider-specific `dispatchArgs`.
 
-`mode` is the honest enforcement status, computed right there and never persisted:
+Selection modes:
 
-- **enforced** — the provider has a real mechanism and OAT dispatched the requested control.
-- **advisory** — the ceiling is recorded as intent, but the provider can't deterministically enforce it (or an above-orchestrator request couldn't be honored).
-- **unsupported** — no adapter mechanism exists for that provider.
+- `capped` - implementer/fix dispatch selects `min(preferred, cap)`.
+- `uncapped` - implementer/fix dispatch selects the preferred value.
+- `review-target` - reviewer dispatch targets a configured cap when one exists.
+- `no-review-target` - managed uncapped reviewer dispatch has no configured
+  target and falls back to the base/unpinned reviewer.
+- `inherit-default` - OAT returns no dispatch args and leaves controls to the host.
+- `unresolved` - non-interactive implementation blocks before work starts.
 
-## Per-provider behavior
+## Provider Behavior
 
-The same ceiling intent produces different — but honest — behavior per provider, because each adapter declares its own mechanism.
+|                   | Codex                                       | Claude Code                             | Unsupported provider |
+| ----------------- | ------------------------------------------- | --------------------------------------- | -------------------- |
+| Managed mechanism | Pinned role variants                        | Task `model` argument                   | None                 |
+| Axis              | effort (`low < medium < high < xhigh`)      | model (`haiku < sonnet < opus < fable`) | None                 |
+| Capped policy     | selected pinned variant up to cap           | selected Task model up to cap           | advisory/unsupported |
+| Uncapped          | preferred pinned variant, no cap            | preferred Task model, no cap            | advisory/unsupported |
+| Inherit/default   | base/unpinned role follows provider default | omit `model`                            | normal behavior      |
 
-|                   | **Codex**                                                                                         | **Claude**                             | **Unsupported provider**   |
-| ----------------- | ------------------------------------------------------------------------------------------------- | -------------------------------------- | -------------------------- |
-| Can OAT enforce?  | Yes                                                                                               | Yes                                    | No (no adapter yet)        |
-| Mechanism         | Pinned variant files                                                                              | Per-call Task `model` argument         | None                       |
-| Where it lives    | Sync-time committed `.codex` role variants (`oat-phase-implementer-high`, `oat-reviewer-high`, …) | Passed at dispatch time — **no files** | —                          |
-| Axis              | effort (`low < medium < high < xhigh`)                                                            | model tier (`haiku < sonnet < opus`)   | —                          |
-| `dispatchArgs`    | `{ variant: "oat-reviewer-high" }`                                                                | `{ model: "sonnet" }`                  | `null`                     |
-| `mode`            | `enforced`                                                                                        | `enforced`                             | `advisory` / `unsupported` |
-| If no ceiling set | base/unpinned role (provider default)                                                             | inherits the orchestrator's model      | normal behavior            |
+Codex uses pinned variants because per-call effort controls were unreliable in
+dogfooding. For managed `Uncapped`, OAT still selects the preferred pinned
+variant; the dispatching host should verify whether upward effort selection is
+actually honored in the current session.
 
-### Why the mechanisms differ
+Claude Code uses the per-call Task `model` argument. It has no OAT-managed
+per-dispatch effort axis, so dispatch logs use `effort_axis=not-applicable`.
+`Frontier` maps to Claude `fable`.
 
-- **Codex** dispatches through **pinned, sync-time role variants**. Per-call reasoning-effort proved unreliable in practice, so OAT generates committed `oat-phase-implementer-{low..xhigh}` / `oat-reviewer-{low..xhigh}` role files. Implementer/fix dispatch passes `--preferred` so `dispatchArgs.variant` matches the selected capped effort; reviewer dispatch uses the variant matching the resolved ceiling.
-- **Claude** uses the **per-call Task `model` parameter**, which is reliable and bidirectional (a Sonnet orchestrator can dispatch an Opus subagent and vice-versa) and overrides agent frontmatter. Implementer/fix dispatch passes `--preferred` as the preferred model tier and receives the capped selected `model`; reviewer dispatch uses the ceiling model. OAT needs no variant files.
-- **Unsupported providers** (any without a registered adapter) resolve to `unsupported` with `dispatchArgs: null`. The resolve command **returns cleanly and never blocks** — the ceiling is recorded as intent and applied if/when an adapter ships, while the provider runs at its own capabilities.
+## Implementer, Fix, and Reviewer Behavior
 
-A **provider adapter registry** is what lets these genuinely different mechanisms sit behind one resolver, so the lifecycle skills consume `dispatchArgs` without ever branching on provider.
+For implementer and fix dispatches:
 
-## Cap vs target: implementer vs reviewer
+- Capped managed policies select `min(preferred, cap)`.
+- Managed `Uncapped` selects the preferred value without a cap.
+- Inherit/default mode returns no model/effort dispatch args.
 
-The ceiling means slightly different things for the two dispatch roles:
+For reviewer dispatches:
 
-- **Implementer** runs at `min(preferred, ceiling)` — the ceiling is a **cap**. A simple phase may run below it.
-- **Reviewer** runs **at** the ceiling — a **target** — so quality gates are deterministic.
+- Capped managed policies target the configured cap for deterministic review
+  quality gates.
+- Managed `Uncapped` has no reviewer cap, so OAT uses the base/unpinned reviewer
+  fallback and logs provider-default behavior.
+- Inherit/default mode also uses the base/unpinned reviewer fallback.
 
-Both providers honor this distinction (Codex selects the matching variant; Claude passes the matching model).
+Generic sidecars such as `explorer` are outside the implementer/reviewer/fix
+contract. If their payload does not pin a reliable provider control, logs should
+say `provider-default`.
 
-Generic sidecars such as built-in `explorer` are outside this implementer/reviewer/fix contract. They may run at provider default when they are read-only advisory helpers. In that case, dispatch logs should say `Preferred effort: provider-default`, `Selected effort: provider-default`, and `Effort axis: provider-default`; only log a concrete selected effort when the actual sidecar payload pins a reliable provider control.
+## Dispatch Logs
 
-## Verify-on-upgrade
-
-Only a request for a tier **above** the orchestrator's current tier risks a silent plan/entitlement fallback. So the adapter verifies the actually-dispatched model **only** on that upgrade path; capping down or staying lateral needs no check. OAT never logs `enforced` unless the requested control was actually honored.
-
-## Dispatch logs
-
-OAT logs the honest enforcement state per dispatch, for example:
+Examples:
 
 ```text
-Dispatch ceiling: high (codex, enforced — variant oat-reviewer-high)
-Dispatch ceiling: sonnet (claude, enforced — Task model arg)
-Dispatch ceiling: balanced (cursor, unsupported — no adapter; informational)
+Dispatch policy: balanced; selected=high; cap=high (codex, enforced — variant oat-phase-implementer-high)
+Dispatch policy: high; selected=xhigh; cap=xhigh (codex, enforced — variant oat-reviewer-xhigh)
+Dispatch policy: uncapped; selected=xhigh; cap=none (codex, enforced — variant oat-phase-implementer-xhigh)
+Dispatch policy: inherit host defaults; selected=none; cap=none (codex, advisory — base role follows provider default)
+Dispatch policy: frontier; selected=fable; cap=fable (claude, enforced — Task model arg)
 ```
 
-## Summary
-
-You declare intent once (a preset, explicit per-provider values, or nothing). Under Codex it becomes deterministic pinned variants; under Claude it becomes a per-call Task `model` argument; under any other provider it is recorded as advisory and that provider runs normally. The logs tell you honestly whether the ceiling was `enforced`, `advisory`, or `unsupported` — one provider-neutral knob that enforces where it can and degrades gracefully where it can't.
+OAT logs `enforced` only when the provider accepted the requested control.
+Above-orchestrator Claude upgrade requests may require post-dispatch
+verification. Unsupported providers do not block; OAT records the policy as
+advisory/unsupported and dispatch follows provider behavior.

package/assets/docs/workflows/projects/hill-checkpoints.md

@@ -10,6 +10,8 @@ OAT supports two checkpoint classes:
 - Workflow phase checkpoints
 - Plan phase checkpoints
 
+The [phase review gate](reviews.md#phase-review-gate) (`oat_phase_review_gate`) is a separate, non-pausing mechanism — it does not pause on a passing gate and never modifies the HiLL keys below (`oat_hill_completed`, `oat_plan_hill_phases`).
+
 ## Workflow checkpoints (`state.md`)
 
 Frontmatter keys:

package/assets/docs/workflows/projects/implementation-execution.md

@@ -12,8 +12,8 @@ This page covers how `oat-project-implement` actually runs a plan: tier selectio
 - **When to use:** you have a plan ready and want to understand what happens during `oat-project-implement`.
 - **Unit of dispatch:** one phase at a time (not one task). A phase implementer executes all tasks in the phase, commits per task, and returns a single summary.
 - **Two tiers, one lock:** capability detection picks Tier 1 (native subagents) or Tier 2 (inline) at start. The tier is locked for the whole run — no mid-run downgrades.
-- **Dispatch ceiling:** implementation resolves an OAT-owned, provider-neutral ceiling before work starts. A ceiling is set as a preset (`balanced`, `maximum`, `cost-conscious`) or per-provider advanced values; runtime dispatch reads only the compiled concrete values. Codex uses effort values (`low`, `medium`, `high`, `xhigh`); Claude uses model tiers (`haiku`, `sonnet`, `opus`).
-- **Runtime dispatch:** each phase uses the lowest available model/effort/control that can confidently complete the work, capped by the resolved dispatch ceiling, unless `plan.md` includes an explicit Dispatch Profile override.
+- **Dispatch policy:** implementation resolves an OAT-owned dispatch policy before work starts. Managed policies are `Economy`, `Balanced`, `High`, `Frontier`, and `Uncapped`; `Inherit Host Defaults` explicitly leaves model/effort controls to the host.
+- **Runtime dispatch:** each phase uses the lowest available model/effort/control that can confidently complete the work. Capped managed policies cap preferred selections, managed `Uncapped` uses preferred selections directly, and inherit/default mode uses no OAT-selected control.
 
 ## Execution model
 
@@ -35,11 +35,11 @@ The selected tier is reported to the user and locked for the remainder of the ru
   → Selected: Tier 1 — Subagents
 ```
 
-### Dispatch ceiling preflight
+### Dispatch policy preflight
 
-Before phase work starts, `oat-project-implement` resolves and prints the dispatch ceiling for the current provider. For the conceptual model and per-provider enforcement (Codex vs Claude vs unsupported), see [Dispatch Ceiling](dispatch-ceiling.md).
+Before phase work starts, `oat-project-implement` resolves and prints the dispatch policy for the current provider. For the conceptual model and per-provider enforcement (Codex vs Claude vs unsupported), see [Dispatch Policy](dispatch-ceiling.md).
 
-The compiled resolver is the source of truth:
+The resolver is the source of truth. The command name remains `dispatch-ceiling` for compatibility:
 
 ```bash
 oat project dispatch-ceiling resolve --provider codex --preflight --json
@@ -47,46 +47,50 @@ oat project dispatch-ceiling resolve --provider codex --preflight --json
 
 Resolution order:
 
-1. `workflow.dispatchCeiling.providers.<provider>` from effective config
-2. `oat_dispatch_ceiling` in project `state.md` frontmatter
-3. Interactive implementation preflight prompt
-4. Non-interactive unresolved state blocks before work starts
+1. `workflow.dispatchPolicy.mode` / `workflow.dispatchPolicy.policy` from effective config
+2. Compatibility `workflow.dispatchCeiling.providers.<provider>` from effective config
+3. `oat_dispatch_policy` in project `state.md` frontmatter
+4. Legacy `oat_dispatch_ceiling` in project `state.md` frontmatter
+5. Interactive implementation preflight prompt
+6. Non-interactive unresolved state blocks before work starts
 
-The ceiling is set via a preset or Advanced per-provider values. Runtime dispatch reads the compiled concrete provider values only — never the preset label. If no ceiling is configured, the interactive preflight prompt offers the preset choices; non-interactive mode blocks.
+Runtime dispatch reads the resolved policy and provider-specific selection only. If no policy is configured, the interactive preflight prompt offers the policy choices; non-interactive mode blocks.
 
-**Preset options (interactive prompt):**
+**Policy options (interactive prompt):**
 
-| Option         | Codex            | Claude           |
-| -------------- | ---------------- | ---------------- |
-| Balanced       | `high`           | `sonnet`         |
-| Maximum        | `xhigh`          | `opus`           |
-| Cost-conscious | `medium`         | `sonnet`         |
-| Advanced       | per-provider     | per-provider     |
-| No ceiling     | provider default | provider default |
+| Option                | Mode    | Codex    | Claude   |
+| --------------------- | ------- | -------- | -------- |
+| Economy               | managed | `medium` | `sonnet` |
+| Balanced              | managed | `high`   | `sonnet` |
+| High                  | managed | `xhigh`  | `opus`   |
+| Frontier              | managed | `xhigh`  | `fable`  |
+| Uncapped              | managed | none     | none     |
+| Inherit Host Defaults | inherit | none     | none     |
 
-For Codex, provider default effort is displayed when available but is not treated as the OAT ceiling. Provider default only explains base/unpinned role behavior.
+For Codex, provider default effort is displayed when available but is not treated as managed `Uncapped` or as a cap. Provider defaults apply only to explicit inherit/default behavior or base/unpinned fallback paths.
 
 ```text
-Dispatch ceiling: high (codex, enforced — variant oat-phase-implementer-high)
-Source: project state  |  Preset: balanced
+Dispatch policy: balanced (codex, managed capped — pinned-variant)
+Resolved cap: high
+Source: project state
 Provider default effort: medium
-Note: OAT will use pinned subagent variants up to high. Base/unpinned roles resolve through the provider default.
+Note: OAT will use pinned subagent variants up to high. Base/unpinned roles resolve through the provider default only on fallback paths.
 ```
 
 **Enforcement modes** (from resolver):
 
 - `enforced` — the adapter compiled concrete dispatch args and the provider accepted them (Codex: pinned variants; Claude: Task `model` parameter).
 - `advisory` — the provider is supported but no value resolved, or an upgrade request was not honored by the provider.
-- `unsupported` — the provider has no registered adapter; the ceiling is informational only. Dispatch follows provider defaults.
+- `unsupported` — the provider has no registered adapter; the policy is informational only. Dispatch follows provider behavior.
 
-In non-interactive mode, an unresolved ceiling blocks before any implementation work:
+In non-interactive mode, an unresolved policy blocks before any implementation work:
 
 ```text
-BLOCKED: Codex dispatch ceiling is unresolved in non-interactive mode.
-Set workflow.dispatchCeiling.providers.codex in .oat/config.json or oat_dispatch_ceiling in project state.
+BLOCKED: Codex dispatch policy is unresolved in non-interactive mode.
+Set workflow.dispatchPolicy.mode/workflow.dispatchPolicy.policy, workflow.dispatchCeiling.providers.codex, oat_dispatch_policy, or legacy oat_dispatch_ceiling.
 ```
 
-Dry-run reports unresolved ceiling and planned behavior without writing project state.
+Dry-run reports unresolved policy and planned behavior without writing project state.
 
 ### Runtime dispatch selection
 
@@ -103,14 +107,14 @@ The orchestrator considers, in order:
 Model and effort are separate axes. Each axis logs one of these states:
 
 - `selected:<value>` — the host exposes the axis and the orchestrator chose a value.
-- `provider-default` — Codex base/unpinned role follows configured/provider default effort.
+- `provider-default` — Codex base/unpinned role follows configured/provider default effort for explicit inherit/default behavior or fallback paths.
 - `inherited` — the host exposes the axis and the orchestrator deliberately defers to the parent session.
 - `not-applicable` — this host/API has no meaningful per-dispatch concept for that axis.
 - `host-auto` — exceptional; the host uses that axis internally but the orchestrator cannot read or pin it.
 
-In Codex, implementation and fix dispatch classify a preferred effort (`low`, `medium`, `high`, or `xhigh`) and pass it to `oat project dispatch-ceiling resolve --provider codex --role implementer --preferred <effort>`. The resolver selects `min(preferred, resolved_ceiling)` and returns the matching pinned role: `oat-phase-implementer-low`, `oat-phase-implementer-medium`, `oat-phase-implementer-high`, or `oat-phase-implementer-xhigh`. Reviewer dispatch uses the reviewer variant matching the resolved ceiling (`oat-reviewer-low|medium|high|xhigh`) for deterministic quality gates. Base/unpinned Codex roles are provider-default fallbacks; they should be logged as `provider-default`, not as inherited parent-session ceiling.
+In Codex, implementation and fix dispatch classify a preferred effort (`low`, `medium`, `high`, or `xhigh`) and pass it to `oat project dispatch-ceiling resolve --provider codex --role implementer --preferred <effort>`. For capped managed policies, the resolver selects `min(preferred, resolved_cap)` and returns the matching pinned role. For managed `Uncapped`, the resolver selects the preferred pinned role with no cap. For inherit/default mode, it returns no pinned role and OAT uses the base/unpinned role. Reviewer dispatch targets the configured cap only when a capped managed policy exists; managed `Uncapped` and inherit/default use base `oat-reviewer` fallback.
 
-In Claude Code, implementation and fix dispatch classify a preferred model tier (`haiku`, `sonnet`, or `opus`) and pass it to `oat project dispatch-ceiling resolve --provider claude --role implementer --preferred <model> --orchestrator-tier <current-orchestrator-tier>`. The resolver selects `min(preferred, resolved_ceiling)` and returns the `model` argument to pass at dispatch. Reviewer dispatch targets the resolved Claude ceiling directly. The separate effort axis is `not-applicable`.
+In Claude Code, implementation and fix dispatch classify a preferred model tier (`haiku`, `sonnet`, `opus`, or `fable`) and pass it to `oat project dispatch-ceiling resolve --provider claude --role implementer --preferred <model> --orchestrator-tier <current-orchestrator-tier>`. Capped policies select `min(preferred, resolved_cap)`, managed `Uncapped` selects the preferred model, and inherit/default omits `model`. Reviewer dispatch passes a `model` only when the resolver returns one. The separate effort axis is `not-applicable`.
 
 Dispatch logs use a consistent structured block so provider behavior is comparable without flattening the model and effort axes:
 
@@ -125,25 +129,43 @@ Rationale: multi-file integration with mock wiring; sonnet is the lowest suffici
 OAT Dispatch: Phase p02 implementation
 Host: Codex
 Preferred effort: high
-Dispatch ceiling: medium
+Dispatch policy: economy
+Resolved cap: medium
 Selected effort: medium
-Ceiling source: repo config
+Policy source: repo config
 Provider default effort: high
+Selection mode: capped
 Model axis: inherited
 Effort axis: selected:medium
 Dispatch target: oat-phase-implementer-medium
-Rationale: shared TypeScript/config substrate; high preferred due to integration risk, capped by configured ceiling.
+Rationale: shared TypeScript/config substrate; high preferred due to integration risk, capped by configured policy.
 
 OAT Dispatch: Phase p03 review
 Host: Codex
-Dispatch ceiling: high
-Selected effort: high
-Ceiling source: project state
+Dispatch policy: high
+Resolved cap: xhigh
+Selected effort: xhigh
+Policy source: project state
 Provider default effort: medium
+Selection mode: review-target
 Model axis: inherited
-Effort axis: selected:high
-Dispatch target: oat-reviewer-high
-Rationale: reviewer runs at the configured ceiling for deterministic quality gate behavior.
+Effort axis: selected:xhigh
+Dispatch target: oat-reviewer-xhigh
+Rationale: reviewer runs at the configured policy cap for deterministic quality gate behavior.
+
+OAT Dispatch: Phase p03 implementation
+Host: Codex
+Preferred effort: xhigh
+Dispatch policy: uncapped
+Resolved cap: none
+Selected effort: xhigh
+Policy source: project state
+Provider default effort: medium
+Selection mode: uncapped
+Model axis: inherited
+Effort axis: selected:xhigh
+Dispatch target: oat-phase-implementer-xhigh
+Rationale: high-risk phase; managed uncapped policy allows the preferred pinned variant.
 
 OAT Dispatch: Phase p04 implementation
 Host: Other
@@ -155,9 +177,10 @@ Rationale: host does not expose readable or pinnable dispatch controls; rational
 OAT Dispatch: p02-t10 sidecar exploration
 Host: Codex
 Preferred effort: provider-default
-Dispatch ceiling: xhigh
+Dispatch policy: high
+Resolved cap: xhigh
 Selected effort: provider-default
-Ceiling source: project state
+Policy source: project state
 Provider default effort: xhigh
 Model axis: inherited
 Effort axis: provider-default
@@ -165,7 +188,7 @@ Dispatch target: explorer
 Rationale: read-only sidecar exploration; generic explorer payload does not pin an OAT-managed effort variant.
 ```
 
-Phase and review scope packets include dispatch context when the orchestrator has resolved it: `model_axis`, `effort_axis`, `dispatch_ceiling`, `ceiling_source`, `provider_default_effort`, and `dispatch_rationale`.
+Phase and review scope packets include dispatch context when the orchestrator has resolved it: `model_axis`, `effort_axis`, `dispatch_policy`, `dispatch_ceiling`, `policy_source`, `ceiling_source` as a compatibility alias, `provider_default_effort`, and `dispatch_rationale`.
 
 Generic sidecars such as built-in `explorer` are not OAT-managed implementer, reviewer, or fix roles. If a sidecar payload does not pin a reliable effort/model control, log it as provider-default rather than classifying the task complexity as a selected effort. Sidecar results are advisory context; implementation and review/fix gates still follow the OAT-managed dispatch rules above.
 
@@ -183,11 +206,12 @@ For each phase in the plan (whether sequential or inside a parallel group):
 2. **Dispatch the selected implementer role** with a Phase Scope block (project path, phase id, artifact paths, commit convention, workflow mode, and dispatch context when known). In Codex, `effort_axis=selected:low|medium|high|xhigh` uses `oat-phase-implementer-low|medium|high|xhigh`. Base `oat-phase-implementer` means provider-default/unpinned fallback.
 3. **Receive the summary:** `DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED`.
    - `BLOCKED` stops the run and surfaces the blocker to the user.
-4. **Dispatch the selected reviewer role** with a Review Scope block (phase id, commit range, optional files-changed hint, and dispatch context). The commit range is authoritative; the file list is only orientation metadata. In Codex, pass this as a self-contained packet with `fork_context: false` and use the `oat-reviewer-<ceiling>` variant. In Claude Code, cap any selected model by the Claude ceiling and record `effort_axis=not-applicable`. If the reviewer does not conclude on the first wait, poll once more, then send a concise "return now with current findings" nudge before falling back inline for that phase.
+4. **Dispatch the selected reviewer role** with a Review Scope block (phase id, commit range, optional files-changed hint, and dispatch context). The commit range is authoritative; the file list is only orientation metadata. In Codex, pass this as a self-contained packet with `fork_context: false`; use an `oat-reviewer-<value>` variant only for capped managed policies, and use base `oat-reviewer` for managed `Uncapped` or inherit/default. In Claude Code, pass a review `model` only when the resolver returns one and always record `effort_axis=not-applicable`. If the reviewer does not conclude on the first wait, poll once more, then send a concise "return now with current findings" nudge before falling back inline for that phase.
 5. **Parse the verdict:** zero Critical + zero Important findings → `pass`; otherwise `fail`.
 6. **On fail, run the bounded fix loop** (see below).
 7. **Update artifacts** (`implementation.md`, `plan.md` review row, `state.md`) and make the mandatory bookkeeping commit.
-8. **HiLL checkpoint** if the phase id is listed in `oat_plan_hill_phases`.
+8. **Phase review gate** — when `oat_phase_review_gate` selects the phase, run the optional non-pausing external gate (`oat gate review`) after the step 7 bookkeeping commit and before the HiLL check. A passing gate continues automatically; a blocking gate is received and fixed, reusing the bounded fix loop's `oat_orchestration_retry_limit`. See [Reviews → Phase review gate](reviews.md#phase-review-gate).
+9. **HiLL checkpoint** if the phase id is listed in `oat_plan_hill_phases`.
 
 ### Bounded fix loop
 
@@ -206,8 +230,8 @@ Tier is never silently downgraded. If a Tier 1 dispatch has a transient failure,
 
 When escalation re-dispatches at a stronger control, the ladder is provider-specific:
 
-- **Codex:** `selected:low -> selected:medium -> selected:high -> selected:xhigh`, capped by the resolved Codex dispatch ceiling.
-- **Claude Code:** `selected:haiku -> selected:sonnet -> selected:opus`, capped by the resolved Claude dispatch ceiling (compiled from preset or `workflow.dispatchCeiling.providers.claude`).
+- **Codex:** `selected:low -> selected:medium -> selected:high -> selected:xhigh`, capped by the resolved managed cap when one exists. Managed `Uncapped` can select the preferred value; inherit/default mode has no OAT escalation control.
+- **Claude Code:** `selected:haiku -> selected:sonnet -> selected:opus -> selected:fable`, capped by the resolved managed cap when one exists. Managed `Uncapped` can select the preferred model; inherit/default mode has no OAT escalation control.
 
 Escalation re-dispatches still count against the bounded retry budget; escalation changes the dispatch control, it does not grant extra retry attempts.
 

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

@@ -14,7 +14,7 @@ Projects are where the workflow layer becomes concrete: lifecycle phases, `state
 - [Lifecycle](lifecycle.md) - End-to-end flow from discovery through completion.
 - [Design Modes](design-modes.md) - How full design balances collaborative, selective collaborative, and draft-and-review interaction.
 - [HiLL Checkpoints](hill-checkpoints.md) - Human-in-the-Loop Lifecycle configuration and approval behavior.
-- [Dispatch Ceiling](dispatch-ceiling.md) - Provider-neutral ceiling model and provider-specific enforcement.
+- [Dispatch Policy](dispatch-ceiling.md) - Managed capped tiers, managed Uncapped, Inherit Host Defaults, and provider-specific enforcement.
 - [Project Artifacts](artifacts.md) - What lives in `state.md`, `discovery.md`, `plan.md`, `implementation.md`, and related files.
 - [Implementation Execution](implementation-execution.md) - Phase dispatch, runtime selection, review/fix loop, and dry-run behavior.
 - [Project Splitting](splitting.md) - How broad discoveries or brainstorms become coordination parents and child projects.
@@ -47,7 +47,7 @@ This sub-section is the deep technical surface for how tracked OAT projects exec
 - [Lifecycle](lifecycle.md) - End-to-end flow from discovery through completion.
 - [Design Modes](design-modes.md) - How full design balances collaborative, selective collaborative, and draft-and-review interaction.
 - [HiLL Checkpoints](hill-checkpoints.md) - Human-in-the-Loop Lifecycle configuration and approval behavior.
-- [Dispatch Ceiling](dispatch-ceiling.md) - Provider-neutral ceiling model: presets, the compile/resolve flow, and how enforcement differs for Codex, Claude, and unsupported providers.
+- [Dispatch Policy](dispatch-ceiling.md) - Managed capped tiers, managed Uncapped, Inherit Host Defaults, legacy dispatch-ceiling compatibility, and provider-specific enforcement.
 - [Artifacts](artifacts.md) - What lives in `state.md`, `discovery.md`, `plan.md`, `implementation.md`, and related files.
 - [Project Splitting](splitting.md) - How broad discoveries or brainstorms become coordination parents and child projects.
 - [State Machine](state-machine.md) - Lifecycle and review status transitions across a project.

package/assets/docs/workflows/projects/lifecycle.md

@@ -136,7 +136,17 @@ flowchart LR
 
 During the Design step, `oat-project-design` asks how to work through the document unless a mode was selected by argument, environment, or `workflow.designMode`. The three full-design choices are collaborative, selective collaborative, and draft-and-review.
 
-Before a plan is marked ready for implementation, planning resolves the current provider's dispatch ceiling from `workflow.dispatchCeiling.providers.<provider>` (compiled from a preset or set directly) or project `state.md` frontmatter. If no ceiling is configured and the session is interactive, planning asks once and stores the answer as `oat_dispatch_ceiling`; non-interactive planning leaves it unresolved so implementation preflight can fail before work starts with setup instructions.
+Before a plan is marked ready for implementation, planning resolves the current
+provider's dispatch policy from `workflow.dispatchPolicy.mode` and
+`workflow.dispatchPolicy.policy`, or from project `state.md` frontmatter. The
+legacy `workflow.dispatchCeiling.providers.<provider>` config and
+`oat_dispatch_ceiling` frontmatter remain compatibility inputs for capped
+managed policies. If no policy is configured and the session is interactive,
+planning asks once and stores the answer as `oat_dispatch_policy`;
+non-interactive planning leaves it unresolved so implementation preflight can
+fail before work starts with setup instructions. `Uncapped` is explicit managed
+selection with no maximum cap; `Inherit Host Defaults` is separate and means OAT
+does not select model or effort controls.
 
 ### Quick lane
 
@@ -152,7 +162,12 @@ flowchart LR
 
 Quick lane lightweight design intentionally keeps a smaller collaborative/draft choice. Selective collaborative becomes available only after promotion into the full spec-driven design lane.
 
-Quick-start follows the same dispatch ceiling rule at the plan boundary: capture it when interactive, persist it to project state, and avoid any mid-implementation ceiling prompt.
+Quick-start follows the same dispatch policy rule at the plan boundary: capture
+the policy when interactive, persist `oat_dispatch_policy` to project state, and
+avoid any mid-implementation policy prompt. Legacy dispatch-ceiling state is
+still read as compatibility capped-policy input, but new quick-start selections
+should use the dispatch-policy names, including explicit `Uncapped` and
+`Inherit Host Defaults`.
 
 ### Import lane
 

package/assets/docs/workflows/projects/reviews.md

@@ -107,6 +107,23 @@ Auto-triggered reviews use `oat_review_invocation: auto` in the review artifact
 
 This feature is opt-in and disabled by default. When disabled, the manual `oat-project-review-provide` workflow applies.
 
+## Phase review gate
+
+The phase review gate is an optional, **non-pausing** external review gate that runs after a phase's standard per-phase reviewer passes and the phase bookkeeping is committed. Where the Tier 1 reviewer is an in-session self-review, the gate calls `oat gate review` against the configured cross-provider target, adding an independent perspective before implementation moves to the next phase. It is enabled per-project through `plan.md` frontmatter (`oat_phase_review_gate`; see [Project Artifacts](artifacts.md#oat_phase_review_gate) for the field shape and validation).
+
+It is independent of [HiLL checkpoints](hill-checkpoints.md): a passing gate does not pause, and the gate never touches `oat_hill_completed`, `oat_plan_hill_phases`, or `oat_auto_review_at_hill_checkpoints`.
+
+Gate-produced review artifacts use `oat_review_invocation: gate` in frontmatter (the third invocation marker alongside `manual` and `auto`). The gate verdict — controlled by `exit_nonzero_on` (default `important`) — decides whether the **phase stops**; it does not decide whether sub-threshold findings are ignored. Either way the produced artifact is consumed by `oat-project-review-receive`, autonomously and without user prompts, so findings never evaporate:
+
+- **Passing gate** (no findings at or above the threshold): receive runs a non-pausing **judgment sweep**. It makes a per-finding decision for each Medium/Minor — defer to final review (the default, recorded so [final review](#phase-and-final-review) resurfaces it), address now (only for small, contained, low-risk fixes, which do **not** re-trigger the standard reviewer or re-gate the phase), or reject with rationale — then archives the artifact. Address-now is an exception, not the norm; if such a fix reveals a Critical/Important concern it escalates to the blocking path.
+- **Blocking gate** (one or more findings at or above the threshold): receive converts findings to fix tasks and implementation re-runs the standard reviewer and the gate for the phase. These block → fix → re-gate rounds are bounded by `oat_orchestration_retry_limit` (default `2`); exhausting the bound stops a sequential run or excludes the phase in a parallel group, matching the standard fix loop's terminal handling.
+
+Gate-originated artifacts (`oat_review_invocation: gate`) are excluded from the same-scope review-cycle cap in `oat-project-review-receive`. The cap measures failed fix cycles of the standard review loop, so counting gate artifacts would trip it on artifact volume rather than real fix rounds.
+
+When a phase is re-gated multiple times, each round produces a distinct review artifact — filenames and `oat_generated_at` are seconds-precision, so rounds never collide and `oat review latest` resolves the newest. An orchestrator should know a gate finished from the `oat --json gate review` result envelope on process exit (`status`, `runId`, `generatedAt`), not by watching the `reviews/` directory or the provider's log; see [Gate completion signal](../../cli-utilities/workflow-gates.md#gate-completion-signal).
+
+This feature is opt-in and disabled by default (missing or `enabled: false`). For a parallel phase group, selected gates run after fan-in and bookkeeping, one per merged phase in plan order.
+
 ## Auto artifact-review loops
 
 Generated planning and analysis artifacts have a separate review loop from code/phase reviews.

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.1.41",
-  "docs-config": "0.1.41",
-  "docs-theme": "0.1.41",
-  "docs-transforms": "0.1.41"
+  "cli": "0.1.43",
+  "docs-config": "0.1.43",
+  "docs-theme": "0.1.43",
+  "docs-transforms": "0.1.43"
 }