Queue-North-Website/docs/qa/ClaudeQAPlan.md

Claude QA Plan — Queue North Website

Status: Current
Owner: _null
Last reviewed: 2026-08-18
Governs: what a QA round consists of
Review trigger: Any new user-facing surface, or a defect class that got through

The playbook. What a round is, so two rounds are comparable and a gap is visible rather than assumed covered.

Before a round

• Build from a clean checkout at a known SHA, and record that SHA.
• Run from a detached worktree if other work is in flight, so uncommitted changes cannot contaminate what is under test.
• Note the environment: device, OS version, browser, screen size — whatever the product's behaviour actually depends on.

The passes

Each pass gets a letter, so ClaudeQACoverage.md can report per pass and a skipped one is visible.

Pass	What it covers
A	First run: install or load, cold start, permissions, empty states
B	The core flow, end to end, as a real user would do it
C	The core flow with things going wrong: no network, denied permission, invalid input
D	Persistence: quit and return, background and resume, restart
E	The end of the loop — the state that is hardest to reach on purpose
F	Accessibility: keyboard only, screen reader labels, contrast, text scaling
G	Performance under the load this product will actually see
H	Abuse, and what a stranger can reach — rewritten for this project, see below

<Add, remove and rename to fit. A pass that never applies is noise; a pass that is always skipped is a lie.>

Why H is separate from B, here

The template's pass H is about authorization: authenticated is not owning, and owning is not permitted. None of that applies to this project — there is no login, no session, no role and no per-user row. Every one of those checks would be a box ticked against nothing.

What does apply is the other half, and it is the most exposed thing here: two unauthenticated POST endpoints that write to a database, on a public origin, behind nothing but a rate limiter and a reCAPTCHA score. Pass B submits those forms as a real visitor would. Pass H is somebody who is not being polite:

• both endpoints called directly, off the form, with hand-made payloads
• the rate limiter driven past RATE_LIMIT_PER_MINUTE, and the 429 body read
• the honeypot field and the reCAPTCHA path bypassed deliberately
• the 1 MB body limit and the 30 s request timeout tripped on purpose
• a duplicate email driven into the 409, to confirm the Zoho forward still fires
• dist/ inspected — VITE_RECAPTCHA_SITE_KEY is inlined into the bundle at build time, which is correct for a site key and catastrophic for a secret one. scripts/secrets.sh --built dist/ is the mechanical half of this

scripts/preflight.sh covers headers and TLS and nothing else. Its --auth checks stay off: there is no login to rate-limit and no account to enumerate.

Pass I — money flowing backwards — is deleted from this plan rather than carried as skipped. No money moves through this site: no checkout, no subscription, no refund path. A pass that never applies is noise, and one that is always skipped is a lie.

Measure it before you file it

Batches 10 and 11 were twenty UI and accessibility issues written from reading source. Seven of ten misstated their own evidence — two contrast figures were wrong, one proposed a colour measuring 1.96:1 against the background it would sit on, one asked for a change that would have spread a Level A failure, one described a clipping ancestor that does not exist, one an overlap that is a 12px gap, one an attribute that is not in the file.

None of that was carelessness about whether something was wrong. It was confidence about how much, without measuring.

So, before filing a UI defect and before acting on one:

node scripts/qa-browser.mjs                       # production, five pages, five widths
node scripts/qa-browser.mjs --url http://localhost:3099 --viewports 320,768

Contrast is arithmetic — composite the colour over its background and compute the ratio, do not judge it by eye. Overlap is two rectangles. "Does it clip" is a computed style you can read off the ancestors. A filed defect's numbers are a claim to check, not a measurement.

What counts as a finding

A finding needs: what was done, what happened, what should have happened, and the build SHA. Without the SHA it cannot be re-tested, and a finding that cannot be re-tested cannot be closed.

Severity

Findings are filed as issues, labelled:

• P0 — ships broken, or loses data
• P1 — materially wrong, but shippable
• P2 — cosmetic or low impact
• release-blocker — a release built today would be wrong rather than merely incomplete

Exactly these label names: the Command Center queries them by name, and a repository that spells them differently has its defects reported as not adopted rather than counted wrongly. This one did, until 2026-08-18 — the labels read P0 Critical, P1 High and P2 Medium, and 205 issues reported as not adopted rather than as 87% complete.

Do not use P3. It exists on 21 closed issues from before the convention and is frozen. It is not one of the four names anything queries, so a defect filed P3 today is counted by nothing.

Severity is what it costs, not how annoying it is to fix.

After a round

File each finding as a labelled issue. Update ClaudeReport.md's run-state block and its overall sentence, and ClaudeQACoverage.md with what each pass actually reached. A pass that could not be run is recorded as blocked, with what blocks it — never quietly left out, which reads identically to "passed".

Then push, and reconcile. The verdict on the project screen at privacyllc.dev is read out of ClaudeReport.md in the pushed repository, so a round whose report is committed but not pushed — or pushed but not reconciled — leaves a stakeholder reading the previous round's judgment with no indication that a newer one exists. The rest of the cycle is in docs/WORK_CYCLE.md.