create-warlock 4.2.6 → 4.2.8

package/templates/warlock/skills/security-baseline/SKILL.md

@@ -0,0 +1,352 @@
+---
+name: security-baseline
+description: 'Project-level security floor for Warlock.js apps — input validation at every boundary via `@warlock.js/seal` schemas, authentication via `@warlock.js/auth` (JWT + refresh) with `userType` config, server-side authorization never trusting client-supplied `userId`/`organizationId`, secrets only via `env(...)` + typed config files (never `process.env.X` scattered), parameterized queries through Cascade ORM (never raw concatenation), rate limiting via `@fastify/rate-limit` configured in `config/http.ts`, PII / token redaction in logs (`log.configure({ redact })`), `bcryptjs` for password hashing, `@mongez/encryption` for symmetric encryption, dependency vulnerability scanning (`yarn audit`). Triggers: writing a route handler / controller that accepts external input; touching auth, login, signup, session, token, JWT, password, refresh-token; reading secrets / API keys / env vars; writing a Cascade query or repository filter; handling file uploads, webhook payloads, queue messages; setting rate limits; user asks "is this secure", "input validation", "SQL / NoSQL injection", "XSS", "CSRF", "rate limiting", "secrets management", "authentication vs authorization", "where does X env var go"; importing `@warlock.js/seal` or `@warlock.js/auth` or `bcryptjs`. Skip: pure UI / styling that handles no data; code-style questions (load `skills/code-standards/SKILL.md`); HTTP envelope shape (load `skills/api-design/SKILL.md`); cryptography internals / writing your own crypto — stop and use a vetted lib; advanced auth flows (OAuth, SAML) — load `@warlock.js/social-auth` skill.'
+---
+
+# Security baseline
+
+**Status:** Stable
+**Applies to:** Every code path that touches external input, identity, secrets, persistence, or the public network.
+
+The non-negotiable security floor for any project on this template. Each rule maps to a real class of incident — most production breaches trace back to one of these eight being absent or sloppy.
+
+> **Sub-agent rule:** Before writing any code that handles external input, identity, or secrets, read this file. Code-style rules live in `skills/code-standards/SKILL.md` — this skill is about what the code must do, not how it must look.
+
+---
+
+## 1. Input trust model
+
+TypeScript types are runtime lies. The only thing standing between a malicious payload and your service is a runtime validator. Use `@warlock.js/seal`.
+
+### 1.1 What counts as untrusted input
+
+Anything that crosses the process boundary:
+
+- Request bodies, query params, path params, headers
+- File uploads (the binary AND the filename AND the MIME type)
+- Webhook payloads
+- Queue messages
+- Env vars (validated once at boot — see § 3)
+- Database rows from a *different* service (treat them as external if you don't own the writer)
+
+### 1.2 Where validation runs
+
+At the boundary, exactly once. Never inside services.
+
+The Warlock pattern: schema lives in the module's `schema/` folder, the controller types itself with the schema and attaches it via `controller.validation.schema`. See `skills/api-design/SKILL.md` § 6 for the full controller shape.
+
+```typescript
+// ✅ schema/create-order.schema.ts
+import { v, type Infer } from "@warlock.js/seal";
+
+export const createOrderSchema = v.object({
+  cartId: v.string(),
+  paymentToken: v.string(),
+  shippingAddress: v.object({
+    street: v.string().min(1),
+    city: v.string().min(1),
+    postalCode: v.string().min(1),
+    country: v.string().min(2).max(2),
+  }),
+});
+
+export type CreateOrderSchema = Infer<typeof createOrderSchema>;
+
+// ✅ controller — framework rejects invalid input with 422 before the handler runs
+import { type GuardedRequestHandler } from "app/auth/requests/guarded.request";
+import { type CreateOrderSchema, createOrderSchema } from "../schema/create-order.schema";
+
+export const createOrderController: GuardedRequestHandler<CreateOrderSchema> = async (
+  request,
+  response,
+) => {
+  const order = await placeOrderService(request.validated()); // already typed + safe
+  return response.success({ order });
+};
+
+createOrderController.validation = { schema: createOrderSchema };
+```
+
+The framework returns `422 Unprocessable Entity` with structured field errors automatically. **Never** catch validation errors in the controller — the boundary handles them.
+
+### 1.3 File uploads
+
+- Cap the size at the route level (`fileUploadLimit` in `config/http.ts` is the project floor; tighten per-route).
+- Sniff the real MIME type from the bytes; don't trust the `Content-Type` header.
+- Never use the client-supplied filename as a path component — generate a server-side identifier.
+- Quarantine until processed; scan if user-visible.
+
+### 1.4 Webhook payloads
+
+- **Verify the signature first**, schema-validate second. A signature failure aborts before any other work.
+- Reject requests older than the provider's replay window (typically 5 minutes).
+- Idempotency-key the handler (see `skills/observability-and-resilience/SKILL.md` § 4) — providers retry.
+
+---
+
+## 2. Authentication vs authorization
+
+AuthN proves who you are. AuthZ decides what you can do. Conflating them is how incidents start.
+
+### 2.1 Identity comes from the session, never the request body
+
+```typescript
+// ❌ trusting the client
+const order = await ordersRepository.find({ id, userId: request.input("userId") });
+
+// ✅ identity from the authenticated session
+const user = request.user;
+const order = await ordersRepository.find({ id, userId: user.id });
+```
+
+Any field whose value would determine permission (`userId`, `organizationId`, `roleId`, `isAdmin`) is read from the authenticated session — never from the request body, query, or header.
+
+### 2.2 Authentication via `@warlock.js/auth`
+
+The project's auth stack: JWT access tokens (1h) + refresh tokens (30d), configured in `config/auth.ts`. Password hashing via `bcryptjs`. The framework's `authService` (`@warlock.js/auth`) is the single entry point:
+
+```typescript
+// ✅ thin wrapper service — the framework does the work
+import { authService } from "@warlock.js/auth";
+import { User } from "app/users/models/user/user.model";
+
+export async function loginService(credentials, deviceInfo) {
+  return authService.login(User, credentials, deviceInfo);
+}
+```
+
+### 2.3 Authorization happens server-side, every endpoint, every time
+
+A `guarded(() => { ... })` wrapper around routes enforces authentication. **Authorization is separate** — being authenticated proves identity, not permission.
+
+Pattern: at the start of every mutating service, check ownership and role:
+
+```typescript
+// ✅
+export async function updateOrderService(orderId: string, input, user) {
+  const order = await ordersRepository.find({ id: orderId });
+
+  if (!order) {
+    throw new OrderNotFoundError(orderId);
+  }
+
+  if (order.userId !== user.id && !user.isAdmin) {
+    throw new ForbiddenError("not your order");
+  }
+
+  // ... mutate
+}
+```
+
+Resource ownership checks live in the service, not the controller. The controller only orchestrates.
+
+### 2.4 Role checks
+
+Use centralized role helpers, never inline string comparisons (`user.role === "admin"` is a typo waiting to happen). Define roles as an enum in `app/shared/utils/enums.ts`.
+
+---
+
+## 3. Secrets management
+
+### 3.1 `.env` is never committed
+
+- `.env.local` and `.env` are in `.gitignore` from day one.
+- `.env.example` is committed and documents every variable the app needs.
+- Production secrets come from the deployment platform's secret manager (Doppler, AWS Secrets Manager, Kubernetes secrets), not files on disk.
+
+### 3.2 Secrets enter through validated config
+
+The pattern is already established in `src/config/*.ts`. Every config file reads `env(...)` and exports a typed object. Never read `process.env.X` outside `config/`.
+
+```typescript
+// ✅ config/auth.ts — the project's actual pattern
+import { type AuthConfigurations } from "@warlock.js/auth";
+import { env } from "@warlock.js/core";
+
+const authConfigurations: AuthConfigurations = {
+  userType: { user: User },
+  jwt: {
+    secret: env("JWT_SECRET"),
+    expiresIn: "1h",
+    refresh: { /* ... */ },
+  },
+};
+```
+
+A missing critical env var should fail loudly at boot. Don't silently fall back to a default for security-relevant values (`JWT_SECRET` has no sensible default).
+
+### 3.3 Secrets never appear in logs
+
+The logger redaction layer is the safety net, but the first line of defence is not putting them in context at all.
+
+```typescript
+// ❌
+log.info("auth", "login", "User authenticated", { user, password, token });
+
+// ✅
+log.info("auth", "login", "User authenticated", { userId: user.id });
+```
+
+Configure `log.configure({ redact: { paths: ["password", "token", "*.secret", "*.apiKey"] } })` at startup — see `@warlock.js/logger/redact-sensitive-log-fields/SKILL.md`.
+
+### 3.4 Token lifetimes
+
+Short-lived access tokens (≤ 1h), longer-lived refresh tokens (≤ 30d) with rotation on every refresh, revocation on logout. The default in `config/auth.ts` matches this — don't extend access-token lifetime to "make it easier" for the frontend.
+
+---
+
+## 4. Injection prevention
+
+### 4.1 Cascade ORM — always parameterized
+
+Never compose query strings from user input. Cascade's repository and query builder are parameterized by default; never reach for a raw query mode.
+
+```typescript
+// ✅
+const orders = await ordersRepository.list({ status: input.status });
+
+// ❌ string-built filter with user value
+const orders = await ordersRepository.raw(`status = '${input.status}'`);
+```
+
+### 4.2 NoSQL operator injection
+
+If a request body is `{ status: { $ne: null } }`, a naive `find({ status: input.status })` becomes a `$ne: null` match — returns every row. The seal schema is what prevents this: declaring `status: v.string()` rejects an object value at the boundary.
+
+This applies to **query strings too**, not just bodies — a `?status[$ne]=` smuggled through the query is the same attack. That's why list endpoints validate the query with a schema and never pass raw `request.all()` to the repository (see `skills/api-design/SKILL.md` § 3.5).
+
+This is a real reason § 1 is non-negotiable.
+
+### 4.3 Command execution
+
+- Avoid `exec` / `spawn` with user input entirely.
+- If unavoidable, use the array-args form (`spawn(cmd, [arg1, arg2])`), never the string form.
+- Validate the input against a strict allowlist.
+
+### 4.4 Path traversal
+
+- Never concatenate user input into a file path.
+- Canonicalize (`path.resolve`) and verify the result starts with the expected prefix.
+- File uploads land under a server-generated path, never a client-supplied one.
+
+---
+
+## 5. Output safety
+
+### 5.1 HTML escaping
+
+For any user-controlled string rendered into HTML (email templates, server-rendered pages), escape at the template engine level. React Email handles this by default; if you reach for a raw string, you've taken on the responsibility.
+
+### 5.2 JSON responses
+
+The framework sets `Content-Type: application/json` for `response.success(...)` automatically. Don't override unless you genuinely mean to return a different type.
+
+### 5.3 Open redirects
+
+If you implement a "redirect back to where the user came from" feature, validate the destination URL against a whitelist of internal paths. Never blindly follow a user-supplied URL.
+
+### 5.4 CORS
+
+`config/http.ts` controls the CORS policy. The template default `origin: "*"` is **fine for early development** — but before production:
+
+- Replace `*` with the explicit frontend origin(s).
+- If credentials cross the boundary (cookies, auth headers), `*` is no longer allowed by the spec anyway.
+
+---
+
+## 6. Rate limiting and abuse
+
+### 6.1 Default limiter
+
+`config/http.ts` ships with `rateLimit: { max: 260, duration: 60_000 }` — 260 requests per minute per IP. That's the project floor for all routes.
+
+### 6.2 Aggressive limiter on `/auth/*`
+
+Login, signup, password-reset, and refresh-token endpoints get a much tighter limit (e.g. 10/min/IP, 5/hour/email). Brute-force is the cheapest attack; defending it is cheap too.
+
+### 6.3 Account-targeted limits
+
+For `/auth/login` and `/auth/reset-password`, key the limiter on the **email or user-id** in the payload as well as the IP — otherwise an attacker rotating IPs has free rein on a target account.
+
+### 6.4 Progressive lockout
+
+After N failed login attempts:
+- 3 failures → 1-minute delay
+- 5 failures → 5-minute delay + email notification
+- 10 failures → temporary account lock + manual review
+
+Never silently succeed-and-fail (returning 200 with no body to hide whether the account exists) — that's a UX disaster and doesn't actually slow attackers. Honest `401` + rate limiter is the right answer.
+
+---
+
+## 7. Dependency hygiene
+
+### 7.1 `yarn audit` in CI
+
+CI runs `yarn audit --level=high` on every PR. High and critical vulnerabilities block merge. Moderate goes on the backlog with a fix-by date.
+
+### 7.2 Lockfile committed
+
+`yarn.lock` is checked in. Always. CI installs with `--frozen-lockfile`.
+
+### 7.3 No `latest` in `package.json`
+
+Every dependency is pinned or carets-pinned. Never `"some-dep": "latest"` — that's a supply-chain attack waiting to happen.
+
+### 7.4 Prefer framework / std lib
+
+Every dependency is future risk. Before adding a 5-line utility, ask whether it's already covered by `@warlock.js/*`, `@mongez/*`, or the standard library.
+
+---
+
+## 8. Logging and PII
+
+See `skills/code-standards/SKILL.md` § 8 for the call signature. This is the **what not to log** list:
+
+### 8.1 Never log
+
+- Passwords (raw or hashed), API keys, JWT tokens, session ids, refresh tokens
+- Authorization headers
+- OTP codes
+- Payment data — card numbers, CVVs, card-holder data of any kind
+- Cookies
+
+### 8.2 Redact unless required
+
+- Personal identifiers: email, phone, full name, address
+- IP address (legal in some jurisdictions, regulated in others — check)
+- Device identifiers
+
+When a debugging incident genuinely needs personal data, route it through a separate, access-controlled channel — never the default log stream.
+
+### 8.3 Configure once
+
+```typescript
+log.configure({
+  redact: {
+    paths: ["password", "token", "*.secret", "*.apiKey", "authorization", "cookie"],
+  },
+  channels: [/* ... */],
+});
+```
+
+See `@warlock.js/logger/redact-sensitive-log-fields/SKILL.md` for the additive per-channel layer.
+
+---
+
+## 9. Review checklist
+
+Before merging a change that touches input, identity, secrets, or persistence:
+
+- [ ] Every untrusted input has a `@warlock.js/seal` schema attached at the controller
+- [ ] No identity field (`userId`, `organizationId`, role) is read from the request body
+- [ ] Ownership / authorization check runs in the service, not the controller
+- [ ] No `process.env.X` outside the `config/` folder
+- [ ] No secret value appears in any log call
+- [ ] All DB queries go through Cascade — no raw string-built queries
+- [ ] Rate limit appropriate for the route family (default for general, aggressive for auth)
+- [ ] No `.env` or secrets file in the commit
+- [ ] `yarn audit --level=high` passes
+- [ ] Logger redaction config covers any new sensitive field introduced
+- [ ] File uploads cap size, sniff MIME, server-generate the stored filename
+- [ ] Webhooks verify signature before any other work

package/templates/warlock/skills/testing-strategy/SKILL.md

@@ -0,0 +1,323 @@
+---
+name: testing-strategy
+description: 'Test pyramid posture for Warlock.js apps — Vitest co-located (`foo.ts` → `foo.spec.ts`); **when testing is enabled in the project (a `test`/`test:*` script in package.json OR a `vitest.config.*` / `vite.config.*` file), it is mandatory that every service ships a co-located `.service.spec.ts` and every HTTP controller / request handler ships a test — a new service or endpoint without a spec is incomplete**; unit tests dominate (~70%), integration tests via `@testcontainers/mongodb` + `@testcontainers/postgresql` (~25%), e2e for critical user journeys only (~5%); coverage is a smoke detector not a target (`yarn test:coverage` via `@vitest/coverage-v8`); flaky-test zero-tolerance (quarantine in 24h, fix or delete in 7); test isolation (no shared state, no order dependency); AAA structure with blank-line phases; mock at the boundary not deep inside; `MockSDK` from `@warlock.js/ai` for AI calls; real DB via testcontainers for integration; snapshot tests only for small deterministic output; contract tests for external integrations. Triggers: deciding whether to write a unit / integration / e2e test for a change; setting up a new `.spec.ts`; debugging a flaky test; reviewing the test plan in a PR; user asks "should I unit test this", "what is our coverage policy", "this test keeps failing intermittently", "what should I mock", "test pyramid", "integration test vs unit test", "snapshot tests", "how do I test a service that hits the DB", "how do I test AI code". Skip: Vitest assertion API mechanics — that''s the testing framework''s docs; language / runtime questions; load testing / performance benchmarking; framework-package internals — load the relevant `@warlock.js/*` skill.'
+---
+
+# Testing strategy
+
+**Status:** Stable
+**Applies to:** Every test in the project, and every code change that should but doesn't have one.
+
+Tests are insurance, not ceremony. The right tests prevent the right bugs at the right cost. Wrong-shape tests slow the team down and rot until everyone ignores them.
+
+> **Sub-agent rule:** Before writing tests, read this file to decide what kind of test belongs here.
+
+---
+
+## 0. When this skill applies — and the mandate
+
+This skill governs projects that have **opted into testing**. Testing is **enabled** when **either** is true:
+
+- `package.json` has a `test` (or `test:*`) script, **or**
+- a `vitest.config.*` / `vite.config.*` file exists at the project root.
+
+When the `test` feature is selected at scaffold time, both land automatically (Vitest, `@vitest/coverage-v8`, testcontainers, and a per-worker DB/cache test setup).
+
+### 0.1 If testing is enabled, tests are mandatory — not optional
+
+- **Every service** ships a co-located unit spec: `place-order.service.ts` → `place-order.service.spec.ts`. Cover the happy path, every branch, and every error path. Mock the repository — the service's logic is the unit under test.
+- **Every HTTP controller / request handler** ships a test: a unit test with mocked services for its branch / validation / authorization logic, **or** an integration test through the route when the wiring is the point. A new endpoint without a test is an incomplete endpoint.
+
+Write the spec in the **same change** that adds the service or controller. A reviewer treats a missing spec as a blocking defect, not a follow-up.
+
+### 0.2 If testing is NOT enabled
+
+No `test` script and no vitest/vite config — e.g. a scaffold created without the `test` feature. **Do not** add tests or testing dependencies unprompted, and don't invent a `vitest.config`. If the project is outgrowing prototype stage, *suggest* enabling the `test` feature — but never scaffold a suite the project didn't ask for.
+
+---
+
+## 1. The pyramid
+
+```
+        /\
+       /  \      e2e        (~5%)  — slow, full system, critical journeys only
+      /----\
+     /      \   integration (~25%) — real DB / queue, exercises wiring
+    /--------\
+   /          \  unit       (~70%) — fast, isolated, pure logic
+  /____________\
+```
+
+### 1.1 Unit — most of the suite
+
+- Services with mocked repositories
+- Utility functions (pure)
+- Model getters, validators, computed fields
+- Resource mappers
+- Error class construction
+
+Fast (< 50ms each), isolated (no I/O), pinned to a single function or class.
+
+### 1.2 Integration — real wiring
+
+- Services + real DB (via testcontainers)
+- Repository queries against a real DB
+- Queue producer + consumer wired together
+- Auth flow through the framework's middleware
+
+Medium (100ms–2s each), real dependencies, fewer than unit tests.
+
+### 1.3 E2E — critical journeys
+
+- "User can sign up and place an order"
+- "User can log in, hit rate-limit, recover"
+- Payment + webhook handshake
+
+Slow (5–30s each), small number (10–30 per app), only for journeys whose breakage is a business-impacting incident.
+
+### 1.4 The 70 / 25 / 5 split
+
+Not enforced numerically. Enforced culturally — when a reviewer sees ten new e2e tests for one feature, they push back.
+
+---
+
+## 2. What to test, what not to
+
+### 2.1 Test
+
+- **Public surface of a module** — services, controllers, resources, models' public methods
+- **Branches and edge cases** — every `if` / `else` worth its salt has a test
+- **Error paths** — what happens when the dependency fails / the input is invalid / the user lacks permission
+- **Security-sensitive logic** — auth, authorization, input validation, rate limiting
+- **Money and time arithmetic** — these break silently; tests are the only safety net
+- **Business rules** — anything where "the spec says X" matters more than "the code does Y"
+
+### 2.2 Don't test
+
+- **The framework** — `@warlock.js/*` has its own tests. Don't re-test that `response.success()` returns 200.
+- **Trivial getters / setters** — `cart.totalCents` returning `this.get<number>("total_cents", 0)` doesn't need a test
+- **One-line passthroughs** — `loginService(...)` just calling `authService.login(...)` doesn't need a unit test (an integration test of the wiring is better)
+- **Generated code** — migrations, resource scaffolds
+
+### 2.3 The rule of thumb
+
+If a future change to this function could silently break behaviour someone cares about, write a test. If a future change would either be obviously broken or obviously fine, skip it.
+
+---
+
+## 3. Test isolation — non-negotiable
+
+### 3.1 No shared mutable state
+
+Each test sets up and tears down its own world. No `let users = []` at the top of the file mutated across tests.
+
+### 3.2 Test order independence
+
+`vitest --shuffle` should still pass. If it doesn't, you have shared state somewhere — fix it before adding more tests.
+
+### 3.3 Database tests
+
+Use transactions that roll back, or use testcontainers with a fresh container per file. Never share rows across tests.
+
+The project's testcontainers setup makes "fresh DB per test file" cheap — use it.
+
+### 3.4 Time and randomness
+
+Stub `Date.now()` / `Math.random()` / UUID generation when the test depends on the value. `vi.useFakeTimers()` and `vi.spyOn()` are your tools.
+
+---
+
+## 4. Mocking philosophy
+
+### 4.1 Mock at the boundary
+
+Mock the HTTP client, not the internal functions that use it. Mock the AI provider, not the service that calls it. The further from the boundary you mock, the more your tests describe implementation rather than behaviour.
+
+### 4.2 AI calls — `MockSDK`
+
+Never hit a real provider in tests. Use `MockSDK` from `@warlock.js/ai`:
+
+```typescript
+// ✅
+import { MockSDK } from "@warlock.js/ai";
+
+const ai = MockSDK({
+  responses: [{ text: "mocked response" }],
+});
+
+const result = await summarizeContentService(input, { provider: ai });
+expect(result).toBe("mocked response");
+```
+
+See `@warlock.js/ai/skills/run-ai-agent/SKILL.md` for the full mock surface.
+
+### 4.3 Database — real, via testcontainers
+
+For integration tests, run a real Mongo or Postgres container via `@testcontainers/mongodb` or `@testcontainers/postgresql`. The cost (a few seconds at suite start) is worth the fidelity (catching real-world query issues, real index usage, real type coercion).
+
+For pure-unit tests of services, mock the repository — the service's logic is the unit under test, not the DB.
+
+### 4.4 Time — stub, don't sleep
+
+```typescript
+// ❌
+await sleep(1000);
+
+// ✅
+vi.useFakeTimers();
+vi.advanceTimersByTime(1000);
+```
+
+A test that sleeps is a test that's slow and flaky. Stub the clock.
+
+---
+
+## 5. AAA structure
+
+Every test has three phases, separated by blank lines:
+
+```typescript
+it("denies cart updates after checkout", async () => {
+  // Arrange
+  const cart = await cartFactory.create({ status: CartStatus.CHECKED_OUT });
+  const update = { totalCents: 99999 };
+
+  // Act
+  const promise = updateCartService(cart.id, update, mockUser);
+
+  // Assert
+  await expect(promise).rejects.toThrow(CartLockedError);
+});
+```
+
+### 5.1 One assertion target per test
+
+Multiple `expect` calls are fine if they all verify one outcome. A test that asserts five unrelated things hides which one broke.
+
+### 5.2 Descriptive `it(...)` names
+
+The name describes the expected behaviour, not the implementation. "rejects cart updates after checkout" beats "throws CartLockedError when status is CHECKED_OUT" (the implementation detail is irrelevant to the reader scanning the suite).
+
+---
+
+## 6. Coverage policy
+
+### 6.1 Coverage is a smoke detector
+
+Low coverage = guaranteed gaps. High coverage = no guarantee of correctness. Treat it as a "definitely look here" signal, not a quality metric.
+
+### 6.2 Suggested floors
+
+- `src/app/**/services/**` — ≥ 70% line coverage
+- `src/app/**/utils/**` — ≥ 80% (pure code, easy to test)
+- `src/app/**/resources/**` — no floor (output-only, low risk)
+- `src/app/**/models/**` — no floor (mostly getters; framework tests cover the rest)
+- `src/app/**/types/**` — no floor (no runtime behaviour)
+
+### 6.3 Aim for "the meaningful paths are tested", not 100%
+
+Chasing the last 5% of coverage produces brittle tests over edge-case code that nobody cares about. Spend the time on tests that catch real regressions.
+
+### 6.4 The `yarn test:coverage` command
+
+Runs Vitest with `@vitest/coverage-v8` (already in dependencies). Add coverage as a CI gate per the floors above once the suite is large enough.
+
+---
+
+## 7. Flaky test policy — zero tolerance
+
+A test that fails intermittently is a bug, not a nuisance.
+
+### 7.1 The deadline
+
+- **24 hours** to quarantine (mark `.skip` with a tracking ticket).
+- **7 days** to fix or delete.
+
+### 7.2 Why the deadline matters
+
+Once a team accepts flakes, the suite dies. Every flake makes the next failure easier to dismiss ("probably flaky"). The signal-to-noise ratio collapses, real failures get ignored, the suite stops being trusted, the team stops writing tests.
+
+Guard against this actively — flake reports are first-priority bugs.
+
+### 7.3 Common causes
+
+- Shared state between tests (see § 3)
+- Real I/O without proper teardown
+- Timing assumptions (`setTimeout`, polling)
+- Test order dependency
+- Race conditions in the code under test (test exposed a real bug — fix the code)
+
+---
+
+## 8. Snapshot tests
+
+### 8.1 Use for
+
+- Small structured output that's deterministic
+- Error response shapes
+- Resource serialization output (small ones)
+
+### 8.2 Don't use for
+
+- Large objects (the diff becomes unreadable; reviewers rubber-stamp)
+- Non-deterministic output (timestamps, generated ids — stub them first or omit)
+- HTML / large strings (use targeted string assertions instead)
+
+### 8.3 Update with care
+
+`vitest -u` regenerates snapshots. **Read every line of the diff before committing the update.** A blind `-u` is how silent regressions land.
+
+---
+
+## 9. Contract tests
+
+### 9.1 What and why
+
+For any external integration whose shape might drift (third-party API, partner webhook):
+
+- **Provider contract** — what we send, what we expect back
+- **Consumer contract** — what they send us, what we expect to handle
+
+Run against a recorded fixture in CI (fast, deterministic). Run against the real endpoint in a nightly job — if their API drifts, you catch it within 24h instead of in production.
+
+### 9.2 Where they live
+
+Co-located with the integration: `src/app/payments/clients/stripe-client.contract.spec.ts`.
+
+---
+
+## 10. File layout
+
+```
+src/app/orders/services/
+  place-order.service.ts
+  place-order.service.spec.ts       ← unit test, mocks repository
+  place-order.service.integration.spec.ts  ← integration, real DB
+```
+
+- `.spec.ts` — default suffix; covers unit tests
+- `.integration.spec.ts` — when the test needs real I/O (DB, queue)
+- `.e2e.spec.ts` — full-system journey tests (sparse; one per critical flow)
+
+Tests live next to the file under test, always. Never in a separate `__tests__/` or `test/` folder — colocation makes the link obvious and survives refactors.
+
+---
+
+## 11. Review checklist
+
+Before merging a change that should include tests (testing enabled — see § 0):
+
+- [ ] Every new/changed **service** has a co-located `.service.spec.ts`
+- [ ] Every new/changed **HTTP controller / request handler** has a test (unit with mocked services, or integration through the route)
+- [ ] New public function has at least one test
+- [ ] Branches / error paths / edge cases covered
+- [ ] No real provider API hit in tests (use `MockSDK` for AI, mock HTTP clients otherwise)
+- [ ] Integration tests use testcontainers, not mocked DBs
+- [ ] AAA structure, blank-line phase separation
+- [ ] One assertion target per test (where practical)
+- [ ] No `await sleep(...)` — fake timers instead
+- [ ] No shared mutable state between tests
+- [ ] Test names describe behaviour, not implementation
+- [ ] No `.only`, no `.skip` without a tracking ticket
+- [ ] Snapshots reviewed line-by-line if updated
+- [ ] `yarn test --run` passes; `yarn test:coverage` doesn't drop the floor