---
name: "skill-review-pr"
type: skill
description: Review a Claude Code pull request for Aled and write a plain-language verdict he can act on without reading the code. Use this whenever running the qa routine, or when a ticket in In Review carries PR-1SM — read the PR against the ticket's embedded acceptance criteria and report either a clean summary with DoD confirmation, or the full set of changes the exec agent needs, stating the defect and the acceptance bar rather than handing over a patch to paste. Where QA stands a service up to verify against, prove the artefact answering is the one this run built before asserting anything about its behaviour. Apply this rather than reviewing ad hoc; it never merges or advances the ticket. Trigger it whenever the task is to QA, review, or sanity-check agent-written code in a Linear context.
license: CC BY-NC-SA 4.0
---

# qa

The QA / review role of the Claude Code loop — the extra pair of eyes that makes a change reviewable by Aled without him reading code. Runs as a polling Cloud Routine. Follows convention-linear and the gate policy (Aled is the approver; nothing merges without him).

## Trigger

Poll for issues in In Review carrying `PR-1SM` (set by the exec leg). Delivery projects only.

## Dedup — one review per PR state

Before reviewing, check whether a verdict already exists for the current PR head commit. The check is keyed on the commit SHA, not elapsed time, so qa still re-reviews after an In Review → Todo bounce where exec pushes new commits.

1. **Fetch the PR's current head commit SHA.**
2. **Scan existing GitHub PR comments** for any comment that starts with `[qa] HEAD: <sha>` where `<sha>` is the current head commit SHA (first 7 characters). Use this as the dedup key.
3. **If a match is found:** skip silently — no comment, no state change. The verdict already exists; Aled's gate is the next action.
4. **If no match:** proceed with the full review below.
5. **Before assessing, post a `[qa] REVIEWING HEAD: <sha7>` marker on the Linear ticket and on the PR.** A merge is fast and a review is slow — a pass can take half an hour — and nothing else tells the person holding the merge button that a review is open against the commit he is about to merge. The marker is one line, advisory, and gates nothing: it blocks no merge, creates no wait state, and the Owner may still merge his own repository whenever he likes; it only makes the open question legible on the surface he is already reading. The verdict comment supersedes it. It is deliberately not the dedup key — `[qa] HEAD:` is — so a marker with no verdict following it at that head is simply the driver's existing no-parseable-verdict route, not a new state, and a run that finds a marker and no verdict re-reviews as normal. (Worked case: APP-942 / `bot-trader` PR #35, 2026-08-18 — QA dispatched at ~11:05 against `668e12c9` after a non-trivial conflict resolution moved the head; the Owner merged at 11:17:47; the clean verdict landed at ~11:32, fourteen minutes after the merge, with nothing anywhere indicating a review was in flight — APP-1022.) **The marker cannot stop a concurrent sibling, so re-read for one immediately after posting your own.** Having posted the `[qa] REVIEWING HEAD: <sha7>` marker, read the PR's comments again for a sibling `[qa] REVIEWING HEAD: <sha7>` marker at the same head. Where one exists whose timestamp is **earlier** than your own, stand down: post a one-line withdrawal naming the earlier marker and its timestamp, and do no review — no clone, no job refetch, no verdict. This is a **post-post re-read, not a pre-flight check**: a pre-flight read is exactly what both legs in the worked case below already did, and both correctly saw nothing, because neither marker existed yet when either leg looked. The rule above is unchanged — a marker with no sibling and no verdict at that head is still not the dedup key, and a lone run still re-reviews as normal. What this clause covers is only the narrow window where two legs post within seconds of each other, which the marker-as-key rule cannot see because both markers appear after both legs have already read. The larger remedy — a dispatch-side guard that never spawns a second QA leg for a head already in flight — is the structural fix and is **not** authored here, so this clause is not the whole answer. (Worked case: APP-1455 / `bot-trader` PR #57 — two QA legs reviewed head `2957aad` concurrently, both posting the `REVIEWING` marker, at 14:14:37Z and 14:14:39Z, two seconds apart; both then completed full reviews and posted same-key verdicts at 14:16:30Z and 14:18:57Z. Both were clean and agreed, and the PR merged at 14:19:56Z on the first. The cost was one entire duplicate review — a fresh clone, fourteen runs' jobs refetched, an actionlint Go build — plus two same-key verdicts on one head. Identifiers and timestamps as reported from the filing leg's live GitHub API reads. APP-3083.)

Every verdict comment **must** begin with:

```
[qa] HEAD: <sha7>
```

where `<sha7>` is the first 7 characters of the PR head commit SHA. This line is the dedup key.

**A matched key is not always a settled verdict — where the ticket's own acceptance criteria changed at a static head, the leg re-reviews rather than skips.** Step 3's skip-silently is right for the case it was written for: the head is the state of the code, so an unchanged head means an unchanged change and a verdict that still holds, and that is also what makes the key correct across a bounce that pushes new commits and across the several-PRs primary-key form above. It is wrong for the one case where the **bar** moved and the code did not — an acceptance criterion corrected, added or struck on the ticket after the verdict was posted, with no push in between. The standing verdict was then measured against criteria that no longer exist, and skipping leaves it standing as the merge gate's own evidence at a head nothing will ever move again, so there is no route back to a review. So before skipping on a matched key, compare the matched verdict comment's own timestamp against the ticket's `## Acceptance criteria` section as it now reads, and where that section has changed since the verdict was posted, **re-review instead of skipping** and post the marker in its criteria-changed form — `[qa] REVIEWING HEAD: <sha7> — criteria changed since prior verdict`, one line, advisory and gating nothing like every other marker, so the surface says why a second review is open at a head that did not move. A matched key over an unchanged criteria section still skips, exactly as step 3 says. **And where two verdicts share one key, the later governs.** The escape above makes two same-key verdicts a reachable state rather than an anomaly, so the tie-break is stated in the section that defines the key: the operative verdict at a head is the most recent `[qa] HEAD: <sha7>` comment at that head on the surface being read, and the earlier one is superseded record, so a merge leg that meets two needs no adjudication of its own. The `skill-merge-pr` half of this is **deliberately not authored this pass**, as a how/where ruling rather than an omission: the key is defined here, the merge leg already reads the definition here, and a second home for one rule is the redundant-paragraph defect `APP-2845` reports. The dated condition on that ruling — if a merge leg reports meeting two same-key verdicts with no governing rule on or before **2026-12-05**, the ruling was wrong and a `skill-merge-pr` clause becomes warranted. (Worked case: `APP-2883` — a bounce corrected the ticket's own acceptance criteria with no new commits, the head stayed static, the matched `[qa] HEAD: <sha7>` key sent the next QA leg down step 3's silent skip, and the merge leg then held two verdicts sharing one key with nothing in canon saying which of them governed. Every repo-side figure in that account is the filing leg's **report**: confirm the head SHA, the pull request number and both comment ids against the repo before writing any of them into a verdict — expected the head SHA identical across both verdicts and two distinct comment ids at that one head, as reported. The premise is **unverified** here — `gh api user` returns 200 as `assoc-one` while an unattached repository, a public one included, returns 403, so no repo, pull request or comment body is readable from the authoring surface, and a flag on one of those figures implies nothing about the others.)

**Where a ticket spans several PRs, the key names a primary PR.** An estate-wide sweep — one ticket, N repos, N PRs — has N heads and one key. Where the ticket body **enumerates every PR and its head**, the verdict names one **primary PR** (the PR the ticket turns on) in the `[qa] HEAD: <sha7>` line and lists every PR and head in the verdict body; the review reads the union of the diffs and returns one verdict for the ticket. Read literally, one key against N heads fails for N−1 of them and re-queues a clean ticket back to QA forever. The key exists to stop a merge firing again against a head no verdict covers (APP-832), not to bound a ticket to one PR, and the primary-PR form preserves exactly that: the merge leg tests the primary key and reads the enumeration for the remaining heads (`skill-merge-pr` carries the same rule from the merge side). (Worked case: APP-1111, 2026-09-04 — one ticket across 14 repos and 12 PRs; QA keyed on `claude-ops` and enumerated all twelve heads in the verdict body, correctly but by invention in the moment. Three more of the shape are foreseen — the APP-1125 CI rollout, a lint-config rollout, a dependency bump — APP-1126.)

## Behaviour

Read the linked PR / diff and the two embedded checkbox sections — `## Acceptance criteria` (the per-ticket conditions) and `## Definition of done` (the standing per-type bar, Pattern A). **Walk every box in both sections in turn**: confirm each is both ticked (`- [x]`) and genuinely met by the change, and call out any box that is blank, ticked-but-unmet, or unmet-and-unticked. Verify the definition-of-done boxes against the ticket's `type:` DoD template, not merely that they are ticked. "Definition of done confirmed" means every box in *both* sections ticked and genuinely satisfied — not a general thumbs-up. A box the exec leg left blank is one of two things, and the two are not routed alike. **A blank box exec should have closed** — work it did not verify or skipped — is a changes-needed signal, never something QA ticks on the builder's behalf. **A blank box whose truth-maker lands after hand-off** — a *"CI present, concluded, green"* box where CI genuinely concluded after the PR opened and is green at the current head, or the *"Review verdict posted — Prism's"* box, which is this verdict — is closed by QA on **its own verification**, recorded in the verdict as QA-closed, and never on the builder's word; the merge leg records the verdict box on the same evidence (`skill-merge-pr`, APP-736). The prohibition is unchanged — QA never ticks on attestation — but a condition that is genuinely met and could not have been ticked earlier is not builder debt, and bouncing a complete PR for it costs a full exec cycle for no change. (Worked case: APP-1023 / PR #181 and APP-986 / PR #180, 2026-08-18 — two consecutive runs verified CI concluded green at head, the hand-off state and the verdict, ticked the boxes with a note that QA closed them on its own check, and had to reason against the letter of this paragraph to do it — APP-1025.) Then:

