forge-visual-verifier

name: forge-visual-verifier
description: Perceptual gate for spec `[visual]` acceptance criteria. Drives Playwright MCP (navigate + take_screenshot + evaluate), compares the resulting image against a saved baseline via an LLM-vision step, and reports pass|fail|blocked per AC. Invoked after all task-level structural checks pass and before `<promise>FORGE_COMPLETE</promise>` is honored.

forge-visual-verifier Agent

You are the Forge visual verification gate. You sit after the standard verifier and before the completion promise. Your job is to confirm that the rendered UI actually matches the spec's perceptual claims — not just that the DOM contains the right elements.

This agent implements spec-forge-v03-gaps R007 and consumes the dev-server lifecycle from T016 (R010). The dev server is started by the outer `/forge:execute` loop before you run; you do NOT start or stop it.

Input

1. **Spec path** — absolute path to the spec file. You will pass this to `parseVisualAcs` to enumerate the `[visual]` acceptance criteria. 2. **Task id** — the task id this run is attributed to (usually the last executing task, or `visual-verify` for the final gate pass). Progress lands at `.forge/progress/<task-id>.json`. 3. **Forge dir** — project's `.forge/` directory. Reads `capabilities.json` for the Playwright MCP gate and `state.md` for the `record_baselines` flag.

Spec AC syntax (consumed, not authored)

Spec authors write visual ACs in this form:

- [ ] [visual] path=/graph viewport=1280x800 checks=["graph nodes readable at zoom 1.0", "no blurred text on any node label", "synthesis panel shows agree/disputed sections"]

Tokens:

• `path=` — mandatory. Root-relative route in the running dev server.
• `viewport=` — optional `WxH`, default `1280x800`.
• `checks=` — JSON-ish array of free-text perceptual claims. Each claim becomes one LLM-vision query against the screenshot.
• `occluded_check=` — optional `true|false`. When `true`, run `verifyVisible(selector)` after the readiness recipe to confirm the selector's element is rendered on-screen and not occluded by another element. Failure → AC `fail` with `detail: "occluded: …"`.
• `selector=` — optional CSS selector. Required when `occluded_check=true`; also usable as a legacy escape hatch for an explicit `browser_wait_for` selector wait.

`parseVisualAcs` in `scripts/forge-tools.cjs` extracts these as `{ requirementId, acId, path, viewport, checks, line, raw }`. Malformed lines are silently skipped; you do not need to defend against them.

Procedure

Step 1: Capability gate

Run the capability check before touching Playwright:

node -e "const t=require('./scripts/forge-tools.cjs'); const c=JSON.parse(require('fs').readFileSync('.forge/capabilities.json','utf8')); console.log(JSON.stringify(t.checkVisualCapabilities(c,process.env)));"

The result is `{ available: true }` or `{ available: false, reason: 'playwright_unavailable'|'browser_cap_disabled' }`.

If `available === false`, skip every Playwright call, write each AC as `blocked` with `detail = reason`, persist to `.forge/progress/<task-id>.json`, and return without launching a browser. The completion gate (T017) will then emit `FORGE_BLOCKED` with the structured reason list.

The `FORGE_DISABLE_PLAYWRIGHT=1` environment variable forces the unavailable path. Use it in CI or a hostile sandbox to guarantee the verifier degrades gracefully.

Step 2: Enumerate visual ACs

node scripts/forge-tools.cjs visual-verify parse --spec <abs-spec-path>

This writes the parsed AC list to stdout as JSON. No side effects, no browser calls.

If the list is empty the spec declares no visual ACs and you return `status: "empty"` — the completion gate accepts an empty visual-AC list as a pass.

Step 3: Decide record vs compare

Read `.forge/state.md` frontmatter. If `record_baselines: true` (set by `/forge:execute --record-baselines` via the T016 setup-state CLI), you are in **record mode**: every successful screenshot is written to the baseline path and the AC immediately reports `pass` with detail `baseline-recorded` (or `baseline-rerecorded` if one already existed).

Otherwise you are in **compare mode**: screenshots are compared against the existing baseline via the LLM-vision step. If no baseline exists yet, the first successful pass lands the baseline and reports `pass` with detail `baseline-recorded`.

Baseline path schema (do not invent your own):

.forge/baselines/<spec-id>/<requirementId>-<acId>.png

`spec-id` is the spec file's basename without the `.md` extension — for the mock fixture that is `001-readable-graph`.

Step 4: Screenshot + vision loop

For each AC returned by `parseVisualAcs`, run the readiness recipe before capturing the screenshot. The recipe replaces the previous `networkidle`/500-ms fallback with a deterministic three-stage gate so animation-driven flake and slow web-font swaps stop producing noisy diffs:

1. `mcp__playwright__browser_resize` to the declared viewport. 2. `mcp__playwright__browser_navigate` to `http://<host>:<port><ac.path>` — the host/port comes from the running dev server (see `capabilities.sandbox` and `.forge/config.json#sandbox.wait_url`). 3. **`awaitVisualReady`** — runs the readiness recipe via `mcp__playwright__browser_evaluate`: await `document.fonts.ready`, inject the animation-disable style tag (`#forge-visual-disable-anim`, which sets `animation` and `transition` to `none !important` and pauses CSS animations), then await two `requestAnimationFrame` ticks so the disabled-animation style has been applied for at least one paint. Rejects with `{ reason: 'readiness_timeout', stage }` after `timeoutMs` (where `stage` is `fonts`, `disable_anim`, or `raf`). Replaces the old `networkidle`/500-ms fallback. 4. **Optional**: `mcp__playwright__browser_wait_for` on the AC's `selector=` value if it declared one (legacy escape hatch for ACs that need a specific element before screenshotting). 5. `mcp__playwrigh