@open-agent-toolkit/cli 0.1.10 → 0.1.12

package/assets/docs/cli-utilities/configuration.md

@@ -160,13 +160,69 @@ oat config describe activeIdea
 
 ## Dispatch ceiling resolution
 
-`oat config get workflow.dispatchCeiling.<provider>` shows only the effective
-config value. Implementation workflows should use the project-aware resolver
-instead:
+The dispatch ceiling is set as a **provider-neutral preset** (or per-provider
+advanced values) and compiled at write time into concrete per-provider values.
+Runtime dispatch reads only the concrete values — never the preset label.
+
+For the full conceptual model — presets, the compile/resolve flow, and how
+enforcement differs for Codex, Claude, and unsupported providers — see
+[Dispatch Ceiling](../workflows/projects/dispatch-ceiling.md).
+
+### Config keys
+
+Three keys control the ceiling, all under `workflow.dispatchCeiling`:
+
+| Key                                         | Values                                  | Purpose                                             |
+| ------------------------------------------- | --------------------------------------- | --------------------------------------------------- |
+| `workflow.dispatchCeiling.preset`           | `balanced`, `maximum`, `cost-conscious` | Convenience preset; compiles to concrete values     |
+| `workflow.dispatchCeiling.providers.codex`  | `low`, `medium`, `high`, `xhigh`        | Concrete Codex ceiling (set by preset or Advanced)  |
+| `workflow.dispatchCeiling.providers.claude` | `haiku`, `sonnet`, `opus`               | Concrete Claude ceiling (set by preset or Advanced) |
+
+**Presets compile to:**
+
+| Preset           | Codex    | Claude   |
+| ---------------- | -------- | -------- |
+| `balanced`       | `high`   | `sonnet` |
+| `maximum`        | `xhigh`  | `opus`   |
+| `cost-conscious` | `medium` | `sonnet` |
+
+**Advanced (no preset):** set `providers.codex` and/or `providers.claude`
+individually. No `preset` key is stored.
+
+**No ceiling:** leave `oat_dispatch_ceiling` unset; implementer subagents run at
+provider defaults.
+
+### How enforcement works
+
+OAT applies the ceiling where the provider exposes a reliable mechanism. Other
+providers receive it as advisory.
+
+| Provider | Mechanism                 | Enforcement mode           |
+| -------- | ------------------------- | -------------------------- |
+| Codex    | Pinned role variants      | `enforced`                 |
+| Claude   | Task `model` parameter    | `enforced`                 |
+| Others   | None (informational only) | `advisory` / `unsupported` |
+
+**Verify-on-upgrade:** when the requested tier exceeds the current orchestrator
+tier (an upgrade request), the resolver sets `verifyOnDispatch: true`. The skill
+confirms the actual model used after dispatch. If the provider did not honor the
+upgrade, the enforcement log reads `advisory — provider did not honor upgrade;
+ran <tier>` instead of `enforced`.
+
+### Clean break
+
+The previous flat keys (`workflow.dispatchCeiling.codex` and
+`workflow.dispatchCeiling.claude`) are removed. There is no migration path — set
+the new keys.
+
+### Using the resolver
+
+Implementation workflows should use the project-aware resolver rather than
+reading config keys directly:
 
 ```bash
 oat project dispatch-ceiling resolve --provider codex --json
-oat project dispatch-ceiling resolve --provider claude --json
+oat project dispatch-ceiling resolve --provider claude --orchestrator-tier sonnet --json
 ```
 
 The resolver checks effective config first, then project `state.md`
