git:20260917.4faca15 to git:20260922.913f49e

- description: Fires when verifying a change by driving a running app in a browser — session artifact naming, evidence capture, and the report.md contract other tooling reads. Load this whether you're the dispatched QA persona, an ad-hoc browser-verification task, or the lead doing it directly.

- Drive the running app with a browser tool of your choice; open the app, observe the accessible surface, perform the affected flow, and capture screenshots as evidence. Never read markup or reason about code instead. Read-only re: code — never edit, that routes back to lead.

-

- ## Steps

-

- 1. **Find the app.** Port via `source .envrc && echo $PORT`, else 3000. Confirm the server responds before any browser action. Not running → report and stop, don't guess.

- 2. **Identify affected flows** from the dispatch. Check the project AGENTS.md for selectors and credentials.

- 3. **Check for a linked Figma design** — read the pull request description for a `figma.com/design|file` URL, then inspect the dispatch focus. Found one → visual fidelity becomes an acceptance dimension: open the reference with a browser tool when accessible and compare layout, spacing, and copy against the live UI. If it is unavailable, record that limitation.

- 4. **Capture evidence as you go** (below).

- 5. **Map every piece of evidence to an acceptance criterion** — in your return message and in `report.md`. Design findings map to the AC of the flow they verify.

- 6. **Report pass/fail with specifics**, including the design verdict when a design was checked.

-

- ## Session audit trail

-

- ```bash

- SESSION_DIR="$HOME/.local/share/qa/$(basename "$PWD")/qa-$(date +%Y%m%d-%H%M%S)"

- mkdir -p "$SESSION_DIR"

- ```

-

- After **every** browser action: scroll into view with `tab.scrollIntoView()` or `tab.evaluate(() => window.scrollTo(0, 0))`, screenshot with `tab.screenshot()`, and capture the URL with `tab.evaluate(() => location.href)`. Record console errors when they appear.

-

- Write `$SESSION_DIR/report.html` — a self-contained local page, one section per step: screenshot, short title, one-line description, the page URL. Close it out and `open` it when testing is done.

-

- ## `report.md`

-

- Alongside the HTML, same session dir:

-

- - Heading `## 🧪 QA — PASS ✅` or `## 🧪 QA — FAIL ❌`. **Never rename it** — the verdict is parsed from this exact string.

- - Per verified flow, the acceptance criterion it covers.

- - Failure and final-state screenshots inline as **relative** refs ``; step-by-step in a collapsed `<details>` (blank line after `</summary>` or the inner Markdown won't render).

- - Page URLs as inline code, never links — they're local and non-navigable.

- - A `**Could not verify:**` line, or `none`.

- **The store contract is load-bearing.** `report.html`, the `NNN-name.png` names, the `~/.local/share/qa/<project>/qa-<ts>/` path, and `report.md`'s heading are read by the demo command and pruned by the cleanup job. Don't rename or relocate them. The publisher reads these local artifacts to create a pull request review body. Never write to the remote from here.

- ## Output

- Verdict per flow (not "looks fine"). Flows exercised and states confirmed, with screenshot refs. Failures with exact repro steps, expected vs. observed, URL, console errors — a failure without repro steps isn't actionable. What you couldn't reach, and why. The `$SESSION_DIR` path.