@open-agent-toolkit/cli 0.1.6 → 0.1.8

package/assets/agents/oat-phase-implementer.md

@@ -1,6 +1,6 @@
 ---
 name: oat-phase-implementer
-version: 1.0.1
+version: 1.0.2
 description: Implements a single plan phase end-to-end — reads artifacts once, executes tasks sequentially, commits per task, self-reviews, and returns a structured summary. Dispatched by oat-project-implement.
 tools: Read, Write, Edit, Bash, Grep, Glob
 color: cyan
@@ -34,10 +34,15 @@ You will be given a "Phase Scope" block including:
 - **commit_convention**: Commit message format from plan.md (e.g., `feat({scope}): {description}`)
 - **workflow_mode**: `spec-driven` | `quick` | `import` (default `spec-driven`)
 - **model_axis**: Optional model dispatch state selected by the orchestrator (`selected:<value>`, `inherited`, `not-applicable`, or `host-auto`)
-- **effort_axis**: Optional effort dispatch state selected by the orchestrator (`selected:<value>`, `inherited`, `not-applicable`, or `host-auto`)
+- **effort_axis**: Optional effort dispatch state selected by the orchestrator (`selected:<value>`, `provider-default`, `inherited`, `not-applicable`, or `host-auto`)
+- **dispatch_ceiling**: Optional resolved provider ceiling that capped/selected this dispatch
+- **ceiling_source**: Optional source for the resolved ceiling (`repo config`, `project state`, or `preflight prompt`)
+- **provider_default_effort**: Optional Codex provider default effort, used only to explain base/unpinned fallback dispatches
 - **dispatch_rationale**: Optional short rationale for the model/effort axis choices
 
-The `model_axis` and `effort_axis` fields describe the dispatch state the orchestrator already chose; they are descriptive context for your report, not actions for you to take. Echo whatever values were provided in your summary under `Model axis` / `Effort axis`. If neither field is in your scope packet, report both as "not provided."
+The `model_axis`, `effort_axis`, `dispatch_ceiling`, `ceiling_source`, and `provider_default_effort` fields describe dispatch state the orchestrator already chose; they are descriptive context for your report, not actions for you to take. Echo whatever values were provided in your summary. If a field is absent, report it as "not provided."
+
+For Codex, `provider-default` means the base/unpinned role follows Codex configured/provider default effort. It does not mean OAT inherited the parent session ceiling.
 
 If `mode: fix`, the block also includes:
 
@@ -126,6 +131,9 @@ Report format:
 **Confidence:** high | medium | low
 **Model axis:** {model_axis if provided, otherwise "not provided"}
 **Effort axis:** {effort_axis if provided, otherwise "not provided"}
+**Dispatch ceiling:** {dispatch_ceiling if provided, otherwise "not provided"}
+**Ceiling source:** {ceiling_source if provided, otherwise "not provided"}
+**Provider default effort:** {provider_default_effort if provided, otherwise "not provided"}
 
 ### Task Outcomes
 
@@ -192,6 +200,9 @@ If a fix introduces a regression or doesn't address its finding, either re-fix w
 **Confidence:** high | medium | low
 **Model axis:** {model_axis if provided, otherwise "not provided"}
 **Effort axis:** {effort_axis if provided, otherwise "not provided"}
+**Dispatch ceiling:** {dispatch_ceiling if provided, otherwise "not provided"}
+**Ceiling source:** {ceiling_source if provided, otherwise "not provided"}
+**Provider default effort:** {provider_default_effort if provided, otherwise "not provided"}
 
 ### Fix Outcomes
 

package/assets/agents/oat-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: oat-reviewer
-version: 1.0.1
+version: 1.0.2
 description: Unified reviewer for OAT projects - mode-aware verification of requirements/design alignment and code quality. Writes review artifact to disk.
 tools: Read, Bash, Grep, Glob, Write
 color: yellow
@@ -32,6 +32,8 @@ Reviews catch issues before they ship:
 
 Your review artifact feeds into `oat-project-review-receive`, which converts findings into plan tasks for systematic gap closure.
 
