@open-agent-toolkit/cli 0.2.26 → 0.2.28

package/assets/docs/reference/troubleshooting.md

@@ -113,9 +113,56 @@ oat tools has <pack> --scope user
 - Reconcile `state.md`, `plan.md` review table, and `implementation.md`.
 - Ensure phase/review status has been updated after reviews and fix cycles.
 
+## An Explainer Kit recap ends as `built-needs-review`
+
+`built-needs-review` means the required unattended visual-review chain did not
+reach a valid `pass`. The run retains available output for diagnosis, but OAT
+will not finalize, archive, attest, publish, or push it as a successful recap.
+Do not bypass the review gate by copying the package into a durable location.
+
+Inspect:
+
+1. `build-record.json` and `manifest.json` for the terminal outcome and warning.
+2. `qa/browser/` for all required mobile, tablet, and desktop PNG/metrics pairs.
+3. `qa/visual-review/attempt-*/request.json` and `result.json` for request
+   binding, critic disposition, and findings.
+4. `qa/visual-review/revision.json` when a correction was requested.
+5. Adapter logs for missing or invalid `browserSession`, `visualCritic`, or
+   correction-provider modules.
+
+Common causes include unavailable Chromium, a fixture or unbranded session,
+missing screenshots, invalid decoded PNG dimensions, runtime/capture identity
+drift, critic exceptions, evidence mutation, `fail`, and an unresolved
+correction. Fix the provider or artifact problem and rebuild the recap; partial
+evidence is diagnostic only.
+
+See
+[Explainer Provider Integration](../workflows/skills/explainer-kit-providers.md)
+for the trusted-session and critic contracts.
+
+## Explainer Kit resume fails with `E_APPROVAL_RESUME`
+
+Interactive resume is same-request only. Keep the opaque `ekrt2` token returned
+as `approval.resumeToken` outside the package and provide it as
+`reviewedSource.resumeToken` with the complete original request.
+
+The error is expected when:
+
+- the token is missing, malformed, or not `ekrt2`;
+- the configured output root or retained run root moved;
+- `run-request.json` or a retained set-plan record changed;
+- the current request differs in source binding, recipe, mode, theme, render
+  strategy, privacy, public URL, durability, or publish destination; or
+- the package contains a legacy `ekrt1` token.
+
+Do not edit retained files or weaken the current request to force a match.
+Restore the exact original request and package bytes. Legacy paused runs cannot
+be upgraded in place; restart them to receive an authenticated `ekrt2` token.
+
 ## Reference artifacts
 
 - `.oat/projects/<scope>/<project>/implementation.md`
 - `.oat/projects/<scope>/<project>/reviews/`
+- `.oat/projects/<scope>/<project>/explainers/<slug>/qa/`
 - `packages/cli/src/commands/doctor/index.ts`
 - `packages/cli/src/commands/instructions/`

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

@@ -57,12 +57,30 @@ The archive exports at most one selected recap package. It preserves structured
 failure outcomes and successful intermediates, rejects an existing dated
 destination, and requires the selected path to stay under the project's
 `explainers/` directory with a `project-recap` manifest. Verification covers
-the exact retained bytes for the privacy-safe request, content approval, fact
-base JSON and Markdown, declared author results, authored content, resolved
-theme, and every built artifact. Canonical fact-base and theme hashes remain
-normalized-object identities; `manifest.immutableHashes` independently covers
-serialized file bytes. Missing, stale, or tampered coverage fails before the
-active project is deleted.
+the complete mode-aware package:
+
+- privacy-safe request and content approval;
+- fact-base JSON and Markdown;
+- the five immutable set-plan records and authored drafts;
+- declared author results and authored content;
+- resolved theme and every built artifact;
+- canonical mobile, tablet, and desktop screenshots;
+- paired `browser-evidence/v2` metrics with launched Chromium name, version,
+  and capture identity;
+- cohesion observations and each visual-review request/result; and
+- the bounded revision record when a correction occurred.
+
+Canonical object hashes identify normalized fact-base, theme, runtime, and
+capture objects; `manifest.immutableHashes` independently covers serialized file
+bytes. The archive requires one complete, internally consistent browser and
+review chain for a successful unattended recap. Missing, stale, forged,
+cross-record-mismatched, or tampered coverage fails before the active project is
+deleted.
+
+`built-needs-review` is a terminal review-gate outcome, not a non-durable
+success. Its partial evidence remains available for diagnosis, but it cannot be
+finalized, exported, attested, archived, or pushed. Review and rebuild the recap
+to a passing visual-review outcome first.
 
 Local-scope projects are not archived through this export path. Their explainer
 packages inherit the local project's untracked posture and remain

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/docs/workflows/skills/explainer-kit-providers.md

