devflow-kit 3.11.0 → 3.12.0

package/src/assets/skills/software-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: software-design
-description: This skill should be used when the user asks to "handle errors", "inject dependencies", "return Result", "make it immutable", or implements business logic or error handling.
+description: This skill should be used when the user asks to "inject dependencies", "return Result", "make it immutable", or implements business logic or error handling.
 user-invocable: false
 allowed-tools: Read, Grep, Glob, AskUserQuestion
 ---
@@ -11,119 +11,36 @@ The canonical source of architectural patterns and principles for consistent, hi
 
 ## Iron Law
 
-> **NEVER THROW IN BUSINESS LOGIC** [1][11]
+> **Never throw in business logic**
 >
-> All operations that can fail MUST return Result types. Exceptions are allowed
-> ONLY at system boundaries (API handlers, database adapters). Any `throw` statement
-> in business logic is a violation. No exceptions.
+> Every operation that can fail must return a Result type. Exceptions are allowed
+> only at system boundaries (API handlers, database adapters). A `throw` statement
+> in business logic is a violation.
 
 ## Philosophy
 
-1. **Functional Core, Imperative Shell** [11] — Pure business logic, side effects at boundary
-2. **Explicit Error Handling** [1][8] — Result types, no exceptions in business logic
-3. **Immutability by Default** [7][14] — Return new objects, never mutate
-4. **Dependency Injection** [3] — All deps injected, nothing instantiated internally
-5. **Make Illegal States Unrepresentable** [4][2] — Types enforce invariants at compile time
-6. **Parse, Don't Validate** [12] — Schema transforms at boundaries
+1. **Functional Core, Imperative Shell** — Pure business logic, side effects at boundary
+2. **Explicit Error Handling** — Result types, no exceptions in business logic
+3. **Immutability by Default** — Return new objects, never mutate (copy before `.sort()`)
+4. **Dependency Injection** — All deps injected, nothing instantiated internally
+5. **Make Illegal States Unrepresentable** — Types enforce invariants at compile time; discriminated unions with exhaustive switches; each error variant carries its full context
+6. **Parse, Don't Validate** — Schema transforms at boundaries
+7. **Compose with pipes**, and clean up resources in `finally`
 
----
-
-## Pattern 1: Result Types [1][5][6][18]
-
-```typescript
-type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };
-
-function createUser(data: unknown): Result<User, ValidationError> {
-  if (!valid(data)) return Err({ type: 'ValidationFailed', details: validate(data).errors });
-  return Ok(buildUser(data));
-}
-// Libraries: neverthrow [18], ts-results [19]. Theory: Moggi [5] + Wadler [6].
-```
-
-## Pattern 2: Dependency Injection [3]
-
-```typescript
-class UserService {
-  constructor(private db: Database, private emailer: EmailService) {}
-  // Test: new UserService(mockDb, mockEmailer) — never new Database() inside [3]
-}
-```
-
-## Pattern 3: Immutability [7][14]
-
-```typescript
-// New object, never mutate input; copy before .sort() [7][14]
-function updateUser(user: User, changes: Partial<User>): User {
-  return { ...user, ...changes };
-}
-```
-
-## Pattern 4: Functional Core, Imperative Shell [11]
-
-```typescript
-// PURE CORE: no I/O, deterministic [11]
-function calculateTotal(items: Item[], taxRate: number): number {
-  return items.reduce((sum, i) => sum + i.price, 0) * (1 + taxRate);
-}
-// IMPERATIVE SHELL: I/O at boundary only [11]
-async function processOrder(id: string): Promise<Result<Order, Error>> {
-  const order = await db.getOrder(id);
-  return Ok(await db.save({ ...order, total: calculateTotal(order.items, 0.1) }));
-}
-```
-
-## Pattern 5: Type Safety [4][2][21]
-
-```typescript
-// Discriminated unions — compiler enforces exhaustiveness [4][21]
-type UserError =
-  | { type: 'NotFound'; userId: string }           // carries full context [2]
-  | { type: 'ValidationFailed'; field: string; message: string };
-
-type Status = 'pending' | 'completed' | 'failed';
-function handleStatus(status: Status): string {
-  switch (status) {
-    case 'pending': return 'Waiting';
-    case 'completed': return 'Done';
-    case 'failed': return 'Error';
-  }  // Exhaustive — no default needed [21]
-}
-```
-
-## Pattern 6: Pipe Composition [20][13]
-
-```typescript
-const pipe = <T>(...fns: Array<(x: T) => T>) => (x: T) => fns.reduce((v, f) => f(v), x);
-const process = pipe(validate, normalize, enrich); // Composition as glue [20][13]
-```
-
-## Pattern 7: Resource Cleanup + Documentation [7]
-
-```typescript
-const handle = await fs.open(path);
-try { return Ok(parse(await handle.readFile())); }
-finally { await handle.close(); }
-
-// ARCHITECTURE: Repository returns domain objects only
-// ARCHITECTURE EXCEPTION: Direct DB for health check — must work if service layer down
-```
-
----
+`references/patterns.md` shows each pattern in code.
 
 ## Consistency Rules
 