@@ -199,8 +255,9 @@ Workflow preference keys live under the `workflow.*` namespace:
 - `workflow.reviewExecutionModel` — `subagent`, `inline`, or `fresh-session`. Default final-review execution model in `oat-project-implement`. `subagent` and `inline` run automatically. `fresh-session` is a soft preference: the skill prints guidance to run the review in another session but still offers escape hatches to `subagent` or `inline` if you change your mind. When unset, the skill prompts.
 - `workflow.autoReviewAtHillCheckpoints` — boolean. Automatically run the extra lifecycle review when a HiLL checkpoint is reached. This does not control Tier 1 per-phase `oat-reviewer` gates, which run after each phase in Tier 1 regardless of this setting. When unset, the skill prompts.
 - `workflow.autoNarrowReReviewScope` — boolean. Auto-narrow re-review scope to fix-task commits only in `oat-project-review-provide`. When unset, the skill prompts.
-- `workflow.dispatchCeiling.codex` — `low`, `medium`, `high`, or `xhigh`. Maximum Codex reasoning effort OAT may select through deterministic pinned implementer/reviewer variants. Provider default effort is informational for base/unpinned roles and is not treated as this ceiling.
-- `workflow.dispatchCeiling.claude` — `haiku`, `sonnet`, or `opus`. Maximum Claude model tier OAT may select for provider-native subagent dispatch. Claude has no separate per-dispatch effort axis, so the effort axis remains `not-applicable`.
+- `workflow.dispatchCeiling.preset` — `balanced`, `maximum`, or `cost-conscious`. Convenience preset that compiles to per-provider values at write time. Setting this key is the recommended way to configure the ceiling.
+- `workflow.dispatchCeiling.providers.codex` — `low`, `medium`, `high`, or `xhigh`. Concrete Codex ceiling. Set automatically when a preset is selected; also settable directly for Advanced (no preset) configurations. Provider default effort is informational for base/unpinned roles and is not treated as this ceiling.
+- `workflow.dispatchCeiling.providers.claude` — `haiku`, `sonnet`, or `opus`. Concrete Claude ceiling. Set automatically when a preset is selected; also settable directly for Advanced configurations. Claude has no separate per-dispatch effort axis, so the effort axis remains `not-applicable`.
 
 ### Three-layer resolution
 
@@ -224,19 +281,17 @@ oat config set workflow.reviewExecutionModel subagent --user
 oat config set workflow.autoReviewAtHillCheckpoints true --user
 oat config set workflow.autoNarrowReReviewScope true --user
 oat config set workflow.designMode selective --user
-oat config set workflow.dispatchCeiling.codex high --user
-oat config set workflow.dispatchCeiling.claude sonnet --user
+oat config set workflow.dispatchCeiling.preset balanced --user
 
 # Shared repo: team decision for this repo
 oat config set workflow.createPrOnComplete false --shared
 oat config set workflow.designMode collaborative --shared
-oat config set workflow.dispatchCeiling.codex high --shared
-oat config set workflow.dispatchCeiling.claude sonnet --shared
+oat config set workflow.dispatchCeiling.preset balanced --shared
 
 # Repo-local: personal override for this repo (default when no flag)
 oat config set workflow.hillCheckpointDefault every
 oat config set workflow.designMode draft
