@open-agent-toolkit/cli 0.3.13 → 0.3.15

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.

package/assets/docs/workflows/advanced/worktree-bootstrap.md

@@ -0,0 +1,83 @@
+---
+title: Worktree bootstrap
+description: 'Create or validate an isolated Git worktree and run the repository-specific readiness checks before implementation.'
+---
+
+# Worktree bootstrap
+
+Use a separate worktree when a task needs its own branch and checkout. Bootstrap
+prepares that checkout. It does not approve a plan, implement code, or prove that
+another worktree's tests pass here.
+
+Examples beginning with `/` invoke an agent skill. Providers that use `$` skill
+syntax use `$oat-worktree-bootstrap` instead. These are not terminal commands.
+For host-managed worktrees, follow the host's conventions and validate the
+existing checkout rather than creating a duplicate to normalize its path.
+
+Terms used on this page:
+
+- **Worktree:** a separate Git checkout of the same repository, with its own
+  folder and branch, created with `git worktree add`.
+- **Active project:** the OAT project your checkout currently points to,
+  stored as `activeProject` in `.oat/config.local.json`.
+- **Synced project:** a project whose artifacts live on a separate Git ref
+  instead of on your feature branch; `oat project pull` brings them into a
+  checkout.
+
+## oat-worktree-bootstrap
+
+**Invocation:** Name the branch for a new worktree and optionally choose its base.
+Without `--base`, a new branch starts from `origin/main`. `--path` overrides the
+worktree root, not the final branch-specific directory. The skill runs only
+when you invoke it by name.
+
+```text
+/oat-worktree-bootstrap export-filter --base origin/main
+```
+
+To prepare the current already-registered worktree instead:
+
+```text
+/oat-worktree-bootstrap --existing
+```
+
+**Prerequisites:** Needs an active OAT project: no, but the skill uses one if
+it is set. You need a Git repository, its required toolchain, and OAT files in
+`.oat/` and `.agents/`. Creation requires a branch name and a repository clean
+enough for the operation. If the active-project pointer exists but is invalid,
+the skill asks you to clear or open the intended project rather than rewrite
+it.
+
+**What it does without asking:** the skill creates the worktree with
+`git worktree add`, which also creates the branch when it does not exist yet.
+It copies `.oat/config.local.json` into the new worktree when the worktree has
+none, copies configured local-only paths with `oat local sync`, and pulls an
+active synced project with `oat project pull`. It then runs the repository's
+setup command (for example, dependency installation) and its readiness and
+baseline checks, stating each selected command before running it. Apart from
+the invalid-pointer question above, it asks before continuing only when the
+baseline check fails;
+if you choose to proceed anyway and an active project has `implementation.md`,
+it appends a timestamped baseline-failure note there.
+
+**Example scenario:** You need to implement an export filter without mixing its
+changes into a reporting branch. Bootstrap creates the feature worktree at the
+chosen base, carries safe local context, and runs that repository's setup and
+baseline checks. If Orca or another host already created the checkout, choose
+`--existing` to validate and initialize that same worktree.
+
+**Expected output:** The reported checkout has the intended branch and path,
+bootstrap results, readiness status, and a next action. Root selection follows
+the explicit `--path`, environment, configured root, then documented directory
+precedence. Repository-local roots must be Git-ignored before creation.
+
+Local config copies only when the destination is absent. Configured local paths
+are synchronized, and active synced project context is pulled when present.
+Setup comes from repository instructions and manifests, not an assumed package
+manager. Baseline failures require a disposition. Setup failure or a dirty
+post-bootstrap worktree cannot be reported as ready.
+
+**Next step:** Review the actual readiness result, then use
+`oat-project-implement` for an approved tracked plan. Without an active project,
+choose a [project entry workflow](../projects/planning/starting-projects.md)
+before tracked implementation.

package/assets/docs/workflows/approvals-and-automation.md

