@open-agent-toolkit/cli 0.1.6 → 0.1.8

package/assets/skills/oat-project-implement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-implement
-version: 2.0.16
+version: 2.0.18
 description: Use when plan.md is ready for execution. Dispatches phase-level subagents with bounded fix loops; supports plan-declared parallel phase groups with worktree-isolated execution and ordered fan-in.
 argument-hint: '[--retry-limit <N>] [--dry-run]'
 disable-model-invocation: true
@@ -28,6 +28,9 @@ After every code commit and after every phase/review-fix completion, you MUST co
 **CRITICAL — Review boundaries require a committed artifact baseline.**
 Do not enter checkpoint review, final review, revise, or PR-final handoff with dirty core project artifacts (`discovery.md`, `spec.md`, `design.md`, `plan.md`, `implementation.md`, `state.md`, plus `.oat/state.md` when refreshed). If one of those boundaries is next and artifact bookkeeping is still uncommitted, stop and create the bookkeeping commit first.
 
+**CRITICAL — Intentional artifact divergence must be recorded.**
+If implementation intentionally diverges from `spec.md`, `design.md`, or `plan.md`, record the delta in `implementation.md` before the next phase/review boundary. Include what diverged, why it diverged, whether the implementation or original artifact is now source of truth, and any follow-up artifact updates or explicit deferral. Do not leave accepted design drift only in chat, a review artifact, or code comments; final summary generation depends on `implementation.md` preserving the delta.
+
 ## Progress Indicators (User-Facing)
 
 When executing this skill, provide lightweight progress feedback so the user can tell what's happening after they confirm.
@@ -159,132 +162,204 @@ Forbidden: Selected: Tier 2 — Inline because the user did not separately menti
 
 **Legacy state migration:** If `state.md` contains `oat_execution_mode: subagent-driven`, silently ignore it. On the next bookkeeping write, remove that key. Do not redirect to `oat-project-subagent-implement` — that skill is deprecated.
 
-### Runtime dispatch selection
+### Dispatch Ceiling Preflight
 
-Before each phase implementation dispatch, choose and log the phase's runtime dispatch controls. This is separate from the Tier 1/Tier 2 execution mode above: Tier 1/Tier 2 decides whether OAT uses subagents or inline fallback; runtime dispatch selection decides the model and effort controls to use for the specific phase when the host exposes them.
+Before any phase work, resolve and print the OAT dispatch ceiling for the
+current provider. This is a preflight gate, not a mid-run question.
 
-Use these inputs:
+Use the CLI helper as the source of truth for resolution:
 
-- phase ID
-- phase scope, including task count, file boundaries, verification commands, and integration risk
-- optional `## Dispatch Profile` row in `plan.md`
-- host-exposed provider controls, by axis
-- prior outcomes for the phase, including review results and failed retries
+```bash
+oat project dispatch-ceiling resolve --provider <codex|claude> --preflight --json
+```
 
-Selection rule:
+If `oat` is not in PATH, use:
 
-1. If a valid Dispatch Profile override row applies and the host can honor it, use the requested provider control and log that the choice came from the override.
-2. If no override applies, choose the lowest available model and/or effort that can confidently complete the phase.
-3. Treat model and effort as separate axes. Each axis logs exactly one state:
-   - `selected:<value>` — host exposes the axis and the orchestrator chose a value.
-   - `inherited` — 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.
-4. In Codex implementation/fix dispatch, the model axis normally logs `inherited`; choose `effort_axis=selected:low|medium|high` from phase complexity and dispatch the matching effort-specific implementer role. Treat `effort_axis=inherited` as the parent-session ceiling path, not a neutral default.
-5. In Claude Code, when subagent model selection is available, choose the lowest sufficient model on the model axis; the effort axis is `not-applicable` because Claude Code does not expose a separate `reasoning_effort` control for subagent dispatch.
-6. If a host uses model/effort internally but exposes neither axis to the orchestrator, log `model_axis=host-auto, effort_axis=host-auto` and include the rationale that would have informed selection.
-7. If confidence is low, choose a stronger available control before dispatch rather than knowingly underpowering the phase.
+```bash
+pnpm run cli -- project dispatch-ceiling resolve --provider <codex|claude> --preflight --json
+```
 
-**Payload-first dispatch invariant.** Select dispatch controls, construct the actual host dispatch argument map, then print the dispatch log from that argument map. Do not emit an `OAT Dispatch:` block with a `Model axis: selected:<value>` or `Effort axis: selected:<value>` field until the corresponding host-tool selection is present in the argument map you are about to call. A selected axis that exists only in the Phase Scope text is invalid; if you cannot or will not pass the host-tool selection, log that axis as `inherited`, `not-applicable`, or `host-auto` instead of `selected:<value>`.
+Resolution order:
 