-oat config set workflow.dispatchCeiling.codex medium
+oat config set workflow.dispatchCeiling.providers.codex medium  # Advanced: per-provider override
 ```
 
 Default (no flag) targets `.oat/config.local.json` for workflow keys. Pass at most one of `--user`, `--shared`, or `--local`. Structural keys (`projects.root`, `worktrees.root`, `git.*`, `documentation.*`, `archive.*`, `tools.*`) are still shared-only regardless of flag.

package/assets/docs/reference/oat-directory-structure.md

@@ -92,27 +92,28 @@ Legacy `.oat/active-project` / `.oat/projects-root` / `.oat/active-idea` files m
 
 Current schema keys:
 
-| Key                                         | Type       | Default                  | Description                                                                                                                                                                                                                                                                                             |
-| ------------------------------------------- | ---------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `version`                                   | `number`   | `1`                      | Schema version                                                                                                                                                                                                                                                                                          |
-| `worktrees.root`                            | `string`   | `".worktrees"`           | Root directory for git worktrees (repo-relative or absolute)                                                                                                                                                                                                                                            |
-| `projects.root`                             | `string`   | `".oat/projects/shared"` | Default root directory for OAT projects                                                                                                                                                                                                                                                                 |
-| `localPaths`                                | `string[]` | -                        | Gitignored directories to sync between main repo and worktrees. Supports glob patterns. Managed via `oat local add/remove`.                                                                                                                                                                             |
-| `documentation.root`                        | `string`   | -                        | Root directory containing documentation source files (e.g., `apps/docs/docs`)                                                                                                                                                                                                                           |
-| `documentation.tooling`                     | `string`   | -                        | Documentation framework identifier (`mkdocs` or `fumadocs`)                                                                                                                                                                                                                                             |
-| `documentation.config`                      | `string`   | -                        | Path to the documentation framework config file (e.g., `mkdocs.yml`, `next.config.js`)                                                                                                                                                                                                                  |
-| `documentation.index`                       | `string`   | -                        | Path to the docs surface entry point (e.g., `index.md` for Fumadocs, `mkdocs.yml` for MkDocs). Set by `oat docs init` and updated by `oat docs generate-index`.                                                                                                                                         |
-| `documentation.requireForProjectCompletion` | `boolean`  | `false`                  | When `true`, OAT project completion gates require documentation to be updated                                                                                                                                                                                                                           |
-| `git.defaultBranch`                         | `string`   | `"main"`                 | Default branch for PR creation. Auto-detected during `oat init` via `gh repo view` or `origin/HEAD`. Used by `oat-project-pr-final` and `oat-project-pr-progress`.                                                                                                                                      |
-| `workflow.autoReviewAtHillCheckpoints`      | `boolean`  | unset                    | When `true`, completing a HiLL checkpoint automatically runs the extra lifecycle review. Does not control Tier 1 per-phase `oat-reviewer` gates. Can be overridden per-project via `oat_auto_review_at_hill_checkpoints` in `plan.md` frontmatter. Legacy `autoReviewAtCheckpoints` remains a fallback. |
-| `workflow.dispatchCeiling.codex`            | `string`   | unset                    | Maximum Codex reasoning effort OAT may select through deterministic pinned implementer/reviewer variants (`low`, `medium`, `high`, or `xhigh`). Codex provider default effort is informational for base/unpinned roles and is not treated as this ceiling.                                              |
-| `workflow.dispatchCeiling.claude`           | `string`   | unset                    | Maximum Claude model tier OAT may select for provider-native subagent dispatch (`haiku`, `sonnet`, or `opus`). Claude has no separate per-dispatch effort axis.                                                                                                                                         |
-| `archive.s3Uri`                             | `string`   | -                        | Base S3 URI for repo-scoped archived project sync, for example `s3://bucket/oat-archive`                                                                                                                                                                                                                |
-| `archive.s3SyncOnComplete`                  | `boolean`  | `false`                  | When `true`, `oat-project-complete` uploads the archived project to the configured S3 archive after local archive succeeds                                                                                                                                                                              |
-| `archive.summaryExportPath`                 | `string`   | -                        | Repo-relative directory where completion exports `summary.md` as a dated snapshot like `20260401-<project-name>.md` for durable tracked reference                                                                                                                                                       |
-| `archive.wrapUpExportPath`                  | `string`   | -                        | Repo-relative directory where `oat-wrap-up` writes dated reports like `20260413-wrap-up-past-week.md`; when unset, the skill falls back to `.oat/repo/reference/wrap-ups/`                                                                                                                              |
-| `archive.awsProfile`                        | `string`   | -                        | Optional AWS named profile forwarded as `AWS_PROFILE` to every `aws` invocation in archive flows (`oat-project-complete` S3 sync, `oat project archive sync`). Overrides ambient shell `AWS_PROFILE` / `AWS_DEFAULT_PROFILE` when set.                                                                  |
-| `archive.awsRegion`                         | `string`   | -                        | Optional AWS region forwarded as `AWS_REGION` to every `aws` invocation in archive flows. Overrides ambient shell `AWS_REGION` / `AWS_DEFAULT_REGION` when set.                                                                                                                                         |
+| Key                                         | Type       | Default                  | Description                                                                                                                                                                                                                                                                                                                   |
+| ------------------------------------------- | ---------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `version`                                   | `number`   | `1`                      | Schema version                                                                                                                                                                                                                                                                                                                |
+| `worktrees.root`                            | `string`   | `".worktrees"`           | Root directory for git worktrees (repo-relative or absolute)                                                                                                                                                                                                                                                                  |
+| `projects.root`                             | `string`   | `".oat/projects/shared"` | Default root directory for OAT projects                                                                                                                                                                                                                                                                                       |
+| `localPaths`                                | `string[]` | -                        | Gitignored directories to sync between main repo and worktrees. Supports glob patterns. Managed via `oat local add/remove`.                                                                                                                                                                                                   |
+| `documentation.root`                        | `string`   | -                        | Root directory containing documentation source files (e.g., `apps/docs/docs`)                                                                                                                                                                                                                                                 |
+| `documentation.tooling`                     | `string`   | -                        | Documentation framework identifier (`mkdocs` or `fumadocs`)                                                                                                                                                                                                                                                                   |
+| `documentation.config`                      | `string`   | -                        | Path to the documentation framework config file (e.g., `mkdocs.yml`, `next.config.js`)                                                                                                                                                                                                                                        |
+| `documentation.index`                       | `string`   | -                        | Path to the docs surface entry point (e.g., `index.md` for Fumadocs, `mkdocs.yml` for MkDocs). Set by `oat docs init` and updated by `oat docs generate-index`.                                                                                                                                                               |
+| `documentation.requireForProjectCompletion` | `boolean`  | `false`                  | When `true`, OAT project completion gates require documentation to be updated                                                                                                                                                                                                                                                 |
+| `git.defaultBranch`                         | `string`   | `"main"`                 | Default branch for PR creation. Auto-detected during `oat init` via `gh repo view` or `origin/HEAD`. Used by `oat-project-pr-final` and `oat-project-pr-progress`.                                                                                                                                                            |
+| `workflow.autoReviewAtHillCheckpoints`      | `boolean`  | unset                    | When `true`, completing a HiLL checkpoint automatically runs the extra lifecycle review. Does not control Tier 1 per-phase `oat-reviewer` gates. Can be overridden per-project via `oat_auto_review_at_hill_checkpoints` in `plan.md` frontmatter. Legacy `autoReviewAtCheckpoints` remains a fallback.                       |
+| `workflow.dispatchCeiling.preset`           | `string`   | unset                    | Convenience preset compiled at write time to concrete per-provider ceilings (`balanced` = codex `high` / claude `sonnet`; `maximum` = codex `xhigh` / claude `opus`; `cost-conscious` = codex `medium` / claude `sonnet`). Stored only when a preset is chosen; runtime reads compiled `providers.*`, never the preset label. |
+| `workflow.dispatchCeiling.providers.codex`  | `string`   | unset                    | Maximum Codex reasoning effort OAT may select through deterministic pinned implementer/reviewer variants (`low`, `medium`, `high`, or `xhigh`). Codex provider default effort is informational for base/unpinned roles and is not treated as this ceiling.                                                                    |
+| `workflow.dispatchCeiling.providers.claude` | `string`   | unset                    | Maximum Claude model tier OAT may select for provider-native subagent dispatch (`haiku`, `sonnet`, or `opus`). Claude has no separate per-dispatch effort axis. The flat keys `workflow.dispatchCeiling.codex` and `workflow.dispatchCeiling.claude` were removed (no migration).                                             |
+| `archive.s3Uri`                             | `string`   | -                        | Base S3 URI for repo-scoped archived project sync, for example `s3://bucket/oat-archive`                                                                                                                                                                                                                                      |
+| `archive.s3SyncOnComplete`                  | `boolean`  | `false`                  | When `true`, `oat-project-complete` uploads the archived project to the configured S3 archive after local archive succeeds                                                                                                                                                                                                    |
+| `archive.summaryExportPath`                 | `string`   | -                        | Repo-relative directory where completion exports `summary.md` as a dated snapshot like `20260401-<project-name>.md` for durable tracked reference                                                                                                                                                                             |
+| `archive.wrapUpExportPath`                  | `string`   | -                        | Repo-relative directory where `oat-wrap-up` writes dated reports like `20260413-wrap-up-past-week.md`; when unset, the skill falls back to `.oat/repo/reference/wrap-ups/`                                                                                                                                                    |
+| `archive.awsProfile`                        | `string`   | -                        | Optional AWS named profile forwarded as `AWS_PROFILE` to every `aws` invocation in archive flows (`oat-project-complete` S3 sync, `oat project archive sync`). Overrides ambient shell `AWS_PROFILE` / `AWS_DEFAULT_PROFILE` when set.                                                                                        |
+| `archive.awsRegion`                         | `string`   | -                        | Optional AWS region forwarded as `AWS_REGION` to every `aws` invocation in archive flows. Overrides ambient shell `AWS_REGION` / `AWS_DEFAULT_REGION` when set.                                                                                                                                                               |
 
 All `documentation.*` keys are managed via `oat config get/set` and are set automatically by `oat docs init`.
 The `git.defaultBranch` key is auto-detected during `oat init` and can be overridden via `oat config set git.defaultBranch <branch>`.

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

