@open-agent-toolkit/cli 0.2.2 → 0.2.4

package/assets/agents/oat-reviewer.md

@@ -1,8 +1,8 @@
 ---
 name: oat-reviewer
-version: 1.1.7
+version: 1.1.8
 description: Unified reviewer for OAT projects - mode-aware verification of requirements/design alignment and code quality. Writes a review artifact to disk by default, or returns structured findings in-memory when dispatched in structured-output mode.
-tools: Read, Bash, Grep, Glob, Write
+tools: Read, Bash, Grep, Glob, Write, Task
 color: yellow
 ---
 
@@ -73,6 +73,47 @@ For Codex, deterministic review dispatch under a capped managed policy uses the
 
 For Claude Code, review dispatch is model-axis based and the effort axis is `not-applicable`.
 
+## Bounded Reviewer Reconnaissance
+
+The primary reviewer must establish the authoritative scope before considering delegation. Establish its authoritative commit range and read the mode-required discovery, spec, design, plan, and implementation artifacts that are available before decomposition or delegation. Understand the requirements, changed surfaces, and failure consequences in that authoritative scope before deciding whether lanes are independent. Delegation is optional and useful only when the resolved scope has multiple independent evidence lanes. Eligible broad reviews include final code reviews, broad phase/range reviews, docs sweeps, and provider-view audits. Narrow task or artifact reviews stay inline when coordination would cost as much as direct inspection.
+
+When delegation is eligible:
+
+1. Use one bounded, read-only, non-recursive reconnaissance round with disjoint lane scopes. This is a one-level fan-out limit: lane workers must not spawn additional workers.
+2. Before launching any lane, read `.agents/skills/oat-dispatch-subagents/SKILL.md`, resolve the active provider, and read exactly one matching active-provider reference under `.agents/skills/oat-dispatch-subagents/references/`. Reviewer-local reconnaissance must not read or load `.agents/skills/oat-project-dispatch-subagents/SKILL.md`; that adapter is reserved for project lifecycle phase/task policy.
+3. Map every lane worker to the shared `recon` role class (`role.class: recon`); role authority stays read-only and advisory. Assign the independent `task_class`, `classification_source: caller`, and non-empty `classification_reason` fields after understanding the artifacts and diff. These task-class fields are required for reviewer-local reconnaissance even though the generic dispatch contract keeps them optional for other callers.
+4. Classify each lane as `mechanical-recon`, `intelligent-recon`, `default-implementation`, `hard-reasoning`, or `consequential`. Use the stronger floor when uncertain. Classification proceeds from deterministic verification to silent-miss risk, then dispersed context, ambiguity, and consequence; file count alone never justifies escalation.
+   - `mechanical-recon`: deterministic inventories, parity checks, and test/lint/format/build execution whose misses are visible and cheaply checked.
+   - `intelligent-recon`: interpretation, semantic completeness, policy-aware auditing, or unfamiliar-code review where a miss could be silent.
+   - `default-implementation`: rare, independently bounded dossier work that must retain and reconcile dispersed context; prefer keeping it with the root.
+   - `hard-reasoning`: ambiguity, novelty, architecture analysis, or competing interpretations dominate.
+   - `consequential`: security, release safety, irreversible impact, or expensive failure dominates.
+
+   Mechanical workers may execute checks and report exact output, but interpretation and policy judgment require stronger classes or stay with the root reviewer.
+
+5. The generic dispatch contract owns capability, catalog, model, effort, route, authorization, launch evidence, class-floor selection, and floor-satisfaction evidence. It applies active user and repository instructions, the active-provider reference, the live nested catalog, and the supplied policy/ceiling. Select an explicit target meeting the declared floor; never silently inherit the primary reviewer's model and never hard-code provider model names. Prefer a cheaper/faster worker only when the host reliably exposes that control and the target still satisfies the floor.
+6. Give each lane an exact scope and a compact return contract: coverage, checks performed, exact `file:line` evidence, gaps, and explicit uncertainty. Reports are advisory candidate observations, not accepted findings.
+7. Workers must not mutate files, emit final findings, assign severity, make validation decisions, write review artifacts or `StructuredFindings`, or otherwise write either output sink.
+
+Lanes may share one homogeneous dispatch wave only when every existing dispatch axis, `task_class`, and `model_class_floor` match. Mixed task classes require separate records and waves. The one-level fan-out limit applies across all waves.
+
+When delegated reconnaissance is attempted, artifact mode must include a
+compact `## Review Orchestration` section. Record the waves, task classes,
+classification rationale, selected targets, acceptance and outcomes, floor
+satisfaction, fallback, and primary reconciliation. Condense the dispatch
+evidence instead of copying every worker record. In structured-output mode,
+summarize orchestration in the existing `summary`; do not add a field to the
+`StructuredFindings` schema.
+
+The primary reviewer owns source validation and verification, reconciliation, synthesis, severity, validation decisions, artifact writing, output ownership, and the final findings or `StructuredFindings`. Reopen authoritative sources and directly re-verify every load-bearing positive and negative claim; repeat relevant searches for absence claims before promotion to a finding. Reconcile overlap, disagreement, and cross-lane gaps across task classes before deduplicating and assigning severity.
+
+Capability-check reviewer-local delegation once. A reviewer-local request must use `fallback.mode: caller-inline` and `allow_below_task_class_floor: false`. If the requested floor cannot be explicitly satisfied, record it as unsatisfied, do not launch a below-floor worker, and cover the affected lane inline without weakening review coverage, the checklist, or the output contract. The same inline fallback applies when nested dispatch is unsupported, unauthorized, failed, empty, or malformed. The inline and delegated paths preserve the existing artifact-mode, gate-parsing, and structured-output schemas unchanged.
+
+The primary reviewer and lane workers must not write or modify
+`project-log.md` and must not invoke `oat project log append`. The root project
+workflow validates review orchestration evidence and owns any structural log
+entry.
+
 ## Mode Contract
 
 Use workflow mode to determine required evidence:
@@ -338,6 +379,17 @@ oat_invocation_source: { exec-target-config|unknown }
 
 Findings: {N} critical, {N} important, {N} medium, {N} minor
 
+## Review Orchestration
+
+{Include this section only when delegated reconnaissance was attempted.}
+
+| Wave | Task class | Classification rationale | Selected target  | Acceptance / outcome | Floor satisfaction | Fallback |
+| ---- | ---------- | ------------------------ | ---------------- | -------------------- | ------------------ | -------- |
+| {id} | {class}    | {reason}                 | {target or none} | {status / outcome}   | {status}           | {route}  |
+
+**Primary reconciliation:** {independent verification, accepted/rejected
+worker claims, and root-inline coverage}
+
 ## Findings
 
 ### Critical
@@ -414,6 +466,9 @@ For gate-originated artifacts, all six gate-only fields are required when the pr
 **Artifact mode only.** In structured-output mode (`oat_output_mode: structured`), return the `StructuredFindings` object instead — see **Structured-Output Mode** below.
 
 Return a brief confirmation. DO NOT include full review contents.
+Return exactly one reconnaissance status line using only `attempted` or
+`not-attempted`; this signal reports whether delegated reconnaissance was
+attempted, including an attempted launch that fell back or failed.
 
 Format:
 ```
@@ -423,6 +478,7 @@ Format:
 **Scope:** {scope}
 **Findings:** {N} critical, {N} important, {N} medium, {N} minor
 **Review artifact:** {path}
+**Reconnaissance:** {attempted | not-attempted}
 
 Return to your main session and run the `oat-project-review-receive` skill.
 
@@ -439,7 +495,7 @@ When the dispatch payload sets `oat_output_mode: structured`, the output sink ch
 
 ```typescript
 interface StructuredFindings {
-  summary: string; // 2-3 sentence review summary
+  summary: string; // 2-3 sentence review summary; include compact orchestration when reconnaissance was attempted
   findings: Array<{
     id: string; // C1, I1, M1, m1 — stable per dispatch (C/I/M/m prefix matches the severity model)
     severity: 'critical' | 'important' | 'medium' | 'minor';

package/assets/docs/cli-utilities/project-log.md

@@ -93,6 +93,22 @@ 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.
+- When `oat-project-implement` or `oat-project-review-provide` receives an
+  artifact-mode review, the root workflow first consumes exactly one
+  `**Reconnaissance:** attempted` or
+  `**Reconnaissance:** not-attempted` signal from the reviewer's brief
+  confirmation. A missing, duplicate, or invalid signal fails closed before
+  artifact validation or bookkeeping.
+  - `attempted` requires a complete `Review Orchestration` section recording
+    waves, task classes, classification rationale, selected targets,
+    acceptance and outcomes, floor satisfaction, fallback, and primary
+    reconciliation. The root then invokes `oat project log append` exactly once
+    for one structural entry referencing the review artifact instead of copying
+    worker records.
+  - `not-attempted` forbids a `Review Orchestration` section and does not invoke
+    `oat project log append` for review orchestration.
+    Reviewers and reconnaissance workers never write `project-log.md`
+    themselves.
 - `oat gate review` records exactly one entry for every terminal outcome,
   including successful and blocking verdicts, child failure, timeout,
   targeting-correlation failure, and artifact-validation failure. A log append

package/assets/docs/cli-utilities/workflow-gates.md

@@ -33,7 +33,7 @@ Gate config lives under `workflow.gates.skills` and is keyed by skill name.
     "gates": {
       "skills": {
         "oat-project-implement": {
-          "command": "oat gate review --project \"$PROJECT_PATH\" --review-type code --review-scope final \"Use oat-project-review-provide code final for the declared project\"",
+          "command": "oat --json gate review --project \"$PROJECT_PATH\" --review-type code --review-scope final \"Use oat-project-review-provide code final for the declared project\"",
           "description": "Run a fresh-runtime final review before implementation is considered done.",
           "onFailure": "block",
           "maxAttempts": 2
@@ -57,6 +57,52 @@ in skill frontmatter with `oat_gateable: true`, and
 `oat internal validate-oat-skills` warns when config targets a missing or
 non-gateable skill.
 
+### Implementation exit-gate closeout
+
+For `oat-project-implement`, the configured skill gate is a final, resumable
+closeout boundary. It is independent from the root-owned phase reviews, the
+mandatory final lifecycle review, and the optional `oat_phase_review_gate`.
+Passing or disabling one of those mechanisms never satisfies or disables the
+configured implementation gate.
+
+After final verification and the mandatory final lifecycle review pass, OAT
+persists `oat_implement_exit_gate` in project state before it launches the
+configured command. The state records:
+
+- `pending`, `allowed`, `blocked`, or `stale` status;
+- a `configured` or `no_gate` resolution;
+- `passed`, `warned`, `prompt_approved`, or `no_gate` allowed dispositions;
+- the resolved configuration fingerprint, reviewed HEAD, implementation
+  fingerprint, gate run, envelope, and receive provenance; and
+- launch and receive reconciliation data needed to resume without duplicating
+  an accepted run or completed receive.
+
+A `null` resolution is explicit success for that closeout generation:
+`allowed/no_gate` with `disposition: no_gate`. Configured success becomes
+`allowed/passed`; `warn` and an explicit `prompt` continuation persist their
+own allowed dispositions only for a validated, receive-eligible `blocked`
+envelope after eligible receive completes durably. Unresolved, malformed,
+contradictory, validation, correlation, launch, or receive failures ignore
+`onFailure` and remain blocked.
+
+Resume correlates the persisted launch intent with the gate run marker, durable
+JSON result receipt, and run-bound artifact. Eligible receive similarly
+correlates the source and archived artifact, Reviews event, and bookkeeping
+commit. Missing or ambiguous evidence fails closed instead of launching or
+receiving again.
+
+An allowed result remains fresh only while every commit after `reviewed_head`
+contains recognized closeout-only work, such as gate receipts, project
+tracking, summary/documentation/PR sequencing, final HiLL, or completion
+bookkeeping. Implementation, test, skill, template, workflow configuration, or
+unknown changed paths make the result stale and require a current final review
+and a new gate generation.
+
+Only an artifact with `oat_review_invocation: gate` and the matching
+`oat_gate_run_id` can satisfy configured-gate provenance. A normal final
+review, phase review, or manually produced independent review cannot substitute
+for it.
+
 ## Review gates
 
 `oat gate review` is intentionally stateful. It is equivalent to running
@@ -424,7 +470,7 @@ Set or clear a skill gate:
 
 ```bash
 oat gate set oat-project-implement \
-  --command 'oat gate review --project "$PROJECT_PATH" --review-type code --review-scope final "Use oat-project-review-provide code final for the declared project"' \
+  --command 'oat --json gate review --project "$PROJECT_PATH" --review-type code --review-scope final "Use oat-project-review-provide code final for the declared project"' \
   --description "Run final review in another runtime" \
   --on-failure block \
   --max-attempts 2 \
@@ -441,17 +487,18 @@ unset lets the dispatcher avoid the current runtime and choose the
 highest-priority available non-host target. Pin a target only for manual
 dispatch, debugging, or a deliberate local/user-specific override.
 
-### Migrate ambient lifecycle commands
+### Migrate legacy lifecycle commands
 
 Older user-level lifecycle commands often asked a reviewer to inspect the
-"current project" but omitted a machine-readable declaration. Migrate each
-stored `oat gate review` command by inserting `--project "$PROJECT_PATH"` and
-retaining provider-neutral target selection. For example:
+"current project", omitted a machine-readable project declaration, or emitted
+human-oriented output. Migrate each stored command to the canonical global-JSON
+shape `oat --json gate review --project "$PROJECT_PATH" ...` while retaining
+provider-neutral target selection. For example:
 
 ```bash
 export PROJECT_PATH
 oat gate set oat-project-implement \
-  --command 'oat gate review --project "$PROJECT_PATH" --review-type code --review-scope final "Use oat-project-review-provide code final for the declared project"' \
+  --command 'oat --json gate review --project "$PROJECT_PATH" --review-type code --review-scope final "Use oat-project-review-provide code final for the declared project"' \
   --description "Run final review in another runtime" \
   --on-failure block \
   --max-attempts 2 \
@@ -463,6 +510,12 @@ Apply the same command shape to `oat-project-plan`,
 skills have configured review gates. Do not add `--target`; explicit targets
 remain manual/debug or deliberate local/user-specific overrides.
 
+Implementation closeout rejects a stored review command without global
+`--json`, without `--project "$PROJECT_PATH"`, or with a shared `--target`
+before launch. It does not rewrite configuration or inject, reorder, or append
+arguments while executing. Migrate the declaration first; otherwise the
+project remains blocked and resumable through `oat-project-implement`.
+
 Set or clear an exec target:
 
 ```bash
@@ -589,7 +642,9 @@ contributor fields are absent. The achieved level is one of:
 
 ## Failure behavior
 
-Gate failure behavior is owned by the gate-aware skill:
+Gate failure behavior is owned by the gate-aware skill. The configured policy
+applies only to a validated, receive-eligible `blocked` result after its
+eligible receive completes durably:
 
 | `onFailure` | Meaning                                                                              |
 | ----------- | ------------------------------------------------------------------------------------ |
@@ -597,6 +652,12 @@ Gate failure behavior is owned by the gate-aware skill:
 | `prompt`    | Surface the failure and ask the user how to proceed.                                 |
 | `warn`      | Record the failure and continue.                                                     |
 
+`review_failed`, `artifact_validation_failed`,
+`targeting_correlation_failed`, unknown or contradictory envelopes, launch
+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.
+
 `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.

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

@@ -84,6 +84,9 @@ Autonomous execution preserves independent review:
   bounded implement-and-re-review loop.
 - Critical findings and failed blocking reviews stop progression. Important
   findings follow the configured gate policy.
+- A normal phase or final lifecycle review cannot satisfy a configured
+  implementation exit gate. Only gate invocation provenance with the matching
+  run ID can authorize that boundary.
 
 Project review artifacts and review rows reference launcher-owned dispatch
 records. The configured invocation is authoritative evidence; child
@@ -104,12 +107,23 @@ An existing valid explicit list is preserved. An existing `[]` is also
 preserved and means every phase, never no phases. At each configured checkpoint,
 autonomy runs and receives the review without waiting.
 
-At final closeout, pre-approval lifecycle steps run first. After a passing final
-review, autonomy records final HiLL approval and then runs post-approval steps.
-A failed blocking review stops before approval. The default autonomous tail is
-summary, documentation, and final PR when no post-implementation sequence is
-configured; stored legacy or structured sequences retain their documented
-meaning.
+At final closeout, autonomy follows the same authoritative order as an
+interactive run: final verification, mandatory final lifecycle review,
+configured implementation exit gate, pre-approval sequence, final HiLL
+approval, post-approval sequence, then implementation completion and success
+output. A null gate resolution persists an explicit no-gate allowance before
+the sequence starts.
+
+Autonomy does not turn an ordinary independent review into configured-gate
+provenance. A configured review must produce a gate-originated artifact with
+the matching run ID, and eligible receive must be durably reconciled. Blocked,
+ambiguous, malformed, or stale gate state is a boundary stop: the run remains
+resumable through `oat-project-implement` and cannot continue to approval,
+completion, or output.
+
+The default autonomous tail is summary, documentation, and final PR when no
+post-implementation sequence is configured; stored legacy or structured
+sequences retain their documented meaning.
 
 ## Execution-learnings loop
 

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

@@ -20,6 +20,9 @@ and updates project state.
   phase report.
 - **Fix boundary:** blocking findings return to the original phase handle when
   possible.
+- **Final exit-gate boundary:** after final verification and final lifecycle
+  review, the root resolves the configured implementation gate before
+  approval-aware sequencing, final HiLL, completion, or success output.
 - **Optional nesting:** a phase agent may dispatch bounded recon, fanout, or
   specialist work when that materially helps. Ordinary tasks do not require a
   third tier.
@@ -84,6 +87,49 @@ commit range, task IDs and boundaries, project artifacts, and verification
 evidence. The review passes with zero Critical and zero Important findings.
 Medium and Minor findings are recorded without blocking the phase.
 
+## Final Exit-Gate Boundary
+
+After every planned phase and review round finishes, the project root runs final
+verification and the mandatory final lifecycle review. It then resolves
+`workflow.gates.skills.oat-project-implement` and persists the result in
+`oat_implement_exit_gate`. This configured gate is separate from the phase
+reviewer, final lifecycle reviewer, and optional phase gate; none can substitute
+for another.
+
+Resolution and policy outcomes are explicit:
+
+- A null resolution persists `allowed/no_gate` for the current implementation
+  basis.
+- A configured passing review persists `allowed/passed` after any eligible
+  review receive is durably completed.
+- `warn` persists `allowed/warned`; `prompt` proceeds only after explicit
+  approval persists `allowed/prompt_approved`.
+- `block`, an unresolved prompt, invalid or contradictory output, and
+  operational or receive failures remain blocked. Remediation retries follow
+  the persisted `maxAttempts` policy.
+
+Gate execution is resumable across both launch and receive. Before launch, OAT
+persists an attempt ID, start time, and result-receipt path. It correlates those
+with the gate run marker, structured envelope, and run-bound artifact before it
+accepts a result or relaunches. Before receive, it persists the handoff and
+source/archive correlation; resume verifies the archived artifact, Reviews
+event, and bookkeeping commit before marking receive complete. Missing,
+contradictory, or ambiguous correlation fails closed. A valid accepted run or
+completed receive is never duplicated.
+
+Freshness is bound to the reviewed HEAD and an implementation fingerprint.
+Recognized closeout-only descendants preserve a valid result: gate artifacts
+and receipts, project tracking and project-log appends,
+summary/documentation/PR sequence outputs, final HiLL bookkeeping, and
+completion bookkeeping. An implementation, test, skill, template, workflow
+configuration, or unknown path change is substantive. It makes the gate result
+stale, requires a current final lifecycle review for the new basis, and starts
+a new gate generation.
+
+Only an allowed and fresh gate disposition can enter the pre-approval sequence,
+cross final HiLL, run the post-approval sequence, mark implementation complete,
+or emit success.
+
 ## Phase Scope
 
 The root supplies one scope for the whole phase:

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

@@ -44,7 +44,23 @@ flowchart LR
 
 ## Post-implementation flow
 
-After implementation and final review pass:
+Implementation closeout has one authoritative order:
+
+1. Run final implementation verification.
+2. Pass the mandatory final lifecycle review.
+3. Resolve and disposition the configured `oat-project-implement` exit gate.
+4. Run the configured pre-approval sequence.
+5. Record final HiLL approval when the final phase is a checkpoint.
+6. Run the configured post-approval sequence.
+7. Mark implementation complete and emit the implementation success output.
+
+The configured exit gate is independent from the mandatory lifecycle review,
+root-owned phase reviews, and optional `oat_phase_review_gate`. It must reach an
+allowed and fresh disposition before pre-approval work starts. A null
+configuration is recorded explicitly as `allowed/no_gate`; it is not inferred
+from missing state.
+
+After implementation closeout finishes:
 
 1. **Summary** (`oat-project-summary`) — generates `summary.md` as institutional memory from project artifacts; PR-final and completion will auto-refresh it if you have not already run it or if it is stale
 2. **Documentation** (`oat-project-document`) — optional sync of project docs; now uses the shared `tools.project-management` config signal to decide whether repo-reference refresh should run before docs analysis, and should recommend new docs pages/directories when the shipped work introduces a capability area that the docs app does not already cover
@@ -87,11 +103,18 @@ This distinction matters during completion: `oat-project-complete` can skip the
 ### Approval-aware post-implementation sequencing
 
 `workflow.postImplementSequence` can use the legacy string values or a structured
-`{ preApproval, postApproval }` value. After the final review passes, OAT
-snapshots the effective sequence, runs ordered pre-approval steps, records final
-HiLL approval, and only then runs post-approval steps. The snapshot is
-restart-safe: an incomplete sequence routes back to implementation and resumes
-from its first incomplete step.
+`{ preApproval, postApproval }` value. After final verification, final review,
+and an allowed, fresh implementation exit-gate disposition, OAT snapshots the
+effective sequence, runs ordered pre-approval steps, records final HiLL
+approval, and only then runs post-approval steps. The snapshot is restart-safe:
+an incomplete sequence routes back to implementation and resumes from its first
+incomplete step.
+
+`oat-project-next` checks `oat_implement_exit_gate` before every normal
+post-implementation route. Missing, pending, blocked, malformed, or stale state
+routes back to `oat-project-implement` even when `oat_phase_status` is
+`complete` or `pr_open`. Only an allowed, fresh disposition can continue to
+summary, documentation, PR, or project completion.
 
 When `workflow.autoReviewAtHillCheckpoints` is enabled or `plan.md` frontmatter sets `oat_auto_review_at_hill_checkpoints`, completing a HiLL checkpoint automatically runs the extra lifecycle review scoped to every implementation phase not already covered by a passed whole-phase code review, through the just-completed checkpoint. Mid-implementation multi-phase reviews use inclusive phase-range scopes such as `p02-p03`; the final implementation checkpoint uses `code final`. The review uses auto-disposition mode (minors auto-converted to fix tasks, no user prompts). Disabled by default. Legacy `autoReviewAtCheckpoints` and `oat_auto_review_at_checkpoints` are still read as fallbacks. This does not control Tier 1 per-phase `oat-reviewer` gates.
 

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

@@ -216,7 +216,7 @@ Final review `passed` gate requires:
 
 ## Subagent Compatibility
 
-`oat-project-review-provide` uses provider-aware subagent dispatch when available:
+`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:
 
 - Claude Code: dispatch `oat-reviewer` with `subagent_type` (resolved from `.claude/agents/oat-reviewer.md`).
 - Cursor: dispatch `oat-reviewer` via explicit `/oat-reviewer` invocation or natural mention (resolved from `.cursor/agents/oat-reviewer.md`; `.claude/agents/oat-reviewer.md` is also supported for compatibility).
@@ -246,6 +246,93 @@ Final review `passed` gate requires:
   fallback). This generic fallback does not override managed exact-target
   rules: a managed reviewer that cannot be launched exactly blocks the review.
 
+### Reviewer-local reconnaissance
+
+After the outer dispatch, the primary reviewer may use reviewer-local workers
+when a broad review has multiple independent evidence lanes. Examples include
+final code reviews, broad phase or phase-range reviews, documentation sweeps,
+and provider-view audits. Running disjoint searches concurrently can reduce
+wall-clock review time, and matching each lane to the least expensive model
+class that can safely do the work can reduce cost. The primary reviewer first
+reads the authoritative diff and the workflow-required discovery, spec,
+design, plan, and implementation artifacts. It decides lane boundaries and
+task classes only after understanding the changed surfaces, requirements, and
+failure consequences. Narrow task and artifact reviews remain inline when
+coordination would cost as much as direct inspection.
+
+Worker authority and model capability are independent. Every reviewer-local
+worker keeps the read-only, advisory `recon` role class. The lane's separate
+task class sets its minimum model-capability floor:
+
+- **Mechanical recon** covers deterministic inventories, exact parity checks,
+  and test, lint, format, or build execution whose results are cheaply
+  verifiable.
+- **Intelligent recon** covers semantic interpretation, unfamiliar-code
+  auditing, and other evidence where a miss could be silent.
+- **Stronger bounded analysis** is reserved for independently scoped work where
+  dispersed context, ambiguity, security, release safety, irreversible impact,
+  or expensive failure warrants a higher floor.
+
+File count alone does not justify escalation. Interpretation and policy
+judgment either use an adequate stronger class or remain with the primary
+reviewer. Active user and repository instructions, the active-provider
+guidance, and the live nested catalog resolve current model examples; the
+canonical reviewer does not promise named models.
+
+Reviewer-local fan-out is limited to one bounded, read-only, non-recursive
+round. Each worker receives a disjoint scope, cannot modify files or spawn more
+workers, and returns a compact advisory report containing:
+
+- coverage and checks performed;
+- exact `file:line` evidence;
+- gaps in the assigned scope; and
+- explicit uncertainty, including uncertainty about absence claims.
+
+Before launching these lanes, the reviewer loads the generic
+`oat-dispatch-subagents` contract and exactly one active-provider reference.
+That shared contract owns nested capability checks, worker catalog resolution,
+model and effort selection, routing, authorization, launch evidence, and
+provider-specific mechanics. It records each lane's task class, model-class
+floor, classification rationale, and floor satisfaction without assuming that
+workers inherit the primary reviewer's target. Lanes may share one wave only
+when their task classes, model floors, and all other dispatch axes match;
+mixed-class reviews use separate waves and records.
+
+This generic reviewer-local use is distinct from
+`oat-project-dispatch-subagents`, which is reserved for OAT lifecycle phase and
+task dispatch policy. Reviewer-local lanes do not load or depend on that
+lifecycle adapter.
+
+Worker reports are candidate observations, not findings. The primary reviewer
+reopens authoritative sources, verifies load-bearing positive and negative
+claims, reconciles overlap and disagreement, fills cross-lane gaps, performs
+synthesis, assigns severity, decides validation, and alone writes the review
+artifact or final `StructuredFindings`.
+
+When the reviewer attempts delegated reconnaissance, the review artifact
+includes a compact `Review Orchestration` section. It records each wave's task
+class and classification rationale, selected target, acceptance and outcome,
+floor satisfaction, fallback, and the primary reviewer's reconciliation. The
+section is the detailed evidence source; it does not copy every internal worker
+record. Structured-output reviews keep the existing schema and summarize the
+same orchestration evidence in `summary`.
+
+The reviewer and its workers never write `project-log.md`. After validating the
+artifact, the root project implementation or review workflow uses
+`oat project log append` to add one concise structural entry that references
+the artifact. Logging remains capability-gated by the CLI helper, so disabled
+project logging requires no reviewer-side branch or write authority.
+
+If nested workers are unsupported, unauthorized, fail, or return empty or
+malformed reports, the primary reviewer covers those lanes inline. It also
+stays inline when the host cannot explicitly satisfy a lane's model-class
+floor. Fallback never selects below the declared floor. It preserves the same
+checklist, verification depth, severity policy, and final output contract; it
+does not promise provider behavior or silently inherit the primary reviewer's
+model. Workers remain advisory and non-recursive regardless of task class, and
+the primary reviewer keeps final verification, reconciliation, severity,
+validation decisions, and output ownership.
+
 ## Reference artifacts
 
 - `.oat/projects/<scope>/<project>/plan.md` (`## Reviews`)

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.2.2",
-  "docs-config": "0.2.2",
-  "docs-theme": "0.2.2",
-  "docs-transforms": "0.2.2"
+  "cli": "0.2.4",
+  "docs-config": "0.2.4",
+  "docs-theme": "0.2.4",
+  "docs-transforms": "0.2.4"
 }