@open-agent-toolkit/cli 0.3.12 → 0.3.14

package/assets/docs/workflows/{projects → advanced}/dispatch-ceiling.md

@@ -15,13 +15,59 @@ constraints:
 - A **phase target** is one exact configured candidate selected at invocation
   time at or below the named maximum. Optional nested work resolves separately.
 
+**In short:**
+
+- **What this page is for:** choosing the _dispatch policy_, the highest model
+  tier (Economy, Balanced, High, or Frontier) that OAT may use when it starts
+  agents to implement and review each phase, or no cap, or leaving model choice
+  to the provider; and deciding where the list of candidate models (the
+  _ladder_) is stored.
+- **Who needs it:** anyone starting a quick, spec-driven, lite, or imported
+  project, because planning asks you to choose a policy; and team leads who
+  manage model cost.
+- **Know first:** there is no default policy, and a policy set in any config
+  file overrides the one each project chose. A tier is a cap: phase agents may
+  run below it, but per-phase and final code reviews run on the last model
+  listed in the capped tier. Codex and Claude enforce the cap; Cursor pins the model
+  but cannot confirm which one ran; other providers treat it as a suggestion.
+- **Decide:** [Which tier for which work](#which-tier-for-which-work),
+  [How each provider applies the cap](#how-each-provider-applies-the-cap), and
+  [Where the ladder lives](#where-the-ladder-lives). Most other sections are
+  the detailed resolution contract.
+
 The CLI command remains `oat project dispatch-ceiling resolve` for compatibility.
 Legacy `workflow.dispatchCeiling.*` and `oat_dispatch_ceiling` values remain
 readable, but new projects use ordered candidates plus `oat_dispatch_policy`.
 
-For raw config keys, see [Configuration](../../cli-utilities/configuration.md).
+For raw config keys, see [Configuration](../../reference/configuration.md).
 For the root-owned phase-agent loop, see
-[Implementation Execution](implementation-execution.md).
+[Implementation Execution](../projects/execution/implementation-execution.md).
+
+To pick a tier for a project, start with
+[Which tier for which work](#which-tier-for-which-work) and the rest of
+[Choosing policy and ladder ownership](#choosing-policy-and-ladder-ownership)
+near the end of this page.
+
+## How each provider applies the cap
+
+The cap is the named ceiling: the highest tier a project or phase may use. A
+provider is the agent tool running OAT. How firmly the cap holds depends on
+the provider:
+
+- **Codex: enforced.** OAT launches each phase on an agent role that
+  `oat sync` generated, pinned to one model and effort.
+- **Claude: enforced.** OAT launches a generated role pinned to one model and
+  effort, or passes the exact model on each call.
+- **Cursor: pinned, not verified.** OAT launches a generated role pinned to
+  the mapped model, but Cursor can substitute a different model without an
+  error, for example when your plan or account cannot use the pinned one or
+  the pin has a typo. OAT records the model it requested, not the model that
+  ran.
+- **Other providers: advisory.** OAT has no way to pin a model there, so the
+  cap is only a suggestion.
+
+The full rules are in [Provider Enforcement](#provider-enforcement) and
+[Cursor evidence authority](#cursor-evidence-authority).
 
 ## Named Policy Choices
 
@@ -36,8 +82,11 @@ For the root-owned phase-agent loop, see
 
 A named `High` ceiling therefore keeps configured Economy, Balanced, and High
 candidates eligible and available. It does not pin Sol, `opus`, one Cursor
-string, or one effort value. The project root chooses one exact candidate it
-judges sufficient for the phase.
+string, or one effort value. (Model names on this page, such as Sol, Luna,
+Astra, Opus, Sonnet, and Fable, are provider models listed in the ladder that
+ships with OAT; they are examples, and your own ladder may list different
+models.) The project root, meaning the main agent session running the project,
+chooses one exact candidate it judges sufficient for the phase.
 
 `Uncapped` is explicit managed state. It is not represented by omitted policy
 state. `Unresolved` is a planning or preflight deferral and cannot begin
@@ -45,6 +94,18 @@ implementation.
 
 ## Ownership and Adoption
 
+**Who chose the bundled ladder.** OAT ships a recommended ladder, the bundled
+recommendation. OAT's maintainers choose which models go in each tier and in
+what order, using provider documentation, vendor benchmarks and their own
+model-selection guidance, and they refresh it as providers release new models
+(see [Updating Model Guidance](../../contributing/updating-model-guidance.md)).
+OAT has not compared these models on its own workloads, so treat the ladder as
+the maintainers' recommended starting point, not a measured ranking. Your team
+does not have to use it as shipped. You can adopt it and then edit any cell in
+the config file that owns it (see [Config Shapes](#config-shapes)), or write
+your own cells without adopting. Rerunning adoption later replaces edited cells
+unless you pass `--keep-existing`.
+
 Adopt the complete bundled recommendation into one explicit owning scope:
 
 ```bash
@@ -58,6 +119,10 @@ oat config adopt dispatch-matrix --local
 oat config adopt dispatch-matrix --user
 ```
 
+With no scope flag, `oat config adopt dispatch-matrix` writes repo-local config
+(`.oat/config.local.json`), the same as `--local`. The examples on this page
+pass a flag so the owning scope is always explicit.
+
 Adoption replaces populated cells from the bundled recommendation in the
 chosen scope, fills missing cells, and retains extra custom tiers when the
 bundled provider remains a tier map. A bundled provider-level scalar replaces
@@ -87,9 +152,10 @@ Run the same command without `--dry-run` to replace bundled cells. Use
 
 Version `2026-10-01.1` is the current bundled recommendation. It prefers
 GPT-6 Luna and GPT-6.1 Sol in Codex, then Sol 6.1 xhigh, Astra high, and Astra xhigh in
-Codex Frontier. Astra's task advantage has not been measured locally; this is
-an explicit user-directed preference, not acceptance by the separately
-maintained model-selection policy. Sonnet 5.5 medium replaces Sonnet 5 medium
+Codex Frontier. OAT's maintainers added the Astra entries as a preference:
+public benchmarks show task-dependent gains for Astra over GPT-6 Sol, but OAT
+has not tested Astra on its own workloads, and the maintainers' separate
+model-selection review has not yet confirmed the choice. Sonnet 5.5 medium replaces Sonnet 5 medium
 in Claude Economy; the older generation stays supported for explicit cells.
 Opus 5.5 low/medium/high remains in Claude High.
 The Claude low option suits bounded intelligent recon in Balanced or High;
@@ -100,9 +166,9 @@ Opus 5.5 low above Terra high, High orders Sol medium, Opus low, Sol high,
 Opus medium, then Opus high, and Frontier places Opus high and xhigh between
 Sol max and Fable 5.1. Grok 4.6 medium replaces Grok 4.5 high at the bottom of
 Balanced, and Fable 5.1 thinking high replaces Fable 5 as Frontier's terminal
-target. The ordering is an explicit user-directed preference informed by
-vendor benchmarks and the model-selection matrix, not a local workload
-comparison. Grok 4.5 and Fable 5 stay supported for explicit configurations.
+target. OAT's maintainers chose this ordering using vendor benchmarks and their
+model-selection guidance; it is not the result of comparing models on OAT's own
+workloads. Grok 4.5 and Fable 5 stay supported for explicit configurations.
 Rerunning adoption replaces the bundled cells in the chosen scope; use
 `--keep-existing` to preserve explicit older cells. For the complete
 maintenance procedure, see
@@ -455,9 +521,8 @@ defaults to `xhigh`. A typo in a pinned selector therefore ships a
 working-but-wrong model that silently tracks a vendor-controlled default, so
 capability can change with no corresponding change in the repository.
 
-OAT does not currently validate effort rungs at sync time; that is tracked as
-`BL-260726-validate-cursor-pin-effort`. Until it lands, the probe runbook is
-the only guard.
+OAT does not currently validate effort rungs at sync time; that check is
+planned but not yet built. Until it is, the probe runbook is the only guard.
 
 ## Phase and Optional-Worker Layers
 
@@ -476,7 +541,7 @@ tasks and do not own phase commits or review dispatch.
 Tasks run serially in the same worktree. Parallelism remains limited to
 plan-declared phase worktrees unless optional work has explicitly isolated
 write authority. See
-[Implementation Execution](implementation-execution.md) for the full loop.
+[Implementation Execution](../projects/execution/implementation-execution.md) for the full loop.
 
 ## Dispatch Report V1 and Producer Provenance
 
@@ -585,7 +650,87 @@ The following remain readable during migration:
 - project `oat_dispatch_ceiling`
 - `--preferred` resolver selection
 
-Legacy preset names map to managed named tiers: `cost-conscious` to Economy,
-`balanced` to Balanced, and `maximum` to High. Legacy values are migration
-inputs, not evidence that a new project should persist exact provider-family
-pins.
+Legacy presets (`cost-conscious`, `balanced`, `maximum`) compile to bare legacy
+provider ceilings, not complete named candidate tiers. Their values can resemble
+tier caps without supplying a ladder. They remain migration inputs, not evidence
+that a new project should persist exact provider-family pins.
+
+## Choosing policy and ladder ownership
+
+The dispatch policy decides how strong (and how expensive) the models that OAT
+starts for each phase and review may be. A **ladder** is the configured list of
+model and effort candidates for each provider, grouped into four tiers from
+Economy to Frontier. The policy sets the highest tier a project may use.
+Planning asks you for the policy and saves it in the project's `state.md`.
+
+> [!WARNING]
+> A dispatch policy set in any config file (`workflow.dispatchPolicy.*`, or a
+> legacy plain value in `workflow.dispatchCeiling.providers.<provider>`)
+> overrides the policy every project chose for itself in `state.md`. To let each
+> project choose its own policy, leave those keys unset. Adopting a ladder is a
+> separate step from setting a policy.
+
+| Policy             | Choose it when                                         | What you give up                                                           |
+| ------------------ | ------------------------------------------------------ | -------------------------------------------------------------------------- |
+| Economy / Balanced | Routine or normal work where cost matters              | The higher tiers                                                           |
+| High / Frontier    | Broad, security-sensitive, or consequential changes    | Cost: implementation code reviews run on the cap tier, which can cost more |
+| Uncapped           | You trust the main session to choose a model per phase | Any tier ceiling on cost. You must choose it explicitly                    |
+| Inherit            | The provider's own model settings must stay untouched  | All OAT model control: OAT passes no model or effort setting               |
+
+There is no default policy, and a missing policy never means Uncapped. If a
+project has none when implementation starts, an interactive run asks you and a
+non-interactive run stops. The agents that implement a phase may use a lower
+tier than the cap, but when a cap is set, the per-phase and final code reviews
+always use the last candidate listed in the cap tier. Planning-artifact reviews
+and gates choose their reviewers separately.
+
+- If you are trying OAT for the first time, choose Balanced for the project.
+- If cost matters most, choose Economy for routine work or Balanced for normal
+  work.
+- If the change is high-risk, choose High. Choose Frontier only if you want
+  every implementation code review to run on Frontier's last candidate. For a
+  reviewer from a different model family, add a
+  [gate](workflow-gates.md#choosing-gate-posture) instead.
+- If the provider's own settings must stay untouched, choose Inherit.
+
+### Which tier for which work
+
+The tier is a cap, not a target: for each phase the main session still picks
+one candidate at or below it. A Dispatch Profile row is an optional per-phase
+limit in `plan.md` that can lower the cap for one phase.
+
+| Work                                                                                              | Tier to start with                                                                                     | What the tier limits                                                                                                                                                                                          | Cost and speed direction                                      |
+| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| Routine, bounded work: one component and a clear outcome, such as a bug fix                       | Balanced, or Economy if cost matters most                                                              | Phase agents use only Economy and Balanced candidates. Per-phase and final code reviews run on the last Balanced candidate                                                                                    | Lower cost; usually faster                                    |
+| Ambiguous or cross-cutting work: a broad change across several components                         | High                                                                                                   | Economy through High candidates are eligible. Code reviews run on the last High candidate                                                                                                                     | Higher, because every implementation code review runs at High |
+| Consequential or high-risk change: security-sensitive, or a missed defect costs more than the run | High. Choose Frontier only if every implementation code review should run on Frontier's last candidate | At Frontier all four tiers are eligible, and its last candidate may need model access your account lacks. For a reviewer from a different model family, add a [gate](workflow-gates.md#choosing-gate-posture) | Higher at High; highest and usually slowest at Frontier       |
+| Cost-sensitive team                                                                               | Economy for routine work and Balanced for normal work, set per project                                 | Economy allows only Economy candidates. A Dispatch Profile row can lower one phase, but code reviews still run at the project cap                                                                             | Lowest of the managed tiers                                   |
+
+OAT sets no prices and does not measure cost or speed. What a run costs depends
+on your provider plan and on the models in your ladder. The directions above
+assume a ladder ordered like the bundled one, where higher tiers hold larger
+models or higher effort settings, which usually cost more per run and take
+longer.
+
+### Where the ladder lives
+
+`oat config adopt dispatch-matrix` writes the bundled ladder to the config scope
+you choose, and to repo-local config if you pass no flag. Without
+`--keep-existing` it replaces cells you already set, so preview with `--dry-run`
+first.
+
+- If you are rolling OAT out to a team, adopt the ladder with `--shared` so
+  everyone uses the same candidates and the change is reviewed in Git.
+- If you are trying OAT alone, run `oat config adopt dispatch-matrix --user
+--dry-run`, then rerun it without `--dry-run`. A shared or repo-local ladder
+  in a repository still overrides your user ladder there.
+- If you are testing candidates in one checkout, use `--local`. After
+  `oat sync`, the agent roles generated from it still appear in the tracked
+  `.codex`, `.claude`, and `.cursor` folders, so check `git status` before
+  committing.
+
+How firmly the cap holds depends on the provider. Codex and Claude enforce the
+model and effort that OAT selects. Cursor pins mapped candidates, but OAT
+cannot confirm at run time which model actually ran, so it records what it
+requested. Other providers treat the cap as a suggestion only. See
+[Provider Enforcement](#provider-enforcement).

package/assets/docs/workflows/{projects → advanced}/evidence-layers.md

@@ -235,7 +235,7 @@ For how to run this end to end and when to refresh the fixture, see
   producer-provenance record that back Layers 1 and 2.
 - [Orchestration Model](orchestration-model.md) — the dispatch topology that
   produces these records.
-- [Review Flavors](review-flavors.md) — how the four review flavors are recorded
+- [Review Flavors](../projects/reviews/review-flavors.md) — how the four review flavors are recorded
   through the same launcher-owned evidence.
 - [Smoke testing](../../contributing/smoke-testing.md) — operating the evidence
   pipeline against real providers.

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

@@ -0,0 +1,19 @@
+---
+title: Advanced
+description: 'Dispatch, autonomy, execution surfaces, evidence layers and workflow gates.'
+---
+
+# Advanced
+
+Use these guides for advanced workflow execution and its safety boundaries.
+
+## Contents
+
+- [Worktree bootstrap](worktree-bootstrap.md) - Prepare an isolated checkout with repository-specific readiness checks.
+- [Workflow Gates](workflow-gates.md) - Completion-safe headless reviews, budgets, liveness evidence, and cross-runtime dispatch with `oat gate`.
+- [Autonomous Project Execution](autonomy.md) - Session-scoped autonomy signals, gate boundaries, review requirements, and execution learnings.
+- [OAT in Cursor Cloud](cursor-cloud.md) - Project-home, provisioning, asset-precedence, and execution-surface guidance for cloud agents.
+- [Dispatch Policy](dispatch-ceiling.md) - Managed capped tiers, managed Uncapped, Inherit Host Defaults, and provider-specific enforcement.
+- [Orchestration Model](orchestration-model.md) - The layered dispatch model: roles, selection flow, and per-harness topology.
+- [Evidence Layers](evidence-layers.md) - The three-layer dispatch evidence model behind records and smoke verification.
+- [Programmatic Execution](programmatic-execution.md) - Per-harness headless/CLI execution surfaces and where OAT uses them.

package/assets/docs/workflows/advanced/meta.json

@@ -0,0 +1,13 @@
+{
+  "title": "Advanced",
+  "pages": [
+    "worktree-bootstrap",
+    "workflow-gates",
+    "autonomy",
+    "cursor-cloud",
+    "dispatch-ceiling",
+    "orchestration-model",
+    "evidence-layers",
+    "programmatic-execution"
+  ]
+}

package/assets/docs/workflows/{projects → advanced}/orchestration-model.md

@@ -15,6 +15,18 @@ OAT separates lifecycle ownership from implementation ownership:
 This topology keeps model control at the meaningful phase boundary without
 making every task pay another dispatch and context-loading round.
 
+Terms used on this page:
+
+- **Phase:** one numbered section of a project's `plan.md` (for example `p02`)
+  that groups related tasks.
+- **Dispatch:** launching a worker or reviewer subagent on a chosen model and
+  route. The **dispatch policy** is the project's rule for which models those
+  subagents may use; see [Dispatch Policy](dispatch-ceiling.md).
+- **Worktree:** a separate Git checkout of the same repository on its own
+  branch, used so parallel phases do not overwrite each other's files.
+- **HiLL checkpoint:** a human-in-the-loop stop after a phase where an
+  interactive run waits for your approval.
+
 ## Default Topology
 
 ```mermaid
@@ -103,7 +115,7 @@ The root verifies the report against Git rather than trusting child prose:
 - clean worktree; and
 - optional child records, if any.
 
-See [Implementation Execution](implementation-execution.md) for the executable
+See [Implementation Execution](../projects/execution/implementation-execution.md) for the executable
 contract.
 
 ## Independent Phase Review
@@ -172,7 +184,7 @@ terminated at its background-wait ceiling (600 seconds by default). Interactive
 Claude Code is unaffected. Headless gate children therefore do not follow the
 ordinary background preference; they use the gate's inline or synchronously
 awaited route and fail closed when neither is available. See
-[Workflow Gates](../../cli-utilities/workflow-gates.md#headless-completion-safety).
+[Workflow Gates](workflow-gates.md#headless-completion-safety).
 
 ## Catalogs and Exact Selection
 
@@ -229,9 +241,56 @@ optional child has explicitly isolated write authority.
 
 ## Related
 
-- [Implementation Execution](implementation-execution.md)
+- [Implementation Execution](../projects/execution/implementation-execution.md)
 - [Dispatch Policy](dispatch-ceiling.md)
-- [Review Flavors](review-flavors.md)
+- [Review Flavors](../projects/reviews/review-flavors.md)
 - [Programmatic Execution](programmatic-execution.md)
 - [Evidence Layers](evidence-layers.md)
 - [Workflow Smoke Testing](../../contributing/smoke-testing.md)
+
+## subagent-orchestration
+
+Use this skill to decide what to delegate and which capability class the task
+needs. It supplies model-selection guidance, not a command that launches workers.
+OAT's dispatch skills own capability checks, exact routes, acceptance records,
+and recovery.
+
+**Invocation:** Give the agent a bounded delegation decision. The slash form is
+a skill request, not a terminal command. Providers with `$` syntax use
+`$subagent-orchestration`.
+
+```text
+/subagent-orchestration
+Classify a read-only API-usage audit and a final approval-provenance review. Define their scopes, required evidence, and escalation conditions before selecting models.
+```
+
+**Prerequisites:** Needs an active OAT project: no. The guidance is
+self-contained and needs no OAT project or installation. You need the task's
+objective, authority, verification needs, and active provider context. Read
+exactly that provider's selection reference. Current catalogs and instructions
+outrank dated model examples.
+
+**What it does without asking:** nothing outside the conversation. The skill
+is guidance only: it writes no files, makes no commits, and launches no
+subagents. Any launch happens later, through the dispatch skills, under their
+own checks.
+
+**Example scenario:** A root agent needs an unfamiliar API audit and an
+independent review of approval handling. The audit needs intelligent
+reconnaissance because a missed usage could be silent. Approval provenance
+needs consequential review because a subtle miss could authorize unsafe work.
+The root keeps authorization and cross-scope judgment while defining each
+worker's output and evidence. Choosing a stronger model does not repair an
+over-broad assignment.
+
+**Expected output:** A routing decision states the task class, role, exact model
+selector, provider-native effort, service tier, route, and authority separately.
+It preserves each class's capability floor and names escalation conditions.
+Load-bearing worker claims require verified evidence before the root acts on
+them. File count or duration alone does not justify a higher reasoning class.
+
+**Next step:** Use the appropriate dispatch machinery only after the bounded
+scope and route are justified. Within OAT, follow the project adapter
+(`oat-project-dispatch-subagents`) and the dispatch engine
+(`oat-dispatch-subagents`). Guidance alone is not evidence that a worker launched or that
+its result passed review.

package/assets/docs/workflows/{projects → advanced}/programmatic-execution.md

@@ -77,14 +77,14 @@ independent of the harness's native subagent catalog — the point of a gate is
 route the producing context could not have selected for itself. The
 lifecycle/final gate is the one flavor that may spawn a **nested managed
 reviewer child inside the gate exec target**; see
-[Review Flavors](review-flavors.md) for which flavor fires when and how
+[Review Flavors](../projects/reviews/review-flavors.md) for which flavor fires when and how
 independent each must be.
 
 Gates **fail closed**. If no different-family target is available, OAT records
 the degraded achieved level rather than pretending diversity was achieved, and
 an unavailable required-independent target blocks the gate instead of quietly
 downgrading to a same-context self-review. Only summarize the execution-surface
-angle here — see [Workflow Gates](../../cli-utilities/workflow-gates.md) for the
+angle here — see [Workflow Gates](workflow-gates.md) for the
 gate envelope, exec-target configuration, receive-eligibility, and completion
 contract. The cross-runtime `gates.execTargets` design (host-avoidance and
 independence from native catalogs) is the smoke fixture's cross-runtime gate
@@ -126,13 +126,13 @@ require either capability.
 
 - [Orchestration Model](orchestration-model.md) — route tiers, native-first
   selection, and per-harness topology.
-- [Review Flavors](review-flavors.md) — the four review flavors and which one
+- [Review Flavors](../projects/reviews/review-flavors.md) — the four review flavors and which one
   may spawn a nested managed reviewer inside a gate.
 - [Evidence Layers](evidence-layers.md) — the three-layer dispatch evidence
   model these launches feed.
 - [Dispatch Policy](dispatch-ceiling.md) — candidate ladders, named ceilings,
   and the dispatch report.
-- [Workflow Gates](../../cli-utilities/workflow-gates.md) — gate envelope,
+- [Workflow Gates](workflow-gates.md) — gate envelope,
   exec-target configuration, and completion contract.
 - [Smoke Testing](../../contributing/smoke-testing.md) — per-harness drive
   protocols and live evidence.

package/assets/docs/{cli-utilities → workflows/advanced}/workflow-gates.md

@@ -11,17 +11,52 @@ the work, then `oat gate review` dispatches a normal OAT review to another
 runtime such as Codex or Claude and maps blocking review findings to the gate
 exit status.
 
+**In short:**
+
+- **What this page is for:** setting up a _gate_, an extra review (or other
+  command) that a lifecycle skill runs as its last step, usually by a second
+  agent CLI such as Codex, Claude Code, or Cursor. No gate is configured by
+  default.
+- **Who needs it:** a team lead setting a review policy, or anyone who wants a
+  second model to check plans or code. If you have only one agent CLI
+  installed, you can skip gates.
+- **Know first:** every gate needs an explicit `--on-failure` (`block`,
+  `prompt`, or `warn`). The reviewer prefers a different model family but falls
+  back to the best available reviewer with only a warning, so check
+  `diversity.achieved` in the gate result. A shared gate guides agents; a
+  teammate can still turn it off on their own machine.
+- **Decide:** [Choosing gate posture](#choosing-gate-posture),
+  [When the gate finds blocking problems](#when-the-gate-finds-blocking-problems),
+  and [How independent the reviewer must be](#how-independent-the-reviewer-must-be).
+  The sections between here and there are the detailed contract.
+
+The shortest way to add an independent review to the implement step, shared
+with your team through the committed `.oat/config.json`, is the same command as
+in
+[Approvals and Automation](../approvals-and-automation.md#a-person-approves-the-plan-and-the-final-result-and-an-independent-model-reviews-the-code):
+
+```bash
+oat gate set oat-project-implement \
+  --command 'oat --json gate review --project "$PROJECT_PATH" --review-type code --review-scope final "Use oat-project-review-provide code final for the declared project"' \
+  --on-failure block \
+  --layer shared
+```
+
+Type it exactly as shown; `$PROJECT_PATH` stays literal, because the skill sets
+it when the gate runs. Commit `.oat/config.json` afterwards.
+
 `oat gate cross-provider-exec` remains the generic child-status executor. It
 selects an exec target, runs the prompt, and exits with the child process
 status. Use `oat gate review` when the command is specifically an OAT review
 gate that should inspect the produced review artifact.
 
-:::note Release note: default avoidance changed
-Gate dispatch now defaults to `--avoid same-family`, not `same-runtime`.
-For multi-family providers such as Cursor, this prevents a gate from reviewing
-with the same model family that produced the work. Use `--avoid none` only when
-you intentionally allow same-family review.
-:::
+> [!NOTE]
+> **Release note: default avoidance changed.**
+> Gate dispatch now defaults to `--avoid same-family`, not `same-runtime`.
+> For multi-family providers such as Cursor, this prefers a different model
+> family, but falls back to the best available target with a recorded warning
+> when diversity is unavailable. Inspect `diversity.achieved`; use `--avoid none` only when
+> you intentionally allow same-family review.
 
 ## Gate config
 
@@ -205,7 +240,7 @@ generation stale again, and a malformed waiver fails closed. An interactive
 implement run offers the waiver before it persists `stale`; an operator can
 also give it when resuming implementation after `oat-project-next` reports
 stale state. See
-[Implementation Execution](../workflows/projects/implementation-execution.md).
+[Implementation Execution](../projects/execution/implementation-execution.md).
 
 Only an artifact with `oat_review_invocation: gate` and the matching
 `oat_gate_run_id` can satisfy configured-gate provenance. A normal final
@@ -405,7 +440,7 @@ status.
 `oat-project-implement` uses `oat gate review` per phase when a project opts in
 via the `oat_phase_review_gate` plan frontmatter — a non-pausing gate that runs
 after each selected phase's standard reviewer passes. See
-[Reviews → Phase review gate](../workflows/projects/reviews.md#phase-review-gate)
+[Reviews → Phase review gate](../projects/reviews/index.md#phase-review-gate)
 for the frontmatter contract and how passing versus blocking gates are
 dispositioned.
 
@@ -1058,3 +1093,122 @@ starts and then fails, OAT does not try another target after dispatch. If no
 different-family target is available, OAT warns, records the degraded achieved
 level, and runs the best available target rather than pretending diversity was
 achieved.
+
+## Choosing gate posture
+
+A gate is an extra review that a lifecycle skill runs as its last step: the
+skill hands the work to a second agent CLI (the reviewer) and turns its findings
+into a pass or a fail. No gate is configured by default. A gate on a planning
+skill reviews the plan before any code is written; a gate on
+`oat-project-implement` reviews the finished code before closeout. Either one
+needs a working reviewer CLI on the machine and adds time to every run.
+
+`oat gate set` writes to your user config unless you pass `--layer`. A gate set
+with `--layer shared` is committed with the repository and wins over a
+user-level gate for the same skill. It does not bind every machine: a
+repo-local setting, stored in the gitignored `.oat/config.local.json`,
+overrides the shared gate on that machine (for example
+`oat gate set <skill> --disable --layer local`), and a project can disable a
+configured gate in its own `state.md` (see
+[Per-project gate overrides](#per-project-gate-overrides)). See
+[Can a teammate weaken a team rule?](../approvals-and-automation.md#can-a-teammate-weaken-a-team-rule).
+
+- If you are a solo developer and want speed, or you have only one agent CLI
+  installed, skip gates.
+- If you want a second model to check every plan before coding, gate the
+  planning skills.
+- If your team is rolling out a review policy, set the gate with
+  `--layer shared` and commit it.
+
+### When the gate finds blocking problems
+
+| `onFailure` | Choose it when                   | What you give up                                                                                               |
+| ----------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `block`     | Findings must be fixed           | Time: the agent fixes and reruns, then hands over to a person and leaves the skill incomplete if still failing |
+| `prompt`    | A person should decide each case | Unattended runs: with no answer, the gate stays blocked                                                        |
+| `warn`      | The review is advisory only      | Enforcement: the failure is recorded and the skill continues                                                   |
+
+Every gate needs an explicit `onFailure`; there is no default.
+`maxAttempts` defaults to two runs in total: the first run plus one
+fix-and-rerun. A reviewer that fails to start, times out without producing a
+review, or produces an invalid result has not reviewed anything, so treat that
+as a failed gate, never as a pass.
+
+How the skills handle that case differs:
+
+- `oat-project-implement` and `oat-project-lite` keep it blocked whatever
+  `onFailure` says, so even a `warn` gate does not let them continue.
+- `oat-project-plan`, `oat-project-quick-start`, and `oat-project-import-plan`
+  apply your `onFailure` setting to any failed gate run, including one where no
+  review happened. With `block`, they retry and then hand the problem to you,
+  as for findings. With `prompt`, they ask you. With `warn`, they record the
+  failure and finish planning, so the plan can be marked ready although no
+  reviewer looked at it.
+
+So if you put a `warn` gate on a planning skill, check the outcome before you
+run `/oat-project-implement`. The gate's JSON result has a `status` field, and
+each `oat gate review` run that starts a reviewer also adds a line to the
+project's `project-log.md` ending in `status=…` and `run=…` (it skips this only when `workflow.projectLog` is `false` and the
+project has no `project-log.md` yet): `status=ok` means the review ran and passed; `status=review_failed`,
+`artifact_validation_failed`, or `targeting_correlation_failed` means no usable
+review was produced. If you need a planning gate that cannot be skipped this
+way, use `block`.
+
+- If the work is high-risk (production, security, or data-migration code),
+  choose `block`.
+- If a maintainer is available and should decide whether to accept findings,
+  choose `prompt`.
+- If the gate runs in CI or a script, choose `block` to enforce it or `warn` to
+  keep it advisory. Never choose `prompt`, because nobody can answer it.
+
+### How independent the reviewer must be
+
+The `--avoid` option in the gate command controls which reviewers are excluded.
+A model family is the maker or line of model, such as Claude versus GPT; a
+runtime is the agent CLI, such as Claude Code, Codex, or Cursor.
+
+> [!WARNING]
+> The default, `same-family`, falls back to the best available reviewer when no
+> reviewer from a different model family is available, and only records a
+> warning in the result. That fallback can pick the same agent CLI that did
+> the work. Before relying on a gate for an independent review, check
+> `diversity.achieved` in the gate result: `different-family` means the
+> reviewer really was from another family. A reviewer that cannot start, or a
+> review that cannot be validated, is different: that blocks the gate. See
+> [Independence: what blocks and what falls back](../projects/reviews/review-flavors.md#independence-what-blocks-and-what-falls-back).
+
+| `--avoid`               | Choose it when                                     | What you give up                                                                                                                        |
+| ----------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `same-family` (default) | You want a different model family when one exists  | A guarantee, because of the fallback above                                                                                              |
+| `same-runtime`          | You need the reviewer to use a different agent CLI | Runs on machines with only one CLI. On a host OAT does not recognize, such as CI, it excludes nothing. It never checks the model family |
+| `none`                  | You knowingly accept a review from the same family | Independence                                                                                                                            |
+
+- For most teams, including mixed Claude Code, Cursor, and Codex teams, keep
+  `same-family`.
+- For a high-risk change, keep `same-family` and check `diversity.achieved` in
+  every gate result. For a hard guarantee in a manual run, pin a known
+  independent reviewer with `--target`. Stored lifecycle gate commands refuse
+  `--target`.
+- Choose `none` only when you deliberately want a same-family review, and do not
+  present it as independent evidence.
+
+### Reviewer setup and time budget
+
+An exec target is a saved command that starts a reviewer CLI, such as
+`claude -p`. The built-in targets deliberately leave out the provider flags that
+skip tool-approval prompts, so an unattended reviewer can stall on such a
+prompt. On a trusted machine that runs gates unattended, add your own target
+with the permissions it needs, for example with `--layer user`.
+
+A code review of a whole phase, a phase range, or the final result may run for
+30 minutes by default; other reviews get 15 minutes. OAT uses the first timeout
+it finds: the command's `--timeout-ms`, then the target's `timeoutMs`, then
+`workflow.gateTimeouts`, then the `OAT_GATE_EXEC_TIMEOUT_MS` environment
+variable, then the built-in default.
+
+- If one reviewer keeps timing out on large final reviews, raise that target's
+  `timeoutMs` rather than slowing every review.
+
+A timeout that leaves no valid review artifact is a failed review, never a pass.
+If the reviewer did write a valid artifact after the timeout, OAT uses it and
+reports it as a late completion.