+Some findings are artifact drift rather than implementation defects. If shipped implementation is defensible but `spec.md`, `design.md`, or `plan.md` is stale, frame the issue as artifact alignment and say which artifact should change. Do not require a code fix solely because the design artifact lagged behind implementation.
+
 ## Inputs
 
 You will be given a "Review Scope" block including:
@@ -45,12 +47,19 @@ You will be given a "Review Scope" block including:
 - **artifact_paths**: Paths to available artifacts (spec/design/plan/implementation/discovery/import reference)
 - **tasks_in_scope**: Task IDs being reviewed (if task/phase scope)
 - **model_axis**: Optional model dispatch state selected by the orchestrator (`selected:<value>`, `inherited`, `not-applicable`, or `host-auto`)
-- **effort_axis**: Optional effort dispatch state selected by the orchestrator (`selected:<value>`, `inherited`, `not-applicable`, or `host-auto`)
+- **effort_axis**: Optional effort dispatch state selected by the orchestrator (`selected:<value>`, `provider-default`, `inherited`, `not-applicable`, or `host-auto`)
+- **dispatch_ceiling**: Optional resolved provider ceiling that capped/selected this review dispatch
+- **ceiling_source**: Optional source for the resolved ceiling (`repo config`, `project state`, or `preflight prompt`)
+- **provider_default_effort**: Optional Codex provider default effort, used only to explain base/unpinned fallback dispatches
 - **dispatch_rationale**: Optional short rationale for the model/effort axis choices
 
 ## Dispatch Control
 
-Reviews, re-reviews, and review-fix evaluation inherit the parent session's model and effort axes unless the user explicitly requested a review override. In Codex, the orchestrator should omit `model` and `reasoning_effort` overrides when spawning this reviewer; in Claude Code, it should not pass a per-review model override. The review scope should record `model_axis=inherited` and `effort_axis=inherited` on hosts that expose an effort axis (such as Codex), or `effort_axis=not-applicable` on hosts that do not (such as Claude Code). Do not read `plan.md` Dispatch Profile rows to self-select a tier; the orchestrator owns dispatch control.
+The orchestrator owns dispatch control. Do not read `plan.md` Dispatch Profile rows to self-select a tier.
+
+For Codex, normal deterministic review dispatch uses pinned reviewer variants (`oat-reviewer-low`, `oat-reviewer-medium`, `oat-reviewer-high`, or `oat-reviewer-xhigh`) selected by the resolved OAT dispatch ceiling. The base `oat-reviewer` role is a provider-default/unpinned fallback; if you are running as the base role, report any provided `provider_default_effort` as context but do not treat it as an OAT ceiling.
+
+For Claude Code, review dispatch is model-axis based and the effort axis is `not-applicable`.
 
 ## Mode Contract
 
@@ -161,6 +170,11 @@ For each design decision relevant to scope:
    - Do endpoints match the design?
    - Are error responses as specified?
 
+4. **Artifact drift classification**
+   - If implementation diverges from design/spec/plan, decide whether the implementation is wrong or the artifact is stale.
+   - When the implementation is defensible, write the finding as stale-artifact alignment guidance instead of a code defect.
+   - Include enough rationale for `oat-project-review-receive` to convert the finding into an artifact-alignment task or explicit deferral.
+
 ### Step 6: Verify Code Quality
 
 This step applies to **code reviews** only.
@@ -204,6 +218,7 @@ Group findings by severity:
 - Missing error handling
 - Significant maintainability issues
 - Missing tests for important paths
+- Stale spec/design/plan artifact that conflicts with a defensible implementation and should be aligned before closeout
 
 **Minor** (fix if time permits)
 
@@ -211,6 +226,7 @@ Group findings by severity:
 - Style issues
 - Minor refactoring opportunities
 - Documentation gaps
+- Low-impact artifact wording drift where implementation is defensible and the stale wording is unlikely to mislead near-term work
 
 ### Step 8: Write Review Artifact
 

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

@@ -158,13 +158,38 @@ oat config get lastPausedProject
 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:
+
+```bash
+oat project dispatch-ceiling resolve --provider codex --json
+oat project dispatch-ceiling resolve --provider claude --json
+```
+
+The resolver checks effective config first, then project `state.md`
+`oat_dispatch_ceiling` frontmatter. For Codex it also reports
+`providerDefaultEffort`, which is informational for base/unpinned roles and is
+not treated as the OAT ceiling.
+
+For non-interactive preflight checks, use:
+
+```bash
+oat project dispatch-ceiling resolve --provider codex --preflight --non-interactive
+```
+
+If unresolved, the command exits non-zero with the same `BLOCKED:` guidance used
+by `oat-project-implement`.
+
 ## Workflow preferences (`workflow.*`)
 
 Workflow preferences let power users answer repetitive confirmation prompts once and have OAT workflow skills respect those answers automatically. They are the highest-value escape hatch from interactive friction when you always make the same choices.
 
 ### Preference keys
 
-All eight workflow preference keys live under the `workflow.*` namespace:
+Workflow preference keys live under the `workflow.*` namespace:
 
 - `workflow.designMode` — `collaborative`, `selective`, or `draft`. Default design interaction mode. `selective` applies only to full `oat-project-design`; quick-start lightweight design treats it as collaborative because quick-start keeps the smaller collaborative/draft choice.
 - `workflow.hillCheckpointDefault` — `every` or `final`. Default HiLL checkpoint behavior in `oat-project-implement`: pause after every phase or only after the last phase. When unset, the skill prompts.
@@ -174,6 +199,8 @@ All eight 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`.
 
 ### Three-layer resolution
 
@@ -197,14 +224,19 @@ 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
 
 # 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
 
 # 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
 ```
 
 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/provider-sync/config.md

@@ -62,6 +62,7 @@ It is read by:
   - unset: provider falls back to directory detection.
 - `defaultStrategy` is used when no provider-specific `strategy` is set.
 - At runtime, config is normalized so `providers` is always present in memory.
+- Codex project sync also manages generated role variants derived from canonical agents. `oat-phase-implementer-low|medium|high|xhigh` and `oat-reviewer-low|medium|high|xhigh` are managed outputs used by dispatch-ceiling-aware implementation. They should not be adopted as stray roles.
 
 ## Recommended management flow
 

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

@@ -104,6 +104,8 @@ Current schema keys:
 | `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                                                                                                                                                       |

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

@@ -12,7 +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.
-- **Runtime dispatch:** each phase uses the lowest available model/effort/control that can confidently complete the work, unless `plan.md` includes an explicit Dispatch Profile override.
+- **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`).
+- **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
 
@@ -34,6 +35,41 @@ The selected tier is reported to the user and locked for the remainder of the ru
   → Selected: Tier 1 — Subagents
 ```
 
+### Dispatch ceiling preflight
+
+Before phase work starts, `oat-project-implement` resolves and prints the dispatch ceiling for the current provider.
+
+The compiled resolver is the source of truth:
+
+```bash
+oat project dispatch-ceiling resolve --provider codex --preflight --json
+```
+
+Resolution order:
+
+1. `workflow.dispatchCeiling.<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
+
+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
+Note: OAT will use pinned subagent variants up to high. Base/unpinned roles resolve through the provider default.
+```
+
+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.
+```
+
+Dry-run reports unresolved ceiling and planned behavior without writing project state.
+
 ### Runtime dispatch selection
 
 Tier selection decides whether OAT uses native subagents or inline fallback. Runtime dispatch selection is separate: it decides which provider-specific model and effort controls to use for a specific phase when the host exposes those axes.
@@ -46,14 +82,17 @@ The orchestrator considers, in order:
 2. The phase's files, risk, requirements, and recent review/fix-loop evidence.
 3. The host's actual control surface by axis.
 
-Model and effort are separate axes. Each axis logs one of four states:
+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.
 - `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, the normal model choice is inherited unless the user requested a model override or the phase clearly requires one. Implementation and fix dispatch default to selected effort: classify the phase, choose the lowest sufficient `low`, `medium`, or `high`, and dispatch the matching configured Codex implementer role (`oat-phase-implementer-low`, `oat-phase-implementer-medium`, or `oat-phase-implementer-high`) rather than relying on per-call effort overrides. The base `oat-phase-implementer` role represents inherited effort, which is the parent-session ceiling path, not a neutral default. Use inherited effort only for an explicit user/Dispatch Profile override, when the phase needs the parent-session ceiling and `selected:high` is insufficient, or when selected-effort roles are unavailable. `xhigh` is inherited-only: use it when the parent/orchestrator session is already xhigh, otherwise split/revise the phase or stop for user re-invocation instead of inventing an `xhigh` variant. In Claude Code, subagent model selection is a model axis when available; the separate effort axis is `not-applicable`.
+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`.
 
 Dispatch logs use a consistent structured block so provider behavior is comparable without flattening the model and effort axes:
 
