chore(pr-quality): add proof-backed PR contract

.agents/README.md

@@ -16,6 +16,7 @@ changes — no drift between three half-maintained instruction files.
 | [`project/ARCHITECTURE.md`](project/ARCHITECTURE.md) | …before adding or moving any module. It is the pattern you must follow. |
 | [`project/CONVENTIONS.md`](project/CONVENTIONS.md) | …while writing code — naming, structure, imports, errors, state. |
 | [`project/DEFINITION_OF_DONE.md`](project/DEFINITION_OF_DONE.md) | …before you claim a task is finished. The gates enforce this list. |
+| [`project/PR_QUALITY.md`](project/PR_QUALITY.md) | …before opening, updating, or marking a pull request ready. |
 | [`project/TECH_STACK.md`](project/TECH_STACK.md) | …to know which tool owns which concern (and what *not* to add). |
 | [`project/GLOSSARY.md`](project/GLOSSARY.md) | …when you meet a domain term. Use these words exactly, in code and prose. |
 | [`decisions/`](decisions/) | …to understand *why* a constraint exists before you challenge it. ADRs. |

.agents/project/DEFINITION_OF_DONE.md

@@ -25,6 +25,9 @@ gates" are the same statement. An agent must not report a task complete until
       `.size-limit.json` budget).
 - [ ] **Visuals accounted for.** Any CSS change is either an *intended* change
       approved in the StyleProof report, or a refactor certified as zero-diff.
+- [ ] **PR proof is ready.** The pull request body follows
+      [`PR_QUALITY.md`](PR_QUALITY.md), with exact local commands, visual proof
+      or `N/A` with a reason, CI status, risk, rollback, and no private details.
 - [ ] **Patterns followed.** The change matches
       [`ARCHITECTURE.md`](ARCHITECTURE.md) and [`CONVENTIONS.md`](CONVENTIONS.md);
       new files were created from [`../templates/`](../templates).
@@ -41,3 +44,6 @@ pnpm e2e      # behaviour map
 
 If both are green and the checklist holds, the work is done. If either is red,
 it is not — regardless of how finished the code looks.
+
+Before opening or marking a PR ready, also complete
+[`PR_QUALITY.md`](PR_QUALITY.md) through the GitHub pull request template.

.agents/project/PR_QUALITY.md

@@ -0,0 +1,54 @@
+# PR Quality Contract
+
+A pull request is ready for review only when it explains the change and proves
+the change. The proof must be specific enough that a reviewer can separate:
+
+- what passed locally;
+- what GitHub Actions proved on the latest commit;
+- what was verified in a browser or deployed runtime;
+- what remains unverified.
+
+Do not collapse those into one vague "all good" statement.
+
+## Required proof
+
+Every PR body must include:
+
+- **Why:** the problem, risk, or capability the change exists to address.
+- **What changed:** the smallest reviewable summary of the diff.
+- **Local verification:** exact commands run, with pass/fail status.
+- **Visual proof:** screenshots, video, StyleProof report, or `N/A` with a
+  reason. Any UI-visible or CSS change needs visual proof.
+- **CI status:** whether checks are green for the latest commit, still pending,
+  or failing with the failure named.
+- **Risk and rollback:** the likely blast radius and how to back out.
+- **Definition of Done:** the checklist in
+  [`DEFINITION_OF_DONE.md`](DEFINITION_OF_DONE.md) is satisfied or each gap is
+  explicitly named.
+
+## Ready means reviewable
+
+Open a ready PR when the work is reviewable and the body has proof. Do not open
+placeholder PRs with missing verification and then call the work done. If a PR
+must be opened before CI finishes, say exactly which checks are pending and do
+not report completion until the latest-sha checks are green.
+
+## Evidence rules
+
+- Use command names, not summaries: `pnpm verify` is useful; "tests passed" is
+  not.
+- For UI-visible work, include screenshots, video, or the StyleProof report. For
+  docs-only or config-only work, write `N/A` and point to deterministic proof
+  such as lint, build, or workflow validation.
+- If a command fails, keep the failure visible and fix the cause. Never use
+  `--no-verify`, weaken a gate, or remove a check to make the PR green.
+- If proof depends on a deploy or external service, verify that runtime directly
+  before claiming it works there.
+- Keep private project details, secrets, tokens, customer names, and local-only
+  paths out of public PR bodies.
+
+## PR body source
+
+Use [`.github/pull_request_template.md`](../../.github/pull_request_template.md)
+for every pull request. The template is the review-facing version of this
+contract; this document explains the standard behind it.

