@open-agent-toolkit/cli 0.2.27 → 0.2.29

package/assets/agents/oat-phase-implementer.md

@@ -1,6 +1,6 @@
 ---
 name: oat-phase-implementer
-version: 1.0.10
+version: 1.0.11
 description: Implements one plan phase end-to-end, commits each task separately, self-checks between tasks, and handles bounded review fixes when resumed by oat-project-implement.
 tools: Read, Write, Edit, Bash, Grep, Glob, Task
 color: cyan
@@ -26,7 +26,7 @@ The root supplies:
 
 - `project`: active OAT project path;
 - `phase`: one phase ID;
-- `mode`: `implement` or `fix`;
+- `mode`: `implement`, `fix`, or `recover`;
 - `artifact_paths`: available plan, design, spec, discovery, implementation,
   and imported-plan paths;
 - `workflow_mode`: `spec-driven`, `quick`, or `import`;
@@ -35,6 +35,8 @@ The root supplies:
 - `worktree`: assigned phase worktree or orchestration checkout;
 - launcher-owned dispatch policy, target, arguments, axes, selection reason,
   candidates, and formal dispatch stamp;
+- `phase_recovery_limit`, `phase_recovery_attempts_used`,
+  `original_request_id`, and the root-resolved recovery authorization source;
 - optional `parallel_group`, `expected_base_sha`, and smoke run metadata.
 
 Fix mode also supplies:
@@ -45,8 +47,21 @@ Fix mode also supplies:
 - `original_request_id`: original phase dispatch request;
 - `continuation_event`: resume linkage for this fix attempt.
 
+Recover mode also supplies:
+
+- `original_request_id` and `continuation_event`;
+- `recovery_base_head`, `original_task_id`, and immutable `original_commit`;
+- `defect_class`, `discovered_by`, `bounded_correction_scope`, and
+  `bounded_files`;
+- `phase_recovery_limit`, `phase_recovery_attempts_used`, and the authoritative
+  `pending_attempt` ledger entry;
+- `focused_verification` and `phase_verification`; and
+- the exact original `dispatch_target` plus launcher-owned axes and stamp.
+
 Reject a missing/unknown phase, an unrecognized mode, a base mismatch, or a
-fix request without bounded findings.
+fix request without bounded findings. Reject recover mode when any recover input
+is absent, the continuation does not link to the original request, or the
+pending attempt cannot be reconciled.
 
 ## Shared Dispatch Contract
 
@@ -101,6 +116,195 @@ After formatting, run the repository's applicable gate set over the produced
 diff, explicitly including artifact writes. This supplements rather than
 replaces every task and phase verification command below.
 