@@ -67,17 +106,26 @@ 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
+Selected effort: medium
+Ceiling source: repo config
+Provider default effort: high
 Model axis: inherited
 Effort axis: selected:medium
 Dispatch target: oat-phase-implementer-medium
-Rationale: shared TypeScript/config substrate; medium is the lowest sufficient Codex effort.
+Rationale: shared TypeScript/config substrate; high preferred due to integration risk, capped by configured ceiling.
 
 OAT Dispatch: Phase p03 review
 Host: Codex
+Dispatch ceiling: high
+Selected effort: high
+Ceiling source: project state
+Provider default effort: medium
 Model axis: inherited
-Effort axis: inherited
-Dispatch target: oat-reviewer
-Rationale: reviewer dispatches inherit parent controls by default.
+Effort axis: selected:high
+Dispatch target: oat-reviewer-high
+Rationale: reviewer runs at the configured ceiling for deterministic quality gate behavior.
 
 OAT Dispatch: Phase p04 implementation
 Host: Other
@@ -87,7 +135,7 @@ Dispatch target: host default
 Rationale: host does not expose readable or pinnable dispatch controls; rationale maps to standard effort.
 ```
 
-Phase scope packets include implementation `model_axis`, `effort_axis`, and `dispatch_rationale` when the orchestrator has resolved them. Review dispatches inherit the parent session controls unless the user explicitly requests a review override; their review scope should record `model_axis=inherited` and `effort_axis=inherited` on hosts that expose an effort axis (such as Codex), or `effort_axis=not-applicable` on hosts that do not (such as Claude Code).
+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`.
 
 ### Dispatch Profile overrides
 
@@ -100,10 +148,10 @@ Add Dispatch Profile rows only when the user has an explicit constraint or prefe
 For each phase in the plan (whether sequential or inside a parallel group):
 
 1. **Select runtime dispatch control** for the phase and log the chosen control plus rationale.
-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` uses `oat-phase-implementer-low|medium|high`. Inherited effort uses base `oat-phase-implementer` only for an explicit ceiling/override/fallback reason; it should not be used just to avoid choosing a selected effort.
+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 `oat-reviewer`** with a Review Scope block (phase id, commit range, optional files-changed hint, and inherited review dispatch context). Review dispatches inherit the parent session's model and effort axes unless the user explicitly requested an override. 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 the base reviewer role without model or effort overrides, and record `model_axis=inherited, effort_axis=inherited` so the reviewer reads git/OAT artifacts directly instead of inheriting the orchestration thread. In Claude Code, do not pass a per-review model override and record `effort_axis=not-applicable` since Claude Code does not expose a per-dispatch effort axis. 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` 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.
 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.
@@ -126,8 +174,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`. `high` is the strongest selectable effort variant. Beyond `high`, dispatch uses `effort_axis=inherited` only when the parent session is already `xhigh`; otherwise escalation is exhausted — stop, split the phase, or have the user re-invoke at `xhigh`.
-- **Claude Code:** `selected:haiku → selected:sonnet → selected:opus`. `opus` is directly selectable via the Task `model` parameter — there is no inherited-only restriction.
+- **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.
 
 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/lifecycle.md

@@ -136,6 +136,8 @@ 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.
+
 ### Quick lane
 
 ```mermaid
@@ -150,6 +152,8 @@ 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.
+
 ### Import lane
 
 ```mermaid

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.1.6",
-  "docs-config": "0.1.6",
-  "docs-theme": "0.1.6",
-  "docs-transforms": "0.1.6"
+  "cli": "0.1.8",
+  "docs-config": "0.1.8",
+  "docs-theme": "0.1.8",
+  "docs-transforms": "0.1.8"
 }