.claude/skills/pr-quality-contract/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: pr-quality-contract
+description: >-
+  Use before opening, updating, or marking a pull request ready. It turns the
+  repo Definition of Done into a proof-backed PR body with exact local checks,
+  visual evidence, CI status, and explicit unverified gaps.
+---
+
+# PR Quality Contract
+
+Use this skill any time you prepare a PR, update a PR body, respond to review
+asking for proof, or decide whether work is ready to report complete.
+
+## Read First
+
+- `.agents/project/DEFINITION_OF_DONE.md`
+- `.agents/project/PR_QUALITY.md`
+- `.github/pull_request_template.md`
+- `git status --short --branch`
+- the current diff against the intended base branch
+
+## Process
+
+1. **Confirm scope.** Identify the intended base branch, current branch, and
+   changed files. Do not include unrelated local changes in the PR.
+2. **Run local proof.** Prefer `pnpm verify` and `pnpm e2e`. If a narrower
+   command is appropriate, name why it is enough and list what remains unproven.
+3. **Collect visual proof.** For UI-visible or CSS changes, attach screenshots,
+   video, or a StyleProof report. For non-UI changes, write `N/A` with the
+   reason instead of pretending visual proof exists.
+4. **Separate proof layers.** Keep local command proof, GitHub Actions status,
+   deploy/runtime proof, and pending gaps in separate sentences.
+5. **Fill the template.** Use `.github/pull_request_template.md`; do not leave
+   placeholder comments, empty checkboxes with no explanation, or vague
+   summaries such as "all tests pass".
+6. **Gate completion.** Do not report the work complete until the latest-sha CI
+   checks are green, or until you have clearly said which checks are still
+   pending or failing.
+
+## Failure Rules
+
+- If a gate fails, report the exact command and failure, then fix the cause.
+- Never use `--no-verify`, remove a hook, weaken TypeScript/Biome/Jest config,
+  or lower a budget to get a green PR.
+- Keep private project names, secrets, tokens, and local-only paths out of a
+  public PR body.
+
+## Ready Output
+
+When handing off the PR, include:
+
+- PR URL and branch;
+- one-sentence change summary;
+- exact local commands run;
+- latest GitHub Actions status;
+- visual proof link or explicit `N/A`;
+- any residual risk or unverified surface.

.claude/skills/pr-quality-contract/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "PR Quality Contract"
+  short_description: "Prepare proof-backed PRs with local checks, visual evidence, CI status, and explicit gaps."

.github/pull_request_template.md

@@ -0,0 +1,34 @@
+## Why
+
+<!-- What problem, risk, or capability does this PR address? -->
+
+## What Changed
+
+<!-- Keep this to the smallest reviewable summary of the diff. -->
+
+## Proof
+
+- [ ] `pnpm verify`
+- [ ] `pnpm e2e`
+- [ ] Visual proof attached or linked, or `N/A` with reason:
+- [ ] StyleProof reviewed, or `N/A` with reason:
+- [ ] Other proof:
+
+## CI Status
+
+- [ ] Latest-sha GitHub Actions are green.
+- [ ] Pending checks are named below.
+- [ ] Failing checks are named below with the fix plan.
+
+## Risk And Rollback
+
+<!-- What could break, and how would this be backed out? -->
+
+## Definition Of Done
+
+- [ ] Behaviour is covered by the E2E map when user-visible behaviour changed.
+- [ ] Logic is unit-tested where logic changed.
+- [ ] Accessibility was considered and verified for interactive/UI changes.
+- [ ] The diff follows `.agents/project/ARCHITECTURE.md` and `CONVENTIONS.md`.
+- [ ] Any new architectural decision is recorded as an ADR.
+- [ ] No gates were bypassed or weakened.

AGENTS.md

@@ -36,7 +36,9 @@ pnpm e2e              # the end-to-end behaviour map
 6. **Done means the gates are green.** Do not report a task complete until
    `pnpm verify` and `pnpm e2e` pass — see
    `.agents/project/DEFINITION_OF_DONE.md`.
-7. **Change rules in the open.** If a constraint is wrong, propose an ADR in
+7. **PRs need proof.** Before opening or marking a PR ready, complete the
+   pull request template and follow `.agents/project/PR_QUALITY.md`.
+8. **Change rules in the open.** If a constraint is wrong, propose an ADR in
    `.agents/decisions/`; don't quietly diverge.
 
 ## Where to look
