pi-dev-team 0.2.0

package/knowledge/test-matrix-examples/react-node-spa.md

@@ -0,0 +1,24 @@
+# Worked example — React SPA + Node/Express API
+
+Few-shot template for `test-design-advisor`. Adapt the rows; don't copy verbatim. Feature: **a logged-in user submits a "place order" form and sees a confirmation**. Architecture is thin-logic glue over frameworks → **trophy** shape (`test-pyramid.md`).
+
+## Pyramid placement (advisor output shape)
+
+| Behavior | Layer | Gate | Tool (`test-stack-profiles/`) | Why |
+|----------|-------|------|-------------------------------|-----|
+| Order total + tax calculation | Unit | — | Vitest/Jest (`node`, `react`) | pure logic, edge cases |
+| `POST /orders` persists + returns 201 | Integration | — | supertest + test DB (`node`) | route, validation, persistence wiring |
+| Order form renders + disables submit while pending | Component | — | Testing Library + MSW (`react`) | DOM, wiring, async state — API mocked |
+| User submits and sees confirmation | E2E | ↑E2E (Gate A) | Playwright (`react`) | user acts and must *see* the rendered result — amortize into the existing checkout journey |
+
+## Quadrants (`testing-quadrants.md`)
+
+Q1 unit+integration+component ✓ · Q2 the E2E journey doubles as an acceptance example ✓ · **Q3 empty** → charter one exploratory session on the checkout flow · **Q4** → add a load check on `POST /orders` if it's hot.
+
+## Techniques (`testing-techniques/`, on match)
+
+Order-total invariants (never negative, tax ≤ total) → **property-based**. Payload from an untrusted client → **schema-validation** on the request body.
+
+## Notes
+
+One E2E for the journey, not one per field — field validation is a component/unit concern (avoid the ice-cream cone). The fat integration+component middle is correct for this architecture, not an hourglass.

package/knowledge/test-matrix-examples/spring-boot-service.md

