@open-agent-toolkit/cli 0.3.14 → 0.3.16

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

@@ -35,14 +35,21 @@ For a one-page view of where people approve and what runs automatically in each
 
 ## Lifecycle Map
 
-```mermaid
-flowchart LR
-  D["Discovery"] --> S["Spec"] --> G["Design"] --> P["Plan"]
-  P --> I["Implement (oat-project-implement)"]
-  I --> R["Review loop"] --> PR["PR flow"]
-  PR --> DOC["Docs sync (optional)"]
-  DOC --> C["Complete"]
-```
+=== "Diagram"
+
+    ![Project lifecycle map: discovery, spec, design, plan, implement, review loop, PR flow, optional docs sync, complete](/diagrams/project-lifecycle-1-lifecycle-map-light.svg)
+    ![Project lifecycle map: discovery, spec, design, plan, implement, review loop, PR flow, optional docs sync, complete](/diagrams/project-lifecycle-1-lifecycle-map-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart LR
+      D["Discovery"] --> S["Spec"] --> G["Design"] --> P["Plan"]
+      P --> I["Implement (oat-project-implement)"]
+      I --> R["Review loop"] --> PR["PR flow"]
+      PR --> DOC["Docs sync (optional)"]
+      DOC --> C["Complete"]
+    ```
 
 This map shows the spec-driven default. The quick, lite, import, and capture
 lanes each skip part of it — see [Lane diagrams](#lane-diagrams) below. Lite in
@@ -311,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
 
@@ -340,12 +348,19 @@ See [Implementation Execution](execution/implementation-execution.md) for the fu
 
 ### Spec-Driven workflow lane
 
-```mermaid
-flowchart LR
-  D["Discover"] --> S["Spec"] --> G["Design"] --> P["Plan"]
-  P --> I["Implement (oat-project-implement)"]
-  I --> R["Review"] --> PR["PR"] --> Doc["Docs (optional)"] --> C["Complete"]
-```
+=== "Diagram"
+
+    ![Spec-driven lane: discover, spec, design, plan, implement, review, PR, optional docs, complete](/diagrams/project-lifecycle-2-spec-driven-light.svg)
+    ![Spec-driven lane: discover, spec, design, plan, implement, review, PR, optional docs, complete](/diagrams/project-lifecycle-2-spec-driven-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart LR
+      D["Discover"] --> S["Spec"] --> G["Design"] --> P["Plan"]
+      P --> I["Implement (oat-project-implement)"]
+      I --> R["Review"] --> PR["PR"] --> Doc["Docs (optional)"] --> C["Complete"]
+    ```
 
 During the Design step, `oat-project-design` asks how to work through the document unless a mode was selected by argument, environment, or `workflow.designMode`. The three full-design choices are collaborative, selective collaborative, and draft-and-review.
 
@@ -365,18 +380,31 @@ effort controls.
 
 ### Quick lane
 
-```mermaid
-flowchart LR
-  Q["Quick Start\n(adaptive discovery)"] --> D{"Design depth?"}
-  D -->|Straight to plan| P["Plan"]
-  D -->|Lightweight design| LD["Design (quick)"] --> P
-  D -->|Promote| SD["→ Spec-Driven lane"]
-  P --> QI["Implement (oat-project-implement)"]
-  QI --> QR["Review / PR"]
-```
+=== "Diagram"
+
+    ![Quick lane: quick start with adaptive discovery, then a design-depth choice (straight to plan, lightweight design, or promote to spec-driven), plan, implement, review and PR](/diagrams/project-lifecycle-3-quick-lane-light.svg)
+    ![Quick lane: quick start with adaptive discovery, then a design-depth choice (straight to plan, lightweight design, or promote to spec-driven), plan, implement, review and PR](/diagrams/project-lifecycle-3-quick-lane-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart LR
+      Q["Quick Start\n(adaptive discovery)"] --> D{"Design depth?"}
+      D -->|Straight to plan| P["Plan"]
+      D -->|Lightweight design| LD["Design (quick)"] --> P
+      D -->|Promote| SD["→ Spec-Driven lane"]
+      P --> QI["Implement (oat-project-implement)"]
+      QI --> QR["Review / PR"]
+    ```
 
 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
@@ -386,13 +414,20 @@ should use the dispatch-policy names, including explicit `Uncapped` and
 
 ### Lite lane
 
-```mermaid
-flowchart LR
-  L["Lite interview\n(one batched round)"] --> P["Single-phase plan\n(one approval)"]
-  P --> I["Implement (oat-project-implement)"]
-  I --> R["Final review"] --> PR["PR (default closeout)"]
-  P -->|Scope grows| Q["Promote to Quick"]
-```
+=== "Diagram"
+
+    ![Lite lane: one batched interview, a single-phase plan with one approval, implement, final review and PR, with promotion to quick if scope grows](/diagrams/project-lifecycle-4-lite-lane-light.svg)
+    ![Lite lane: one batched interview, a single-phase plan with one approval, implement, final review and PR, with promotion to quick if scope grows](/diagrams/project-lifecycle-4-lite-lane-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart LR
+      L["Lite interview\n(one batched round)"] --> P["Single-phase plan\n(one approval)"]
+      P --> I["Implement (oat-project-implement)"]
+      I --> R["Final review"] --> PR["PR (default closeout)"]
+      P -->|Scope grows| Q["Promote to Quick"]
+    ```
 
 Lite keeps planning and validation in `plan.md`. The interview selects a
 `minimal`, `product`, `technical`, or `both` content shape and records the
@@ -420,29 +455,36 @@ from its five core sections plus any adaptive Product Behavior and Technical
 Design, a **fresh** quick template takes over the `plan.md` path, and `state.md`
 is **rewritten** to quick mode.
 
-```mermaid
-flowchart LR
-  subgraph Before
-    LPLAN["plan.md\nfive core sections plus adaptive\nProduct Behavior / Technical Design"]
-    LSTATE["state.md\noat_workflow_mode: lite"]
-  end
-
-  CMD["oat project promote\n--to quick"]
-
-  subgraph After
-    DISC["discovery.md\nderived from the lite plan\noat_ready_for: oat-project-quick-start"]
-    REF["references/lite-plan.md\noriginal lite plan, preserved"]
-    QPLAN["plan.md\nfresh quick-start template"]
-    QSTATE["state.md\noat_workflow_mode: quick\noat_phase: discovery (complete)\noat_ready_for: oat-project-quick-start"]
-  end
-
-  LPLAN --> CMD
-  LSTATE --> CMD
-  CMD -->|derive| DISC
-  CMD -->|move| REF
-  CMD -->|scaffold| QPLAN
-  CMD -->|rewrite| QSTATE
-```
+=== "Diagram"
+
+    ![Promoting a lite project to quick: oat project promote --to quick derives discovery.md from the lite plan, moves the original to references/lite-plan.md, scaffolds a fresh quick plan.md, and rewrites state.md to quick mode](/diagrams/project-lifecycle-5-promote-lite-to-quick-light.svg)
+    ![Promoting a lite project to quick: oat project promote --to quick derives discovery.md from the lite plan, moves the original to references/lite-plan.md, scaffolds a fresh quick plan.md, and rewrites state.md to quick mode](/diagrams/project-lifecycle-5-promote-lite-to-quick-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart LR
+      subgraph Before
+        LPLAN["plan.md\nfive core sections plus adaptive\nProduct Behavior / Technical Design"]
+        LSTATE["state.md\noat_workflow_mode: lite"]
+      end
+
+      CMD["oat project promote\n--to quick"]
+
+      subgraph After
+        DISC["discovery.md\nderived from the lite plan\noat_ready_for: oat-project-quick-start"]
+        REF["references/lite-plan.md\noriginal lite plan, preserved"]
+        QPLAN["plan.md\nfresh quick-start template"]
+        QSTATE["state.md\noat_workflow_mode: quick\noat_phase: discovery (complete)\noat_ready_for: oat-project-quick-start"]
+      end
+
+      LPLAN --> CMD
+      LSTATE --> CMD
+      CMD -->|derive| DISC
+      CMD -->|move| REF
+      CMD -->|scaffold| QPLAN
+      CMD -->|rewrite| QSTATE
+    ```
 
 The project slug, directory, and branch are untouched, so history and any open
 work continue uninterrupted. `oat_ready_for` is stamped on **both** `discovery.md`
@@ -455,21 +497,35 @@ categorical `reason` and exit non-zero. See
 
 ### Import lane
 
-```mermaid
-flowchart LR
-  I["Import Plan"] --> II1["Implement (oat-project-implement)"]
-  II1 --> IR["Review / PR"]
-```
+=== "Diagram"
+
+    ![Import lane: import a plan, implement, then review and PR](/diagrams/project-lifecycle-6-import-lane-light.svg)
+    ![Import lane: import a plan, implement, then review and PR](/diagrams/project-lifecycle-6-import-lane-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart LR
+      I["Import Plan"] --> II1["Implement (oat-project-implement)"]
+      II1 --> IR["Review / PR"]
+    ```
 
 ### Capture lane
 
 Retroactive project creation for work done outside the OAT project workflow. Common scenario: mobile/cloud sessions where you brainstorm and implement with an agent, then want to open a PR and review from your desktop.
 
-```mermaid
-flowchart LR
-  W["Work on branch\n(no project)"] --> Cap["oat-project-capture"]
-  Cap --> R["Review / PR"]
-```
+=== "Diagram"
+
+    ![Capture lane: work on a branch without a project, run oat-project-capture, then review and PR](/diagrams/project-lifecycle-7-capture-lane-light.svg)
+    ![Capture lane: work on a branch without a project, run oat-project-capture, then review and PR](/diagrams/project-lifecycle-7-capture-lane-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart LR
+      W["Work on branch\n(no project)"] --> Cap["oat-project-capture"]
+      Cap --> R["Review / PR"]
+    ```
 
 Entry point: `/oat-project-capture` (skill-only, no CLI command — requires agent conversation context).
 

package/assets/docs/workflows/projects/reviews/index.md

@@ -166,7 +166,7 @@ is evaluated.
 - **Passing gate** (no findings at or above the threshold): receive runs a non-pausing **judgment sweep**. It makes a per-finding decision for each Medium/Low — defer to final review (the default, recorded so [final review](#phase-and-final-review) resurfaces it), address now (only for small, contained, low-risk fixes, which do **not** re-trigger the standard reviewer or re-gate the phase), or reject with rationale — then archives the artifact. Address-now is an exception, not the norm; if such a fix reveals a Critical/High concern it escalates to the blocking path.
 - **Blocking gate** (one or more findings at or above the threshold): receive converts findings to fix tasks and implementation re-runs the standard reviewer and the gate for the phase. These block → fix → re-gate rounds are bounded by `oat_orchestration_retry_limit` (default `2`); exhausting the bound stops a sequential run or excludes the phase in a parallel group, matching the standard fix loop's terminal handling.
 
-Gate-originated artifacts (`oat_review_invocation: gate`) are excluded from the same-scope review-cycle cap in `oat-project-review-receive`. The cap measures failed fix cycles of the standard review loop, so counting gate artifacts would trip it on artifact volume rather than real fix rounds.
+Gate-originated artifacts (`oat_review_invocation: gate`) and saved complexity reports are excluded from the same-scope review-cycle cap in `oat-project-review-receive`. The cap measures failed fix cycles of the standard review loop, so counting gate artifacts would trip it on artifact volume rather than real fix rounds.
 
 When a phase is re-gated multiple times, each round produces a distinct review artifact — filenames and `oat_generated_at` are seconds-precision, so rounds never collide and `oat review latest` resolves the newest. An orchestrator should know a gate finished from the `oat --json gate review` result envelope on process exit (`status`, `runId`, `generatedAt`), not by watching the `reviews/` directory or the provider's log; see [Gate completion signal](../../advanced/workflow-gates.md#gate-completion-signal).
 
@@ -226,6 +226,68 @@ Final review `passed` gate requires:
 - Deferred Medium findings resurfaced and explicitly dispositioned.
 - Low findings explicitly dispositioned (after plain-language explanation).
 
+## Complexity review at budget exhaustion
+
+When a review or gate budget runs out, another round of the same review is
+unlikely to converge. Before asking the operator how to proceed, the root
+dispatches one complexity review and shows it together with the reasons the
+loop stopped. The review asks whether the reviewed work, and the machinery the
+findings keep demanding, earns its cost against the contract. It is not
+another correctness review.
+
+It runs at every budget-exhaustion point:
+
+| Exhaustion point                                              | Owning skill                 |
+| ------------------------------------------------------------- | ---------------------------- |
+| Phase review fix rounds reach `oat_orchestration_retry_limit` | `oat-project-implement`      |
+| A phase review gate still blocks at that limit                | `oat-project-implement`      |
+| The final review reaches its three-cycle cap                  | `oat-project-implement`      |
+| The implementation exit gate ends in `block` at `maxAttempts` | `oat-project-implement`      |
+| A review scope reaches the three-cycle cap                    | `oat-project-review-receive` |
+| The quick-start plan gate ends in `block` at `maxAttempts`    | `oat-project-quick-start`    |
+
+A single `prompt` failure, a `warn` outcome, and launch or transport failures
+that consume no attempt are not budget exhaustions. The operator can ask for
+the same review at any other time; there is no automatic early trigger.
+
+How it runs:
+
+- **Probe.** OAT looks for an installed `complexity-review` skill in
+  `~/.agents/skills`, then `~/.claude/skills`, then the repository's
+  `.agents/skills`. When one is found, the reviewer follows it as a document,
+  without asking questions. Otherwise the reviewer follows a condensed method
+  bundled with the lifecycle skills: restate the contract from independent
+  sources, establish the simplest viable baseline, inventory the machinery,
+  apply the deletion test, build a ledger (Item, Claimed value, Evidence,
+  Lifecycle cost, Recommendation), and give a verdict of
+  `Deletion-rule compliant`, `Partially compliant`, or `Not compliant`.
+- **Read-only reviewer.** One reviewer-class subagent at the resolved reviewer
+  ceiling reads the reviewed target, the contract sources (backlog items,
+  discovery, spec, design, and decision records), and every review artifact of
+  the exhausted loop. It writes nothing and returns its report to the root.
+  Outside an implement run (quick-start, or a standalone review-receive), the
+  root loads the project dispatch skills and resolves the reviewer ceiling with
+  `oat project dispatch-ceiling resolve --role reviewer`.
+- **One review per exhausted loop.** A saved report for the scope that is newer
+  than every review artifact of that scope is reused, so re-entering a capped
+  receive does not dispatch a second review.
+- **OAT additions.** The report marks rows only the operator can settle as
+  `REQUIRES-OPERATOR`, classifies each open finding as an accepted
+  requirement, a regression, or new hardening, lists the findings a
+  simplification would dissolve, and recommends a disposition: extra cycles,
+  proceed with override, corrective revision, or **simplify**.
+- **Decision message.** The root saves the report as
+  `reviews/archived/complexity-<scope>-<timestamp>.md` (outside the top-level
+  `reviews/` directory, so routers never mistake it for an unprocessed review,
+  and outside the review-cycle count), shows one decision message with the
+  stop reasons, verdict, dissolvable findings, and operator questions, and
+  records the operator's choice with the report path in `implementation.md`.
+
+Agents never select the disposition, including the recommended one. Under
+`OAT_AUTONOMOUS=1` the run stops at its boundary report, which carries the same
+content. The condensed method adapts the operator's `complexity-review` skill
+from `tkstang/skills`; see `NOTICES.md`.
+
 ## Subagent Compatibility
 
 `oat-project-review-provide` uses provider-aware subagent dispatch when available. This outer dispatch starts the primary `oat-reviewer`; it is separate from any optional reconnaissance workers that the reviewer may launch after resolving its authoritative review scope:

package/assets/docs/workflows/projects/reviews/review-flavors.md

@@ -38,29 +38,36 @@ for the deep review request/receive mechanics.
 
 ## Flow map
 
-```mermaid
-flowchart TD
-  subgraph Planning
-    PL["Planning-phase\nartifact self-review"] --> PLR["Inherit planning parent"]
-    PLR --> PLT["Parent model\n(root already at/above ceiling)"]
-  end
-
-  subgraph Implementation
-    IM["Root-owned phase\nself-review"] --> IMR["Resolve dispatch ceiling"]
-    IMR --> IMPIN["At-ceiling pin\n(ceiling final candidate)"]
-    IMR --> IMINH["Inherit\n(only if dispatcher known at/above ceiling)"]
-    IMR --> IMCLI["Exact CLI reviewer\n(selected pre-launch)"]
-  end
-
-  subgraph Gates
-    PG["Phase review gate\n(external)"] --> PGR["Configured exec target\n(gates.execTargets)"]
-    PGR --> PGT["Separate reviewer CLI\n(prefers another model family;\nfalls back with a warning)"]
-
-    LG["Lifecycle / final gate"] --> LGR["Configured exec target\n(gates.execTargets)"]
-    LGR --> LGT["Separate reviewer CLI\n(never replaced by self-review;\nfalls back with a warning)"]
-    LGT -. may spawn .-> LGN["Nested managed\nreviewer child inside gate"]
-  end
-```
+=== "Diagram"
+
+    ![Review flavors: planning self-review inherits the planning parent; implementation self-review resolves the dispatch ceiling to an at-ceiling pin, inherit, or an exact CLI reviewer; phase and lifecycle gates run a separate reviewer CLI from a configured exec target, and the lifecycle gate's reviewer CLI may spawn a nested reviewer child](/diagrams/review-flavors-light.svg)
+    ![Review flavors: planning self-review inherits the planning parent; implementation self-review resolves the dispatch ceiling to an at-ceiling pin, inherit, or an exact CLI reviewer; phase and lifecycle gates run a separate reviewer CLI from a configured exec target, and the lifecycle gate's reviewer CLI may spawn a nested reviewer child](/diagrams/review-flavors-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart TD
+      subgraph Planning
+        PL["Planning-phase\nartifact self-review"] --> PLR["Inherit planning parent"]
+        PLR --> PLT["Parent model\n(root already at/above ceiling)"]
+      end
+
+      subgraph Implementation
+        IM["Root-owned phase\nself-review"] --> IMR["Resolve dispatch ceiling"]
+        IMR --> IMPIN["At-ceiling pin\n(ceiling final candidate)"]
+        IMR --> IMINH["Inherit\n(only if dispatcher known at/above ceiling)"]
+        IMR --> IMCLI["Exact CLI reviewer\n(selected pre-launch)"]
+      end
+
+      subgraph Gates
+        PG["Phase review gate\n(external)"] --> PGR["Configured exec target\n(gates.execTargets)"]
+        PGR --> PGT["Separate reviewer CLI\n(prefers another model family;\nfalls back with a warning)"]
+
+        LG["Lifecycle / final gate"] --> LGR["Configured exec target\n(gates.execTargets)"]
+        LGR --> LGT["Separate reviewer CLI\n(never replaced by self-review;\nfalls back with a warning)"]
+        LGT -. may spawn .-> LGN["Nested managed\nreviewer child inside gate"]
+      end
+    ```
 
 The dotted branch marks the only flavor that may **spawn a nested managed
 reviewer child** inside the gate exec target: the lifecycle/final gate.

package/assets/docs/workflows/waves/wave-workflows.md

@@ -113,7 +113,9 @@ for your approval before the first wave starts. When the final wave merges,
 the skill stops at one human-gated checkpoint that asks whether to run the
 deferred completion tail (archive, S3 upload, and active-project clear) for
 every wave's wrapper project; autonomous runs never answer that question
-themselves.
+themselves. On yes, it runs `oat-project-complete-auto` once in batch mode;
+a wrapper the companion refuses keeps its deferral, and the report names its
+next step (usually completing it with `oat-project-complete`).
 
 **Example scenario:** Twelve reviewed external plans include a shared API
 foundation, client changes, and independent documentation work. Use `new` to
@@ -173,7 +175,10 @@ closeout it archives the wave's backlog items with `oat backlog archive` and
 runs the configured closeout sequence (which can open the PR). It then stops
 once at a HiLL (human-in-the-loop) approval checkpoint before running the
 `oat-project-complete` process, including project archive and any configured
-S3 upload. After you merge the wave, it resets the working branch, deletes
+S3 upload. Under autonomous execution it runs that process through the
+`oat-project-complete-auto` companion, which needs
+`workflow.autonomousComplete: true` and records a completion-before-merge
+exception for the open wave PR. After you merge the wave, it resets the working branch, deletes
 stale phase branches, and runs `oat-wave-program wave-close`. Merging the wave
 into `main` stays your decision.
 
@@ -192,7 +197,10 @@ presented as proof the integrated tree passes.
 
 Closeout writes end-of-run synthesis before archive work. Autonomous execution
 can defer a wrapper's archive tail to program close only with an explicit
-ledger disposition. That deferral does not satisfy the full completion tail.
+ledger disposition, and only when the companion refuses for a deferrable
+reason (the opt-in is off, the PR precondition is unmet, or a completion
+question has no recorded answer); any other refusal stops closeout at a
+boundary. That deferral does not satisfy the full completion tail.
 Source-plan requirements remain intact even when live drift changes a mechanism.
 
 **Next step:** Follow the wave's reported review and merge boundary. After the

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.3.14",
-  "docs-config": "0.3.14",
-  "docs-theme": "0.3.14",
-  "docs-transforms": "0.3.14"
+  "cli": "0.3.16",
+  "docs-config": "0.3.16",
+  "docs-theme": "0.3.16",
+  "docs-transforms": "0.3.16"
 }

package/assets/skills/oat-project-autonomous/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion, Task
 metadata:
-  version: 1.0.17
+  version: 1.0.18
 ---
 
 # Autonomous OAT Project