@open-agent-toolkit/cli 0.3.15 → 0.3.16

package/assets/NOTICES.md

@@ -154,3 +154,51 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
+
+## tkstang/skills
+
+**Source:** https://github.com/tkstang/skills/tree/main/skills/complexity-review
+**License:** MIT
+**Version referenced:** `complexity-review` 1.0.2 (commit `8767bce4819a2cae1a9f257de650a5ed0ae0afc1`)
+
+### `complexity-review` skill
+
+Source files: `skills/complexity-review/SKILL.md` and
+`skills/complexity-review/references/evidence-guide.md`.
+
+Passages adapted and condensed into `.agents/docs/complexity-review-fallback.md`:
+the core premise, contract restatement, simplest viable baseline, machinery
+inventory, deletion test, evidence and recommendation scales, ledger columns,
+verdict criteria, report sections, and reviewer stance. The OAT version adds
+the budget-exhaustion triggers, the installed-skill probe, the read-only
+dispatch contract, the REQUIRES-OPERATOR, open-finding, and disposition
+sections, and the decision-message record.
+
+Consumer OAT skills: `oat-project-implement`, `oat-project-quick-start`, and
+`oat-project-review-receive` (each vendors the doc under `references/docs/`).
+
+### Upstream MIT license
+
+```text
+MIT License
+
+Copyright (c) 2026 Thomas Stang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

package/assets/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.3.15"
+  "oatVersion": "0.3.16"
 }

package/assets/docs/provider-sync/commands.md

@@ -98,6 +98,27 @@ Key behavior:
   failures, but skew present — apply reports
   `Manifest version refreshed; no content changes required.` instead of
   `No changes required.`, so a manifest write is never described as a no-op.
+- A faithful copy-strategy entry whose manifest row records a stale
+  `contentHash` (a pre-framing legacy digest or a tampered value) is planned as
+  `skip` with the reason
+  `already in sync; restamp stale manifest content hash`, and `--json` plan
+  entries carry the verified digest as `restampContentHash`. Apply writes that
+  digest, so the next run is a no-op. Only a row that tracks the same provider
+  path that sync checked is restamped. Dry-run then reports
+  `Run without --dry-run to restamp N stale manifest content hashes.` instead
+  of `No changes to apply.`. Apply reports
+  `Manifest content hash restamped for N entries; no content changes required.`
+  (combined with the version-refresh sentence when both happen), or
+  `Manifest content hash restamped for N entries.` beside a partial failure.
+- A copy-strategy canonical skill directory without `SKILL.md`, or agent
+  directory without `AGENT.md`, is planned as an `error` operation whose reason
+  names the missing file, instead of a copy that never verifies and is retried
+  on every run. It changes nothing and is not a planned operation; other
+  entries still sync. Apply reports it as a failed result (`status: failed`
+  with a `failure` in `--json` `operationResults`) and exits 1. Dry-run lists
+  it, warns `N entry cannot sync until its configuration error is fixed.`,
+  counts it in `summary.failed`, and still exits 0. Symlink strategy is
+  unaffected.
 
 `oat sync` is not the only command that replaces a manifest's producer version.
 `oat init`, `oat remove skill`, and `oat status` each capture the manifest's

package/assets/docs/reference/cli-reference.md

@@ -162,7 +162,7 @@ Notable commands introduced in the current CLI surface:
 - `oat project validate-plan --project-path <path>` - validates `oat_plan_parallel_groups` metadata in `plan.md`; exits non-zero on invalid. Lite plans must contain exactly one phase, declare no parallel groups, and give every Validation Criteria bullet either a backticked command or a `manual:` instruction. See [Implementation Execution](../workflows/projects/execution/implementation-execution.md#parallel-phase-groups).
 - `oat project log append|check|synthesize|rollup` - manage the optional append-only project observation log: append validated judgment or structural entries, inspect grammar and synthesis status, complete end-of-run synthesis, and roll observations into `summary.md` plus the configured repository ledger. See [Project Log](../workflows/projects/execution/project-log.md).
 - `oat project set-mode` — deprecated no-op. Execution mode is no longer user-selectable; emits a deprecation warning and preserves the `--json` contract.
-- `oat gate review <prompt...>` - run a stateful, headless OAT review through the target registry, parse the produced review artifact, and exit nonzero for configured blocking findings. `--timeout-ms <milliseconds>` overrides target, `workflow.gateTimeouts`, environment, and scope defaults; accepted values are 1,000–14,400,000. Final/phase/range code reviews default to 30 minutes, while task code and artifact reviews default to 15 minutes. With `--json`, the result envelope on exit is the canonical completion signal: `status` is `ok` | `blocked` | `review_failed` | `artifact_missing` | `artifact_validation_failed` | `targeting_correlation_failed`, alongside `runId`, `generatedAt`, and `artifactPath` when available. `artifact_missing` means an accepted child exited cleanly without an artifact; fix synchronous review/artifact completion and start a new run, without review-receive or same-run remediation. For `targeting_correlation_failed`, correct the project declaration or artifact routing and start a new run; do not run review-receive even if an artifact path is present. For `artifact_validation_failed`, correct the artifact and rerun the gate until it revalidates as `ok` or `blocked`. Invoke `oat-project-review-receive` only when all three conditions hold: `status` is `ok` or `blocked`, `receiveEligible` is `true`, and `handoff` is non-null. `review_failed` may include structured `refusal`, `noOutputProduced`, and metadata-only `activityEvidence`; these diagnostic fields never make a run receive-eligible. After a timeout, a validated run-correlated artifact returns the ordinary `ok` or `blocked` envelope with additive `lateCompletion: true`. When post-selection work fails after the reviewer already committed a run-correlated artifact, the gate re-validates that selected snapshot through the same eligibility path rather than re-parsing whatever the path now holds, never re-dispatching, and returns the ordinary `ok` or `blocked` envelope with additive `postSelectionRecovery: true`; the artifact must still be present and unchanged for re-validation to succeed. When nothing recovers, `review_failed` names the failing sub-step in `postSelection.step` and its cause in `postSelection.code`. Duplicate run-ID matches or a changed artifact with a mismatched run ID retain `targeting_correlation_failed` and `receiveEligible: false`. Orchestrators should read the structured result rather than poll the filesystem. See [Workflow Gates](../workflows/advanced/workflow-gates.md).
+- `oat gate review <prompt...>` - run a stateful, headless OAT review through the target registry, parse the produced review artifact, and exit nonzero for configured blocking findings. `--timeout-ms <milliseconds>` overrides target, `workflow.gateTimeouts`, environment, and scope defaults; accepted values are 1,000–14,400,000. Final/phase/range code reviews and artifact reviews default to 30 minutes, while task code reviews default to 15 minutes. With `--json`, the result envelope on exit is the canonical completion signal: `status` is `ok` | `blocked` | `review_failed` | `artifact_missing` | `artifact_validation_failed` | `targeting_correlation_failed`, alongside `runId`, `generatedAt`, and `artifactPath` when available. `artifact_missing` means an accepted child exited cleanly without an artifact; fix synchronous review/artifact completion and start a new run, without review-receive or same-run remediation. For `targeting_correlation_failed`, correct the project declaration or artifact routing and start a new run; do not run review-receive even if an artifact path is present. For `artifact_validation_failed`, correct the artifact and rerun the gate until it revalidates as `ok` or `blocked`. Invoke `oat-project-review-receive` only when all three conditions hold: `status` is `ok` or `blocked`, `receiveEligible` is `true`, and `handoff` is non-null. `review_failed` may include structured `refusal`, `noOutputProduced`, and metadata-only `activityEvidence`; these diagnostic fields never make a run receive-eligible. After a timeout, a validated run-correlated artifact returns the ordinary `ok` or `blocked` envelope with additive `lateCompletion: true`. When post-selection work fails after the reviewer already committed a run-correlated artifact, the gate re-validates that selected snapshot through the same eligibility path rather than re-parsing whatever the path now holds, never re-dispatching, and returns the ordinary `ok` or `blocked` envelope with additive `postSelectionRecovery: true`; the artifact must still be present and unchanged for re-validation to succeed. When nothing recovers, `review_failed` names the failing sub-step in `postSelection.step` and its cause in `postSelection.code`. Duplicate run-ID matches or a changed artifact with a mismatched run ID retain `targeting_correlation_failed` and `receiveEligible: false`. Orchestrators should read the structured result rather than poll the filesystem. See [Workflow Gates](../workflows/advanced/workflow-gates.md).
 - `oat gate route --expect-runtime <runtime> --expect-model <model> --can-await <true|false> --json` - return the headless child route (`inline`, `delegate-sync`, or `refuse`) from provider-marker and model evidence. Ambiguous or contradictory evidence never routes inline.
 - `oat gate exec <prompt...>` / `oat gate cross-provider-exec <prompt...>` - run a generic target prompt. `--timeout-ms` uses the same validated CLI override; untyped runs otherwise retain the legacy default path.
 - `oat gate target set <id> --invocation-model <model|provider-default> --invocation-reasoning-effort <effort|provider-default>` - persist optional configured invocation metadata alongside an exec target without inferring it from the target command.
@@ -203,6 +203,7 @@ The `workflow.*` namespace holds user-facing workflow preferences that let you a
 - `workflow.hillCheckpointDefault` (`every` | `final`) — default HiLL checkpoint behavior in `oat-project-implement`
 - `workflow.archiveOnComplete` (`boolean`) — skip the archive prompt in `oat-project-complete`
 - `workflow.createPrOnComplete` (`boolean`) — skip the "Open a PR?" prompt in `oat-project-complete`
+- `workflow.autonomousComplete` (`boolean`, default `false`) — standing opt-in for the non-interactive `oat-project-complete-auto` companion; when `false` it stops with "interactive completion required"
 - `workflow.postImplementSequence` (legacy `wait` | `summary` | `pr` | `docs-pr`, or structured `{preApproval, postApproval}` arrays) — approval-aware post-implementation chaining
 - `workflow.reviewExecutionModel` (`subagent` | `inline` | `fresh-session`) — default final-review execution model
 - `workflow.autoReviewAtHillCheckpoints` (`boolean`) — auto-run the extra lifecycle review at HiLL checkpoints

package/assets/docs/reference/configuration.md

@@ -272,7 +272,13 @@ packaged `assets/` directory next to the installed CLI. Setting a non-empty
   required bundle directory is empty in the packed tarball.
 - Produce a matching bundle with `bash packages/cli/scripts/bundle-assets.sh`
   while `OAT_ASSETS_DIR` points at the target directory (the script already
-  honors the variable as its destination).
+  honors the variable as its destination). Because publishing replaces the
+  destination, the script accepts an override destination only when it is
+  absent, an empty directory, or a previous bundle (a directory holding
+  `bundle-metadata.json`); it refuses anything else, including a directory it
+  cannot list. The default `packages/cli/assets` destination is exempt. The
+  script also stops before copying when an inventory lookup comes back empty,
+  absolute, climbing with `..`, or naming the repository root.
 
 This is primarily a test-isolation and packaging seam; day-to-day use of the CLI
 does not need it.
@@ -294,7 +300,7 @@ must be integer milliseconds from `1,000` through `14,400,000`.
   "workflow": {
     "gateTimeouts": {
       "code": 2400000,
-      "artifact": 900000
+      "artifact": 2400000
     },
     "gates": {
       "execTargets": {
@@ -712,6 +718,7 @@ Workflow preference keys live under the `workflow.*` namespace:
 - `workflow.hillCheckpointDefault` — `every` or `final`. Default HiLL checkpoint behavior in `oat-project-implement` (a HiLL, or human-in-the-loop, checkpoint is a stop for your review): pause after every phase or only after the last phase. When unset, the skill prompts. See [Choosing a checkpoint default](#choosing-a-checkpoint-default).
 - `workflow.archiveOnComplete` — boolean. Skip the "Archive after completion?" prompt in `oat-project-complete`. When unset, the skill prompts.
 - `workflow.createPrOnComplete` — boolean. Skip the "Open a PR?" prompt in `oat-project-complete`; when true, completion auto-triggers PR creation. When unset, the skill prompts.
+- `workflow.autonomousComplete` — boolean, default `false`. Standing opt-in for `oat-project-complete-auto`, the non-interactive completion companion that runs only when a workflow names it as a step (today `oat-wave-execute` closeout step 8 and the `oat-wave-program` completion checkpoint). Its `OAT_AUTONOMOUS` lifecycle route refuses until a lifecycle skill names the companion, and none does today. When `false`, the companion stops with "interactive completion required" and writes nothing. The interactive `oat-project-complete` is unaffected.
 - `workflow.postImplementSequence` — legacy `wait`, `summary`, `pr`, or `docs-pr`, or `{ "preApproval": [...], "postApproval": [...] }`. Legacy values remain strings and keep their existing mappings. Structured arrays contain ordered, globally unique `summary`, `document`, `pr`, and `retro` steps. `retro` is post-approval only: a structured value containing it in `preApproval` is rejected. Pre-approval steps run after final review and before final HiLL approval; post-approval steps run only after that approval. Plain retrieval keeps legacy strings and prints structured values as compact JSON; `--json` returns the raw value.
 - `workflow.retro.filing.repo` — `issues`, `backlog`, or `none`; unset by default. Selects the repo-lane filing destination.
 - `workflow.retro.filing.upstream` — `issues` or `none`; unset by default. Selects the upstream-lane filing destination.
@@ -889,6 +896,7 @@ Other preferences **depend on per-repo configuration** to be safe. These should
 - `workflow.archiveOnComplete` — correctness depends on the repo's `archive.s3Uri` / `archive.s3SyncOnComplete` being configured. A user-level `true` would try to archive in repos that aren't set up for it.
 - `workflow.postImplementSequence` — correctness depends on `documentation.requireForProjectCompletion`. Setting `pr` at user level would foot-gun you in any repo that requires docs, because completion would later block on the docs gate while the PR is already open.
 - `workflow.createPrOnComplete` — this key is almost always redundant with `postImplementSequence`-driven flows. When it's meaningful, its correctness depends on the same per-repo docs and PR gates. Prefer shared scope, or omit it entirely and rely on `postImplementSequence: pr` or `docs-pr` to handle PR creation at the end of implement.
+- `workflow.autonomousComplete` — authorizes unattended completion, which archives with the repo's `workflow.archiveOnComplete` and `archive.*` settings. It never creates a PR: it reads and reports `workflow.createPrOnComplete` without acting on it, and only updates the description of an already tracked PR. A user-level `true` would authorize autonomous completion in every repo, including ones whose archive settings were never chosen for it. Set it with `--shared` (or `--local` for one checkout) in each repo whose completion settings you have reviewed.
 
 **Cross-repo foot-gun example:** If you set `workflow.createPrOnComplete: true --user`, it applies to every repo you work on. In a repo with `documentation.requireForProjectCompletion: true` and `postImplementSequence: pr` (no docs step), running `oat-project-complete` would try to auto-create a PR, then immediately hit the docs gate and block you — leaving you with an open PR and a stuck completion. Your user-level preference silently asserted something that only holds in a specific shared-config shape.
 

package/assets/docs/skills/index.md

@@ -145,6 +145,7 @@ for policy, storage, approval, and recovery details.
     - `oat-explainer-kit`
     - `oat-wrap-up`
     - `oat-project-complete`
+    - `oat-project-complete-auto`
     - `oat-wave-program`
     - `oat-wave-execute`
 

package/assets/docs/skills/recon.md

@@ -303,11 +303,14 @@ downgrades. Every claim a review kept below `verified` (an unresolved issue
 scoped to it or global to its review, a coverage finding that names it, or a
 non-affirming disposition) is listed under Review Downgrades with the review's
 own text, even when it is not a key claim, so a `complete` packet cannot hide a
-downgraded claim. A claim that a required review left without a disposition stays
-`unresolved`. Any claim below `verified` that an incorporated assurance review,
-core or thorough, listed in its brief but left without a disposition is listed
-there as not reviewed by that review; a claim outside a review's brief is never
-reported as its omission. A review's
+downgraded claim. The required reviews are semantic, adversarial, and coverage,
+plus redundant verification when the run achieves `thorough`; contradiction
+resolution is never required. A claim that any required review left without a
+disposition stays `unresolved`, so the run publishes an honest packet instead of
+failing validation. Any claim below `verified` that an incorporated assurance
+review, core or thorough, listed in its brief but left without a disposition is
+listed there as not reviewed by that review; a claim outside a required review's
+brief is listed as outside its brief, never as that review's omission. A review's
 `unresolvedIssues` entry may name the claim IDs it affects or apply to the
 whole review; a legacy plain-string entry is read as review-wide. A material
 coverage gap does not fail publication by itself: the claims it affects stay

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

@@ -75,6 +75,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/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