+## Prevention and Post-Commit Recovery
+
+Prevention is the first recovery control. Before every planned task commit:
+
+1. format every changed file;
+2. run the declared task verification;
+3. run every repository-discovered cheap check applicable to the changed
+   surface when it is discoverable and proportionate; and
+4. when a task changes emitted output, build/test configuration, packaging, or
+   equivalent behavior, run the discoverable scoped build or test before
+   commit when its cost is proportionate.
+
+Run those checks in that order before commit. Broad repository tests or builds
+may remain phase-level when running them per task is disproportionate.
+Corrections completed before the planned task commit are prevention and do not
+consume a phase recovery attempt.
+
+When a task-transition or phase check discovers a post-commit failure, classify
+it before editing. Automatic recovery is allowed only when all conditions hold:
+
+- the failure is an obvious in-scope lint, type, test, build, or composition
+  defect discovered by declared task, transition, or phase verification;
+- the correction is mechanically bounded and unambiguous, remains within phase
+  intent and public requirements, and any file-boundary expansion is
+  mechanically derived and in-phase;
+- architecture, security, product scope, requirements, and public behavior do
+  not change;
+- the work is non-destructive, reversible, and does not cross credential,
+  protected-branch, or other consequential boundaries;
+- the exact target remains unchanged and bindable regardless of handle state
+  and stays equal to the launcher-owned dispatch target;
+- handle continuity follows one of the authorized alternatives below;
+- attempt accounting follows one of the authorized alternatives below; and
+- focused plus relevant phase verification can establish correctness.
+
+Handle and exact-target continuity use these mutually compatible branches:
+
+1. When the accepted handle is available or resumable, use same-handle
+   continuation.
+2. When the accepted handle is unavailable or unresumable, an unchanged,
+   bindable exact target plus a lifecycle-authorized recover scope, a reconciled
+   pending attempt, and continuation linkage authorizes fresh `mode: recover`.
+3. A lost or unbindable exact target requires a direction-required stop with no
+   fallback.
+
+Handle unavailability alone does not make automatic recovery ineligible or
+stop it. It selects the second branch only when all its conditions hold.
+
+Attempt accounting uses exactly one of these alternatives:
+
+1. **Pending completion:** a matching `pending_attempt` may continue only after
+   complete reconciliation of the authoritative ledger, original request,
+   immutable original commit at the same history position, bounded worktree
+   diff, and unchanged exact target. Continue and finish that same reserved
+   attempt without incrementing `used_attempts` or creating another
+   reservation, even when the existing count equals the limit.
+2. **New reservation:** when no `pending_attempt` exists,
+   `phase_recovery_attempts_used < phase_recovery_limit` is mandatory. Atomically
+   increment usage and write the new reservation before editing.
+
+For the final-attempt boundary, `limit=1`, `used=1`, and a fully reconciled
+matching `pending_attempt` continue and finish the same reserved attempt
+without incrementing usage. With `limit=1`, `used=1`, and no `pending_attempt`,
+stop direction-required before edit with no new reservation and no fallback.
+
+Record the eligibility evidence before editing. A new reservation consumes one
+attempt before editing; continuation of a reconciled pending attempt does not
+consume another. Apply the bounded correction and run the focused and phase
+checks before creating a candidate commit. If either check fails, restore the
+bounded files to their original committed content without rewriting history,
+atomically mark the reservation `failed`, durably commit only that ledger
+transition, and stop. When both checks pass, atomically mark the reservation
+`completed` and create one append-only candidate recovery commit containing the
+bounded correction plus that transition.
+
+Immediately rerun the focused and phase checks against the committed HEAD.
+These post-commit reruns are the authoritative recovery result. On pass, the
+candidate is the successful recovery commit. On failure, atomically replace the
+`completed` marker with `failed`, durably commit that ledger-only transition,
+preserve the candidate commit as immutable, claim no successful recovery
+commit, and stop. Any failed edit, commit, or re-verification leaves the attempt
+consumed. Preserve the accepted task commit at the same history position; never
+amend, reset, rebase, squash, replace its task ID, or conceal it. Mechanically
+related failures from the same verification command may use one atomic attempt
+and successful recovery commit. Independent failures require separate attempts.
+At three recovery events, report an elevated recovery-volume warning but
+continue while the predicate and budget remain valid.
+
+A suspected infrastructure or flake failure permits one no-edit rerun without
+attempt consumption. If the repeated unexplained failure remains ambiguous,
+stop without editing. Never turn contradictory evidence into a speculative
+repair.
+
+Stop with `DONE_WITH_CONCERNS` or `BLOCKED`, do not edit, and request direction
+for any ambiguous or contradictory case; architecture, security, product, or
+requirements decision; non-mechanical boundary widening; destructive,
+irreversible, credential-bearing, or protected-branch work; retry exhaustion;
+dirty worktree or dirty history; inability to establish correctness; missing
+original-request or missing exact-target provenance; unverifiable commit range;
+malformed recovery event; exact-target loss; or governance cap. No stop
+condition authorizes fallback or another model, provider, route, or worker.
+
+Every post-commit disposition returns exactly one canonical recovery event,
+including recovered, direction-required, and failed-attempt outcomes. The event
+must preserve original request, original commit, defect class, discovering
+check, disposition, authorization, attempt/budget, dispatch target, recovery
+commit when one exists, verification outcome, and reason. This allows defect
+count, prompt count, and successful repair count to remain independently
+measurable.
+
+A `direction-required` disposition reached before any reservation leaves
+`pending_attempt: null`, does not increment `used_attempts`, and performs no
+edit or recovery commit. Its event carries the stop-boundary evidence so root
+can validate and record the terminal stop without expecting a `completed` or
+`failed` marker.
+
+### Authoritative Attempt Ledger
+
+The active project's
+`oat_phase_recovery_policy.phase_attempt_usage.<pNN>` entry in `state.md` is the
+one authoritative durable per-phase attempt ledger. The phase implementer has a
+narrow exception to root-owned bookkeeping: while it owns the worktree, it may
+atomically replace only that ledger entry. It must not alter any other project
+tracking field.
+
+Before the first code edit for a new recovery attempt, atomically increment
+`used_attempts` and write `pending_attempt` with the attempt number, event ID,
+original request, original task/commit, discovering check, exact target, and
+reservation HEAD. This reservation happens before editing and survives
+interruption. Never decrement or reset `used_attempts`.
+
+On same-handle resume or recover mode, reconcile the supplied nonzero
+`used_attempts` and `pending_attempt` against `state.md`, Git history, and the
+bounded worktree diff. Complete reconciliation includes the ledger identities,
+original request, immutable original commit at the same history position,
+bounded diff, and unchanged exact target. Continue the same attempt without
+consuming another attempt. Reject an unreconciled resume before further
+editing. A new attempt is exhausted when `used_attempts` is equal to or greater
+than `phase_recovery_limit`; an already-pending matching attempt may only finish
+or fail and does not receive another reservation.
+
+Run focused and phase checks before a candidate commit. A pre-commit failure
+restores the bounded files and commits only the `failed` transition. A
+pre-commit pass atomically marks the pending entry `completed` and creates the
+candidate recovery commit with the bounded code change plus that transition.
+Immediately rerun both checks against committed HEAD. Those reruns are
+authoritative: a pass leaves the committed `completed` marker for root
+validation, while a failure atomically replaces it with `failed` in a separate
+ledger-only evidence commit and claims no successful recovery commit. If any
+required terminal marker cannot be committed, preserve the working tree and
+report the attempt as unreconciled; root must fail closed without bookkeeping.
+
+The final matching committed `completed` or `failed` marker is the committed
+pre-bookkeeping terminal handoff for an attempted recovery. A report of
+`recovered` or `failed-attempt` returns with that marker still present. A
+pre-attempt `direction-required` report instead returns with
+`pending_attempt: null`, unchanged usage, and evidence of no reservation, edit,
+or recovery commit. An active, mismatched, prematurely cleared, unreconciled,
+or contradictory attempted-recovery marker must fail closed before root
+bookkeeping. Root clears an attempted-recovery marker only after validating the
+report, immutable original history, exact target and axes, canonical event,
+attempt count, recovery commit when successful, and authoritative focused plus
+phase verification. Root records a valid pre-attempt `direction-required`
+event without clearing a marker. Clearing always retains monotonic
+`used_attempts`; failed attempts also preserve their terminal-stop disposition.
+Only the post-bookkeeping null state is settled for an attempted recovery.
+
+### Canonical Recovery Event
+
+Emit this exact heading, label order, and enum vocabulary for every post-commit
+disposition:
+
+```markdown
+### Recovery Event {event-id}
+
+- Phase/task: {phase and originating task when known}
+- Original request: {original_request_id}
+- Original commit: {immutable task commit}
+- Defect class: lint | type | test | build | composition | other
+- Discovered by: {exact verification command or transition check}
+- Disposition: recovered | direction-required | failed-attempt
+- Authorization: phase-standing | operator-extension | operator-scope
+- Attempt: {used}/{phase_recovery_limit}
+- Dispatch target: {exact launcher-owned implementation target}
+- Recovery commit: {sha or -}
+- Verification: {focused and relevant phase result}
+- Reason: {eligibility or stop-boundary evidence}
+```
+
 ## Mode: Implement
 
 ### 1. Verify Phase Base
