agent-quality-skills 1.0.0

package/skills/quality-gate/references/gates-and-fixes.md

@@ -0,0 +1,132 @@
+# Mechanical gates and the safe-fix policy
+
+How to find and run the repo's real gates, and exactly what may be auto-fixed. The
+goal: let tooling catch mechanical problems so reading time goes to judgment, and only
+ever apply a change that cannot alter behaviour or a public contract.
+
+---
+
+## Detect, don't assume
+
+Read the project's manifest and run the scripts that **actually exist**. Do not run a
+command that is not defined — report it as absent instead. Run long gates in the
+background so review continues while they do.
+
+```bash
+# node
+node -e "console.log(Object.keys(require('./package.json').scripts||{}).join('\n'))"
+# make
+grep -E '^[a-zA-Z_-]+:' Makefile
+# python / rust / go
+ls pyproject.toml tox.ini Cargo.toml Makefile go.mod 2>/dev/null
+```
+
+Then run each one that is a gate. Typical shapes:
+
+| gate | look for |
+|---|---|
+| lint | `lint`, `lint:ci`, `check`, `ruff`, `clippy`, `golangci-lint` |
+| format | `format`, `fmt`, `format:check` — prefer the **check** variant for reporting |
+| typecheck | `typecheck`, `check`, `tsc --noEmit`, `mypy`, `svelte-check` |
+| test | `test`, `test:unit`; integration and e2e separately |
+| build | `build`, `compile` |
+
+**Package manager and monorepo:** honour the lockfile (`pnpm`/`yarn`/`npm`/`bun`). In
+a monorepo, scope to the changed workspace rather than building the world.
+
+**Integration and e2e suites** often need a database, a cache, a browser, or a network
+service. If one cannot run cleanly here, **say so and separate it from genuine
+failures** — a false red costs as much trust as a false green.
+
+---
+
+## Three traps that each produced a false green
+
+### 1. Never pipe a gate and then read `$?`
+
+```bash
+npm test | tail -5 ; echo $?      # ← this is TAIL's exit code. Always 0.
+```
+
+A failing suite reads as a pass. Redirect and read the tool's own status:
+
+```bash
+npm test > /tmp/test.log 2>&1 ; echo "exit=$?"
+```
+
+The same applies to a trailing `echo`, and to any wrapper that reports the status of
+the last command in a chain rather than the gate's.
+
+### 2. Run the gates that exist, not the ones you remember
+
+Enumerate the manifest every time. A suite you never ran is not a suite that passed,
+and the one you forgot is usually the one that would have gone red — a change that
+adds a dependency to a class breaks the **unit** spec that hand-builds it while
+integration tests, which wire the real thing, stay green.
+
+### 3. The 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 — for example a docs or lint checker whose npm script lacks the `--check` flag
+and therefore always succeeds. Compare the script body against the CI invocation.
+
+---
+
+## Reporting gate results
+
+- Report the **real** counts from the output: `Tests: ❌ 2 failed (40 passed)`, with
+  the first failing names. Never guess.
+- A missing script is `⏭ no "lint" script found` — not a failure, and not a pass.
+- **Sanity-check the test count against the baseline.** If the diff adds four tests,
+  the total should move by four. A total that did not move, or moved by the wrong
+  amount, means a suite silently did not run — which a green exit code will not tell
+  you. Measure the baseline on the base branch rather than recalling it.
+
+---
+
+## Safe-fix policy
+
+A fix is **safe to auto-apply** only if a formatter or linter would make it **and** it
+cannot change runtime behaviour or a public contract.
+
+### Auto-fix — apply, then list each one with its file
+
+- The project formatter (`prettier --write`, `ruff format`, `gofmt`, `cargo fmt`).
+- Linter autofix of safe rules: import ordering, unused-import removal,
+  const-over-let, quote / semicolon / trailing-comma style, simple reflows.
+
+### Report only — never auto-apply
+
+- Any change to logic, control flow, or behaviour.
+- Replacing loose types with concrete ones; adding or changing validation schemas.
+- Renaming public symbols, endpoints, response fields, or enum values — a consumer
+  depends on every one of them.
+- Security changes: adding authorization, sanitisation, rate limiting.
+- Architecture moves: taking logic out of a controller, introducing a worker path.
+- Any schema or migration change.
+- Deleting code that looks dead, unless you have confirmed it is unreferenced. A
+  removed export can be a breaking change; when unsure, report instead of deleting.
+
+### After auto-fixing
+
+Re-run the affected gate so the report reflects the corrected state. If an autofix
+touched something logic-adjacent, review that diff before keeping it.
+
+---
+
+## Proving a test is load-bearing
+
+When the change adds a test, the report is stronger if the test is shown to be able to
+fail. Neutralise the fix, confirm the test goes red **for the right reason**, restore
+it. A test that stays green under a mutation of the code it claims to cover is proving
+nothing, however well it reads.
+
+Two things worth stating when you do this:
+
+- **which** cases went red, counted — not "the test fails", but which ones and how
+  many; and
+- **how** they failed — an assertion mismatch and a hang are different evidence, and
+  the one that matches the production symptom is the stronger claim.
+
+Undo a mutation from a saved copy, never with a checkout that could take unrelated
+work with it.