@@ -0,0 +1,123 @@
+---
+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."
+---
+
+# Dispatch Ceiling
+
+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.
+
+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).
+
+## Two principles
+
+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.
+
+## Setting a ceiling
+
+Set it via `oat config set` (repo / user / local) or answer the planning/implementation preflight prompt. Three shapes:
+
+| 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          |
+
+The fixed preset table:
+
+| Preset         | Codex    | Claude   |
+| -------------- | -------- | -------- |
+| Balanced       | `high`   | `sonnet` |
+| Maximum        | `xhigh`  | `opus`   |
+| Cost-conscious | `medium` | `sonnet` |
+
+`cost-conscious` deliberately keeps Claude at `sonnet` (no `haiku` reviewers by default) so review quality stays trustworthy.
+
+Config keys:
+
+- `workflow.dispatchCeiling.preset`
+- `workflow.dispatchCeiling.providers.codex` (`low` \| `medium` \| `high` \| `xhigh`)
+- `workflow.dispatchCeiling.providers.claude` (`haiku` \| `sonnet` \| `opus`)
+
+```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 }
+
+# Or set providers directly (advanced — no preset key stored):
+oat config set workflow.dispatchCeiling.providers.codex high --shared
+```
+
+Project state can persist the compiled answer as `oat_dispatch_ceiling` (`preset?` + `providers` + `source`) so a planning/preflight choice carries into implementation.
+
+> The earlier flat `workflow.dispatchCeiling.codex` / `.claude` keys were removed. This was a clean break with no migration — set the new keys above.
+
+## How it resolves at dispatch
+
+Before dispatching a subagent, the orchestrator calls:
+
+```bash
+oat project dispatch-ceiling resolve --provider <provider> --role <implementer|reviewer> --preflight --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. returns a per-provider result: `{ value, mode, mechanism, dispatchArgs }`.
+
+`mode` is the honest enforcement status, computed right there and never persisted:
+
+- **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.
+
+## Per-provider behavior
+
+The same ceiling intent produces different — but honest — behavior per provider, because each adapter declares its own mechanism.
+
+|                   | **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            |
+
+### Why the mechanisms differ
+
+- **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 and dispatches the variant matching the resolved effort.
+- **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 — so OAT simply passes `model` at dispatch and 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.
+
+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.
+
+## Cap vs target: implementer vs reviewer
+
+The ceiling means slightly different things for the two dispatch roles:
+
+- **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.
+
+Both providers honor this distinction (Codex selects the matching variant; Claude passes the matching model).
+
+## 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:
+
+```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)
+```
+
+## 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.

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

@@ -12,7 +12,7 @@ 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-aware ceiling before work starts. Codex uses effort values (`low`, `medium`, `high`, `xhigh`); Claude uses model tiers (`haiku`, `sonnet`, `opus`).
+- **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.
 
 ## Execution model
@@ -37,7 +37,7 @@ The selected tier is reported to the user and locked for the remainder of the ru
 
 ### Dispatch ceiling preflight
 
-Before phase work starts, `oat-project-implement` resolves and prints the dispatch ceiling for the current provider.
+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).
 
 The compiled resolver is the source of truth:
 
@@ -47,25 +47,43 @@ oat project dispatch-ceiling resolve --provider codex --preflight --json
 
 Resolution order:
 
-1. `workflow.dispatchCeiling.<provider>` from effective config
+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
 
+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.
+
+**Preset 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 |
+
 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.
 
 ```text