@@ -0,0 +1,144 @@
+---
+title: Explainer Provider Integration
+description: 'Provider-neutral planner, author, browser-session, and visual-critic contracts for Explainer Kit integrators.'
+---
+
+# Explainer Provider Integration
+
+Explainer Kit keeps model and browser providers outside its retained request
+contracts. Integrators supply executable seams in process or through validated
+module exports; the core owns schemas, evidence binding, and terminal outcomes.
+
+For recipes, authoring behavior, themes, and lifecycle policy, start with
+[Explainer Kit](explainer-kit.md).
+
+## Provider boundaries
+
+Use exactly one form for each required role:
+
+| Role               | Direct input     | Module-path input          | Required export                     |
+| ------------------ | ---------------- | -------------------------- | ----------------------------------- |
+| Set planning       | `planSet`        | `planSetModulePath`        | `planSet` function                  |
+| Artifact authoring | `author`         | `authorModulePath`         | `author` function                   |
+| Browser evidence   | `browserSession` | `browserSessionModulePath` | branded `browserSession` descriptor |
+| Whole-set review   | `visualCritic`   | `visualCriticModulePath`   | `visualCritic` function             |
+
+`project-recap` requires all four roles. Other recipes require the author and
+use their recipe-specific planning behavior. Direct-plus-module conflicts,
+missing files, and invalid exports fail at the adapter boundary before core
+execution.
+
+Do not place browser or visual-review providers in `coreOptions`. Executable
+callbacks, descriptors, and module paths are transient and never enter
+`ExplainerRunRequestV1`, `run-request.json`, or immutable package hashes.
+
+## Set planner
+
+The provider-neutral `planSet` callback runs once after fact reconciliation and
+before any author callback. It returns the complete portfolio and one shared
+claim ledger.
+
+For a project recap, the portfolio must contain the required hub, architecture
+view, and deck. Optional entries must use a recipe-licensed profile, remain
+inside recipe and per-profile limits, and carry source-backed justification.
+Duplicate identities, undeclared sources, conflicting shared terms, and
+unjustified optionals fail validation.
+
+Every author request receives the immutable set context and its matching planned
+artifact. Authors cannot add, remove, replace, or rename portfolio entries.
+
+## Artifact author
+
+The core invokes `author` once per planned artifact with
+`explainer-kit.author-request/v2`. The request contains:
+
+- artifact identity, type, and authoring path;
+- the versioned brief and bundled medium-specific guidance;
+- reconciled facts and the shared set context;
+- the matching planned artifact;
+- the resolved theme; and
+- the bundled shell for artistic HTML.
+
+Return `explainer-kit.author-result/v2` with exactly one of
+`content.markdown` or `content.html` and non-secret provenance. The core
+validates source overlap, path ownership, script identity, and structural
+contracts after the callback returns.
+
+The author, fact critic, browser probe, and visual critic must have distinct
+callback identities. One provider implementation may back multiple roles, but
+the adapter still requires separate executable boundaries.
+
+## Trusted browser session
+
+Create a direct session with the compatible core:
+
+```js
+const browserSession = await core.createBrowserProbeSession();
+
+try {
+  await runOatExplainer(request, {
+    planSet,
+    author,
+    browserSession,
+    visualCritic,
+  });
+} finally {
+  await browserSession.close();
+}
+```
+
+The factory launches Chromium and derives the runtime name and version from the
+actual browser instance. A private in-memory brand prevents a plain object with
+caller-authored `{name, version}` metadata from impersonating a trusted
+session. Module providers export the already branded descriptor as
+`browserSession`, not a bare callback.
+
+For unattended project recaps, the core chooses 320, 768, and 1440 widths and
+requires default-scenario PNGs. It validates the PNG signature, decoded
+dimensions, and pixel payload, then writes paired
+`explainer-kit.browser-evidence/v2` metrics. Every record retains:
+
+- launched Chromium name and version;
+- fixed capture settings;
+- one derived capture identity;
+- viewport and scenario;
+- screenshot path and byte binding; and
+- measured overflow, clipping, readability, motion, keyboard, deck, and theme
+  behavior.
+
+All records in one review chain must carry the same runtime and capture
+identity. Deterministic fixture sessions are explicit test helpers and are
+rejected by unattended production recap paths.
+
+## Whole-set visual critic
+
+The `visualCritic` receives one
+`explainer-kit.visual-review-request/v1` plus a confined evidence reader. The
+request binds:
+
+- every rendered artifact and its exact content hash;
+- every viewport-matched screenshot and metrics hash;
+- cohesion observations from the shared ledger; and
+- the trusted browser runtime and capture identity.
+
+Return `explainer-kit.visual-review-result/v1` with the exact request identity,
+all reviewed artifact IDs, structured findings, and one disposition:
+
+- `pass` completes the review gate;
+- `correct` requests one bounded correction and one final review; or
+- `fail` terminates the gate.
+
+The critic must not mutate rendered files or evidence. The core revalidates all
+bound bytes after each callback.
+
+## Terminal behavior
+
+There is never a second correction or third review. Missing, malformed, forged,
+stale, cross-record-mismatched, or mutated evidence; a thrown callback; a
+`fail`; or an unresolved correction produces `built-needs-review`.
+
+That outcome retains available artifacts and review evidence for diagnosis, but
+invokes neither durability nor publication. It cannot be finalized, archived,
+attested, or pushed as a successful recap.
+
+See [Troubleshooting](../../reference/troubleshooting.md) for recovery steps.