package/skills/quality-gate/references/go-live-checklist.md

@@ -0,0 +1,93 @@
+# Go-live / release-readiness checklist
+
+Use this **only** when asked for a release, go-live or production-readiness review —
+never for a routine per-change review.
+
+Produce a report grouped by priority, each item ✅ / ❌ / ⏭ (n/a) with a one-line note,
+then a **Go / No-Go**. Any failing P0 → **No-Go**.
+
+> ⚠️ **Mark ✅ only from evidence you gathered in this run.** An item copied forward
+> from a previous release, or taken from a status page, is ⏭ with a note saying who
+> owns it — not ✅. The single most common way a release checklist misleads is a tick
+> that records somebody's memory rather than a check.
+
+---
+
+## P0 — must pass
+
+**Security** — authentication verified · authorization verified on every protected
+action · no secret in source or logs · production secrets in a secret store ·
+input validation · upload validation · rate limits on public routes · CORS reviewed ·
+transport encrypted · credentials and tokens absent from logs.
+
+**Data** — production backup taken **and a restore tested** · every migration reviewed
+and run both directions · constraints and indexes verified · connection pool sized ·
+rollback documented.
+
+**Infrastructure** — environment and variables verified · images built and versioned ·
+health checks answering · certificates valid · DNS correct · firewall reviewed.
+
+**Observability** — service, data-store and worker monitoring on · error alerting on ·
+**alert delivery tested**, not just configured.
+
+**Logging** — structured · correlation ids present · no sensitive field logged.
+
+**Async and integrations** — queues, retries and dead-letter paths configured · workers
+connected · each external integration's credentials, connectivity, retry and failure
+handling exercised.
+
+**Application flows** — every critical user journey tested end to end, named
+individually rather than as a group.
+
+**Deployment** — release notes · deployment plan · **rollback plan** · named owner ·
+business approval.
+
+**Delivery channel** — ⚠️ the one most often missing from a plan that tracks only code
+and data. Can the built artefact actually reach users? Store or distribution account in
+good standing, signing identity valid, build toolchain at the version the store
+requires, and somebody named as its owner. Verify it by pushing a build through the
+real path, not by assuming — this is regularly discovered on the day of release,
+because nothing in the development process touches it.
+
+---
+
+## P1 — should pass
+
+**Testing** — unit, integration and end-to-end green · regression done · user
+acceptance done.
+
+**Performance** — response times measured · slow queries reviewed · N+1 checked ·
+indexes confirmed · queue throughput reviewed. Measured numbers, not impressions.
+
+**Localisation** — every locale's content verified · switching and fallback verified.
+
+**Documentation** — API reference regenerated **and published** — the generated file in
+the repository is not what consumers read · deployment docs current.
+
+**Auditability** — audit log covers the actions that matter, including the value
+before a change, and someone can read it.
+
+**CI/CD** — build, test, deploy and rollback pipelines each exercised.
+
+---
+
+## P2 — nice to have
+
+Caching and asset optimisation · runbook, on-call and incident docs · disaster-recovery
+rehearsal with a stated objective · capacity and scaling reviewed.
+
+---
+
+## Final Go / No-Go
+
+- [ ] All P0 complete
+- [ ] Outstanding risks written down, with an owner each
+- [ ] Stakeholders informed
+- [ ] Rollback approved
+
+**Recommendation: Go / No-Go**, with justification.
+
+> 🔒 **Do not publish an open security item.** A vulnerability already fixed is good
+> material for a release note — it shows the review is real. One still open tells a
+> reader where to push before it is closed. Track those internally and say only that
+> internal security follow-ups exist, if it must be mentioned at all.

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

