@open-agent-toolkit/cli 0.2.26 → 0.2.28

package/assets/NOTICES.md

@@ -0,0 +1,156 @@
+# NOTICES
+
+This file records attribution for externally-sourced prose incorporated
+into this repository. When you adapt or lift prose from an external
+project into a skill, template, or doc, add an entry here — do not
+add attribution footers to the skill files themselves.
+
+## Obra Superpowers
+
+**Source:** https://github.com/obra/superpowers
+**License:** MIT
+**Version referenced:** 5.0.7
+
+### `brainstorming` skill
+
+Source file: `skills/brainstorming/SKILL.md`
+
+Passages adapted or lifted verbatim into OAT:
+
+- "Exploring approaches" (4 lines) — used in `oat-project-design` Component 3.5 (approach reaffirmation)
+- "Presenting the design" (5 lines) — used in `oat-project-design` Component 4 (section iterator)
+- "Design for isolation and clarity" (4 lines) — used as a principle in `oat-project-design`
+- Self-review four-check template — used in `oat-project-design` Component 6
+- User-review gate phrasing — used in `oat-project-design` Component 7
+
+Consumer OAT skills: `oat-project-design`, `oat-project-quick-start`
+(via lightweight-design mode choice inheriting the same prose).
+
+### Upstream MIT license
+
+```text
+MIT License
+
+Copyright (c) 2025 Jesse Vincent
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+### `brainstorming` skill — visual companion
+
+Source files: `skills/brainstorming/scripts/{server.cjs, start-server.sh,
+  stop-server.sh, frame-template.html, helper.js}` and
+`skills/brainstorming/visual-companion.md`.
+
+Files lifted into OAT (under `.agents/skills/oat-brainstorm/`):
+
+- `scripts/server.cjs`, `scripts/stop-server.sh`, `scripts/frame-template.html`,
+  `scripts/helper.js` — verbatim from upstream.
+- `scripts/start-server.sh` — verbatim except for default persistence-path
+  changes (`.superpowers/brainstorm/` → OAT-managed prefixes:
+  `<project>/.oat/brainstorm/`, `<repo-root>/.oat/brainstorm/`,
+  `~/.oat/brainstorm/`).
+- `references/visual-companion.md` — adapted prose: persistence paths and
+  example invocations updated to OAT conventions.
+
+Consumer OAT skills: `oat-brainstorm`.
+
+## shadcn/improve
+
+**Source:** https://github.com/shadcn/improve/tree/main/skills/improve
+**License:** MIT
+**Version referenced:** `main` (retrieved 2026-07-12)
+
+### `improve` skill
+
+Source files: `skills/improve/SKILL.md` and
+`skills/improve/references/{audit-playbook.md,closing-the-loop.md,plan-template.md}`.
+
+Files copied into `.agents/skills/oat-repo-improve/`; the skill identifier,
+heading, invocation examples, and generated-plan attribution were renamed for
+the OAT repository namespace.
+
+### Upstream MIT license
+
+```text
+MIT License
+
+Copyright (c) 2026 shadcn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+## visual-explainer
+
+**Source:** https://github.com/nicobailon/visual-explainer
+**License:** MIT
+**Version referenced:** 0.8.1
+
+### Explainer templates and render QA
+
+Visual presentation and QA patterns were adapted into
+`.agents/skills/explainer-kit/`, including self-contained HTML shells,
+responsive navigation, slide-deck interaction and print behavior, overflow
+containment, reduced-motion handling, and structural/render checks.
+
+The OAT implementation replaces upstream branding, destinations, invocation
+commands, and example content with destination-neutral contracts, themes,
+templates, and fixtures. Consumer OAT skill: `explainer-kit`.
+
+### Upstream MIT license
+
+```text
+MIT License
+
+Copyright (c) 2025 Nico Bailon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

package/assets/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/docs/contributing/explainer-kit-verification.md

@@ -0,0 +1,125 @@
+---
+title: Verifying Explainer Kit
+description: 'Maintainer runbook for semantic golden cases, temporary real-Chromium evidence, and release validation.'
+---
+
+# Verifying Explainer Kit
+
+Explainer Kit uses portable behavioral goldens and a real-browser release gate.
+The goal is not pixel identity: output may change markup, spacing, and
+composition when it preserves the same meaning, topology, interactions, and
+evidence quality.
+
+## Golden cases
+
+The suite under
+`.agents/skills/explainer-kit/tests/fixtures/golden/` contains three
+portable semantic cases:
+
+| Case                           | What it proves                                             |
+| ------------------------------ | ---------------------------------------------------------- |
+| `simple`                       | Viewport-sized lead evidence and a cohesive baseline recap |
+| `non-linear`                   | Exact branch, fan-in, and cycle preservation               |
+| `explainer-authoring-redesign` | Archive-only rebuild from a dense completed project record |
+
+Every case retains only its descriptor, source input, and content-addressed
+source record. The three cases share one rubric. Generated artifacts, browser
+evidence, screenshots, manifests, catalogs, and review results stay in a
+temporary test directory and are never committed. Paths are
+repository-relative; machine roots, home-relative paths, `file://` URLs,
+Windows drive paths, and UNC paths are rejected.
+
+## Prerequisites
+
+- Install workspace dependencies.
+- Ensure the repository-supported Chromium runtime is installed and launchable.
+- Run from the repository root.
+
+The end-to-end benchmarks require an actual launched Chromium session. A
+deterministic fixture session is valid only for bounded unit/integration tests
+and cannot satisfy a golden production path.
+
+## Run the golden suite
+
+```bash
+node --test \
+  .agents/skills/explainer-kit/tests/golden-conformance.test.mjs
+```
+
+A passing run proves:
+
+- one planner-owned hub, architecture view, and deck;
+- source and terminology cohesion;
+- exact topology and catalog parity;
+- mobile, tablet, and desktop Chromium evidence;
+- one independent critic invocation; and
+- a passing terminal review without correction.
+
+The focused integration suites below separately exercise the one-correction
+ceiling.
+
+The suite recomputes semantic-input hashes, grounds every claim in retained
+source evidence, and evaluates the shared rubric against live runtime output.
+A prose claim or status label without runtime proof does not pass.
+
+## Inspect generated evidence
+
+The suite materializes each case's runtime package under its temporary working
+directory, validates it, and removes it at test completion. Add a local
+debugger breakpoint or temporarily disable cleanup when diagnosing a failure;
+do not add generated runtime output to the fixture directories.
+
+## Focused integrity suites
+
+Use these when changing browser identity, immutable evidence, resume, or archive
+contracts:
+
+```bash
+node --test \
+  .agents/skills/explainer-kit/tests/records.test.mjs \
+  .agents/skills/explainer-kit/tests/run.integration.test.mjs
+
+node --test \
+  .agents/skills/explainer-kit/tests/browser-runtime.test.mjs \
+  .agents/skills/explainer-kit/tests/qa.test.mjs \
+  .agents/skills/explainer-kit/tests/contracts.test.mjs \
+  .agents/skills/explainer-kit/tests/durability.test.mjs \
+  .agents/skills/explainer-kit/tests/rebuildability.test.mjs
+
+pnpm --filter @open-agent-toolkit/cli exec vitest run \
+  src/commands/project/archive/archive-utils.test.ts \
+  src/release/public-package-contract.test.ts
+
+node --test tools/smoke/explainer-kit/*.test.mjs
+```
+
+## Release gate
+
+The required publishable-package gate is:
+
+```bash
+pnpm release:validate
+```
+
+It validates all five lockstep public package tarballs and then runs the bounded
+curated-style/template matrix in real Chromium. The visual gate retains 65
+machine-readable viewport, clipping, motion, keyboard, no-JavaScript, and print
+measurements. Missing Chromium or untrusted retained evidence fails closed.
+
+For the full repository closeout, also run the standard checks documented in
+the root `AGENTS.md`:
+
+```bash
+pnpm check
+pnpm type-check
+pnpm test
+pnpm build
+pnpm lint
+pnpm format
+pnpm build:docs
+git diff --check
+```
+
+Do not treat an isolated transient timeout as a product pass or failure without
+reproducing the failing test. Preserve the exact-head successful rerun evidence
+used for release closure.

package/assets/docs/contributing/index.md

@@ -17,4 +17,5 @@ Use this section when you are changing OAT itself rather than consuming it as a
 - [Commit Conventions](commit-conventions.md) - Traceable commit patterns for project and docs work.
 - [Hooks and Safety](hooks-and-safety.md) - Safety and mutation contracts for provider-sync behavior.
 - [Smoke Testing](smoke-testing.md) - Runbook for the live workflow smoke runner: prerequisites, scenarios, evidence reports, and recovery.
+- [Verifying Explainer Kit](explainer-kit-verification.md) - Golden recap cases, real-Chromium evidence, fixture regeneration, and release validation.
 - [Verifying Cursor Pins](verifying-cursor-pins.md) - Runbook for probe-verifying a Cursor model pin before shipping it.