-**Passing axis values to the host dispatch API.** The log shape and the actual dispatch call must agree: never log a `selected:<value>` axis without passing the corresponding parameter on the dispatch invocation, and never pass an explicit parameter that the log does not reflect.
+1. Effective config key `workflow.dispatchCeiling.<provider>` via the resolver CLI
+2. Project `state.md` frontmatter key `oat_dispatch_ceiling`
+3. Interactive implementation preflight prompt
+4. Non-interactive unresolved: block before work starts
 
-- **Claude Code implementer/fix dispatch:** when `model_axis=selected:<value>`, pass `model: "<value>"` on the Task tool call. When `model_axis=inherited`, omit the `model` parameter so Claude Code uses its own default. `effort_axis=not-applicable` for both cases because the Task tool exposes no per-dispatch `reasoning_effort` control.
-- **Codex implementer/fix dispatch:** default to a selected effort. Classify phase complexity, choose the lowest sufficient `effort_axis=selected:low|medium|high`, and dispatch the matching configured role: `agent_type: "oat-phase-implementer-low"`, `agent_type: "oat-phase-implementer-medium"`, or `agent_type: "oat-phase-implementer-high"`. Those roles set `model_reasoning_effort` in `.codex/agents/*.toml`. Use the base `agent_type: "oat-phase-implementer"` only when `effort_axis=inherited` is intentionally selected for an allowed reason below. Do not use top-level per-call `reasoning_effort` as the standard OAT selected-effort path; dogfooding showed that path can be inconsistent in some Codex runs.
-- **Codex inherited effort is the ceiling path:** because inherited effort follows the parent/orchestrator session and may be `xhigh`, do not use `effort_axis=inherited` merely because it is valid, convenient, or avoids choosing a selected effort. Use inherited effort for Codex implementer/fix dispatch only when the user explicitly requested inherited/default parent controls; a valid Dispatch Profile row explicitly requests inherited/default controls; the phase requires the parent-session ceiling and `selected:high` is insufficient; or the selected-effort roles are unavailable or fail to resolve. The dispatch rationale must cite the allowed reason. For ceiling-needed dispatch, explain why `selected:high` is insufficient.
-- **Codex xhigh:** do not create or select an `xhigh` implementer variant. Use `xhigh` only when the parent/orchestrator session is already xhigh and therefore `effort_axis=inherited` on the base role is the correct representation. If a phase appears to require xhigh while the parent is not xhigh, choose `selected:high` only if high is sufficient; otherwise split/revise the phase or stop for user re-invocation at xhigh.
-- **Claude Code `opus`:** unlike Codex `xhigh`, `opus` is directly selectable. Claude Code exposes `opus` through the Task tool's `model` parameter, so OAT may select it when available (`model_axis=selected:opus`) — including as a terminal escalation step. There is no `opus` inherited-only restriction; the `xhigh` rule above is specific to Codex's effort-variant mechanism, not a general "never select the maximum tier" rule.
-- **Reviewer dispatch on either host:** use `model_axis=inherited` by default. For `effort_axis`: use `inherited` on hosts that expose an effort axis (such as Codex); use `not-applicable` on hosts that do not expose a meaningful effort axis (such as Claude Code). Omit `model` and, on Codex, `reasoning_effort` overrides entirely.
+Provider values:
 
-Codex selected-effort implementer/fix dispatch shape:
+- Codex: `low`, `medium`, `high`, `xhigh`
+- Claude: `haiku`, `sonnet`, `opus`
 
-```yaml
-agent_type: oat-phase-implementer-low # or oat-phase-implementer-medium/high
-message: |
-  Phase Scope:
-    model_axis: inherited
-    effort_axis: selected:low
-    ...
+For Codex, also resolve the provider default effort when possible by reading
+Codex configuration (for example `.codex/config.toml`). If it cannot be found,
+display `unknown`. Do not treat provider default as the OAT ceiling.
+The resolver prints this as `providerDefaultEffort` in JSON and includes it in
+human-readable output.
+
+Print this before phase work:
+
+```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.
 ```
 
-Invalid Codex selected-effort dispatch shape:
+If no ceiling resolves and the session is interactive, ask before starting
+implementation and persist the answer in project `state.md` frontmatter:
 
 ```yaml
