explorbot 0.2.3 → 0.2.5

package/docs/superpowers/specs/2026-08-07-prima-fixes-design.md

@@ -0,0 +1,394 @@
+# Prima Fixes — Perception Ladder, No Heal, Proof-Carrying Envelopes
+
+**Date:** 2026-08-07
+**Status:** Draft for review
+**Supersedes parts of:** `2026-08-01-prima-boat-design.md`
+**Evidence:** `docs/superpowers/reviews/2026-08-06-prima-vs-playwright-cli.md`
+
+## Problem
+
+A field run of prima against a live app (Testeiya, `localhost:3050`) found the boat working but
+not trustworthy as an executor. Four defects matter:
+
+- A `pw` call on a selector that does not exist returned `ok: true`, `healed: true`, having
+  clicked an unrelated control ("New agent"). Heal substituted the target and reported success.
+- `### Changes` never appeared in any successful envelope, so a successful action proved
+  nothing and every step had to be confirmed with a playwright-cli snapshot.
+- `do` given two instructions performed four, typing into a live chat box actions nobody asked
+  for.
+- Auto-discovery of a playwright-cli session never matched, while the failure message advised
+  opening the session the user already had open.
+
+Underneath the third defect is a perception problem. `action.ts:139` captures
+`page.locator('body').ariaSnapshot()` **without** `mode: 'ai'`, so `do` sees roles and text but
+no element handles and must invent locators. That is why the `click` tool's schema demands
+"multiple commands targeting the SAME element" and why one click produced five ladder attempts,
+one of them invalid JavaScript.
+
+## Goals
+
+- Prima is the executor for an expensive orchestrator: page data never enters that context on
+  the happy path, intent is never guessed, and every action carries proof of what changed.
+- `do` acts on element handles it was given, not on locators it invented.
+- Failures are failures. No code path may reach a different element than the one asked for.
+- Attachment to an existing playwright-cli session works without hand-editing files.
+
+## Non-Goals
+
+- Replacing playwright-cli. It remains the fallback for direct driving and the tool prima
+  points back to when it cannot help.
+- Reducing per-command latency, and improving `research` locator quality. Separate concerns.
+- Changing Tester, Navigator, or Researcher behaviour outside the shared pieces named below.
+
+---
+
+## 1. Perception ladder for `do`
+
+Four tiers, tried in order. Each tier answers "what can I act on here?" at a different cost.
+
+| Tier | Source | When |
+|---|---|---|
+| 1 | Research UI map | a stored map exists for this state hash and the state is well-visited |
+| 2 | **ARIA snapshot with refs** | default |
+| 3 | Compact HTML tree | a ref action failed, or the control is absent from the ARIA tree |
+| 4 | Vision (`visualClick`) | click only, when the target is identifiable solely by appearance |
+
+### Tier 1 — research map
+
+Read through `getPreviousResearch(hash)` — a TTL-free disk read. Not `getCachedResearch`, whose
+six-hour TTL carries session-scoped semantics that must not be stretched for cross-invocation
+reuse. The trigger is the StateManager visit count for the current state hash, the same number
+the envelope already prints as `visit #N`: use the map from the **third visit onward**, so a
+state has to prove it is worth the map before prima prefers one. Below that, skip to tier 2.
+The threshold is a single config field under `ai.agents.prima`, per the one-knob convention.
+
+Research cost is real — 41s on the vision model in the field run — so tier 1 only pays off
+amortized across repeat visits to one state. Prima does not run research on the caller's behalf
+inside `do`; it consumes a map that already exists.
+
+### Tier 2 — ARIA snapshot with refs (the default)
+
+`page.locator('body').ariaSnapshot({ mode: 'ai' })` emits `[ref=eN]` handles. Playwright resolves
+them natively through the `aria-ref=` selector engine, verified live against the running app:
+
+```
+aria-ref=e1 → 1 match
+```
+
+No DOM mutation, no attribute stamping. The model is given the ref-bearing tree and names a ref;
+resolution to a CodeceptJS command is §1.1. One ref becomes one command and the
+multiple-locator fallback ladder collapses.
+
+**Ref lifetime is one context injection.** Refs are snapshot-scoped and shift between calls —
+in the field run the same sidebar button was `ref=e13` in one snapshot and `ref=e284` in a later
+one on the same page. Prima re-snapshots whenever the `do` loop re-injects context on state-hash
+change (the hook exists at `prima.ts:104`), and the prompt states that refs from an earlier
+injection are dead.
+
+**Ref shape.** Refs are frame-qualified: every ref this app emits is `f1e13`-shaped, not `e13`.
+A validator that accepts only `e\d+` rejects every real ref and silently disables the whole tier,
+so the accepted shape is `(f\d+)?e\d+`. Refs are never adapted or invented — a ref that does not
+parse, or that resolves to nothing, is a failure with its own message.
+
+### Tier 3 — compact HTML tree
+
+The current `simplifiedHtml` path. Entered when a ref action fails or the target is not
+represented in the accessibility tree.
+
+### Descending the ladder — `context()`
+
+The tiers above are only reachable if something can move between them mid-run. The `do` loop
+re-injects context between iterations when the state hash changes, which leaves no way to
+recover from a ref that died *within* an iteration — the model's only remaining moves would be
+to guess a locator, which the prompt forbids, or to stop.
+
+`do` therefore carries a `context` tool. First call returns the page as it is now with fresh
+refs, which replace every ref the model was holding; a later call on the same page drops to
+capped markup for elements the accessibility tree does not describe. It is the tier descent, not
+a page dump.
+
+This is deliberately **not** the `context` tool from `createAgentTools`. That one returns
+`getInteractiveARIA()` — `compactAriaSnapshot` over `ActionResult.ariaSnapshot`, captured without
+`mode: 'ai'`, so it carries **no refs** — plus a 6k-char HTML dump beside it. Offering it here
+would hand the model a ref-less tree and push it straight back to guessed locators, undoing
+tier 2.
+
+### Tier 4 — vision
+
+`visualClick` (`src/ai/tools.ts:791`), already implemented. Click only — a coordinate is not a
+handle, so it cannot serve fills, selects, or assertions.
+
+### 1.1 Acting on a ref — `clickRef` / `hoverRef` in `boat/prima/src/tools.ts`
+
+CodeceptJS has no `aria-ref` locator, so a ref cannot be handed to `I.click()` directly. It is
+resolved to a locator CodeceptJS does understand, using machinery that already exists:
+
+```
+page.locator(`aria-ref=${ref}`)
+  → WebElement.fromPlaywrightLocator(...)     (web-element.ts:112)
+  → I.click(<xpath>)
+```
+
+**Which XPath, and the one that is not available.** `WebElement` declares two — `clickXPath`,
+built attribute-first by `buildClickableXPath` (`utils/xpath.ts`), and `xpath`, the absolute
+positional path. On this path only `clickXPath` exists: `fromPlaywrightLocator` builds through
+`fromRawData`, which hardcodes `xpath: ''` (`web-element.ts:89`). Only `fromXPathMatch`, the
+static-HTML path, populates the absolute form. So there is no positional fallback to reach for,
+and that is the right outcome anyway — an absolute path is deduplication machinery, fragile the
+moment the DOM shifts, and the ref resolution and the click happen on separate round-trips.
+
+Verified live, ref → `clickXPath` → match count:
+
+```
+e15  link "Checking the proxy…"  //*[self::a and contains(.,"Checking the proxy and the firewall")]  → 1
+e19  button "Reload"             //*[@id="reload-button"]                                            → 1
+e20  button "Details"            //*[@id="details-button"]                                           → 1
+```
+
+**Require a unique match.** Because there is no fallback, the resolved `clickXPath` is checked
+to match exactly one element before it is used. Zero or many is a failure, reported as such —
+never a click on an ambiguous match and never a retreat to guessed locators.
+
+Ref acting lives in **separate tools in the boat** — `clickRef` and `hoverRef`, from a
+`createRefTools` factory in `boat/prima/src/tools.ts`. `click` and `hover` in `src/ai/tools.ts`
+are left byte-identical. A prima-only tool belongs to prima; core keeps only what every caller
+uses, and lends the boat its result-shaping helpers (`successToolResult`, `failedToolResult`,
+`commitNote`) rather than having them copied.
+
+Adding an optional `ref` to the existing tools looks cheaper and is wrong. A tool's schema and
+description are shared with every caller, and Tester never receives ref-bearing snapshots, so it
+would be shown a parameter it can only fill by inventing one. Making `commands` optional to
+accommodate the new field weakens the contract for Tester too. "Prima enables ref mode, Tester is
+untouched" is not achievable through one definition: there is one definition, and Tester sees it.
+
+Each ref tool takes a ref and nothing else, resolves it, executes one command, and reports that
+command as `used:` — real CodeceptJS a generated test can keep. A ref that does not resolve is a
+failure, not a cue to fall back to a guessed locator: it means the context is stale.
+
+`hoverRef` exists for the same reason as `hover` — revealing hover-only controls is a
+prerequisite for clicking them.
+
+Prima keeps the locator tools alongside the ref tools: tier 3 works from markup that carries no
+refs, and needs them. Tier 4 keeps the coordinate input.
+
+---
+
+## 2. Heal is deleted
+
+`heal()` (`prima.ts:428-460`) is removed, along with `--no-heal`, `PrimaOptions.heal`, the
+`healed:` / `healNote` envelope fields, the `HealAttempt` type, and the
+`### Healing attempts` section. The three call sites — `pw` (`:79`), `do` (`:135`), `go` (`:211`)
+— go straight to `failureEnvelope`.
+
+The failure envelope already does the right thing and becomes the only failure path: `ok: false`,
+the exact error with its call log, and compact ARIA inline. Measured at 8.6s in the field run
+against 34.8s for the heal path that got the answer wrong.
+
+This removes the substitution defect at the root. No remaining code path can select an element
+other than the one asked for, so no envelope can report success for an action the caller did not
+request. Routine obstructions — an overlay covering a button, an element not yet visible — now
+return the failure envelope, and the orchestrating model decides. That is the accepted cost: the
+compact ARIA block is the one place page data deliberately enters the expensive context.
+
+---
+
+## 3. Proof-carrying envelopes
+
+Two defects with one cause. `renderOutcome` (`envelope.ts:76`) returns the **first** of
+changes / answer / research / verdict, so `### Changes` is structurally impossible alongside
+`### Verdict`, `### Answer`, or `### Research`. And `pageChanges` returns `ariaChanges ?? null`,
+which renders nothing when the diff is empty or `previousState` is null.
+
+- `### Changes` renders on every action envelope, showing `no change` explicitly when the tree is
+  identical. A caller can then tell "nothing happened" from "prima did not say".
+- `renderOutcome` stops being mutually exclusive: `### Changes` renders alongside the command's
+  own outcome section.
+- Prima captures an explicit before-snapshot rather than relying on whatever `stateManager`
+  holds at process start.
+- New `### Steps` block for `do`: one line per instruction, each naming the ariaDiff entry that
+  proves it, or marked `unproven`.
+
+### Refs must never reach the diff or hash pipeline
+
+The ref-bearing snapshot is a **context artifact only**. Refs are stripped before hashing and
+diffing. Storing the `mode: 'ai'` output in `ActionResult.ariaSnapshot` would poison every
+`### Changes` block, because Playwright renumbers refs on each call. Measured on an identical
+page whose refs merely shifted:
+
+```
+ref churn only, page identical → diff count = 6
+  added:   button "Cancel" [ref=e21], button "Save" [ref=e20], textbox "Name" [ref=e22]
+  removed: button "Cancel" [ref=e11], button "Save" [ref=e10], textbox "Name" [ref=e12]
+```
+
+Six phantom entries for a page that did not change. Capture ref-bearing and ref-free variants,
+and feed only the ref-free one to `diffAriaSnapshots` and `getStateHash`.
+
+---
+
+## 4. Executor prompt
+
+`instructionSystemPrompt` (`prima.ts:493`) already says to stop when every instruction is done,
+but nothing tracks per-instruction completion, so the loop runs until the model stops calling
+tools. Two rules are added, stated as general principles rather than as counter-examples from
+any debugging session:
+
+- Act only on the listed instructions. An adjacent action that appears helpful is out of scope;
+  report it as an observation instead of performing it.
+- For each instruction, cite the observed page change that proves it. An instruction that cannot
+  be tied to an observed change is reported unproven rather than claimed as done.
+
+The prompt also states the ref contract: act on refs from the current context injection; refs
+from an earlier injection are dead.
+
+---
+
+## 5. Attachment and discovery
+
+Three separate faults, all confirmed empirically.
+
+**Connect with the daemon's own build when attached.** `connectDescriptor` (`prima.ts:374`)
+tries prima's own playwright first and only falls back to `descriptor.playwrightLib` if connect
+fails. Connect *succeeds* across builds, so the fallback is never reached — and then the tier-2
+snapshot breaks:
+
+| client lib | `connect()` | `ariaSnapshot({mode:'ai'})` |
+|---|---|---|
+| own playwright 1.62.1 | ok | `locator.ariaSnapshot: timeout: expected float, got undefined` |
+| daemon playwright-core 1.62.0-alpha | ok | ok, 3376 bytes, `aria-ref=e1` → 1 match |
+
+In attached mode, prefer `descriptor.playwrightLib` when present and fall back to our own. Carry
+`playwrightLib` through the `--endpoint` path too, which currently hardcodes `''`.
+
+**Stop keying discovery on `workspaceDir`.** No `@playwright/cli` release writes that field —
+verified on 0.1.13 and 0.1.17. `parseDescriptor` (`pw-registry.ts:56`) requires it and
+`selectDescriptor` filters on it, so every descriptor is dropped and discovery finds nothing no
+matter what is installed. Resolution becomes: `--endpoint` → `--pw-session <title>` →
+`PLAYWRIGHT_CLI_SESSION` → live descriptor titled `default` → the single live descriptor →
+tool error listing candidate titles. Liveness-probe before selecting.
+
+**Bump the playwright pin to `^1.62`.** `playwright@^1.60` could not `connect()` to a 1.61/1.62
+browser server at all; 1.62.1 connects. The pin is the reason the original review concluded
+attach was broken outright.
+
+Consequences: `browser list` shows attachable sessions rather than reporting none while one is
+live, and the no-browser error stops advising `playwright-cli open <url>` to someone who already
+ran it.
+
+---
+
+## 6. `verify` honesty
+
+`rules/navigator/verification-actions.md` offers nine assertions — `see`, `seeElement`,
+`seeInField`, `seeInTitle`, `seeInSource` and their `dontSee*` counterparts — none of which
+express enabled, disabled, checked, selected, or expanded. A claim about interactive state is
+therefore unprovable by construction, and the field run reported a working feature as failing:
+
+```
+verify "the Save button in the skill editor is now enabled ..."
+→ passed: false, code: (empty), evidence: no assertion held on the current page
+```
+
+The app was correct — `● unsaved` was displayed and the button was enabled.
+
+- Add state assertions to the rule.
+- `verify` distinguishes **assertion failed** from **could not express this assertion**. The
+  second is not a test failure and must not be reported as one.
+- With §7's compaction fix, `verify` reads state from the same ref-bearing snapshot the tier-2
+  ladder produces.
+
+---
+
+## 7. Prerequisite fix — ARIA compaction drops refs and state
+
+`compactAriaSnapshot` keeps only the first bracket group on a line. Playwright emits state
+attributes before `[ref=]`, so every stateful control loses its handle. Measured:
+
+```
+button "Plain"    [ref=e10]              → ref KEPT
+button "Active"   [active]   [ref=e13]   → ref LOST
+button "Disabled" [disabled] [ref=e14]   → ref LOST
+button "Pressed"  [pressed]  [ref=e15]   → ref LOST
+button "Expanded" [expanded] [ref=e16]   → ref LOST
+checkbox "Checked" [checked] [ref=e17]   → ref LOST
+button "Cursor"   [ref=e18] [cursor=pointer] → ref KEPT
+```
+
+The controls most worth acting on and asserting about are exactly the ones stripped of their
+handle. **Keep every bracket group on a line.** No allow-list, no drop-list — parsing one group
+and discarding the rest is the whole bug, and any rule about which groups survive re-creates it
+the next time Playwright adds an attribute. This fix is a prerequisite for §1 tier 2 and enables
+§6.
+
+---
+
+## 8. Envelope hygiene
+
+- `used:` carries the winning line only — no concatenated ladder attempts, no comment lines. The
+  field run produced `I.click(".sidebar button:has-text("Workflows")")`, which is not valid
+  JavaScript, and a `// 1. Open dialog...` comment inside the code block.
+- `click` and `fill` stop labelling themselves `do` in `command:`.
+- `network.jsonl` is written and advertised only when requests were actually captured. It was
+  0 bytes across all 18 runs while being advertised in every envelope; an artifact line that
+  points at an empty file is worse than no line.
+- Research annotation overlays are removed from the DOM after use. The browser is shared with
+  playwright-cli, and leftover `Legend` / `e8` / `e10` nodes appeared in its next snapshot.
+- Commands stop requiring a URL when attached to a browser already on a page.
+- A redirect that preserves origin and path counts as navigation success. The app's
+  `/` → `/?session=<uuid>&ws=1` redirect cost 3m00s and eight attempts under the old heal path,
+  and a hard tool failure against a prima-owned browser — in an envelope whose own inlined ARIA
+  proved the page had loaded.
+
+---
+
+## Testing
+
+- **Unit** — envelope rendering with `### Changes` always present, including the `no change`
+  form and the combination with `### Verdict` / `### Answer` / `### Research`; compaction
+  preserving every bracket group across the §7 combinations and any order of them; ref-free
+  diffing (the six-phantom case must yield zero); descriptor selection without `workspaceDir`,
+  including the ambiguous multi-session error.
+- **Ref resolution** — a ref resolves to an attribute-based `clickXPath` matching exactly one
+  element, and still matching after unrelated siblings are added or removed; a ref that resolves
+  to zero or many fails rather than falling back to a guessed locator.
+- **Integration** — `do` prompt behaviour through the existing `@copilotkit/aimock` harness per
+  `docs/contributing/ai-integration-tests.md`: instructions performed and nothing beyond them,
+  per-instruction proof citation, unproven reporting. Fictional fixture data only.
+- **End-to-end** — against a local fixture: a ref named from the snapshot clicks the element it
+  names and no other; a failing `pw` returns `ok: false` with compact ARIA and never a
+  substituted action; attach to a live playwright-cli session with no descriptor editing; a
+  session-param redirect resolves as success.
+
+---
+
+## Decisions Log
+
+- Heal is deleted outright rather than constrained to same-target recovery. No flag, no opt-in.
+- `do` perception is a four-tier ladder: research map, ARIA with refs, compact HTML, vision for
+  click.
+- Refs come from Playwright's native `aria-ref=` engine. No eidx attribute stamping, so the
+  shared browser's DOM is not mutated.
+- Ref acting lives in `boat/prima/src/tools.ts`, not in core; `click` and `hover` are untouched.
+  Extending a shared tool would show Tester a `ref` parameter it can only fill by inventing one,
+  and would weaken `commands` for every caller.
+- A ref resolves through `WebElement` to an attribute-based `clickXPath`. The absolute positional
+  `xpath` is not a fallback — `fromRawData` never populates it on the live-locator path, and it
+  would be the fragile choice regardless.
+- A resolved `clickXPath` must match exactly one element. A dead or ambiguous ref is a failure,
+  never a fallback to guessed locators.
+- ARIA compaction keeps every bracket group. No allow-list of attributes to preserve.
+- Refs are a context artifact only, stripped before hashing and diffing.
+- Ref lifetime is one context injection; the loop re-snapshots on state-hash change.
+- Tier 1 reads maps via `getPreviousResearch`; the trigger is StateManager visit count.
+- Discovery matches on title plus liveness; `workspaceDir` is abandoned as a key.
+- Attached mode connects with `descriptor.playwrightLib` first, because connect succeeds across
+  builds but `ariaSnapshot` does not.
+- The playwright pin moves to `^1.62`.
+- `verify` reports inexpressible assertions as inexpressible, never as failures, and does not
+  record them as verifications — a claim that could not be checked must not be remembered as
+  one that failed.
+- `do` carries a prima-shaped `context` tool that descends the ladder — fresh refs first, capped
+  markup on a repeat call. The shared `context` from `createAgentTools` is not reused: it returns
+  a ref-less tree and an HTML dump.
+- The baseline snapshot is captured lazily when a command needs a diff, not in `start()`, which
+  runs before a page is loaded.

