@open-agent-toolkit/cli 0.3.14 → 0.3.16

package/assets/docs/workflows/advanced/orchestration-model.md

@@ -29,25 +29,32 @@ Terms used on this page:
 
 ## Default Topology
 
-```mermaid
-flowchart TD
-  Root["Project root\nlifecycle owner"]
-  Adapter["Project dispatch adapter"]
-  Engine["Provider-neutral dispatch engine"]
-
-  Root --> Adapter --> Engine
-  Engine --> P["Phase implementer\none per phase"]
-  P --> T1["Planned task commit"]
-  P --> T2["Planned task commit"]
-  P -. optional .-> Recon["Recon / specialist / isolated fanout"]
-
-  Root -. independent review lane .-> Adapter
-  Engine -. exact reviewer route .-> R["Phase reviewer"]
-  R -->|blocking findings| Root
-  Root -->|resume bounded fix| P
-
-  Root -. external gate lane .-> G["Configured cross-runtime gate"]
-```
+=== "Diagram"
+
+    ![Default topology: the project root goes through the dispatch adapter and provider-neutral engine to one phase implementer per phase, which makes planned task commits and optionally a recon or specialist fanout; the engine routes an exact phase reviewer whose blocking findings return to the root, which resumes a bounded fix; dashed lanes show independent review and an external cross-runtime gate](/diagrams/orchestration-model-1-default-topology-light.svg)
+    ![Default topology: the project root goes through the dispatch adapter and provider-neutral engine to one phase implementer per phase, which makes planned task commits and optionally a recon or specialist fanout; the engine routes an exact phase reviewer whose blocking findings return to the root, which resumes a bounded fix; dashed lanes show independent review and an external cross-runtime gate](/diagrams/orchestration-model-1-default-topology-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart TD
+      Root["Project root\nlifecycle owner"]
+      Adapter["Project dispatch adapter"]
+      Engine["Provider-neutral dispatch engine"]
+
+      Root --> Adapter --> Engine
+      Engine --> P["Phase implementer\none per phase"]
+      P --> T1["Planned task commit"]
+      P --> T2["Planned task commit"]
+      P -. optional .-> Recon["Recon / specialist / isolated fanout"]
+
+      Root -. independent review lane .-> Adapter
+      Engine -. exact reviewer route .-> R["Phase reviewer"]
+      R -->|blocking findings| Root
+      Root -->|resume bounded fix| P
+
+      Root -. external gate lane .-> G["Configured cross-runtime gate"]
+    ```
 
 The solid implementation lane is mandatory. The dotted nested lane is
 benefit-driven. A run does not fail merely because the phase agent cannot or
@@ -83,21 +90,28 @@ matrix. The lifecycle workflow remains authoritative for classification,
 selection judgment, synthesis, and state mutation. The dispatch engine does
 not edit `plan.md`, `implementation.md`, or project state.
 
-```mermaid
-sequenceDiagram
-  participant Root as Project root
-  participant Adapter as Project adapter
-  participant Engine as Dispatch engine
-  participant Record as Run record in implementation.md
-  participant Phase as Phase implementer
-
-  Root->>Adapter: Phase + lifecycle authority
-  Adapter->>Engine: Provider-neutral dispatch request
-  Engine-->>Root: Exact route + request ID
-  Root->>Phase: Phase Scope
-  Root->>Record: Accepted or blocked-before-start result
-  Phase-->>Root: Phase report + commits
-```
+=== "Diagram"
+
+    ![Dispatch layers sequence: the project root passes phase and lifecycle authority to the adapter, the adapter sends a provider-neutral request to the engine, the engine returns the exact route and request ID, the root sends the phase scope and records the accepted or blocked result in implementation.md, and the implementer returns its report and commits](/diagrams/orchestration-model-2-dispatch-layers-light.svg)
+    ![Dispatch layers sequence: the project root passes phase and lifecycle authority to the adapter, the adapter sends a provider-neutral request to the engine, the engine returns the exact route and request ID, the root sends the phase scope and records the accepted or blocked result in implementation.md, and the implementer returns its report and commits](/diagrams/orchestration-model-2-dispatch-layers-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    sequenceDiagram
+      participant Root as Project root
+      participant Adapter as Project adapter
+      participant Engine as Dispatch engine
+      participant Record as Run record in implementation.md
+      participant Phase as Phase implementer
+
+      Root->>Adapter: Phase + lifecycle authority
+      Adapter->>Engine: Provider-neutral dispatch request
+      Engine-->>Root: Exact route + request ID
+      Root->>Phase: Phase Scope
+      Root->>Record: Accepted or blocked-before-start result
+      Phase-->>Root: Phase report + commits
+    ```
 
 ## Phase Execution
 

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/ideas/lifecycle.md

@@ -22,31 +22,38 @@ Each level has its own independent backlog, scratchpad, and active-idea config v
 
 Start in the home that matches how formed the thought is. Every home is a fine place to stop. Dashed arrows are optional moves.
 
-```mermaid
-flowchart TD
-  Q{"How formed is\nthe thought?"}
-  BS["oat-brainstorm\n(may end inline\nor as a doc)"]
-  SP["Scratchpad seed\n.oat/ideas/\nscratchpad.md"]
-  ID["Idea\n.oat/ideas/{idea}/\ndiscovery.md"]
-  SUM["Summarized idea\n.oat/ideas/{idea}/\nsummary.md"]
-  BL["Backlog item\n.oat/repo/pjm/\nbacklog/items/"]
-  PR["Project\n.oat/projects/\n{scope}/{slug}/"]
-  SPLIT["Parent +\nchild projects"]
-
-  Q -->|unsure| BS
-  Q -->|seed| SP
-  Q -->|explore| ID
-  Q -->|scoped| BL
-  Q -->|ready| PR
-  BS -.-> ID
-  BS -.-> BL
-  BS -.->|"project(s)"| PR
-  SP -.->|optional| ID
-  ID -.->|optional| SUM
-  SUM -.->|optional| PR
-  BL -.->|optional| PR
-  PR -.->|"optional\n(spec-driven)"| SPLIT
-```
+=== "Diagram"
+
+    ![Where a thought starts depending on how formed it is: oat-brainstorm when unsure, a scratchpad seed, an idea, a backlog item, or a project, with optional moves between them and an optional spec-driven split into parent and child projects](/diagrams/ideas-lifecycle-light.svg)
+    ![Where a thought starts depending on how formed it is: oat-brainstorm when unsure, a scratchpad seed, an idea, a backlog item, or a project, with optional moves between them and an optional spec-driven split into parent and child projects](/diagrams/ideas-lifecycle-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart TD
+      Q{"How formed is\nthe thought?"}
+      BS["oat-brainstorm\n(may end inline\nor as a doc)"]
+      SP["Scratchpad seed\n.oat/ideas/\nscratchpad.md"]
+      ID["Idea\n.oat/ideas/{idea}/\ndiscovery.md"]
+      SUM["Summarized idea\n.oat/ideas/{idea}/\nsummary.md"]
+      BL["Backlog item\n.oat/repo/pjm/\nbacklog/items/"]
+      PR["Project\n.oat/projects/\n{scope}/{slug}/"]
+      SPLIT["Parent +\nchild projects"]
+
+      Q -->|unsure| BS
+      Q -->|seed| SP
+      Q -->|explore| ID
+      Q -->|scoped| BL
+      Q -->|ready| PR
+      BS -.-> ID
+      BS -.-> BL
+      BS -.->|"project(s)"| PR
+      SP -.->|optional| ID
+      ID -.->|optional| SUM
+      SUM -.->|optional| PR
+      BL -.->|optional| PR
+      PR -.->|"optional\n(spec-driven)"| SPLIT
+    ```
 
 Where to start:
 

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

@@ -38,21 +38,28 @@ and updates project state.
 
 Tasks execute serially in one worktree for the phase.
 
-```mermaid
-flowchart LR
-  Root["Project root\nlifecycle owner"] --> P["Phase implementer\none per phase"]
-  P --> T1["Task 1\nbounded commit"]
-  P --> T2["Task 2\nbounded commit"]
-  P -. optional benefit-driven .-> N["Recon / specialist child"]
-
-  P --> Report["Phase report\nverification + commits"]
-  Report --> Root
-  Root --> Ledger["Commit task ledger\npre-review bookkeeping"]
-  Ledger --> R["Independent phase reviewer"]
-  R -->|pass| Book["Review-outcome bookkeeping\n+ next phase"]
-  R -->|blocking findings| Fix["Resume phase implementer\nbounded fix scope"]
-  Fix --> R2["Fresh root-owned review round"]
-```
+=== "Diagram"
+
+    ![Phase execution: the project root dispatches one phase implementer, which makes bounded task commits and optionally a recon or specialist child, then reports back; the root commits the task ledger, an independent reviewer passes the phase or sends blocking findings to a resumed implementer for a bounded fix and a fresh review round](/diagrams/implementation-execution-1-quick-look-light.svg)
+    ![Phase execution: the project root dispatches one phase implementer, which makes bounded task commits and optionally a recon or specialist child, then reports back; the root commits the task ledger, an independent reviewer passes the phase or sends blocking findings to a resumed implementer for a bounded fix and a fresh review round](/diagrams/implementation-execution-1-quick-look-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart LR
+      Root["Project root\nlifecycle owner"] --> P["Phase implementer\none per phase"]
+      P --> T1["Task 1\nbounded commit"]
+      P --> T2["Task 2\nbounded commit"]
+      P -. optional benefit-driven .-> N["Recon / specialist child"]
+
+      P --> Report["Phase report\nverification + commits"]
+      Report --> Root
+      Root --> Ledger["Commit task ledger\npre-review bookkeeping"]
+      Ledger --> R["Independent phase reviewer"]
+      R -->|pass| Book["Review-outcome bookkeeping\n+ next phase"]
+      R -->|blocking findings| Fix["Resume phase implementer\nbounded fix scope"]
+      Fix --> R2["Fresh root-owned review round"]
+    ```
 
 ## Ownership
 
@@ -67,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.
@@ -101,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
@@ -443,21 +456,42 @@ The new dispatch record links to the original `request_id` through the existing
 `continuation_events` field. This is a new fix scope, not replacement of an
 accepted failed launch and not a new schema version.
 
-```mermaid
-sequenceDiagram
-  participant Root
-  participant Phase as Phase implementer
-  participant Review as Phase reviewer
-
-  Root->>Phase: Phase Scope (request_id=A)
-  Phase-->>Root: DONE + task commits
-  Root->>Review: Review phase commit range
-  Review-->>Root: Critical / High findings
-  Root->>Phase: Resume A in fix mode
-  Phase-->>Root: Fix commit + verification
-  Root->>Review: New independent review round
-  Review-->>Root: Pass
-```
+=== "Diagram"
+
+    ![Fix continuity sequence: root sends the phase scope with request_id A, the implementer returns DONE with task commits, the reviewer returns Critical or High findings, root resumes request A in fix mode, the implementer returns a fix commit, and a new independent review round passes](/diagrams/implementation-execution-2-fix-continuity-light.svg)
+    ![Fix continuity sequence: root sends the phase scope with request_id A, the implementer returns DONE with task commits, the reviewer returns Critical or High findings, root resumes request A in fix mode, the implementer returns a fix commit, and a new independent review round passes](/diagrams/implementation-execution-2-fix-continuity-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    sequenceDiagram
+      participant Root
+      participant Phase as Phase implementer
+      participant Review as Phase reviewer
+
+      Root->>Phase: Phase Scope (request_id=A)
+      Phase-->>Root: DONE + task commits
+      Root->>Review: Review phase commit range
+      Review-->>Root: Critical / High findings
+      Root->>Phase: Resume A in fix mode
+      Phase-->>Root: Fix commit + verification
+      Root->>Review: New independent review round
+      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
 

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