@open-agent-toolkit/cli 0.1.45 → 0.1.48

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

@@ -1,6 +1,6 @@
 ---
 name: oat-project-plan-writing
-version: 1.2.6
+version: 1.2.8
 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
@@ -23,6 +23,227 @@ This is a sub-phase indicator; the calling skill owns the top-level banner.
 
 - When invoked by a calling skill, print the sub-banner immediately before plan authoring begins.
 
+## Managed Dispatch Readiness and Review Contract
+
+All plan-producing workflows and their artifact reviews use this contract:
+spec-driven planning, quick-start, imported plans, and provider-plan-via-import.
+The contract runs before a plan becomes implementation-ready and immediately
+before each artifact review dispatch.
+
+1. Resolve the active provider through the CLI source of truth. For artifact
+   review, always request the reviewer contract:
+
+   ```bash
+   oat project dispatch-ceiling resolve --provider "$ACTIVE_PROVIDER" --role reviewer --preflight --json
+   ```
+
+### Complete Dispatch Ladder Adoption Contract
+
+Before any plan becomes implementation-ready, inspect the effective
+`workflow.dispatchCeiling.providers` value and compare its ordered candidate
+ladders with the bundled
+`packages/cli/config/dispatch-matrix-recommendation.json` source (or the
+installed bundle's `config/dispatch-matrix-recommendation.json` asset). A
+complete custom ladder is allowed, but every supported provider must have valid
+ordered `candidates` cells through the named project ceiling. A legacy scalar,
+single fallback route, missing tier, empty candidates array, or malformed
+ordering is not a complete ladder.
+
+When the effective ladder is missing or incomplete, show the complete bundled
+recommendation before asking to write anything:
+
+| Provider        | Economy                                                        | Balanced                                                                                                       | High                                                        | Frontier                               |
+| --------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | -------------------------------------- |
+| Codex           | Luna/low, Luna/medium, Luna/high                               | Luna/xhigh, Terra/low, Terra/medium, Terra/high, Terra/xhigh                                                   | Sol/low, Sol/medium, Sol/high                               | Sol/xhigh, Sol/max                     |
+| Claude          | haiku, sonnet                                                  | sonnet                                                                                                         | opus                                                        | fable                                  |
+| Cursor (opaque) | `gpt-5.6-luna-low`, `gpt-5.6-luna-medium`, `gpt-5.6-luna-high` | `gpt-5.6-luna-xhigh`, `gpt-5.6-terra-low`, `gpt-5.6-terra-medium`, `gpt-5.6-terra-high`, `gpt-5.6-terra-xhigh` | `gpt-5.6-sol-low`, `gpt-5.6-sol-medium`, `gpt-5.6-sol-high` | `gpt-5.6-sol-xhigh`, `gpt-5.6-sol-max` |
+
+Ask the user to select the owning scope explicitly before any adoption write:
+
+1. **Shared repository** - team-owned `.oat/config.json`; run
+   `oat config adopt dispatch-matrix --shared`.
+2. **Repo-local checkout** - personal `.oat/config.local.json`; run
+   `oat config adopt dispatch-matrix --local`.
+3. **User** - cross-repository `~/.oat/config.json`; run
+   `oat config adopt dispatch-matrix --user`.
+4. **Do not adopt** - leave setup unresolved and block implementation
+   readiness.
+
+The selected ownership scope owns only the reusable ladder. The active
+project's named ceiling is a separate project-state constraint. A
+project-specific active policy or ceiling must not be written to user
+`~/.oat/config.json`.
+
+Adoption preserves explicit cells. Re-run the resolver and re-check the full
+ladder after adoption. If preserved legacy or partial cells still leave the
+ladder incomplete or missing, identify those cells and block; do not overwrite,
+infer, or mark the plan implementation-ready. In non-interactive mode, an
+incomplete or missing ladder blocks readiness without choosing an ownership
+scope.
+
+### Reviewer Ceiling Contract
+
+A managed active-provider result is runnable only when the resolver returns
+concrete native dispatch controls or an explicit deferred cross-harness target.
+Otherwise treat the active-provider reviewer contract as unresolved.
+Reviewer resolution uses the final candidate of the configured review ceiling:
+call `--role reviewer` without an ephemeral implementer candidate request.
+Do not select a lower candidate for artifact, phase, project, or final review
+unless a separate reviewed contract explicitly authorizes reviewer lowering and
+defines its bounds. A `## Dispatch Profile` row alone is not such a contract.
+
+Bind every concrete managed reviewer target to the actual provider
+invocation before probing generic reviewer availability or selecting an
+execution tier. That target takes precedence over every availability, tier,
+timeout, and inline fallback.
+A concrete managed Codex target takes precedence over tier availability.
+
+- Codex: use the exact registered reviewer variant returned by
+  `providers.codex.dispatchArgs.variant` when the host can select that role.
+  If the exact role is unavailable or the current host cannot select it,
+  launch a fresh Codex child with the resolver target's explicit model,
+  reasoning effort, and canonical role instructions from
+  `.agents/agents/oat-reviewer.md`. If the fresh child cannot preserve the
+  target, use only a verified-equivalent inline route or block the review.
+- Claude: require a non-empty `providers.claude.dispatchArgs.model` and put
+  that exact value in the actual provider invocation as its `model` argument.
+- Cursor: treat `providers.cursor.dispatchArgs.model` as opaque and put that
+  exact, unnormalized string in the actual provider invocation as its `model`
+  argument.
+
+Build the actual host invocation payload before declaring the target enforced.
+On timeout, retry, or artifact rewrite/re-dispatch, reuse the same exact role or
+complete provider payload, including the exact model argument. If the host
+cannot apply the required role or model argument, fail closed or block unless
+the guarded inline-equivalence rule below applies. Never continue through a
+generic tier fallback.
+
+Workflow correctness must not require provider restart or hot reload.
+Runtime materialization may be best effort, but it is not the correctness
+boundary. Never use a managed base role because an exact target is missing or
+unavailable in the current session. Base Codex roles are allowed only for
+explicit inherit/default behavior and the documented managed-uncapped reviewer
+fallback.
+
+Inline review of a concrete managed target is permitted only after verifying
+equivalent current-host model and effort controls. Otherwise inline or base
+execution is limited to explicit inherit/default behavior or the documented
+managed-uncapped reviewer fallback.
+
+The Auto Artifact-Review Loop below consumes this reviewer dispatch contract.
+Tier selection happens only after the target-preserving route is known and
+changes execution mechanics, not the resolved model/effort contract.
+
+## Shared Phase-Review Setup Contract
+
+Every plan-producing workflow invokes this procedure after the complete plan
+has stable phase IDs and before the plan artifact review begins. The calling
+skill owns the prompt and the write to `plan.md`; this section owns the shared
+eligibility, preservation, validation, and non-interactive behavior.
+
+### 1. Preserve explicit plan state
+
+Inspect `plan.md` frontmatter before probing configuration. If an explicit
+existing `oat_phase_review_gate` key is present, preserve the complete value
+unchanged. Do not probe targets, prompt, or mutate the setting. This applies to
+enabled, disabled, resumed, and imported explicit values. Report:
+
+```text
+Phase review: preserved existing oat_phase_review_gate setting.
+```
+
+Implementation preflight remains responsible for rejecting a malformed
+explicit value. Planning must not silently repair, replace, or disable it.
+
+### 2. Probe qualifying targets
+
+When no explicit setting exists, run the canonical read-only probe:
+
+```bash
+oat gate target list --json
+```
+
+If `oat` is not available directly, use the repository source CLI with the
+same arguments. Do not select or execute a reviewer during this probe. A target
+qualifies only when all three JSON fields are literal booleans with these
+values:
+
+```text
+target.explicitlyConfigured === true
+target.enabled === true
+target.available === true
+```
+
+Built-in-only, disabled, unavailable, missing, or malformed entries do not
+qualify. Never infer qualification from target origin, runtime, invocation
+metadata, command text, or a merely non-empty target list.
+
+If the probe fails, emit exactly this concise warning and continue planning
+without adding the setting:
+
+```text
+Warning: phase review target probe failed; phase review remains disabled.
+```
+
+If no qualifying target exists, emit:
+
+```text
+Phase review: disabled (no qualifying target); phase review remains disabled.
+```
+
+Do not invent enablement in either branch.
+
+### 3. Offer the canonical choice
+
+When at least one target qualifies and an interactive user-response channel is
+available, offer exactly these outcomes:
+
+1. **All phases** - enable review for every implementation phase.
+2. **Selected phases** - enable review only for chosen stable phase IDs.
+3. **Disabled** - leave phase review disabled.
+
+For all phases, write the existing plan frontmatter shape:
+
+```yaml
+oat_phase_review_gate:
+  enabled: true
+  phases: []
+  review_type: code
+  exit_nonzero_on: important
+```
+
+For selected phases, use the same shape with `phases` populated. Validate the
+selected phase IDs against the actual stable phase IDs in the finished plan.
+Reject unknown IDs and re-prompt instead of persisting them; de-duplicate valid
+IDs and serialize them in plan order, regardless of selection order. Require at
+least one valid phase for this choice.
+
+If the user declines or chooses Disabled, do not add
+`oat_phase_review_gate`; emit:
+
+```text
+Phase review: disabled (user declined); phase review remains disabled.
+```
+
+### 4. Handle non-interactive planning
+
+Non-interactive mode includes `OAT_NON_INTERACTIVE=1` and any environment with
+no user-response channel. Never prompt in this mode. Even when the probe finds
+a qualifying target, do not guess all phases or selected phases and do not
+invent enablement. Leave the setting absent and emit:
+
+```text
+Phase review: disabled (non-interactive; no selection recorded); phase review remains disabled.
+```
+
+### 5. Keep review gates independent from HiLL
+
+This setup is independent from HiLL checkpoints. It must not read or change
+`oat_plan_hill_phases`, `oat_auto_review_at_hill_checkpoints`, or
+`oat_hill_completed`. The qualifying target only controls whether the setup
+choice is offered; normal lifecycle gate commands remain provider-neutral.
+They must not add a provider/model `--target` argument.
+
 ## Auto Artifact-Review Loop
 
 This is the canonical contract for bounded automated reviews of generated OAT artifacts. Calling skills own the concrete edits, progress indicators, and commits; this section defines the shared loop they must follow.
@@ -45,10 +266,11 @@ Use this loop after an artifact has been written and before the calling skill ha
    - The bound controls rewrite/re-dispatch cycles after the initial review. A bound of `0` still permits the initial structured review, then surfaces residual findings without retrying.
 
 3. **Dispatch `oat-reviewer` in structured mode**
-   - Tier 1: use the configured `oat-reviewer` subagent when available and authorized.
-   - Tier 2: if Tier 1 is unavailable or declined, run the same reviewer prompt inline with the same payload and checklist.
+   - When the resolver returned a concrete managed Codex target, use its exact registered reviewer or a fresh child pinned to the same model, effort, and canonical instructions. If neither is possible, run inline only with verified equivalent current-host controls; otherwise block.
+   - When the resolver returned a concrete managed Claude or Cursor target, require `providers.claude.dispatchArgs.model` or `providers.cursor.dispatchArgs.model` respectively and pass that exact value in the actual provider invocation's `model` argument. Cursor values are opaque and must not be normalized. If the host cannot apply the model argument, fail closed unless inline execution has verified equivalent controls.
+   - For explicit inherit/default behavior or the documented managed-uncapped reviewer fallback, Tier 1 uses the configured `oat-reviewer` subagent when available and authorized; Tier 2 may run the same reviewer prompt inline.
    - Always set `oat_output_mode: structured`; the loop consumes `StructuredFindings` in-memory and the reviewer writes no artifact.
-   - Do not downgrade the checklist when falling back inline. The fallback changes only execution tier, not review requirements.
+   - Do not downgrade the resolved target or checklist when changing execution mechanics.
 
 4. **Apply or offer fixes by severity**
    - If the structured review is clean, proceed to outcome recording.
@@ -57,7 +279,7 @@ Use this loop after an artifact has been written and before the calling skill ha
    - If a finding cannot be fixed within the artifact boundary, preserve it as residual and surface it before handoff.
 
 5. **Rewrite and re-dispatch within the bound**
-   - After applying fixes, rewrite the artifact and re-dispatch `oat-reviewer` with the same target payload.
+   - After applying fixes, rewrite the artifact and re-dispatch `oat-reviewer` with the same complete target payload, including the exact Claude or Cursor `dispatchArgs.model` argument.
    - Each rewrite/re-dispatch cycle consumes one retry.
    - Stop when the reviewer returns no findings or when the retry bound is exhausted.
 
@@ -91,16 +313,22 @@ 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 policies are not stored in `plan.md`. Plan-producing skills resolve
-  them from `workflow.dispatchPolicy.*`, compatibility
-  `workflow.dispatchCeiling.*` keys, or project `state.md` frontmatter, then
-  persist interactive answers back to `state.md` as `oat_dispatch_policy`.
+- Reusable candidate ladders are config-owned and are never copied into
+  `plan.md` or project state. Plan-producing skills resolve them from
+  `workflow.dispatchCeiling.*`.
+- Project dispatch policy is a named maximum constraint. Persist interactive
+  project answers to `state.md` as `oat_dispatch_policy`; never copy
+  compiled provider/model targets into that project policy.
 
 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.
 
 ### Dispatch Profile Overrides
 
-`## Dispatch Profile` is optional and should be omitted by default. Runtime selection chooses the lowest available tier/model/effort that can confidently complete each phase.
+`## Dispatch Profile` is optional and should be omitted by default. A profile
+may narrow a phase to a named ceiling at or below the project ceiling. The
+named ceiling is a maximum candidate tier, not an exact model-family or effort
+preference; the later coordinator chooses exact task targets from the complete
+configured ladder.
 
 Only include the section when the user has explicit constraints or preferences. Routine hand-tuning can be worse than runtime selection because the orchestrator has fresher phase context and host capability information at dispatch time.
 
@@ -109,16 +337,19 @@ If a user-authored override is needed, use this table shape:
 ```markdown
 ## Dispatch Profile
 
-| Phase | Claude model                     | Codex effort                   | Rationale                     |
-| ----- | -------------------------------- | ------------------------------ | ----------------------------- |
-| pNN   | haiku\|sonnet\|opus\|fable\|auto | low\|medium\|high\|xhigh\|auto | why this constraint is needed |
+| Phase | Named ceiling                           | Rationale                     |
+| ----- | --------------------------------------- | ----------------------------- |
+| pNN   | economy\|balanced\|high\|frontier\|auto | why this constraint is needed |
 ```
 
 Validation rules for explicit rows:
 
 - `Phase` must match a real `pNN` phase in the plan.
-- `Claude model` must be `haiku`, `sonnet`, `opus`, `fable`, `auto`, or blank.
-- `Codex effort` must be `low`, `medium`, `high`, `xhigh`, `auto`, or blank. In Codex, explicit effort values are preferred controls. `oat-project-implement` caps them when a capped managed policy exists, selects them directly under managed `Uncapped`, and maps selected efforts to pinned implementer variants when available. Provider default effort is informational only for explicit inherit/default behavior or base/unpinned fallback paths.
+- `Named ceiling` must be `economy`, `balanced`, `high`, `frontier`,
+  `auto`, or blank, and it must not exceed the project named ceiling.
+- Under a `High` ceiling, configured candidates from `Economy`, `Balanced`, and
+  `High` remain eligible and available; the row does not pin Sol, a Claude
+  family, a Cursor string, or an effort value.
 - 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.10
+version: 2.1.13
 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"]'
 oat_gateable: true
@@ -434,20 +434,54 @@ git add "$PROJECT_PATH/discovery.md" "$PROJECT_PATH/state.md"
 git diff --cached --quiet || git commit -m "chore(oat): complete quick-start discovery for {project-name}"
 ```
 
+### Step 2.9: Snapshot Explicit Phase-Review Setting Before Plan Rewrite
+
+Before any template-based create, update, replacement, or normalization of
+`"$PROJECT_PATH/plan.md"`, inspect the existing plan frontmatter and snapshot:
+
+1. The key presence of `oat_phase_review_gate` as a separate boolean. Presence
+   is not truthiness: an explicit key is authoritative regardless of validity or
+   value.
+2. When the key is present, the complete explicit value as the exact YAML
+   frontmatter entry, including its full nested mapping or scalar form. Preserve
+   enabled, disabled, selected-phase, `null`, and malformed-for-contract values
+   verbatim; do not normalize, validate, or reconstruct the value while taking
+   the snapshot.
+
+This snapshot protects a resumed explicit value from the template rewrite. Its
+explicit presence must not trigger a target probe or re-prompt, even when the
+preserved value is `null` or malformed for the phase-review contract.
+
 ### Step 3: Generate Plan Directly
 
 Create/update `"$PROJECT_PATH/plan.md"` from `.oat/templates/plan.md`.
 
+Restore the exact snapshot into the resulting `plan.md` frontmatter as part of
+the first resulting plan write, before any later frontmatter rewrite and before
+Step 3.55 invokes the shared setup contract. Carry the snapshot losslessly
+through every subsequent plan update. When the key was explicitly present, its
+complete value must still be present exactly as captured; do not probe,
+re-prompt, validate, or replace it here. When the key was absent, do not invent
+one before the shared setup contract runs.
+
 Required frontmatter updates:
 
-- `oat_status: complete`
-- `oat_ready_for: oat-project-implement`
+- `oat_status: in_progress`
+- `oat_ready_for: null`
 - `oat_phase: plan`
-- `oat_phase_status: complete`
+- `oat_phase_status: in_progress`
 - `oat_plan_source: quick`
 - `oat_import_reference: null`
 - `oat_import_source_path: null`
 - `oat_import_provider: null`
+- `oat_template: true`
+
+These values are the interruption-safe pre-review state. Here,
+`oat_template: true` marks the generated plan as still owned by the current
+planning workflow even after its substantive content has been written. If the
+skill pauses, is interrupted, or cannot resolve dispatch before Step 3.7,
+persist and commit this state. `oat-project-next` must route it back to the
+current planning workflow and cannot advance it to implementation.
 
 Plan requirements — apply `oat-project-plan-writing` canonical format invariants:
 
@@ -470,112 +504,96 @@ Required parallelism pass before finalizing the plan:
 ### Step 3.5: Resolve Dispatch Policy Before Implementation Readiness
 
 Before moving the quick project to ready-for-implementation, resolve the
-dispatch policy.
-
-Resolution order:
-
-1. Config keys `workflow.dispatchPolicy.mode` / `workflow.dispatchPolicy.policy` via the resolver CLI
-2. Layered dispatch matrix / compatibility config under `workflow.dispatchCeiling.providers.<provider>` and `workflow.dispatchCeiling.providers.<provider>.<tier>`
-3. Project `state.md` frontmatter key `oat_dispatch_policy`
-4. Legacy project `state.md` frontmatter key `oat_dispatch_ceiling`
-5. Interactive quick-planning prompt (below)
-6. Leave unresolved for implementation preflight when non-interactive
+complete dispatch ladder and the project named ceiling.
 
-If no policy resolves and the session is interactive, present the dispatch
-policy prompt once before finalizing `plan.md`:
+Invoke the `Complete Dispatch Ladder Adoption Contract` from
+`oat-project-plan-writing`. If the effective ladder is missing or incomplete,
+show the full bundled recommendation and ask the user to select its owning
+scope before running exactly one command:
 
-```text
-Set the dispatch policy — how OAT should choose subagent model/effort controls.
+```bash
+oat config adopt dispatch-matrix --shared
+oat config adopt dispatch-matrix --local
+oat config adopt dispatch-matrix --user
+```
 
-  Managed capped policies:
-  1. Economy   — Codex: medium · Claude: sonnet
-  2. Balanced  — Codex: high   · Claude: sonnet  (recommended)
-  3. High      — Codex: xhigh  · Claude: opus
-  4. Frontier  — Codex: xhigh  · Claude: fable
+The selected scope owns only the reusable ladders. A project-specific active
+policy or ceiling must not be written to user `~/.oat/config.json`.
+Adoption preserves explicit cells, so re-run the resolver and completeness
+check. An incomplete or missing ladder after adoption blocks readiness; do not
+overwrite explicit cells or silently infer a fallback. Non-interactive setup
+also blocks on a missing or incomplete ladder.
 
-  Managed uncapped:
-  5. Uncapped — OAT selects the preferred implementer/fix target without a stored maximum cap.
+Then resolve the named ceiling in this order:
 
-  Host defaults:
-  6. Inherit Host Defaults — OAT does not select model/effort controls.
+1. Project `state.md` frontmatter `oat_dispatch_policy`
+2. Legacy project `oat_dispatch_ceiling`
+3. Config `workflow.dispatchPolicy.*` as a proposed starting value
+4. Interactive quick-planning prompt
+5. Unresolved non-interactive state blocks implementation readiness
 
-OAT applies managed policies where the provider exposes a reliable mechanism
-(Codex: pinned variants; Claude: Task model parameter). Other providers may
-treat managed policies as advisory until their provider column has a resolvable
-matrix cell.
+Generate the canonical prompt with:
 
-For multi-family providers such as Cursor, these options choose the abstract
-policy rung; concrete model values live in the dispatch matrix under
-`workflow.dispatchCeiling.providers.*`. If the user wants OAT's recommended
-starting matrix, offer `oat config adopt dispatch-matrix` for the chosen config
-layer before finalizing `plan.md`.
+```bash
+oat project dispatch-ceiling choices --format markdown
 ```
 
-**Managed capped policy selection (options 1-4)** persists `mode: managed`,
-`policy`, and the compiled provider targets. On selection, print the exact
-compiled result (e.g., "Dispatch policy set: balanced → Codex: high · Claude:
-sonnet") before proceeding.
-
-If the resolver reports that the selected policy has a missing matrix cell for
-the active provider/tier, run prompt-and-persist once before final review:
-
-1. Ask for the exact provider value for the missing cell, using the provider's
-   native vocabulary (for example, `composer-2.5`, `gpt-5.5-xhigh`, `opus`, or
-   `xhigh`), or an ordered route when escalation needs multiple targets.
-2. Persist the answer to the selected config layer with
-   `workflow.dispatchCeiling.providers.<provider>.<tier>`. Use project
-   `state.md` only for sparse project-specific matrix overrides.
-3. Re-run the resolver. Do not silently treat a missing cell as uncapped,
-   inherited, or provider-default behavior.
-
-**Uncapped (option 5)** persists explicit managed uncapped state. It does not
-write provider caps, and it must not be represented by leaving dispatch policy
-state absent.
+Do not hand-type the dispatch policy menu.
+`Uncapped`: OAT still manages dispatch selection. It has no named maximum.
+`Inherit Host Defaults`: OAT does not choose model or effort.
+`Leave Unresolved` is a planning deferral.
+Implementation preflight must block until a runnable ceiling resolves.
 
-**Inherit Host Defaults (option 6)** persists explicit inherit/default state.
-Use this only when the user wants OAT to leave implementation, fix, and review
-model/effort controls to the executing host/provider.
-
-Persist the answer in `"$PROJECT_PATH/state.md"` frontmatter using the
-normalized shape:
+The menu includes every named tier plus `Uncapped`, `Inherit Host
+Defaults`, and `Leave Unresolved`. A named tier is a maximum, never an
+enduring exact model-family or effort preference. A named `High` ceiling
+keeps lower configured `Economy`, `Balanced`, and `High` candidates
+available at or below that maximum. An optional phase Dispatch Profile may
+narrow the maximum.
 
 ```yaml
 oat_dispatch_policy:
   mode: managed
-  policy: balanced
-  providers:
-    codex: high
-    claude: sonnet
+  policy: high
   source: project-state
 ```
 
-For `Uncapped`:
+Persist the active project ceiling only in `"$PROJECT_PATH/state.md"`. Do not
+copy compiled provider targets into this shape or user config. `Uncapped` and
+`Inherit Host Defaults` remain explicit modes; `Leave Unresolved` and
+non-interactive unresolved state are not implementation-ready.
 
-```yaml
-oat_dispatch_policy:
-  mode: managed
-  policy: uncapped
-  source: project-state
-```
+### Step 3.55: Configure Optional Phase Review
 
-For `Inherit Host Defaults`:
+After the generated quick plan has stable phase IDs and before Step 3.6 starts
+the plan artifact review, invoke the `Shared Phase-Review Setup Contract` from
+`oat-project-plan-writing`.
 
-```yaml
-oat_dispatch_policy:
-  mode: inherit
-  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 policy.
+If `plan.md` already contains an explicit `oat_phase_review_gate`, preserve it
+through the shared contract without probing, prompting, or mutation. Otherwise
+let the contract probe qualifying targets and offer all phases, selected
+phases, or disabled. If the probe fails, no target qualifies, or the user
+declines, leave phase review disabled and continue with the contract's concise
+status output.
 
-Do not treat provider default effort as the OAT dispatch policy. Provider
-defaults apply only for explicit inherit/default behavior or base/unpinned
-fallback paths.
+This phase-review setup is independent from HiLL checkpoints. Do not read or
+change HiLL fields here, and do not add a provider/model `--target` to any
+lifecycle command.
 
 ### Step 3.6: Run Plan Artifact Review Loop
 
+Before dispatching the artifact reviewer, invoke the `Managed Dispatch
+Readiness and Review Contract` from `oat-project-plan-writing`:
+
+```bash
+oat project dispatch-ceiling resolve --provider "$ACTIVE_PROVIDER" --role reviewer --preflight --json
+```
+
+If managed resolution or the complete ladder is unresolved, return to Step
+3.5, adopt the recommendation in the selected ownership scope, and re-run the
+resolver. Do not hand the quick plan to implementation while either contract is
+unresolved.
+
 Invoke the shared `Auto Artifact-Review Loop` from `oat-project-plan-writing` with target `plan` before syncing project state or handing off to implementation.
 
 Required payload:
@@ -590,11 +608,44 @@ Apply the shared loop exactly:
 
 - Resolve `workflow.autoArtifactReview.plan`; only an explicit `false` skips the loop.
 - Resolve `oat_orchestration_retry_limit` from project state, defaulting to `2`.
-- Dispatch `oat-reviewer` in structured mode using Tier 1 subagent when available and Tier 2 inline fallback otherwise.
+- For a concrete managed target, dispatch the exact registered reviewer role. If the host cannot select it, launch a fresh Codex child pinned to the resolved model and reasoning effort with the canonical reviewer instructions.
+- For Claude or Cursor, pass the exact resolver-returned
+  `providers.<provider>.dispatchArgs.model` as the actual invocation's model
+  argument. Preserve the same complete payload on timeout and retry; Cursor
+  strings remain opaque.
+- Run inline only with verified equivalent current-host model and effort controls, or for explicit inherit/default behavior or the managed-uncapped reviewer exception. If none applies, fail closed before artifact review.
+- If the reviewer times out or does not conclude, poll and nudge once, then retry the same exact role or pinned child within the retry bound. If that target-preserving retry still fails, fail closed; never downgrade the review to inline.
 - Apply Critical and Important artifact-local fixes when unambiguous; offer Medium and Minor fixes instead of silently applying them.
 - Re-dispatch after rewrites until clean or the retry bound is exhausted.
 - Update the `plan` artifact row in the `## Reviews` table to `passed` when clean. If residual findings remain, preserve the row and surface the residual findings before downstream handoff.
 
+### Step 3.7: Record Review Disposition and Mark Plan Complete
+
+Before changing readiness, durably record the review outcome in `plan.md`:
+
+- When review ran, update the `plan` review row in the `## Reviews` section to
+  the outcome reached by Step 3.6. Use `passed` only for a clean result. If
+  residual findings remain, retain their actual non-passed status and add a
+  concise residual-finding disposition in the same section.
+- When `workflow.autoArtifactReview.plan` is explicitly `false`, record the
+  explicit skip in the `## Reviews` section as
+  `Plan artifact review: skipped (workflow.autoArtifactReview.plan=false)`.
+  Do not claim that the plan passed review.
+
+The review row or explicit skip must be written to `plan.md`; chat or status
+output alone is not durable. Only after that write succeeds, atomically update
+the plan frontmatter:
+
+- `oat_status: complete`
+- `oat_ready_for: oat-project-implement`
+- `oat_phase_status: complete`
+- `oat_template: false`
+
+If dispatch remains unresolved, review execution fails closed, or the outcome
+cannot be recorded, leave the Step 3 pre-review values unchanged and commit
+them before stopping. Never expose a partially reviewed quick plan to
+`oat-project-implement`.
+
 ### Step 4: Sync Project State
 
 Update `"$PROJECT_PATH/state.md"`:
@@ -654,18 +705,29 @@ Before reporting this skill as complete, run the configured gate as the final st
 
    If the command returns JSON `null`, no gate is configured; the skill is complete.
 
-2. If a gate config is returned, run its `command` exactly as configured. Capture stdout, stderr, and the exit code. A zero exit code means the gate passed and the skill is complete.
+2. Export the resolved project path into the command shell:
+
+   ```bash
+   export PROJECT_PATH
+   ```
+
+   If the resolved command invokes `oat gate review`, the configured review command must already include `--project "$PROJECT_PATH"` and must not include `--target <id>`. A valid reusable shape is `oat gate review --project "$PROJECT_PATH" ...`. If the declaration is missing, stop and migrate the stored gate command; do not inject or append arguments at execution time.
+
+3. Execute the resolved command exactly as configured. Capture stdout, stderr, the exit code, and the structured JSON result. A zero exit code means the review passed its threshold, but it does not by itself authorize artifact receipt or complete the handoff.
 
-3. Review-artifact handoff:
-   - If the gate reports a produced review artifact, the host must run `oat-project-review-receive` to receive and disposition that artifact before treating the review as consumed.
-   - This applies to `oat gate review ...` outputs regardless of whether the gate ultimately exits zero or nonzero; the command output owns the exact artifact path, and receive-review owns disposition and archival.
+4. Review-artifact handoff:
+   - Parse the structured gate result. An exit code or artifact path alone never authorizes `oat-project-review-receive`.
+   - Invoke receive only when all three conditions hold: `status` is `ok` or `blocked`, the envelope explicitly sets `receiveEligible: true`, and a non-null `handoff` confirms the artifact was corroborated.
+   - `receiveEligible: false` is a hard stop even when `artifactPath` is present. Never receive `targeting_correlation_failed`; correct the project/run routing and run a new gate.
+   - Keep `artifact_validation_failed` outside receive until the artifact is corrected and the gate successfully revalidates it. Treat `review_failed`, unknown statuses, null handoffs, and contradictory eligibility fields as operational failures.
+   - `blocked` exits nonzero but is receive-eligible; `ok` exits zero and still requires durable receive disposition. Route by structured status and eligibility, not by exit code.
 
-4. If the command exits nonzero, use `description` to orient the next steps and handle `onFailure`:
+5. If the command exits nonzero, use `description` to orient the next steps and handle `onFailure`:
    - `block`: read gate feedback, remediate, and re-run the gate up to `maxAttempts` attempts (default `2`). If attempts are exhausted, escalate to the human with accumulated feedback and append that feedback to `implementation.md`. Treat a launch failure, missing CLI, or no eligible runtime as escalation-biased and do not spend it as a remediation attempt.
    - `prompt`: surface the gate failure and ask the human how to proceed.
    - `warn`: record the gate failure and continue.
 
-5. Runtime selection note (V1): the step runs the gate `command` as-is and reads no OAT runtime env var. By default, `oat gate review` and `oat gate cross-provider-exec` resolve the current host from built-in `hostDetectionCommand`s and avoid the same runtime when no exact target is supplied. Reusable lifecycle skill-gate commands should normally omit `--target <id>` so independent review stays provider-neutral. Use explicit targets only for manual/debug commands or deliberate local/user-specific overrides; do not hardcode provider/model targets in bundled skill guidance or shared lifecycle gate examples.
+6. Runtime selection note (V1): the step runs the gate `command` as-is and reads no OAT runtime env var. By default, `oat gate review` and `oat gate cross-provider-exec` resolve the current host from built-in `hostDetectionCommand`s and avoid the same runtime when no exact target is supplied. Reusable lifecycle skill-gate commands must not include `--target <id>` so independent review stays provider-neutral. Use explicit targets only for manual/debug commands or deliberate local/user-specific overrides; do not hardcode provider/model targets in bundled skill guidance or shared lifecycle gate examples.
 
 ### Step 7: Output Next Action
 
@@ -688,4 +750,4 @@ Report:
 - ✅ `plan.md` records the plan artifact review row unless `workflow.autoArtifactReview.plan` was explicitly disabled.
 - ✅ `implementation.md` is initialized for resumable execution.
 - ✅ Changed quick-start artifacts are committed before handoff or pause; `.oat/state.md` is refreshed locally when available.
-- ✅ Configured gate has run, and any produced review artifact has been handed off to `oat-project-review-receive` before it is treated as consumed.
+- ✅ Configured gate has run, and only a corroborated, receive-eligible artifact has been handed off to `oat-project-review-receive` before it is treated as consumed.