-Codex dispatch ceiling: high
-Source: project state
-Codex provider default effort: medium
+Dispatch ceiling: high (codex, enforced — variant oat-phase-implementer-high)
+Source: project state  |  Preset: balanced
+Provider default effort: medium
 Note: OAT will use pinned subagent variants up to high. Base/unpinned roles resolve through the provider default.
 ```
 
+**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.
+
 In non-interactive mode, an unresolved ceiling blocks before any implementation work:
 
 ```text
 BLOCKED: Codex dispatch ceiling is unresolved in non-interactive mode.
-Set workflow.dispatchCeiling.codex in .oat/config.json or oat_dispatch_ceiling in project state.
+Set workflow.dispatchCeiling.providers.codex in .oat/config.json or oat_dispatch_ceiling in project state.
 ```
 
 Dry-run reports unresolved ceiling and planned behavior without writing project state.
@@ -92,7 +110,7 @@ Model and effort are separate axes. Each axis logs one of these states:
 
 In Codex, implementation and fix dispatch classify a preferred effort (`low`, `medium`, `high`, or `xhigh`) and select `min(preferred, resolved_ceiling)`. The selected effort maps to 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 Claude Code, subagent model selection is a model axis when available and is capped by `workflow.dispatchCeiling.claude` or project `oat_dispatch_ceiling`. The separate effort axis is `not-applicable`.
+In Claude Code, subagent model selection is a model axis when available and is capped by `workflow.dispatchCeiling.providers.claude` (or the compiled concrete value from a preset) or project `oat_dispatch_ceiling`. 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:
 
@@ -175,7 +193,7 @@ 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.
+- **Claude Code:** `selected:haiku -> selected:sonnet -> selected:opus`, capped by the resolved Claude dispatch ceiling (compiled from preset or `workflow.dispatchCeiling.providers.claude`).
 
 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

@@ -33,6 +33,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.
 - [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,7 @@ 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.<provider>` 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 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.
 
 ### Quick lane
 

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.1.10",
-  "docs-config": "0.1.10",
-  "docs-theme": "0.1.10",
-  "docs-transforms": "0.1.10"
+  "cli": "0.1.12",
+  "docs-config": "0.1.12",
+  "docs-theme": "0.1.12",
+  "docs-transforms": "0.1.12"
 }