package/docs/superpowers/specs/2026-08-18-prima-false-verdicts.md

@@ -0,0 +1,159 @@
+# Prima False Verdicts — No Reload, Vision-Confirmed Outcomes, Unconfirmed ≠ Failed
+
+**Date:** 2026-08-18
+**Status:** Implemented
+**Follows:** `2026-08-07-prima-fixes-design.md`
+**Evidence:** field feedback from an orchestrator driving prima over eight calls
+
+## Problem
+
+Prima returned verdicts that did not match what happened, in both directions.
+
+- `prima do` reported `error: open: <instruction>` for clicks that had landed. The caller only
+  found out by screenshotting anyway — which is the cost the boat exists to remove.
+- `prima check` returned `ok: false` for an environmental reason and said nothing about it.
+- No command answered a visual question with a verdict. `check` and `verify` never read a
+  screenshot; `ask` read one but returned prose.
+
+The skill tells callers to trust `### Result`. A false red trains them out of that, and then the
+greens stop meaning anything either.
+
+## Mechanisms found
+
+1. **`check` reloaded the page before checking it.** `prima.check()` → `tester.test()` →
+   `runTestSession` → `explorer.visit(task.startUrl!)` (`tester.ts:192`, unconditional) →
+   `I.amOnPage()` (`explorer.ts:431`) → `page.goto()`, which reloads even on the same URL.
+   `task.startUrl` is the page the caller is already on. Any transient state — an open dialog, a
+   selected tab, an unsaved form — was destroyed by the command asked to inspect it. This was
+   guaranteed, not a race with a dev-server reload.
+2. **`check` could not say why it failed.** `reportEnvelope` never sets `failure`, and
+   `envelope.steps` was built only from notes with `status === FAILED`. An abort produced
+   `ok: false` with an empty Steps section and no Failure section.
+3. **`do`'s verdict was the model's bookkeeping, not the page.** An instruction the model never
+   passed to `completed()` was rendered as an error, so an envelope could show every step green
+   and `ok: false` at once. `settleLedger`'s `.catch(() => null)` made a provider error
+   indistinguishable from a model that would not report.
+4. **Vision routing was per command, not per question.** `verify` produced DOM assertions only;
+   `check`'s verdict came from that same tool plus `settleExpectations`, which judged a text log.
+   The `inexpressible` branch told the model to "check it with `see()`" with no model in the loop
+   to act on the suggestion.
+5. **`prima status` printed the page tree.** `saveStatus` stored the full compact ARIA under
+   `changes`, so the command whose job is to cite artifact paths dumped the tree inline instead.
+
+## Changes
+
+### 1. `check` starts where the caller is
+
+`Tester.test(task, opts)` takes `startOnCurrentPage`, which skips the initial visit. Prima passes
+it. Nothing else changes for the explore flow, where reload-to-start-url is intentional.
+
+`reset` needs no guard: it already refuses when the current URL equals the start URL, which is
+the case for a check that starts in place. Once a check has navigated away, resetting back is
+the right behaviour anyway.
+
+### 2. The screenshot is the proof, and a disagreement is a finding
+
+`settleExpectations` is called from exactly one place, `prima.ts`, so it is prima's final judge
+and can change without touching the explore flow. It now takes the final `ActionResult` and, when
+that carries a screenshot and a vision model is configured, settles every outcome in one
+structured call on the vision model with the image attached.
+
+The screenshot is not one of two equal inputs. An outcome is satisfied when the page shows it to
+somebody looking at it; the log only says what the run did. The prompt says so.
+
+**Where the two disagree, the judge does not choose.** It reports `contradiction` and says what each
+side shows. An assertion that matched an element nobody can see is a defect in the application, and
+it is exactly the case both other verdicts destroy: `passed` hides it behind an assertion that
+happens to match, `failed` mislabels a feature that half works. It comes back as its own status
+with both sides quoted, it fails the command, and `### Artifacts` names the html, aria and screenshot
+on disk so the caller can settle it on the page itself rather than on the judge's word.
+
+**Absence in the picture is not a contradiction.** Review of the first pass raised this: a
+screenshot is not proof that a thing is missing, only that the judge could not make it out. A
+contradiction now requires the picture to show something *incompatible* — a list visibly empty, an error
+where a result was expected, the old value still displayed. "I cannot find it" is `unverified`,
+which does not fail the command.
+
+The screenshot is the final page only. An outcome the run established earlier stays established
+even when the page has moved past it, and the prompt says that is not a contradiction — otherwise every
+"record deleted, then navigated away" scenario reports one.
+
+### 3. `check`'s verdict is its outcomes
+
+`ok` no longer comes from `tester.test()`'s success flag, which could contradict the outcomes
+printed beside it. `ok: true` when no outcome failed and none was contradicted; each failure and
+each contradiction names itself in `### Failure`. `unverified` is not a failure — it is a statement about
+the run, matching what the help text already promised.
+
+A run that could not complete is reported separately from an application failure: when the test
+never finished or was skipped, the envelope says the run established nothing and cites the last
+step recorded.
+
+### 4. `do` distinguishes failed from unconfirmed
+
+`ok` is a function of what ran, not of the paperwork. An action error or a `blocked()` fails the
+command. An instruction the model never reported becomes a `??` row in `### Steps` — the actions
+that ran are listed above it — and does not fail the command. An AI error while settling the
+ledger is reported as its own step rather than attributed to the instruction.
+
+The `<proof>` block gains one general line: how much of the page moved is not evidence of whether
+something happened. A change confined to one region proves an instruction as well as one that
+redraws everything.
+
+### 5. `verify` reaches for vision when no assertion can express the claim
+
+The `inexpressible` branch now judges the claim from a screenshot and reports the judgement,
+instead of dead-ending on a suggestion nothing acts on. Because Tester's `verify` tool calls the
+same `navigator.verifyState`, this covers `check` as well.
+
+`Prima.visionEnabled()` also honours `Stats.visionDisabled`, so a session that lost vision
+mid-run stops claiming to have it.
+
+### 6. `status` cites artifacts instead of reprinting the page
+
+The ARIA blob is gone from `status.json`. `status` returns the page block and the artifact paths,
+which is its whole job.
+
+## Decisions Log
+
+- `check` starts on the current page. A command that inspects transient UI must not destroy it.
+- Vision is not a fallback in `check`; it closes every run that has a vision model. The
+  screenshot is the proof — what a user can see — and the run log only says what was done.
+- A disagreement between the picture and the run is reported as `contradiction`, never settled one
+  way. An assertion matching an element nobody can see is a defect, and both `passed` and `failed`
+  would bury it. A contradiction fails the command, and hands the caller the page files to judge on.
+  The word is `contradiction` rather than `conflict` because it names what happened, and rather than
+  `ambiguity` because that is what `unverified` already means.
+- A contradiction needs the picture to show something incompatible. Not finding something is `unverified`;
+  absence of evidence is not evidence of absence, and treating it as one is how a false-verdict fix
+  becomes a false-verdict generator.
+- Nothing probes the page to explain *why* something is invisible. A first attempt walked the DOM
+  comparing colours, sniffing screen-reader patterns and hit-testing every element; it was a pile of
+  heuristics guessing at an answer the contradiction already states. "The run says it is there and
+  the picture does not show it" is the finding, and the caller is better placed to say why.
+- `settleExpectations` judges all outcomes, not only undecided ones, when it has a screenshot —
+  otherwise a DOM assertion the run already made could never be contradicted by the page.
+- `unverified` is not a failure, in `check` outcomes and in `do` instructions alike. A statement
+  about the run is not a statement about the application.
+- Bookkeeping is not evidence. `do`'s `ok` follows actions and blocks; an unreported instruction
+  is surfaced, never rendered as an error.
+- A run that could not complete is reported as such, never as an application failure.
+- `provider.getVisionModel()` is added for symmetry with `getModelForAgent`/`getAgenticModel`;
+  `processImage` returns free text and cannot carry a per-outcome verdict.
+- A failed vision judgement falls back to the text model and flips `Stats.visionDisabled` — the
+  existing global for "vision is not usable this session" — which prima reads through
+  `visionEnabled()`.
+- No line reports which evidence the judge had; that is plumbing. Only the degraded case is
+  stated, as a `### Warning`, because only that case is a fact the caller must act on.
+- The verdict vocabulary lives in `prima <command> --help`. A marker the caller can see in an
+  envelope but cannot look up is not documented.
+
+## Not done
+
+- `explorer.beginTest` still calls `closeOtherTabs()`, so `check` closes other tabs of an
+  attached session. Guarding it means threading an option through `beginTest`, which every flow
+  shares.
+- `do` gets no vision confirmation pass. Its `completed()` proof is the same kind of unverified
+  paperwork, but a per-instruction vision call is a different cost profile.
+- The `prima` skill in `testomatio/skills` documents the old envelope vocabulary. It needs the
+  `??` row, the `CONTRADICTION` status, and the unconfirmed-is-not-failed rule.