-agent_type: oat-phase-implementer
-reasoning_effort: low
-message: |
-  Phase Scope:
-    effort_axis: selected:low
+oat_dispatch_ceiling:
+  provider: codex
+  value: high
+  source: project-state
 ```
 
-The invalid shape relies on per-call override behavior that has proven inconsistent during dogfooding. It also risks creating a log/dispatch mismatch if the override is ignored.
+If no ceiling resolves and `OAT_NON_INTERACTIVE=1` or no user-response channel
+exists, rerun the resolver with non-interactive behavior and stop before work
+starts if it blocks:
 
-**Post-spawn verification gate.** After any Codex implementer/fix `spawn_agent` call with `effort_axis=selected:<value>`, immediately inspect the returned spawn status before waiting for work or updating the plan. If the status shows a different effort, such as `effort_axis=selected:low` followed by `(gpt-5.5 high)`, this is an orchestration deviation. Stop using that agent, record the mismatch in `implementation.md`, and redispatch with the correct effort-specific `agent_type`. Do not continue to `wait_agent`, phase bookkeeping, or the next phase with a mismatched selected-effort dispatch.
+```bash
+oat project dispatch-ceiling resolve --provider <codex|claude> --preflight --non-interactive
+```
+
+```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 mode must report the unresolved ceiling and planned behavior without
+modifying project state.
+
+### Runtime dispatch selection
+
+Before each phase implementation, fix, or review dispatch, choose and log the
+runtime dispatch controls. This is separate from Tier 1/Tier 2 execution mode:
+Tier 1/Tier 2 decides whether OAT uses subagents or inline fallback; runtime
+dispatch selection decides model/effort controls for the specific work.
+
+Use these inputs:
 
-After the payload-first check, log the choice before dispatch in this structured shape:
+- resolved dispatch ceiling and source
+- phase ID and phase scope
+- optional `## Dispatch Profile` row in `plan.md`
+- host-exposed provider controls, by axis
+- prior outcomes for the phase, including review results and failed retries
+
+Axis states:
+
+- `selected:<value>` - host exposes the axis and the orchestrator chose a value.
+- `provider-default` - Codex base/unpinned role follows configured/provider default effort.
+- `inherited` - host/API explicitly inherits the parent setting and OAT can trust that behavior.
+- `not-applicable` - this host/API has no meaningful per-dispatch concept for that axis.
+- `host-auto` - exceptional; the host uses that axis internally but OAT cannot read or pin it.
+
+Codex rules:
+
+1. Codex effort order is `low < medium < high < xhigh`.
+2. Classify preferred effort from scope:
+   - `low`: trivial docs-only, narrow single-file, or mechanical changes
+   - `medium`: normal multi-file implementation and moderate integration risk
+   - `high`: broad architecture, security/auth/redaction boundaries, subtle state behavior, or repeated substantive review failures
+   - `xhigh`: highest-risk work that requires the configured ceiling to allow xhigh
+3. Selected effort is `min(preferred, resolved_ceiling)`.
+4. Dispatch implementer/fix work through `oat-phase-implementer-<selected>`.
+5. Dispatch review work through `oat-reviewer-<resolved_ceiling>` for deterministic quality gate behavior.
+6. Use base/unpinned Codex roles only as a fallback or explicit provider-default choice. Log `Selected effort: provider-default`, display provider default effort when known, and do not describe this as parent-ceiling inheritance.
+7. Do not use top-level per-call `reasoning_effort` as the standard OAT selected-effort path; dogfooding showed that path can be inconsistent.
+
+Claude rules:
+
+- Claude ceiling is model-based: `haiku < sonnet < opus`.
+- Select the lowest sufficient model capped by `workflow.dispatchCeiling.claude` or project `oat_dispatch_ceiling`.
+- Pass `model: "<value>"` when `model_axis=selected:<value>` on the Task tool call.
+- Keep `effort_axis=not-applicable`; Claude Code has no separate per-dispatch effort axis.
+
+Payload-first invariant:
+
+- Build the actual host dispatch argument map before logging.
+- Do not emit `selected:<value>` unless the host invocation contains the corresponding role/model selection.
+- Derive `Dispatch target` and `Effort axis` / `Model axis` from the payload.
+
+Structured dispatch log:
 
 ```text
 OAT Dispatch: Phase {phase_id} {implementation | fix | review}
 Host: {Claude Code | Codex | Cursor | other host}
+Preferred effort: {low | medium | high | xhigh | not-applicable}
+Dispatch ceiling: {resolved ceiling value}
+Selected effort: {low | medium | high | xhigh | provider-default | not-applicable}
+Ceiling source: {repo config | project state | preflight prompt}
+Provider default effort: {value | unknown | not-applicable}
 Model axis: { selected:<value> | inherited | not-applicable | host-auto }
-Effort axis: { selected:<value> | inherited | not-applicable | host-auto }
+Effort axis: { selected:<value> | provider-default | inherited | not-applicable | host-auto }
 Dispatch target: {host-specific subagent/role/tool target}
-Rationale: {short rationale grounded in phase scope}
+Rationale: {short rationale grounded in phase scope and any ceiling cap}
 ```
 