@@ -0,0 +1,120 @@
+# Security checklist (cross-cutting)
+
+Read **`evidence-contract.md` first** if you are about to write a finding. This file
+is the *what to look at*; that one is *what makes a claim count*.
+
+Security is never deferred: a **confirmed** gap is Blocking, full stop. A suspicion is
+`needs-validation` and carries no severity.
+
+Principles: least privilege · defence in depth · secure by default · explicit
+authorization · fail securely. Never trust user input, client-side validation, or an
+external integration. **Every control is enforced server-side.**
+
+---
+
+## Authentication
+
+- Short-lived access credentials; refresh rotated; signature **and** expiry verified.
+- Login, logout, refresh and password-reset paths all exist and all agree.
+- Passwords hashed with a memory-hard or adaptive KDF (argon2, bcrypt, scrypt) — never
+  plaintext, never a bare fast hash, never logged.
+- A token minted for one purpose must not be accepted for another. If the system issues
+  scoped or single-purpose tokens, the verifier checks the scope, not just the
+  signature.
+
+## Authorization
+
+- Enforced on the **server**, at route *and* resource level. A frontend check is UX.
+- **Ask it as: who writes this value, who can change it, and who can see it?** — not
+  "does the check exist?". The check usually exists.
+- **Every door that reaches the same write must carry the same rule.** A guard on the
+  endpoint in the ticket, with a sibling route reaching the same mutation unguarded, is
+  a gap — and it is the most common one.
+- Hiding a control in the client is not hiding the data: if it is on the wire, it has
+  leaked.
+
+## Input validation and injection
+
+- Validate body, query, path params and uploads at the boundary, with a schema.
+- **SQL:** parameterised queries only. String-interpolated SQL with user input is
+  Blocking.
+- **XSS:** escape on output; never render untrusted HTML. Where a page renders both
+  authored content and user-submitted content, **check which path each field takes** —
+  the usual defect is one field crossing from the escaped path to the authored one.
+- **SSRF:** never fetch a user-supplied URL without validating scheme and host and
+  blocking internal ranges.
+- **Deserialisation and templating:** no user input reaching an evaluator.
+
+## Rate limiting and abuse
+
+- Public and unauthenticated routes are limited. Login, one-time codes and
+  password-reset need the tightest.
+- Outbound calls respect the **partner's** limit too, not only ours.
+- A counter that does not move for one class of caller is itself an oracle — check that
+  a refusal path and a success path are not distinguishable by timing or by a side
+  effect when the intent is that they should not be.
+
+## File upload
+
+- Validate size, declared type **and** actual content; allow-list rather than deny-list.
+- Never execute an upload; store outside any executable path; serve private files
+  through a signed, expiring URL rather than a public one.
+- **Keep public and private storage physically separate**, and make the separation
+  structural — two ports or two buckets, not one flag. A flag is one wrong argument
+  away from publishing an identity document; a missing method is not.
+
+## Secrets
+
+- No secret in source: signing keys, database and cache passwords, integration
+  credentials, API keys. A hardcoded secret is Blocking.
+- Never commit environment files, private keys or tokens. Run a secret scanner over
+  history, not just the diff.
+- A default value for a secret that is only refused in production is a secret in source.
+
+## Logging
+
+- Structured, with a correlation id and the acting principal.
+- **Never log** passwords, tokens, authorization headers, one-time codes, full card or
+  identity numbers. Logging any of these is Blocking.
+- Log the id, not the person: a user id is fine, an email address in a log is a
+  retention problem.
+
+## Error handling
+
+- No stack trace, SQL, internal path or secret in a response. Generic message out,
+  detail to the log.
+- **The message must be true.** A handler that answers "invalid credentials" from a
+  path that never checked a credential sends the client to re-prompt for something that
+  was correct, and sends whoever reads the log hunting a bug that does not exist.
+
+## Infrastructure, when visible in the diff
+
+- Transport encrypted; only required ports exposed.
+- Data stores authenticated and not publicly reachable.
+- If the app trusts a forwarded client IP, something upstream must be setting it — if
+  that cannot be established from the repository, it is `needs-validation`, with the
+  consequence stated (per-IP limits and any IP kept as evidence are wrong).
+
+## Dependencies
+
+- No unused packages. Known-vulnerability check before release. A pinned-backwards
+  version to dodge a break can drag in advisories — check before pinning down.
+
+---
+
+## Quick triage
+
+**Blocking** — missing authn/authz on a reachable action · secret or token in code or
+logs · interpolated SQL · untrusted HTML rendered · arbitrary URL fetched · uploads
+executed or exposed · responses leaking internals · **a control that reports success
+and changes nothing** (adding the button is what makes it reachable, so the change owns
+it, even when the broken behaviour predates it).
+
+**Major** — missing rate limit on a sensitive public route · weak upload validation ·
+missing validation not yet exploitable · missing audit trail on a sensitive action.
+
+**Minor** — hardening suggestions, log-field completeness, naming.
+
+**Needs validation** — anything whose decisive fact is a proxy, provider, identity or
+deployment behaviour not present in the repository. No severity. State the missing fact
+and a safe way to check it.

