agent-quality-skills 1.0.0

package/skills/quality-gate/SKILL.md

@@ -0,0 +1,275 @@
+---
+name: quality-gate
+description: Pre-ship review gate for a codebase — run it before committing, merging, opening a PR, or releasing. Runs the repo's own lint/typecheck/test/build scripts and reports their real output, audits the diff against the project's written standards, checks the diff against the spec or ticket it came from (missing / scope creep / implemented-but-wrong), applies only mechanically-safe fixes, and returns Blocking / Major / Minor findings plus a separate no-severity Needs-validation list, ending in an Approve / Approve with Comments / Request Changes / Reject verdict. Use when someone says a module, endpoint, service, component, migration, or page is done and asks "is this ready to merge / production-ready", "review this", "does it follow our standards", "does this match the spec", or wants a security review of auth, validation, or data-access code — even without the words "skill" or "standards". Do NOT use it to write features, explain how code works, or scaffold specs.
+---
+
+# Quality Gate
+
+A review that a strict human reviewer would sign, produced the same way every time.
+
+The bar is **"would a careful reviewer approve this for production?"**, not "does it
+run". When in doubt the verdict is **Request Changes** — a flagged non-issue costs a
+second look; a missed Blocking costs an incident.
+
+## What this is not
+
+- **Not a linter.** Linters are step 3 of 6, and they are the cheap part.
+- **Not an author.** It reviews and applies mechanically-safe fixes. It does not
+  design features, rename things, or refactor.
+- **Not a substitute for a security audit.** See `references/evidence-contract.md`
+  for where that line sits and what to do at it.
+
+---
+
+## Step 1 — Resolve the standards
+
+Standards are the source of truth and they belong to the project, not to this skill.
+Read the project's own docs when they exist; fall back to the bundled checklists when
+they do not.
+
+1. Look for project standards. Try, in order, and stop at the first that exists:
+   `docs/standards/`, `docs/requirements/standards/`, `standards/`, `.standards/`,
+   `CONTRIBUTING.md`. Search upward from the working directory — in a multi-repo
+   workspace the standards often live one level above the repo. Use glob/ls; do not
+   assume a path.
+2. If found, skim the documents relevant to the files in the diff. **They override
+   anything bundled here when they conflict.**
+3. If not found, use `references/` below. They are a faithful, general version of the
+   same rules and are enough to run a full review.
+
+| bundled file | read it when the diff includes… |
+|---|---|
+| `references/backend-checklist.md` | server code: controllers, services, repositories, DTOs, entities, migrations, workers, queues |
+| `references/frontend-checklist.md` | UI: components, pages, loaders, forms, client-side state, rendering of user input |
+| `references/security-checklist.md` | auth, authorization, input handling, uploads, logging, secrets, outbound URLs — **almost always** |
+| `references/evidence-contract.md` | **every run that is about to write a security finding.** What it takes for a claim to count |
+| `references/gates-and-fixes.md` | **every run** — how to find and run the repo's real gates, and the exact safe-fix policy |
+| `references/go-live-checklist.md` | only when asked for a release / production-readiness review, not a per-change one |
+
+> **Project config.** If the project has a `QUALITY-GATE.md` (see `templates/`), read
+> it first: it names the lanes, the protected branches, the queue file, and any
+> project-specific traps. It is optional; the skill works without one.
+
+---
+
+## Step 2 — Determine scope
+
+- If the user named a file, folder, or module, review that.
+- Else, in a git repo, review the **diff**: uncommitted changes, plus the branch
+  against its base (`main`/`master`/`develop`, whichever exists).
+- If the tree is clean and there is no branch delta, review the last commit.
+- If there is no git and no path, ask which file or folder to review.
+
+Review what changed **plus what it affects** — a changed DTO touches its controller,
+its service, and any published API contract. Skip generated and vendored files.
+
+**State the scope in one line at the top of the report**, so the reader knows exactly
+what was and was not covered.
+
+### Pin what the change was SUPPOSED to be
+
+Everything else asks *is this code good?* This asks *is it the thing that was asked
+for?* — and good code can fail it. Find the originating spec, in this order:
+
+1. A path or spec the user named.
+2. The project's spec directory, if it has one (`docs/specs/`, `docs/superpowers/specs/`, `spec/`).
+3. An issue referenced in the commit messages (`#123`, `Closes #45`).
+4. The open PR body.
+5. The project's backlog or queue file, if it has one — an item there is a spec of sorts.
+
+If none exists, write **"no spec available"** in the report and skip the Spec axis.
+Do not invent one from the diff and then check the diff against it: that always
+passes and proves nothing.
+
+> This axis exists because the author and the reviewer are usually the same context,
+> and a spec written an hour earlier stops being read. The characteristic failure is
+> code that looks entirely correct on its own and is only wrong **next to the spec**.
+
+---
+
+## Step 3 — Run the repo's real gates
+
+Machines catch mechanical problems faster than reading does. Run them first so your
+reading time goes to judgment.
+
+1. **Read the manifest and run the scripts that exist** — `package.json`,
+   `Makefile`, `pyproject.toml`, `Cargo.toml`, whatever the project uses. Typically
+   some of: lint, typecheck, test, build.
+2. **Capture the actual output.** Report real pass/fail counts and the first real
+   errors. Never a guess.
+3. If a script does not exist, say so (`no "lint" script found`) and move on. Absence
+   is not failure, and it is not a pass either.
+
+Three traps that have each produced a false green, all covered in
+`references/gates-and-fixes.md`:
+
+- **Never pipe a gate and read `$?`** — `cmd | tail` returns `tail`'s status, not the
+  gate's. Redirect to a file and read the tool's own exit code.
+- **Run the gates that exist, not the ones you remember.** List the manifest's scripts
+  and run each that is a gate. A suite you never ran is not a suite that passed.
+- **An npm script is not always what CI runs.** If CI invokes a binary with flags the
+  script omits, the script can exit 0 while CI fails. Compare them.
+
+Record each result for the Gates table.
+
+---
+
+## Step 4 — Audit against the standards
+
+Read each file in scope, route it to the matching checklist, and evaluate along these
+dimensions:
+
+- **Correctness** — requirements met, edge cases, null/undefined, failure paths.
+- **Security** — see the evidence contract below before writing anything here.
+- **Architecture** — layer boundaries respected; thin controllers; logic in services;
+  persistence-only repositories; external calls where the project puts them.
+- **API contract** — naming, versioning, consistent envelope, pagination on
+  collections, documented; no breaking change without a version.
+- **Data** — keys, audit fields, soft delete, naming, foreign keys and indexes,
+  reversible migrations, no auto-sync in production.
+- **Maintainability** — clear names, small functions, shallow nesting, no magic
+  values, no dead or clever code, strict types, no escape hatches.
+- **Testing** — changed logic comes with tests; critical flows covered; no
+  sleep-based or order-dependent tests.
+- **Performance, caching and limits** — ask the four **together** for every endpoint
+  the diff touches, not only the one the ticket named: **bounded** · **cached where
+  the project's policy says so** · **authorized on every door that reaches the same
+  write** · **rate limited where it is public**. "It was already unbounded" is not a
+  defence once the diff touches that line.
+- **Spec fidelity** — only when Step 2 found a spec. Quote the spec line for each
+  finding: **Missing** (asked for, absent or half-done) · **Scope creep** (behaviour
+  nobody asked for — extra surface others may build on) · **Implemented but wrong**
+  (present, not what the spec described — the one that hides, because the code reads
+  fine on its own). A deviation is not automatically Blocking: judge it on
+  consequence, and if the **spec** turned out wrong, say that instead.
+
+### Before you write a security finding
+
+**Read `references/evidence-contract.md`.** It is short, and it decides whether what
+you are about to write is a finding at all. Three rules:
+
+1. **Name a boundary AND a result.** Six rows: lower-trust principal · accepted input
+   or action · intended control · crossed boundary · affected principal or resource ·
+   observed or owner-observable result. A missing best practice with no principal and
+   no crossed boundary is a hardening note, not a security finding.
+   ⚠️ **The six rows are the bar for CONFIRMING. To REJECT, one line is enough — name
+   the lower-trust principal and what they gain; if you cannot, stop there.** Spending
+   the whole table to say something is not a finding is ceremony.
+2. **`needs-validation` is a state, and it carries no severity.** When the decisive
+   fact is outside the repository — a proxy header, an IAM policy, a provider default,
+   live configuration — say so with the exact missing fact and a safe way to check it.
+   Do not guess presence *or* absence.
+3. **Severity cannot exceed demonstrated impact.** Use the anchors in the contract.
+   If you cannot state the concrete damage, it is lower than it feels.
+
+### Classify every finding
+
+- **🔴 Blocking** — must fix before merge. Confirmed security gap, missing
+  authorization, data-corruption risk, undocumented breaking change, critical bug,
+  architecture violation.
+- **🟠 Major** — should fix before release. Missing tests for changed logic, missing
+  validation, N+1 or unbounded query, incomplete error handling.
+- **🟡 Minor** — optional. Naming, readability, small refactors.
+- **🔍 Needs validation** — no severity. A source-grounded question blocked on a fact
+  outside the repo.
+
+If unsure between Blocking and Major, say so in the finding and lean stricter.
+
+---
+
+## Step 5 — Apply safe fixes only
+
+A fix is safe only if a formatter or linter would make it and it **cannot change
+runtime behaviour or a public contract**.
+
+**Apply, then list:** formatter output; linter autofix for import order, unused
+imports, const-over-let, quote and semicolon style, trailing commas.
+
+**Report, never apply:** anything touching logic or control flow; replacing loose
+types with real ones; adding or changing validation; renaming public symbols,
+endpoints, fields or enum values; security fixes; architecture moves; schema and
+migration changes.
+
+Re-run the affected gate after fixing so the report reflects the fixed state. Full
+policy: `references/gates-and-fixes.md`.
+
+---
+
+## Step 6 — Emit the verdict
+
+Always produce exactly this structure:
+
+```
+# Quality Gate — <scope, e.g. "feature/x vs develop · 6 files">
+
+## Summary
+<1–3 sentences: what was reviewed and overall health>
+
+## Gates
+| Gate      | Result                                            |
+|-----------|---------------------------------------------------|
+| Lint      | ✅ pass (3 auto-fixed) / ❌ 5 errors / ⏭ no script  |
+| Typecheck | ✅ pass / ❌ 2 errors                              |
+| Tests     | ✅ 42/42 / ❌ 2 failed / ⏭ none                    |
+| Build     | ✅ pass / ❌ fail / ⏭ skipped                      |
+
+## Spec fidelity — <spec path or issue, or "no spec available">
+- **Missing** — <what the spec asked for and the diff does not do>, spec: "<quoted line>"
+- **Scope creep** — <behaviour nobody asked for>
+- **Implemented but wrong** — <present but not as described>, spec: "<quoted line>"
+<or> Matches the spec. <or> No spec available — axis skipped.
+
+## 🔴 Blocking  (must fix before merge)
+- `path/file.ts:24` — <defect> — violates <standard>. <smallest effective fix>.
+<or> None.
+
+## 🟠 Major  (should fix before release)
+<or> None.
+
+## 🟡 Minor  (optional)
+<or> None.
+
+## 🔍 Needs validation  (no severity — the decisive fact is outside the repo)
+- `path/file.ts:NN` — <source-grounded hypothesis>, blocked on <exact missing fact>.
+  Check by: <safe owner-observable or local step>.
+<omit this section when empty — EXCEPT on a diff touching infrastructure, configuration
+or deployment, where it is mandatory even as "None.". A heading that is always empty
+trains readers to skip it.>
+
+## Auto-fixes applied
+<or> None.
+
+## Verdict
+**Request Changes** — <short justification tied to the findings above>
+```
+
+The verdict is one of **Approve**, **Approve with Comments**, **Request Changes**,
+**Reject**.
+
+Do **not** Approve if any of these hold:
+
+- A Blocking issue exists.
+- A **confirmed** security concern exists. A `Needs validation` entry does not block
+  on its own — it is a question, not a defect. Say plainly in the verdict that it is
+  open, and never promote it to Blocking "to be safe": doing that is what makes a
+  security list unreadable, because nobody can then tell measured from suspected.
+- A breaking API or schema change is present without versioning and documentation.
+- A critical test is failing.
+- An architecture standard is violated.
+- The diff departs from its spec and the departure is neither called out nor agreed.
+  A silent departure is not a style question: whoever reads the spec next will believe
+  something that is not true of the code.
+
+Reserve **Reject** for a fundamentally wrong approach.
+
+---
+
+## Notes
+
+- Be specific and kind. Findings are about the code's production-readiness, not the
+  author.
+- Do not pad. "None." in a tier is a good outcome — say it plainly.
+- **Never claim a gate passed without running it, and never invent a finding to look
+  thorough.** Every finding cites a file:line and the standard it violates.
+- **Review is a separate pass from writing.** If you wrote the code, you are not the
+  one to approve it — and that includes the fix for a review finding.

