# 0027. Verification is scoped to the change

- **Status:** Accepted
- **Date:** 2026-08-08

## Context

Two rules were missing from opposite ends of the same question.

`docs/TESTING.md` said when the suite *has* to run, but never when it should not — so the suite got run on
documentation changes, where it cannot see the change and proves nothing.

`docs/WORKFLOW.md` §3 listed what is measurable without a browser — HTTP responses, rendered markup, headless
Chrome screenshots, the built bundle in jsdom — inside a paragraph about handing over a review summary. It
answered "what is possible" and never "which of these should I have used", and two of the four items turned
out not to be possible here at all.

## Decision

**A gate or a verification method is chosen by what it can actually see, and the cheapest sufficient one
wins.**

- `docs/WORKFLOW.md` gains a **Which gates run** table: nothing for documentation-only changes, `composer
  test` for PHP inside the tested surface, nothing automatic outside it — *said out loud in the review rather
  than left to imply coverage* — and `composer test` before every push without exception. The principle:
  **a gate that cannot see the change proves nothing and costs minutes.**
- The verification list moves out of §3 into its own document, [VERIFICATION.md](../VERIFICATION.md),
  structured as the gates / behaviour / pages in a browser / what needs the developer's eyes, and led by the
  rule: **pick the cheapest method that proves the change, and stop there.** Rough order, cheapest first:
  read the file → assert in a test → `curl` the response → crawl → ask him to look.
- **What is unavailable is documented as explicitly as what is available.** Verified on this machine, not
  assumed: `curl` reaches `raktar24.dev.hu`; the Chrome DevTools MCP connects but navigation to the dev vhost
  fails with `net::ERR_BLOCKED_BY_CLIENT`; the bundled Chrome binary does not start (`libnspr4.so` missing);
  jsdom is not an npm dependency. There is therefore **no screenshot, no viewport check, no Lighthouse and no
  way to execute the page's JavaScript here.**

## Alternatives

- **Leaving the list in WORKFLOW.md and adding the rule there.** The section is about handing over a summary;
  the list had already outgrown it, and a reader looking for "how do I check this" would not open a document
  called Workflow.
- **Running the full suite always, for safety.** It is under a second, so the cost is not the runtime — it is
  the false signal. A green run on a change the suite cannot see reads as proof and is not one.
- **Assuming the browser tooling works because it works in the sibling project.** It does not; that
  assumption is what this ADR replaces with measurements.

## Consequences

- "Could not verify" becomes a checkable claim: it is only honest for the last two sections of
  VERIFICATION.md. Everything else means "did not check".
- The unavailable-browser section is machine-specific and will go stale silently if the environment is fixed.
  It carries the date it was measured and an instruction to correct it rather than rediscover it.
- Layout, hover and focus, JavaScript behaviour and anything visual land on the developer permanently, not
  occasionally — the phase review has to name which part is his every time.
- The `<source>` allowlist in `phpunit.xml.dist` is fourteen files. The workflow now states that a green suite
  says nothing about the several hundred others, instead of letting the passing run imply it.