@brunosps00/dev-workflow 2.2.0 → 2.3.0

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

@@ -5,191 +5,39 @@ allowed-tools:
   - Read
 ---
 
-# Testing Discipline
+# Testing discipline
 
-## Founding principle
+Use for test design, test review or diagnosing failures/flakiness. Skip cosmetic test edits and reproductions that do not need a testing workflow. Tests expose defects in required behavior; a passing mock or coverage number does not establish correctness.
 
-> 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.
+## Core decisions
 
-Everything else in this skill follows from that.
+- Identify the behavior and lowest layer that can detect its regression. Extend an existing suite when it fits; do not create test-only production seams.
+- Read the project's runner/configuration before choosing commands. Package manager and runner are different: `bun test` and `bun run test` need not run the same suite.
+- Run actual production logic. Mock external boundaries only when justified, and cover integration boundaries with the appropriate real/contract test. Do not require a live external service for every unit change.
+- On failures, inspect production behavior and expected contract before changing assertions. Explain changed expectations when requirements changed; do not weaken tests to obtain green output.
+- Test relevant invalid/error cases, not a mandatory negative companion for every positive assertion. Avoid fixed sleeps and accidental clock/random/environment dependencies.
+- Use project-required thresholds; no universal coverage target, assertion-count cap or mock-size gate. Assess whether the test can catch the intended defect.
 
-## The six core rules
+## Read only the relevant reference
 
-```
-1. Test the behavior, never the mock.
-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.
-6. No test-only methods, branches, or flags leak into production code.
-```
+| Task | Reference |
+|---|---|
+| Choose layer or boundary | `references/core-rules.md` |
+| Design tests | `references/patterns.md` |
+| Review a concrete test smell | `references/anti-patterns.md` |
+| Agent needs test-authoring checks | `references/agent-guardrails.md` |
+| Explicit TDD / test first / red-green-refactor | `references/tdd-loop.md` |
+| Diagnose flaky tests | `references/flaky-discipline.md` |
+| Investigate weak tests or plan scoped mutation analysis | `references/mutation-testing.md` |
+| Playwright browser tests | `references/playwright-recipes.md` |
+| Browser auth/CSRF/header boundary | `references/security-boundary.md` |
+| Choose UI/network/performance workflow | `references/three-workflow-patterns.md` |
 
-Each rule has nuance read `references/core-rules.md` for the long version with examples.
+The task/PR may record behavior, owning layer and suite in ordinary prose. Do not demand magic preamble strings or a new approval merely to name an already-defined invariant. Ambiguous product behavior needs clarification; discoverable runner/suite choices do not.
 
-## When to use
+## Verification
 