-For Codex implementation/fix dispatches, the rationale must include the phase complexity class that drove the selected effort (for example, mechanical, normal multi-file, or broad/high-risk). If `Effort axis: inherited`, the rationale must also cite the allowed reason for using the parent-session ceiling instead of `selected:low|medium|high`.
-
-Examples:
+Codex capped example:
 
 ```text
-OAT Dispatch: Phase p01 implementation
-Host: Claude Code
-Model axis: selected:haiku
-Effort axis: not-applicable
-Dispatch target: oat-phase-implementer
-Rationale: mechanical template edits; haiku is the lowest sufficient Claude model.
-
 OAT Dispatch: Phase p02 implementation
-Host: Claude Code
-Model axis: selected:sonnet
-Effort axis: not-applicable
-Dispatch target: oat-phase-implementer
-Rationale: multi-file integration with mock wiring; sonnet is the lowest sufficient Claude model.
-
-OAT Dispatch: Phase p03 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 with cross-file contracts; medium is the lowest sufficient Codex effort.
+Rationale: normal multi-file implementation; high preferred due to integration risk, capped by configured ceiling.
+```
 
-OAT Dispatch: Phase p04 implementation
-Host: Other
-Model axis: host-auto
-Effort axis: host-auto
-Dispatch target: host default
-Rationale: host does not expose readable or pinnable dispatch controls; rationale maps to standard effort.
+Codex reviewer example:
 
-OAT Dispatch: Phase p05 review
+```text
+OAT Dispatch: Phase p02 review
 Host: Codex
+Preferred effort: high
+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.
 ```
 
-Use `low` for trivial docs-only, narrow single-file, or mechanical changes; `medium` for normal multi-file implementation and moderate integration risk; `high` for broad architecture, security/auth/redaction boundaries, subtle state behavior, or repeated substantive review failures. Use inherited `xhigh` only when the parent/orchestrator session is already xhigh.
+Codex base/unpinned fallback example:
+
+```text
+OAT Dispatch: Phase p02 review
+Host: Codex
+Preferred effort: provider-default
+Dispatch ceiling: high
+Selected effort: provider-default
+Ceiling source: project state
+Provider default effort: medium
+Model axis: inherited
+Effort axis: provider-default
+Dispatch target: oat-reviewer
+Rationale: base unpinned role fallback; effective effort follows Codex provider default.
+```
 
-Include the resolved implementation dispatch axes and rationale in the Phase Scope packet when known. Reserve `host-auto` for an axis the host uses internally but the orchestrator cannot read or pin; use `inherited` for deliberate inheritance and `not-applicable` when an axis is not meaningful for that host/API.
+Include resolved dispatch context in scope packets when known:
 
 ```yaml
 model_axis: { selected:<value> | inherited | not-applicable | host-auto }
-effort_axis: { selected:<value> | inherited | not-applicable | host-auto }
+effort_axis:
+  {
+    selected:<value> | provider-default | inherited | not-applicable | host-auto,
+  }
+dispatch_ceiling: { resolved ceiling value }
+ceiling_source: { repo config | project state | preflight prompt }
+provider_default_effort: { value | unknown | not-applicable }
 dispatch_rationale: { short rationale }
 ```
 
-Review dispatch is intentionally different. A reviewer should inherit the parent session's model and effort axes unless the user explicitly requests a review override. In Codex, omit `model` and `reasoning_effort` overrides when spawning `oat-reviewer`; in Claude Code, do not pass a per-review model override. Log review scope as `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).
-
 ### Dry-Run Mode
 
 When the skill is invoked with `--dry-run`:
@@ -557,25 +632,29 @@ For each phase `pNN` in the plan (or each phase in the current parallel group),
      spec: {PROJECT_PATH}/spec.md
      implementation: {PROJECT_PATH}/implementation.md
      discovery: {PROJECT_PATH}/discovery.md
+   delta_recording: record any intentional divergence from spec/design/plan in implementation.md with rationale, source of truth, and follow-up artifact disposition
    commit_convention: {from plan.md header}
    workflow_mode: {from state.md or plan.md frontmatter}
    model_axis: {selected:<value> | inherited | not-applicable | host-auto; omit if unknown}