@@ -46,6 +48,7 @@ pnpm e2e              # the end-to-end behaviour map
 | The pattern to follow | `.agents/project/ARCHITECTURE.md` |
 | Naming, imports, errors | `.agents/project/CONVENTIONS.md` |
 | When am I done? | `.agents/project/DEFINITION_OF_DONE.md` |
+| What proof does a PR need? | `.agents/project/PR_QUALITY.md` |
 | Which tool owns what | `.agents/project/TECH_STACK.md` |
 | Domain language | `.agents/project/GLOSSARY.md` |
 | Why a rule exists | `.agents/decisions/` (ADRs) |

CLAUDE.md

@@ -21,6 +21,8 @@ This repo commits its own skills under `.claude/skills/`:
 
 - **`run-e2e-tests`** — map a behaviour to a Playwright test and run it.
 - **`write-unit-tests`** — Jest + React Testing Library, behaviour-first.
+- **`pr-quality-contract`** — prepare proof-backed PRs with local checks,
+  visual evidence, latest-sha CI status, risk, and explicit gaps.
 
 Install the external skill libraries once with `pnpm setup:agents`:
 
@@ -44,4 +46,5 @@ fails, fix the cause.
    `.agents/templates/`.
 3. Run `pnpm verify` and `pnpm e2e` until green.
 4. Commit with a Conventional Commit message.
-5. For a health-check of the whole repo, run the ArchitectPlaybook audits.
+5. Use `pr-quality-contract` before opening or marking the PR ready.
+6. For a health-check of the whole repo, run the ArchitectPlaybook audits.

README.md

@@ -43,6 +43,7 @@ to do:
   [architecture pattern](.agents/project/ARCHITECTURE.md) agents must follow, the
   [conventions](.agents/project/CONVENTIONS.md) for naming, imports, errors, and
   state, the [Definition of Done](.agents/project/DEFINITION_OF_DONE.md), the
+  [PR quality contract](.agents/project/PR_QUALITY.md), the
   [tech stack](.agents/project/TECH_STACK.md) and what not to add to it, the
   [glossary](.agents/project/GLOSSARY.md), the [decision records](.agents/decisions)
   that explain why each rule exists, and [templates](.agents/templates) to copy
@@ -69,6 +70,12 @@ same checks, so "works on my machine" and "passes CI" mean the same thing.
 honestly report a task finished until `pnpm verify` and `pnpm e2e` pass, no
 matter who or what wrote the code.
 
+PRs then carry that proof into review. The
+[PR quality contract](.agents/project/PR_QUALITY.md) and
+[pull request template](.github/pull_request_template.md) require exact local
+commands, visual proof or an explicit `N/A`, latest-sha CI status, risk, and
+rollback. A reviewer should never have to guess what was actually verified.
+
 The catch is that your context files and your codebase have to speak the same
 language. If the foundations hold three different patterns while `AGENTS.md`
 defines one, the agent struggles to remember which it is meant to follow, and the
@@ -209,6 +216,7 @@ AGENTS.md / CLAUDE.md     Agent contract. Thin entry points into .agents/.
   project/ARCHITECTURE.md   The pattern agents must follow.
   project/CONVENTIONS.md    Naming, imports, errors, state.
   project/DEFINITION_OF_DONE.md  "Done" means these gates are green.
+  project/PR_QUALITY.md     Proof required before a PR is ready.
   project/TECH_STACK.md     One tool per concern, and what not to add.
   project/GLOSSARY.md       Shared language (pairs with graphify).
   decisions/                Decision records: why each constraint exists.
@@ -217,8 +225,10 @@ AGENTS.md / CLAUDE.md     Agent contract. Thin entry points into .agents/.
   settings.json             Permission allowlist and PreToolUse hook.
   hooks/block-gate-bypass.sh  Refuses --no-verify. Gates are not optional.
   skills/                   This repo's own packaged processes.
+    pr-quality-contract/    PR proof, CI status, risk, and handoff workflow.
 .husky/                     pre-commit, commit-msg, pre-push gates.
 .github/
+  pull_request_template.md  Proof-backed PR handoff template.
   dependabot.yml            Weekly npm and GitHub Actions updates.
   workflows/
     ci.yml                  Quality, tests, build and size, e2e, security.