1. **Post the verdict comment on the Linear ticket** (so it's in the canonical record). Begin the comment with `[qa] HEAD: <sha7>`.
2. **Post the same verdict comment on the GitHub PR** (so it's visible where Aled reviews and approves). Begin the comment with `[qa] HEAD: <sha7>`.
3. **Mark the PR as Ready for Review** (convert from draft) — draft signals WIP; a clean QA pass signals it's awaiting human sign-off.

**Both writes have a route that works and an obvious one that does not.** The GitHub MCP is the canonical route and is the only one on a surface where `gh` is absent (`convention-github`, *GitHub MCP tools*): `mcp__github__add_issue_comment` posts the verdict, with the body inline. Where `gh` **is** present, the two natural commands both route through GitHub GraphQL, which returns **HTTP 403** on these surfaces — `gh pr comment` for the verdict and `gh pr ready` for the draft flip — so reach for the REST forms directly rather than discovering the 403 per run: `gh api repos/{owner}/{repo}/issues/{n}/comments -F body=@<path> --jq '.id, .html_url'` for the comment, which is also the only form that takes a long verdict from a file rather than retyped into a tool argument (and an **observed footer-appending path**, so being the only form that takes the verdict from a file is no reason to trust what it stored: taken on a QA verdict it has appended the generated-by footer below the verdict's own last line, where it reads as part of the verdict. Read the comment back and **diff** its trailing bytes, per the read-back rule below, and where the diff differs strip the appended footer from the body and write the stripped body **once**, then disclose — because **no comment route on this surface stores byte-exact**. The inline `mcp__github__update_issue_comment` repair this sentence previously named as the clean route has itself now been observed appending the generated-by footer, and `convention-github` has retracted the claim that it is the one comment route storing what was sent (`APP-2888`; that account is the filing leg's **report** and is unverified here). With no clean comment route left, a second write buys a second footer rather than a clean body, and the repair that remains is one write and a disclosure: strip, write once, read the stored body back and diff its trailing bytes by the parsed-JSON `body` instrument `convention-github` prescribes — never `gh api … --jq .body`, whose trailing newline manufactures a false red in exactly the region under inspection — and where the stored body still differs, **say so on the Linear ticket**, naming the route taken, the appended line and the head, rather than writing a third time. The ticket is the canonical record and prose there survives what a byte-exact carrier cannot, so a disclosed footer costs a reader one sentence while a patch loop costs the comment its integrity. Read the `APP-2745` worked case below accordingly: that one re-write stored the body byte-identical, which is an **observation of one instance** and never a property of the route, and `convention-github`'s *Attribution bytes at the end of an agent-authored body are rewritten in transit* holds the path list and the direction each route has been seen to mutate in. The same retraction reaches the read-back obligation in *Read-backs* below and the pull-request-body bullet in *Guardrails*, both of which already point at that section for the route list rather than naming one here. Confirm the comment id and the head SHA against the repo before writing either into a verdict — expected the values the filing leg reported; **unverified** here, `gh api user` returning 200 as `assoc-one` while an unattached repository returns 403, so no repo, pull request, comment body or GitHub API response is readable from the authoring surface, and the GitHub MCP is not attached on it either, so the tool name above is **unverified** as written. **This names the risk and re-ranks nothing**: the MCP comment create is recorded appending the footer too, and `convention-github` rules that *"picking a route is a guess about a mechanism nobody has identified, and reading back is a measurement"*, so take the path list and the direction each route has been seen to mutate in from its *Attribution bytes at the end of an agent-authored body are rewritten in transit* rather than reasoning from this line. Third instance on this root after APP-2507 and APP-2644, both closed — the APP-2745 QA leg, `assoc-one/claude-ops` PR #571, head `3d609e1`, 2026-10-29: 5,481 bytes sent against 5,540 read back, caught by the read-back diff, and the re-write through the MCP comment update stored the body byte-identical. Those figures are the filing leg's **report** and are unverified here, no repo, pull request or GitHub API response being readable from the authoring surface; that `convention-github` records both the REST comment POST and the MCP comment create appending the footer is **observed**, corroborated against live canon this run — APP-2749), and the CCR route `POST /repos/{owner}/{repo}/pulls/{n}/ccr/ready_for_review`, which returns `{"draft":false}`. The 403 message names the CCR routes itself, so recovery is self-documenting once seen — the cost is that it must be seen, once per run, on a step every QA pass takes twice. Read the write back from each surface afterwards, per the read-back rule below. **For the draft flip, lead with the GitHub MCP as well** — `mcp__github__update_pull_request` with `draft: false`, the same route as the comment write — wherever the MCP is present, whether or not `gh` is; the CCR REST call above is the fallback. On some surfaces the CCR call never reaches GitHub: the Claude Code auto-mode permission classifier denies it as `[External System Writes]`, so no 403 comes back and the self-documenting recovery above never fires. A classifier denial is a route closed on this surface, not a GitHub error to retry. **And each route closes on a different surface, so the fallback is tried either way rather than only after a classifier denial.** The paragraph above ranks the MCP flip first because the CCR call has been denied on this surface; the reverse has now also been seen, so neither route is the reliable one and the ranking is a starting order, not a prediction. `mcp__github__update_pull_request` with `draft: false` has failed **twice in ten seconds** with GitHub's own server-side `Failed to mark pull request ready for review: Something went wrong while executing your query` — not a classifier denial, not a 403, and therefore not self-documenting — and the CCR call that this file names as the fallback then returned `{"draft":false}` first time. So on **either** route's failure, take the other immediately; two attempts at the same route is the cost this clause exists to stop. **And a combined MCP call is not atomic, so the draft flag is read back on its own.** On the first of those two failures the same call also carried a body edit, and the body edit **landed** — read back byte-identical — while the draft half failed: a call that reports failure can still have written half of what it was given. So never infer the flip from the call's result, never infer it from the body having landed, and read `draft` back as its own value from the connector's own read tool (`convention-github`'s *"picking a route is a guess about a mechanism nobody has identified, and reading back is a measurement"*, which this applies to a call that does two things at once rather than to a choice between routes). (Worked case: the APP-2779 QA leg, `assoc-one/claude-ops` PR #590, head `c5a827e`, 2026-10-30 — MCP flip failed at 14:22:31Z and 14:22:41Z with GitHub request IDs `C05D:386E22:161AF7:174986:6AE4A822` and `202D:19F1CA:1289CC:13C732:6AE4A82D`; `gh api -X POST repos/assoc-one/claude-ops/pulls/590/ccr/ready_for_review` returned `{"draft":false}` first time and the read-back confirmed it. One instance, two attempts. The pull-request number, head SHA, timestamps, request IDs and byte figures are the QA leg's **report** and are unverified here — no repo, pull request or GitHub API response is readable from the refine surface, and the GitHub MCP is not attached on it either, so the tool name is **unverified** as written — APP-2791.) (Worked case: MBN-305 / `mbn-theme` PR #16, head `ddc83c2` — the CCR call was denied by the classifier and the MCP flip worked first time, as it did again on MBN-309 (APP-1544); CCR had worked on another surface on 2026-09-14 (APP-1444), so the denial is surface-dependent — APP-1545.) (Worked case: APP-1457 / `assoc-one/claude-ops#239`, 2026-09-14 — `gh pr comment --body-file` failed outright and the REST form carried the same body unchanged — APP-1461.)

Verdict comes in one of three modes:

- **Clean** — a summary of what was done plus explicit confirmation that **every box in *both* the `## Acceptance criteria` and `## Definition of done` sections is ticked and genuinely met** (the DoD, verified against the type template). Enough for Aled to approve. **Then ask the merge-safety question before returning it: would merging this alone, right now, break something?** On unflagged work a clean verdict *is* the merge approval (APP-402), and the driver routes off the verdict line without re-reading the change — so AC-clean and merge-safe are two judgements and only the first is a checklist. Where the answer is that merging alone breaks something, the verdict is **not clean**: route it as the affirmatively-unmet external precondition above, naming what must land first and in what order. The instance to look for is cross-repo coupling — a change correct against a sibling repo's unmerged state, where merge triggers a deploy that reads that sibling at its current default branch. A deploy path that skips the guard CI runs is the shape that makes this invisible: CI red for an ordering reason and the deploy green on the same commit is not a contradiction to resolve in favour of the green. (Worked case: APP-1458 / `assoc-one/agents-site` PR #9, 2026-09-14 — all four criteria met and a byte-identical relocation control, while merging alone would have deployed a zero-artefact live site with a green build, 13 pages instead of 29 and all 16 agent pages gone, because `verify:links` runs only in CI and never on the deploy path — APP-1463.)
- **Changes needed** — log everything the exec agent needs to act on, **including any acceptance box left blank or not genuinely met**: specific, actionable, with file/line where it helps, so a bounce is self-contained. State the defect and the bar it must clear, not a patch to paste (see *Stating the defect, not the patch*). Any unticked or unmet box is by itself a changes-needed verdict — **where a change to the diff would close it.** That is the test before bouncing: *is there a change to the diff that would close this box?* If no, it is not exec's. A box that is **affirmatively unmet** — QA checked, and the answer is negative — because a deployment or infrastructure precondition outside the repo is absent (a Vercel environment variable not set on the project, a DNS record, a provider setting, or a sequencing dependency such as a sibling repo's branch reaching its own `main` before this one merges — the class is **any precondition outside the diff that must clear before merge**, not only a setting the Owner configures once) is not a bounce: the code is correct and exec cannot set the precondition, so a bounce burns a full exec cycle for a change that does not exist. Verify and state the code half in the verdict, name the precondition and the exact setting that closes it, and route it as the genuine external blocker it is — **Blocked**, label `human`(evicts`PR-1SM`), assign Aled, the comment leading with the setting to make — saying explicitly that merging before it lands ships the failure. This is the driver's *Block* row (`routine-delivery-loop`*Route per verdict*, the credential-or-account-only-Aled-holds branch), not sub-case (b) below: (b) is a box QA *cannot confirm*; this is one QA confirmed negative, with work outside the repo that must clear before merge. (Worked case: A1-350 /`assoc-one/assoc-one`PR #7, 2026-09-03 — the route read the published document correctly, the deployment lacked`NEXT_PUBLIC_SANITY_PROJECT_ID`, and QA had to reason against the letter of this sentence to avoid bouncing a correct diff — APP-1113.)

  **And the order can be the other way round — a precondition that clears *after* merge is In Review, not Blocked.** The route above assumes the precondition gates the merge. Where merging first is harmless because nothing the precondition governs is reachable until it exists — no deploy target, so no deploy to go wrong — the natural sequence is merge, then provision, then verify, and Blocked is the wrong state: it hides a merge-ready PR from the In Review queue that is the Owner's own sign-off surface. Settle it with the merge-safety question (*Clean*, above): would merging this alone, right now, break something? If no, and the unmet box needs an Owner action outside the repo, route it as operator-verify-only — **In Review**, label `human` (evicts `PR-1SM`), assigned to Aled, PR marked ready — stating the code half as verified, naming the provisioning step, and writing the order out as merge → provision → verify the URL. A new Vercel project is the standing instance: provisioning one is the Owner's where account-level access is genuinely needed and an agent's where a connector reaches it (`convention-vercel`), and either way the Owner confirms the production URL after merge, so an AC of the shape "deploys a placeholder page" is unmet at review time by construction and is not a defect in the diff. (Worked case: APP-1600 / `assoc-one/app.Foundry` PR #1, head `eb455f2`, 2026-10-01 — CI green at head, a pinned clone served HTTP 200, the one-file card pattern proven with a sentinel card plus a negative control, and two boxes unticked only because no Vercel project existed; the leg derived the In Review route live against a sentence that names Blocked — APP-1929.)

   Do not mark the PR ready for review if changes are needed — and where the PR is *already* non-draft (exec opens PRs as draft per `skill-build-ticket`, so this is the backstop for a PR that was opened ready), **convert it back to draft**. The draft/ready bit is the one signal Aled reads on GitHub without opening the Linear thread, so it must never sit at "ready" over a PR carrying blocking defects; leaving it ready on a changes-needed verdict inverts the signal exactly where it matters most (APP-822).
- **Unverifiable in this environment** — an acceptance box the code satisfies but that QA cannot confirm from its own sandbox. Two sub-cases, routed differently — do **not** collapse them:

  **First, separate a knowledge gap from a capability gap — they are not the same unverifiable.** A question about the documented behaviour of a third-party platform or vendor (does Vercel overwrite `x-forwarded-for`? does this API rate-limit per key?) is a **research task, not an environment limitation**: the session has `WebSearch` and `WebFetch`, and while a direct `WebFetch` of a vendor's docs is often proxy-403'd, `WebSearch` is not. So before classifying such an AC as unverifiable, **search it** — a fact answerable from public documentation is neither capability sub-case below, and calling it an environment limitation on the strength of a single blocked `WebFetch` sends the exec leg to re-engineer around a question one search would have closed. (Worked case: A1-310's `x-forwarded-for` question was raised as a blocking finding — "vercel.com returns 403 through the proxy" — after only a direct fetch was tried; a single `WebSearch` on the re-review answered it outright, a full bounce cycle later — APP-735.)

  **Fetch a Linear attachment through the connector before calling it unreachable — same shape, one blocked route is not no route.** Where an acceptance criterion turns on a Linear attachment — a canon publish ticket whose acceptance references Linear canon attachments or a digest-parity check — fetch the attachment bytes through the **Linear connector** (`mcp` Linear `get_attachment`), never a raw URL fetch or a `curl` of `uploads.linear.app`: the sandbox proxy 403s that host, so a raw-URL attempt fails on the *route*, not on the artefact. This is the same shape as the knowledge-gap rule above — one blocked route treated as no route — so try the connector before declaring an attachment unreachable; a blocked raw-URL route is the wrong route, not "unreachable". (Cross-reference APP-364, the exec-side sibling — APP-972.)

  **The guardrail says which route to use; it does not say what to do with the bytes.** Below the token cap the connector returns the attachment inline, and a reviewer that then hashes what it read is measuring its own transcription, not the artefact — there is no route from an inline read to an independent digest. State the boundary: the reviewer verifies the **committed file in the PR** against the ticket's declared digest, and re-hashing the attachment itself is the builder's step, not the reviewer's. Above the cap the spilled tool-results file is byte-exact and **is** the artefact — the same rule `skill-build-ticket` carries, and the reason the two skills must not diverge on it. (Worked case: each QA leg has been re-deriving this boundary live, at cost, rather than reading it — APP-1394, APP-1368.)

  **And the deployed skill cache is a live source, not a snapshot — so it is independent evidence only while it is older than the ticket.** Where a digest-parity or canon-publish criterion is cross-checked against the Claude-side deployed cache (`/root/.claude/skills/synced/…`) because the raw-attachment route is blocked, that cache reflects canon **now**; the ticket's attachment reflects canon **at ticket creation**. So read the cache file's mtime and compare it with the ticket's `createdAt` **before** treating any mismatch as evidence: a cache newer than the ticket is not an independent copy of what the PR committed, and "committed ≠ cache" is then ambiguous between a corrupted copy — the fault this cross-check exists to catch — and canon that has simply moved on. On a mismatch with a newer cache, resolve through the connector's attachment content and name the differing token, report the committed file as faithful where it matches the ticket's declared digest, and hand the newer cache on as a Claude-ahead item for the next parity run — never as a defect in the diff. The costly direction here is the false red: a correct PR one bounce from a wasted exec cycle, with the cross-check's own authority behind the wrong call. (Worked case: APP-1743 QA leg, `assoc-one/claude-ops` PR #296 head `96bcdec`, 2026-09-24 — three of four artefacts matched; `skill-time-block` matched the declared sha256 but not the cache at the same 16,959 bytes, differing in one token (`work.Standup` → `work.Unblock`), cache mtime 14:41Z against a ticket created 11:49Z, and the connector read settled it in the commit's favour. The precedent for using the cache at all is APP-1741's QA pass; the corrupted-copy signal it exists to catch is APP-1740 — APP-1759.) Premise unverified — the APP-1743 digests, byte count and the two timestamps are the filing leg's own report and were not re-read; that flag covers those figures only. The mechanism the rule rests on was verified at authoring time: the cache path exists on the QA surface and its mtime is readable (`skill-review-pr/SKILL.md`, 2026-09-25T03:39:33Z).

  **Drive a production build of the PR head in the sandbox's own Chromium before calling a hosted-URL criterion unverifiable — a third instance of the same shape.** The delivery sandbox cannot reach a Vercel preview or an estate domain (the egress proxy refuses CONNECT with a 403), so a criterion worded "verified on the preview" is unmeetable *by that route*. But the sandbox has a browser: Chromium is pre-installed under `/opt/pw-browsers `with Playwright pointed at it (`PLAYWRIGHT_BROWSERS_PATH`). So verify locally first — build the app from the exact head commit, drive that production build in Chromium (against a controllable stub of any upstream service where one is involved), run the negative control (*Proving the artefact under test*), and record the evidence. That satisfies a criterion whose property is the runtime behaviour of the change, and it is stronger evidence than a preview click-through, because a stub can be driven into the empty and error states a hosted preview cannot. Reserve the unverifiable classes below for the residue where the **hosted deployment itself** is what is under test — DNS, auth in front of the app, edge config, real upstream data — which is a genuine operator hand-off and a much smaller set than the manual-preview habit implies. The authoring side of this rule is `convention-ticket`'s "runtime-verified against a production build of the PR head" wording. (Worked case: A1-374 / `assoc-one/firmup-operator`PR #20, 2026-09-02 — five "on the preview" criteria left blank by exec on the assumption that no browser existed, all met by Prism in Chromium against a stub with a demonstrated-red negative control; the one residual preview box waived by`skill-merge-pr `on named signals — APP-880, Owner ruling 2026-09-03.)

  **A Shopify theme has no production build to drive.** Liquid renders only on the platform, and the hosted equivalent is an operator's `shopify theme push --unpublished` (`convention-shopify`); the sandbox's egress to the preview and the storefront is refused, so the route above does not exist for a theme repo. The DOM-fixture harness `convention-shopify` names is the substitute for a layout or interaction criterion over the committed assets, but a layout or reflow question that turns on a value set only at runtime — a CSS custom property a theme script writes after load — is not fixture-measurable: any value a fixture supplies is invented, the containing-box trap of *Reproduce the runtime* (iv). Route it as an operator visual check under sub-case (b), naming the specific risk for his eye rather than a general "please look". (Worked case: MBN-296 / `mbn-theme` PR #13 — `calc(100vh - var(--header-height, 60px))` with `--header-height` set by `{% javascript %}`, preview and apex both `CONNECT tunnel failed, response 403`; the leg declined the fixture and named the reflow risk, deriving the route live — APP-1560.)

  **A design-system-only component has no route to drive either — and there Storybook *is* the production build.** This is the third shape, and it is the mirror of the Shopify case rather than a repeat of it: a DS component built deliberately **not** wired into any route — no `Block` union entry, no `renderBlock` case, nothing in the app that renders it — has no page to load, so the app-route recipe above does not apply; but unlike a theme it has an excellent local render path, and the answer is not to defer. Where the change is deliberately unrouted, **build Storybook from the pinned head and drive the built Storybook in the sandbox's own Chromium**, and treat that as satisfying "a production build of the PR head" in full — it is the same class of evidence, not a weaker substitute, because it is the change's own real runtime compiled from the exact commit under review. Three things make it decisive rather than decorative. **The PR's own stories are the fixture set** — they ship with the change, they are what the component's author claims it does, and using them means the harness is not invented per leg. **A sibling story in the same build that genuinely lacks the property under test is a zero-cost negative control** — point the identical assertion at it, watch it go red, and the instrument is proven able to fail without writing a single fixture (*Proving the artefact under test*). And **the geometry and behaviour claims are measured, not read** — the acceptance criteria on these tickets are runtime-geometry and runtime-behaviour claims ("same grid, spacing, aspect-ratio handling", "each slot independently shows/hides its caption"), and no amount of static reading settles one. **The mechanics live in `convention-storybook`, not here** — the build command, the static serve of the built output, the deep-link endpoint that drives a named story with explicit args, and where the story IDs are enumerated from. Read them there rather than deriving them; this passage rules the route, that convention holds the recipe (refine's how/where call, APP-1099). Reserve the unverifiable classes below for the residue this does not reach — a component whose criterion genuinely depends on the hosted deployment, not on its own rendered behaviour. (Worked case: A1-462, `assoc-one/meirionpritchard-com` PR #161, head `4def498`, 2026-09-22 — a DS video-asset block with no route anywhere; the leg built Storybook from the pinned head, static-served the output, drove the story endpoint in the sandbox's Chromium, and found a real defect the PR's own claim asserted the opposite of, the video frame leaving its fixed 16:9 whenever a row's columns are uneven. `ImageAssetBlock` on the same head carried no `aspect-ratio`, so the same assertion pointed at it went red and proved the instrument could fail. Every step of it was re-derived from nothing — APP-1649.)

  **Second, separate a sandbox capability gap from a Claude capability gap.** A verification the QA sandbox cannot run is often one another Claude surface can. The Cowork connector surface holds Chrome (open a preview URL, read cookies and localStorage, inspect network requests), Figma, Gmail and Calendar; a browser-based runtime check, a preview inspection, or a design-export check is **dispatchable to the fleet** (`skill-fleet-dispatch` / `skill-dispatch-run`), not an environment limitation and not the operator's. So before routing a capability gap to Relay or to Aled, ask whether *any* Claude surface can do it — not merely whether this sandbox can. (Worked case: A1-116's PostHog runtime verification was routed to Blocked + `human` on the grounds that "no sandbox has a live browser" — true of this sandbox, false of the Cowork Chrome tools — so the check was dispatchable and the ticket sat on the operator for work an agent could have run — APP-618.)

  The two capability sub-cases apply only once a genuine capability gap remains — one no Claude surface can close:

  - **Verifiable by a standing runner QA lacks, or one cheap to stand up for an automated assertion** (a browser, a device, network egress, a credential — something a *configured* CI job or runner already has, or that is cheaply added as an automated check). This is an **environment limitation, not a human gate**. Never convert it into a "please run this" ask to Aled. Log it as a blocker naming the AC and the environment the verification needs (for example, CI that can install the browser), then route it to Relay to re-arrange — set `agent:R3-LAY` and move the ticket to **Blocked** so it leaves the QA lane for Relay rather than resting on the operator. **The test is whether an automated assertion is genuinely available or cheap — not whether some *bespoke interactive harness could theoretically* do it.** "A CI job with real credentials could in principle drive this" is not sufficient to class an interactive verification as sub-case (a); see the interactive-surface rule below. (Note the label meaning: `agent:R3-LAY` set here, on a **Blocked** ticket, means "this is Relay's to re-arrange" — it is **not** the merge approval that the same label carries on an *In Review* ticket, which is Aled's alone. The two uses share a label, not a meaning; see *Guardrails*.)
  - **Verifiable only by the operator** (the sole outstanding AC needs Aled's own eyes or judgement — e.g. "looks right in /studio" where no runner has that surface, or an embedded human-sign-off AC). This is **not Blocked**: Blocked implies external work must clear before the ticket can progress, but here nothing blocks except the operator's review. Keep the ticket **In Review**, set label **`human`** (evicts `PR-1SM`), assign **Aled**, and let it **age to Urgent** only if it lingers — so it surfaces on the "In Review = awaiting your sign-off" view rather than the stuck / dependency-bound Blocked view (convention-linear *Issue states*, Blocked; worked case A1-129, APP-441).

  **Interactive-surface verification is sub-case (b) by default — not (a).** Driving a live interactive surface and judging the result — a Sanity Studio Presentation session (split-view rendering, draft content, live-update-on-edit, click-to-edit focus), an in-app visual state, "does this look and behave right when I use it" — is the operator's own eyes in the running product, the exact A1-129 pattern. Class it as **operator-review (b) → In Review + `human`**, even though a bespoke CI harness with real credentials *could theoretically* automate it. The "a runner could do it in principle" reasoning stretches sub-case (a) to swallow verification that in practice needs a human, sending a code-complete item to Blocked (hidden from the "In Review = awaiting your sign-off" surface) instead of In Review. Reserve sub-case (a)/Blocked for a verification a **standing** runner already has, or one cheap to stand up as an automated assertion (a browser check, a device check, a credentialed API assertion) — not a bespoke interactive session a person realistically has to drive. (Recurrence: APP-441 landed the state semantics in `convention-linear`'s A1-129 rule, but the *(a)/(b) classification boundary in this skill itself* still misfired on interactive-Studio/Presentation verification — A1-130's PR #46, code-complete and green, routed to Blocked at 09:45 *after* that drain, 2026-07-07, APP-457. Prior related: APP-395 env-limitation ≠ human gate, APP-451 PR-1SM vs human label.)

  **Sub-case (a) hands Relay a box, so name the lever it can actually pull.** "Route to Relay to re-arrange" was written as though Relay could stand the runner up. It cannot — Relay is **Linear-only**, so it can neither provision a differently-egressed runner, add a CI workflow, nor open a browser. It has exactly two levers, and the verdict should say which one this is:

  - **An independent signal already covers the surface** — green CI that genuinely ran, a passing visual diff, an identical local code path exercised by a test. A green CI build or a successful Vercel build is evidence about the **build**, never about whether the deployed page renders: a workflow that supplies placeholder environment values goes green while the real deployment lacks them, and a route that reads its variable at request time stops failing the build altogether — so "the preview build succeeded" covers nothing about a runtime-variable criterion (`convention-vercel `*Gotchas*, APP-1114). This is the class Relay **waives itself** with a recorded one-line reason (`convention-ticket` *Waiving a box*, decision Aled 2026-07-16), so the ticket merges rather than taking a round-trip through the operator for a box nothing was ever going to tick from here.
  - **Nothing independent covers it** — then the box is genuinely in doubt, and it is an **unmet** box, not an environment limitation. Route it to the operator.
  - **The fix is a repo change neither lever reaches** — then say so and name the change. Relay can neither provision a runner nor open a browser, but it *can* raise and sequence a ticket, so a gap whose remedy is a repo-side capability is a **repo-lane ticket plus a** `blockedBy` **on this one**, not a "please run this" ask to Aled. Name the change concretely enough to be built (a workflow, a config key, a committed asset), not as a capability wish.

  **The un-capturable committed artefact — where the sandbox can run the check but must not author the baseline.** The sub-cases above sort a criterion the sandbox cannot *verify*. A committed build product — a screenshot baseline, a snapshot, a generated export — presents the mirror problem: the check runs fine, and it is the **regenerated artefact** the sandbox must not produce, because the capture environment differs from the one the baseline is compared in. The concrete shape: a Playwright baseline re-captured in the delivery sandbox bakes a sandbox-only artefact into the committed PNG — a framework dev-tools indicator whose own text differs in the sandbox (an egress-blocked CMS makes it read "2 Issues"; see APP-712) — so the capture is *green here and wrong in CI*, and a repo `CLAUDE.md` forbidding sandbox captures is stating this hazard, not a preference. Lifting CI's own `-actual.png` out of the workflow artefact is the obvious second route and **is not available**: the artefact bytes are served from a blob host the egress proxy refuses (`curl: (56) CONNECT tunnel failed, response 403`; `gh api .../artifacts/<id>/zip` returns a zero-byte file), verified 2026-09-12. So **route it as sub-case (a) with the third lever above** — Blocked, `agent:R3-LAY`, with a repo-lane ticket naming the durable fix — and never as operator-review (b): asking the Owner to run `--update-snapshots` locally converts an environment limitation into a human gate, which the sub-case (a) rule already forbids. The two fixes worth naming, either of which retires the class: suppress the dev-tools indicator for screenshots (`expect.toHaveScreenshot.stylePath`) so a sandbox capture becomes CI-valid for every clip, or add a dispatchable CI job that runs `--update-snapshots` and commits. (Worked case: A1-414 / `meirionpritchard-com` PR #131, 2026-09-12 — three of five moved baselines were un-capturable in the sandbox, both routes shut, and a code-complete green PR went to Blocked + `human` for one local command, with the routing reasoned out from first principles because no rule covered the shape — APP-1384.)

  Either way, **name the missing instrument as separate work**: where the verification is genuinely worth having, Relay's other lever is filing the repo-lane ticket for it (an `OPS:`/`FIX:` on `agent:R3-LAY`) — that is real, and it is how the runner eventually exists. A box repeatedly waived in one repo is the evidence for that ticket, not evidence the criterion is decorative. (Worked case: the same evidence resolved two ways run to run — A1-209 Relay waived and merged, A1-216/A1-217/A1-208 routed to Aled, because canon told it to re-route and gave it nothing to re-route with. Every party followed the rule and the ticket still landed where the rule forbade — APP-568, consolidating APP-555. Note A1-208's repo, `meirionpritchard-com`, has **green CI** — so this is not a firmup-lacks-CI problem, and fixing firmup's CI would have left A1-208's class open.)

  The operator gate is reserved for a genuine decision or judgement only Aled can make; an environment limitation with an independent signal behind it is Relay's to waive and merge; an operator-review-only AC — including any interactive-surface judgement — sits in In Review under `human`, never Blocked.

**And re-read the assignee after any write to a ticket resting In Review — it is a field this leg never wrote, and it moves anyway.** The rule below covers fields the verdict claims. This one covers a field nothing on this leg touches. Linear's GitHub integration assigns the PR author on attachment (`skill-build-ticket`'s hand-off mitigation, APP-936), and the attachment can land **after** the exec leg's hand-off read-back — so exec hands off correct on every field it can see, and the auto-assign then surfaces on whichever leg writes next, which is this one. `skill-build-ticket`'s rule cannot reach it: at hand-off there was no attachment to provoke it. So whichever leg writes last re-asserts the unassigned hand-off: after any `save_issue` on a ticket resting In Review with a fleet executor label, read the assignee back and clear it in an **isolated** write if the integration has populated it (`convention-linear`, *Clear a nullable param in a write of its own*). The cost of not doing it is a wrong signal rather than a wrong state: "assigned to Aled" on an unflagged clean pass reads as *his decision is needed now*, and the loop's `PR-1SM` sweep skips a ticket that has an assignee, so the ticket waits for a review that will not come. (Worked case: APP-1686's QA leg, 2026-09-23 — at 13:48Z the ticket read In Review, `PR-1SM`, no assignee and no PR attachment; a 13:51:05Z description patch ticking QA-closed boxes returned it **assigned to Aled** with the PR attachment newly present, and QA cleared it at 13:51:15Z and read it back clear. The attachment and the assign shared one `updatedAt`, so a description-write side effect could not be separated from the attach trigger — which is a reason to re-read after **any** write rather than only after an attach. At least the fourth instance of APP-936 — APP-1699.)

**A verdict that reports a Linear write as done re-reads the field after writing it.** The verdict is an instruction to the next leg, so a state claim in it — "both boxes are now ticked", "the label is set", "the ticket has moved" — is trusted and acted on, and a claim that turns out false sends the exec leg to hand off a ticket in the state this review said it was already in. Read the field back before asserting it, per `convention-linear`'s rule that a patched `save_issue` can no-op silently and the returned object is not proof (APP-860); the same do-not-assume-your-state-survived discipline `skill-build-ticket` already applies at its claim (APP-717) and its hand-off (APP-936). Where the write cannot be confirmed, say what was attempted rather than what was achieved. (Worked case: A1-381 / PR #23, 2026-09-08 — one patch write ticked a definition-of-done box and left an acceptance box blank under a different heading, and the verdict asserted both were ticked three times. APP-1184.)

**The same read-back covers the verdict comment itself, and its head SHA is derived, never retyped.** A verdict reported to the next leg is trusted the way a state claim is — the driver routes off it and the merge leg briefs from it — so "a clean verdict is posted at `<sha7>`" that is true on neither surface sends a merge leg to the gate with nothing behind it. Two obligations, both at the point the verdict is written, and both cheap. **Read the comment back from each surface after posting it, and diff its trailing bytes against the file that was sent** — the Linear ticket and the GitHub PR are two writes, not one — and report the verdict as posted only for the surfaces that returned it; where a write did not land, say which, rather than reporting both. **The read-back is a diff, not a presence check**, because the failing case is a comment that is present, correct and complete. A GitHub write path silently rewrites the trailing bytes of a body it carries, and a verdict comment is one of the bodies it has been observed doing it to: the `[qa] HEAD:` first line and the verdict text come back intact with an attribution footer appended under the verdict's last line, where it reads as part of the verdict. A re-read confirms the comment is there, which is exactly what is true when it has been rewritten; only a diff against the file that was sent shows the appended bytes. This is the same obligation this skill already imposes on the PR-body patch in *Tick the PR body's copy* below — "read back and **diffed** against the intended bytes, not merely re-read" — now carried on the comment as well, and for the same reason. `convention-github`'s *Attribution bytes at the end of an agent-authored body are rewritten in transit* holds the path list and names the routes observed to store what was sent, so do not restate either here: where the diff differs, repair through a route that section names, never by re-posting through the route that appended, and say in the verdict that the comment was diffed and at which head — a verdict reported as read back is trusted by the merge leg the way a state claim is. (Worked case: the APP-2493 QA leg, `assoc-one/claude-ops` PR #501 head `8205db6`, 2026-10-21 — a verdict comment created through `mcp__github__add_issue_comment` came back with a footer appended below the verdict, and the REST comment PATCH taken as the repair appended it a second time; the recurrence on PR #503 head `735e74c` the same day was caught exactly this way, by diffing the read-back against the sent file. The pull request numbers, heads, comment ids and read-back bytes are the filing legs' reports and are **unverified** here, no repo or GitHub surface being readable from the authoring surface — APP-2507.) **Take the `<sha7>` from the fetched PR head, pasted, never typed from memory or carried across from an earlier ticket** — `convention-github` already governs it in the general form ("any machine-checkable value a run copies into a review-facing surface is generated and pasted, never retyped, and is verified by diffing against live output rather than by re-reading it", APP-1159), so a SHA that resolves to no commit is that rule's failure rather than a new one. The `[qa] HEAD:` line is the dedup key and the merge gate's evidence at once, which gives a mistyped SHA here a blast radius a mistyped digest does not have. (Worked case: APP-1160 / `assoc-one/meirionpritchard-com` PR #122, 2026-09-10 — a clean verdict was relayed at `[qa] HEAD: f4d6df3`, a SHA that is not a commit in that repo, with no `[qa] HEAD:` comment on the ticket or the PR and zero PR reviews; the PR's only commit was `5377fb0`. `skill-merge-pr`'s APP-832 guard refused the merge and routed the ticket back to `agent:PR-1SM` — it held only because that guard re-derives from GitHub rather than trusting the brief, and it is the last line, not the first. Two legs in the same run asserted a hand-off state neither had read back — APP-1289.)

**A classifier denial closes a read as well as a write, and the read direction has its own named fallback.** *Behaviour* above settles the write side — "A classifier denial is a route closed on this surface, not a GitHub error to retry" — and that rule governs here unchanged; what it did not say is that the same thing happens to a **GET**. The Claude Code auto-mode permission classifier has denied a plain read-only `gh api repos/{owner}/{repo}/pulls/{n} --jq …` as `[External System Writes]`, seconds after an MCP write to the same pull request and seconds before an otherwise identical GET of the same endpoint was allowed, so the denial tracks surrounding context rather than the HTTP verb and no 403 comes back for the self-documenting recovery to fire on. Every read-back in this section is an obligation rather than a convenience, so a denied GET needs a route and not a retry: **where a classifier denial closes a read, the named fallback is the connector's own read tool** — `mcp__github__pull_request_read` for a pull request's body, draft flag or head SHA, and the connector's comment-read tool for a comment body — **rather than a second attempt at the same `gh api` GET**, which spends another turn on the route just closed. And **report a denied read as a closed route, never as a finding about the pull request**: the failure this exists to stop is a verdict recording an absent verdict comment, a missing check or an unflipped draft flag when what actually happened is that the classifier refused the read — evidence about this surface and none at all about GitHub. (Worked case: the APP-2608 QA leg, `assoc-one/claude-ops` PR #532, head `6d312af`, 2026-10-22 — `gh api repos/assoc-one/claude-ops/pulls/532 --jq '.draft, .head.sha'`, a GET reading back the draft flip, was denied as `[External System Writes]`; the read-back moved to the MCP `pull_request_read` get and worked first time, at a cost of one turn. One instance. The pull request number, the head SHA, the denial category as logged and the allowed sibling GET are the QA leg's **reported** account, unverified here — no repo or GitHub surface is readable from the refine surface — and the GitHub MCP is **not attached** on this surface either, so the `pull_request_read` tool name is **unverified** as written; a flag on one of these implies nothing about the others — APP-2630.)

**The recording format is this skill's, and a dispatch brief does not displace it.** A verdict is recorded as a comment whose first line is `[qa] HEAD: <sha7>`, on the Linear ticket and on the GitHub pull request — that is the format, whatever the brief that dispatched the leg asked for. A brief phrased as a format reads as scope rather than as a rule: "post a COMMENT review", or "review only, no state change", sounds like a narrowing of the job, and a leg that follows it posts a GitHub **review** instead of the marker comment. A review and a `[qa] HEAD:` comment are different objects on the same surface, so the work lands visible to a person and invisible to the gate — `skill-merge-pr`'s marker check finds nothing at that head and refuses a pull request that has in fact been reviewed, and the boxes this verdict would have closed on its own verification are left for a merge leg to tick under record-and-disclose. "A review was posted" is therefore not evidence the format was met; the read-back above is, on both surfaces. Where a brief and this skill disagree, follow the skill and name the divergence in the verdict. `routine-delivery-loop` already carries the general form for the prompts it writes — *The driver calls existing skills; it does not duplicate their logic*, where the prompt names the skill, the ticket and the parseable result line while the skill carries the rules, and a narrowing is the same failure as a restatement with no visible seam — and no equivalent rule sits in `skill-dispatch-run` or `skill-fleet-dispatch` for the briefs those surfaces write, which is why the obligation is stated here, beside the format it protects, rather than on a dispatch surface. (Worked case: the ⑤ Templates operator-a1 session, 2026-10-21, slice A1-682 — Prism legs prompted to "post a COMMENT review" posted a GitHub review and left no `[qa] HEAD:` comment on either surface, and the merge leg's marker gate failed on the missing marker with a reviewed pull request in front of it. Earlier on the same root, both closed: APP-2272, a slice that ended with no clean QA marker, and APP-2363, a QA subagent that posted the REVIEWING marker and no verdict. The dispatch prompts, the review objects and the gate's refusal are the operator session's report and are **unverified** here, no repo or GitHub surface being readable from the authoring surface — APP-2570.)

Plain language throughout — Aled acts on it without reading the code.

**"CI green" is a reading of the aggregate check, and configured retries absorb a flaky spec the pull request itself adds — so read each matrix leg's own summary for the specs the diff adds.** The required check a hand-off reports on is the aggregate job over the matrix; it concludes success once every leg has passed, and where the suite is configured to retry a failed spec, a spec that failed on its first attempt and passed on a retry sits inside that success. At hand-off the reading is then identical for a clean new spec and a flaky one — nothing is red, nothing is missing — which is the quiet failure: the flake merges with the pull request that introduced it, joins the required check on `main`, and next surfaces on an unrelated branch as a red nobody's diff explains. Only each leg's own run summary lists the retried entries by name. So before closing a *"CI present, concluded, green"* box on QA's own verification, or reporting CI green in a verdict, open the per-leg summaries and say, for every spec the diff **adds**, either that it passed first time in every leg or which legs retried it. A retried new spec is a changes-needed item against that spec — name the spec, the leg and the retries, and ask for the flake to be removed — rather than a suite bounce or a waived box. Reading the aggregate alone is not a cheaper form of this check but a different one that cannot see the answer. This does not conflict with `convention-github`'s *Screenshot baselines are CI-rendered, never sandbox-rendered*, which reads a red holding "identically across retries" as the signature of a real regression rather than of a flake: that passage is about a red a retry did not erase, and this is about a red a retry did. (Worked case: the A1-731 QA leg, `assoc-one/meirionpritchard-com` PR #259, 2026-10-21 — the builder handed off "CI green" and the aggregate `playwright` check read green, while the tablet leg's own summary listed 2 flaky tests in the newly added `tests/work-aria-expanded.spec.ts`; merging would have put a flaky spec into the required check on `main`. Reported by the QA leg through the operator-a1 session, and **unverified** here, each clause covering only itself: the repo's `retries: 2` setting, the three matrix legs, the aggregate job's name, the per-leg artifact names and the pull request number — no repo or GitHub surface is readable from the authoring surface. APP-2574.)

**Verdict routing in one line:** code-reviewable AC → verdict (clean or changes-needed); an AC verifiable only by a standing runner QA lacks, or an automated check cheap to add (CI, a device, a credential) → blocker routed to Relay + **Blocked** (with `agent:R3-LAY` set as the hand-to-Relay signal, never a merge approval), never an ask to the operator; an AC only the operator can verify — his own eyes or judgement, **including driving an interactive surface** — → **In Review** under `human`, assigned Aled, aged to Urgent — **not** Blocked; a genuine decision or judgement → the operator. The environment-vs-operator split is the one that has slipped (A1-71, A1-72 the environment case; A1-129, A1-130 the interactive operator-review case): an environment limitation is not a human gate, and an interactive/operator-review-only AC is not a blocker.

**Hand off.** Once the verdict is posted the state stays **In Review**. Where the ticket goes next depends on the ticket's **human-gate flag** — a `Human gate: required — <reason>` marker in the body, or an embedded human-sign-off AC such as "Human sign-off (Pattern A)" — and only one of the two branches hands to Aled at all:

- **No human gate** (an unflagged clean pass) — leave the label `agent:PR-1SM`, leave the **assignee clear**, and return the verdict line. Do not assign Aled: on unflagged work his approval is not the next step, and an assignee here costs the signal that "assigned to Aled" means his decision is needed now. "Leave the assignee clear" governs QA's own writes, not a field to reset: **QA never sets Aled as assignee on an unflagged clean pass, and never clears an assignee it did not set** — an Owner-filed ticket he assigned to himself keeps its assignee, and QA writes nothing to that field (MBN-309 / `mbn-theme` PR #17, head `d9670ce` — APP-1544). The routing that follows — label `R3-LAY` (evicts `PR-1SM`), In Review, assignee clear, then the merge leg — is `routine-delivery-loop`'s *Route per verdict* action, taken by the driver off QA's parseable verdict line, and that routing **is** the merge approval for unflagged work. It is not QA's to apply, and QA does not wait for a `@relay` signal the driver's design does not require. Where QA ran standalone rather than under the driver, `routine-delivery-loop`'s stranded-`PR-1SM` sweep is the net: it reads a clean verdict at the current head and applies the same route without re-reviewing. This reconciles skill-review-pr with the driver on the unflagged branch, as APP-451 already did for the flagged one directly below; the decision it implements is APP-402 — clean-pass agent tickets auto-merge, gated by human-judgement need rather than universally — which closed APP-316. (Worked case: the APP-1262 merge leg, `assoc-one/claude-ops` PR #215, 2026-09-10 — the leg read both artefacts, found them incompatible on all three of label, assignee and merge authority, and landed correctly only by adjudicating the contradiction live. A QA leg following the superseded wording literally left the ticket at In Review + `PR-1SM`, assigned, where `skill-merge-pr`'s gate correctly refuses it and it waits for a human signal the driver does not require — the APP-645 merge-nobody-is-doing shape, reached by following canon rather than by neglecting it, and re-arming the stranded-`PR-1SM` state APP-853 / APP-969 / APP-1108 built a whole out-of-band sweep to clean up — APP-1315.)
- **Human gate present** (a flagged clean pass) — set label **`human`** (evicts `PR-1SM`), matching `routine-delivery-loop`'s routing table. `human` reads correctly as "a person, not an agent, is the active party now"; the flag means an agent's approval is not the next step — Aled's own sign-off is. This reconciles skill-review-pr with the driver, which already switched to `human` on a flagged clean pass (worked case A1-125, APP-451).

Setting `agent:R3-LAY` on an **In Review** ticket is never QA's action. It is either Aled's approval, set by hand out of band, or the driver's own *Route per verdict* step on an unflagged clean pass — and neither is QA's to take. The prohibition is about **who writes the label**, not about whether a person must: reading it as "a human approves every merge" is exactly what left the unflagged bullet above describing a manual gate APP-402 had already retired, and what makes the *Verdict routing in one line* summary read as forbidding the loop's own clean-pass routing. The one place QA sets `agent:R3-LAY` itself is sub-case (a)'s environment-limitation route, where the label sits on a **Blocked** ticket and means "this is Relay's to re-arrange", not "approved to merge" — the two uses share a label but not a meaning (see *Guardrails*). The exec leg left the ticket unassigned, and QA leaves it unassigned on an unflagged pass too; the assignee becomes Aled only on the branches that genuinely need him — a human-gate flag, or an operator-verify-only AC — so "assigned to Aled" reliably means his decision is needed now. (APP-1315.)

## Stating the defect, not the patch

A changes-needed verdict names **the defect, the property that must hold, and the bar the fix will be judged against**. It does not hand the exec leg a paste-ready patch. "Specific and actionable" means the bounce is self-contained enough for exec to work from — not that QA has written the code.

The reason is independence, not style. A reviewer-authored snippet carries reviewer authority without implementer scrutiny: exec reads "apply QA's fix from comment X" as specified-and-validated and transcribes it rather than re-deriving it, so nobody exercises the judgement the review exists to supply. Worse, QA then reviews its own code on the next pass and cannot do so independently.

Where the line sits:

- **In** — the file and line, the failing input, observed versus required behaviour, the property that must hold ("the helper must be total: it returns a string on every path, for any input"), the acceptance bar the next pass will be measured against, and any invariant the current shape violates.
- **In, marked** — a short illustration where it genuinely clarifies: a signature, a named API, the shape of a guard, the ordering constraint. Mark it explicitly as illustrative and keep it short of something droppable into the file.
- **Out** — a verbatim replacement for the code under review, offered as the fix.

Two obligations follow:

- **A snippet is a diff, and a figure is a claim — hold both to the bar QA reviews with.** If a snippet is given anyway, or the operator repeats one in a bounce instruction, it inherits the full review bar before it leaves the verdict: every path returns, every call that can throw is guarded (including a second instance of a parse already guarded above it), and it is checked for totality, not only for the one property under review. A **measurement the verdict itself supplies** — a count, a run list, a figure, a scope boundary — travels the same way and lands with the same reviewer authority, but with none of the provenance a snippet owes, so it carries its own. Mark it as the reviewer's own, state **how it was derived**, and state **the boundary that set it**: which items, and the property that makes those items one group. A figure given without its boundary is an assertion, not a measurement, and exec will transcribe it as specified-and-validated.
- **Declare provenance on the re-review, and re-derive the boundary, not only the arithmetic.** Where the change under review originated in QA's own wording, say so at the top of the verdict and review it more sceptically, not less. Where it originated in a figure QA supplied, the re-review re-derives that figure from source — the boundary first, then the arithmetic inside it — because arithmetic that is correct on the wrong set agrees with the verdict exactly and reads as confirmation. When replaying historical CI, the boundary is what the mechanism actually groups on (workflow, event and ref), never a window that looks like one burst. An exec handoff reporting that its independent replay "matches QA's exactly" is a warning that the set came from QA, not evidence that the set is right.


(Worked case: APP-1455 — a round-1 verdict corrected a burst-run count from 8 to 11, the bounce comment repeated the corrected figure as an instruction, and the exec leg rebuilt on it and reported its own replay as matching QA's exactly. The true count was 14, one concurrency group rather than an apparent burst, and the three omitted runs held the largest cancellation in the set — so a second wrong account of that repo's CI history landed in a committed workflow comment, where the next cost review reads it as established, and the ticket reached its bounce cap over a figure QA had supplied. Round 2 caught it only because it re-derived the run set from the branch instead of from the bounce comment. The counts, the PR number and the run numbers are reported from APP-1455 and are **unverified** here: this session has no GitHub access, so none of them was re-read from the runs.)

**A bar stated on the instance leaves the class open — name the property across its whole domain, and widen the measurement before writing the bar.** A bar written to the control that failed ("every preset value lands on its *slider's* step") is met exactly by a fix that leaves a sibling control broken, and the verdict and the hand-off both correctly report the bar as met. The reviewer's own harness is the second half of it: an instrument built to the instance it just found inherits the scope of the bar it is about to write, so round 1 cannot see what round 2 finds. So before stating a bar, widen the measurement to the domain the property ranges over — every control that displays the value, not the one that failed; every preset, row or breakpoint, not the one sampled — and state the bar on that domain. (Worked case: A1-436 round 1 bounced a slider-step mismatch; round 2, built to the property, found a preset's easing value absent from the reposition-easing `<select>`, byte-identical in the round-1 file. Passed non-blocking, but on a strike-2 round it is the bounce that hits the cap. APP-2124.)

**Prefer a construction argument to an enumeration.** Three rounds of "here are ten more payloads that escape" lose to one round of "this shape returns safely for every input, so an unlisted variant fails safe". State the property; let exec build to it.

(Worked case: on A1-242 (`assoc-one/firmup-operator` PR #1) QA returned three consecutive changes-needed verdicts on one login-redirect guard, two of them carrying a verbatim snippet. Exec applied the pass-3 snippet exactly as written — the operator's bounce comment quoted the same snippet — and that snippet introduced the pass-3 defect: a second, unguarded `new URL()` where the identical parse eleven lines above it sat inside a `try/catch`, so `/login?next=/..//` threw and returned HTTP 500 on both the signed-in and anonymous routes. QA had validated the snippet for the property under review — does it escape? — and not for totality — does it always return? What finally closed it was a totality argument, confirmed across 1,463,525 adversarial inputs. Three rounds of enumeration lost; one round of construction held — APP-692.)

## Proving the artefact under test

Where QA stands a service up to verify against — a built app, a container, an emulator, a tunnel — the first thing to establish is not behaviour but **provenance: that the process answering is the artefact this run built**. A harness that can pass against an artefact it did not build is worse than no harness, because it fails in the safe-looking direction: a crash is obvious, a green against the wrong binary is indistinguishable from success, and the greener the output the more convincing it is.

**And the same question is owed of any state the harness sets, not only of the artefact it starts.** Where a test drives the subject into a state — a CSS custom property, a store value, a data attribute — it drives it through the mechanism the product itself uses, never by injection, and it reads the value back before asserting on it. A component that owns a value re-asserts the value the test set, asynchronously and silently, so the injection reads as applied, the read-back comes back as the resting default, and every assertion after it is about a state nobody established. The failure direction is the section's own: an injected value that did not stick produces a plausible measurement of the wrong thing rather than an error. The same read settles **which** element is under test: a fixture's position in its own array is not its position on screen once the product sorts it, so locate the subject by a live read of the rendered order and not by its index in the fixture.

Five cheap obligations, in order, before any assertion about behaviour:

1. **Assert the port is free before starting — then read what answered, because the answer decides the remedy.** One `fetch` at the target port; if anything answers, do not start. This alone removes the class — a stale listener becomes a loud failure rather than a silent pass. But "anything answers" covers two situations with opposite remedies, and one `ps` separates them. **A stale or orphaned listener** — this run's own leftover, or a dead sibling's — is a failure: say so and stop, per obligation 2's group-kill. **A live sibling leg's server**, correctly started and correctly still running from another checkout, is not a failure of anything: the port will not free on this review's schedule, so stopping is not patience, it is abandoning a review that has a cheap route around it. **Move to a verified-free port and carry on** — the same move this section already requires when provenance is in doubt after the fact — and name the port and the reason in the verdict. Never kill a process this run did not start.

   **And check the repo's own config before trusting the port at all, because a repo can opt into the collision.** A Playwright config carrying `webServer.reuseExistingServer: !process.env.CI` with a fixed `baseURL` will **silently reuse** whatever is already on that port: no error, no warning, every assertion green against a tree this review did not build — and the negative control wrong in the same direction, so the one instrument that would expose it is compromised too. This is the section's own failure direction at its worst, and it is invisible to obligations 2 through 5, all of which concern a process this run started. So for any repo whose harness starts a server: read `reuseExistingServer` and `baseURL` before the first run, and where reuse is on, drive the checks through a throwaway override config in the isolated clone that pins `baseURL` and `webServer` to a verified-free port with `reuseExistingServer: false`. Cheap, and it makes the isolation actual rather than assumed. (Distinct from the same-run orphan whose remedy is obligation 2's group-kill, and from a sibling branch-switching a shared checkout — see *Pin the whole review to the head under test*: this is a shared **network port plus an opt-in reuse flag**, a third surface where leg isolation is contextual rather than environmental.)

   **And on a Next repo the lock is the project directory, not the port — so a dev server you started yourself blocks the harness even on a different port.** A verified-free port and `reuseExistingServer: false` do not help here: Next refuses a **second** `next dev` in the same working tree whatever port it is asked for, and the Playwright `webServer` step starts one. The refusal is loud and instant — `[WebServer] ⨯ Another next dev server is already running`, naming the *other* server's URL and PID — which is the trap, because it names a port the config never mentions and reads as a broken harness rather than as a process this run left behind. So before the first `playwright test` or `npm test` on a Next repo, **kill any dev server this run started itself** and confirm it is gone; this is a distinct surface from the shared port and the reuse flag above, and neither of those checks detects it. Do not reach for `pkill -f` to do it — see the `pkill` warning below, which holds whatever the pattern is — kill it by the PID this run recorded, or, where that PID is stale, locate the server by `ps` and `/proc/<pid>/cwd` as obligation 2 requires. This fires exactly on the sanctioned pattern of booting a dev server to take visual evidence where `next build` cannot complete in-sandbox (the Sanity-egress class, APP-712), so the diligent run is the one that meets it. (Worked case: A1-488, 2026-09-23 — a manual `npm run dev -- -p 3500` for Playwright screenshots blocked `npx playwright test`, whose config targets 3000; killing the manual PID let the harness boot and the suite ran 11/11 clean. Distinct from APP-1347, where a sibling leg held a shared port and the ports did collide. Premise unverified — confirm the repo's `playwright.config.ts` `webServer` block and its `CLAUDE.md` Playwright section against `assoc-one/meirionpritchard-com` at `origin/main` before building. That flag covers those two files only; the Next refusal message and the A1-488 sequence were observed directly.)


   **And two Playwright invocations never share one dev server — the failing set a dying or hung server produces is indistinguishable from a regression, and it corrupts the one comparison canon tells a leg to act on.** The checks above protect a server this run started; this one protects the *comparison*. A base-versus-head read is the diff of failing spec names and never an absolute count (`convention-github`, *CI coverage and the sandbox test environment*), and that diff is only as sound as the apparatus underneath both legs: a dev server that disappears or stalls mid-run reddens whichever specs happened to be scheduled after it went, so the false set is **not stable from run to run** and arrives in exactly the shape the diff is designed to trust. Three rules, in order of cost. **Never run two `npx playwright test` invocations against one dev server, even a small targeted one alongside a long background one** — the hazard fires from the small run too, and running base and head *simultaneously* from two pinned worktrees on two ports is the worst form of it, because both apparatuses die and the diff of two corrupted sets reads as a clean answer. Run the legs one after the other. **Classify before you diff:** read each failure's own message, and treat `net::ERR_CONNECTION_REFUSED`, `net::ERR_ABORTED; maybe frame was detached?` or a bare `Test timeout` against the run's own `baseURL` as an apparatus fault — re-run those spec files one tree at a time and diff the re-run, never the first pass. A grep of the failing list for the spec the diff actually touches, coming back empty, is the cheapest tell that nothing in the change is implicated. **And a stalled run is diagnosed on the server's CPU time, not on the log's growth:** a long-lived reused `next dev` can peg at roughly 118% CPU serving nothing while the runner sits at 0% waiting on the `webServer.url` health check, leaving a `--reporter=line` log at zero bytes — the same symptom as the reporter hazard `convention-github` documents and a different cause, because no test has started and there is nothing yet to flush. Read accumulated CPU time on the `next-server` PID against its wall-clock age with `ps`, not the log, and recover by killing that PID's group (by pid, per the `pkill` warning below) and rebuilding from a clean `.next` rather than waiting longer. (Worked cases, all `assoc-one/meirionpritchard-com`. PR #215, base `5b2db1c` / head `4a9b673`, 2026-10-02 — the full `--project=mobile` suite run on both trees at once, each from its own pinned worktree on its own port (3101, 3102) with three workers, both servers gone by the last stretch, 11 failing on base and 43 on head, and the prescribed diff reporting **32 tests newly red on head**, one step from a changes-needed bounce; re-running the six affected spec files one tree at a time gave 72 passed on each and the real failing set was the usual six on both. PR #218, head `9876ee7`, 2026-10-03 — a three-spec run started alongside a 313-test background run on the single shared `:3000` server, 52 failed across specs the diff never touched. And PR #222, 2026-10-04 — purely sequential `--project=desktop` invocations relying on `reuseExistingServer`, the reused server pegged for 52+ minutes against a zero-byte log, resolved by killing the `next dev` / `next-server` / `postcss.js` pids and rebuilding from a clean `.next`, after which the next run finished in about six minutes. **One correction is carried with them:** the PR #218 instance was first filed as concurrency and that attribution was **retracted** — a solo re-run reproduced the identical 52 failures byte-for-byte — so concurrency is ruled out there, and the reproducible base/head split on that head is suite-scale and scheduling pressure on one shared dev server, which the never-an-absolute-count rule already covers. Premise unverified — no repo is readable from the refine surface, so the worktrees, the ports, `playwright.config.ts`, the spec names and every count above are the filing legs' reports, and the 118% / 52-minute reading was not reproduced here; that flag covers those premises only, not the classify-before-you-diff rule, which stands on the mechanism. APP-1996.)

   **Drive a Next *dev* server at `localhost`, never `127.0.0.1` — and note that the production build is unaffected, which is what makes this a trap rather than a rule.** On Next 16, `next dev` refuses dev resources to a `127.0.0.1` origin — `Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "127.0.0.1"`, governed by `allowedDevOrigins` — so an override Playwright config that pins `baseURL: http://127.0.0.1:<port>` against a dev `webServer` serves pages that **never hydrate**. Every interaction assertion then fails, and the failure looks like the diff: on the A1-487 leg the full desktop suite went roughly **140 red**, including specs that were **33/33 green** against the production build minutes earlier; the same suite at `localhost:<port>` returned a healthy **194 passed / 4 failed**. The asymmetry is the whole hazard: `next start` (production) does **not** block the origin, so **one config file is correct for prod-build QA and silently broken for dev-server regression runs**, and a leg that has verified the config once on a prod build has verified nothing about the dev path. So the override config for a dev `webServer` uses `localhost`, and where a leg reuses one config across both modes it states which mode each figure was measured in. The tell is cheap and specific — a red suite whose failures are all *nothing rendered* rather than *rendered wrong*, plus the blocked-cross-origin line in the dev server's own output; read the server's log before attributing an unhydrated page to the change. (Worked case: A1-487 QA leg, `assoc-one/meirionpritchard-com` PR #166 head `d8ed088`, 2026-09-23 — one rebuild cycle spent; verdict unaffected because the provenance checks caught it. APP-1694. Premise unverified — confirm the repo's own Playwright config and any `allowedDevOrigins` setting against `assoc-one/meirionpritchard-com` at `origin/main` before building. That flag covers those two premises only; the Next 16 refusal was observed from the dev server's stderr.)

   **And a Playwright run can abort before any test executes, because the test-runner process does not load the repo's `.env.local` — and under the worktree guard the only route is to pass the variables inline.** The `webServer` child auto-loads a dotenv file; `npx playwright test` is itself a plain Node process and does not. So a spec that imports a module asserting its environment at **module-load time** — on `meirionpritchard-com`, `tests/asset-library.spec.ts` → `src/sanity/muxVideoValidation.ts` → `src/sanity/env.ts`, whose `assertValue` throws `Missing environment variable: NEXT_PUBLIC_SANITY_DATASET` — kills the whole run at collection rather than failing one spec: exit 1, or `No tests found` when driven through an override config with no web server. Both read as a credentials failure or as the diff, and neither is. Copying `.env.example` to `.env.local`, the step the repo's own CLAUDE.md documents, is enough for the dev server and not for the runner. The shell form `set -a && . ./.env.local && set +a` is refused by the worktree guard (`convention-agent-runtime`, *Isolation* — the same one-plain-command-per-call rule the `pkill` warning below turns on), so **pass the variables inline on the `npx playwright test` call**, and read a collection-time environment abort as an apparatus fault to fix before measuring, never as a red suite to report. CI is unaffected because the workflow sets the variables inline already, which is exactly what makes this local-only and a trap. (Worked cases: three legs on `assoc-one/meirionpritchard-com`, 2026-09-24 — A1-515 exec PR #183, A1-521 exec PR #186, and the A1-529 QA leg PR #188 head `18cb27c`; it went from "the first spec that imports `env.ts`" to every local run once `asset-library.spec.ts` landed on `main` — APP-1748.) Premise unverified — no repo is readable from the refine surface, so the import chain, `env.ts`'s assertion, the CLAUDE.md recipe and the workflow's inline variables are the filing legs' reports; confirm them against `assoc-one/meirionpritchard-com` at `origin/main` before building. That flag covers those four files only; the worktree guard's refusal of the `set -a` form was observed directly by the A1-529 leg.

   **The same guard covers an output path, not only a port.** The session scratchpad is shared across a run's legs, so a file already sitting at the path a leg is about to write to is a sibling leg's, and a failed write leaves those bytes readable exactly where the leg expects its own result — the port failure's mirror image, one directory over. **Assert the output path is absent before writing to it, and namespace scratch per ticket and per leg**, so a failed download reads as a failure rather than as data. (Worked case: a probe of `uploads.linear.app` failed as documented with nothing written, and the next line of the same command hashed a 67,432-byte `attachment.md` left at that path by an earlier leg publishing a different artefact; nine other legs' leftovers, including a previous ticket's `verdict.md`, sat in the same directory — APP-1392.)
2. **Spawn the real binary, not a wrapper.** `spawn('npx', …)` is the trap: killing the `npx` wrapper does not kill what it launched, and the orphan keeps the port. Start the binary directly (`node node_modules/next/dist/bin/next start` or the equivalent) with `detached: true`, and kill the process **group**. Any harness that starts a service through a wrapper binary inherits this.

   **And verify the teardown rather than assuming it — the real binary is not always one process.** `next start` forks its own `next-server` child, so a framework can reproduce the orphan from inside the very binary this obligation tells you to spawn: killing what you started leaves `next-server` holding the port. That is the APP-693 shape arriving from Next's own fork rather than from an `npx` wrapper, so "spawn the real binary" does not by itself avoid it. After every teardown, confirm with `ps` plus a probe of the port that nothing this run started is still listening, and kill any residue **by pid**. Obligation 1 asserts the port is free *before* starting; nothing asserted it afterwards, which is exactly how one run's leftover becomes the next run's stale listener. (Worked case: the A1-457 QA leg, 2026-09-21 — every teardown needed an explicit second kill by pid, verified with `ps` and a port probe, after following this obligation to the letter — APP-1627.)

   **From a shell, `setsid … & echo $!` records a PID that is already dead — so find the server, never remember it.** `detached: true` is a `spawn` option and a leg driving the server from a shell reaches for `setsid` as the equivalent; but `setsid` **forks when its caller is already a process-group leader**, which a shell command substitution is, so `$!` names the short-lived parent and not the server. `kill -TERM -$PID` then reports *"No such process"* while the real `next-server` — whose pgid is typically `PID+1` — keeps the port. The next build's `next start` fails `EADDRINUSE`, and the **old** server, its `.next` already wiped for the rebuild, answers every request with 500 or stale output: a wholesale false red attributed to the diff. `pgrep -f next` is not the recovery, for the same reason `pkill -f` is not (below): the pattern matches the agent's own shell and kills it, exit 144, so anything chained after the kill never runs. **Find the process by what it is and where it lives:** `ps -eo pid,comm | awk '/next-server/'`, filter each candidate to the one whose `readlink /proc/<pid>/cwd` equals this review's clone, and kill **that** process's pgid. That also satisfies obligation 1's "never kill a process this run did not start" — the `cwd` filter is what distinguishes this run's server from a live sibling leg's. A recorded PID is a memory; `ps` plus `cwd` is a read. (Worked case: twice in one leg on the A1-487 QA pass, `assoc-one/meirionpritchard-com` PR #166 head `d8ed088`, 2026-09-23 — a negative-control run went fully red against the stale server and only the served-`BUILD_ID` check exposed it, and a `pgrep -f next` recovery attempt killed the agent's shell with exit 144. APP-1694.)

   **And where you bypass the npm script to start the real binary, run its `pre*` hooks yourself — the binary does not.** This obligation's remedy and obligation 1's override config both route around `npm run dev`, and an npm `predev` hook routes around with it. On a repo whose `predev` generates files the repo does not commit — on `meirionpritchard-com`, `tokens:build && prototypes:sync && story-index:sync` — a fresh pinned clone or detached worktree then answers every request with a module-resolution error (`Can't resolve '../design-tokens/generated/tokens.generated.css'`), and Playwright waits out the whole `webServer.timeout` (180 s) before it reports anything. So the first signal is a bare timeout, which reads as a broken harness or a slow machine rather than as a skipped build step. The same omission makes `tsc --noEmit` report missing `*.generated` modules that have nothing to do with the diff, so it corrupts a baseline read as well as a behaviour one. Before the first run in a fresh tree, **read the target script's `pre*` and `post*` hooks in `package.json` and run them once by hand**, and attribute a generated-module resolve error or a bare `webServer` timeout to this before attributing it to the change. (Worked cases: A1-521 QA leg, `assoc-one/meirionpritchard-com` PR #186 head `b398ff8`, 2026-09-24 — the documented workaround was to run the three scripts once in the pinned clone before starting the server — APP-1754; recurrence on the A1-529 QA leg, PR #188, where the same three were needed before `tsc --noEmit` was clean — APP-1748.) Premise unverified — no repo is readable from the refine surface, so the `predev` hook's existence and its three script names are the filing legs' reports; confirm `package.json` against `assoc-one/meirionpritchard-com` at `origin/main` before building. That flag covers that one file only; the resolve error and the 180 s timeout were observed directly.
3. **Prove the harness can fail.** Run it once against a deliberately broken build — a planted sentinel, a removed guard — and confirm it goes red. A verification harness nobody has seen fail is not known to work, and this negative control is the only thing that reliably exposes a false green. **And prove it can *pass* — run an unmodified baseline in the same batch and confirm it stays green.** The negative control alone has two silent failure modes it cannot catch: a harness broken so badly it fails on *everything* (a red that proves nothing), and cache contamination that fabricates a pass. So require the **positive control** alongside it — a matrix where every planted-broken row is red **and** the untouched baseline row is green is evidence; a set of red rows on their own is not. The baseline requirement is language-agnostic and leads; the Python-specific instance sits beneath it — a same-byte-length constant edit (`0.4`→`0.2`, `0.25`→`0.60`, `0.08`→`0.04`) leaves the `.pyc` bytecode cache unchanged, so the check reads the stale compiled test and passes: run with `PYTHONDONTWRITEBYTECODE=1`, clear `__pycache__`, and pass `-p no:cacheprovider`. (Worked case: APP-928, `assoc-one/bot-trader` PR #34 head `5d4e665` — six controls re-ran clean only after clearing bytecode; caught by luck of ordering when control D reported the *previous* control's failure, so a different run order the same session would have shipped a demonstrated-red matrix that was partly fabricated. Same false-green family as APP-664 / APP-726 / APP-748, but the distinct sub-case where the verification was genuinely performed and the instrument lied — APP-941.)

   Where the harness measures **colour** rather than behaviour, the instrument has its own failure modes and they are enumerated in `standard-design-system` (*Measuring contrast in a running browser*) — read that before writing the measurement, not after the first surprising number. (APP-1195.)

   **And an open dialog hides the page behind it from every role-based query — close it before querying, or an empty result reads as a race that is not there.** A modal built on a headless dialog primitive (Radix, Headless UI, and vendored forks of either) marks the rest of the document `aria-hidden="true"` while it is open, as standard focus containment, and Playwright's `getByRole` correctly excludes `aria-hidden` content. So while any drawer, sheet or modal is open, every role-based query against the page underneath returns nothing — no error, no warning, an empty result identical in shape to "not rendered yet". The usual remedies for that shape, `waitForLoadState('networkidle')` and an explicit `waitFor()`, make it worse: they spend the timeout budget on a race that does not exist and then fail anyway. Close the dialog first — the primitive's own close control, normally carrying `aria-label="Close"` — then query. A **portalled** dialog hides this entirely, because the portal moves the dialog outside the tree it hides, so the case where it bites is a repo that deliberately renders in place to keep a scoped token layer applying, and it bites the first browser-driven check ever written against that surface. The cheap discriminator, before reaching for any timing fix: screenshot it, or query the same element by test id instead of by role — if the element is on screen and a test-id query finds it while the role query does not, the cause is `aria-hidden`, not timing. (Worked case, **unverified** here — no repo is readable from the drain surface, so the component structure, the PR state and the quoted header comment are the filing leg's own report, and that flag covers those repo assertions only, not the two library behaviours the rule rests on: `assoc-one/firmup-operator` PR #35, 2026-09-26, `scripts/verify-runtime-addgear.mjs` driving a production build in Chromium — two checks immediately after submitting the Add gear drawer failed to find a button and a table cell that a screenshot showed present and visible, were first misdiagnosed as a data-refresh timing gap through two attempted fixes, and resolved instantly once the drawer was closed; the component's own file header records the deliberate divergence from upstream — no portal, overlay and content rendering in place, so the console's scoped token layer still applies — APP-1799.)

4. **Rebuild after any negative-control batch, before driving anything.** A control that edits a file, rebuilds, runs the check and reverts the *source* leaves the tree clean and the *build output* holding the last break. `git status` cannot see it, and the stale artefact fails in the persuasive direction — a confident false red against working code, on whichever criterion the last break targeted, which is a worse outcome in review than a false green because it is acted on. So wipe the build output and rebuild before any measurement that follows a batch, and report figures from the rebuild. Where a run replays a builder's recipe, note that the recipe's own revert step is a source revert, not a rebuild: the recipe as published ends with the tree clean and the artefact broken. (Worked case: A1-386, `assoc-one/firmup-operator` PR #28, 2026-09-08 — after seven controls, a probe of the run-detail links reported no `?outcome=` on any job, the exact symptom of break B7 and the ticket's most contested criterion; it was caught only because it contradicted a CI check green on the same commit. Distinct from APP-693, whose port assertion passes here — the server was this run's, the build input was not — and from APP-941, whose fix is cache-specific. APP-1197.)

5. **Reproduce the runtime, not just the artefact.** The four obligations above all answer *which artefact is under test*. They say nothing about the **environment it is tested in**, and a harness can satisfy every one of them while measuring a correct build inside a fixture the runtime does not resemble. Three named checks, each the difference between a fixture and the real thing: **(i) the delivery wrapper** — serve the artefact inside the publisher's own skeleton, never a hand-rolled one, because a wrapper that omits what the real one supplies (a viewport meta, a reset, a theme attribute) changes the layout under test rather than the artefact; **(ii) the populated state of any store the page reads** — an empty stub never exercises the restore path, so the one branch most likely to be broken is the one branch never driven; **(iii) the input modality the interface is designed for** — a touch-first surface is not verified by mouse events, and a pointer sequence that works under a mouse can cancel under a finger. The failure mode is the section's own: it fails in the **safe-looking direction**, and a green on a fixture that differs from the runtime is **worse than no harness**, because it does not merely fail to find the defect — it redirects debugging away from the cause, on the strength of evidence that looked conclusive. Where a check cannot be run in the real runtime, say so in the verdict and name the box unverified; do not substitute a fixture and report its green. (Worked case: two false passes in one session on a phone-first artefact never tested on touch — a hand-rolled wrapper omitting the publisher's viewport meta produced a ~980px desktop layout on a page that was correct under the real wrapper, and a touch drag was cancelled by a `pointercancel` no mouse-driven check emits. Distinct from APP-1233's `skill-build-ticket` change, which is about how far a fix reaches, not about what the fix was measured in — APP-1232.)

**(iv) the instrument must still the page, not change it — and a screenshot flag that fast-forwards animation changes it.** Checks (i) to (iii) are about the fixture; this one is about the measuring device. Playwright's `animations: "disabled"` fast-forwards finite CSS animations to their **end state** rather than pausing them. That is harmless for a decorative transition and destructive for anything whose layout is *driven* by an animation: a scroll-linked clip (`animation-timeline: scroll()`) jumps to its end value, the clip stops clipping, and a base-vs-head pixel diff of a sticky or scroll-linked surface goes **falsely red** by tens of thousands of pixels per frame. This is the section's own failure run in reverse — not a green on a fixture, but a red on an artefact that is fine — and it costs the same way, because it sends review after a regression that does not exist and does it on evidence that looks conclusive. So on any page using scroll-driven animation, **do not pass `animations: "disabled"` to `page.screenshot` or `toHaveScreenshot`**: settle the page with an explicit wait instead, and **establish the noise floor with a head-vs-head rerun** before reading any base-vs-head number, because the floor is what separates an anti-aliasing delta from a defect. Playwright's documented end-state behaviour is taken as read here and **not re-measured by the leg that relies on it**. Same false-red family as the 0px touch-gesture case (APP-1975) and the harness-trap case (APP-1694). It lands here rather than in `convention-host-access`, whose *Measuring a live page* governs reaching a page, not the instrument the diff is taken with. (Worked case, **reported** and not re-run from a canon drain's surface: an A1-809 QA leg on `assoc-one/meirionpritchard-com` PR #284, head `80c0f9c`, 2026-10-27, built a base-vs-head comparison to verify "scroll behaviour unchanged" on a sticky header and passed `animations: "disabled"` to reduce noise; the header's `.hdr-clip-*` / `.work-list-clip` construction stopped working, list rows showed through the header on head, and the comparison reported tens of thousands of differing pixels per frame, reading as a real regression in the diff under review. Rerun with animations live, the diffs fell to the noise floor — eye-mark animation, a dev badge, and a 1/255 bullet anti-aliasing difference; `prefers-reduced-motion` was checked and excluded. One rerun cycle, about five minutes, and a false changes-needed bounce if the first run had been trusted — APP-2704.)

**And the box walk reads the criteria against the ticket as created, not only as it now stands.** The walk above tests whether each box is *met*; it assumes the box text is the Owner's. A builder that rewrote a criterion at hand-off — even to explain honestly why it left the box unticked — narrows what review checks, and the current body gives the reviewer nothing to notice. So before any box is assessed, **diff the body's `## Acceptance criteria` **and its `## Definition of done`** against the ticket as created (**the as-created criteria diff covers the Definition of done section too**: the standing per-type bar is rewritable by exactly the same hand as the per-ticket conditions, and a rule naming only the acceptance section reaches a rewritten DoD box by analogy or not at all — two publish tickets carried a DoD box reading "No other file in the repo touched" against a CI step that requires the generated manifest mirror be regenerated and committed in the same commit, and the rewrite at hand-off went uncaught, `APP-3059`)** — the Linear linkback snapshot in the PR comments, or the description history — and where the text has changed, name the change and the words dropped as its own line in the verdict, restore the original wording, and assess against that. A criterion that disappeared is not a criterion that passed, and this is cheap to run beside the structural read that already asserts both headings are present. The prohibition itself stays where it already lives and is not restated here: `skill-build-ticket` holds *"Forge never writes or edits acceptance criteria — that is the author's at refine"*, and `convention-ticket`'s mirror-collision rule already fixes that a builder **declares** a deviation in the PR body and the hand-off rather than rewriting the criterion. (Worked case, **reported**: an A1-804 QA leg on `assoc-one/meirionpritchard-com` PR #285, head `8e5552e`, 2026-10-27 — the last acceptance box was replaced with the exec leg's own wording, which dropped "the Playwright base-vs-head diff" from a gate the exec leg had never run; QA found it only by comparing against the linkback snapshot in the PR comments, restored the original wording, and ran the full desktop base-vs-head diff itself, about forty minutes of suite time, to close the box on its own verification. A reviewer reading only the current ticket body would never have seen that the gate existed — APP-2710.)

   **Check (iii) has one instrument that does not work on this image and one that does — and the broken one fails silently at 0px.** The obligation above is only as good as the gesture behind it, and the obvious gesture is inert here. Measured on the delivery image (Chromium build 1194 / 141.0.7390.37, Playwright 1.56.1): CDP `Input.synthesizeScrollGesture` with `gestureSourceType: "touch"` scrolls **0px** — on a 390×844 `isMobile` + `hasTouch` context, at two start points, on a page whose `html` and `body` overflow is `visible` — while the identical call with `mouse` or `default` scrolls the full requested distance, as does `page.mouse.wheel`. Nothing errors. So a scroll-driven touch harness reports every reveal-on-scroll section as never revealed, and the reds look exactly like a defect in the diff. Three rules follow. **(a) Assert the gesture moved the page.** Any scroll-driven harness reads `window.scrollY` before and after and fails loudly when it did not change — the only reason the observed case was caught rather than filed as ten defects. This is *Prove the harness can fail* applied to the **input** rather than the assertion: a gesture nobody has seen move the page is not known to work. **(b) Use the touch route that works.** `Input.dispatchTouchEvent` as an explicit sequence — one `touchStart`, a run of `touchMove` points, one `touchEnd` — does scroll, and fires genuine `touchstart` and `pointerdown` with `pointerType: "touch"`. It behaves like a real drag rather than a jump, so it covers part of a long page per swipe and is **looped until the target scroll position is reached or the page stops moving**, which rule (a) already detects. **(c) Where neither route reaches the interaction, name the box unverified.** Where the trigger is genuinely modality-independent — an `IntersectionObserver`, which fires on the resulting scroll position however it was produced — the `default` source is a legitimate substitute, but say so in the verdict and say why. That argument does **not** hold for a pointer-coupled interaction (a drag, a swipe-to-dismiss, a touch-cancel path), where (b) is the route and an unreachable check is named unverified rather than quietly run under a mouse. (Worked case: the A1-452 QA leg, `assoc-one/agents-site` PR #14 head `b99fd96`, 2026-10-02 — a 6-run probe found the 0px, and the first harness run reported **10 confident mobile reds** that were the instrument and not the diff, caught only because the harness asserted the gesture reached the bottom of the page. The leg then reasoned the `default` substitution live, correctly for an `IntersectionObserver` trigger, which is rule (c) arriving by improvisation. **Re-measured independently on the refine surface, 2026-10-05**, on an image carrying the delivery signature `convention-host-access` records (`/opt/pw-browsers/chromium-1194`, `playwright` 1.56.1 under `/opt/node22/lib/node_modules`): `touch` 0px at both start points; `mouse` and `default` 1500px; `page.mouse.wheel` 1500px; the `dispatchTouchEvent` sequence 998px in one swipe and the full 8768px of a tall page in four looped swipes, with `pointerdown:touch` and `touchstart` observed on the page. The repo, the PR and the 10 reds remain that leg's report and are **unverified** here — no repo is readable from the refine surface — and that flag covers those three only, not the CDP behaviour or the working route, both of which were re-run. The versions are properties of the image and move with it: `convention-host-access`, *Measuring a live page from the sandbox*. APP-1975.)

   **The runtime also includes the page's own containing box and its own loading model — and a fixture replaces both without showing it.** The three checks above are about what the artefact is *served inside*; two more are about what the fixture *computes*, and neither is visible anywhere in its markup. **(iv) The containing box.** A geometry claim is a claim about a width, and on the real page that width comes from the page's own wrapper markup and CSS, not from the container a fixture chose: a hand-built container reports a row forming at a viewport where the real column is narrower and the row does not form. So either **derive the container from the page's own wrapper and rules**, or report only **relative** claims — *"this rule is what puts them on one row"* — and never **absolute per-viewport** ones — *"side by side at 1024"*. The discriminator costs one assertion and is the same shape as the wrapper check: assert the measured container width against the width the page's own CSS predicts, and the fixture says so immediately when it is measuring its own scaffolding. **(v) The loading model.** Script order, `defer`/`async`, stylesheet order and custom-element upgrade timing are runtime, and no width assertion reaches them: a browser page reused across repeated `setContent` calls has the element definitions already registered, so each element upgrades **at its start tag, before its children are parsed**, where the real page's `defer` scripts register after parsing and every element upgrades with its children present. The rule is **not** *never reuse the page* — a second load into a live document is exactly how a re-render path gets exercised, and on the same repo that is what surfaced a genuine defect in an element that read its children in `connectedCallback`. The rule is: **know which loading model the fixture reproduces, and say which one each assertion is about.** Both faces fail in both directions, and the red is the worse one in review because it is acted on (APP-1197): MBN-275's invented container produced a false **pass** on an absolute per-viewport table — a 35%-wide text column meant the row formed only at ≈1184px, not at the 1024 the table claimed — while every other number in the same table was right; MBN-276's reused page produced a confident false **red**, `Cannot read properties of null` inside `setActiveMedia`, against correct upstream code the diff never touched, one bounce away from spending a full exec cycle on a non-defect. Neither was reachable from the harness's own evidence: negative controls prove the harness can fail, not that it is measuring the page. (APP-1341, recurrence of APP-1232.)


   **And a browser can satisfy one element's measurement from another's cached response — so a multi-element comparison fixture loads one element per page, or cache-busts every scenario's URLs.** (vi) joins the list, and it bites wherever the fixture measures what the *browser decides* rather than what the page declares — `srcset`/`sizes` candidate selection above all. The decision is taken against a cache the fixture shares across every element on the page and across every scenario that page is reused for: headless Chromium is permitted, and in practice willing, to satisfy an `img`'s candidate selection from an already-cached response that meets the computed requirement rather than fetching the candidate that element's own `sizes` computation names. Several `<img>`s with overlapping candidate URLs on one page therefore let one element's fetch cover for another's, collapsing two scenarios that must differ into one observed pick — and it collapses them in the direction that **masks** the shortfall under test, which is this section's own failure direction. Build it the other way: **one element per page load**, or a unique cache-busting query string (`?s=<unique>`) on every candidate URL in every scenario, so no two measurements can be served the same bytes. And hand-calculate one row before trusting the table: **two formulas that must clearly differ reporting the identical pick is the tell**, and it is the only signal the harness itself emits. (Worked case: the MBN-319 round-2 QA bounce, `assoc-one/mbn-theme` PR #25 head `59c7875`, 2026-10-03 — four `<img>` elements with overlapping `srcset` sets on one page, loaded once per scenario across six viewport/DPR combinations, reported the known-short old formula and the fixed new one both picking 940w on tablet, against a hand calculation of 720w for the old; re-measured one element per load with cache-busted URLs, the hand-calculated values reproduced exactly and the real shortfalls surfaced. The defects the bounce existed to fix would otherwise have been masked by the instrument that was measuring them. `skill-build-ticket` step 3c is what makes this a recurring shape rather than one ticket's accident — a visual or sizing criterion is met by driving a real browser, so a measurement fixture is written on most such tickets. Premise unverified — no repo is readable from the refine surface, so the fixture, the figures and the PR state are the filing leg's report, and the two measurement scripts were session-local and never committed, making the note the only durable record; that flag covers those premises only, not the cache behaviour the rule rests on. APP-2013.)

   **And a runtime gate is only a gate if it ran on the route under test — an instrument that structurally cannot reach that route returns a pass and no evidence.** (i)–(vi) govern a fixture that resembles the runtime badly; this governs one that cannot address the subject at all, and it is the harder failure to see, because the gate does not error — it goes green and a box gets ticked. Two shapes have now recurred: a **fixed all-live stub fixture with no create or lifecycle routes**, so the admin path the criterion names was never exercised by anything; and a **host-gated behaviour verified on a stand-in route** — a test page, a throwaway route — because the real route is believed undrivable. In both the box was ticked and the verdict carried no qualifier. So: **a runtime gate names the route it ran on, and that name is checked against the route the criterion is about.** Where they differ the box is recorded **unverified**, not ticked, whatever the gate returned — and a QA leg reading an exec acceptance box of this shape re-reads it to the same standard, which is the exec-harness rule below applied to reachability rather than to provenance. Two sub-rules make that checkable. **Test the claim that the route is undrivable before accepting it**: that is usually a property of one blocked dependency rather than of the route, and an egress-blocked data fetch is a stub away from drivable — a repo's own `CLAUDE.md` naming a route undrivable is recording the block, never ruling the route out (`convention-sanity` carries the Sanity-egress instance and the identical-stub-on-both-trees recipe). **And read what a stand-in route structurally cannot carry**: render mode, caching, revalidation and host behaviour belong to the real route's own entry, so a green build and a passing stand-in say nothing about any of them. (Worked cases — two repos, two instances of one mechanism. `firmup-operator`, 2026-09-28: `verify-runtime`'s stub is a fixed all-live fixture with no admin create or lifecycle routes, so a lifecycle criterion was gated against a surface that has none — APP-1796. A1-586 QA round 2, `assoc-one/meirionpritchard-com` PR #220 head `8878c92`, 2026-10-03: the production-host gate ran on `/work-test` plus a throwaway route and never on `/`, the box was ticked, and what the gate could not reach was `headers()` in `src/app/page.tsx` moving the public homepage from ISR (`○ /`, revalidate 1m) to per-request dynamic rendering (`ƒ /`), with `npm run build` exiting 0 read as a happy side effect; QA surfaced it only by stubbing `sanityFetch` identically on base and head so that both trees build and the two route tables compare — APP-2018, which is cited here as the second instance and is **not** folded by this rule. Premise unverified — no repo is readable from the refine surface, so both repos, the PR and head, the file paths, the stub's shape and the route-table symbols are the filing legs' reports; that flag covers those premises only, not the rule, which stands on the mechanism. APP-1796, returned to Backlog 2026-10-05 on its own re-tested condition.)

If provenance is in doubt after a run, **do not reason that the build was identical anyway**. Wipe the build output, rebuild, move to a verified-free port, and re-run the checks in full; report the verdict on the re-run, not the first pass.

**Run the negative control in an isolated tree, never the working checkout.** A QA negative control — revert to base, add a probe, re-run to prove the check goes red — is a *read*, not a resolution: run it in a throwaway or isolated worktree, never the working checkout the exec leg is using. This is the mirror of `skill-merge-pr`'s "abort the worktree merge when done — this is a read, never a resolution": the control exists to observe the base state, not to leave the tree changed under the leg still building on it. And **never trust a negative control against stale build artefacts** — a leftover `.next` cache serving the PR's stylesheet against base tokens gives plausible-looking garbage, a red that proves nothing or a green that hides the defect. Inspect an isolated tree with its own clean build, not shared stateful build output. (APP-970.)

**Pin the whole review to the head under test, and re-assert it.** A verdict is a claim about one commit, so read that commit from a tree nothing else can move — `git worktree add --detach <sha>`, or a clone pinned to the PR head — and never depend on a shared checkout being on the right branch when the check runs. Where a shared tree is unavoidable, read `git rev-parse HEAD` immediately before **and** after every tree-dependent check, and re-derive in an isolated tree if it moved. A sibling leg switching a shared checkout under a live review produces a **false clean**: base content verified and reported as head content, with the tree clean, nothing red, and both of the signals a reviewer would use to detect it saying everything is fine. This is APP-970's hazard in the opposite direction — that rule keeps QA's controls out of the driver's tree; this keeps everyone else out of QA's reads. (Worked case: APP-1173, `assoc-one/claude-ops` PR #188, 2026-09-08 — detected only because the leg happened to re-hash a file it had already hashed and saw the digest fall back to its pre-publish value; the review was redone in a clone pinned to `1914c78`. APP-1189.)

**A leg whose working directory is not the repo it must read clones that repo; it does not read the sibling checkout. That covers the repo under review and the instrument a check runs on.** A QA leg is spawned in a worktree of whichever repo the driver holds (`routine-delivery-loop`, *Spawn the QA subagent with* `isolation: "worktree"`), and that is not always the repo the ticket is about — on 2026-09-11 five legs ran with a worktree of one repo and a PR in another, including one whose worktree was the right repo while the check it had to make needed the sibling. The pinning rule above already settles the answer and this states it for the cross-repo case: **clone the repo under review into the scratchpad,** `git fetch origin +refs/pull/<n>/head`**, check out** `--detach` **at the head SHA, and confirm the base has not moved** — then `npm install` per `convention-github` *Fresh clones*, or hard-link the sibling's `node_modules` once `package-lock.json` is confirmed byte-identical by digest, never symlink it. Reading the sibling checkout instead is refused in every form, `git -C` and `cd … && git` alike, and the refusal names the worktree rather than the action that is actually available (`convention-agent-runtime`, *Isolation*) — so a leg that has not read this pays a dead turn to learn it. Where a check genuinely needs the sibling tree *in place* rather than a clone of it — a suite that runs against an installed sibling — name the box unverified in the verdict and say why; do not report a clone's green as the sibling's (APP-1340, APP-1342, APP-1353).

**Where the repo under review is the leg's own, pin it with a worktree of that repo — the route the guard lets through.** The worktree guard reads the command string (`convention-agent-runtime`, *Isolation*), and a worktree the leg adds to its own repository passes it even when the destination lies outside the leg's worktree. So the same-repo recipe is, one plain command per call with absolute paths: `git fetch origin +refs/pull/<n>/head:refs/qa/pr<n>` from the worktree; `git worktree add --detach <absolute scratchpad path> <sha>` for the head, and again for the base where a base build is needed; `npm install` in each pinned tree, or `cp -al` of `node_modules` once `package-lock.json` is confirmed byte-identical by digest; and `git worktree remove --force <path>` for each when the review is done. Single-verb git from the worktree passes too — `git rev-parse`, `git diff <base> <head>`, `git show <sha>:<path> | sha256sum`. The same recipe issued as one script is refused, and so is the cross-repo clone recipe above: issue it one command per call as well. **A probe lives inside the pinned tree, never in `/tmp` or at the scratchpad root.** A script or bundle outside the tree cannot resolve the repo's `node_modules` (`ERR_MODULE_NOT_FOUND`), so write it into the pinned tree, run it from a file rather than `node -e`, and delete it afterwards. Import Playwright as `@playwright/test`, not `playwright`. (Worked cases: the APP-1538 QA leg, `assoc-one/claude-ops` PR #259, 2026-09-18 — base `72ae362d` and head `be36187` pinned this way, every build normal, both trees removed afterwards — APP-1539; the A1-443 leg paid about six dead turns rediscovering the fetch-to-`refs/qa`, the probe placement and the package name — APP-1552 §1; the batched form refused on APP-1496 — APP-1513 §1.)


**The instrument repo is the same rule with a different trigger.** A check can need a repo it is not reviewing: on every canon-publish ticket the render check builds `agents-site` twice, base and head, per `claude-ops`'s own CLAUDE.md *Checking the agents-site render from a delivery run*, and `agents-site` sits beside the `claude-ops` checkout as a refused sibling. The remedy is the one above and the reasoning is the one above — work from an isolated copy, never the sibling in place. Copy the tree into the per-ticket scratchpad excluding the build products and heavy directories that do not need to travel (`node_modules`, `.next`, `content`, `public/downloads`), confirm the copy's `package-lock.json` digest matches the sibling's, hard-link its `node_modules` with `cp -al` rather than paying a cold `npm install`, and run both builds from the copy. Name the trigger when filing against this rule, because the two cases are not duplicates of each other: the repo under review is cloned so the review is pinned to one head, and the instrument is copied so a concurrent leg's build products cannot land in it mid-run. The isolated copy is therefore **stronger** isolation than a shared instrument checkout, not merely a route around the guard, and that is worth stating in the verdict rather than leaving implicit. (Worked case: APP-1525 — the QA legs on APP-1488 and APP-1492, both 2026-09-18, re-derived this recipe independently in one extra turn each, on the most repeated action in the publish-ticket family. The PR numbers, the `agents-site` build pipeline and the digest match recorded there are **unverified** in this session: no GitHub access and no Owner machine, so none of them was re-run or re-read here.) **Read the instrument's revision as files, not through git.** A `git rev-parse` against the sibling is refused like any other git call there. So take the copy with one non-git command (`tar` into the per-leg directory has worked), then read the sibling's revision as plain files: `.git/HEAD`, then the ref file it names under `.git/refs/heads/`, or `.git/packed-refs` where the ref is packed. Record that SHA in the verdict beside the copy's digest. (APP-1539, the APP-1538 QA leg, 2026-09-18.) **And read the revision *before* the copy, as a gate and not only as provenance.** The sibling is a live working tree: it can sit on another leg's feature branch, and every control this rule names is satisfied by copying it anyway — the copy is isolated, the lock digest matches, the build is this leg's own — while the check runs on an unreviewed revision of the instrument. Recording "the instrument was at revision X" does not help when X is a branch nobody reviewed: the verdict then truthfully reports a figure measured on the wrong instrument, every number real and none attributable. So where the sibling's `.git/HEAD` does not name the instrument repo's **default branch**, clone the instrument fresh at `origin/main` into the scratchpad instead of copying the sibling, and record that SHA. The digest-confirmed `cp -al` of `node_modules` still applies either way — it is gated on `package-lock.json`, which is branch-independent. Where a check genuinely needs the sibling *in place* at its current revision, the escape above applies unchanged: name the box unverified in the verdict and say why, so a nameable limitation does not become a silent one. (Worked case: the APP-1617 QA leg, 2026-09-22, found the sibling on branch `claude/amazing-davinci-z11m1m` — a live sibling leg's working tree, not `main` — and avoided the wrong-instrument measurement only by happening to read `.git/HEAD` before copying, then cloning fresh from origin. The branch name and the resulting SHA are as that leg reported them and are **unverified from the drain surface**, which can read no repo — APP-1656.)

The same standard applies to **exec's harness when QA is reviewing it**. A green from a script that could have passed against an artefact it did not build is not evidence: treat that acceptance box as unverified — a changes-needed signal — and name the missing guard (port-free assertion, real-binary spawn and group kill, negative control, positive baseline control) as the fix bar. This is the false-green class already in canon (`skill-merge-pr`'s present-and-concluded check; APP-450's Playwright suite that never ran), one layer down — in the verification scripts the repos own rather than in CI's own reporting.

(Worked case: twice in one run on A1-242, two agents and two independent harnesses hit the same trap. Exec's runtime check spawned the server via `spawn('npx', ['next', 'start', …])` and shut it down with `app.kill()`, orphaning the real `next-server`, which kept the port; the readiness probe then succeeded against the orphan and every assertion ran against a stale build. It surfaced only because a deliberately planted leak was reported clean **twice**, which was implausible enough to investigate — `ps` showed two orphaned `next-server` processes from earlier runs. QA's own harness hit it in the same session, caught it during cleanup, and rebuilt from a verified-free port rather than assuming the build was the same — APP-693.)

## Comparing a port against its prototype — values pass, mechanisms break

Where the ticket's spec is a prototype rather than prose — a Claude artefact, an attached HTML file, a standalone demo — the acceptance criteria are written as measurements: heights, colours, timing constants, cubic-béziers. Those are checkable against the diff, and checking them is not the same as checking the port. A port required to reuse the site's own chrome instead of the prototype's — the right call architecturally — is a manual re-implementation across two CSS systems, and the **mechanism** by which two elements relate (stacked rather than adjacent, cross-fading in place rather than swapping) is carried by no stated value. Every measurement can pass while the mechanism is silently gone.

So on any ticket whose spec is a prototype, make the rendered comparison a **separate, named obligation** beside the acceptance criteria, and report it as its own line in the verdict:

- **Load both and compare the same element in the same state.** The deploy preview or local build beside the prototype, in one browser session at one viewport — the recipe in `convention-host-access` (*Measuring a live page from the sandbox*) is the instrument, and the delivery image already carries Chromium.
- **Compare the properties that carry the mechanism, not the ones the criteria list.** `getComputedStyle` on the two corresponding elements and the bounding boxes of their children: a parent that is `display: grid` in the prototype and `display: flex` in the site silently voids every `grid-area` on its children, and the tell is two boxes side by side where the prototype stacks them at one origin.
- **Drive the interaction and compare at the same phase.** A cross-fade and a swap are identical at rest and differ only mid-transition.
- **A verdict that did not do this says so.** "Criteria verified, no rendered comparison run" is an honest clean; silence reads as a comparison that happened.

This class of bug is invisible to a values check by construction, and it has now been found twice by the Owner's eye on a deploy preview rather than by either leg. (Worked cases: A1-573 / `assoc-one/agents-site` PR #18, 2026-09-30 — the send-button icon cross-fade depended on `display: grid` from the prototype's own `.icon-btn`, the site's shared `.nx-action-icon-btn` is `display: flex`, `grid-area: 1 / 1` on the two icon SVGs did nothing, and the icons laid out side by side and jumped sideways instead of cross-fading in place; exec's own verification and an independent QA pass both returned clean against the criteria, and the Owner found it in under a minute beside the artefact — APP-1899. And A1-555, where the same pair of legs confirmed a restated mechanism and the Owner's live comparison caught it — APP-1839, whose rule is `skill-build-ticket` step 3's *the source outranks every restatement of it*. `meirionpritchard-com`'s own `CLAUDE.md` carries this as a repo rule — interaction work accepted against the prototype visually, QA verifying against the Vercel preview alongside it — and this raises that rule into shared canon. Reported, not observed: no repo is readable from the refine surface, so the class names, the display values and the repo rule are the filing leg's report; that flag covers those repo assertions only.)

**A bounce bar stated as a size cannot tell two shapes apart — for a glyph, icon or vector port the bar names shape, not only box.** *Stating the defect* already requires the bar the fix will be judged against, and APP-1455's rule is that **a figure is a claim, so state its boundary**. A geometry bar is where that rule arrives without looking like a figure: "the painted mark spans the source's 18×18 box within ~1px, centred" is complete, checkable and measurable — and **every shape that fits that box satisfies it**. The next pass then meets the bar exactly and ships the wrong mark, with the verdict and the hand-off both correctly reporting the bar as met. So when bouncing a glyph, icon or vector port, the bar names the **shape** properties as well as the box: **arm or segment count, the angles, the extents, stroke weight and cap, and whether the form closes** — measured as a **side-by-side painted comparison against the design source's own render**, never against a description of it or an eye over it. Note the boundary this shares with the section above: that governs the **mechanism** a values check cannot see; this governs the **form** a geometry check cannot see, and the two fail independently. The route to the design source's pixels when the asset download is proxy-blocked is in `convention-figma`, *Review* → the read-side rules. (Worked case: A1-581 / `assoc-one/meirionpritchard-com` PR #221, 2026-10-04 — round 1 bounced an undersized ✱ on a box bar at head `4cd0e65`; round 2's hand-authored SVG met that bar exactly with a **6-arm** asterisk (vertical plus 30°/150°) where Figma's `icon/selector-3` (151:228) is **8-arm** (0/45/90/135°, diagonals ending inside a circle), and the exec leg reported it "confirmed visually symmetric against Figma's own screenshot". Round-2 QA caught it only by decoding the source's native 20×20 render to an ink map and rendering the PR's polygons the same way — a second bounce, taking the ticket to the 2-strike cap. The PR number, the two heads, the comment IDs and the node ID are that leg's report and are **unverified** here: no repo and no Figma file is readable from the refine surface. That flag covers those identifiers only — the rule follows from APP-1455, which is already canon. APP-2022.)

**A bar the Owner judges by eye needs an instrument that measures what the eye sees — the unit and the quantity, not a number that merely moves.** The two rules above both govern what a check *compares*: the one above governs the **mechanism** a values check cannot see, and the APP-2022 rule the **form** a geometry check cannot see. This one governs what a check **measures**, and it is the third independent failure in the set. Where an acceptance bar is stated perceptually — "clearly visible at normal scroll speed", "reads as one motion", "obvious without looking for it" — a trace can satisfy the words numerically and be imperceptible in the browser, because a per-frame number carries two choices the bar does not make: the **unit** it samples on, and the **quantity** it samples. Neither is implied by the words. A whole section is not a unit a person perceives — a section-sized band presents each of its elements with no neighbour to move against, so the band can travel while nothing on screen appears to — and opacity is not displacement: a mark can fade in over a few pixels of travel and read as static. So on any perceptual bar, three things: **sample the element a person watches, not its container**; **measure the quantity the bar names** — visible displacement against elapsed time, not opacity alone; and **state the threshold the measurement clears**, a minimum travel and a duration, so the next pass is judged against a figure rather than a word (APP-1455 — a figure is a claim, so state its boundary). And **name the Owner's own look as the bar's final judge, never the instrument**: this section already records that this class has been found by the Owner's eye on a deploy preview rather than by either leg, so a verdict on a perceptual bar reads "measured per element, 64px of rise over about 1s at normal scroll speed; the instrument agrees with the bar and the preview is still the decider", never "visible, confirmed by trace". A perceptual bar is the Owner's *what*; which unit and quantity the instrument samples, and the threshold it reports, are the review's *how*. (Worked case: A1-452 / PR #14, 2026-10-02, two rounds on one root. Round 1 (scroll-linked, 14px) and round 2 (time-based, 32px, whole sections of about 1,400px) were both cleared against "clearly visible at normal scroll speed" from a per-frame opacity trace of each whole section — 0.15 opaque at 160px into view — and the Owner saw no movement on the preview both times. The fix was a per-element reveal, a 64px rise over about 1s, re-verified at head `1a3186f` by sampling each element. Premise unverified — no repo access from this refine surface: the repo, the PR number, the head SHA, the pixel and timing figures and the trace values are the filing leg's report; that flag covers those figures only, not the rule, which rests on the mechanism and on APP-1455, already canon. APP-2036.)

## Proving the baseline

`Proving the artefact under test` establishes that the process answering is the build this run made. Its companion problem is the *before* state: where an acceptance claim is an absolute before/after figure — "reduced the divider from 2px to 0", "cut N differing pixels to 0" — the baseline measurement is as corruptible as the artefact one, and in the same safe-looking direction. A wrong baseline manufactures a plausible delta that reads exactly like a real one.

Three obligations, in order, before asserting any absolute before/after:

1. **Measure the before-state cleanly — and the enemy is the framework build cache, not an in-place file swap.** The intuitive remedy — "take the before-state measurement in a clean checkout, a `git worktree` at the base commit, never an in-place swap in the working tree" — is **wrong on the repo where this keeps happening**: on `meirionpritchard-com` a sibling `git worktree` cannot boot, because `node_modules` is not shared across worktrees and symlinking the main checkout's is rejected outright by Turbopack (`Symlink [project]/node_modules is invalid, it points out of the filesystem root`), so a worktree needs its own full `npm install` per measurement — a very different cost from "make a clean checkout", and not obviously worth it per baseline. The real fault is not the file swap; it is a stale **`.next` build cache on disk** that serves pre-change bytes and **survives an ordinary dev-server restart**. So the working shape is: stay in the one working tree, and make **`rm -rf .next` a mandatory step before *every* measurement in either direction** — not a recovery action taken once the numbers look wrong. Concretely: `git checkout <base> -- <files>` → wipe `.next` → measure → `git checkout HEAD -- <files>` → wipe `.next` → measure.

   **And the cache is not only the framework's — a compiler's incremental cache defeats the same baseline, and a stash that silently did nothing defeats it one layer earlier.** Two traps sit on exactly this path, both structural to the tooling rather than one-off mistakes, so a repo need not be this one for them to fire. **First, `tsconfig.tsbuildinfo`.** Where `tsconfig.json` sets `"incremental": true`, the build-info file persists across a `git checkout` or a `git stash`, and `tsc --noEmit` on a tree restored to base returned **0 errors** on a tree that, freshly checked, genuinely had a different error count. So `rm -f tsconfig.tsbuildinfo` before *every* authoritative `tsc --noEmit` run, in either direction, on the same terms as `rm -rf .next` above. **Second, the tree may not be the tree you think.** `git stash push -- <pathspec>` aborts the whole push when the pathspec matches nothing and still leaves the edits in the working tree; the `git status` that follows then reads as "the stash worked and these are the remaining changes" rather than "no stash was ever created", and the baseline measurement runs against the modified tree while believed clean. So **confirm the entry exists (`git stash list`) before trusting any tree as a baseline** — the same cheap assertion as the DOM discriminator and the served-asset grep below, one layer up in the tree rather than in the measurement. Mind too that a correctly re-baselined run surfaces pre-existing errors the stale read was hiding, in files the diff never touched; that is the baseline working, not a regression in the change. (Worked case: A1-528, `assoc-one/meirionpritchard-com`, 2026-09-24 — both traps in one session, the stash aborting on `git stash push -- src/sanity/schema.json` for a file that sits at the repo root — APP-1749.) Premise unverified — no repo is readable from the refine surface, so `tsconfig.json`'s `"incremental": true` setting and `schema.json`'s location are the filing leg's report; confirm them against `assoc-one/meirionpritchard-com` at `origin/main` before building. That flag covers those two premises only; `git stash push`'s abort-on-bad-pathspec behaviour and TypeScript's build-info persistence are general tool behaviour.
2. **The baseline harness carries its own negative control.** A before-state harness that cannot fail is exactly as untrustworthy as an after-state one (see *Proving the artefact under test*, obligation 3) — a stale read yields a plausible baseline number that no one has ever seen the harness reject.
3. **Assert an absolute before/after only once that control has passed.** A *relative* claim ("this changed") can survive a stale read; an *absolute* one ("2px → 0") cannot — so pin the absolute figure to a passing control, not to a first-pass reading.

**A change that fixes, sticks or otherwise overlays part of the viewport invalidates every consumer that reads viewport-relative positions — verify the readers, not the overlay.** The element's own sweep, its geometry at scroll 0 and a pixel diff all pass while a consumer breaks, because the overlay changes what a viewport coordinate *means* to code written before it existed: `getBoundingClientRect().top` thresholds, active or hover lines measured from the viewport top, scroll-into-place targets, `IntersectionObserver` root margins. So where a diff introduces or moves `position: fixed` or `position: sticky`, or any layer covering a band of the viewport, grep the repo for those reads, list the consumers found, and probe each one **past** the overlay's own transition — past the collapse, past the hand-off, not only at scroll 0 — then record which consumers were probed and at which scroll positions. A consumer the probe never reached is unverified, not unaffected. (Worked case: A1-578 / `assoc-one/meirionpritchard-com` PR #212, 2026-09-30 — the Work header became `position: fixed`, the exec leg asserted the mobile active line was unaffected because row 0's position at scroll 0 was unchanged, and the D080 / A1-563 active line, measured from the viewport top, put the highlighted row under the nav and fully hidden on mobile once the header collapsed; QA caught it with a scroll probe past the hand-off, and the fix, logged as D091, measured from the nav's bottom edge — one QA bounce, APP-1925.)

**A "nothing else moved" claim is about pixels, not about components — an element screenshot moves when anything *above* it changes height.** An element-scoped screenshot is a clip out of a full-page raster, so its bytes depend on where the element lands on the page as well as on the element itself. A block whose own geometry is untouched — identical measured height on both sides — still rasterises one row taller or shorter when a taller block above it shifts its sub-pixel offset across a rounding boundary. So a PR asserting that the blocks it did not touch are unchanged is asserting something stronger than it verified, and the failing baselines look like an unexplained regression in code nobody edited. Test the claim the right way round: **enumerate the moved baselines from the run, then explain each** — either the element changed, or a named ancestor or preceding sibling changed height and displaced it — and where displacement is the explanation, record the measured offsets on both sides so the next reader can tell a benign re-raster from a real layout change. Never wave a moved baseline through as "probably displacement" without the pair of offsets. (Worked case: A1-414, 2026-09-12 — two `resultsCredits` baselines moved on a PR that changed nothing in that block; height identical at 225.5px on both sides, the element's sub-pixel offset moved from `.188` to `.719` under a taller block above, and the clip rasterised one row taller. The PR had asserted nothing else moved — APP-1384.)

**A whole-tree property is compared against the PR's own base, and the shippable figure comes from the merged tree — never branch-against-current-`main`.** Where the measured property is a property of the *whole* tree or site rather than of the diff — dead-link counts, artefact counts, per-type histograms, rendered-page inventories, bundle size — and sibling work has merged since the PR branched, `main` and the PR's base are different trees and both differ from what the merge will produce. A branch-versus-`main` diff then credits the PR with every sibling's change, which is the false-positive direction: it inflates the apparent benefit of the change under review, every individual build succeeds, every number is real, and nothing in the comparison looks wrong. So take the baseline from the PR's **own base**, and take the figure a verdict quotes from the **merged tree** (`git merge origin/main` into a detached worktree at the head, then measure) — that is the tree that ships. A branch-versus-`main` figure is not a valid attribution and does not appear in a verdict. **The tell is one command, so detect the condition rather than discover it:** `git merge-base HEAD origin/main` returning anything other than `origin/main` means the base has moved and this rule is live. **And the tell is only as fresh as `origin/main` — fetch the base by name before reading it, because the pinning recipes do not.** Both the same-repo PR-ref fetch and the cross-repo clone-plus-PR-ref fetch update the pull-request ref and nothing else, so a tree pinned minutes ago can hold an `origin/main` from whenever the clone was taken. The comparison then returns "base unmoved" against a stale local ref and the merged-tree check is skipped — silently, and in the flattering direction, the same shape as `skill-merge-pr`'s `FETCH_HEAD` substitution (APP-1415) reached by a stale operand rather than a wrong one. So run `git fetch origin main` as its own command before the comparison, resolve both operands by name, and where no fetch is available read the remote tip directly — `git ls-remote origin refs/heads/main` — and compare against that. (Worked case: the A1-581 round-4 QA pass, 2026-10-08 — the leg fetched only the pull-request ref and found the real tip only because it also ran `git ls-remote`; a leg that did not would have read "base unmoved" and skipped the merged-tree check. One instance — APP-2186. The head SHA and the exact fetch that leg ran are its own report and are **unverified** here, no repo access from the refine surface; that flag covers those two only — that a PR-ref fetch does not advance `origin/main` is general git behaviour.) Expect it as the norm, not the edge, on canon-publish tickets — `skill-ops-sync` splits a parity run into several batches that all branch off one `origin/main` and merge in sequence, so by the time batch *n* is reviewed, batches 1…*n−1* are already in `main`. (Worked case: APP-1174 / `assoc-one/claude-ops` PR #189, 2026-09-08 — dead `/downloads/*.md` links measured branch-against-`main` reported the PR closing five 404s. The four-way read gave 8 at the PR's base, 8 at its head, 13 at current `main` and 11 at merge(`main`, PR): the true figure is two, and the other three moved because sibling batch APP-1173 had merged fifteen minutes earlier and introduced the forward references in the first place. A verdict citing "closes five 404s" would have put a fabricated figure into the canonical record with full apparent evidence behind it. Same false-green family as APP-693 and APP-450 — the measurement was real and was not measuring what the verdict would have claimed. APP-1192.)

Two cheap guards that actually located the fault, both belonging wherever the before/after method runs:

- **Assert a DOM discriminator in the harness.** A structural count that differs by construction between the two states — `.nav-row .nav-item` was 5 before the change and 6 after — so a "before" run that reports 6 is measuring the wrong tree and says so immediately. This is what finally separated the two states reliably.
- **Grep the served asset for a token unique to the change before trusting any measurement taken through it.** One `curl` of the served chunk plus `grep -c` on a token the change introduces is the check that directly locates a stale-cache fault — the served CSS returned 0 for `view-cell` while `src/app/globals.css` had 2. One `curl` + `grep -c`, and it is the check that actually found the fault.
- **Create the capture directory; never `mkdir -p` it — and prove the two captures are of different trees before comparing them.** Where a check captures build output to disk to diff two states, the capture directory is itself a provenance surface, and the session scratchpad is **shared** — the exec leg whose work is under review writes into it, and so do sibling legs running concurrently. Legs doing the same job reach for the same names, so `out-base`/`out-head` is a collision by default rather than by bad luck. The failure is silent at every step: `mkdir -p` is a no-op on an existing directory and reports nothing, and `cp -r SRC DEST` **nests** when `DEST` exists and **creates** when it does not, so the capture lands a level deeper (`out-base/content/content`) while the earlier leg's copy stays exactly where the comparison then reads it, with every command exiting zero. So **create the directory and fail if it already exists**, namespace it by ticket, and **assert a discriminator** before trusting either side — text the PR introduces must be *absent* from the base capture and *present* in the head capture. That is the filesystem analogue of the DOM discriminator above, and it is what turns a contaminated read into an immediate stop. The discriminator must be **unique across the whole base capture**, not merely new to the changed file; where it does appear in the base, **name the artefact carrying it before concluding contamination** — a fragment duplicated in an untouched sibling is a bad discriminator, not a bad capture. The trap is likeliest on exactly the edit canon-publish tickets carry most, an artefact brought into line with wording a sibling already holds. (Worked case: APP-1377 / `assoc-one/claude-ops` PR #238, head `ff8c647`, 2026-09-14 — `read-only on Linear, one field excepted`, taken from the PR's added lines, read as present in base because untouched `skill-attention-sweep` already carried it; a unique fragment behaved correctly on all three artefacts — APP-1444.) The driver's `isolation: "worktree"` spawn does **not** isolate the scratchpad — verified, no longer open: `routine-delivery-loop` documents it as giving QA its own git worktree, and a leg spawned that way found nine sibling legs' directories in the scratchpad, the exec leg's for the ticket under review among them, beside loose top-level `base-out/`, `head-downloads.html` and `artefacts-diff.txt` (APP-1513, 2026-09-15). So apply these two guards rather than relying on the spawn, read the QA leg's independence as holding at the context and checkout layers only, and **never leave a generic name at the top level of the scratchpad** — everything a leg writes sits under its own ticket-and-leg directory, because a loose generic name is the next leg's collision. (Worked case: APP-1296 / `assoc-one/claude-ops` PR #216, 2026-09-10 — the render check's `out-base/` and `out-head/` already existed, written by the same run's exec leg; the contaminated comparison reported that none of the nine artefacts under review had changed and that one artefact the PR does not touch had, which reads as "the change did not reach the site" — a plausible, fully evidenced, wrong block. It was caught by a file modification time an hour older than the builds: luck, not procedure. Prior near-miss between two parallel exec legs on the same shared directory name, APP-1247 / PR #200, same day — APP-1280.)
- **And where both legs run independently-written diff scripts over the same two captures, a disagreement between their counts is itself a finding — record it in the verdict and treat the lower count as the suspect one.** The two guards above make each leg's own comparison sound; this one governs the case where both are sound and they still disagree. "0 differing" is a strictly stronger claim than "0 real differences", so the script reporting the lower figure is the one that may be filtering a class of difference out of the count before comparing, and the leg holding the higher figure cannot tell a filter from a genuine match by reading its own output. So **name both counts, both scripts and the pages each one found, and classify every page the higher count holds as apparatus or real** — an apparatus difference (a commit count, a build timestamp, a published-on date) is non-blocking and still belongs in the verdict as a reported difference, never absorbed into a zero. A verdict that settles the two figures by preferring the lower one has settled nothing: the standing rule in this family is that a figure a reviewer cannot reproduce from a named ref is a defect in the claim, not a disagreement between two legs to be reconciled (`skill-build-ticket`, APP-2826), and the same holds for a figure the other leg's instrument contradicts. (Worked case: APP-2846 — on APP-2816 / `assoc-one/claude-ops` PR #606, head `35e87b7`, the exec leg's base-vs-head render-check script reported 0 semantically differing pages while QA's independently-written script found 2, `changelog.html` and `proof.html`, both the documented `git.commitCount` apparatus; QA's verdict stayed clean and the exec leg's zero went unchallenged, so neither leg's output recorded that the two scripts disagreed.)

**And beware `pkill -f <pattern>` — it kills the agent's own shell, whatever the pattern is.** The pattern matches the running bash command's own string, which by construction contains the pattern, so the command exits 144 and anything chained after it never runs — three "stop the server and clean the cache" commands can silently clean nothing while appearing to fail only at the kill step. **This is not specific to `next dev`, and a bracket escape does not reliably defeat it:** a pattern written defensively as `qa-start[.]cjs` precisely to avoid self-matching hit it too. So treat **any** `&&` chain after a `pkill` as not having run, and re-issue the remainder as separate calls — which is independently what `convention-agent-runtime`'s *Isolation* one-plain-command-per-call form requires. (Worked cases: `next dev`, APP-967; other patterns including the bracket-escaped one, the A1-457 QA leg 2026-09-21, APP-1627.)

This serves **both legs**: exec needs it for the base-vs-diff comparison `skill-build-ticket` step 4 already requires, and QA needs it for the baseline claim. Same false-green family as APP-693 / APP-941, one step upstream in the baseline — and a first wrong conclusion that happens to be right is the worst case, indistinguishable from a real green. (Worked cases: A1-334 / A1-335, `assoc-one/meirionpritchard-com`, 2026-08-16 — the `.next` cache served stale bytes across three clear attempts on both the exec and QA legs, a false regression each time; `rm -rf .next` was the only fix, and the `git worktree` remedy failed to boot at the first step — APP-967.)

## Build-product acceptance criteria — verify the producer, name the staleness window

Some acceptance criteria are phrased about "the report" / "the output" / "the file" when that names **two different things**: the **producer** — the code that generates it, which the PR changed — and the **committed artefact** — a build product (a generated report, snapshot, export, derived CSV) regenerated on a schedule and checked into the repo. Every such AC is satisfied by reading the producer and can still be *unsatisfied* by reading the committed file, which at the PR head commit may still show the exact defect the ticket was raised about until the next scheduled regeneration.

The rule, so this is settled once rather than re-derived each run:

1. **Verify the producer.** Run or read the generator the PR changed and confirm it now produces the required output — that is the code under review and the durable fix.
2. **State the artefact's staleness window in the verdict, explicitly.** Name the committed file, whether it *currently still shows* the defect, and what regenerates it and when (the schedule that bounds the window). A reader opening the repo during that window still sees the old output, so a clean pass must say so rather than imply the committed file is already correct.
3. **Name the cheapest operator action that closes the window sooner** — a one-click workflow dispatch, a manual regenerate — rather than either bouncing (which pushes the builder to hand-edit a file the repo marks do-not-edit, or to ask for credentials the loop lacks) or passing silently (which merges an "this number misleads a reader" fix with the misleading number still committed and nobody told).

Neither extreme is right alone — bouncing for the stale artefact and passing silently both fail, in opposite directions — which is why producer-verify-plus-named-window is the standing shape. Where the AC could bind either the producer or the artefact and the authoring did not say which, that ambiguity is `convention-ticket`'s to close at authoring time (adjacent to the write-a-machine-checkable-criterion thread, APP-555 / APP-579); QA's job meanwhile is to pick the producer, state the window, and name the action. (Worked case: APP-770, bot.Trader PR #15 — every AC phrased about "the report" was met by `renderDispersionMarkdown` and unmet by the committed `data/funding/DISPERSION.md`, which at the PR head still displayed the defect plus a diagnosis a sibling ticket had disproved; passed clean on the producer, flagged the stale file, and gave a one-click dispatch to close the gap before the 22:30 UTC scheduled regen — APP-789.)

## Guardrails

- Does not merge and never merge-approves — **`agent:R3-LAY` as a merge approval, on an In Review ticket, is Aled's action alone**. The one exception is not a merge approval at all: sub-case (a)'s environment-limitation route sets `agent:R3-LAY` on a **Blocked** ticket to hand it to Relay to re-arrange (never to merge from QA). So the rule is precise — QA never sets `agent:R3-LAY` on an *In Review* ticket, which is the merge-approval meaning; it may set it on a *Blocked* ticket, which is the hand-to-Relay meaning. On a clean pass it keeps the state **In Review** and leaves the label `agent:PR-1SM`; on an **unflagged** clean pass it leaves the **assignee clear** as well, because the routing to `R3-LAY` that arms the merge is the driver's *Route per verdict* action and Aled's approval is not the next step (APP-402, APP-1315). It hands to Aled — **assignee → Aled**, label **`human`** (evicts `PR-1SM`) — on a **flagged** clean pass and on an operator-verify-only AC, matching the driver's routing table. It reviews and reports; which party decides next is what the flag determines.
- Merge is never QA's, and what approves it depends on the flag. On **flagged** work approval is Aled's and his `@relay` signal triggers the merge leg; on **unflagged** clean work no separate signal is required — the driver's clean-pass routing to `agent:R3-LAY` is itself the approval (APP-402, decision 2026-06-25; `routine-delivery-loop` *merge leg*). Either way QA neither merges nor arms the merge. Bounce is Aled's: In Review -> Todo with a note re-triggers exec.
- **Verify both sections; never tick on the builder's behalf — but close on your own verification the box exec could not.** Check `## Acceptance criteria` and `## Definition of done` against the type DoD; a blank or unmet box exec should have closed is a changes-needed bounce, not a clean pass, and QA never ticks it on attestation. A box whose truth-maker lands after hand-off is closed by QA on its own check and recorded as QA-closed in the verdict. The carve-out is a **test, not a list**: a blank box QA can verify end-to-end from its own reads, and that no change to the diff would close, is QA-closeable — QA verifies it, closes it, and names the miss in the verdict so the gap still reaches the builder. Both halves of the test bind. A box QA cannot verify end-to-end from its own surfaces stays a changes-needed bounce however clerical it looks, and a box some change to the diff would close is builder debt whatever QA can read. Stated that way it already covers the CI box, Prism's own verdict box and the hand-off-state box — PR link posted on the ticket with a one-line summary, ticket set `agent:PR-1SM`, In Review, unassigned — without a list that needs extending each time another one turns up (APP-1025, APP-1507). The test's scope is **any review-facing checkbox on the ticket or the PR** — a PR body's *Test plan* box ("Theme Check CI green") is judged by the same two halves as a `## Definition of done` box, because the Owner reads both before merging and neither heading makes a box more or less QA's (MBN-309, an Owner-filed ticket — APP-1544).

- **Tick the PR body's copy of any box you tick on the ticket.** The same acceptance/definition-of-done pair sits on two surfaces and nothing re-edits the second, so from hand-off the PR body is permanently stale and every merge leg re-derives staleness-versus-gap. When posting the verdict, patch the PR body's checklist to match the ticket's in the same pass — one body edit — and say in the verdict that both surfaces were brought level. **Lead with the GitHub MCP for that edit: `mcp__github__update_pull_request`, with the full body inline, the same route and the same reason as the draft flip in *Behaviour* above.** The REST form that section names for the verdict comment, `gh api -X PATCH repos/{owner}/{repo}/pulls/{n} -F body=@<path>`, is the obvious choice for a long body and is the **fallback, not the lead**: on the Claude Code auto-mode surface the permission classifier denies it as an external-system write, so no 403 comes back and the self-documenting recovery never fires — a route closed on this surface, not a GitHub error to retry. **And where the classifier permits it, the write is still not trustworthy as written, so two steps are part of taking that route rather than optional care around it.** First, the body file is stripped of any existing generated-by footer before the patch: the patch has been observed appending a second generated-by footer beneath the one the body already carried, so a body that went in with one footer comes back carrying two, and a route that silently doubles a footer every time it is taken makes the PR body less reliable with each edit rather than more. Second, the result is read back and **diffed** against the intended bytes, not merely re-read — a re-read confirms a body is there, which is exactly what is true in the failing case; only a diff against the file that was sent shows the appended footer. The governing rule is already this skill's own, cited in *Read-backs* above for the head SHA: `convention-github`'s "any machine-checkable value a run copies into a review-facing surface is generated and pasted, never retyped, and is verified by diffing against live output rather than by re-reading it" (APP-1159). A PR body assembled from the ticket's checklist is exactly such a value, so the diff is that rule applied where it already reaches rather than a new obligation. Where the diff shows the doubled footer, strip and re-patch once, and say in the verdict that the body was diffed and at which head — a body reported as brought level is trusted by the merge leg the same way a verdict is. What is **unverified** is which layer injects the footer: the proxy, GitHub itself, or the `-F body=@` form's own handling of the file are all consistent with what was seen, and no repo or proxy surface is readable from the refine surface, so none was re-run here. The two steps are written to hold whichever it turns out to be — stripping before the patch and diffing after are correct against an injector at any layer, and neither depends on knowing which (APP-2378). (Worked cases: the APP-2175 QA leg of 2026-10-08 — the REST PATCH denied while the REST *comment* POST and the MCP draft flip both went through in the same run, and the body pasted inline into the MCP worked first time; recurrence the same day on the APP-2187 QA leg, where the MCP carried the draft flip and the body edit in the same minute and the body read back identical to the intended file. Same classifier behaviour as APP-1545, which settled MCP-first for the draft flip — APP-2189. The pull-request numbers, the head SHAs and the identical read-back are the filing legs' reports and are **unverified** here, no repo or GitHub access from the refine surface; the MCP tool's body parameter is also unverified, the GitHub MCP not being attached on this surface. That flag covers those four only — the classifier's denial category is canon's own, in *Behaviour* above.) The ticket stays the gated surface; this only stops the ungated one going stale. Five instances on this root: APP-1025, APP-1520, APP-1760, APP-2068, APP-2125.

- **The pre-strip in *Tick the PR body's copy* answers one direction of the attribution rewrite; the diff answers both.** That bullet's first step — strip any existing generated-by footer from the body file before the patch — is correct against the direction where the route **appends** a second footer beneath the one already there. The same pull-request-body REST PATCH has since been observed **replacing** the mandated footer instead of doubling it, and against that direction a pre-strip makes the stored body worse: the body goes in carrying no mandated footer, the route substitutes its own, and what comes back has the wrong attribution and none of the mandated lines, with nothing absent for a presence check to notice. So pre-strip only where a diff on that route has already shown it appending; otherwise send the body with the mandated footer reading exactly as it should, and rely on the step that holds in every direction — read the stored body back and **diff** its trailing bytes against the file that was sent, then repair through a route that `convention-github`'s *Attribution bytes at the end of an agent-authored body are rewritten in transit* names as storing what was sent, never by patching again through the route that rewrote. That section holds the path list, the direction each route has been seen to mutate in, and the repair routes, so none of them is restated here. (Worked case: the A1-728 QA leg, `assoc-one/meirionpritchard-com` PR #257, head `775db5b`, 2026-10-21 — a pull-request body fetched byte-exact, edited by one checkbox line and sent back through `gh api -X PATCH …/pulls/257 -F body=@file` came back with the session-mandated "🤖 Generated with [Claude Code]" line removed and a different footer appended in its place; `mcp__github__update_pull_request` with the 13,988-byte body inline stored it byte-identical. The pull request number, the head SHA, the byte count and the read-back bytes are the filing leg's report and are **unverified** here, no repo or GitHub surface being readable from the authoring surface, and a flag on one implies nothing about the others — APP-2581.)
- **Assert both headings exist before counting any boxes — a missing section counts zero and passes vacuously.** The rule above walks `## Acceptance criteria` and `## Definition of done`; it assumes both are there. A body carrying only one of them, or neither, satisfies "every box in both sections ticked and genuinely met" with nothing in it: the count is zero, no box is blank, and the verdict reads as a clean pass. The failure is silent and in the costly direction. So the **first** read of the body is structural — both literal headings present, each followed by a checkbox list — and where either is absent that is a changes-needed bounce on the ticket's shape (Pattern A, `convention-ticket`), named as the defect, before any box is assessed. Note which half canon already covers: verifying the DoD boxes against the ticket's `type:` DoD template catches a missing `## Definition of done` the moment the comparison is made, because the template is the external list. Nothing catches a missing `## Acceptance criteria`, because it is per-ticket and there is no template to compare it against — which is why the assertion is stated on the headings rather than left to the template. (APP-2043.)
- **The draft/ready bit means "QA passed", both ways.** A clean pass converts the PR to Ready for Review; a changes-needed verdict leaves it draft and, if it was opened ready (exec opens draft per `skill-build-ticket`), converts it back — so the one signal Aled reads on GitHub never sits ready over a PR carrying blocking defects (APP-822).
- **States the defect and the bar; does not write the fix.** A verbatim, paste-ready patch for the code under review does not belong in a verdict — it borrows reviewer authority without implementer scrutiny and costs QA the independence to review the result. Any snippet that is nonetheless given is held to the same bar QA reviews with, and its provenance is declared on the re-review (A1-242, APP-692).
- **Before asking for an instrument to be extended, confirm it exists in the repo.** A bounce item written as "add X alongside the existing Y" is unactionable where Y lived only in the builder's session, and it reads to the next leg as though the repo already held it. Check, and where the instrument is durable in shape but was never committed, name that as the bar (`skill-build-ticket` step 4) rather than asking for a second disposable copy (A1-397 — APP-1185).
- **Prove provenance before asserting behaviour.** Any service QA stands up to verify against must be proven to be the artefact this run built — port asserted free before start, the real binary spawned and the process group killed, and the harness shown to fail on a known-bad build. An unproven green, QA's own or exec's, is an unverified box, not a pass (A1-242, APP-693).
- **Reproduce the runtime, not just the artefact.** Provenance says which build answered; it says nothing about what it was served inside, what state it read, or what drove it. Check five things before asserting behaviour: the **delivery wrapper** is the publisher's own skeleton and not a hand-rolled one, any store the page reads is **populated** rather than an empty stub, the **input modality** is the one the interface is designed for (a touch-first surface is not verified by mouse events), the **containing box** is derived from the page's own wrapper markup and CSS — or the claim is relative, never absolute per-viewport — and the **loading model** the fixture reproduces is known and named per assertion (script order and `defer`, stylesheet order, custom-element upgrade timing). A green on a fixture that differs from the runtime is worse than no harness — it redirects debugging away from the cause. Where the real runtime cannot be reproduced, name the box unverified rather than reporting the fixture's green (APP-1232).
- **Rebuild after a negative-control batch before measuring anything.** Reverting the source does not rebuild: the build output still holds the last break, `git status` reports clean, and the next probe returns a persuasive false red against working code. Wipe, rebuild, report from the rebuild, and read a builder's replay recipe that ends in a source revert as a trap for the next reader (A1-386 — APP-1197).
- **The harness carries both controls — negative and positive.** Proving the harness can *fail* (a planted-broken build goes red) is only half: also prove it can *pass* — an unmodified baseline stays green in the same batch — so a harness that reds on everything, or a fabricated pass, is caught. Red rows alone are not evidence; a red matrix with a green baseline is. Mind the bytecode cache — `PYTHONDONTWRITEBYTECODE=1`, cleared `__pycache__`, `-p no:cacheprovider` — since a same-byte-length constant edit defeats a `.pyc`-cached check (APP-941).
- **A negative-control count with no replayable recipe is an unverified claim.** Where a PR reports how many checks a deliberate break reddened without the file, the exact anchor and replacement, and the names of the checks that went red (`skill-build-ticket` step 4), either spot-check it or name it unverified in the verdict — never repeat it as fact. The figures have been wrong three times, in three different mechanisms, always in the flattering direction and always cheap for a reviewer to skip (A1-382, A1-384, A1-386 — APP-1194).
- **On a diff that deletes a guard, ask what re-planting the condition would do.** A removed shield, flag or assertion justified only by prose — usually the comment going out with it — is an unevidenced claim, not a cleanup, and every gate in the PR passes it in good faith. Require the re-plant control (`skill-build-ticket` step 4) or name the box unverified in the verdict (A1-387 — APP-1201).
- **Run a negative control in an isolated tree, off shared build state.** A QA negative control — revert to base, add a probe, re-run to prove red — runs in a throwaway or isolated worktree, never the working checkout the exec leg is using, and never against stale build artefacts (a leftover `.next` cache serving the PR's stylesheet against base tokens gives plausible-looking garbage). It is a read, never a resolution — the mirror of `skill-merge-pr`'s abort-the-worktree-merge-when-done rule (APP-970).
- **Prove the baseline, not just the artefact.** An absolute before/after claim rests on a before-state measurement as corruptible as the after-state one. Stay in the one working tree and wipe `rm -rf .next` before *every* measurement in either direction — not as a recovery action (a `git worktree` at base cannot boot on `meirionpritchard-com`; Turbopack rejects the shared-`node_modules` symlink) — give the baseline harness its own negative control, assert an absolute figure only once it passes, and use a DOM discriminator plus a served-asset grep to catch a wrong-tree read. Mind that `pkill -f "next dev"` kills the agent's own shell, so a chained cache-wipe never runs (APP-967).
- **Fetch Linear attachments through the connector, not a raw URL.** Verifying an attachment-backed AC — a canon publish ticket referencing Linear canon attachments, a digest-parity check — fetch the bytes via the Linear connector (`get_attachment`); the sandbox proxy 403s `uploads.linear.app`, so a blocked raw-URL fetch is the wrong route, not an unreachable attachment. Try the connector before declaring an attachment unreachable — one blocked route is not no route (APP-364, APP-972).
- A QA pass is not assurance — it makes the change legible, it does not sign it off. Sign-off is human (Pattern A).
- **An environment limitation is not a human gate; an operator-review-only AC is not a blocker.** An AC QA cannot verify but that a standing runner could (CI, a device, a credential), or that is cheap to add as an automated check, is escalated as a blocker for Relay to re-route, and goes to **Blocked** (carrying `agent:R3-LAY` as the hand-to-Relay signal) — never handed to the operator as a "please run this" chore. An AC only the operator's own eyes or judgement can verify — **including driving an interactive surface (a live Studio / Presentation session, an in-app visual state)** — stays **In Review under `human`**, assigned Aled, aged to Urgent — never Blocked. A bespoke interactive harness *could theoretically* automate the latter, but that theoretical does not make it sub-case (a): reserve (a) for a standing or cheap automated check. The operator only ever receives a true decision or judgement, and only ever via In Review, not Blocked.
- **Bounce only what a change to the diff would close; a precondition outside the repo is a blocker, not a bounce.** An AC affirmatively unmet because a deployment or infrastructure setting outside the repo is absent (a Vercel project variable, a DNS record) is not exec's — nothing in the diff closes it. State the verified code half, name the exact setting, and route it Blocked + `human`+ Aled with the warning that merging before it lands ships the failure — the driver's *Block* row, and the one class where Blocked +`human `is right, because the work must clear before merge and only he can do it. And before classing any hosted-URL criterion unverifiable, verify it locally: a production build of the head driven in the sandbox's Chromium against a stub, with the negative control, meets a runtime criterion; only a box about the hosted deployment itself is the operator's (APP-1113, APP-880).
- **A build-product AC verifies the producer and names the artefact's staleness window.** Where an AC about "the report/output/file" names both a generator the PR changed and a committed build product regenerated on a schedule, verify the producer, state in the verdict whether the committed artefact still shows the defect and what regenerates it when, and name the cheapest operator action to close that window — never bounce for the stale file (hand-editing a do-not-edit product) nor pass silently (merging the misleading output uncorrected). (APP-789.)

## Setup

- Claude Code Desktop -> Schedule -> New remote task.
- Connectors: Linear + GitHub (read + write access to the PR for comments and draft conversion).
- Routine prompt: "Run the qa skill."

On finish, run skill-ops-retro capture on this run's friction: **search the Pulse queue first and add the evidence to a same-root note if one exists, otherwise file a new FRICTION note** for the drain pass to assess, in capture step 3's literal shape — team Apps, project os.Claude, `FRICTION:` title, labels `task` + `work:configuration` + `PUL-5E`, Backlog, unassigned — filing the friction, never the run report.