package/assets/skills/oat-pjm-review-backlog/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-pjm-review-backlog
-version: 1.1.0
+version: 1.2.0
 description: Use when prioritizing the file-backed repo backlog or evaluating roadmap alignment. Produces value-effort ratings, dependency mapping, and execution recommendations.
 argument-hint: '[backlog-root] [--roadmap=<path>] [--output=<path>]'
 disable-model-invocation: true
@@ -48,11 +48,12 @@ When executing this skill, provide lightweight progress feedback so the user can
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 - Before multi-step work, print short step indicators, e.g.:
-  - `[1/5] Resolving backlog inputs…`
-  - `[2/5] Cataloging backlog items…`
-  - `[3/5] Reading codebase context…`
-  - `[4/5] Writing review document…`
-  - `[5/5] Summarizing recommendations…`
+  - `[1/6] Resolving backlog inputs…`
+  - `[2/6] Cataloging backlog items…`
+  - `[3/6] Reading codebase context…`
+  - `[4/6] Writing review document…`
+  - `[5/6] Summarizing recommendations…`
+  - `[6/6] (Optional) Priority-alignment walkthrough…` — only print after the operator accepts the offer in Step 9
 
 ## Arguments
 
@@ -60,7 +61,8 @@ Parse from `$ARGUMENTS`:
 
 - **backlog-root**: (optional) Path to the backlog root directory. Defaults to `.oat/repo/reference/backlog/`.
 - **--roadmap=\<path\>**: (optional) Path to a roadmap document for alignment analysis.