@@ -125,7 +329,12 @@ For every task:
 3. Follow RED/GREEN/refactor ordering when specified.
 4. Implement only that task. Optional nested help does not transfer task
    ownership or commit authority.
-5. Run every task verification command.
+5. Apply the Prevention and Post-Commit Recovery ordering: format, run every
+   declared task verification, run applicable discoverable proportionate cheap
+   checks, and, for emitted output or build/test configuration changes, run a
+   scoped build/test before commit. Broad repository tests and builds may stay at
+   the phase boundary when per-task execution is disproportionate. This
+   prevention does not consume a recovery attempt.
 6. Self-review requirements, behavioral tests, scope, and accidental changes.
 7. Fix any issue before committing.
 8. Create exactly one task commit using `commit_convention`.
@@ -139,8 +348,9 @@ For every task:
    - every task verification passed; and
    - the worktree is clean.
 10. Perform a brief between-task transition check before starting the next
-    task. If the committed task is defective, stop with `DONE_WITH_CONCERNS` or
-    `BLOCKED`; do not amend, add an unplanned task commit, or conceal it.
+    task. If the committed task is defective, apply the post-commit eligibility,
+    accounting, append-only recovery, event, and stop contract above. Never
+    amend or conceal the task commit.
 
 Do not skip, reorder, combine, or split planned task commits.
 