package/skills/quality-gate/references/backend-checklist.md

@@ -0,0 +1,116 @@
+# Backend checklist
+
+Server-side code: controllers/handlers, services, repositories, DTOs and schemas,
+entities, migrations, workers and queues. Stack-neutral — the project's own standards
+win where they differ.
+
+---
+
+## Layering
+
+- **Handlers stay thin**: parse, authorize, delegate, shape the response. No business
+  rules, no data access, no outbound integration calls in the request path.
+- **Services own the rules**, and own the transaction boundary.
+- **Repositories persist**, and do nothing else.
+- Outbound integrations go where the project puts them — a queue, a worker, an outbox.
+  A synchronous third-party call inside a request is an availability coupling; if the
+  project has a pattern for this, not using it is an architecture violation.
+
+## Routing
+
+- **A literal path loses to a parameterised one unless it is registered first.**
+  `/things/active` behind `/things/:id` is silently handled by `:id` — and the symptom
+  is a type error deep in the handler, not a 404. Declare literals above parameters,
+  and register a literal-path controller before the one owning the parent path.
+- After adding a sub-path under an existing `:id` route, **call it once**. A route with
+  no caller is not a route that works.
+
+## API contract
+
+- Consistent naming and versioning; one success and one error envelope across the API.
+- **Collections are paginated**, and the response reports the true total so nothing is
+  truncated silently.
+- Every response shape documented. If the contract is published, a consumer builds from
+  the document, not from the behaviour — **a documented field that is not sent, or a
+  sent field that is not documented, is a defect in the contract**, and the cost lands
+  on someone else's week.
+- No breaking change without a version: removing a field, making a documented field
+  optional or nullable, narrowing a type, or removing an undeprecated path.
+- **Additive is the escape hatch.** A new field or a new endpoint is almost always
+  allowed where a change to an existing one is not.
+
+## Data and migrations
+
+- Stable primary keys; audit columns; soft delete where the project uses it; consistent
+  naming; foreign keys with the indexes to match.
+- Migrations are reversible and ordered. No schema auto-sync outside development.
+- **Moving a column moves its indexes.** A unique index defined on the old table
+  disappears quietly when the column is recreated elsewhere — check the index list, not
+  the column list.
+- **Appending to a column with a CHECK constraint** can make an existing row
+  unrepresentable. Read the constraint before widening a value.
+- A uniqueness rule that depends on the current time cannot live in a partial index.
+- **`INSERT … WHERE NOT EXISTS` is not a lock.** Under read-committed two concurrent
+  transactions both pass it. Use an advisory lock or a real constraint.
+- An upsert that emits an unconditional update will clobber a concurrent writer — make
+  the update conditional when that matters.
+
+## Money, time and identity
+
+- **Money is an integer in the smallest unit**, or a decimal type — never a float.
+  Sum it in the database, narrow it only at the boundary.
+- **Timezone is a decision, not a default.** If the product's day boundary is not UTC,
+  extracting a date part from a timestamp in the server's session timezone is wrong.
+  Put the rule in one named helper.
+- Identifiers that a person will be shown are never reissued after a race is lost.
+
+## Performance, caching and limits
+
+Ask the four **together** for every endpoint the diff touches, not only the one the
+ticket named:
+
+| | |
+|---|---|
+| **fast** | bounded query · no N+1 · indexed predicate · no `SELECT *` |
+| **cached** | apply the project's policy for this data class rather than inventing one; bust on our own write; include any database or tenant discriminator **in the cache key** |
+| **authorized** | the rule holds on every door reaching the same write |
+| **limited** | public routes have a rate limit; outbound calls respect the partner's |
+
+- **A consumer asking for the convenient shape is not a reason to drop a bound.** Give
+  them what their screen needs *and* a ceiling, report the true total so nothing is cut
+  silently, and say what the ceiling is.
+- No per-row lookup inside a loop on a paginated endpoint.
+- Check the query count on any list or dashboard route — those are the hot ones.
+
+## Caching hazards
+
+- **One cache instance shared across environments needs the environment in the key**,
+  or a value from a dropped database is served to a live one.
+- **Bump a version segment in the key when a value's shape changes**, or a stale entry
+  deserialises into a shape the code no longer handles.
+- A cache-aside helper with single-flight must not be re-entered on its own key by its
+  own factory: it hands the factory the promise it is producing and the request never
+  settles.
+
+## Errors
+
+- Fail closed. A degraded dependency should make the answer slower or narrower, never
+  more permissive.
+- Distinguish "the store is unavailable" (often survivable) from "the rule says no"
+  (never survivable).
+
+## Testing
+
+- Changed business logic ships with a test. Missing is Major — Blocking for auth,
+  money, permissions, and anything on a published contract.
+- **Unit specs are where a new dependency surfaces.** A hand-built collaborator in a
+  unit spec is the only written record of that class's dependency shape; an
+  integration test wires the real thing and stays green.
+- **Shared-database suites must seed what they assert on**, and purge it. A suite that
+  reads another suite's leftovers passes locally and fails on a fresh database.
+- **An assertion that loops over a list passes on an empty list.** Put a length
+  assertion ahead of every such loop — without it the test cannot fail, which is the
+  one thing a security test must be able to do.
+- Fixtures must be unique **by construction**, not by luck. A derived random value with
+  a small space collides eventually, and the failure surfaces inside a helper where it
+  reads as a bug in the code under test.

