@brunosps00/dev-workflow 0.13.0 → 0.15.0

package/scaffold/skills/dw-testing-discipline/SKILL.md

@@ -1,97 +1,126 @@
 ---
 name: dw-testing-discipline
-description: Use when authoring, reviewing, or debugging tests — enforces Six Iron Laws (behavior over mocks, push to lowest layer, fix prod first on red, real systems gate merge), 25 anti-patterns, 7 AI agent gates, and flaky-test discipline so tests reveal bugs instead of decorating CI.
+description: Use when authoring, reviewing, or debugging tests — enforces six core rules (assert behavior, push to lowest layer, fix prod first on red, real systems gate merge, mutation > coverage, no test backdoors), a catalog of anti-patterns, agent-authoring guardrails, and flaky-test discipline so tests reveal bugs instead of decorating CI.
 ---
 
 # Testing Discipline
 
-> **Inspired by** [`pedronauck/skills/testing-boss`](https://github.com/pedronauck/skills/tree/main/skills/mine/testing-boss) (MIT). Six Iron Laws, positive/anti-pattern catalogs, AI agent gates, and flaky-test taxonomy adapted from Pedro Nauck's work. The browser security-boundary and three-workflow-patterns references additionally cite [`addyosmani/agent-skills/browser-devtools`](https://github.com/addyosmani/agent-skills) (MIT), and Playwright recipes carry over from earlier dev-workflow work.
-
-## Cardinal Premise
+## Founding principle
 
 > Tests exist to expose defects, not to keep CI green.
 > A test that fails has done its job.
 > A test that passes for the wrong reason is worse than no test.
 
-## Six Iron Laws
+Everything else in this skill follows from that.
+
+## The six core rules
 
 ```
 1. Test the behavior, never the mock.
-2. Push every test to the lowest layer that can detect the failure.
-3. When a test fails, fix production first — change the test only after writing why.
+2. Push each test to the lowest layer that can detect the defect.
+3. When a test fails, read production first — change the test only with documented justification.
 4. Real systems gate the merge. Mocks isolate; they do not validate.
-5. Coverage is a flashlight. Mutation score is a quality probe. Neither is a target.
+5. Coverage is a flashlight; mutation score is a quality probe. Neither is a target.
 6. No test-only methods, branches, or flags leak into production code.
 ```
 
-Each law has nuance — read `references/iron-laws.md` for the full version with examples.
+Each rule has nuance read `references/core-rules.md` for the long version with examples.
+
+## When to use
 
-## Required Reading Router
+- Authoring any test (unit, integration, contract, E2E).
+- Reviewing a PR diff under test paths.
+- Debugging a flaky test (or considering retry-as-fix — read `references/flaky-discipline.md` first).
+- Generating tests via an AI agent → invokes `references/agent-guardrails.md` automatically.
+- Browser-based E2E with Playwright → recipes in `references/playwright-recipes.md`.
+- Verifying browser-side trust boundaries (auth, CSRF, headers) → `references/security-boundary.md`.
+- Picking which test workflow applies (UI / network / perf) → `references/three-workflow-patterns.md`.
 
-| Task | MUST read |
-|------|-----------|
-| Deciding where a test belongs | `references/iron-laws.md` (Law 2 deep-dive) |
-| Writing new tests | `references/positive-patterns.md` |
-| Reviewing / debugging tests | `references/anti-patterns.md` |
-| Test authored by an AI agent | `references/ai-agent-gates.md` + `references/anti-patterns.md` |
-| Flaky tests appeared | `references/flaky-discipline.md` |
-| Browser-based E2E with Playwright | `references/playwright-recipes.md` |
-| Browser security boundary testing | `references/security-boundary.md` |
-| Picking the right test workflow (UI vs network vs perf) | `references/three-workflow-patterns.md` |
+## Reference router
 
-## Twelve positive patterns (one-liners, full version in references/positive-patterns.md)
+| Doing what | Read |
+|------------|------|
+| Placing a new test (which layer?) | `references/core-rules.md` (Rule 2 deep-dive) |
+| Writing new tests | `references/patterns.md` |
+| Reviewing tests / spotting smells | `references/anti-patterns.md` |
+| Agent-generated tests | `references/agent-guardrails.md` + `references/anti-patterns.md` |
+| Flaky tests | `references/flaky-discipline.md` |
+| Playwright E2E | `references/playwright-recipes.md` |
+| Browser trust boundary | `references/security-boundary.md` |
+| Picking the right workflow | `references/three-workflow-patterns.md` |
+
+## Patterns that produce reliable tests (one-liners; full in `references/patterns.md`)
 
 1. Query by behavior and accessible role; never CSS selectors or DOM indices.
-2. Selector hierarchy: role → label → text → test-id → structural (stop at highest rung that disambiguates).
+2. Selector ladder: role → label → text → test-id → structural. Stop at the highest rung that disambiguates.
 3. Wait on observable conditions; never wall-clock sleeps.
-4. Each test independent and order-free; setup over teardown.
-5. One behavior per test; as many assertions as that behavior needs.
-6. Names read like specifications: `should <outcome> when <condition> given <state>`.
+4. Each test independent and order-free; lean on `beforeEach`, not `beforeAll`.
+5. One behavior per test; as many assertions as that behavior requires.
+6. Names read as specifications: `should <outcome> when <condition> given <state>`.
 7. Table-driven / parameterized when inputs vary.
 8. Build test data via factories; literal blobs only for fields under test.
-9. Mock at boundaries you don't control; real wiring for owned systems.
-10. Real systems gate final merge; contract tests bridge unit and E2E.
+9. Mock at boundaries you don't control; real wiring for the systems you own.
+10. Real systems gate the final merge; contract tests bridge unit and E2E.
 11. Mutation score, not coverage percentage, measures suite strength.
-12. Page Object Model is a tool, not a religion — collapse for small suites.
-
-## Five anti-pattern families (25 total, full catalog in references/anti-patterns.md)
-
-**Brittleness** — tests bound to internals:
-- Implementation-detail selectors, internal-structure assertions, testing private methods, snapshot-as-test, vague existence assertions, action-without-assertion.
-
-**Flakiness** — tests randomizing verdicts:
-- Static sleeps, test order dependency, non-deterministic inputs (clock, RNG, locale).
-
-**Mock misuse** — tests testing the test setup:
-- Asserting the mock exists, mock drift, over-mocking children, incomplete mocks, mocking wrong level.
-
-**Process** — team and suite pathologies:
-- Coverage-as-vanity, happy-path-only, eternal `beforeAll`, cleanup in `afterEach`, magic strings, testing third-party sites, quarantine-as-cemetery, retry-as-fix, duplicate tests across layers, weakening tests to make them pass, mock-driven confidence.
-
-**AI-specific** — agent failure modes:
-- The seven failure modes that gates in `ai-agent-gates.md` block.
-
-## Seven AI agent gates (mandatory when an agent writes tests)
-
-These are mandatory pre-conditions whenever an LLM produces test code. Each gate is a forcing function against a specific LLM tendency:
-
-1. **Invariant first** — agent prints `INVARIANT: …`, `OWNING_LAYER: …`, `EXISTING_SUITE: …` before any code.
-2. **Owning layer** — extend an existing suite; reject new files without a named invariant.
-3. **Real execution** — every test runs against real DB / real route / real external integration at least once before merging.
-4. **Failure → fix production** — on a red test, the next move reads production code, NOT the test. Document the analysis before changing either.
-5. **No snapshot without contract** — classify the artifact as `PRODUCT_CONTRACT` or `IMPLEMENTATION_DETAIL`. The latter forbids snapshots.
-6. **No assertion on self-set mock** — cannot assert on values the same test body wrote into the mock.
-7. **Negative companion** — every positive assertion ships with a negative test for invalid input or failure mode.
-
-Full prompt blocks and verification recipes in `references/ai-agent-gates.md`.
+12. Page Object Model is a tool; collapse it for small suites where it adds noise.
+
+## Anti-pattern catalog (four families, full in `references/anti-patterns.md`)
+
+The four kinds of smell that produce most test debt:
+
+**A. Fragile to refactor** — tests bound to internals, not behavior:
+- Implementation-detail selectors.
+- Asserting internal structure instead of observable outcome.
+- Testing private methods directly.
+- Snapshots replacing real assertions.
+- Vague existence assertions (`toBeTruthy`, `should('exist')`).
+- Actions with no assertion ("clicking save works").
+
+**B. Non-deterministic outcomes** — tests that flip verdict on the same code:
+- Static sleeps / fixed-timeout waits.
+- Test order dependency / hidden shared state.
+- Non-deterministic inputs (clock, RNG, locale).
+
+**C. Mock-driven false confidence** — tests testing the test setup:
+- Asserting the mock exists.
+- Mock drift (mocked response no longer matches real API).
+- Over-mocking child components.
+- Incomplete mocks (missing fields the code reads).
+- Mocking the wrong level (mocking methods of the SUT itself).
+- Asserting on a value the test body fed into a mock.
+
+**D. Suite hygiene problems** — team and suite-level pathologies:
+- Coverage as vanity metric.
+- Happy-path-only coverage.
+- Eternal `beforeAll` hiding dependencies.
+- Cleanup in `afterEach` (move to `beforeEach`).
+- Magic strings and logic in tests.
+- Testing against third-party sites.
+- Quarantine-as-cemetery (skip without owner or deadline).
+- Retry-as-fix (auto-retry hiding real bugs).
+- Duplicate tests across pyramid layers.
+- Weakening assertions to make tests pass.
+
+Total: 25 specific patterns across the four families.
+
+## Agent-authoring guardrails (mandatory when an LLM writes tests)
+
+Six guardrails block the most common failure modes when an LLM produces test code. Each is a pre-condition before the diff goes to review. Full prompts and verification in `references/agent-guardrails.md`:
+
+1. **State the invariant first** — agent prints `INVARIANT`, `OWNING_LAYER`, `EXISTING_SUITE` before writing code.
+2. **Extend, don't sprawl** — agent extends an existing suite; new files require a named invariant.
+3. **Real execution somewhere** — at least one test path runs against real systems before merge.
+4. **Red? Read production** — on failure, the agent reads production code first and prints `ANALYSIS:` before changing tests.
+5. **Classify before snapshot** — snapshots only with explicit `PRODUCT_CONTRACT` classification; `IMPLEMENTATION_DETAIL` forbids them.
+6. **Negative companion** — every positive assertion ships with a negative test for invalid input or failure mode.
 
 ## Placement doctrine (tripwires)
 
 Before writing test code:
 
 - Name the invariant in **one sentence**. Fuzzy language signals unclear requirements — stop and clarify.
-- Place the test at the **lowest layer** capable of detecting the failure when the invariant breaks.
-- Reject tests where `(likelihood × blast-radius)` falls below the ten-minute-maintenance threshold (the test is more expensive to maintain than the bug would be to fix).
+- Place the test at the **lowest layer** capable of detecting the defect when the invariant breaks.
+- Reject tests where (`likelihood-of-bug` × `blast-radius`) falls below a ten-minute-maintenance threshold (the test is more expensive to maintain than the bug would be to fix).
 
 ## Flaky discipline (tripwires)
 
@@ -103,9 +132,9 @@ Full taxonomy in `references/flaky-discipline.md`.
 
 ## Cross-cutting red flags
 
-Any of these in a PR triggers REJECTED in `/dw-code-review`:
+Any of these in a PR is enough to REJECT a verdict:
 
-- Mock setup larger than test logic.
+- Mock setup larger than the test logic.
 - Test breaks when an internal method is renamed (not the public contract).
 - Removing the assertion body leaves the test green.
 - Test fails when run with `.only` in isolation.
@@ -117,9 +146,9 @@ Any of these in a PR triggers REJECTED in `/dw-code-review`:
 - Failing tests auto-retried until green; no investigation.
 - Skipped/quarantined tests without named owner and fix-by date.
 - Test depends on `new Date()`, `Math.random()`, or system locale.
-- `afterEach` resets database (move to `beforeEach`).
-- AI-written test has 6+ assertions and zero edge cases.
-- Phrase "I'll mock this to be safe" appears in the diff.
+- `afterEach` resets database state.
+- Agent-written test has 6+ assertions and zero edge cases.
+- The diff contains the phrase "I'll mock this to be safe."
 
 ## When NOT to use this skill
 
@@ -131,18 +160,12 @@ Any of these in a PR triggers REJECTED in `/dw-code-review`:
 
 ## Integration with dev-workflow commands
 
-- `/dw-create-tasks` uses the placement doctrine — each test-adding task must name the invariant.
-- `/dw-run-task` applies the 7 AI gates when generating tests as part of implementation.
+- `/dw-create-tasks` applies the placement doctrine — each test-adding task names the invariant.
+- `/dw-run-task` runs the 6 agent guardrails when generating tests during implementation.
 - `/dw-code-review` runs the anti-pattern checks on diff hunks under test paths.
-- `/dw-fix-qa` runs flaky-discipline taxonomy when retesting bugs.
+- `/dw-fix-qa` applies the flaky-discipline taxonomy in retest cycles.
 - `/dw-run-qa` (UI mode) references `playwright-recipes.md` for concrete recipes.
 
-## Why this skill exists
-
-The previous bundled skill (`webapp-testing`) mixed Playwright recipes with two discipline references (`security-boundary`, `three-workflow-patterns`) added later. The discipline references were enterred in a tactical skill that the agent didn't reach for as doctrine.
-
-This skill consolidates: doctrine at the top, Playwright recipes as one reference, security and workflow patterns as their own references. One skill, coherent voice, doctrine-first.
-
 ## Bottom line
 
-> A test that cannot fail is decorative. A test that fails for the wrong reason is misleading. Build tests that fail for exactly one reason — the reason the invariant was violated — and trust them when they do. Mocks isolate. Real systems validate. Coverage shines a light. Mutation score grades the suite. Agents will reach for the mock and the snapshot; the gates here make them put both down. Tests reveal bugs, not just pass.
+> A test that cannot fail is decorative. A test that fails for the wrong reason is misleading. Build tests that fail for exactly one reason — the reason the invariant was violated — and trust them when they do. Mocks isolate. Real systems validate. Coverage shines a light. Mutation score grades the suite. Agents will reach for the mock and the snapshot; the guardrails make them put both down. Tests reveal bugs, not just pass.

package/scaffold/skills/dw-testing-discipline/references/agent-guardrails.md

@@ -0,0 +1,170 @@
+# Six guardrails — mandatory when an agent writes tests
+
+LLMs have characteristic failure modes when authoring tests. Six guardrails are forcing functions for the most common ones.
+
+Every test produced by an agent (via `/dw-run-task`, `/dw-bugfix`, `/dw-autopilot`, or any code-generating flow) must clear all six BEFORE the diff goes to review.
+
+## Guardrail 1 — State the invariant, layer, and host suite first
+
+**Failure mode it blocks:** agent writes 200 lines of test code without articulating what the test is supposed to prove or where it belongs.
+
+**What the agent must do:**
+
+Before any test code, print:
+
+```
+INVARIANT: <one sentence — what behavior the test verifies>
+OWNING_LAYER: <unit | integration | contract | e2e>
+EXISTING_SUITE: <path to the existing test file the new test joins, or "NEW: <reason>">
+```
+
+If the agent can't fill any line, it stops and asks the user — it does NOT invent an invariant.
+
+**Why it works:**
+- "Invariant" forces specific behavior naming.
+- "Owning layer" forces Rule 2 (lowest detectable layer).
+- "Existing suite" forces extending coverage rather than spawning orphan files.
+
+**Verification:** `/dw-code-review` looks for this 3-line preamble in the PR description or commit body. Missing = REJECTED.
+
+## Guardrail 2 — Real execution somewhere
+
+**Failure mode it blocks:** agent writes tests that mock everything. They pass green forever and validate nothing.
+
+**What the agent must do:**
+
+At SOME layer, the test path must run against real systems before merge:
+
+- Pure logic: unit only is sufficient.
+- Code touching DB: at least one integration test with real DB (testcontainers, ephemeral container, dedicated test DB).
+- Code calling external services: a contract test OR a sandbox-account smoke test.
+- UI interactions: at least one E2E run on a real preview environment.
+
+**Verification:** PR description lists the real-system runs covering the touched code. If no real-system path covers the change → REJECTED.
+
+## Guardrail 3 — On red, read production first
+
+**Failure mode it blocks:** agent sees a test go red and modifies the test until green. Bug ships.
+
+**What the agent must do:**
+
+When a test fails (its own or pre-existing):
+
+1. Print: `INVESTIGATING FAILURE: <test name>`.
+2. Read production code in the path that produced the observed value.
+3. Print: `ANALYSIS: <2-3 sentences — is production wrong, the test wrong, or has the invariant changed?>`.
+4. Decide:
+   - Production wrong → fix production.
+   - Test wrong → fix the test AND document the change in the commit body.
+   - Invariant changed → update the test AND open an ADR if it's a public-contract change.
+
+**Verification:** every commit changing a previously-green test must have an `ANALYSIS:` line. Missing = REJECTED.
+
+## Guardrail 4 — No self-confirming assertions
+
+**Failure mode it blocks:** two related shortcuts —
+- Agent writes `mockFn.mockReturnValue('X')` then asserts `expect(mockFn()).toBe('X')`. Proves nothing — the test asserts what the test set up.
+- Agent reaches for `toMatchSnapshot()` whenever unsure what to assert. The snapshot becomes the assertion; drift goes unnoticed.
+
+**What the agent must do:**
+
+**For mocks:** never assert on a value the test body fed into a mock. Assert on:
+- The OUTPUT of production code that consumed the mock.
+- The SIDE EFFECTS (DB state, network calls, event emissions) caused by production code.
+- The VISIBLE behavior (UI change, log line, response) the user/caller observes.
+
+**For snapshots:** before adding `toMatchSnapshot()`, classify the artifact:
+- `PRODUCT_CONTRACT` — a stable contract worth pinning (serialized API output, stored-record schema). Snapshot OK; document the classification in a comment.
+- `IMPLEMENTATION_DETAIL` — HTML structure, internal representation, component tree shape. Snapshot is FORBIDDEN; write specific assertions instead.
+
+**Verification:**
+- Mock value flowing directly from setup to assertion without passing through production code → REJECTED.
+- Snapshot in diff without classification comment → REJECTED.
+- Snapshot classified `IMPLEMENTATION_DETAIL` → REJECTED.
+
+## Guardrail 5 — Negative companion
+
+**Failure mode it blocks:** agent writes happy-path-only tests. Edge cases, error paths, boundary inputs uncovered.
+
+**What the agent must do:**
+
+Every positive assertion ships WITH at least one negative companion:
+
+- Asserting `createUser(validInput)` succeeds → also assert `createUser(invalidInput)` fails with a specific error.
+- Asserting `parseDate(validString)` returns a Date → also assert `parseDate(invalidString)` throws or returns null.
+- Asserting `transferFunds(...)` succeeds with sufficient balance → also assert it fails with insufficient balance.
+
+**Verification:** a PR adding N positive assertions to a public path must add ≥1 negative assertion. Imbalance >3:1 (positive:negative) on a public path → REJECTED.
+
+## Guardrail 6 — Don't expand the surface to test it
+
+**Failure mode it blocks:** agent exports internals, adds `*ForTesting` methods, or introduces `process.env.NODE_ENV === 'test'` branches in production code to make the test possible.
+
+**What the agent must do:**
+
+If the test needs access the production API doesn't grant:
+- **Refactor production for testability** via dependency injection or interface seams.
+- **Emit an observable side effect** the test can verify (event, log line, metric) that production also benefits from.
+- **Use a dedicated test environment** with test credentials, not a backdoor flag.
+
+The agent does NOT:
+- Export `_internal` symbols just for tests.
+- Add `// for testing only` methods on classes.
+- Wrap production logic in `if (process.env.NODE_ENV !== 'test')` branches.
+
+**Verification:** diff includes new production exports, env checks, or `*ForTesting`-style symbols → REJECTED. Refactor the surface or change the test approach.
+
+## How the six guardrails compose
+
+A test that passes all six:
+1. States the invariant, layer, and host suite up front (Guardrail 1).
+2. Exercises real systems somewhere in the pipeline (Guardrail 2).
+3. When red, reads production first and documents the analysis (Guardrail 3).
+4. Asserts on production's observable output, not its own setup (Guardrail 4).
+5. Covers failures alongside successes (Guardrail 5).
+6. Lives inside the production API's existing surface (Guardrail 6).
+
+Tests passing all six are worth running. Tests missing any one are more likely to mislead than to help.
+
+## Override procedure
+
+To skip a guardrail explicitly:
+1. State which guardrail is skipped.
+2. State why in one sentence.
+3. Add a `// SKIP-GUARDRAIL-N: <reason>` comment in the test.
+4. Open a follow-up issue tracking the gap.
+
+Without all four, the guardrail is enforced.
+
+## Prompt block injected when an agent writes tests
+
+```
+You are about to write tests. Before producing test code, complete the
+6-guardrail preamble:
+
+INVARIANT: ___
+OWNING_LAYER: ___
+EXISTING_SUITE: ___
+
+If you cannot complete these three lines, STOP and ask the user for
+the requirement. Do not invent an invariant.
+
+Then, while writing tests:
+- Real execution: name the real-system path covering this code.
+- On red: read production first; print ANALYSIS: before changing the test.
+- Mocks: never assert on values fed into a mock.
+- Snapshots: classify PRODUCT_CONTRACT or IMPLEMENTATION_DETAIL — the latter is forbidden.
+- Coverage: every positive assertion needs a negative companion.
+- Production surface: don't export internals or add test-only branches.
+
+Tests violating guardrails without explicit SKIP-GUARDRAIL-N comments
+will be REJECTED at review.
+```
+
+`/dw-run-task` and `/dw-bugfix` inject this prompt block before generating test code.
+
+## Why six and not more
+
+These are the highest-frequency LLM failure modes observed across multiple projects. Other tendencies exist but are either covered by the positive patterns (e.g., wall-clock waits) or are lower-frequency than these six.
+
+If a new failure mode appears that none of the six catches, add a guardrail AND document the failure that motivated it. Don't add guardrails speculatively.

package/scaffold/skills/dw-testing-discipline/references/anti-patterns.md

@@ -1,10 +1,10 @@
-# Anti-patterns — 25 patterns across 5 families
+# Anti-patterns — 25 smells across 4 families
 
-Each anti-pattern names the smell, shows the violation in pseudo-code, gives the fix, and notes how `/dw-code-review` detects it.
+Each anti-pattern names the smell, shows the violation in pseudo-code, gives the fix, and notes how `/dw-code-review` detects it. Agent-specific failure modes are covered separately in `agent-guardrails.md`.
 
 ---
 
-## Family 1: Brittleness (tests bound to internals)
+## Family A: Fragile to refactor (tests bound to internals, not behavior)
 
 ### A1. Implementation-detail selectors
 
@@ -81,7 +81,7 @@ test('clicking save works', async () => {
 
 ---
 
-## Family 2: Flakiness (tests randomizing verdicts)
+## Family B: Non-deterministic outcomes (tests that flip verdict on the same code)
 
 ### A7. Static sleeps / fixed-timeout waits
 
@@ -117,7 +117,7 @@ test('today is Monday', () => {
 
 ---
 
-## Family 3: Mock misuse (tests testing the test setup)
+## Family C: Mock-driven false confidence (tests asserting on their own setup)
 
 ### A10. Asserting the mock exists
 
@@ -181,7 +181,7 @@ You've tested the SCAFFOLD, not the logic.
 
 ---
 
-## Family 4: Process (team and suite pathologies)
+## Family D: Suite hygiene problems (team and suite-level pathologies)
 
 ### A15. Coverage as vanity metric
 

package/scaffold/skills/dw-testing-discipline/references/core-rules.md

@@ -0,0 +1,128 @@
+# Six core rules — expanded with examples
+
+The rules are short for memorization. Each carries nuance that matters in practice.
+
+## Rule 1: Test the behavior, never the mock
+
+**What it means:** the test asserts what the system DOES from the caller's perspective. It does not assert that internal call X was made with internal argument Y.
+
+**Why it matters:** a test bound to internal calls breaks the day you refactor — even when behavior didn't change. The "test is red, behavior is fine" experience erodes trust. Soon no one runs the suite.
+
+**Violation:**
+
+```javascript
+// BAD — asserting on mock internals
+test('createOrder calls inventory.reserve', () => {
+  const inventory = { reserve: vi.fn() };
+  createOrder({ items: [...] }, inventory);
+  expect(inventory.reserve).toHaveBeenCalledWith(items, 'reserve');
+});
+```
+
+You've asserted that `createOrder` USES the inventory adapter a specific way. The refactor that consolidates `reserve` into `commit-with-reservation` breaks this even though the order still gets created.
+
+**Correct version:**
+
+```javascript
+// GOOD — asserting behavior
+test('createOrder reserves inventory before confirming', async () => {
+  const result = await createOrder({ items: [...] });
+  expect(result.status).toBe('confirmed');
+  expect(await getInventoryFor(items[0].sku)).toBe(originalStock - 1);
+});
+```
+
+Now the test cares about the OUTCOME (inventory decremented, order confirmed), not the path.
+
+## Rule 2: Push each test to the lowest layer that can detect the defect
+
+**What it means:** if a unit test can catch the bug, use a unit. If only an integration test can, integration. If only an end-to-end run can, E2E.
+
+**Why it matters:** lower layers run faster, fail more precisely, isolate the cause better. A bug in pure logic caught at unit takes 50ms and points at the exact function. The same bug at E2E takes 30 seconds and tells you "checkout failed."
+
+**The pyramid resolved:**
+
+| Layer | Catches | Speed | Cost |
+|-------|---------|-------|------|
+| Unit | Pure logic, math, parsing, formatters | <100ms | low |
+| Integration | Module composition, DB queries, HTTP handlers | 500ms–5s | medium |
+| Contract | Producer/consumer agreement at API boundary | 1–10s | medium |
+| E2E | User journey across multiple services | 10s–60s | high |
+
+**Rule of thumb:**
+- If you can write a unit test, do so.
+- If unit can't reach it (needs DB, queue, real HTTP), write integration.
+- E2E only for journeys NO lower layer can detect: browser-renders-correctly, third-party-callback-arrives, multi-step session state.
+
+## Rule 3: When a test fails, read production first — change the test only with documented justification
+
+**What it means:** a red test is a signal. The first question is "what's wrong with production?" — not "why is the test wrong?"
+
+**Why it matters:** tests are weakened to pass far more often than they should be. "The behavior is fine; the test is too strict" is the slope that leaves a green suite full of meaningless assertions.
+
+**Process when a test goes red:**
+
+1. **Read the failure message.** What invariant did the test claim? What did it observe?
+2. **Read production code** in the path that produces the observation.
+3. **Decide which is wrong.** If production violates the invariant, fix production. If the test mis-states the invariant, document WHY before relaxing.
+4. **Commit the analysis** in the test's commit message or PR body. "Relaxed assertion from X to Y because `<reason>`" is auditable; "fix test" is not.
+
+**Anti-pattern:** re-run the test until green. Auto-retry on flake. Add `.only` to skip the rest.
+
+## Rule 4: Real systems gate the merge. Mocks isolate; they do not validate.
+
+**What it means:** before code merges to main, at least ONE test path exercised real systems — real DB, real route, real external integration in a sandbox or test account. Mocks are fine for fast unit feedback; they cannot decide "safe to ship."
+
+**Why it matters:** mock drift is real. The mocked HTTP response from 3 months ago no longer matches the actual API. Tests pass; production fails on first real call.
+
+**Practical pattern:**
+
+- Unit tests: mock the world; run on every keystroke / commit.
+- Integration tests: real local DB (testcontainers, in-memory if equivalent); run on every PR.
+- Contract tests: real producer/consumer agreement check; run on every PR.
+- E2E: real preview environment with real services; run on PRs before merge to main.
+
+The discipline: no merge without a green E2E (or equivalent real-system check) for the touched path.
+
+## Rule 5: Coverage is a flashlight; mutation score is a quality probe. Neither is a target.
+
+**What it means:**
+- **Coverage** tells you what lines executed. Useful as a NEGATIVE signal — 30% coverage means lots of dark code. Useless as a positive signal — 95% coverage with weak assertions is decorative.
+- **Mutation score** introduces small bugs (mutations) and measures whether tests catch them. A high mutation score means tests actually probe behavior, not just execute lines.
+- Neither should be a number you optimize for. They're diagnostics.
+
+**Anti-pattern:** "We need 90% coverage to merge." Coverage as a gate produces tests written to pass the gate, not to find bugs.
+
+**Healthier framing:** "What lines in the touched diff are NOT covered? Why?" Sometimes the answer is "we don't care, it's logging." Sometimes it's "actually that's a critical branch — add a test."
+
+## Rule 6: No test-only methods, branches, or flags leak into production code
+
+**What it means:** production code should not have `if (process.env.NODE_ENV === 'test') { ... }` branches, `// for testing only` methods exposed on classes, or internals exported just for assertions.
+
+**Why it matters:** production code carrying test-only logic is test decorations leaking into the artifact users run. Bug surface grows; the test environment diverges from production.
+
+**Correct patterns:**
+
+- Need to inject a dependency for testing? Use constructor injection / dependency injection.
+- Need to assert on internal state? Add a logging hook or event emission that production also benefits from.
+- Need to bypass auth in tests? Use a dedicated test environment with test credentials, not a backdoor flag.
+
+**Tells:**
+- `// only used in tests` comments.
+- `*ForTesting` suffix on methods.
+- `vi.spyOn(module, '_internal')` accessing underscore-prefixed members.
+- `process.env.E2E_MODE` reaching into production runtime decisions.
+
+If you see these, the test design is wrong. Refactor production to be testable; don't add backdoors.
+
+## Putting the rules together
+
+A healthy test:
+1. Asserts behavior visible to a caller (Rule 1).
+2. Sits at the lowest layer that can prove that behavior (Rule 2).
+3. When red, sends you to read production code (Rule 3).
+4. Has a sibling exercising real systems somewhere in the pipeline (Rule 4).
+5. Survives a mutation in the code it claims to cover (Rule 5).
+6. Has zero footprint in production code (Rule 6).
+
+Any test failing ≥2 of these is technical debt accumulating. `/dw-code-review` flags them.

package/scaffold/skills/dw-testing-discipline/references/playwright-recipes.md

@@ -2,7 +2,7 @@
 
 Practical Playwright code for the common scenarios. Use this when `/dw-run-qa` runs in UI mode or when `/dw-functional-doc` needs E2E coverage.
 
-> These recipes ASSUME the doctrine in this skill (Iron Laws, positive patterns) has already been applied. Recipes are the HOW once the WHY is settled.
+> These recipes ASSUME the doctrine in this skill (core rules, positive patterns) has already been applied. Recipes are the HOW once the WHY is settled.
 
 ## Basic Navigation
 
@@ -275,7 +275,7 @@ Tests now start authenticated. No login loop in every test.
 ## Cross-skill integration
 
 When running these recipes, the doctrine in this skill applies:
-- Apply Iron Laws (especially Law 2: lowest layer first — many E2E tests should be integration tests instead).
+- Apply core rules (especially Rule 2: lowest layer first — many E2E tests should be integration tests instead).
 - Run the 7 AI Agent Gates if a coding agent is producing this test.
 - Check for Anti-Patterns 1, 5, 7, 20 in the diff.
 - For browser security scenarios (auth bypass, XSS, CSRF), see `security-boundary.md`.