@@ -0,0 +1,261 @@
+---
+title: Approvals and Automation
+description: Where a person approves in each OAT workflow mode, what runs without asking, how many agent runs a project starts, and which controls are advisory rather than enforced.
+---
+
+# Where people approve, and what runs automatically
+
+This page shows where a person approves work in each OAT workflow mode, what
+an agent does without asking, and how many agent runs a project starts. It also
+says which team settings a developer can change on their own machine, and links
+to the detail.
+
+## At a glance
+
+A HiLL (human-in-the-loop lifecycle) checkpoint is a point where the agent
+stops and waits for a person to approve before it continues.
+
+| Mode           | A person approves before code is written                                                                                                                                                   | Pauses during implementation                                                    | Reviews that run automatically                        | At the end                                                                   | Never                  |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------- | ---------------------- |
+| No project     | You direct each step yourself                                                                                                                                                              | None                                                                            | None; run `oat-review-provide` when you want a review | OAT opens no pull request                                                    | Not applicable         |
+| Lite           | Once: the requirements and the single-phase plan                                                                                                                                           | None                                                                            | Plan review, phase review, final review               | Opens a pull request by itself; no setting removes this step                 | Merges a pull request  |
+| Quick          | You confirm the requirements (or the lightweight design). No plan-approval prompt: the plan is marked ready after an automatic review                                                      | First run lists the phases and asks where to stop; suggested: after every phase | Plan review, a review after every phase, final review | Opens a pull request by itself only if `workflow.postImplementSequence` asks | Merges a pull request  |
+| Spec-driven    | Discovery, then the requirements and design. Planning asks you in chat to confirm the task breakdown, but no plan approval is recorded; the plan is marked ready after an automatic review | Same as quick                                                                   | Same as quick                                         | Same as quick                                                                | Merges a pull request  |
+| Imported plan  | No approval step; OAT normalizes your plan and reviews it automatically                                                                                                                    | Same as quick                                                                   | Same as quick                                         | Same as quick                                                                | Merges a pull request  |
+| Autonomous run | None; it answers its own questions and stops only at defined boundaries                                                                                                                    | None; it approves the final checkpoint itself after a passing final review      | All of the above, plus a review at every checkpoint   | Opens a pull request by default                                              | Merges or force-pushes |
+
+Phase reviews need no person. The final review always runs, but an interactive
+run first asks how to run it unless `workflow.reviewExecutionModel` is set. If
+the final phase is a checkpoint, you approve the finished work after the final
+review; with `workflow.postImplementSequence` set to `pr` or `docs-pr`, the pull
+request opens before that approval.
+
+**Quick, spec-driven, and imported projects have no plan-approval prompt.**
+Planning ends with an automatic plan review. That review applies Critical and
+High fixes itself and offers you the Medium and Low ones, and then the skill
+marks `plan.md` ready for implementation. The planning skill
+(`/oat-project-quick-start`, `/oat-project-plan`, or `/oat-project-import-plan`)
+then stops: it reports the phases and names `/oat-project-implement` as the
+next step, and no code is written until you run that skill (or
+`/oat-project-next`, which starts it without asking). That stop is your chance
+to review the plan, so read `plan.md` when planning finishes and before you run
+`/oat-project-implement`. Do not re-run `/oat-project-quick-start` to continue:
+on a quick project whose plan is ready, it starts implementation straight away.
+
+What does and does not give a person a say on the plan:
+
+- **Lite:** its single approval covers the requirements and the plan, and the
+  decision is written into `plan.md`.
+- **Spec-driven:** `/oat-project-plan` asks "Does this breakdown make sense? Any
+  tasks missing?" in the chat and revises until you confirm. That confirmation
+  is not recorded as an approval, and the automatic review that follows can
+  still change the plan.
+- **Quick and imported:** nothing asks you to approve or confirm the plan.
+  Planning may still ask setup questions, such as which dispatch policy to use
+  or whether to add gates.
+- **A `plan` checkpoint does not add a pause.** Listing `plan` in a project's
+  `oat_hill_checkpoints` in `state.md` does not stop the agent: the planning
+  skill marks that checkpoint complete itself when it finishes.
+- **First implementation run:** `oat-project-implement` lists every phase and
+  asks where to pause before any task runs. That is a checkpoint question, not
+  a plan approval, but it is the last point to stop before code is written. It
+  is skipped when `workflow.hillCheckpointDefault` is set and in autonomous
+  runs. See [HiLL Checkpoints](projects/planning/hill-checkpoints.md).
+- **Autonomous runs:** no person sees the plan before implementation.
+
+## How many agent runs does a project start?
+
+An agent run is one model launch for one bounded job, such as implementing or
+reviewing a phase. A _gate_ is an optional extra review that a skill runs as
+its last step, by a separate reviewer agent, usually in a different agent tool.
+No gate is configured by default.
+
+| Step                      | Runs                                                       | Limit                                                                                                                                                                  |
+| ------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Plan review               | 1, plus 1 re-review after each round of fixes              | `oat_orchestration_retry_limit` in `state.md`: 2 re-reviews by default                                                                                                 |
+| Each implementation phase | 1 implementer and 1 reviewer                               | A Critical or High finding adds a fix and a new review, at most 2 rounds by default                                                                                    |
+| Final review              | 1 reviewer                                                 | At most 3 review cycles, then the agent stops and asks you how to proceed                                                                                              |
+| Review at checkpoints     | 1 extra review at each checkpoint before the last, when on | Off unless you answer yes to the auto-review question on the first implementation run or set `workflow.autoReviewAtHillCheckpoints`; autonomous runs always turn it on |
+| Gate (optional)           | 1 reviewer run per gate                                    | `maxAttempts`, 2 runs in total by default                                                                                                                              |
+
+OAT does not estimate prices. Cost depends on your provider's pricing and on
+your _dispatch policy_: the highest model tier OAT may use for subagents.
+Implementers may run below that tier, but under a capped policy (Economy,
+Balanced, High, or Frontier), phase and final reviews use the last model listed
+for that policy's tier. See [Dispatch Policy](advanced/dispatch-ceiling.md).
+
+**Illustration, derived from the defaults:** a three-phase quick project, run
+interactively with no gates and checkpoint reviews off, where no review finds a
+Critical or High problem, uses 8 agent runs: 1 plan review, 3 implementers, 3
+phase reviewers, and 1 final reviewer. Each phase review that returns a Critical
+or High finding adds 2 runs, a fix and a new review, at most twice per phase, so
+the phases alone can reach 18. Not counted: the summary, documentation, and pull
+request steps, the project explainer and project recap, and the optional phase
+gate review (one extra reviewer run per selected phase). A blocked
+implementation gate also reruns the final review before the gate runs again.
+
+## What OAT does without asking
+
+- **Commits** once per task, plus tracking commits at each phase and review
+  boundary, on your current branch. See
+  [Execution Skills](projects/execution/execution-skills.md#oat-project-implement).
+- **Pushes project files to `origin`.** New projects default to the _synced_
+  scope: the project's files live on their own Git ref, which is pushed to
+  `origin` every time a skill saves it. To stop that, run
+  `oat config set projects.defaultScope shared`. This changes the team's
+  committed `.oat/config.json`. Project files are then committed on your branch
+  and reach `origin` only when the branch is pushed. Use the `local` scope to
+  keep them on this machine only. See
+  [Before your first project](projects/planning/starting-projects.md#before-your-first-project).
+- **Starts subagents**, an implementer and a reviewer per phase, without asking
+  each time. On Codex, when launching subagents needs authorization, it asks
+  once per run.
+- **Merges parallel phases into your branch.** When the plan declares a
+  parallel group, it runs each phase in its own worktree and merges the phases
+  that pass review into your current branch with `git merge --no-ff`.
+- **Pushes your branch and opens the pull request** without confirming. The
+  final-PR step (`oat-project-pr-final`) runs `git push -u origin <branch>` and
+  `gh pr create`: always in lite, when `workflow.postImplementSequence` includes
+  `pr`, and in autonomous runs. `oat-project-complete` opens a pull request
+  without asking when `workflow.createPrOnComplete` is `true`, and it also
+  pushes your branch after archiving a synced project, whether or not it opens
+  a pull request. Autonomous runs also push the branch, without force, after
+  each lifecycle step such as planning and implementation. See
+  [Autonomous Project Execution](advanced/autonomy.md).
+
+## Set it up the way you want
+
+### A person approves the plan and the final result, and an independent model reviews the code
+
+1. Run `/oat-project-quick-start` and confirm the requirements when asked, or
+   `/oat-project-new` to also approve discovery and design.
+2. When planning finishes, the skill stops and names `/oat-project-implement`
+   as the next step. There is no plan-approval prompt, so read `plan.md` now
+   and ask the agent for any changes before you start implementation; that
+   reading is your plan approval, and nothing records it. Do not re-run
+   `/oat-project-quick-start` to continue, because on a ready plan it starts
+   implementation straight away.
+3. At the first implementation prompt, choose "Stop only after the final
+   phase". To make that your own default, run
+   `oat config set workflow.hillCheckpointDefault final --user`. Use `--shared`
+   instead only if your team has agreed that every project pauses only at the
+   end. Either way, a configured value is used on each project's first
+   implementation run without asking and replaces any checkpoint value already
+   in `plan.md`.
+4. Keep the pull request until you approve:
+   `oat config set workflow.postImplementSequence wait --shared` (a legacy
+   value that is still supported), then run `/oat-project-pr-final` yourself.
+5. Add a review gate on implementation and commit `.oat/config.json`:
+
+   ```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
+   ```
+
+   `--on-failure` is required. With `block`, the agent fixes findings and reruns
+   the gate (2 runs in total by default), then hands over to you. The gate runs
+   after the final code review and before your approval. The built-in reviewer
+   targets run without permission-bypass flags and can stall on the reviewing
+   tool's approval prompts; read
+   [Permissions for unattended review](#permissions-for-unattended-review)
+   before relying on this unattended.
+
+> [!WARNING]
+> The default independence setting falls back to the best available reviewer,
+> which may be from the same model family, and only records a warning. Check
+> `diversity.achieved` in the gate result: `different-family` means the review
+> was independent. See
+> [Workflow Gates](advanced/workflow-gates.md#how-independent-the-reviewer-must-be).
+
+### Maximum human control
+
+1. Work on a feature branch: `git switch -c my-change`.
+2. Stop OAT from pushing project files every time it saves them.
+   `oat config set projects.defaultScope shared` makes it commit them on your
+   branch instead, but this edits the team's committed `.oat/config.json`, and
+   the files still reach `origin` whenever that branch is pushed, for example
+   when the pull request opens. To keep them on this machine only, create the
+   project with the `local` scope (next step), or run
+   `export OAT_PROJECTS_DEFAULT_SCOPE=local` in your shell.
+3. Run `/oat-project-new my-change` (spec-driven; add `--scope local` for a
+   local project) and choose the collaborative design mode, so you approve
+   discovery and each design section.
+4. At the first implementation prompt, keep "Stop after each phase". Check
+   first with `oat config get workflow.hillCheckpointDefault`: if it prints
+   `final`, the prompt will not appear and the project pauses only at the end.
+   Unset it in the layer that sets it, or set `every` for yourself with
+   `oat config set workflow.hillCheckpointDefault every --user` (a shared or
+   local value still wins over a user value).
+5. Avoid automatic pull requests: do not use lite, run
+   `oat config set workflow.postImplementSequence wait --shared` (a legacy
+   value that is still supported), and leave `workflow.createPrOnComplete`
+   unset.
+
+### Mostly unattended, within limits
+
+1. Work on a feature branch; an autonomous run pushes whichever branch is
+   checked out.
+2. Set a dispatch policy, which autonomy never chooses:
+   `oat config set workflow.dispatchPolicy.policy balanced --local`. A policy in
+   config overrides each project's own choice.
+3. Give any gate `--on-failure block` or `warn`; a failing `prompt` gate stops
+   the run.
+4. Run `/oat-project-autonomous "<your goal>"`.
+
+It still stops at a product decision, a destructive action, an unresolved
+Critical finding, a protected branch or required approval, a missing
+credential, or a question it has no rule for. It never merges; review the pull
+request yourself.
+
+## Can a teammate weaken a team rule?
+
+Yes, on their own machine. Configuration resolves local first
+(`.oat/config.local.json`), then shared (the committed `.oat/config.json`),
+then user (`~/.oat/config.json`). Shared beats user, but local beats shared,
+and `oat init` adds `.oat/config.local.json` to `.gitignore`, so the change
+never appears in a diff. A few keys, such as `projects.defaultScope`, also take
+an environment variable that beats every file.
+
+- `oat gate set oat-project-implement --disable --layer local` switches a
+  shared gate off for that checkout.
+- Interactive planning asks whether to keep or disable each configured gate
+  for the new project. A **Disable** answer, or a hand edit, writes
+  `oat_skill_gate_overrides: { oat-project-implement: disabled }` to that
+  project's `state.md`, and OAT records the gate as disabled by the project.
+- `oat config set workflow.autoArtifactReview.plan false --local` skips the
+  automatic plan review on that machine; the plan records the skip.
+- A local `workflow.hillCheckpointDefault`, or an edit to
+  `oat_plan_hill_phases` in `plan.md`, changes where a project pauses.
+
+These controls guide agents on a developer's machine; they are not an
+enforcement boundary. Enforce team rules with branch protection, required
+reviewers, and CI checks.
+
+## Permissions for unattended review
+
+An _exec target_ is a saved command that starts a reviewer tool. The built-in
+targets run `codex exec`, `claude -p`, and `cursor-agent -p`, and OAT adds only
+a model choice and the prompt, never a permission-bypass flag. An unattended
+gate can therefore be stopped by the reviewing tool's own permission checks.
+
+- An attended review needs no bypass, but it takes the place of a gate; it does
+  not satisfy one. Leave the gate unset, choose the fresh-session option at the
+  final-review prompt (or set `workflow.reviewExecutionModel` to
+  `fresh-session`), and run `oat-project-review-provide code final` yourself in
+  another session or agent tool that has the OAT skills installed. Answer its
+  prompts, then run `oat-project-review-receive` in the original session.
+- Some trusted-target examples in [Workflow Gates](advanced/workflow-gates.md)
+  add a provider's permission-bypass flag. A team may choose that for a trusted
+  machine; OAT does not require it.
+- OAT documents no narrower permission allowlist for reviewers. If you build
+  one, test it on an unattended gate before you rely on it.
+
+## Where to go next
+
+- [Choose a Workflow](choose-workflow.md) to pick a mode.
+- [Execution Skills](projects/execution/execution-skills.md) for what
+  implementation does step by step.
+- [Workflow Gates](advanced/workflow-gates.md) for gate setup and limits.
+- [Configuration](../reference/configuration.md) for every setting named here.