-- 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.
-- Explicit test-first requests ("TDD", "test first", "red-green-refactor") → use `references/tdd-loop.md` as an on-demand operating mode, not the default workflow.
-- 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`.
-
-## Step 0 — detect the runner before writing any test
-
-Do not assume `npm test`. The package manager and the test runner are different things — confirm both:
-
-1. Read `package.json` `scripts.test` (plus `test:watch` / `test:coverage`), or the language equivalent (`pyproject.toml`/`tox.ini`, `Cargo.toml`, `*.csproj`, `go.mod`).
-2. Identify the actual runner: jest / vitest / mocha / `node:test` / `bun:test` / pytest / `go test` / `cargo test` / `dotnet test`.
-3. Invoke it through the project's package manager, not a hardcoded `npm`:
-
-| Manager | test | watch | coverage |
-|---|---|---|---|
-| npm | `npm test` | `npm test -- --watch` | `npm run test:coverage` |
-| pnpm | `pnpm test` | `pnpm test --watch` | `pnpm test:coverage` |
-| yarn | `yarn test` | `yarn test --watch` | `yarn coverage` |
-| bun (native) | `bun test` | `bun test --watch` | `bun test --coverage` |
-
-**Bun gotcha:** `bun test` runs Bun's native runner (`bun:test`); `bun run test` runs whatever `scripts.test` is (often jest/vitest). They are not interchangeable — use the one the project actually configures. When unsure, confirm with `<runner> --help`.
-
-## Reference router
-
-| Doing what | Read |
-|------------|------|
-| Placing a new test (which layer?) | `references/core-rules.md` (Rule 2 deep-dive) |
-| Writing new tests | `references/patterns.md` |
-| Explicit test-first / TDD loop | `references/tdd-loop.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 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; 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 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; 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 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)
-
-- Quarantine flaky tests within ONE HOUR of detection. Assign a named owner within 24 hours with a fix-by date.
-- Track `flaky_rate` as a first-class metric: SLO under 1–2%; alert at >5%.
-- Real systems at the final gate: mock at unit; contract-test boundaries; real DB/queue/route at integration; near-zero mocks at E2E.
-
-Full taxonomy in `references/flaky-discipline.md`.
-
-## Cross-cutting red flags
-
-Any of these in a PR is enough to REJECT a verdict:
-
-- 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.
-- `sleep`, `Thread.sleep`, or `cy.wait(<number>)` appears.
-- Selector contains CSS class, index, or `xpath`.
-- Test asserts a third-party site is reachable.
-- Snapshot diffs accepted without reading.
-- Coverage percentage is the only metric quoted.
-- 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 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
-
-- General code review unrelated to tests.
-- Library-specific debugging where the test is just a reproduction.
-- Non-testing CI pipeline design (deploys, artifacts, secrets).
-- Production observability and alerting.
-- Single-line typo fixes in existing tests.
-
-## Integration with dev-workflow commands
-
-- `/dw-plan tasks` applies the placement doctrine — each test-adding task names the invariant.
-- `/dw-run` runs the 6 agent guardrails when generating tests during implementation. When the task or user explicitly requests test-first work, `/dw-run` switches to `references/tdd-loop.md` for that task only.
-- `/dw-review --code-only` runs the anti-pattern checks on diff hunks under test paths.
-- `/dw-qa --fix` applies the flaky-discipline taxonomy in retest cycles.
-- `/dw-qa` (UI mode) references `playwright-recipes.md` for concrete recipes.
-
-## 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 guardrails make them put both down. Tests reveal bugs, not just pass.
+Use `dw-verify` for evidence validity and required delivery gates. Run affected tests while fixing, then complete invalidated required checks. Reuse equivalent passing evidence. Keep scenario-specific test discipline separate from generic CI/production policies.
 
 ## Structured Return
 

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

@@ -1,170 +1,12 @@
-# Six guardrails — mandatory when an agent writes tests
+# Test-authoring checks
 
-LLMs have characteristic failure modes when authoring tests. Six guardrails are forcing functions for the most common ones.
+Read when designing or reviewing agent-authored tests. Apply checks to actual behavior rather than mandatory output tokens.
 
-Every test produced by an agent (via `/dw-run`, `/dw-bugfix`, `/dw-autopilot`, or any code-generating flow) must clear all six BEFORE the diff goes to review.
+1. Identify the behavior, owning layer and existing suite. Infer these from approved requirements and repository evidence; ask only if expected product behavior remains ambiguous.
+2. Execute production logic. Use a real DB/integration fixture when the changed contract depends on it, a contract test for external boundaries, and browser tests for meaningful interactive risk. Pure logic can be verified in unit tests.
+3. Investigate failures before changing tests. Distinguish a code defect, outdated expectation, environment issue or unrelated failure, and explain material expectation changes.
+4. Reject self-confirming mock assertions. Snapshots require a meaningful stable contract and inspected diffs; prefer direct assertions when they express behavior more clearly.
+5. Include relevant error/invalid-input cases where they can detect a real defect. A fixed negative-test quota or assertion count does not measure coverage quality.
+6. Extend existing suites when suitable and avoid production branches solely for tests. Keep new files when a separate behavior boundary justifies them.
 