-   effort_axis: {selected:<value> | inherited | not-applicable | host-auto; omit if unknown}
+   effort_axis: {selected:<value> | provider-default | inherited | not-applicable | host-auto; omit if unknown}
+   dispatch_ceiling: {resolved ceiling value; omit if unknown}
+   ceiling_source: {repo config | project state | preflight prompt; omit if unknown}
+   provider_default_effort: {value | unknown | not-applicable; omit if unknown}
    dispatch_rationale: {short rationale; omit if unknown}
    ```
 
 2. Perform a pre-dispatch assertion against the host invocation parameters. The Phase Scope fields are audit/context fields; selected axes must also be represented in the actual host dispatch call.
    - Codex implementer/fix dispatch:
-     - Before building the `spawn_agent` argument map, classify the phase complexity and choose the lowest sufficient selected effort (`low`, `medium`, or `high`) when the matching effort-specific role is available.
-     - Build the `spawn_agent` argument map before logging the dispatch. If `effort_axis=selected:low|medium|high`, the argument map MUST use the matching `agent_type`: `"oat-phase-implementer-low"`, `"oat-phase-implementer-medium"`, or `"oat-phase-implementer-high"`. Then derive the `OAT Dispatch:` block `Effort axis:` field from that same argument map.
+     - Before building the `spawn_agent` argument map, classify the phase complexity and choose preferred effort (`low`, `medium`, `high`, or `xhigh`), then cap it to the resolved Codex dispatch ceiling.
+     - Build the `spawn_agent` argument map before logging the dispatch. If `effort_axis=selected:low|medium|high|xhigh`, the argument map MUST use the matching `agent_type`: `"oat-phase-implementer-low"`, `"oat-phase-implementer-medium"`, `"oat-phase-implementer-high"`, or `"oat-phase-implementer-xhigh"`. Then derive the `OAT Dispatch:` block `Effort axis:` field from that same argument map.
      - Example selected low payload shape: `agent_type: "oat-phase-implementer-low"` and a Phase Scope message containing `effort_axis: selected:low`.
      - Immediately after spawning, compare the returned Codex status line with the selected effort before waiting on the agent. If the spawned status reports a different effort than the selected value (for example, the log says `effort_axis=selected:medium` but the spawn result reports `gpt-5.5 high`), treat this as an orchestration deviation. Stop, record the deviation in `implementation.md`, and redispatch with corrected parameters before continuing. Do not use work from the mismatched dispatch.
-     - If `effort_axis=inherited`, use base `agent_type: "oat-phase-implementer"` and omit `reasoning_effort`. This is the parent-session ceiling path, so the dispatch rationale MUST cite the explicit user/Dispatch Profile override, explain why `selected:high` is insufficient, or record that the selected-effort roles are unavailable or failed to resolve.
+     - If `effort_axis=provider-default`, use base `agent_type: "oat-phase-implementer"` and omit `reasoning_effort`. The dispatch rationale MUST say this is a base/unpinned fallback and include provider default effort when known.
    - Claude Code implementer/fix dispatch:
      - If `model_axis=selected:<value>`, the Task tool call MUST include `model: "<value>"`.
      - If `model_axis=inherited`, omit `model`.
 
-3. Dispatch the selected implementer role (Tier 1 via provider-native subagent mechanism) — the role asserted in the pre-dispatch step above (e.g., `oat-phase-implementer-low`, `oat-phase-implementer-medium`, `oat-phase-implementer-high`, or base `oat-phase-implementer` for inherited effort) — with the Phase Scope block as input and with the asserted host invocation parameters.
+3. Dispatch the selected implementer role (Tier 1 via provider-native subagent mechanism) — the role asserted in the pre-dispatch step above (e.g., `oat-phase-implementer-low`, `oat-phase-implementer-medium`, `oat-phase-implementer-high`, `oat-phase-implementer-xhigh`, or base `oat-phase-implementer` only for provider-default fallback) — with the Phase Scope block as input and with the asserted host invocation parameters.
 
 4. Receive the structured summary (DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED).
 
@@ -610,8 +689,8 @@ Escalate the runtime dispatch control when there is evidence that the current co
 When escalation is needed:
 
 1. If a stronger available control exists, re-dispatch at the next stronger control and include the reason in the scope packet. The escalation ladder is provider-specific:
-   - **Codex:** `selected:low → selected:medium → selected:high → exhausted`. `high` is the strongest control OAT can select. Beyond `high`: if the parent/orchestrator session is already `xhigh`, dispatch uses `effort_axis=inherited`; otherwise escalation is exhausted — stop, split the phase, or ask the user to re-invoke at `xhigh` (see step 4).
-   - **Claude Code:** `selected:haiku → selected:sonnet → selected:opus`. `opus` is a selectable terminal step when available (and not capped by a future Claude-specific ceiling).
+   - **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.
 2. Count the escalation redispatch against the existing bounded retry budget. Escalation changes the control; it does not create extra retry attempts.
 3. Record a compact note in `implementation.md` when practical:
    - `Dispatch: p03 escalated to model_axis=selected:opus, effort_axis=not-applicable after repeated review failures.` (Claude Code)
@@ -630,8 +709,9 @@ After the implementer returns DONE (or DONE_WITH_CONCERNS without correctness co
 **Dispatch:**
 
 - Use the same tier that was selected at start.
-- Inherit the parent session's model/effort/control for review. Do not choose a separate reviewer model or reasoning effort unless the user explicitly requests an override.
-- Tier 1: dispatch `oat-reviewer` via provider-native subagent mechanism with Review Scope:
+- For Codex, dispatch the reviewer variant matching the resolved ceiling (`oat-reviewer-low|medium|high|xhigh`) for deterministic quality gates.
+- For Claude Code, cap any selected review model by the resolved Claude ceiling and keep `effort_axis=not-applicable`.
+- Tier 1: dispatch the selected reviewer target via provider-native subagent mechanism with Review Scope:
 
   ```
   project: {PROJECT_PATH}