@@ -149,6 +359,8 @@ Do not skip, reorder, combine, or split planned task commits.
 After all task commits:
 
 - run phase-wide verification;
+- apply the same post-commit recovery contract to an eligible phase-level
+  composition failure;
 - verify task outputs compose correctly;
 - compare the phase result with design/spec/discovery;
 - confirm no task boundary or dependency was missed; and
@@ -166,10 +378,12 @@ report.
 **Phase:** {phase-id}
 **Tasks executed:** {N} of {N}
 **Phase base:** {sha}
+**Final head:** {sha}
 **Commits:** {first sha}..{last sha}
+**Recovery attempts:** {used}/{phase_recovery_limit}
 **Phase verification:** pass | fail
 **Confidence:** high | medium | low
-**Request ID:** {request_id}
+**Request ID:** {original_request_id}
 **Dispatch target:** {launcher-owned target}
 **Dispatch stamp:** {formal Dispatch: line}
 
@@ -179,6 +393,10 @@ report.
 | ------- | ------ | ------ | ------------ | --------------- |
 | pNN-tNN | done   | {sha}  | pass         | {bounded files} |
 
+### Recovery Events
+
+- {None, or exactly one canonical event per recovered, direction-required, or failed-attempt disposition}
+
 ### Optional Nested Dispatches
 
 - {None, or request ID / bounded purpose / exact target / terminal outcome}