package/skills/quality-gate/references/evidence-contract.md

@@ -0,0 +1,164 @@
+# Evidence contract for security findings
+
+A checklist answers *does the code do X?* This file answers the other half: **what it
+takes for a claim about X to count.**
+
+It exists because the expensive failure in review is rarely a missed check. It is a
+claim that says more than it measured — a suspicion written in the same ink as a
+proven defect, so that a week later nobody can tell them apart, and the real one is
+buried in the pile.
+
+The three rules are adapted from Cloudflare's `security-audit` skill
+(MIT, <https://github.com/cloudflare/security-audit-skill>), which is the companion to
+this gate. See "Where this gate stops" at the bottom.
+
+---
+
+## Rule 1 — A finding needs a boundary AND a result
+
+Fill in all six, or it is not a security finding:
+
+| | |
+|---|---|
+| **lower-trust principal** | who is doing this — an anonymous caller, a basic user, a suspended account, another tenant's admin |
+| **accepted input or action** | what they send or do |
+| **intended control** | the guard or rule that is supposed to stop it |
+| **crossed boundary** | which line that control was drawing |
+| **affected principal or resource** | whose data or capability moves |
+| **observed or owner-observable result** | what actually happens — not what could |
+
+### The six rows are the bar for CONFIRMING — rejecting takes one line
+
+**To reject a candidate, ask one question: name the lower-trust principal and
+what they gain.** If you cannot, it is a hardening note. Stop there.
+
+The table is what a **confirmed** finding must carry, and that is where it earns
+its cost — somebody is going to act on the answer. Filling six rows in order to
+throw a candidate away is heavier than the throwing-away deserves, and a rule
+that costs more than it returns is one people quietly stop using.
+
+### What this excludes, on purpose
+
+- **A missing best practice with no principal and no crossed boundary.** "Tokens are
+  kept in `localStorage`" names nobody and crosses nothing on its own. It becomes a
+  finding when you can say who reads them and what they then reach. Until then it is
+  a hardening note, and filing it as a security finding makes the real ones harder to
+  see.
+- **Guessed deployment behaviour.** A proxy, provider default, browser policy or IAM
+  rule that is not in the repository is not evidence in either direction. That is what
+  Rule 2 is for.
+- **A generic crash with no security outcome.**
+- **Self-impact.** A caller degrading only their own session has not crossed a
+  boundary.
+
+---
+
+## Rule 2 — `needs-validation` is a STATE, and it carries no severity
+
+Three states, and keeping them apart is the whole point:
+
+| state | means |
+|---|---|
+| **confirmed** | the six rows above are filled in from source, or from a bounded local run |
+| **needs-validation** | a specific, source-grounded hypothesis whose **decisive fact is outside** what the repository can show |
+| **rejected** | traced, and the boundary holds |
+
+🔴 **`needs-validation` is not "a confirmed finding I am less sure about".** It gets
+**no severity at all** — not a lower one. A severity on an unverified item is how a
+list of *things to go and check* silently becomes a list of *holes*.
+
+A `needs-validation` entry must carry:
+
+1. the exact missing fact (`is the load balancer setting X-Forwarded-For, or is the
+   app trusting a client-supplied one?`), and
+2. a safe way to establish it — an owner-observable check or a bounded local test.
+   Never a probe against production or shared infrastructure.
+
+**Write it down even when you cannot resolve it.** An unrecorded question comes back
+as an incident; a recorded one comes back as a task.
+
+⚠️ **Print the `needs-validation` section only when it has something in it** —
+except on a diff touching infrastructure, configuration or deployment, where it
+is mandatory even as "None.", because that is where the outside-the-repo facts
+live and "None." is then a real statement. Elsewhere a standing empty heading
+trains readers to skip the section, which defeats the rule it exists to serve.
+
+---
+
+## Rule 3 — Severity cannot exceed demonstrated impact
+
+| | |
+|---|---|
+| **critical** | an unauthenticated actor gains code execution, full data-store access, or takeover of arbitrary accounts |
+| **high** | an explicit control is **fully defeated** with real consequence — auth bypass, cross-tenant read or write, stored script execution affecting other users, authenticated code execution, unauthenticated remote stop of a shared service |
+| **medium** | a real boundary violation with limited blast radius or uncommon preconditions |
+| **low** | non-secret internals disclosed, or sustained effort for minimal gain |
+| **informational** | confirmed but minimal — useful mainly as a step inside a larger finding |
+
+**The high/medium line:** does the demonstrated result *fully defeat* the control, or
+only weaken it?
+
+**If you cannot state the concrete damage, the severity is lower than it feels.**
+
+> This governs how a finding is **described**. It does not soften the merge rule: a
+> confirmed security gap is Blocking wherever it lands on this table.
+
+---
+
+## Rule 4 — Recommend the smallest effective fix
+
+Name the invariant the code must enforce, and the narrowest change that enforces it
+**at the last trusted decision point**. A repository-relative edit plus a regression
+test, not generic hardening advice.
+
+If the same rule is enforced at several doors, say so — a fix at one door while the
+others still reach the same write is a fix that moves the defect rather than closing
+it.
+
+---
+
+## Where this gate stops, and the audit begins
+
+This gate reviews **a diff**. A security audit surveys **a system**, and they are not
+the same activity or the same cost.
+
+Use the companion skill's **guidance mode** from here: when the diff calls for it,
+read the ONE domain file that matches. Reading a reference is not running an audit.
+
+| the diff touches | read |
+|---|---|
+| auth, sessions, tokens, CORS, headers, route guards | `WEB-PROTOCOL-AND-AUTH.md` |
+| tenancy, soft delete, exports, retention, cross-account reads | `DATA-ISOLATION-AND-LIFECYCLE.md` |
+| cloud runtime, IAM, buckets, caches, manifests, environment | `CLOUD-AND-DEPLOYMENT.md` |
+| rendering user input, uploads, CSP, client-side state | `CLIENT-SIDE.md` |
+| pagination, unbounded queries, rate limits, timeouts | `RESOURCE-EXHAUSTION-AND-AVAILABILITY.md` |
+| dependencies, build, release, signing | `SUPPLY-CHAIN-AND-RELEASE.md` |
+
+🔴 **Do NOT run that skill's six-phase workflow from inside this gate.** Its unit of
+cost is an *agent invocation*: even its `quick` profile is four reconnaissance calls
+plus a hunter wave, a critic, and one or two verifiers per candidate. A per-change
+gate cannot afford that, and the skill says so itself — loading it does not authorize
+the workflow.
+
+**Schedule full audit mode as its own activity**, ideally before an external
+penetration test so the cheap findings are already fixed.
+
+⚠️ **Know this before the run, not during it:** that skill requires an OS-enforced
+sandbox — no network, empty environment, hard CPU/memory/wall-clock limits — before
+executing any target code, and states that without every control you do not execute
+it. Most machines do not have one. A run without it is **source-only**, and every
+dynamic claim comes back `needs-validation`. That is the honest result, and it is
+exactly why Rule 2 has to be in place *before* the audit rather than after it.
+
+---
+
+## Anti-patterns
+
+1. A checklist deviation presented as a vulnerability.
+2. Defence-in-depth advice with no reachable boundary violation.
+3. Probing live or shared environments where bounded local evidence would do.
+4. Guessing provider, proxy, browser, identity or deployment behaviour absent from source.
+5. Treating same-principal authority or self-impact as a crossed boundary.
+6. Reporting an effect stronger than the one observed.
+7. Assigning a severity to a `needs-validation` record.
+8. Letting the prose and the structured findings disagree.

package/skills/quality-gate/references/frontend-checklist.md

@@ -0,0 +1,98 @@
+# Frontend checklist
+
+UI code: components, pages, route loaders, forms, client state, and anywhere user
+input is rendered. Stack-neutral — the project's own standards win where they differ.
+
+---
+
+## The frontend is never authoritative
+
+- Every rule the UI expresses is also enforced on the server. A hidden button is UX,
+  not a permission.
+- **A control that reports success and changes nothing is Blocking**, not Minor — even
+  when the broken behaviour predates the change. Adding the control is what makes it
+  reachable, so the change owns it.
+- Where the server refuses, show **the server's own reason**. A message invented in the
+  client drifts from the rule the server actually enforces, and then two places disagree
+  about what happened.
+
+## Write mappers — the blind spot
+
+The single highest-value area in a UI review, because a mocked or faked API layer
+**cannot see it**: a mock never receives a request body, so a mapper that *drops* a
+field and one that *clears* it look identical from the mock.
+
+- **`undefined` is not "empty" — it is "don't touch this".** Serialisation drops the
+  key, so a partial update leaves whatever the record had. If the intent is *clear this
+  field*, send the explicit empty value the API accepts.
+- **Never send an empty string to mean empty** where the API's empty is null: `""` is
+  accepted and stored, then reaches consumers as a string rather than an absence, and
+  downstream renderers throw on it.
+- **Absent and empty-collection are different requests.** If the API treats a missing
+  key as "leave alone" and an empty array as "remove all", the mapper must be able to
+  express both, and the difference must be a distinct code path — not a falsy check.
+- **Anything mapping UI state onto a request body needs a test that stubs the transport
+  and asserts on the serialised body.** Not on the mock. That test is the only thing
+  that can distinguish the two failures above.
+
+## Read mappers
+
+- Map at the boundary; do not pass a raw response through typed as the domain object.
+  A cast type-checks and validates nothing, and the field you add next arrives unmapped.
+- Decide what a malformed value defaults to, and pick the default that **fails toward
+  the recoverable side** — an over-permissive screen the server then refuses beats a
+  screen that cannot be used.
+
+## Loading, empty and failure are three states, not two
+
+- **A failed read is not an empty result.** Many data libraries report "not loading"
+  once a request errors, so keying only on a loading flag draws "there is nothing here"
+  over data that exists and the user cannot tell.
+- A paused query — offline, or a network-mode guard — is a fourth case that looks like
+  neither. Use an explicit "has anything arrived?" check rather than inferring it.
+- Put the error branch **first**, so a 403 reads as "you may not see these" rather than
+  "there are none".
+
+## Lists and pagination
+
+- **One request with no limit is not "the whole list" — it is the first page,
+  silently.** Either page through to the server's reported total, or ask for a bound
+  and show it.
+- If the screen prints a count, it must come from a **different source** than the array
+  it labels. A count taken from the rendered array agrees with the screen by
+  construction and can never catch a truncation.
+
+## Rendering user input
+
+- Escape everything that came from a person. Where a page renders both authored content
+  and submitted content, **check which path each field takes** — the usual defect is
+  one field crossing from the escaped path to the authored one, and it is stored XSS on
+  a page colleagues read.
+
+## Forms
+
+- Validate with the same rules the server uses, and treat the server as the decider.
+- Trim before length rules, not after, or whitespace passes a minimum and stores empty.
+- Surface field-level server errors next to their fields.
+
+## Internationalisation
+
+- No user-visible string hardcoded when the project has a message catalogue.
+- Adding a key means adding it to **every** locale; a missing translation should be
+  visible in a check, not at runtime.
+
+## Accessibility and layout
+
+- Interactive controls are reachable by keyboard and carry an accessible name.
+- Icon-only buttons need a label.
+- **A page that loads is not a page that renders.** Every link resolving is not evidence
+  of a working screen — a layout can collapse to an unusable strip while every request
+  returns 200. When a page is reported broken, open it and measure the container.
+
+## Testing
+
+- Test the mapping and the state machine; do not re-test the framework.
+- **A test of on-screen copy must anchor the claim it makes.** Asserting a string exists
+  proves the string exists, not that it is shown in the right state.
+- Prefer a walk through the real screen for a flow bug; an assertion can agree with a
+  broken screen when both were written from the same wrong assumption.