-## 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-review --code-only` 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` 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.
+A review finding needs evidence that a test can pass for the wrong reason, fail nondeterministically, miss a relevant defect, or constrain implementation unnecessarily. Missing ceremonial preamble text is not a defect.

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

@@ -88,10 +88,10 @@ The discipline: no merge without a green E2E (or equivalent real-system check) f
 
 **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.
+- **Mutation analysis** introduces small code changes and observes whether tests detect them. Inspect survivors and selected scope: a high score alone does not establish meaningful behavior coverage, and equivalent mutants may survive correct tests. Use `mutation-testing.md` for a scoped investigation.
 - 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.
+**Anti-pattern:** inventing a universal coverage or mutation threshold and treating it as proof of correctness. Follow existing project-required gates; propose policy changes explicitly when warranted.
 
 **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."
 
@@ -122,7 +122,7 @@ A healthy test:
 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).
+5. Detects meaningful defects in the behavior it claims to cover; mutation analysis can probe this when justified (Rule 5).
 6. Has zero footprint in production code (Rule 6).
 
 Any test failing ≥2 of these is technical debt accumulating. `/dw-review --code-only` flags them.

package/scaffold/skills/dw-testing-discipline/references/mutation-testing.md

@@ -0,0 +1,19 @@
+# Investigating weak tests with mutations
+
+Use when an important behavior has weak evidence, when auditing tests, or when the approved testing strategy includes mutation analysis. Do not install a mutation framework for a copy edit or make every test change run a repository-wide campaign.
+
+1. Name the behavior at risk and inspect its production path and tests. Select a bounded module and the existing runner. Confirm a clean baseline test run so unrelated failures are not misreported as detected mutants.
+2. Run the installed mutation tool with an explicit source scope and inspect its execution status. If unavailable, a reversible deliberate defect in an isolated copy can probe one invariant; report it as a targeted experiment, not a complete mutation score. Never leave a deliberate defect in the delivery tree.
+3. For a survivor, examine the changed expression, reachable inputs and expected observable result. Distinguish a missing assertion from equivalent behavior, unreachable code, exclusion, timeout or tooling failure. Report unassessed cases instead of calling them safe.
+4. Add or strengthen a test only for a meaningful missing behavior. Derive expected values from requirements, fixtures or an independent oracle; do not repeat the algorithm under test. Ensure mocks match real module exports and API contracts. Assertions on shape, invocation or snapshots are useful only when that is the actual contract being protected.
+5. Demonstrate that the selected defect is detected and the unmodified implementation passes. Record source scope, cases investigated, remaining limitations, command, tool version and report path. Do not weaken assertions, alter production semantics or exclude survivors just to improve a number.
+
+Do not introduce a default mutation-score gate. Preserve existing project-required policy and raise a proposal if it needs revision. A run can succeed while reporting surviving mutants; a tool crash or zero selected files does not establish successful behavioral validation.
+
+## Incremental execution
+
+[StrykerJS incremental mode](https://stryker-mutator.io/docs/stryker-js/incremental/) reuses a prior report; it is not automatically selection of the current PR diff. Determine the PR base and intended source set separately. Include test changes and affected production scope. An empty selection must be explicitly justified.
+
+Stryker's cache does not detect every dependency, configuration, snapshot or environment change. Invalidate reuse when those inputs affect results; use the installed version's supported force/full-scope mechanism. Preserve the unmutated dry run and check runner support for test-change detection. Reuse under `dw-verify` also requires valid input and environment evidence.
+
+In CI, publish inspectable reports and distinguish infrastructure failures from investigated survivors. Select schedule and scope according to risk and measured cost. Broad campaigns belong in an agreed audit or scheduled job, not an implicit requirement on unrelated tasks.

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

@@ -192,20 +192,11 @@ No merge to main without a real-system path going green. Mocks are speed, real i
 
 **Anti-pattern:** 100% mocked test suite. "It all passes locally" → first user request fails because the mock didn't match the real API shape.
 
-## 11. Mutation score over coverage percentage
+## 11. Mutation analysis investigates specific behavioral gaps
 
-**Pattern:**
-
-Set up mutation testing (Stryker for JS/TS, mutmut for Python, etc.) ONCE per project. Run weekly on critical modules.
-
-```bash
-npx stryker run
-# Output: 87 mutants, 78 killed, 9 survived → mutation score 89.6%
-```
-
-A surviving mutant means: this code path runs in tests, but the tests don't actually assert anything that breaks when the code changes. Investigate each.
+Use `mutation-testing.md` when critical behavior or weak assertions justify the cost. Inspect survivors individually: they may expose missing tests, equivalent behavior or analysis limits. Strengthen assertions against the intended contract and verify both the deliberate defect and unmodified behavior. Choose scope and cadence from project risk; do not install a tool in every project or introduce a score target.
 
-**Anti-pattern:** 95% line coverage with assertions like `expect(result).toBeTruthy()` — every line ran, but mutations all survive. The suite is decorative.
+**Anti-pattern:** increasing coverage or killing mutants while assertions still repeat the implementation or only confirm mock setup.
 
 ## 12. Page Object Model is a tool, not a religion
 

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

@@ -23,70 +23,13 @@ If you're tempted to skip this "because it's just a small tweak" — that's the
 
 ## The four grounding questions
 
-Answer all four before proposing colors, layouts, components, or any visual decision.
-
-### 1. Where do design decisions come from?
-
-Find the project's design source-of-truth in this order:
-1. `.dw/rules/<frontend-module>.md` design system section.
-2. `DESIGN.md`, `BRAND.md`, `STYLE_GUIDE.md` at project root.
-3. Design token config — Tailwind theme, CSS variables in `theme.css`/`globals.css`, MUI/Chakra theme.
-4. Component library config — `components.json` for shadcn, theme exports.
-5. Storybook stories (implicit canonical components).
-
-**Stop at the first match** in this list — that source is the authority; defer to it and do not override it with a lower rung or a training-data default. If a needed token is missing (e.g., a danger-secondary color), propose adding it to the authority FIRST, not inline.
-
-If **none exists**: read `references/curated-defaults.md` and pick one of the 10 neutral palettes + one of the 10 font pairings shipped there. Mark the choice in the techspec/PR description: "Design source: no project authority found; using curated default `<name>`; recommend establishing `DESIGN.md`."
-
-**Anti-patterns at this question:**
-- Inventing color hex values inline (`bg-[#FF6B35]`).
-- "I'll use Tailwind defaults" — that's training-data defaults, not project authority.
-- Copying values from "a site I like" without understanding what it solved.
-
-### 2. What does this surface help the user do?
-
-Write one sentence: **"This surface helps the user `<verb-phrase>` so that `<outcome>`."**
-
-Good examples:
-- "...helps the user filter overdue invoices so they can chase late payers in under 30 seconds."
-- "...helps the on-call engineer diagnose which deploy caused the spike so they can roll back without paging the team."
-- "...helps the manager approve or reject expense reports without leaving Slack."
-
-Bad examples:
-- "This surface displays invoice data." (no user, no outcome)
-- "Settings page for managing the account." (vague, no specificity)
-- "Dashboard." (one word)
-
-If you can't write the sentence, the requirements are unclear. Stop and clarify before proceeding.
-
-### 3. What states does the surface have?
-
-Enumerate all states before designing the happy path. Minimum nine, plus domain-specific ones — see `references/state-matrix.md`:
-
-`default`, `hover`, `active`, `focus-visible`, `disabled`, `loading`, `empty`, `error`, `success` plus any domain states (read/unread, online/offline, stale/fresh, pending/approved/rejected, draft/saved/dirty, partial/complete, etc.).
-
-Missing a state at design time = production bug later. The "we'll add empty state later" trap is real.
-
-### 4. Who uses this surface, where, and in what mood?
-
-One sentence: **"`<Who>` uses this on `<where>` in `<what light>` while `<what mood>`."**
-
-Good examples:
-- "An on-call engineer uses this on a dark-room laptop at 3am while troubleshooting a fire."
-- "A field nurse uses this on a phone in bright outdoor light while juggling clipboards."
-- "A receptionist uses this on a 24″ monitor at a busy front desk while talking to a visitor."
-
-Decisions cascade from the answer:
-- 3am dark room → dark mode, high contrast, no flashing animations.
-- Bright outdoor → minimum 7:1 contrast, larger touch targets, no thin fonts.
-- Busy front desk → glanceable info, no nested menus, large numbers.
-
-Without this sentence, defaults take over: light mode, default contrasts, animations, regular touch targets. Production users hate it; you can't articulate why.
+For the four grounding questions, read `references/the-four-grounding-questions-detail.md`. Load only when this part of the task applies.
 
 ## Required reading by context
 
 | Doing what | Read |
 |------------|------|
+| Planning/auditing frontend data flow, dependencies or quality tooling | `references/frontend-engineering.md` (may be read directly without visual grounding for nonvisual work) |
 | Any UI work (the full version of the grounding) | `references/hard-gate.md` |
 | Reviewing or proposing a design | `references/visual-slop.md` (14 patterns + specific anti-default values) |
 | Designing state coverage | `references/state-matrix.md` |

package/scaffold/skills/dw-ui-discipline/references/frontend-engineering.md

@@ -0,0 +1,46 @@
+# Frontend engineering controls
+
+Read when planning frontend architecture, auditing a frontend module, or reviewing changes to its data flow, dependencies or quality tooling. A visual/copy-only edit needs only the relevant UI checks. This reference can be used directly without running visual grounding for an API client or CI configuration change.
+
+## Discover before changing
+
+Inspect the target workspace's scripts, lockfile, framework, compiler, API source, lint configuration, entry points and CI. Reuse working controls. Record observed configuration separately from proposed policy; an absent tool is not a failed check. Installation of dev-workflow does not authorize replacing consumer tooling.
+
+For a project audit, use the installed `frontend-quality-template.md` in `.dw/templates/` to document the baseline in the module's existing rules file. For a feature, include only affected decisions in its TechSpec. Read those decisions during implementation and review. A request to analyze produces findings and proposals; an authorized implementation may add compatible scripts/configuration and validate them.
+
+When using this skill standalone without the scaffold template, record the same compact control fields from the adoption section below in the project's existing document; no template installation is required.
+
+## Contract and type boundaries
+
+- Identify the authoritative API schema and its owner/revision before introducing response fields. If generation is used, record the generator version, command and output paths. Review contract changes, regenerate reproducibly and inspect drift; correct the source or generator rather than editing generated output.
+- When there is no maintained schema, derive a narrow boundary from verified backend code or documented responses and test it; label unresolved assumptions. Do not invent an OpenAPI specification from frontend guesses.
+- Runtime data still needs validation at relevant trust boundaries. Generating a validator is insufficient unless the actual response path calls it and handles failure. [Hey API's Zod integration](https://heyapi.dev/docs/openapi/typescript/plugins/zod) is one option when compatible with the existing client.
+- For TypeScript, inspect effective inherited configuration. Consider [`strict`](https://www.typescriptlang.org/tsconfig/strict.html), [`noUncheckedIndexedAccess`](https://www.typescriptlang.org/tsconfig/noUncheckedIndexedAccess.html) and [`exactOptionalPropertyTypes`](https://www.typescriptlang.org/tsconfig/exactOptionalPropertyTypes.html). Migrate by package or a coherent project boundary; passing filenames to a compiler invocation must not accidentally bypass project settings. Do not hide migration errors behind casts, `any` or non-null assertions.
+
+## Architecture and lint feedback
+
+Derive allowed imports from the project's architecture, including framework-specific server/client boundaries. Reuse an existing graph checker; [eslint-plugin-boundaries](https://github.com/javierbrea/eslint-plugin-boundaries) is an option for JS/TS. Verify aliases, workspace packages, type imports and legitimate framework entry points. A rejected dependency should identify its source, forbidden destination and the intended placement. Do not impose a universal folder layout.
+
+Choose lint rules against concrete failure modes and the installed runner: missing assertion awaits, accidentally focused tests, unsafe type escapes and inaccessible JSX. For React state changes, check whether an Effect actually synchronizes an external system; derived values and event responses often belong in rendering or handlers. Preserve legitimate synchronization. See [React's Effect guidance](https://react.dev/learn/you-might-not-need-an-effect).
+
+For a recurring repository-specific defect, prefer an existing rule. A custom detector needs a documented failure mode, an actionable diagnostic and valid/invalid fixtures. Exercise aliases, exclusions and unsupported syntax; an unresolved import is an analysis limitation, not proof of safety. Use an AST or the framework's parser when syntax matters. [ESLint's RuleTester workflow](https://eslint.org/docs/latest/extend/custom-rule-tutorial) supports rule validation. Avoid adding a regex-based import graph when the existing tool already models it.
+
+## Code that should disappear
+
+Evaluate dead-code findings against runtime reachability and public exports before deletion. Configure framework/plugin entry points, generated sources and workspace aliases. Tests alone can keep otherwise unused production code appearing live: [Knip production mode](https://knip.dev/features/production-mode) provides a separate view of shipped code and does not replace its normal analysis. Validate a newly configured detector with an intentionally unused fixture and a legitimately reachable fixture in an isolated workspace.
+
+Use textual duplication reports such as [jscpd](https://github.com/kucherenko/jscpd) as candidates for inspection. Apply different policies to repeated markup/fixtures and business calculations. Search for semantic duplicates too. Consolidate only when copies represent the same rule and should evolve together; a shared abstraction must preserve callers' behavior. Record exclusions with a reason and review trigger, instead of growing blanket ignores to make a report green.
+
+## Tests and adoption
+
+When critical logic changes or existing tests appear weak, use the testing skill's `references/mutation-testing.md` if available. Mutation testing complements contract and user-flow tests; neither coverage nor a diagnostic score establishes acceptance.
+
+For each adopted control record: risk, configuration, exact workspace command, scope, baseline, enforcement status, evidence and owner/review trigger. Use `required`, `advisory`, `deferred` or `not_applicable`; record actual execution separately (`passed`, `failed`, `not_run`). Start noisy new controls as advisory, triage findings, then promote demonstrated checks. Existing required gates remain required. Typechecking, builds and dependency graphs often need the whole affected project even when lint or mutation analysis can target a diff.
+
+Local hooks may shorten feedback, but CI must execute required checks independently of editor or agent hooks. Keep failures identifiable; verify that deployment depends on successful required jobs and that repository rules actually require the intended status checks. Do not claim a workflow file alone establishes branch protection. Advisory mutation runs may publish findings without a score threshold; report execution failures explicitly. Never hide a required check behind `continue-on-error`, an empty selection or a silently skipped job.
+
+Record command, inputs, environment and analysis scope through `dw-verify` when available. Treat new ignores, disabled rules, changed generation/configuration and lost CI coverage as reviewable changes. Delivery still requires checking product behavior, architecture and accessibility; automated findings reduce review work without replacing that judgment.
+
+## Attribution
+
+Workflow adaptation prompted by Yuri Mikhin's [Evil Martians article](https://evilmartians.com/chronicles/ten-anti-ai-slop-moves-for-frontend-projects-going-faster-than-humans-can-review), September 1, 2026. Procedures are independently written for dev-workflow and supported by the primary documentation linked above (checked September 9, 2026). No article text, source code or third-party tool is bundled here.