@@ -192,6 +410,93 @@ report.
 - {None or concise reason/evidence}
 ```
 
+## Mode: Recover
+
+Recover mode is a continuation of a post-commit recovery attempt already
+authorized when the original accepted handle cannot resume. It is not phase
+implementation, review-fix mode, fallback, or replay.
+
+Require this self-contained Recover Scope:
+
+```yaml
+mode: recover
+original_request_id: { original phase request }
+continuation_event: { generic continuation_events identifier }
+recovery_base_head: { current immutable Git HEAD }
+original_task_id: { originating planned task }
+original_commit: { immutable task commit }
+defect_class: { lint|type|test|build|composition|other }
+discovered_by: { exact command or transition check }
+bounded_correction_scope: { mechanical correction only }
+bounded_files: { declared or mechanically derived in-phase files }
+phase_recovery_limit: { resolved total limit }
+phase_recovery_attempts_used: { authoritative nonzero used count }
+pending_attempt: { matching authoritative ledger entry }
+focused_verification: { exact failing check }
+phase_verification: { relevant phase command }
+dispatch_target: { exact original launcher-owned target }
+dispatch_axes: { unchanged original launcher-owned axes }
+dispatch_stamp: { original formal Dispatch line }
+```
+
+1. Validate every recover input. Confirm the exact launcher-owned target equals
+   the original target and the generic `continuation_events` record links
+   `continuation_event` to `original_request_id`.
+2. Confirm HEAD exactly equals `recovery_base_head`; the `original_commit`
+   remains immutable at the same history position; and the worktree contains
+   only the reconciled pending ledger reservation plus an optional mechanically
+   bounded diff inside `bounded_files`. Any other dirt or history change
+   blocks.
+3. Reconcile the authoritative `pending_attempt` and nonzero
+   `phase_recovery_attempts_used` with `state.md`. Recover mode continues that
+   same consumed attempt and must not increment usage again. Missing,
+   contradictory, or unreconciled state blocks before editing.
+4. Apply or complete only `bounded_correction_scope`. Recover mode must not
+   replay planned tasks and must not require, fabricate, or consume a review
+   artifact.
+5. Apply the bounded correction, then run `focused_verification` and
+   `phase_verification` before creating a candidate commit. If either check
+   fails, restore `bounded_files` to their original committed content,
+   atomically mark the pending entry `failed`, durably commit only that
+   ledger transition, emit one `failed-attempt` event, and stop.
+6. When both pre-commit checks pass, atomically mark the pending entry
+   `completed` and create one append-only candidate recovery commit containing
+   only `bounded_files` plus that ledger transition.
+7. Immediately rerun `focused_verification` and `phase_verification` against the
+   committed HEAD; these reruns are authoritative. On pass, emit one `recovered`
+   event and report the candidate as the successful recovery commit. On
+   failure, atomically replace `completed` with `failed`, durably commit that
+   ledger-only transition, emit one `failed-attempt` event, preserve the
+   consumed attempt and immutable candidate, and claim no successful recovery
+   commit. If terminal evidence cannot be committed, report an unreconciled
+   block that root must reject before bookkeeping. Never amend history or
+   launch fallback.
+8. Return the report below. `DONE` is accepted success;
+   `DONE_WITH_CONCERNS` and `BLOCKED` may be accepted terminal stops and must
+   still report provenance, accounting, immutable history, and the event.
+
+```markdown
+## Phase Recovery Continuation Report
+
+**Status:** DONE | DONE_WITH_CONCERNS | BLOCKED
+**Phase:** {phase-id}
+**Original request ID:** {original_request_id}
+**Continuation event:** {continuation_event}
+**Recovery base:** {recovery_base_head}
+**Original task/commit:** {original_task_id} / {original_commit}
+**Attempt:** {phase_recovery_attempts_used}/{phase_recovery_limit}
+**Dispatch target:** {same exact launcher-owned target}
+**Dispatch stamp:** {original formal Dispatch line}
+**Pending handoff:** {completed|failed}
+**Recovery commit:** {sha or -}
+**Verification:** {focused result}; {phase result}
+**Recovery event:** {event-id}
+
+### Concerns or Block
+
+- {None or bounded terminal-stop evidence}
+```
+
 ## Mode: Fix
 
 Fix mode is a continuation of a successfully completed phase, not a replay.

package/assets/bundle-metadata.json

@@ -0,0 +1,4 @@
+{
+  "schemaVersion": 1,
+  "oatVersion": "0.2.29"
+}

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

@@ -66,6 +66,31 @@ The canonical autonomy contract and exhaustive gate inventory
 `references/docs/autonomy-contract.md`) map each prompt to its autonomous
 resolution and provenance.
 
+### Dispatch-ladder scope selection
+
+An incomplete reusable dispatch ladder is auto-resolvable when an authorized
+adoption-compatible config scope is available. Autonomous planning checks
+config-file existence in this fixed order without prompting or reordering from
+effective value or matrix-cell provenance:
+
+1. user config (`~/.oat/config.json`);
+2. repo-local config (`.oat/config.local.json`);
+3. shared config (`.oat/config.json`), only when repository policy already
+   authorizes that write.
+
+Before writing, planning rejects a candidate that would preserve a
+provider-level scalar in that scope or remain shadowed by one at higher
+precedence. It always tries the next authorized compatible candidate and stops
+without mutation only when none remains.
+
+The planner runs exactly one matching `oat config adopt dispatch-matrix`
+command, records file-existence and compatibility evidence plus the selected
+scope, and re-runs dispatch preflight. Existing explicit cells remain unchanged;
+their provenance does not select the persistence scope. No authorized
+compatible scope, or a ladder that remains incomplete after adoption, is still
+a repository-policy boundary. `OAT_NON_INTERACTIVE=1` without
+`OAT_AUTONOMOUS=1` does not select a scope and continues to fail closed.
+
 ## Review contract
 
 Autonomous execution preserves independent review:

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

@@ -16,6 +16,10 @@ and updates project state.
   in dependency order.
 - **Task boundary:** each task still produces exactly one bounded, verified
   commit.
+- **Prevention boundary:** formatting, declared task verification, and
+  applicable cheap checks run before the task commit.
+- **Recovery boundary:** an eligible post-commit defect may produce a separate
+  same-target recovery commit under the phase's bounded recovery authority.
 - **Review boundary:** the root dispatches one independent reviewer after the
   phase report.
 - **Fix boundary:** blocking findings return to the original phase handle when
@@ -78,7 +82,138 @@ 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 project bookkeeping.
+It does not dispatch the phase reviewer or mutate general project bookkeeping.
+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
+still present. The root validates that marker against the report, recovery
+event, immutable history, attempt accounting, exact target, and verification
+before clearing it. Only the post-validation null marker is the settled ledger
+state; a premature clear or contradictory marker fails closed.
+
+## Prevent Defects Before Commit
+
+Prevention is the first recovery control. Before each planned task commit, the
+phase implementer runs checks in this order:
+
+1. format every changed file;
+2. run the task's declared verification;
+3. run every repository-discovered cheap check that applies to the changed
+   surface and is proportionate to the task; and
+4. run a discoverable scoped build or test when the task changes emitted
+   output, build or test configuration, packaging, or equivalent behavior.
+
+Broad repository tests and builds may remain phase-level when running them for
+every task would be disproportionate. These broader checks verify that the
+phase's task outputs compose correctly. A correction made before the planned
+task commit is prevention and does not consume a recovery attempt.
+
+## Recover After Commit
+
+When declared task, transition, or phase verification finds a post-commit
+defect, OAT classifies it before editing. Automatic recovery proceeds only when
+the correction is mechanically bounded, unambiguous, in phase, non-destructive,
+and verifiable, and when the exact launcher-owned implementation target and
+original-request provenance remain intact. Architecture, security, product,
+requirements, public-behavior, credential, protected-branch, destructive, or
+non-mechanical scope changes require operator direction.
+
+The accepted task commit remains immutable. For an eligible defect, the phase
+implementer reserves an attempt in the authoritative phase ledger, applies the
+bounded correction, and runs focused and phase checks before a candidate commit.
+After those checks pass, the implementer commits the correction with a
+`completed` pre-bookkeeping marker and immediately reruns both checks against
+the committed HEAD. Those post-commit reruns are authoritative. A pass makes
+the candidate the successful recovery commit; a failure durably transitions the
+marker to `failed` in ledger-only terminal evidence and stops without claiming
+a successful recovery. Mechanically related failures from one verification
+command may share one atomic attempt and successful commit; independent defects
+require separate attempts.
+
+Append-only history protects accepted work by requiring a new, auditable commit;
+it does not require repeated approval for a mechanical repair already covered
+by the phase's standing authority. The important distinctions are:
+
+- a **defect** is a post-commit failure discovered by declared verification;
+- an **authorization prompt** is required only at a direction-required
+  boundary, not for every eligible defect;
+- a **continuation** preserves the original request and exact target, either in
+  the accepted handle or through an explicitly linked fresh same-target
+  recovery launch; and
+- a **successful repair** produces one immutable append-only recovery commit.
+
+This recovery is not accepted-launch fallback. After a launch is accepted,
+completion, failure, timeout, interruption, `BLOCKED`, or contract refusal never
+makes another model, provider, route, or worker eligible. A fresh launch is
+permitted only when the caller-specific lifecycle contract already authorized
+bounded recovery, the accepted handle cannot resume, the exact original target
+remains bindable, a pending attempt is reconciled, and the existing
+`continuation_events` record links it to the original request.
+
+### Recovery Budget
+
+`oat_phase_recovery_policy` is dedicated to implementation recovery and is
+independent of `oat_orchestration_retry_limit`, which continues to govern
+review-fix and gate loops. The project default is `10` attempts per phase.
+Project defaults and phase-specific overrides accept integers from `0` through
+`20`; `0` disables automatic post-commit repair for that scope.
+
+Attempt usage is monotonic and durable per phase. A new attempt is consumed
+before the bounded edit begins, so a failed edit, commit, or re-verification
+cannot retry for free. An already-reconciled pending attempt may finish without
+another reservation, even when usage equals the limit. Evidence of an
+infrastructure or flaky failure permits one no-edit rerun without consuming an
+attempt; a repeated unexplained failure is ambiguous and stops without editing.
+A direction-required boundary reached before reservation leaves the pending
+marker null and usage unchanged, emits its required event, and records no edit
+or recovery commit.
+
+At three recovery events, the phase report warns about elevated recovery volume
+but may continue while every eligibility condition and the budget remain valid.
+At exhaustion, OAT stops for one explicit operator outcome:
+
+1. **Add N attempts:** set that phase's total limit to `used_attempts + N`,
+   capped at `20`, without resetting prior usage.
+2. **Authorize changed scope:** record a separate consequential or
+   scope-expanding action outside automatic recovery.
+3. **Stop:** preserve the worktree, immutable history, and evidence.
+
+### Recovery Event
+
+Every recovered, direction-required, or failed-attempt disposition emits
+exactly one event with this heading, label order, and vocabulary:
+
+```markdown
+### Recovery Event {event-id}
+
+- Phase/task: {phase and originating task when known}
+- Original request: {original_request_id}
+- Original commit: {immutable task commit}
+- Defect class: lint | type | test | build | composition | other
+- Discovered by: {exact verification command or transition check}
+- Disposition: recovered | direction-required | failed-attempt
+- Authorization: phase-standing | operator-extension | operator-scope
+- Attempt: {used}/{phase_recovery_limit}
+- Dispatch target: {exact launcher-owned implementation target}
+- Recovery commit: {sha or -}
+- Verification: {focused and relevant phase result}
+- Reason: {eligibility or stop-boundary evidence}
+```
+
+The event ledger keeps defect volume, authorization-prompt volume, continuation
+volume, and successful repair commits measurable as separate facts. A failed
+attempt still produces one event even when it produces no recovery commit.
+
+### Pre-Change Baseline
+
+The recorded pre-change baseline is nine recovery events plus two
+operator-recovery continuations. Known failures included lint, composition, and
+test-fixture defects; exact per-class counts are unavailable. The repeated
+prompts exposed a latent policy under integration-heavy verification rather
+than a recent regression. In particular, PR #176 changed phase-base anchoring
+and is explicitly excluded from causation: the root still captures a fresh
+phase base immediately before each launch, so earlier recovery commits are
+already part of the next phase's base.
 
 ### Phase reviewer
 
@@ -155,6 +290,21 @@ 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.
 
+## Update Installed Recovery Contracts
+
+Bounded phase recovery ships in OAT `0.2.28`. After upgrading to that release or
+later, update the installed OAT tools and then regenerate provider views from
+the canonical contracts:
+
+```bash
+oat tools update
+oat sync --scope all
+```
+
+Run the commands in that order before expecting global Claude, Codex, or Cursor
+phase agents to use the new contract. Provider assets are generated views, not
+independently maintained policy forks.
+
 ## Phase Scope
 
 The root supplies one scope for the whole phase:

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.2.27",
-  "docs-config": "0.2.27",
-  "docs-theme": "0.2.27",
-  "docs-transforms": "0.2.27"
+  "cli": "0.2.29",
+  "docs-config": "0.2.29",
+  "docs-theme": "0.2.29",
+  "docs-transforms": "0.2.29"
 }

package/assets/skills/oat-dispatch-subagents/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-dispatch-subagents
-version: 1.2.1
+version: 1.2.2
 description: Use when an OAT skill or workflow needs provider-neutral selection, launch, recovery, or evidence for bounded subagent work without project lifecycle policy.
 disable-model-invocation: true
 user-invocable: false
@@ -385,18 +385,31 @@ a declared class floor.
 - An accepted launch is terminal for automatic replacement eligibility.
 - Completion, failure, timeout, interruption, `BLOCKED`, and contract refusal
   are post-acceptance outcomes; none makes another route eligible.
+- Automatic route, model, provider, or worker replacement after acceptance is
+  forbidden fallback. No post-acceptance outcome makes another route eligible.
 - A wrapper failure or payload rejection before child start is a pre-start
   rejection. A new recorded selection is allowed only within caller retry
   policy.
 - Continuing the same accepted child through its valid handle is allowed.
   Record continuation separately and preserve selectors and route.
+- Same-target bounded recovery is a continuation rather than fallback only when
+  a caller-specific lifecycle contract explicitly authorizes it. That contract
+  must supply the bounded scope, exact target, numeric budget, canonical
+  recording, and stop conditions before launch. It may allow either
+  continuation through the accepted handle or an explicitly linked fresh
+  same-target launch when the original handle cannot be resumed.
+- Standing recovery authority is default-deny. `oat-project-implement` may
+  establish it through its complete caller-specific lifecycle contract; wave
+  execution, autonomous projects, cloud-project orchestration, reviewers, and
+  every other consumer remain outside that grant unless their own future
+  contract independently defines the complete boundary.
+- Scope-expanding or consequential recovery requires new operator direction.
+  The same applies to ambiguous, destructive, or retry-exhausted work.
 - A caller may cancel accepted handles only after it proves that the enclosing
   run itself is invalid under caller-owned containment or integrity policy.
   Record `invalid-run-abort` and the invalidating evidence. Cancellation never
   makes another route eligible and never authorizes replacement, fallback, or
   a successful child outcome.
-- Operator-authorized recovery is a new explicit action, never automatic
-  fallback.
 - Runtime identity is optional corroboration. Missing runtime identity does not
   invalidate launcher-owned configured invocation evidence.