docs(P03): complete domain-derived-docs phase

domains/testing/fixtures.md

@@ -0,0 +1,49 @@
+# Test Fixtures — Derived Rules
+
+> Derives from `domains/testing/first-principles.md` P7 (Realism), P2 (Independence), P3 (Determinism).
+
+## Fixtures are Real Data (P7 Realism)
+
+- A fixture resembles production data in shape, distribution, and edge cases.
+- A fixture with `name: "test"` and `email: "a@b.c"` hides bugs that real data surfaces.
+- Use realistic names, realistic emails, realistic dates. `"Jane Doe", "jane.doe@example.com", "2026-03-15"`.
+
+## Factory Over Fixture (P2 Independence, P3 Determinism)
+
+- A fixture file is shared state. A factory is fresh state per test.
+- Prefer factories (e.g., `factory.User()` returning a new instance) over shared fixture files.
+- A shared fixture is mutated by one test, breaks another. Independence is violated.
+
+## Builders for Complex Data
+
+- A builder (`UserBuilder().withEmail().withAdmin().build()`) composes only the fields the test needs.
+- A builder with defaults: every field has a sensible default; tests override only what they test.
+- A builder is the test's API to data. Stable, composable, readable.
+
+## Setup and Teardown (P2 Independence)
+
+- Every test cleans up after itself. No test leaves state for the next.
+- `setUp`/`tearDown` (or `beforeEach`/`afterEach`) restore the world.
+- A test that depends on the order of execution is not independent.
+
+## Determinism (P3)
+
+- No `Date.now()`, no `Math.random()` in fixtures. Inject the clock, inject the RNG.
+- A fixture that uses "now" is non-deterministic. It passes today and fails tomorrow.
+- Fix timestamps: `createdAt: new Date("2026-01-01T00:00:00Z")`.
+
+## Edge Case Fixtures (P9 Edge Case Coverage)
+
+- A fixture set includes: the empty case, the single-item case, the max-size case, the unicode case.
+- A fixture set includes invalid data: malformed email, negative age, future date.
+- Edge case fixtures are first-class, not "extra credit."
+
+## What Violates Fixture Discipline
+
+| Violation | Principle |
+|-----------|-----------|
+| `name: "test"` fixture | P7 Realism |
+| Shared fixture file mutated across tests | P2 Independence |
+| `createdAt: new Date()` (now) in fixture | P3 Determinism |
+| No edge-case fixtures | P9 Edge Case Coverage |
+| A 500-line fixture file | P3 (complexity) |

domains/testing/pyramid.md

@@ -0,0 +1,60 @@
+# Test Pyramid — Derived Rules
+
+> Derives from `domains/testing/first-principles.md` P4 (Fast Feedback), P5 (Coverage of Behavior), P10 (No Test Theater).
+
+## The Pyramid
+
+```
+        /\
+       /e2e\        few, slow, integration
+      /------\
+     /  integ  \    some, medium, contract
+    /----------\
+   /    unit    \   many, fast, isolated
+  /--------------\
+```
+
+- **Unit (many):** test a function/class in isolation. Fast (< 10ms each). The bulk of tests.
+- **Integration (some):** test components together (DB, API client, queue). Medium (< 1s each).
+- **E2E (few):** test the whole system from outside. Slow (> 1s each). The tip of the pyramid.
+
+## Why a Pyramid (P4 Fast Feedback)
+
+- A pyramid inverts to a "ice cream cone" (many e2e, few unit) when devs avoid unit tests.
+- Inverted pyramids are slow and flaky. The feedback loop breaks.
+- The pyramid shape preserves fast feedback: most failures are unit failures, found in < 10ms.
+
+## What Goes Where
+
+| Test Type | What it Covers | Speed | Count |
+|-----------|----------------|-------|-------|
+| Unit | A function, a class, a pure module | < 10ms | Many |
+| Integration | DB queries, API contract, queue behavior | < 1s | Some |
+| E2E | A user flow, an API request → response end-to-end | > 1s | Few |
+
+- A unit test does not hit the database. A unit test does not make a network call.
+- An integration test does not test business logic; it tests the integration.
+- An e2e test does not test edge cases; it tests the happy path. Edge cases are unit tests.
+
+## Anti-Patterns (P10 No Test Theater)
+
+- **Ice cream cone:** many e2e, few unit. Slow, flaky, no signal.
+- **Cupcake:** same count at every level. No pyramid shape. Slow.
+- **Only unit:** 100% unit coverage, 0% integration. The system is untested as a whole.
+- **Only e2e:** every edge case is an e2e test. The suite takes an hour.
+
+## Coverage (P5)
+
+- Unit coverage of behavior: every branch, every edge case, every error path.
+- Integration coverage of contracts: every API endpoint, every DB query, every queue interaction.
+- E2E coverage of flows: the top 3–5 critical user flows. Not every permutation.
+
+## What Violates the Pyramid
+
+| Violation | Principle |
+|-----------|-----------|
+| E2E test for an edge case | P4 (slow feedback) |
+| Unit test that hits the DB | P2 (not isolated) |
+| 0 integration tests | P5 (no coverage of contracts) |
+| 500 e2e tests, 50 unit tests | P10 (theater) |
+| A 30-second test suite | P4 (feedback loop broken) |