From 15b7b4c925f4ba8f3ebea21cb8e8e9581d45d88f Mon Sep 17 00:00:00 2001
From: QA Runner <qa@local>
Date: Mon, 20 Jul 2026 10:46:47 -0700
Subject: [PATCH] docs: testing policy in CONTRIBUTING + PR template with
 verification checklist
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds a Testing section documenting every suite the testing PR series
introduces (unit/integration via vitest, Playwright e2e, offline evals,
gated real-Supabase stack tests), the expectation that changes carry tests
at the lowest layer that catches the regression, and a PR template (ported
from the amal66 fork, Open-Legal-Products/mike#205) whose checklist asks how
the change was verified. Intended as the capstone of the series — the
commands it documents are introduced by the sibling test PRs.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .github/PULL_REQUEST_TEMPLATE.md | 30 ++++++++++++++++++++++++++++++
 CONTRIBUTING.md                  | 19 +++++++++++++++++++
 2 files changed, 49 insertions(+)
 create mode 100644 .github/PULL_REQUEST_TEMPLATE.md

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 0000000..9213ea8
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,30 @@
+## Summary
+
+<!-- What does this PR do, in one or two sentences? -->
+
+## Why / Motivation
+
+<!-- What problem does this solve? Why now, and why this approach?
+     Link the issue or context that prompted it. -->
+
+## Changes
+
+<!-- The notable changes, at a high level. Describe the outcome, not the diff. -->
+
+## Tradeoffs & risks
+
+<!-- What did you weigh? What could break, what's out of scope, and what
+     follow-ups (if any) does this leave behind? Note any security or
+     migration implications. -->
+
+## How verified
+
+<!-- How do you know this works? Tests added/run, manual steps, commands,
+     screenshots. Include the exact commands where relevant. -->
+
+## Checklist
+
+- [ ] Ran the relevant build/test command for the area changed.
+- [ ] Reviewed `git diff` and removed unrelated changes.
+- [ ] Updated docs / env examples if setup, config, or behavior changed.
+- [ ] No secrets, API keys, real documents, or `.env` files committed.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 47e61fe..ba973e4 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -54,3 +54,22 @@ Frontend:
 ```bash
 npm run build --prefix frontend
 ```
+
+## Testing
+
+```bash
+npm test --prefix backend            # backend unit + route integration tests (vitest)
+npm test --prefix frontend           # frontend component/hook tests (vitest + jsdom)
+npm run test:e2e                     # Playwright end-to-end suite — see docs/e2e-ci.md
+node evals/run.mjs --threshold 1.0   # offline eval harness (no network, no API keys)
+npm run test:stack --prefix backend  # gated: real-Supabase auth/access tests (run `supabase start` first)
+```
+
+- New features and bug fixes should come with a test at the lowest layer that
+  can catch the regression: unit first, then route-level integration, then
+  end-to-end only for flows a browser is genuinely needed to prove.
+- CI runs the build, unit/integration tests, and the eval harness on every PR
+  (`.github/workflows/ci.yml`), and the Playwright suite in a full local stack
+  (`.github/workflows/e2e.yml`).
+- Tests that need a live Supabase or an LLM key are env-gated and skip cleanly
+  when the environment is absent — a plain `npm test` should always be green.