qa

/qa — see the real running product

Critical

• /implement REQUIRES this, and will not close without it. /implement phase-4.8 runs scripts/qa-targets.ts over its diff. Every web target it prints gets a full /qa — impeccable on @latest (step-2.6), its fixes (step-2.7), screenshots, sight-check, fresh-context visual review — and validate.ts --require-qa then refuses the close until each one has a marker for the tree that is about to ship. "Fully" is not a posture here, it is the gate's definition: a /qa that stopped after impeccable writes no marker, and the session does not close. scripts/mark-qa-done.ts --tree <sha> writes that marker, only at step-6-teardown, only after the review passed — never by hand, and never early.
• The automatic trigger is /implement, not a hook. Phase 4.8 runs validate.ts --phase qa-list and --require-qa, so a session that changed a web app cannot close without a finished /qa. Invoking /qa by hand is the manual override.
• Tools install on first use; a missing tool is a skip, never a pass. Playwright and Chromium (ensure-playwright.ts), impeccable (impeccable-detect.ts, which also upgrades it when a newer version is published) and the axe packages for --a11y install the first time they are needed — nothing at install time. When one cannot be installed (offline, no npm, QA_NO_INSTALL=1), the script prints qa: skipped — Playwright unavailable (<reason>) or impeccable: detector unavailable — <reason>; repeat that line to the user word for word and write no marker. The sight stamp uses ImageMagick (magick) when installed and Playwright otherwise, so it needs nothing extra. Node 22.18+ is assumed (every script here is TypeScript that Node runs directly).
• A design authority that contains no design is a P1, not a pass. /qa delegates the entire look question to the app's own DESIGN.md — correct — but a delegated file can hold no design. gen-design-md.ts writes a token inventory on a repo's first run, the design-system-* checks run against it, and the result is clean forever; that is how a portal passes /qa while its owner finds it plainly bad. design-authority.ts (step-2.5) now raises the missing system as the run's first finding, and system-drift.ts (step-2.6b) counts how far the source has drifted from whatever the app DID declare. Neither adds a design opinion to this skill: the rubric still prescribes no type ramp, palette or spacing scale.
• Evidence, not assertion. The deliverable is the manifest (page x viewport -> path, bytes, http-status) + the fresh-context findings, NOT "looks good." Give the agent a runnable check, and show the evidence.
• The builder does not grade itself. step-4-fresh-review dispatches a fresh-context subagent (in Claude Code, the Task tool; elsewhere, the harness's subagent or a new session) that Reads the PNGs and checks geometry — never inline-QA in this orchestrator. Hot-context self-review produces motivated reasoning.
• Zero-config — no .qa.json. Routes come from whichever file-based routing dirs the repo actually has — src/pages/, pages/, app/, src/app/ (discover-routes.ts); the live URL from --live-url, or the Cloudflare Pages registry when wrangler's credentials are set. DESIGN.md is the only per-repo file the QA process involves, and /qa commits it itself (step-2.5-design-md).
• Never guess a serve command. Node-server / CLI / render targets REQUIRE a qa:* script in the repo's own package.json (qa:serve / qa:cmd / qa:render). Only Astro / Vite / static get a convention default.
• Own your processes. Teardown signals only the process group serve.ts started + removes only the worktree it created. Never global-pkill workerd/wrangler — that kills other repos' servers on the same machine. Ownership is proved at STARTUP too: the health check refuses a listener that is not in the process group this run spawned (unless no listener pid can be read at all and the port was verified free the instant before spawning — a pid that resolves to another group is refused even then, because another session can take the port in that gap). Answering on a port is not evidence of owning it — a stale server from another repo answers 200 all day.
• CLI/Node Playwright only — npx playwright or an inline Node script importing the playwright package. No Playwright MCP server; the Node API is what screenshot.ts is built on.