@open-agent-toolkit/cli 0.3.15 → 0.3.17

package/assets/docs/skills/repo-improve.md

@@ -213,9 +213,11 @@ does not require a project name or an active-project pointer.
 the `oat-codebase-mapper` subagent. A preflight checks whether background
 agents can write files and switches to a read-only fallback if they cannot.
 Needs an active OAT project: no. If a knowledge directory already exists,
-choose whether to refresh it or skip the run. Refresh first deletes every
-`.md` file in `.oat/repo/knowledge/`, hand-written files included, and then
-regenerates the set. Move any notes you want to keep before you choose it.
+choose whether to refresh it or skip the run. Refresh removes only regular
+Markdown files marked `oat_generated: true` and regenerates the eight named
+outputs. Hand-written notes survive; an unmarked expected-output collision
+stops the run before deletion so you can decide how to preserve it. Symlinked
+knowledge directories and output collisions are refused.
 
 **Example scenario:** A new teammate needs to understand which packages own
 the CLI, how shared configuration reaches applications, and which test
@@ -234,8 +236,9 @@ answered.
 knowledge files already exist. Otherwise it creates `.oat/repo/knowledge/`,
 starts a test subagent and then four `oat-codebase-mapper` subagents in the
 background, and writes the knowledge files. It then runs
-`git add .oat/repo/knowledge/` and `git commit` on your current branch with
-no further prompt; that commit also includes anything you had already staged.
+`oat internal commit-paths` on your current branch with the exact generated
+output/deletion paths and enabled hooks. Unrelated staged and unstaged work
+remains intact.
 Afterwards it records the run in `.oat/tracking.json` and regenerates the
 `.oat/state.md` dashboard with `oat state refresh`; those two files are not
 part of the commit. It does not push.
@@ -244,8 +247,7 @@ part of the commit. It does not push.
 `project-index.md`, `stack.md`, `architecture.md`, `structure.md`,
 `conventions.md`, `testing.md`, `integrations.md`, and `concerns.md`. The
 workflow also updates its tracking/dashboard surface and commits the
-knowledge output on the current branch (unstage unrelated changes first; the
-commit includes anything already staged). Despite its name, `project-index.md` describes the
+knowledge output on the current branch with exact path ownership. Despite its name, `project-index.md` describes the
 repository; it does not require a pre-existing OAT lifecycle project.
 
 **Next step:** Read the index and the concern or testing documents relevant

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

@@ -51,6 +51,46 @@ repository config, user config, or any other durable artifact. A later
 interactive session therefore needs no autonomy cleanup and behaves
 interactively around the state the autonomous run left behind.
 
+## Kickoff limits and hard stops
+
+Kickoff reads the owning recovery, gate and dispatch contracts and reports the
+effective project default and each known phase limit, source/override, prior
+durable usage, remaining capacity and pending-attempt status. For a new project,
+phase values remain unresolved until planning supplies them; the report is
+refreshed before implementation and on resume.
+
+Phase recovery uses `oat_phase_recovery_policy` in `state.md`: a
+`phase_attempt_limits.<pNN>` override wins over `default_attempt_limit`, whose
+owning default is `10`. Limits are integers from `0` through `20`. Usage comes
+from the monotonic `phase_attempt_usage.<pNN>.used_attempts` ledger; remaining
+capacity is `max(0, effective limit - used_attempts)`. A reconciled pending
+reservation finishes that same attempt without another increment, even at the
+limit.
+
+These dry kickoff controls illustrate the unchanged policy, without launching
+a provider:
+
+- Default control: limit 10, used 3, remaining 7; source is the owning default
+  when the project has no override.
+- Phase override control: limit 2, used 1, remaining 1; source is
+  `phase_attempt_limits.p01: 2`, even when the project default is 10.
+- Zero limit: no new automatic attempt; a direction-required stop consumes no
+  attempt.
+
+Capacity is not permission. A failed attempt is terminal even with remaining capacity.
+A continue-after-failure policy remains a separate future choice. Route retries,
+review-fix rounds, gate `maxAttempts`, recovery events and reserved recovery
+attempts are separate counters. An elevated warning at three recovery events
+changes no limit and grants no permission.
+
+Kickoff also names the applicable owning hard stops: recovery eligibility or
+proof failure, new-attempt budget exhaustion, malformed ledger or unresolved
+pending attempt, exact-target/accepted-launch failure, blocking review policy,
+missing credentials, repository authority, unresolved product judgment,
+unauthorized destructive risk and inventory gaps. Each stop retains its owning
+contract and configured gate semantics; the report names evidence and the
+operator action needed to resume.
+
 ## Gate outcomes
 
 Every interactive lifecycle gate has one of two autonomous outcomes:
@@ -75,6 +115,16 @@ A boundary is a successful fail-closed outcome, not permission to continue with
 a guessed answer. The run reports what stopped, the evidence, and the operator
 action needed to resume.
 
+When a review or gate budget runs out (a review-cycle cap, the orchestration
+retry limit, or a gate's `maxAttempts`), the run first dispatches the
+[complexity review](../projects/reviews/index.md#complexity-review-at-budget-exhaustion)
+and includes its decision-message content in the boundary report. The run never
+selects the disposition, including **simplify**: the operator chooses when
+resuming. A quick-start plan gate outcome is persisted as
+`oat_quick_start_gate` (see
+[Gate approval records](workflow-gates.md#gate-approval-records)); a failed
+`prompt` gate is recorded as `blocked`, never as approved.
+
 The canonical autonomy contract and exhaustive gate inventory
 (`.agents/docs/autonomy-contract.md`, vendored into each consuming skill at
 `references/docs/autonomy-contract.md`) map each prompt to its autonomous

package/assets/docs/workflows/advanced/workflow-gates.md

@@ -247,6 +247,45 @@ Only an artifact with `oat_review_invocation: gate` and the matching
 review, phase review, or manually produced independent review cannot substitute
 for it.
 
+### Gate approval records
+
+Two lifecycle gates persist their outcome in project `state.md` with a shared
+five-field core:
+
+| Field                | Meaning                                                                                        |
+| -------------------- | ---------------------------------------------------------------------------------------------- |
+| `status`             | `allowed` or `blocked`                                                                         |
+| `disposition`        | `passed`, `warned`, `prompt_approved`, or `project_disabled` when allowed; `null` when blocked |
+| `config_fingerprint` | Stable hash of the resolved gate declaration                                                   |
+| `reviewed_head`      | The commit the gate reviewed, recorded as provenance                                           |
+| `decided_at`         | ISO 8601 UTC time of the decision                                                              |
+
+`oat_implement_exit_gate` keeps its additional closeout fields and writes
+`decided_at` with every allowed or blocked outcome. `oat_quick_start_gate`,
+written by `oat-project-quick-start` for every configured plan-gate outcome,
+carries exactly the core:
+
+- a passing gate writes `allowed/passed`, and a `warn` failure writes
+  `allowed/warned`;
+- a `prompt` failure the operator explicitly continues past writes
+  `allowed/prompt_approved`;
+- a declined or deferred `prompt` (always under `OAT_AUTONOMOUS=1`), a `block`
+  still failing at `maxAttempts`, or an operational failure writes `blocked`
+  with a `null` disposition;
+- a gate disabled by project override writes `allowed/project_disabled`
+  without launching anything; and
+- a gate that is not configured writes no record (implement writes
+  `allowed/no_gate` instead).
+
+`oat-project-next` and `oat-project-progress` report the quick-start record as
+recorded: status, disposition, `decided_at`, and `config_fingerprint` as
+provenance, or `malformed` when the fields do not form a valid record. They do
+not recompute the fingerprint, because no CLI emits a canonical one for the
+quick-start gate, and they never route on the record: quick plan readiness
+remains the only routing rule for quick plans, and `reviewed_head` is not
+compared with `HEAD` because quick-start commits after the gate. A record
+written before `decided_at` existed is still valid.
+
 ## Review gates
 
 `oat gate review` is intentionally stateful. It is equivalent to running
@@ -953,6 +992,12 @@ failures, and receive failures are operational failures rather than validated
 blocking findings. They remain blocked regardless of `onFailure`; even `warn`
 cannot turn them into an allowed disposition.
 
+When `block` still fails after `maxAttempts`, the implementation exit gate and
+the quick-start plan gate run a
+[complexity review](../projects/reviews/index.md#complexity-review-at-budget-exhaustion)
+before escalating, and show it with the accumulated feedback. The operator
+chooses how to proceed, including **simplify**; agents never choose for them.
+
 `cross-provider-exec` does fallback only before dispatch, while selecting an
 available target. Once a target actually runs, its exit code is the gate result;
 OAT does not try another target after a failed review.
@@ -970,9 +1015,11 @@ the budget at the narrowest useful level. The first valid value wins:
 All configured values must be integer milliseconds from `1,000` through
 `14,400,000`. Invalid persisted values are ignored with a warning and
 resolution continues to the next source. Code reviews at `final`, phase
-(`pNN`), or phase-range (`pNN-pMM`) scope default to 1,800,000 ms (30 minutes).
-Task-scoped code reviews (`pNN-tNN`) and artifact reviews default to 900,000 ms
-(15 minutes). Startup output reports both the resolved value and source.
+(`pNN`), or phase-range (`pNN-pMM`) scope and every artifact review (for
+example `plan`, `design`, or `discovery`) default to 1,800,000 ms (30 minutes),
+because they read the full surface. Task-scoped code reviews (`pNN-tNN`)
+default to 900,000 ms (15 minutes). Startup output reports both the resolved
+value and source.
 
 Example migration from the former single environment override:
 
@@ -981,7 +1028,7 @@ Example migration from the former single environment override:
   "workflow": {
     "gateTimeouts": {
       "code": 2400000,
-      "artifact": 900000
+      "artifact": 2400000
     },
     "gates": {
       "execTargets": {
@@ -1048,10 +1095,60 @@ diagnostic because the refusal itself explains why execution stopped.
 
 Before spawn, the gate also writes a transient marker under the system temp
 directory at `oat-gate-runs/<runId>.json`; startup diagnostics print its path.
-The marker records target, runtime, project, review type/scope, start time,
-budget, and budget source. It is deleted at terminal completion. An orphaned
-marker indicates the gate parent itself stopped unexpectedly, but markers are
-diagnostic only and are never used for artifact validation.
+The marker records target, runtime, project, the resolved project directory
+(`projectRoot`), the owning gate process ID (`pid`), review type/scope, start
+time, budget, and budget source. It is deleted at terminal completion. An
+orphaned marker indicates the gate parent itself stopped unexpectedly. Markers
+are diagnostic only: they are never used for artifact validation or for
+duplicate-run detection.
+
+#### Nested and duplicate runs
+
+Before launching, `oat gate review` atomically claims its project directory,
+review type, and review scope (type and scope compare case-insensitively). The
+claim is a `claim-<hash>.lock` file in the same `oat-gate-runs/` directory,
+created through an exclusive link, so at most one live gate holds a given
+project, type, and scope at a time. That holds even when two identical gates
+start at the same moment. The claim is released when the run ends.
+
+If the claim is already held by a live process, the new run is rejected
+without launching a target, writing a marker, or appending a project-log entry.
+It exits nonzero with `status: review_failed`,
+`outcome: review_did_not_complete`, and a message naming the holding run, its
+process ID, and its claim path. This covers a reviewer that launches its own
+gate for the scope it is reviewing, a second orchestrator launch for a scope
+already under review, and simultaneous launches. Wait for the live run to
+finish; remove the named claim only when that process is not a gate. A claim
+whose owner process is dead, or whose content cannot be parsed, is replaced
+once and the run proceeds. Recovery and release serialize destructive claim
+changes with an exclusive `<claim-path>.mutation` directory. Recovery checks
+ownership again under that guard before removing a stale claim, so a
+replacement live owner remains protected even when three launches compete.
+If another mutation holds the guard, the new run refuses to start; retry after
+it finishes. An interrupted mutation can leave the guard behind. Remove that
+exact guard directory only after verifying that no gate is still using it;
+OAT does not automatically reclaim it. Liveness is a process-ID check, so a stale claim
+whose process ID was reused by an unrelated process still blocks until it is
+removed.
+
+The gate exports its run directory to the reviewer child as
+`OAT_GATE_RUN_MARKER_DIR`, and every gate prefers that variable (when it is an
+absolute path) over the system temp directory. A nested gate therefore finds
+its parent's claim even when the reviewer runtime gives tool commands a
+different `TMPDIR`. Runs in separate checkouts or worktrees resolve to
+different project directories and never block each other.
+
+The `ok`/`blocked` envelope and the `review_did_not_complete` envelope (child
+failure, timeout, refusal, or duplicate rejection) record the decision as
+`recursion`: `{ "decision": "none" }`,
+`{ "decision": "rejected", "matchedRunId": "<runId>" }`, or
+`{ "decision": "unchecked" }` when claim acquisition fails (including an
+unreadable claim or a held mutation guard). The gate warns, exits nonzero with
+`status: review_failed` and `outcome: review_did_not_complete`, and does not
+launch a reviewer, write a run marker, or append a project-log entry. Other envelopes keep
+their existing shape. JSON mode also writes a `gate-recursion` diagnostic line
+beside the `gate-run-marker` line; a rejection adds `matchedPid` and
+`claimPath`.
 
 After a review target times out, OAT re-scans the project reviews for exactly
 one artifact carrying that invocation's `oat_gate_run_id`. A recovered artifact
@@ -1085,6 +1182,7 @@ those artifacts; correct the project/run correlation and start a new gate run.
 | Passing artifact lost receive routing                                 | handoff and `receiveEligible` fixture                                                                                  |
 | Passing review reported as a failed gate after a post-selection error | post-selection recovery cases plus snapshot-replacement, non-gate-marker, and foreign-target controls                  |
 | Transient index lock turned a completed review into a failed gate     | index-lock retry cases plus persistent/transient classification, receipt fixture, and fresh-process recovery control   |
+| A second gate ran for a project and scope already under review        | claim unit cases plus running-gate, simultaneous-launch, and differing-`TMPDIR` nested fake-runtime cases              |
 
 ## Current limits
 
@@ -1200,8 +1298,9 @@ 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
+A code review of a whole phase, a phase range, or the final result, and any
+artifact review, may run for 30 minutes by default; task-scoped code 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.

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

@@ -77,6 +77,7 @@ No gate is configured 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                                                                                                                              |
+| Budget exhausted          | 1 read-only complexity review                              | Runs once when a review cycle cap, the retry limit, or a gate's `maxAttempts` runs out, before the agent asks you how to proceed                                       |
 
 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.
@@ -92,7 +93,8 @@ 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.
+implementation gate also reruns the final review before the gate runs again,
+and any budget that runs out adds one read-only complexity-review run.
 
 ## What OAT does without asking
 

package/assets/docs/workflows/backlog-and-planning/backlog-lifecycle.md

@@ -21,15 +21,6 @@ mutations write nothing and return an error naming the repository path and
 `oat pjm init` as the recovery. Check the current state with
 `oat pjm doctor --json` and read its `adoption.state` field.
 
-> [!WARNING]
-> Running `oat pjm init` again, or running `oat pjm migrate --apply`,
-> currently replaces the `pjm` section of `.oat/config.json` and deletes any
-> `pjm.remote` settings (your remote project management policy). Several
-> skills below tell you to rerun `oat pjm init` to repair a partial setup or
-> missing index markers. Before you do, back up `.oat/config.json`;
-> afterwards, check `git diff .oat/config.json` and restore `pjm.remote` if
-> it was removed.
-
 ## Where a backlog item lives
 
 - **`items/<id>.md`** - active, file-backed records. Each carries frontmatter with a `status` and an `updated` timestamp.
@@ -64,12 +55,24 @@ A single `oat backlog archive` run performs the whole close-out so its parts can
 
 1. Sets the terminal `status` (`closed` by default, `wont_do` with `--wont-do`) and stamps `updated`.
 2. Validates and trims a nonblank `--summary` before mutating a `closed` item, then appends its canonical (standard OAT format) newest-first `completed.md` entry. `wont_do` items may omit the summary and get an entry only when one is provided.
-3. Moves `items/<id>.md` into `archived/` — with `git mv` inside a work tree, or a plain rename outside git.
+3. Moves `items/<id>.md` into `archived/` with a filesystem rename, leaving Git staging to the caller.
 4. Rewrites inbound references to the moved file across Markdown under `.oat/repo/**` (tracked and untracked files that Git does not ignore; a code span whose whole content is the item's path, such as an external plan's source citation, is rewritten, while other code spans and fenced code are left as written with a warning) — external plans, decision records, and other backlog items — so no link dangles at `items/<id>.md`, and reports each rewritten file. A reference it cannot resolve is left alone with a warning.
 5. Regenerates the managed backlog index.
 
 The command is safe to re-run: an item already in `archived/` produces a no-op warning and only retries the reference rewrite and index regeneration, so an interrupted close-out finishes on the next run. A missing closed-item summary or an out-of-enum current status (for example a hand-set `done`) is a hard error before mutation and includes recovery guidance. See the [command reference](../../reference/config-and-local-state.md#oat-backlog-archive) for exit codes and the `--json` payload.
 
+The archive result includes normalized absolute `affectedPaths` for the whole
+operation. Capture `--json` for each item, union the lists, and include owned
+handoff deletions. Format existing affected text with the repository's
+formatter, then use `oat internal commit-paths` with a unique retained identity
+and the exact list. Include the old tracked item deletion and new destination
+as well as ledger/index/references; staging only the old missing path fails.
+Hooks remain enabled, and unrelated staged/unstaged work stays intact. Verify
+helper availability first, stop on failure, and follow its retry diagnostics.
+Settled noops claim only actual repairs; pending Git retries recover earlier
+operation outputs from HEAD evidence. See [exact-path maintenance
+commits](../../reference/cli-reference.md#exact-path-maintenance-commits).
+
 ## Catching lifecycle drift
 
 The manual close-out this command replaces is exactly where the two motivating repos drifted — an item was marked closed in frontmatter and summarized in `completed.md` but never moved to `archived/`, and one shipped with the invalid status `done`. `oat pjm doctor` (and therefore `oat doctor`, which aggregates the `pjm:*` checks) now surfaces that drift:
@@ -101,8 +104,7 @@ work. Like every PJM skill that writes files on this page, it refuses to
 write until the repository has adopted PJM with `oat pjm init`. The skill
 first runs `oat pjm doctor --json` and inspects `adoption.state`; only
 `declared` or `inferred-legacy` permits writes. For `none` or
-`partial-initialization` it stops and tells you to run `oat pjm init` (read
-the [warning about rerunning it](#adoption-comes-first) first). Installed
+`partial-initialization` it stops and tells you to run `oat pjm init`. Installed
 tools alone do not establish adoption. No active OAT project is required.
 
 **Example scenario:** A support incident exposed uncertainty about duplicate
@@ -145,7 +147,7 @@ the living review.
 `oat pjm doctor --json` before writes, and accessible backlog items. A
 roadmap is optional alignment evidence; an active OAT project is not
 required. The skill stops and tells you to run `oat pjm init` if adoption
-is absent or partial (see the [warning about rerunning it](#adoption-comes-first)).
+is absent or partial.
 
 **Example scenario:** Your team has time for one maintenance initiative, but
 the backlog mixes isolated fixes with work blocked on shared infrastructure.
@@ -211,8 +213,7 @@ Context, Decision, and Consequences sections and reruns
 `oat decision regenerate-index` if it changed the status or title. Its
 workflow has no commit or push step. If the decision index markers are
 missing, it stops and tells you to repair the repository with
-`oat pjm init`; that is a rerun, so read the
-[warning about rerunning it](#adoption-comes-first) first.
+`oat pjm init`.
 
 **Next step:** Review the record and link relevant work to it. If later
 evidence changes the choice, preserve history through the appropriate
@@ -249,9 +250,7 @@ sanitized description of which connector or provider CLI it can use for
 that tracker. The skill gathers that evidence for you.
 
 **Prerequisites:** PJM adoption verified by `oat pjm doctor --json` (the
-skill stops and points you to `oat pjm init` otherwise; rerunning init
-deletes `pjm.remote`, as the [warning above](#adoption-comes-first)
-explains), applicable local
+skill stops and points you to `oat pjm init` otherwise), applicable local
 policy, and an available host capability matching the provider, operation,
 and exact account, workspace, site, or repository. No active OAT project is
 required. Remote mutation authority defaults to `read-only`, so `publish`
@@ -336,12 +335,14 @@ sanity check distinguishes valid active paths from retired references.
 the curated overview, and backlog item files under `.oat/repo/pjm/` as it
 judges applicable, with no separate approval step. It runs
 `oat backlog archive` for completed items, which moves each item file into
-`archived/` (with `git mv` inside a Git work tree), and it creates decision
-records with `oat decision new`. Its workflow has no commit or push step,
-so review the working-tree diff afterwards. If the backlog index markers
-are missing, it stops and tells you to repair the repository with
-`oat pjm init`; that is a rerun, so read the
-[warning about rerunning it](#adoption-comes-first) first.
+`archived/` with a filesystem rename, and it creates decision
+records with `oat decision new`. It automatically commits the exact archive
+close-out paths and any owned kickoff handoff deletion with hooks enabled.
+Other reference edits remain uncommitted, and the workflow has no push step,
+so review the close-out commit and remaining working-tree diff afterwards.
+If the backlog index markers are missing, it stops and tells you to repair
+the repository with
+`oat pjm init`.
 
 **Next step:** Review the changes against the implementation evidence and
 rerun diagnostics for lifecycle consistency. Start deferred work separately;

package/assets/docs/workflows/backlog-and-planning/remote-project-management.md

@@ -26,13 +26,6 @@ oat pjm doctor --json
 Continue only when `adoption.state` is `declared` or `inferred-legacy`. Run
 `oat pjm init` first when adoption is absent or only partially initialized.
 
-> [!WARNING]
-> Running `oat pjm init` again, or running `oat pjm migrate --apply`,
-> currently replaces the `pjm` section of `.oat/config.json` and deletes any
-> `pjm.remote` settings, which hold the remote policy described below. Before
-> you rerun either command, back up `.oat/config.json`. Afterwards, run
-> `git diff .oat/config.json` and restore `pjm.remote` if it was removed.
-
 ## Lifecycle operations
 
 The command family is `oat pjm remote`:

package/assets/docs/workflows/ideas/lifecycle.md

@@ -90,13 +90,8 @@ Good to know:
   (shared scope), pushed to a project ref (synced scope, the default on a
   fresh install), or kept on your machine (local scope).
 
-> [!WARNING]
-> Backlog items need project management (PJM, OAT's file-backed backlog,
-> roadmap, and decision records) adopted with `oat pjm init`. Run it once.
-> Running `oat pjm init` again, or running `oat pjm migrate --apply`,
-> currently deletes any `pjm.remote` settings from `.oat/config.json`. If
-> you rerun either command, check `git diff .oat/config.json` afterwards and
-> restore `pjm.remote` if it was removed.
+Backlog items need project management (PJM, OAT's file-backed backlog,
+roadmap, and decision records) adopted with `oat pjm init`. Run it once.
 
 1. Quick capture: `oat-idea-scratchpad` to review or capture idea seeds
 2. Start brainstorming: `oat-idea-new` (scaffolds directory, then invokes `oat-idea-ideate`)

package/assets/docs/workflows/projects/closeout/closeout-skills.md

@@ -21,7 +21,9 @@ When no closeout sequence is stored for the project, finish it in this order:
 4. Optionally, after you approve the finished work, `oat-project-retro` writes
    a retrospective, and `oat-project-retro-file` files its tracker items.
 5. `oat-project-complete` finalizes the project. You can run it before or after
-   the pull request merges.
+   the pull request merges. Wave workflows that complete wrapper projects
+   without prompts use the
+   [`oat-project-complete-auto`](#oat-project-complete-auto) companion instead.
 
 Use `oat-project-pr-progress` instead of the final PR only to share one
 finished phase while later phases are still in progress. Use
@@ -536,3 +538,62 @@ fakes completion by editing a status field by hand.
 **Next step:** Confirm the reported completion and PR-update outcomes. Follow
 any explicit recovery action if the flow stopped. Merge and release remain
 separate operations under repository policy.
+
+## oat-project-complete-auto
+
+The non-interactive companion to `oat-project-complete`. Workflow steps use it
+to complete projects without prompts; a person completing a project uses
+`oat-project-complete`. It decides every completion answer from config and
+recorded project state, refuses whenever an answer would need a human, and
+then follows the interactive skill's current steps.
+
+**Invocation:** You do not invoke it. The skill is model-invocable but not
+user-invocable, so it is never offered as a slash command. It runs only when a
+workflow step names it with a `--requested-by` value: `oat-wave-execute`
+closeout step 8 (one wave wrapper, completed before its merge handoff) and the
+`oat-wave-program` program completion checkpoint (a batch of wrappers, after
+your yes). Its `OAT_AUTONOMOUS` lifecycle route refuses until a lifecycle
+skill names the companion, and none does today. An agent never runs it on its
+own initiative, for example to clean up a finished but unarchived project.
+
+**Prerequisites:** Needs `workflow.autonomousComplete: true`; without it the
+skill stops with "interactive completion required" and writes nothing (see
+[Configuration](../../../reference/configuration.md)). It also needs an
+installed `oat-project-complete` with its scripts. Each project is then
+preflighted on its own and refused, with the failing check named, when its
+closeout sequence is incomplete, a task is incomplete, the final review has
+not passed, the PR precondition is unmet, blockers are recorded, the project
+log is ambiguous, or a completion question has no recorded answer (for
+example `workflow.archiveOnComplete` unset on a shared or synced project). The
+PR must be merged, or, for a step that completes before the merge, open and
+tracked in the project's state.
+
+**What it does without asking:** after every guard passes, it records a
+completion-before-merge exception in `implementation.md` when the PR is still
+open, points the active project at the project, and follows
+`oat-project-complete` with the resolved answers: archive per
+`workflow.archiveOnComplete`, a summary refresh when the summary is missing or
+stale, and no retrospective. It never creates a PR, whatever
+`workflow.createPrOnComplete` says; it updates the description of an existing
+tracked PR as the interactive steps require. The completion commit body
+records the requesting step (for a synced archive, the run report does). In batch mode a refused project stays deferred
+while the others complete.
+
+**Example scenario:** An autonomous wave run reaches closeout with the final
+review passed and the wave PR open. Execute's step 8 runs the companion with
+`--completion-before-merge`, which records the exception and completes and
+archives the wrapper before the merge handoff. Had `workflow.autonomousComplete`
+been off, the companion would refuse and the wave would defer the completion
+tail to program close instead.
+
+**Expected output:** A run report with one entry per project: `completed`,
+`refused`, or `failed`, the refusing check (`opt-in`, `activation`, or
+`preflight:<n>`), the PR and its state, any exception, the archive decision,
+and the completion commit. The calling workflow records the outcome in its own
+ledger.
+
+**Next step:** For a refused project, fix the named check or complete it with
+`oat-project-complete`. If a completion step fails after the project was
+archived, a later companion run refuses because the project directory is gone;
+resume with `oat-project-complete`, whose archive-resume branches finish the
+tail.

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

@@ -74,8 +74,12 @@ The root:
   cleanliness;
 - selects and launches the phase reviewer;
 - owns retry limits, review disposition, worktree fan-in, HiLL checkpoints, and
-  tracking-artifact commits; and
-- runs external phase gates and final closeout.
+  tracking-artifact commits;
+- runs external phase gates and final closeout; and
+- logs root judgment: breaks, surprises, workarounds, or notable successes,
+  including observations relayed from subagent reports, appended through
+  `oat project log append` at the next bookkeeping boundary rather than while
+  a child owns the worktree.
 
 The root does not implement phase tasks while an accepted phase launch owns
 that scope.
@@ -108,7 +112,9 @@ once, and directly executes each task in plan order. For every task it:
 6. verifies the commit, file boundary, tests, and clean worktree.
 
 After all tasks, it runs phase-wide verification and returns a compact report.
-It does not dispatch the phase reviewer or mutate general project bookkeeping.
+It does not dispatch the phase reviewer, mutate general project bookkeeping,
+or write the project log; phase implementers and other dispatched subagents
+have no logging duties.
 While it owns the worktree, it may atomically update only the active phase's
 authoritative `oat_phase_recovery_policy.phase_attempt_usage.<pNN>` entry. The
 phase returns with a matching committed `completed` or `failed` terminal marker
@@ -473,6 +479,20 @@ accepted failed launch and not a new schema version.
       Review-->>Root: Pass
     ```
 
+### Budget exhaustion
+
+The bounded loops end at fixed budgets: fix and re-review rounds at
+`oat_orchestration_retry_limit`, phase review gate rounds at the same limit,
+the final review at its three-cycle cap, and the configured exit gate at
+`maxAttempts`. At each of these points the root dispatches one read-only
+[complexity review](../reviews/index.md#complexity-review-at-budget-exhaustion) before
+escalating, saves its report under `reviews/archived/`, and shows a decision
+message with the stop reasons, the verdict, and the recommended disposition.
+The operator chooses: extra cycles, proceed with override, corrective revision,
+or **simplify**. The choice and the report path are recorded in
+`implementation.md`. Agents never select the disposition; under
+`OAT_AUTONOMOUS=1` the run stops with the same content in its boundary report.
+
 ## Parallel Phase Groups
 
 For a plan-declared parallel group, the root:

package/assets/docs/workflows/projects/execution/project-log.md

@@ -119,6 +119,12 @@ entries without asking agents to edit `project-log.md`:
 - `oat-project-implement` records accepted subagent dispatches, STOP or park
   events, phase outcomes, and parallel-group merge results. These entries point
   to the corresponding `implementation.md` record instead of copying it.
+- The `oat-project-implement` root also appends root-judgment entries when
+  breaks, surprises, workarounds, or notable successes surface, including
+  observations relayed from subagent reports. An entry that surfaces while a
+  child owns the worktree is queued and appended at the next bookkeeping
+  boundary. Phase implementers and other dispatched subagents have no logging
+  duties.
 - When `oat-project-implement` or `oat-project-review-provide` receives an
   artifact-mode review, the root workflow first consumes exactly one
   `**Reconnaissance:** attempted` or

package/assets/docs/workflows/projects/lifecycle.md

@@ -318,6 +318,7 @@ See [Implementation Execution](execution/implementation-execution.md) for the fu
 - `oat-project-review-receive` now presents a findings overview before asking for any disposition decisions.
 - Findings are shown with stable IDs by severity (`C*`, `I*`, `M*`, `m*`) so follow-up choices map clearly to specific items.
 - For each finding, the receive step summarizes the reviewer note, adds agent analysis, and gives a recommendation (convert now vs defer with rationale).
+- When a scope reaches the three-cycle review cap, the receive step dispatches a [complexity review](reviews/index.md#complexity-review-at-budget-exhaustion) and adds **simplify** to the dispositions the operator can choose. Every other budget exhaustion in the lifecycle (the orchestration retry limit, the final review cap, and a gate's `maxAttempts`) runs the same review before escalating.
 
 ## Alternate lifecycle lanes
 
@@ -398,6 +399,12 @@ effort controls.
 
 Quick lane lightweight design intentionally keeps a smaller collaborative/draft choice. Selective collaborative becomes available only after promotion into the full spec-driven design lane.
 
+When a plan gate is configured, quick-start persists its outcome as
+`oat_quick_start_gate` in project state (see
+[Gate approval records](../advanced/workflow-gates.md#gate-approval-records)).
+`oat-project-next` and `oat-project-progress` report that record; quick plan
+readiness stays the only routing rule for quick plans.
+
 Quick-start follows the same dispatch policy rule at the plan boundary: capture
 the policy when interactive, persist `oat_dispatch_policy` to project state, and
 avoid any mid-implementation policy prompt. Legacy dispatch-ceiling state is