-- Result types: if one method returns Result, ALL must [1]
-- DI: apply consistently throughout [3]
+- Result types: if one method returns Result, all must
+- DI: apply consistently throughout
 - Async: single pattern (don't mix callbacks/promises)
 
 ## Anti-Patterns
 
-| Pattern | Source |
-|---------|--------|
-| Throwing in business logic — use Result | [1][11] |
-| Silent failures — swallowed catch blocks | [10] |
-| Mutable state — return new objects | [7][14] |
-| Service locator — inject instead | [3] |
+- Throwing in business logic — use Result
+- Silent failures — swallowed catch blocks
+- Mutable state — return new objects
+- Service locator — inject instead
 
 ### Workaround Labeling (Required)
 
@@ -131,13 +48,11 @@ finally { await handle.close(); }
 
 Unlabeled workarounds are violations. See `references/code-smell-violations.md`.
 
----
-
 ## Extended References
 
 - `references/sources.md` — Full bibliography (25 sources with access links)
 - `references/violations.md` — Violation patterns with citations
-- `references/patterns.md` — Extended correct patterns with citations
+- `references/patterns.md` — The core patterns and extended correct patterns, with citations
 - `references/checklist.md` — Pre-implementation and review checklists
 - `references/code-smell-violations.md` — Fake solutions, deceptive code, magic values
 - `references/detection.md` — Grep patterns for automated detection

package/src/assets/skills/software-design/references/patterns.md

@@ -1,10 +1,92 @@
-# Extended Correct Pattern Examples
+# Correct Pattern Examples
 
-Additional examples of correct implementations beyond the core examples in SKILL.md.
+Correct implementations: the seven core patterns of SKILL.md, then extended examples.
 All patterns cite `references/sources.md`.
 
 ---
 
+## Pattern 1: Result Types [1][5][6][18]
+
+```typescript
+type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };
+
+function createUser(data: unknown): Result<User, ValidationError> {
+  if (!valid(data)) return Err({ type: 'ValidationFailed', details: validate(data).errors });
+  return Ok(buildUser(data));
+}
+// Libraries: neverthrow [18], ts-results [19]. Theory: Moggi [5] + Wadler [6].
+```
+
+## Pattern 2: Dependency Injection [3]
+
+```typescript
+class UserService {
+  constructor(private db: Database, private emailer: EmailService) {}
+  // Test: new UserService(mockDb, mockEmailer) — never new Database() inside [3]
+}
+```
+
+## Pattern 3: Immutability [7][14]
+
+```typescript
+// New object, never mutate input; copy before .sort() [7][14]
+function updateUser(user: User, changes: Partial<User>): User {
+  return { ...user, ...changes };
+}
+```
+
+## Pattern 4: Functional Core, Imperative Shell [11]
+
+```typescript
+// PURE CORE: no I/O, deterministic [11]
+function calculateTotal(items: Item[], taxRate: number): number {
+  return items.reduce((sum, i) => sum + i.price, 0) * (1 + taxRate);
+}
+// IMPERATIVE SHELL: I/O at boundary only [11]
+async function processOrder(id: string): Promise<Result<Order, Error>> {
+  const order = await db.getOrder(id);
+  return Ok(await db.save({ ...order, total: calculateTotal(order.items, 0.1) }));
+}
+```
+
+## Pattern 5: Type Safety [4][2][21]
+
+```typescript
+// Discriminated unions — compiler enforces exhaustiveness [4][21]
+type UserError =
+  | { type: 'NotFound'; userId: string }           // carries full context [2]
+  | { type: 'ValidationFailed'; field: string; message: string };
+
+type Status = 'pending' | 'completed' | 'failed';
+function handleStatus(status: Status): string {
+  switch (status) {
+    case 'pending': return 'Waiting';
+    case 'completed': return 'Done';
+    case 'failed': return 'Error';
+  }  // Exhaustive — no default needed [21]
+}
+```
+
+## Pattern 6: Pipe Composition [20][13]
+
+```typescript
+const pipe = <T>(...fns: Array<(x: T) => T>) => (x: T) => fns.reduce((v, f) => f(v), x);
+const process = pipe(validate, normalize, enrich); // Composition as glue [20][13]
+```
+
+## Pattern 7: Resource Cleanup + Documentation [7]
+
+```typescript
+const handle = await fs.open(path);
+try { return Ok(parse(await handle.readFile())); }
+finally { await handle.close(); }
+
+// ARCHITECTURE: Repository returns domain objects only
+// ARCHITECTURE EXCEPTION: Direct DB for health check — must work if service layer down
+```
+
+---
+
 ## Result Types — Extended Patterns [1][5][6]
 
 ### Chaining Results [1]

package/src/assets/skills/software-design/references/violations.md

@@ -1,6 +1,6 @@
 # Extended Violation Examples
 
-Additional code smell patterns and violations beyond the core examples in SKILL.md.
+Additional code smell patterns and violations beyond the anti-patterns in SKILL.md.
 All violations cite `references/sources.md`.
 
 ---

package/src/assets/skills/test-driven-development/SKILL.md

@@ -19,18 +19,15 @@ activation:
 
 # Test-Driven Development
 
-Enforce the RED-GREEN-REFACTOR cycle for all implementation work. Tests define the design. Code satisfies the tests. Refactoring improves the design without changing behavior.
+Use the RED-GREEN-REFACTOR cycle for all implementation work. Tests define the design. Code satisfies the tests. Refactoring improves the design without changing behavior.
 
 ## Iron Law
 
-> **TESTS FIRST, ALWAYS**
+> **Tests first, always.**
 >
-> Write the failing test before the production code. No exceptions. If you catch
-> yourself writing production code without a failing test, stop immediately, delete
-> the production code, write the test, watch it fail, then write the minimum code
-> to make it pass. The test IS the specification.
-
----
+> Write the failing test before the production code. If you catch yourself writing
+> production code without a failing test, stop, delete that code, write the test,
+> watch it fail, then write the minimum code to make it pass. The test is the specification.
 
 ## The Cycle
 
@@ -38,117 +35,50 @@ Enforce the RED-GREEN-REFACTOR cycle for all implementation work. Tests define t
 
 ### Step 1: RED — Write a Failing Test
 
-Write a test that describes the behavior you want. Run it. Watch it fail. The failure message IS your specification.
+Write a test that describes the behavior you want. Run it. Watch it fail. The failure message is your specification. Describe what the code should do, not how. One behavior per test, and one assertion per test where you can. Name tests as sentences: "returns error when email is invalid".
 
-```
-Describe what the code SHOULD do, not how it does it.
-One behavior per test. One assertion per test (ideally).
-Name tests as sentences: "returns error when email is invalid"
-```
-
-**Checkpoint:** The test MUST fail before proceeding. A test that passes immediately proves nothing.
+**Checkpoint:** The test must fail before you go on. A test that passes at once proves nothing.
 
 ### Step 2: GREEN — Write Minimum Code to Pass
 
-Write the simplest production code that makes the failing test pass. No more, no less.
-
-```
-Hardcode first if that's simplest. Generalize when the next test forces it.
-Don't write code "you'll need later." Write code the test demands NOW.
-Don't optimize. Don't refactor. Don't clean up. Just pass the test.
-```
+Write the simplest production code that makes the failing test pass. Hardcode first if that is simplest; generalize when the next test forces it. No code for later, no optimizing, no cleanup.
 
 **Checkpoint:** All affected tests pass. If any test fails, fix it before moving on.
 
 ### Step 3: REFACTOR — Improve Without Changing Behavior
 
-Now clean up: extract helpers, rename, simplify, apply DRY. Tests stay green throughout.
+Extract helpers, rename, simplify, remove duplication. Run the affected tests after every refactoring step. If a test breaks during refactor, undo: you changed behavior.
 
-```
-Run the affected tests after every refactoring step.
-If a test breaks during refactor, undo immediately — you changed behavior.
-```
-
-**Checkpoint:** All affected tests still pass. Code is clean. Repeat from Step 1 for next behavior.
-
----
+**Checkpoint:** All affected tests still pass. Repeat from Step 1 for the next behavior.
 
 ## Cycle Verification
 
-After each RED-GREEN-REFACTOR cycle, ALL must hold:
+After each cycle, all of these must hold:
 
 - [ ] Test existed BEFORE production code (not concurrent, not after)
-- [ ] Test failed for the RIGHT reason (expected behavior absent, not syntax/import error)
-- [ ] Production code is minimal — no speculative additions beyond what the test demands
+- [ ] Test failed for the right reason (expected behavior absent, not a syntax or import error)
+- [ ] Production code is minimal — nothing beyond what the test demands
 - [ ] ALL affected tests pass, not just the new one
 - [ ] Refactoring happened in Step 3 (or code is already clean — state explicitly)
 - [ ] No untested production code remains
 
-If any fails: you skipped TDD. Back up and redo the cycle correctly.
-
----
-
-## Rationalization Prevention
-
-These are the excuses developers use to skip TDD. Recognize and reject them.
-
-| Excuse | Why It Feels Right | Why It's Wrong | Correct Action |
-|--------|-------------------|----------------|----------------|
-| "I'll write tests after" | Need to see the shape first | Tests ARE the shape — they define the interface before implementation exists | Write the test first |
-| "Too simple to test" | It's just a getter/setter | Getters break, defaults change, edge cases hide in "simple" code | Write it — takes 30 seconds |
-| "I'll refactor later" | Just get it working now | "Later" never comes; technical debt compounds silently | Refactor now in Step 3 |
-| "Test is too hard to write" or "the test setup is too complex" | Mocking is painful | Hard-to-test code = bad design, and complex setup = too much coupling; the test is telling you the interface is wrong | Simplify the interface first |
-| "Need to see the whole picture" or "the architecture first" | Can't test what I haven't designed or structured yet | TDD IS design; each test reveals the next piece of the interface, and tests DEFINE the architecture | Let the tests drive the design and structure |
-| "Tests slow me down" | Faster to just write the code | Faster until the first regression; TDD is faster for anything > 50 lines | Trust the cycle |
-| "Framework is hard to set up" | Setup is complex | One-time cost vs recurring regression cost; untested code compounds debt | Set up the framework first — that IS the work |
-| "This is infrastructure, not logic" | Plumbing doesn't need tests | Infrastructure carries data; broken plumbing floods everything downstream | Test the contract, not the internals |
-| "Deadline is tight, no time for tests" | Ship now, test later | Untested code ships bugs; fixing bugs under deadline is slower than TDD | TDD is faster under pressure, not slower |
-
-See `references/rationalization-prevention.md` for extended examples with code.
-
-### Red Flags — STOP Immediately
+If any fails, you skipped TDD: back up and redo the cycle.
 
-The table above catches excuses *before starting*. These catch you *mid-work*: thoughts that signal you are about to skip a step.
+An excuse to skip the test-first step is a rationalization: reject it. `references/rationalization-prevention.md` lists the common excuses, the mid-work red flags and a test-first example.
 
-| Thought | Correction |
-|---------|------------|
-| "Let me write the implementation first, tests after" | Delete the code. Write the test. Watch it fail. Then rewrite. |
-| "I'll just spike this and add tests later" | Unless the user said "spike" — you're rationalizing, not prototyping. |
-| "Let me get it working, then lock it with tests" | Those tests verify your implementation, not the requirement. Backwards. |
-| "I know this works, I've written it before" | Past code passed past tests. This code needs its own failing test. |
-| "One more function, then I'll write the test" | STOP. Write the test for what you have now. Increments, not batches. |
-
-### Test-First vs Code-First
-
-**Code-first** (wrong): write `parseConfig()`, then a test that mirrors it (`parseConfig("key=val")` passes). Empty input, malformed lines, multi-value keys and whitespace stay hidden until production.
-
-**Test-first** (correct): "ignores comment lines", then "handles empty input", then "rejects malformed lines", each failing first and each driving the next slice of `parseConfig()`, so it handles the edges from the start.
-
-Code-first tests verify what you *happened to build*. Test-first tests specify what *should exist*.
-
-### When Stuck
+## When Stuck
 
 | Blocker | Solution |
 |---------|----------|
-| Don't know what to test first | Test the simplest input/output pair. "Given X, expect Y." Start there. |
-| Test needs complex setup/state | Extract the logic into a pure function. Test that. Integrate after. |
+| Don't know what to test first | Test the simplest input/output pair: "Given X, expect Y." |
+| Test needs complex setup or state | Extract the logic into a pure function. Test that. Integrate after. |
 | Behavior depends on external state (DB, API, clock) | Inject the dependency as a parameter. Pass a fake in tests. |
-| Multiple behaviors tangled together | Decompose. One test = one behavior. If you can't isolate it, the design needs splitting. |
-| Modifying legacy code with no tests | Write a characterization test first — a test that captures the current behavior, even if wrong. Then make your change and see what breaks. |
-
----
+| Multiple behaviors tangled together | One test = one behavior. If you can't isolate it, split the design. |
+| Modifying legacy code with no tests | Write a characterization test first: it captures the current behavior, even if wrong. Then change the code and see what breaks. |
 
-## Process Enforcement
+## What to Test
 
-When implementing any feature under ambient IMPLEMENT, start from the simplest thing it must do, take that one behavior through RED, GREEN and REFACTOR, then repeat for the next behavior.
-
-### File Organization
-
-- Test file lives next to production file: `user.ts` → `user.test.ts`
-- Follow project's existing test conventions (Jest, Vitest, pytest, etc.)
-- Import the module under test, not internal helpers
-
-### What to Test
+Follow the project's test layout and conventions, and import the module under test, not its internal helpers.
 
 | Test | Don't Test |
 |------|------------|
@@ -157,23 +87,18 @@ When implementing any feature under ambient IMPLEMENT, start from the simplest t
 | Integration points (boundaries) | Third-party library correctness |
 | State transitions | Getter/setter plumbing (unless non-trivial) |
 
----
-
 ## When TDD Does Not Apply
 
-- **Quick/chat tasks** — Trivial edits, exploration, conversational requests
-- **Non-code tasks** — Documentation, configuration, CI changes
-- **Exploratory prototyping** — User explicitly says "just spike this" or "prototype"
-- **Existing test suite changes** — Modifying tests themselves (devflow:testing skill applies instead)
-
-When skipping TDD, never rationalize. State clearly: "Skipping TDD because: [specific reason from list above]."
+- **Quick or chat tasks**: trivial edits, exploration, conversational requests
+- **Non-code tasks**: documentation, configuration, CI changes
+- **Exploratory prototyping**: the user explicitly says "just spike this" or "prototype"
+- **Existing test suite changes**: modifying tests themselves (devflow:testing skill applies instead)
 
----
+When you skip TDD, state the reason from this list: "Skipping TDD because: [reason]."
 
-## Integration with Ambient Mode
+## By Mode
 
-- **IMPLEMENT** → TDD enforced. Write the failing test before production code. Skill loaded via Code agent frontmatter.
-- **DEBUG** → TDD applies to the fix: write a test that reproduces the bug first, then fix.
-- **PLAN** → TDD shapes the plan: test strategy section, test-first file ordering, RED-GREEN-REFACTOR cycle awareness.
-- **RESOLVE** → TDD enforced via the Code agent (issue-fix mode). Every fix needs a failing-then-passing regression test first.
-- **PIPELINE** → TDD inherited transitively through `/implement` → the Code agent.
+- **IMPLEMENT**: write the failing test before production code, one behavior at a time. The Code agent preloads this skill.
+- **DEBUG**: write a test that reproduces the bug first, then fix.
+- **PLAN**: the plan has a test strategy and orders test files first.
+- **RESOLVE**: the Code agent (issue-fix mode) writes a failing-then-passing regression test for every fix.

package/src/assets/skills/test-driven-development/references/rationalization-prevention.md

@@ -1,6 +1,38 @@
 # TDD Rationalization Prevention — Extended Examples
 
-Detailed code examples showing how each rationalization leads to worse outcomes.
+The excuses table, the mid-work red flags, a test-first example, and detailed code examples that show how each rationalization leads to worse outcomes.
+
+## Excuses and corrections
+
+| Excuse | Why It Feels Right | Why It's Wrong | Correct Action |
+|--------|-------------------|----------------|----------------|
+| "I'll write tests after" | Need to see the shape first | Tests ARE the shape — they define the interface before implementation exists | Write the test first |
+| "Too simple to test" | It's just a getter/setter | Getters break, defaults change, edge cases hide in "simple" code | Write it — takes 30 seconds |
+| "I'll refactor later" | Just get it working now | "Later" never comes; technical debt compounds silently | Refactor now in Step 3 |
+| "Test is too hard to write" or "the test setup is too complex" | Mocking is painful | Hard-to-test code = bad design, and complex setup = too much coupling; the test is telling you the interface is wrong | Simplify the interface first |
+| "Need to see the whole picture" or "the architecture first" | Can't test what I haven't designed or structured yet | TDD IS design; each test reveals the next piece of the interface, and tests DEFINE the architecture | Let the tests drive the design and structure |
+| "Tests slow me down" | Faster to just write the code | Faster until the first regression; TDD is faster for anything > 50 lines | Trust the cycle |
+| "Framework is hard to set up" | Setup is complex | One-time cost vs recurring regression cost; untested code compounds debt | Set up the framework first — that IS the work |
+| "This is infrastructure, not logic" | Plumbing doesn't need tests | Infrastructure carries data; broken plumbing floods everything downstream | Test the contract, not the internals |
+| "Deadline is tight, no time for tests" | Ship now, test later | Untested code ships bugs; fixing bugs under deadline is slower than TDD | TDD is faster under pressure, not slower |
+
+## Red flags mid-work
+
+| Thought | Correction |
+|---------|------------|
+| "Let me write the implementation first, tests after" | Delete the code. Write the test. Watch it fail. Then rewrite. |
+| "I'll just spike this and add tests later" | Unless the user said "spike" — you're rationalizing, not prototyping. |
+| "Let me get it working, then lock it with tests" | Those tests verify your implementation, not the requirement. Backwards. |
+| "I know this works, I've written it before" | Past code passed past tests. This code needs its own failing test. |
+| "One more function, then I'll write the test" | STOP. Write the test for what you have now. Increments, not batches. |
+
+## Test-first vs code-first
+
+**Code-first** (wrong): write `parseConfig()`, then a test that mirrors it (`parseConfig("key=val")` passes). Empty input, malformed lines, multi-value keys and whitespace stay hidden until production.
+
+**Test-first** (correct): "ignores comment lines", then "handles empty input", then "rejects malformed lines", each failing first and each driving the next slice of `parseConfig()`, so it handles the edges from the start.
+
+Code-first tests verify what you *happened to build*. Test-first tests specify what *should exist*.
 
 ## "I'll write tests after"
 

package/src/assets/skills/testing/SKILL.md

@@ -18,25 +18,21 @@ activation:
 
 ## Iron Law
 
-> **TESTS VALIDATE BEHAVIOR, NOT IMPLEMENTATION** [4][8]
+> **Tests validate behavior, not implementation.**
 >
 > A test should fail when behavior breaks, not when implementation changes. Mock at
 > boundaries, not internals. Test the contract, not the code path. If tests are hard to
-> write, the design is wrong — fix the architecture, not the tests. [3][8]
+> write, the design is wrong — fix the architecture, not the tests.
 
----
-
-## Testing Shapes [6][7][10]
+## Testing Shapes
 
 | Shape | Guidance |
 |-------|---------|
-| Pyramid [6] | Many unit → fewer integration → fewest E2E |
-| Trophy [7] | Integration tests give best ROI for UI-heavy code |
-| Google [4] | 70% unit / 20% integration / 10% E2E; avoid E2E excess [12] |
+| Pyramid | Many unit → fewer integration → fewest E2E |
+| Trophy | Integration tests give best ROI for UI-heavy code |
+| Google | 70% unit / 20% integration / 10% E2E; avoid E2E excess |
 
----
-
-## Test Doubles Taxonomy [1][9]
+## Test Doubles Taxonomy
 
 | Type | When to Use | Example |
 |------|------------|---------|
@@ -46,92 +42,78 @@ activation:
 | **Mock** | Pre-programmed expectations | `expect(fn).toHaveBeenCalledWith(x)` |
 | **Fake** | Working substitute (in-memory DB) | `InMemoryUserRepo` |
 
-"Mock roles, not objects" — mock interfaces you own, never third-party internals [3][9].
-
----
+"Mock roles, not objects" — mock interfaces you own, never third-party internals.
 
 ## Test Design Red Flags
 
 | Red Flag | Symptom | Root Cause | Fix |
 |----------|---------|-----------|-----|
-| Complex setup >10 lines [8] | `beforeEach` with 6+ mocks | Too many dependencies | Split service; use fakes [1][4] |
-| Repetitive try/catch [8] | Same pattern >3 times | API throws, not Result | Migrate to Result types [4] |
-| Nested mock structures [1][3] | `mockDb.orders.create: jest.fn()` | Tight coupling | Extract interface; use fake [9] |
-| Spying on private methods [8] | `jest.spyOn(obj as any, '_method')` | Tests implementation | Assert observable output [4] |
+| Complex setup >10 lines | `beforeEach` with 6+ mocks | Too many dependencies | Split service; use fakes |
+| Repetitive try/catch | Same pattern >3 times | API throws, not Result | Migrate to Result types |
+| Nested mock structures | `mockDb.orders.create: jest.fn()` | Tight coupling | Extract interface; use fake |
+| Spying on private methods | `jest.spyOn(obj as any, '_method')` | Tests implementation | Assert observable output |
 
 ```typescript
-// VIOLATION: Tests private implementation [8]
+// VIOLATION: Tests private implementation
 jest.spyOn(cart as any, 'updateTotal');
 expect(spy).toHaveBeenCalled();   // Tests HOW
 
-// CORRECT: Tests observable behavior [4]
+// CORRECT: Tests observable behavior
 cart.addItem({ id: '1', price: 10 });
 expect(cart.getTotal()).toBe(10); // Tests WHAT
 ```
 
----
-
-## Property-Based Testing [5][14]
+## Property-Based Testing
 
-State invariants; let the framework generate inputs and shrink failures [5]:
+State invariants; let the framework generate inputs and shrink failures:
 
 ```typescript
-// fast-check: property must hold for all valid inputs [14]
+// fast-check: property must hold for all valid inputs
 fc.assert(fc.property(fc.string(), (s) => decode(encode(s)) === s));
 ```
 
-Use for: parsers/serializers, arithmetic, sorting, state machines [5][13][14].
-
----
+Use for: parsers/serializers, arithmetic, sorting, state machines.
 
-## Flaky Tests [11][18]
+## Flaky Tests
 
 | Root Cause | Fix |
 |-----------|-----|
-| Async/timing races | Use fake timers; `await` all async ops [19] |
-| Order dependencies | Each test self-contained; fresh state [4] |
-| Shared mutable state | Reset in `afterEach`; use DI [4] |
-
-Quarantine flaky tests immediately — a suite that sometimes passes is worse than no suite [11].
+| Async/timing races | Use fake timers; `await` all async ops |
+| Order dependencies | Each test self-contained; fresh state |
+| Shared mutable state | Reset in `afterEach`; use DI |
 
----
+Quarantine flaky tests immediately — a suite that sometimes passes is worse than no suite.
 
-## Coverage & Severity [4][8]
+## Coverage & Severity
 
 | Severity | Criteria |
 |----------|----------|
-| **CRITICAL** | Tests don't verify behavior; critical paths untested; everything mocked [4] |
-| **HIGH** | Missing error paths; flaky tests [11]; slow (>10s); setup >10 lines [8] |
-| **MEDIUM** | Missing edge cases; weak assertions; unclear AAA structure [17] |
+| **CRITICAL** | Tests don't verify behavior; critical paths untested; everything mocked |
+| **HIGH** | Missing error paths; flaky tests; slow (>10s); setup >10 lines |
+| **MEDIUM** | Missing edge cases; weak assertions; unclear AAA structure |
 | **LOW** | Organization; naming clarity |
 
----
-
-## Test Suite Safety [19]
+## Test Suite Safety
 
 ```typescript
 { fileParallelism: false, maxWorkers: 1, testTimeout: 10000 }  // vitest / jest
 ```
 
----
-
 ## Extended References
 
 | Reference | Contents |
 |-----------|----------|
 | `references/sources.md` | Full bibliography (20 sources) |
-| `references/violations.md` | Extended violations with citations [1][4][8][11] |
-| `references/patterns.md` | Correct patterns with citations [1][2][5][14] |
+| `references/violations.md` | Extended violations with citations |
+| `references/patterns.md` | Correct patterns with citations |
 | `references/detection.md` | Bash commands for automated detection |
 | `references/report-template.md` | Report format for documenting issues |
 
----
-
-## Quality Gates [4][8][17]
+## Quality Gates
 
-- [ ] Setup <10 lines; use fakes over mocks for complex dependencies [1]
+- [ ] Setup <10 lines; use fakes over mocks for complex dependencies
 - [ ] Each new assertion would fail, not error, with the change reverted: its RED run counts, else a bad input or a temporary uncommitted revert of your own edit, never a stash
 - [ ] All branches covered: happy path + errors + edge cases
-- [ ] Test names describe expected behavior [4]
-- [ ] Tests follow Arrange-Act-Assert structure [17]
-- [ ] No flaky patterns [11][18]
+- [ ] Test names describe expected behavior
+- [ ] Tests follow Arrange-Act-Assert structure
+- [ ] No flaky patterns