@@ -0,0 +1,25 @@
+# Worked example — Spring Boot REST service
+
+Few-shot template for `test-design-advisor`. Adapt the rows. Feature: **a service exposes `POST /transfers`, applies a business rule (no overdraft), persists, and publishes a `TransferCompleted` event**. Rich domain logic → **pyramid** shape (`test-pyramid.md`).
+
+## Pyramid placement (advisor output shape)
+
+| Behavior | Layer | Gate | Tool (`test-stack-profiles/spring-boot`) | Why |
+|----------|-------|------|------------------------------------------|-----|
+| Overdraft rule rejects an over-limit transfer | Unit | — | JUnit (no Spring context) | core domain logic, all branches |
+| `TransferService` orchestrates rule + repo + publisher | Unit (sociable) | — | JUnit + stub repo/publisher | wiring of collaborators |
+| `POST /transfers` maps request → 200/422, JSON shape | Component | — | MockMvc / `@WebMvcTest` | controller, validation, serialization — deps doubled |
+| Repository persists + reads back correctly | Integration | — | Testcontainers (real DB) | the adapter/SQL actually works |
+| Other services still accept our event/response shape | Contract | — | Spring Cloud Contract / Pact | cross-boundary agreement (`microservice-testing.md`) — not E2E |
+
+## Quadrants (`testing-quadrants.md`)
+
+Q1 strong ✓ · Q2 add a BDD acceptance example for "no overdraft" before coding · Q3 N/A (no UI) · **Q4** → security-review the auth on `/transfers`; load-test if it's a hot path.
+
+## Techniques (`testing-techniques/`, on match)
+
+Money math invariants (sum preserved across a transfer) → **property-based**. Resilience claim "degrades if the broker is down" → **chaos**.
+
+## Notes
+
+Keep the overdraft rule a **unit** test, not a MockMvc test — driving the HTTP layer to assert a calculation is the "testing through the UI for logic" anti-pattern. Cross-service agreement is a **contract** test, not a multi-service E2E (don't depend on provider cooperation — see `cd-test-architecture.md`).

package/knowledge/test-matrix-examples/ssr-htmx.md

@@ -0,0 +1,24 @@
+# Worked example — SSR + HTMX dynamic swap
+
+Few-shot template for `test-design-advisor`. Adapt the rows. Feature: **clicking "Add to cart" sends an HTMX `POST`, the server mutates the cart and returns an HTML fragment that swaps the cart badge**. The client-side swap seam is the point of risk → **Gate C fires** (`test-layer-gates.md`).
+
+## Pyramid placement (advisor output shape)
+
+| Behavior | Layer | Gate | Tool (`test-stack-profiles/ssr-htmx`) | Why |
+|----------|-------|------|---------------------------------------|-----|
+| Cart total recomputed after add | Unit | — | server-side unit (`django`/`node`) | pure logic |
+| `POST /cart` mutates state + renders the fragment | Integration | — | TestClient / supertest | handler + template render + persistence |
+| Returned fragment carries the right `hx-target`/`hx-swap` | Component | — | JSDOM + parse the HTML (`ssr-htmx`) | template/wiring assertions, no browser |
+| Badge actually updates in the page after the swap | **Browser (REQUIRED)** | ↑E2E (Gate C) | Playwright | the swap seam — `hx-target`, stale swap, re-init — gets **zero** coverage from integration |
+
+## Quadrants (`testing-quadrants.md`)
+
+Q1/Q2 ✓ · Q3 → exploratory pass on rapid double-clicks and back-button state · Q4 → none unless the endpoint is hot.
+
+## Techniques (`testing-techniques/`, on match)
+
+If the swapped fragment's visual layout matters (a styled receipt) → **screenshot**; if it's text/markup correctness → **approval** on the rendered fragment.
+
+## Notes
+
+Gate C marks the browser test **required, not recommended** — integration verifies the server returns *a* fragment, never that the client wired it into the DOM correctly. The advisor flags the E2E requirement and defers harness/pipeline design to `cd-test-architecture`; it does not design the Playwright setup here.

package/knowledge/test-organization.md

@@ -0,0 +1,70 @@
+# Test Organization
+
+Reference file for `test-review`, `test-smell-review`, and the `test-design-advisor` skill. This file covers how a single test and a whole suite are *structured* — the Four-Phase Test that every test follows, how test classes are grouped, how shared logic is reused, and how the runner finds tests.
+
+Source: Gerard Meszaros, *xUnit Test Patterns* (xunitpatterns.com) — Test Organization patterns + XUnit Basics. Language- and framework-agnostic — described by role, not any runner's API.
+
+Core principle: **make the structure of every test obvious** — its four phases, its place in a cohesive class, and its name — so the suite reads as documentation.
+
+---
+
+## The Four-Phase Test (the anchor)
+
+Every test follows four phases, visibly separated:
+
+1. **Setup** — establish the fixture (→ `fixture-construction.md`).
+2. **Exercise** — invoke the SUT.
+3. **Verify** — assert the outcome (→ `result-verification.md`).
+4. **Teardown** — release what Setup created (→ `fixture-construction.md`).
+
+When setup, exercise, and assertions are interleaved with no visible phases, that is the **Obscure Test** smell — restructure into four phases first.
+
+---
+
+## Testcase Class grouping
+
+| Grouping | One class per… | Use when | Trade-off |
+|---|---|---|---|
+| **Testcase Class per Class** | production class | default, simple SUTs | can bloat as the SUT grows behaviors |
+| **Testcase Class per Feature** | feature/behavior across classes | a feature spans several production classes | needs a clear feature boundary |
+| **Testcase Class per Fixture** | shared setup | one class's methods need *different* setups | more classes, but each has one cohesive fixture (kills General Fixture) |
+
+Split into **Testcase Class per Fixture** when a single class's methods diverge in what they set up.
+
+---
+
+## Sharing logic: composition over inheritance
+
+| Mechanism | What it is | Use when |
+|---|---|---|
+| **Test Utility Method / Test Helper** | Shared arrange/assert logic as called methods (composition) | **Default** for any shared logic — explicit, low-coupling |
+| **Testcase Superclass** | A base test class supplying shared setup/utilities via inheritance | Only for genuinely *universal* setup across many classes; couples every subclass to it |
+
+Prefer a Test Utility Method / Helper; escalate to a Testcase Superclass only for truly universal setup, and note its coupling cost.
+
+---
+
+## Parameterized Test
+
+When several test methods differ only by input/expected **data**, collapse them into a **Parameterized Test** — one test logic over many data rows. This is the in-code counterpart of the **Data-Driven Test** automation strategy in `test-strategy.md`; use it when the variation is purely data, not when cases differ in logic.
+
+---
+
+## Test Discovery / Enumeration / Selection + naming
+
+The runner finds tests by **Test Discovery** (convention/annotation), builds a **Test Enumeration**, and runs a selected subset. Two consequences for design:
+
+- Give each test an **intent-revealing name** stating the scenario and expected outcome — the name is the first line of documentation a failure shows.
+- Keep tests selectable (tags/categories) so fast and slow suites can be run separately.
+
+**Decision flow:** make the four phases visible → group classes per fixture when setups diverge → share via a Test Utility Method, escalating to a Testcase Superclass only for universal setup → collapse data-only duplication into a Parameterized Test → name every test for its scenario.
+
+---
+
+## How this connects to the rest of the toolkit
+
+- **`fixture-construction.md`** — the Setup/Teardown phases.
+- **`result-verification.md`** — the Verify phase.
+- **`test-strategy.md`** — Parameterized Test ↔ Data-Driven Test.
+- **`test-smells.md`** — the smells these fix: Obscure Test, Test Code Duplication, High Test Maintenance Cost.
+- **`test-refactoring.md`** — the moves that get an existing suite here: Extract Testcase Class per Fixture, Extract Test Utility Method, Introduce Parameterized Test, Split Test.

package/knowledge/test-pyramid.md

@@ -0,0 +1,84 @@
+# The Test Pyramid
+
+Reference file for `test-review`, `test-smell-review`, and the `test-design-advisor` skill. The test pyramid is a heuristic for *where* a given check belongs: many fast, isolated tests at the base; progressively fewer, slower, broader tests toward the top.
+
+Source: Martin Fowler, "The Practical Test Pyramid" (martinfowler.com/articles/practical-test-pyramid.html), building on Mike Cohn's original. Language- and stack-agnostic.
+
+Core principle: **push each check to the lowest layer that can meaningfully verify it.** A bug catchable by a unit test should be caught by a unit test — it's faster, more precise, and more stable there. Reserve higher layers for what genuinely needs integration.
+
+---
+
+## The Layers
+
+| Layer | Scope | Speed | Doubles | What it proves |
+|-------|-------|-------|---------|----------------|
+| **Unit** | One unit (class/function/module) in isolation | ms | Real collaborators by default; doubles only per a named blocker | Logic, branches, edge cases of that unit |
+| **Integration** | The unit + one real external it talks to (DB, queue, HTTP client, filesystem) | 10s–100s ms | Real adapter, often a test container | The adapter/serialization/wiring actually works |
+| **Component / Service** | One deployable service in isolation, internals real, *its* externals stubbed | 100s ms–s | Stub the service's own external deps | The service satisfies its own contract end to end, in-process |
+| **Contract** | The agreement between a consumer and a provider | fast | n/a (verifies a pact) | Two services still agree on the interface (see `microservice-testing.md`) |
+| **End-to-End** | The whole system through real entry points (UI/API) | s–min | none (real everything) | Critical user journeys work when wired together |
+
+"Unit" can be **solitary** (all collaborators doubled) or **sociable** (real collaborators used, only true boundaries doubled). **Sociable is the default** — a first-party collaborator stays real; solitary is permitted only where every double names a blocker (B1 out-of-process handle, B2 ambient state, B3 prohibitive real cost). See `internal-collaborator-doubling.md` for the full rule, the blocker table, and the waiver contract.
+
+---
+
+## Layer-Selection Heuristics
+
+Ask, for each thing you want to verify:
+
+1. **Is it pure logic / a branch / an edge case?** → Unit. Always.
+2. **Does it depend on real serialization, SQL, or a third-party client behaving a certain way?** → Integration (test the adapter, not the logic around it).
+3. **Does it cross a service boundary you don't own?** → Contract test, not E2E.
+4. **Is it a business-critical journey a user actually performs?** → one E2E test. Not every permutation — just the journey.
+
+If a check could live at two layers, choose the **lower** one. Duplicating the same assertion at a higher layer is redundant coverage (a project smell — see `test-smells.md`).
+
+---
+
+## Anti-Patterns
+
+| Anti-pattern | Shape | Symptom | Fix |
+|--------------|-------|---------|-----|
+| **Ice-cream cone** | Inverted pyramid — mostly E2E/manual, few unit | Slow suite, flaky CI, slow feedback, hard failure triage | Push logic checks down to unit; keep E2E for journeys only |
+| **Hourglass** | Many unit + many E2E, no integration middle | Wiring/serialization bugs slip the gap between layers | Add integration tests for adapters and boundaries |
+| **Cupcake** | Same scenarios re-tested at every layer | Maintenance multiplied; one behavior change breaks N tests | De-duplicate; each behavior verified at exactly one layer |
+| **Testing through the UI for logic** | Driving a browser to check a calculation | Slow, fragile, obscures the real assertion | Unit-test the calculation; UI test only the rendering/journey |
+
+---
+
+## Other shapes (a strategy lens)
+
+The pyramid is the default, but the *right silhouette follows the architecture*. Two shapes are legitimate, not anti-patterns, when the architecture earns them:
+
+| Shape | Silhouette | Fits when | Source |
+|-------|-----------|-----------|--------|
+| **Pyramid** | wide unit base, narrow E2E top | logic-heavy code with real internal seams | Cohn / Fowler |
+| **Testing trophy** | small unit, **fat integration middle**, some E2E, static analysis as the base | thin-logic apps where most risk is in wiring/serialization (typical UI + API glue) | Kent C. Dodds |
+| **Diamond** | thin unit, **bulging integration/component**, thin E2E | services that are mostly orchestration/adapters over little domain logic | — |
+
+Same rule still governs: **push each check to the lowest layer that can verify it.** The trophy and diamond are wide in the middle because *that is where the behavior lives* in those architectures — not as a license to skip unit tests for real logic.
+
+### Shape ↔ architecture fit
+
+| If the codebase is… | Expected shape | A different shape signals |
+|---------------------|----------------|---------------------------|
+| Rich domain / business logic | pyramid | inverted → logic untested at unit level |
+| Thin glue over frameworks/APIs | trophy | tall pyramid → unit tests asserting framework behavior (low value) |
+| Orchestration / adapter-heavy service | diamond | wide unit base → over-mocked tests proving little |
+| Static site / content | flat (a11y + link/build checks) | any tall shape → testing the framework |
+
+Diagnose by comparing the suite's actual shape to the shape its architecture *should* produce. A mismatch — not the silhouette alone — is the finding.
+
+---
+
+## How to use this during review
+
+- A unit-level test doing **real I/O** (DB, network, disk, sleep) is mis-layered → flag as **Slow Tests** smell; move the I/O to an integration test and double the boundary at unit level.
+- An **E2E test asserting a single edge case** (e.g., validation of one field) → flag as mis-layered; that's a unit concern.
+- A suite that is **all E2E with little/no unit coverage** → flag the ice-cream-cone shape at the suite level.
+- Before flagging "wrong level," confirm the *intended* level of the file (path, naming, framework markers). Integration/E2E tests are *supposed* to touch real resources — don't flag them as slow or non-deterministic for doing their job.
+
+## Boundaries
+
+- The pyramid is a heuristic, not a quota. Don't invent a numeric ratio and flag suites for missing it. Flag *shape pathologies* (inverted, gap in the middle, pervasive duplication), not arithmetic.
+- Some domains legitimately carry more integration/E2E weight (thin-logic integration glue, data pipelines). Judge by "is this check at the lowest layer that can verify it," not by silhouette alone.

package/knowledge/test-refactoring.md

@@ -0,0 +1,67 @@
+# Test Refactoring & Automation Principles
+
+Reference file for `test-review`, `test-smell-review`, and the `test-design-advisor` skill. The capstone of the testing-knowledge set: the **goals & principles** define what a good automated test *is* (the criteria); the **refactoring catalog** lists the behavior-preserving moves that get an existing test there. Together they connect a named smell (`test-smells.md`) to the target pattern in the sibling files and back.
+
+Source: Gerard Meszaros, *xUnit Test Patterns* (xunitpatterns.com) — Goals of Test Automation, Principles of Test Automation, and the Test Refactorings catalog. Language- and framework-agnostic — described by role, not any library's API.
+
+---
+
+## 1. Goals & Principles (the criteria a refactoring moves toward)
+
+**Goals — a good automated test is:**
+
+- **Documentation / specification** — reads as an example of how the SUT is meant to behave.
+- **Self-checking** — passes or fails on its own; no human reads output to judge it.
+- **Repeatable** — same result every run, any order, any machine.
+- **Robust** — breaks only when the behavior it checks changes (not on unrelated edits).
+- **Isolated / independent** — does not depend on other tests or leak state to them.
+- **Economical** — fast, and cheap to write and maintain.
+
+**Principles — how to get there:**
+
+- Write tests first (drive the design); design for testability.
+- Communicate intent (intent-revealing names, Custom Assertions).
+- Verify **one condition per test**; minimize test overlap.
+- Keep tests **independent**; keep **no logic in tests** (no conditionals/loops around assertions).
+
+A test that violates a goal has a smell; the refactoring below moves it back toward the goal.
+
+---
+
+## 2. Test Refactoring catalog (the behavior-preserving moves)
+
+Each move removes a named smell (`test-smells.md`) and targets a pattern in a sibling file:
+
+| Refactoring | Removes smell | Toward (target file) |
+|---|---|---|
+| **Inline Mystery Guest** → build data locally via a Creation Method / Fresh Fixture | Mystery Guest | `fixture-construction.md` |
+| **Replace General Fixture with Minimal Fixture** | General Fixture, Irrelevant Information | `fixture-construction.md` |
+| **Extract Creation Method / Introduce Test Data Builder** | Test Code Duplication (setup) | `fixture-construction.md` |
+| **Replace Inline Setup with Implicit / Delegated Setup** | Test Code Duplication (setup) | `fixture-construction.md` |
+| **Introduce Expected Object** | Assertion Roulette | `result-verification.md` |
+| **Extract Custom Assertion / Verification Method** | Test Code Duplication (verify), poor diagnostics | `result-verification.md` |
+| **Add Guard Assertion** | misleading/cryptic failure | `result-verification.md` |
+| **Split Test** (one logical condition per test) | Eager Test | `test-organization.md` |
+| **Extract Testcase Class per Fixture** | General Fixture, Obscure Test | `test-organization.md` |
+| **Extract Test Utility Method / Testcase Superclass** | Test Code Duplication, High Test Maintenance Cost | `test-organization.md` |
+| **Introduce Parameterized Test** | data-only duplication | `test-organization.md` |
+
+---
+
+## Decision flow
+
+1. Identify the smell (`test-smells.md`).
+2. Name the violated goal/principle (self-checking? isolated? one condition? intent-revealing?).
+3. Pick the refactoring above that moves the test toward it.
+4. Apply **under green** — and **characterization-first**: if the test (or the code it covers) lacks coverage of current behavior, pin that behavior before any move (`testability-patterns.md`, `legacy-code`).
+
+These are **test-side** refactorings. When the blocker is *production* code that can't be tested at all, use the production seams in `testability-patterns.md` instead — never a test workaround (reflection, `InternalsVisibleTo`, mocking concretes).
+
+---
+
+## How this connects to the rest of the toolkit
+
+- **`test-smells.md`** — the smells each refactoring removes.
+- **`fixture-construction.md`** / **`result-verification.md`** / **`test-organization.md`** — the target patterns the moves head toward.
+- **`test-strategy.md`** — the lifecycle/automation choices the refactored test should land on.
+- **`testability-patterns.md`** / **`legacy-code`** — production seams + characterization-first when the target is untested.

package/knowledge/test-review-division-of-labor.md

@@ -0,0 +1,85 @@
+# Test Review — Division of Labor
+
+`test-review` and `test-smell-review` run over the same test files and can
+detect several of the same signals under different names. This file is the
+single source of truth for **how the two agents divide the work**, so the rule
+lives in one place instead of being restated in both agents and in
+`/test-design`.
+
+## The two roles
+
+- **`test-review`** owns the **tactical per-file gate**: an assertion is missing
+  entirely, an `await` is missing, a mock is not reset, a coverage path (edge /
+  error / happy) is untested, or production code is untestable (static factory,
+  singleton, no injectable constructor → recommend the seam, never a test
+  workaround).
+- **`test-smell-review`** owns the **named design smell** and its remedy: it
+  names the xUnit smell, judges test-double choice, and checks pyramid-layer
+  placement, citing the remedy pattern (`fixture-construction.md`,
+  `result-verification.md`, `test-organization.md`, `test-refactoring.md`).
+
+## Shared signals — who reports when both run
+
+Several signals are detectable by both agents. **When both run** (e.g. under
+`/test-design`), the owner below reports it and the other agent stays silent on
+it; the design-level framing wins. When an agent runs **solo**, it reports the
+signal itself.
+
+| Shared signal | Reported by (when both run) | Framing |
+|---|---|---|
+| Non-determinism (clock / RNG / sleep / real-I/O timing) | **test-smell-review** | the **Erratic Test** smell, with root cause |
+| Weak / no-message assertions | **test-smell-review** | **Assertion Roulette** → `result-verification.md` |
+| Copy-pasted arrange/assert blocks | **test-smell-review** | **Test Code Duplication** → builder / custom assertion |
+| Magic literals in assertions | **test-smell-review** | **Hard-Coded / Magic Values** |
+| Mocking concrete classes; wrong double choice | **test-smell-review** | test-double misuse |
+| Unit test doing real I/O; wrong pyramid layer | **test-smell-review** | **Slow Tests** / pyramid placement |
+| Missing assertion entirely; missing `await`; mock-reset hygiene | **test-review** | tactical mechanical gate |
+| Testability blocker (static factory, singleton, no injectable ctor) | **test-review** | flag the blocker; recommend the production-code seam |
+| Internal-collaborator double with no waiver, or a malformed/invalid-blocker waiver | **test-review**, always — never deferred, even when test-smell-review also runs | mechanical gate, same as the row above |
+| An already-waived double's blocker-claim truth, and (B1) owned-adapter-vs-leaf placement | **test-smell-review**, always — only ever applies to a waived (non-`high`-verdict) double, so it never overlaps the row above on the same instance | design-level judgment, cites `internal-collaborator-doubling.md` |
+
+The last two rows partition the detector's verdict space (`high` vs. an
+already-waived, non-`high` verdict) rather than deferring within a shared
+verdict the way every other row above does — the two can never fire on the
+same instance, so there is no dedup decision to make between them.
+
+## The rule in one line
+
+When both agents run, `test-smell-review` defers the pure mechanics (missing
+assertion, missing `await`, mock-reset) to `test-review`, and `test-review`
+defers the named-smell signals above to `test-smell-review`. `/test-design`
+drops any duplicate that slips through, keeping the design-level framing.
+
+## test-smell-review ↔ test-design-advisor — remedy division
+
+`test-smell-review` and `test-design-advisor` both draw remedy guidance from the
+same knowledge set (`fixture-construction.md`, `result-verification.md`,
+`test-organization.md`, `test-refactoring.md`). Rather than de-duplicate remedy
+prose at report time, the two components divide the row structurally.
+`test-smell-review` names the **smell + its remedy family** (the knowledge-file
+cite); `test-design-advisor` names the **specific remedy pattern** and its
+refactor sequence. `/test-design` joins the two on `remedyFamily` — no prose
+matching, no silent drops.
+
+| Column | Owner | Content |
+|---|---|---|
+| Smell name + location | test-smell-review | e.g. "Assertion Roulette at foo_test.js:42" |
+| Severity + confidence | test-smell-review | `error` / `warning` / `suggestion`; `high` / `medium` / `none` |
+| Remedy family (knowledge file) | test-smell-review | one of `fixture-construction`, `result-verification`, `test-organization`, `test-refactoring`, or `null` when no family applies |
+| Specific remedy pattern | test-design-advisor | e.g. "Expected Object", "Custom Assertion", "Creation Method", "Delta Assertion" |
+| Refactor sequence (behavior-preserving) | test-design-advisor | ordered steps from `test-refactoring.md` |
+| Forward-design placement (pyramid, doubles) | test-design-advisor | table row from `test-pyramid.md` / `test-doubles.md` |
+
+**Invocation rule.** When both components run together under `/test-design`,
+the advisor owns the remedy-pattern columns and `test-smell-review` cites the
+family only — the advisor's per-behavior recommendation is the specific fix.
+When `test-smell-review` runs solo (e.g. under `/code-review`, where the
+advisor is not dispatched), it fills the whole row: `suggestedFix` still names
+a specific pattern from the family (not just the family slug), so no downstream
+consumer is blocked on the advisor.
+
+**Grader alignment.** The eval grader (`scripts/eval_graders/verdict.py:40`)
+scans `issue.message` + `summary` prose for `mustMention` keywords. It does
+not read `remedyFamily` structurally. So `test-smell-review` also emits the
+family slug verbatim in the finding's `message` — this makes the family cite
+enforceable by existing fixtures without extending the grader.