package/templates/QUALITY-GATE.md

@@ -0,0 +1,87 @@
+# Quality gate — project configuration
+
+Copy this to your repository root as `QUALITY-GATE.md` and fill it in. It is
+**optional**: the gate works without it, using the bundled checklists and whatever
+scripts your manifest defines. This file is how a project overrides those defaults and
+records the traps a reviewer cannot infer from the code.
+
+Delete every section you do not need. An empty heading is worse than no heading — it
+reads as "nothing here", which is a claim.
+
+---
+
+## Standards
+
+Where the written standards live, if not in one of the conventional locations:
+
+```
+docs/standards/
+```
+
+Which ones cover what, if it is not obvious from the filenames.
+
+---
+
+## Lanes
+
+If not every change needs the same depth of review, say so here — otherwise the gate
+treats them all as full.
+
+| lane | what falls in it | when the gate runs |
+|---|---|---|
+| **full** | auth · money · permissions · migrations · anything on a published contract | before merge |
+| **fast** | internal screens · copy · docs · refactor with no behaviour change · test-only | batched |
+
+> When unsure, it is **full**. A change that looks internal but alters what an external
+> consumer renders is full lane.
+
+---
+
+## Branches and merge rules
+
+```
+feature → develop → staging → main
+```
+
+- Feature into the integration branch: **squash**.
+- Every promotion between long-lived branches: **merge commit, never squash.** Squashing
+  a promotion makes the two branches look like they never met, and every promotion
+  afterwards shows the whole diff with conflicts, permanently.
+- Protected branches: …
+
+---
+
+## Gates the project actually has
+
+List the commands, including any that the manifest does **not** expose as a script —
+those are the ones a reviewer misses.
+
+```bash
+npm run lint
+npm run typecheck
+npm test
+npm run build
+```
+
+⚠️ Note any script whose body differs from what CI runs. A checker whose npm script
+omits its `--check` flag exits 0 always, and reports as a passing gate.
+
+---
+
+## Traps specific to this codebase
+
+The highest-value section, and the only one nothing else can supply. Each entry is a
+thing that has been **wrong while looking right** here.
+
+Write each one as: *the symptom* → *the actual cause* → *what to check instead*.
+
+- …
+
+---
+
+## What must not be published
+
+Anything the gate should never write into a public artefact — open security items,
+internal hostnames, customer identifiers.
+
+- …