@@ -642,13 +722,16 @@ After the implementer returns DONE (or DONE_WITH_CONCERNS without correctness co
   workflow_mode: {from state.md}
   artifact_paths: {same as Phase Scope}
   tasks_in_scope: {list of pNN-tNN IDs in the phase}
+  dispatch_ceiling: {resolved ceiling value}
+  ceiling_source: {repo config | project state | preflight prompt}
+  provider_default_effort: {value | unknown | not-applicable}
   model_axis: inherited
-  effort_axis: inherited   # on Codex; use not-applicable on Claude Code
-  dispatch_rationale: review dispatch inherits parent session controls
+  effort_axis: selected:{resolved Codex ceiling}   # on Codex; use not-applicable on Claude Code
+  dispatch_rationale: reviewer runs at the configured ceiling for deterministic quality gate behavior
   ```
 
   - For Codex Tier 1 dispatches, send the Review Scope block as a self-contained packet and keep fresh context (`fork_context: false`). The reviewer is expected to reconstruct context from git state and the OAT artifacts listed above.
-  - For Codex Tier 1 review dispatches, omit `model` and `reasoning_effort` overrides in the `spawn_agent` call. For Claude Code review dispatches, do not pass a per-review model override. `host-auto` is not the right label when the review is intentionally inheriting parent controls.
+  - For Codex Tier 1 review dispatches, use `agent_type: "oat-reviewer-low|medium|high|xhigh"` matching the resolved ceiling. Use base `oat-reviewer` only as a provider-default fallback and log `effort_axis=provider-default`. For Claude Code review dispatches, do not pass a per-review effort override because the effort axis is not applicable; if selecting a model, cap it by the resolved Claude ceiling.
   - Treat the commit range as authoritative for review scope. `files_changed` is optional orientation metadata only.
   - If a Codex reviewer does not return a terminal result on the first wait, poll once more. If it still has not concluded, send one concise nudge to return immediately with current findings. If the reviewer still does not conclude, treat the Tier 1 review dispatch as failed for this phase and perform the review inline instead of waiting indefinitely.
 
@@ -669,7 +752,7 @@ On reviewer verdict `fail`, run a bounded fix loop.
 
 1. Read `oat_orchestration_retry_limit` from `state.md` frontmatter (default: `2`, range 0–5).
 2. For each retry (up to the limit):
-   a. Select/log fix dispatch axes from the fix scope, then perform the same pre-dispatch assertion used for implementation dispatch. A Codex fix dispatch with `effort_axis=selected:low|medium|high` MUST use matching `agent_type: "oat-phase-implementer-low|medium|high"`; a Claude Code fix dispatch with `model_axis=selected:<value>` MUST pass `model: "<value>"` on the Task call.
+   a. Select/log fix dispatch axes from the fix scope, then perform the same pre-dispatch assertion used for implementation dispatch. A Codex fix dispatch with `effort_axis=selected:low|medium|high|xhigh` MUST use matching `agent_type: "oat-phase-implementer-low|medium|high|xhigh"`; a Claude Code fix dispatch with `model_axis=selected:<value>` MUST pass `model: "<value>"` on the Task call.
    b. Dispatch the selected phase implementer role in `fix` mode (Tier 1) OR read the agent and apply fixes inline (Tier 2), with: - `review_artifact`: the path written by the reviewer - `findings`: the Critical + Important findings list - `prior_summary`: the last implementer summary
    c. Receive the fix summary.
    d. Re-dispatch the reviewer with the updated commit range.
@@ -793,6 +876,14 @@ Append a new entry to the `## Orchestration Runs` section between the `<!-- orch
 #### Outstanding Items
 
 - {None | list of excluded phases with review paths and worktree paths}
+
+#### Artifact / Design Deltas
+
+Run-scoped snapshot only. The durable record is `## Deviations from Plan / Design`; consolidate any non-`None` entries there at the next phase boundary.
+
+| Task / Review                 | Source Artifact                     | Planned / Documented            | Actual / Accepted                      | Reason                       | Source of Truth           | Follow-up                                   |
+| ----------------------------- | ----------------------------------- | ------------------------------- | -------------------------------------- | ---------------------------- | ------------------------- | ------------------------------------------- |
+| {task_id/review_id or `None`} | {spec.md/design.md/plan.md section} | {planned behavior/taxonomy/API} | {actual shipped behavior/taxonomy/API} | {why divergence is accepted} | {implementation/artifact} | {artifact update task or explicit deferral} |
 ```
 
 Append only — never overwrite prior run entries.
@@ -887,6 +978,14 @@ When pausing:
   - Verification run
   - Notable decisions/deviations
 
+**Design/artifact deltas (required when present):**
+
+- If a completed task intentionally diverged from `spec.md`, `design.md`, or `plan.md`, update the `## Deviations from Plan / Design` table in `implementation.md`.
+- For existing project artifacts, treat any `## Deviations...` heading as the deviations section; migrate to the preferred `## Deviations from Plan / Design` heading and table shape when already touching the section.
+- Each delta must include: the affected source artifact/section, the planned/documented expectation, the actual shipped implementation, the reason the divergence is accepted, the current source of truth, and any follow-up artifact update task or explicit deferral.
+- If the implementation is now source of truth and the design/spec/plan is stale, write that directly. Do not treat the stale artifact as a no-op just because code is correct.
+- If no deltas exist for the phase, do not invent one; leave the table unchanged.
+
 **Bookkeeping commit (required):**
 
 **DO NOT SKIP.** This commit prevents state drift across sessions.

package/assets/skills/oat-project-plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-plan
-version: 1.3.2
+version: 1.3.3
 description: Use when design.md is complete and executable implementation tasks are needed. Breaks design into bite-sized TDD tasks in canonical plan.md format.
 disable-model-invocation: true
 user-invocable: true
@@ -312,6 +312,62 @@ Unless the source artifact or user already supplied a confirmed `oat_plan_hill_p
 
 If `## Planning Checklist` is missing (older plans), add it before finalizing with the items above.
 
+### Step 11.5: Resolve Dispatch Ceiling Before Implementation Readiness
+
+Before marking the plan ready for implementation, resolve the dispatch ceiling
+for the current provider.
+
+Resolution order:
+
+1. Repo/user/local config key `workflow.dispatchCeiling.<provider>` via `oat config get`
+2. Project `state.md` frontmatter key `oat_dispatch_ceiling`
+3. Interactive planning prompt
+4. Leave unresolved for implementation preflight when non-interactive
+
+Provider values:
+
+- Codex: `low`, `medium`, `high`, `xhigh`
+- Claude: `haiku`, `sonnet`, `opus`
+
+If no ceiling resolves for the current provider and the session is interactive,
+ask once before final plan review:
+
+```text
+No Codex dispatch ceiling is configured for this project.
+
+Choose the maximum Codex reasoning effort OAT may dispatch during implementation:
+low | medium | high | xhigh
+
+This controls implementer/reviewer subagent variants. It does not change your Codex config.
+```
+
+Adapt the wording for Claude:
+
+```text
+No Claude dispatch ceiling is configured for this project.
+
+Choose the maximum Claude model tier OAT may dispatch during implementation:
+haiku | sonnet | opus
+
+This controls provider-native subagent model selection. It does not change your Claude config.
+```
+
+Persist the answer in `"$PROJECT_PATH/state.md"` frontmatter:
+
+```yaml
+oat_dispatch_ceiling:
+  provider: codex
+  value: high
+  source: project-state
+```
+
+Do not prompt when `OAT_NON_INTERACTIVE=1` or when no user-response channel
+exists. In that case, leave the value unresolved. `oat-project-implement`
+must block before work starts if it still cannot resolve a ceiling.
+
+Do not treat Codex provider default effort as the OAT dispatch ceiling. Provider
+default is informational for base/unpinned roles only.
+
 ### Step 12: Review Plan with User
 
 Present plan summary:

package/assets/skills/oat-project-plan-writing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-plan-writing
-version: 1.2.3
+version: 1.2.4
 description: Use when authoring or mutating plan.md in any OAT workflow. Defines canonical format invariants — stable task IDs, required sections, review table rules, and resume guardrails.
 disable-model-invocation: true
 user-invocable: false
@@ -48,6 +48,10 @@ Runtime routing note:
 
 - Keep `oat_ready_for` canonical as `oat-project-implement`.
 - Declare parallelism via `oat_plan_parallel_groups` in plan.md frontmatter (empty = sequential; nested arrays of phase IDs = parallel groups). `oat-project-implement` reads this field to choose sequential vs worktree-isolated parallel execution.
+- Dispatch ceilings are not stored in `plan.md`. Plan-producing skills resolve
+  them from `workflow.dispatchCeiling.<provider>` or project `state.md`
+  frontmatter, then persist interactive answers back to `state.md` as
+  `oat_dispatch_ceiling`.
 
 Additional frontmatter keys (`oat_phase`, `oat_phase_status`, `oat_blockers`, `oat_last_updated`, `oat_generated`, `oat_template`, `oat_import_reference`, `oat_import_source_path`, `oat_import_provider`) are set by calling skills as needed.
 
@@ -71,7 +75,7 @@ Validation rules for explicit rows:
 
 - `Phase` must match a real `pNN` phase in the plan.
 - `Claude model` must be `haiku`, `sonnet`, `opus`, `auto`, or blank.
-- `Codex effort` must be `low`, `medium`, `high`, `xhigh`, `auto`, or blank. In Codex, `low`, `medium`, and `high` map to effort-specific implementer roles. Codex xhigh is inherited-only; `xhigh` can be honored only by inheriting an already-xhigh parent/orchestrator session, not by selecting an `xhigh` implementer variant.
+- `Codex effort` must be `low`, `medium`, `high`, `xhigh`, `auto`, or blank. In Codex, explicit effort values are preferred controls that `oat-project-implement` caps against the resolved OAT dispatch ceiling and maps to pinned implementer variants when selected. Provider default effort is informational for base/unpinned roles and is not an OAT ceiling.
 - Blank or `auto` means no explicit constraint for that provider.
 - `Rationale` is recommended and should explain why runtime selection should not decide on its own.
 

package/assets/skills/oat-project-quick-start/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-quick-start
-version: 2.1.1
+version: 2.1.2
 description: Use when a task is small enough for quick mode or rapid iteration is preferred. Scaffolds a lightweight OAT project from discovery directly to a runnable plan, with optional brainstorming and lightweight design.
 argument-hint: '<project-name> ["project description"]'
 disable-model-invocation: true
@@ -456,6 +456,62 @@ Required parallelism pass before finalizing the plan:
 - Quick mode is not "sequential by default." A quick-start plan is sequential only when the dependency and write-set analysis says it should be.
 - When a task claims scoped verification, prefer the exact runner invocation that truly scopes to the intended file, test, or target instead of package-level shortcuts that may execute the full suite.
 
+### Step 3.5: Resolve Dispatch Ceiling Before Implementation Readiness
+
+Before moving the quick project to ready-for-implementation, resolve the
+dispatch ceiling for the current provider.
+
+Resolution order:
+
+1. Repo/user/local config key `workflow.dispatchCeiling.<provider>` via `oat config get`
+2. Project `state.md` frontmatter key `oat_dispatch_ceiling`
+3. Interactive quick-planning prompt
+4. Leave unresolved for implementation preflight when non-interactive
+
+Provider values:
+
+- Codex: `low`, `medium`, `high`, `xhigh`
+- Claude: `haiku`, `sonnet`, `opus`
+
+If no ceiling resolves for the current provider and the session is interactive,
+ask once before finalizing `plan.md`:
+
+```text
+No Codex dispatch ceiling is configured for this project.
+
+Choose the maximum Codex reasoning effort OAT may dispatch during implementation:
+low | medium | high | xhigh
+
+This controls implementer/reviewer subagent variants. It does not change your Codex config.
+```
+
+Adapt the wording for Claude:
+
+```text
+No Claude dispatch ceiling is configured for this project.
+
+Choose the maximum Claude model tier OAT may dispatch during implementation:
+haiku | sonnet | opus
+
+This controls provider-native subagent model selection. It does not change your Claude config.
+```
+
+Persist the answer in `"$PROJECT_PATH/state.md"` frontmatter:
+
+```yaml
+oat_dispatch_ceiling:
+  provider: codex
+  value: high
+  source: project-state
+```
+
+Do not prompt when `OAT_NON_INTERACTIVE=1` or when no user-response channel
+exists. In that case, leave the value unresolved. `oat-project-implement`
+must block before work starts if it still cannot resolve a ceiling.
+
+Do not treat Codex provider default effort as the OAT dispatch ceiling. Provider
+default is informational for base/unpinned roles only.
+
 ### Step 4: Sync Project State
 
 Update `"$PROJECT_PATH/state.md"`:

package/assets/skills/oat-project-review-provide/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-review-provide
-version: 1.3.3
+version: 1.3.4
 description: Use when completed work in an active OAT project needs a quality gate before merge. Performs a lifecycle-scoped review after a task, phase, or full implementation, unlike oat-review-provide.
 disable-model-invocation: true
 user-invocable: true
@@ -15,6 +15,8 @@ Request and execute a code or artifact review for the current project scope.
 
 Produce an independent review artifact that verifies requirements/design alignment (mode-aware) and code quality.
 
+Reviewers should distinguish implementation defects from artifact drift. If code is defensible but `spec.md`, `design.md`, or `plan.md` is stale, frame the finding as artifact alignment rather than a required code change.
+
 ## Prerequisites
 
 **Required:** Active project with at least one completed task.
@@ -481,6 +483,12 @@ Build the "Review Scope" metadata for the reviewer:
 - Deferred Medium count: {DEFERRED_MEDIUM_COUNT}
 - Deferred Minor count: {DEFERRED_MINOR_COUNT}
   {DEFERRED_LEDGER}
+
+**Design Drift Review Guidance:**
+
+- If implementation differs from `spec.md`, `design.md`, or `plan.md`, decide whether the code should change or whether the artifact is stale.
+- Use artifact-alignment framing when shipped implementation is defensible and the lifecycle artifact should be updated.
+- Do not force a code-defect framing for accepted design drift; `oat-project-review-receive` can convert artifact drift into alignment tasks or explicit deferrals.
 ```
 
 ### Step 6: Execute Review (3-Tier Capability Model)