package/knowledge/test-smells.md

@@ -0,0 +1,80 @@
+# Test Smells
+
+Reference file for `test-smell-review` and `test-review` agents. A test smell is a symptom in test code that signals a design problem in the test or in the code under test. Each smell below gives a **detection signal** (what to grep/read for), **why it hurts**, and the **fix** — which is sometimes a test change and sometimes a production-code change.
+
+Source taxonomy: Gerard Meszaros, *xUnit Test Patterns* (xunitpatterns.com). Language-agnostic — signals are described by behavior, not syntax.
+
+Core principle: a test smell is never fixed by suppressing the test. If a test is hard to write, hard to read, or flaky, the test is reporting a real design problem. Fix the cause.
+
+---
+
+## Smell Categories
+
+xUnit Test Patterns groups smells into three levels. Detect at all three:
+
+- **Code smells** — visible in a single test method (readability, assertions).
+- **Behavior smells** — visible only when tests run (flakiness, fragility, slowness).
+- **Project smells** — visible across the suite over time (manual intervention, production bugs slipping through).
+
+---
+
+## Code Smells (single test, readable now)
+
+| Smell | Detection signal | Why it hurts | Fix |
+|-------|-----------------|--------------|-----|
+| **Obscure Test** | Reader cannot tell what behavior is verified without running it; setup buried in `beforeEach`, helpers, or shared fixtures far from the assertion | Test stops being executable documentation; maintenance becomes guesswork | Inline the relevant setup; name intent; one clear arrange-act-assert. Sub-types below. |
+| → Eager Test | One test method exercises many behaviors / many asserts on unrelated outcomes | A failure doesn't pinpoint which behavior broke | Split into one behavior per test |
+| → Mystery Guest | Test depends on external data it doesn't create (a file on disk, a seeded DB row, a fixture in another module) | Reader can't see the inputs; data drift breaks the test silently | Create the data in-test (Fresh Fixture) or via a Test Data Builder |
+| → General Fixture | A shared setup builds far more than this test needs | Reader can't tell which parts matter; coupling across tests | Build only what each test uses (Minimal Fixture) |
+| → Irrelevant Information | Setup exposes values that don't affect the assertion | Noise hides the cause-effect the test proves | Hide irrelevants behind builders with sensible defaults |
+| **Assertion Roulette** | Multiple bare assertions with no messages; on failure you can't tell which line failed | Failure triage requires a debugger | Give assertions descriptive messages, or split tests; use single-behavior assertions |
+| **Conditional Test Logic** | `if`/`switch`/loops/try-catch around assertions; test takes different paths | Some assertions may never run; the test verifies different things on different runs | Remove branching; use parameterized tests or separate cases; assert unconditionally |
+| **Hard-Coded / Magic Values** | Unexplained literals in assertions (`expect(x).toBe(42)`) | Reader can't tell why 42 is correct; fragile to legitimate change | Name the constant for its meaning, or derive it visibly from inputs |
+| **Test Code Duplication** | Copy-pasted arrange or assert blocks across tests | A behavior change forces edits in N places; drift | Extract Creation/Custom Assertion methods or a Test Data Builder |
+| **Test Logic in Production** | Production code contains `if (testMode)`, test-only hooks, or back doors | Tested code path ≠ shipped code path; false confidence | Remove; achieve control via dependency injection / seams (see `testability-patterns.md`) |
+
+---
+
+## Behavior Smells (only visible when tests run)
+
+| Smell | Detection signal | Why it hurts | Fix |
+|-------|-----------------|--------------|-----|
+| **Erratic Test** (flaky) | Passes/fails non-deterministically across runs | Destroys trust in the suite; teams start ignoring red | Eliminate the non-determinism source — see sub-types |
+| → Interacting Tests | Test passes alone, fails in suite (or vice versa); order-dependent | Shared mutable state between tests | Fresh Fixture per test; no shared writable state |
+| → Test Run War | Intermittent failures only when suite runs concurrently / on CI | Tests share an external resource (same DB, same file, same port) | Isolate resources per test run (unique schema, temp dir, ephemeral port) |
+| → Nondeterministic timing | `Date.now()`/`now()`, `Math.random()`/`Random`, `sleep`, real timers in assertions | Clock/RNG/scheduler drift | Inject a clock/RNG; use fake timers; never `sleep` to await |
+| → Resource Leakage / Optimism | Test assumes a resource exists or is clean; leaves state behind | Cascading failures, slow degradation | Set up and tear down own resources; assert preconditions |
+| **Fragile Test** | A change unrelated to the behavior under test breaks the test | Maintenance tax; discourages refactoring | Test through stable public behavior, not internals — see sub-types |
+| → Interface Sensitivity | Renaming/reshaping an API breaks many tests | Tests bound to signatures, not behavior | Centralize creation/interaction in helpers (one place to update) |
+| → Behavior Sensitivity | Changing unrelated behavior breaks the test | Over-specified expectations | Assert only what this behavior guarantees |
+| → Overspecified Software (mock-heavy) | Test asserts exact internal call sequences via mocks | Tests the implementation, not the outcome | Prefer state verification; mock only true boundaries (see `test-doubles.md`) |
+| → Context/Data Sensitivity | Breaks when run in a different timezone, locale, or with different seed data | Hidden environmental coupling | Pin locale/timezone; control all inputs explicitly |
+| **Slow Tests** | Unit-level tests taking seconds; real I/O (DB, network, disk) in unit tests | Feedback loop collapses; tests get skipped | Replace boundaries with doubles; push slow checks down the pyramid (see `test-pyramid.md`) |
+| **Frequent Debugging** | Most test *failures* need an interactive debugger or print statements to locate the cause; failure messages don't tell you what broke | The suite has lost Defect Localization — a red bar that doesn't point at the defect is barely better than no test | Add the missing fine-grained unit/component tests; improve Assertion Messages; run tests after every small change so you remember what you touched (see `test-automation-principles.md` → Defect Localization) |
+
+---
+
+## Project Smells (visible across the suite over time)
+
+| Smell | Detection signal | Why it hurts | Fix |
+|-------|-----------------|--------------|-----|
+| **Production Bugs** | Defects reach prod despite a green suite | Tests verify the wrong things, or coverage gaps | Add tests at the level the bug lived (often a missing unit/contract test) |
+| **High Test Maintenance Cost** | Every feature change forces large test rewrites | Accumulated Fragile/Obscure smells | Address the underlying code & behavior smells; introduce builders & custom assertions |
+| **Manual Intervention** | A human must edit config, seed data, or run a step for tests to pass | Tests aren't repeatable or CI-able | Automate setup; make the suite hermetic |
+| **Buggy Tests** | Tests pass when the code is broken (or fail when it's correct) | Negative confidence — worse than no test | Verify the test fails for the right reason (mutation testing surfaces these — see `mutation-testing` skill) |
+| **Developers Not Writing Tests** | Code lands without tests; test count flat or falling while code grows; "no time to test" | The safety net never forms; the rest of the suite's value erodes as untested code accumulates | Address the *root cause*, not the symptom: schedule pressure (make testing part of "done"), missing skills (coach/pair), or Hard-to-Test Code (fix testability — `testability-patterns.md`). Often paired with Lost Tests (tests silently disabled) |
+
+---
+
+## Detection Workflow
+
+1. **Read each test method** for code smells — can you state the behavior under test in one sentence from the test alone? If not → Obscure Test.
+2. **Scan for behavior-smell signals** — clock/RNG/sleep/real-I/O, shared mutable state, exact-call-sequence mock assertions.
+3. **Scan the suite shape** for project smells — heavy `beforeAll` shared state, manual setup steps, fixtures referenced but not created in-test.
+4. For each finding, decide: **test fix** (rename, split, add message, build fresh fixture) or **production fix** (introduce a seam — defer to `testability-patterns.md`).
+
+## Boundaries
+
+- A single behavior asserted with several related assertions on one object is **not** Eager Test or Assertion Roulette — that's normal.
+- Integration/E2E tests are *expected* to touch real resources; "Slow Tests" applies when that work happens at the **unit** level. Confirm the intended test level before flagging (see `test-pyramid.md`).
+- Do not flag duplication between two tests that assert genuinely different boundary conditions — that's coverage, not Test Code Duplication.