-- **--output=\<path\>**: (optional) Where to write the review. Defaults to `.oat/repo/reviews/backlog-and-roadmap-review.md`.
+- **--output=\<path\>**: (optional) Where to write the living review. Defaults to `.oat/repo/reference/backlog/reviews/backlog-and-roadmap-review.md`.
+- **--archive-dated**: (optional) Also write a dated snapshot alongside the living review at `.oat/repo/reference/backlog/reviews/backlog-and-roadmap-review-YYYY-MM-DD.md`. Default: off.
 
 ## Process
 
@@ -85,7 +87,12 @@ Parse from `$ARGUMENTS`:
 **Output path:**
 
 1. If `--output` is provided, use it directly.
-2. Otherwise, default to `.oat/repo/reviews/backlog-and-roadmap-review.md`.
+2. Otherwise, default to `.oat/repo/reference/backlog/reviews/backlog-and-roadmap-review.md` (the living, single-file review co-located with the backlog).
+3. If the `backlog/reviews/` directory does not exist yet, create it before writing. Do not fall back to `.oat/repo/reviews/` — backlog review artifacts now live under the file-backed backlog, not the repo-wide reviews directory.
+
+**Dated snapshot (optional):**
+
+If `--archive-dated` is passed, also write a copy to `.oat/repo/reference/backlog/reviews/backlog-and-roadmap-review-YYYY-MM-DD.md` in the **same directory** as the living review. Do not write dated snapshots to `.oat/repo/reviews/`.
 
 ### Step 2: Read and Catalog Backlog Items
 
@@ -165,6 +172,8 @@ If a roadmap was provided:
 
 Use the template at `.agents/skills/oat-pjm-review-backlog/references/backlog-review-template.md`.
 
+Write the **living** review to the resolved output path (default `.oat/repo/reference/backlog/reviews/backlog-and-roadmap-review.md`). If `--archive-dated` was passed, also write a dated snapshot alongside it (`backlog-and-roadmap-review-YYYY-MM-DD.md` in the same directory). Never split living and dated outputs across different directories — they must live together under `backlog/reviews/`.
+
 Ensure:
 
 - Every active backlog item file appears in the item catalog
@@ -183,6 +192,39 @@ After writing the review, provide:
 
 When listing specific items in this summary, follow the **Reference Format Convention** above — every backlog item must appear as `` `bl-XXXX` (human-readable title) `` (or the bold-with-em-dash variant in tables). Do not emit bare IDs.
 
+### Step 9: Offer Priority Alignment Walkthrough (Optional, Collaborative)
+
+The full review answers "what's in the backlog and how is each item rated." Operators still have to mentally extract "what should I actually do next, and in what order, with what parallelism." `priority-alignment.md` is the one-page execution companion that makes that extraction explicit.
+
+This step is **optional** and **collaborative** — it requires operator context (recent ships, capacity, calendar, ongoing initiatives) that the skill alone does not have. Do not produce or refresh `priority-alignment.md` without operator participation.
+
+**Decision: should we run the walkthrough?**
+
+After the summary, ask the operator:
+
+> Want to walk through the review together and produce a one-page execution view at `backlog/reviews/priority-alignment.md`? It captures phased order, parallelism, and a recommended kickoff stack — a faster reference than the full review.
+
+If `.oat/repo/reference/backlog/reviews/priority-alignment.md` already exists, frame it as an **update** to the existing document rather than a fresh create. Read the existing file first so the walkthrough builds on it.
+
+If the operator declines, stop after the summary. Do not silently write or modify `priority-alignment.md`.
+
+**If the operator accepts, run the walkthrough:**
+
+1. **Propose a phase breakdown** based on the review's quadrants and dependency graph:
+   - "Finishing / in flight" — items already started or in code review
+   - One or more execution phases that group items by initiative, parallel lane, or sequencing constraint
+   - Surface the natural parallelism boundaries from Step 5 as parallel tracks within a phase
+2. **Solicit operator context** that the review alone cannot capture:
+   - What just shipped or changed since the last alignment? (Goes in the **Status** line and **Changelog**.)
+   - What's the operator's capacity / appetite for parallel work this cycle?
+   - Are there calendar constraints (freezes, releases, time off) that affect ordering?
+   - Does the operator want an optional axis like "planning investment" or "design effort" as a column? (Some repos find this useful; many don't. Default: omit unless operator opts in.)
+3. **Iterate on phase names, ordering, and the kickoff stack** until the operator is satisfied. Phase names should reflect the repo's actual initiatives, not generic placeholders.
+4. **Write or update** `.oat/repo/reference/backlog/reviews/priority-alignment.md` using the template at `.agents/skills/oat-pjm-review-backlog/references/priority-alignment-template.md`. Add a new Changelog entry summarizing what shifted in this pass.
+5. **Confirm the result** with the operator: file path, top-of-doc Status line, and the kickoff stack.
+
+When referencing backlog items inside the priority-alignment doc, the **Reference Format Convention** still applies — link to the item file and pair the ID with a human-readable title.
+
 ## Success Criteria
 
 - Every active backlog item file has a value-effort rating with rationale
@@ -190,4 +232,6 @@ When listing specific items in this summary, follow the **Reference Format Conve
 - Parallel lanes and execution waves are actionable
 - Roadmap alignment gaps are surfaced when roadmap input is present
 - Output document follows the review template structure
+- Living review is written to `.oat/repo/reference/backlog/reviews/backlog-and-roadmap-review.md` (unless `--output` is explicitly overridden); dated snapshots, when emitted, live in the same `backlog/reviews/` directory and never under `.oat/repo/reviews/`
+- The operator is offered (but never forced into) a collaborative walkthrough that produces or updates `backlog/reviews/priority-alignment.md`; if the operator accepts, the file is written using the priority-alignment template and includes a Changelog entry for this pass; if the operator declines, no file is created or modified
 - Every user-facing reference to a backlog item pairs the ID with a human-readable title (per the Reference Format Convention)

package/assets/skills/oat-pjm-review-backlog/references/backlog-review-template.md

@@ -1,10 +1,12 @@
 # Backlog & Roadmap Review
 
 **Date:** {YYYY-MM-DD}
-**Scope:** {Description of what was reviewed, e.g., "All items in backlog.md (Inbox + Planned)"}
-**Roadmap:** {Path to roadmap if included, or "N/A"}
+**Scope:** {Description of what was reviewed, e.g., "All active items under `.oat/repo/reference/backlog/items/`"}
+**Roadmap:** {Path to roadmap if included, e.g. `.oat/repo/reference/roadmap.md`, or "N/A"}
 **Purpose:** Prioritize by value/effort, surface dependencies, and recommend an execution sequence
 
+> If a one-page execution companion exists in this directory, see [`priority-alignment.md`](./priority-alignment.md) — produced via the optional walkthrough at the end of `oat-pjm-review-backlog`. It is the short, ordered "what to do next" view of this full review.
+
 ---
 
 ## 1. Executive Summary