@therocketcode/gsd-core 1.4.0

package/gsd-core/references/sketch-variant-patterns.md

@@ -0,0 +1,81 @@
+# Multi-Variant HTML Patterns
+
+Every sketch produces 2-3 variants in the same HTML file. The user switches between them to compare.
+
+## Tab-Based Variants
+
+The standard approach: a tab bar at the top of the page, each tab shows a different variant.
+
+```html
+<div id="variant-nav" style="position:fixed;top:0;left:0;right:0;z-index:9998;background:var(--color-surface, #fff);border-bottom:1px solid var(--color-border, #e5e5e5);padding:8px 16px;display:flex;gap:8px;font-family:system-ui;">
+  <button class="variant-tab active" onclick="showVariant('a')">A: Sidebar Layout</button>
+  <button class="variant-tab" onclick="showVariant('b')">B: Top Nav</button>
+  <button class="variant-tab" onclick="showVariant('c')">C: Floating Panels</button>
+</div>
+
+<div id="variant-a" class="variant active">
+  <!-- Variant A content -->
+</div>
+<div id="variant-b" class="variant" style="display:none">
+  <!-- Variant B content -->
+</div>
+<div id="variant-c" class="variant" style="display:none">
+  <!-- Variant C content -->
+</div>
+
+<script>
+function showVariant(id) {
+  document.querySelectorAll('.variant').forEach(v => v.style.display = 'none');
+  document.querySelectorAll('.variant-tab').forEach(t => t.classList.remove('active'));
+  document.getElementById('variant-' + id).style.display = 'block';
+  event.target.classList.add('active');
+}
+</script>
+```
+
+Add `padding-top` to the body to account for the fixed tab bar.
+
+## Marking the Winner
+
+After the user picks a direction, add a visual indicator to the winning tab:
+
+```html
+<button class="variant-tab active">A: Sidebar Layout ★ Selected</button>
+```
+
+Keep all variants visible and navigable — the winner is highlighted, not the only option.
+
+## Side-by-Side (for small variants)
+
+When comparing small elements (button styles, card layouts, icon treatments), render them next to each other with labels rather than using tabs:
+
+```html
+<div style="display:grid;grid-template-columns:repeat(3,1fr);gap:24px;padding:24px;">
+  <div>
+    <h3>A: Rounded</h3>
+    <!-- variant content -->
+  </div>
+  <div>
+    <h3>B: Sharp</h3>
+    <!-- variant content -->
+  </div>
+  <div>
+    <h3>C: Pill</h3>
+    <!-- variant content -->
+  </div>
+</div>
+```
+
+## Variant Count
+
+- **First round (dramatic):** 2-3 meaningfully different approaches
+- **Refinement rounds:** 2-3 subtle variations within the chosen direction
+- **Never more than 4** — more than that overwhelms. If there are 5+ options, narrow before showing.
+
+## Synthesis Variants
+
+When the user cherry-picks elements across variants, create a new variant tab labeled descriptively:
+
+```html
+<button class="variant-tab" onclick="showVariant('synth1')">Synthesis: A's layout + C's palette</button>
+```

package/gsd-core/references/spidr-splitting.md

@@ -0,0 +1,69 @@
+# SPIDR Story Splitting Rules
+
+> Used by `mvp-phase` workflow when the user-supplied story is too large for a single phase. Per PRD decision Q3, SPIDR runs as a **full interactive flow** — not a lightweight check.
+
+## When SPIDR triggers
+
+Trigger SPIDR splitting if **any** of these size signals fire on the user story:
+
+1. **Compound capabilities.** The story names two or more independent user actions joined by "and" (e.g., "register **and** log in **and** reset their password"). Each "and" is a candidate split point.
+2. **Multi-actor.** The story names more than one `[user role]` (e.g., "As a user or admin..."). Each role is a candidate split.
+3. **Length.** The assembled story exceeds ~120 chars on a single line.
+4. **Vague capability.** The capability is a noun phrase, not a verb-noun pair (e.g., "I want to use the dashboard" — needs to specify *which interaction* with the dashboard).
+
+If none of these fire, skip SPIDR entirely and proceed to ROADMAP write.
+
+## The five SPIDR axes
+
+For each axis, ask one targeted question. The user picks the axis that best fits their story; only one axis is applied per split.
+
+### Spike
+
+> "Is there an unknown that needs research before this can be implemented? If so, the spike is its own phase."
+
+If yes: split out a research phase (no acceptance criteria except "we know enough to plan the rest"). The remaining story becomes a follow-up phase.
+
+### Paths
+
+> "Does this feature have a happy path and one or more error/edge paths?"
+
+If yes: split happy path into the first phase, edge paths into follow-ups. Order: happy path first (it proves the slice works), then progressively edge cases.
+
+### Interfaces
+
+> "Does this feature need to work on more than one interface (web, mobile, API, CLI)?"
+
+If yes: split by interface. Web first if user-facing; API first if integration-driven; mobile last unless it's the primary platform.
+
+### Data
+
+> "Does this feature touch multiple data scopes (one user vs. many, single team vs. multi-tenant, small CSV vs. large dataset)?"
+
+If yes: split by scope. Smallest scope first (one user, single team, small data), then expand.
+
+### Rules
+
+> "Does this feature have multiple business rules that could be added incrementally (basic validation first, then complex policy)?"
+
+If yes: split by rule complexity. Minimum viable rules first; complex policy in follow-ups.
+
+## Workflow
+
+When SPIDR triggers, the workflow:
+
+1. Restates the user-supplied story.
+2. Asks "Which SPIDR axis fits best?" with the five options above.
+3. Walks through the chosen axis interactively (one focused question), produces a split proposal: "Phase N (this one): X. Phase N+1: Y. Phase N+2: Z."
+4. Confirms the split with the user.
+5. On accept: writes the FIRST phase's story to the current ROADMAP entry; defers creating new phases for the splits to a follow-up step (the workflow surfaces a list of `/gsd add-phase` invocations the user can run after `mvp-phase` completes — but does not run them automatically, to preserve user control over phase numbering).
+6. On reject: proceeds with the original story unchanged.
+
+## Anti-patterns to reject
+
+- **Splitting by technical layer.** "Phase 1: schema. Phase 2: API. Phase 3: UI." That's horizontal planning. Reject.
+- **Pre-splitting before the user even sees the original.** Always show the user-supplied story first; only offer split if it triggers a size signal.
+- **Splitting more than one axis at once.** SPIDR is one axis per split. If a story needs splitting on two axes (e.g., paths AND data), do paths first, then re-evaluate the resulting smaller stories.
+
+## Reference
+
+See [Mike Cohn — Five Simple But Powerful Ways to Split User Stories](https://www.mountaingoatsoftware.com/blog/five-simple-but-powerful-ways-to-split-user-stories).

package/gsd-core/references/tdd.md

@@ -0,0 +1,330 @@
+<overview>
+TDD is about design quality, not coverage metrics. The red-green-refactor cycle forces you to think about behavior before implementation, producing cleaner interfaces and more testable code.
+
+**Principle:** If you can describe the behavior as `expect(fn(input)).toBe(output)` before writing `fn`, TDD improves the result.
+
+**Key insight:** TDD work is fundamentally heavier than standard tasks—it requires 2-3 execution cycles (RED → GREEN → REFACTOR), each with file reads, test runs, and potential debugging. TDD features get dedicated plans to ensure full context is available throughout the cycle.
+</overview>
+
+<when_to_use_tdd>
+## When TDD Improves Quality
+
+**TDD candidates (create a TDD plan):**
+- Business logic with defined inputs/outputs
+- API endpoints with request/response contracts
+- Data transformations, parsing, formatting
+- Validation rules and constraints
+- Algorithms with testable behavior
+- State machines and workflows
+- Utility functions with clear specifications
+
+**Skip TDD (use standard plan with `type="auto"` tasks):**
+- UI layout, styling, visual components
+- Configuration changes
+- Glue code connecting existing components
+- One-off scripts and migrations
+- Simple CRUD with no business logic
+- Exploratory prototyping
+
+**Heuristic:** Can you write `expect(fn(input)).toBe(output)` before writing `fn`?
+→ Yes: Create a TDD plan
+→ No: Use standard plan, add tests after if needed
+</when_to_use_tdd>
+
+<tdd_plan_structure>
+## TDD Plan Structure
+
+Each TDD plan implements **one feature** through the full RED-GREEN-REFACTOR cycle.
+
+```markdown
+---
+phase: XX-name
+plan: NN
+type: tdd
+---
+
+<objective>
+[What feature and why]
+Purpose: [Design benefit of TDD for this feature]
+Output: [Working, tested feature]
+</objective>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@relevant/source/files.ts
+</context>
+
+<feature>
+  <name>[Feature name]</name>
+  <files>[source file, test file]</files>
+  <behavior>
+    [Expected behavior in testable terms]
+    Cases: input → expected output
+  </behavior>
+  <implementation>[How to implement once tests pass]</implementation>
+</feature>
+
+<verification>
+[Test command that proves feature works]
+</verification>
+
+<success_criteria>
+- Failing test written and committed
+- Implementation passes test
+- Refactor complete (if needed)
+- All 2-3 commits present
+</success_criteria>
+
+<output>
+After completion, create SUMMARY.md with:
+- RED: What test was written, why it failed
+- GREEN: What implementation made it pass
+- REFACTOR: What cleanup was done (if any)
+- Commits: List of commits produced
+</output>
+```
+
+**One feature per TDD plan.** If features are trivial enough to batch, they're trivial enough to skip TDD—use a standard plan and add tests after.
+</tdd_plan_structure>
+
+<execution_flow>
+## Red-Green-Refactor Cycle
+
+**RED - Write failing test:**
+1. Create test file following project conventions
+2. Write test describing expected behavior (from `<behavior>` element)
+3. Run test - it MUST fail
+4. If test passes: feature exists or test is wrong. Investigate.
+5. Commit: `test({phase}-{plan}): add failing test for [feature]`
+
+**GREEN - Implement to pass:**
+1. Write minimal code to make test pass
+2. No cleverness, no optimization - just make it work
+3. Run test - it MUST pass
+4. Commit: `feat({phase}-{plan}): implement [feature]`
+
+**REFACTOR (if needed):**
+1. Clean up implementation if obvious improvements exist
+2. Run tests - MUST still pass
+3. Only commit if changes made: `refactor({phase}-{plan}): clean up [feature]`
+
+**Result:** Each TDD plan produces 2-3 atomic commits.
+</execution_flow>
+
+<test_quality>
+## Good Tests vs Bad Tests
+
+**Test behavior, not implementation:**
+- Good: "returns formatted date string"
+- Bad: "calls formatDate helper with correct params"
+- Tests should survive refactors
+
+**One concept per test:**
+- Good: Separate tests for valid input, empty input, malformed input
+- Bad: Single test checking all edge cases with multiple assertions
+
+**Descriptive names:**
+- Good: "should reject empty email", "returns null for invalid ID"
+- Bad: "test1", "handles error", "works correctly"
+
+**No implementation details:**
+- Good: Test public API, observable behavior
+- Bad: Mock internals, test private methods, assert on internal state
+</test_quality>
+
+<framework_setup>
+## Test Framework Setup (If None Exists)
+
+When executing a TDD plan but no test framework is configured, set it up as part of the RED phase:
+
+**1. Detect project type:**
+```bash
+# JavaScript/TypeScript
+if [ -f package.json ]; then echo "node"; fi
+
+# Python
+if [ -f requirements.txt ] || [ -f pyproject.toml ]; then echo "python"; fi
+
+# Go
+if [ -f go.mod ]; then echo "go"; fi
+
+# Rust
+if [ -f Cargo.toml ]; then echo "rust"; fi
+```
+
+**2. Install minimal framework:**
+| Project | Framework | Install |
+|---------|-----------|---------|
+| Node.js | Jest | `npm install -D jest @types/jest ts-jest` |
+| Node.js (Vite) | Vitest | `npm install -D vitest` |
+| Python | pytest | `pip install pytest` |
+| Go | testing | Built-in |
+| Rust | cargo test | Built-in |
+
+**3. Create config if needed:**
+- Jest: `jest.config.js` with ts-jest preset
+- Vitest: `vitest.config.ts` with test globals
+- pytest: `pytest.ini` or `pyproject.toml` section
+
+**4. Verify setup:**
+```bash
+# Run empty test suite - should pass with 0 tests
+npm test  # Node
+pytest    # Python
+go test ./...  # Go
+cargo test    # Rust
+```
+
+**5. Create first test file:**
+Follow project conventions for test location:
+- `*.test.ts` / `*.spec.ts` next to source
+- `__tests__/` directory
+- `tests/` directory at root
+
+Framework setup is a one-time cost included in the first TDD plan's RED phase.
+</framework_setup>
+
+<error_handling>
+## Error Handling
+
+**Test doesn't fail in RED phase:**
+- Feature may already exist - investigate
+- Test may be wrong (not testing what you think)
+- Fix before proceeding
+
+**Test doesn't pass in GREEN phase:**
+- Debug implementation
+- Don't skip to refactor
+- Keep iterating until green
+
+**Tests fail in REFACTOR phase:**
+- Undo refactor
+- Commit was premature
+- Refactor in smaller steps
+
+**Unrelated tests break:**
+- Stop and investigate
+- May indicate coupling issue
+- Fix before proceeding
+</error_handling>
+
+<commit_pattern>
+## Commit Pattern for TDD Plans
+
+TDD plans produce 2-3 atomic commits (one per phase):
+
+```
+test(08-02): add failing test for email validation
+
+- Tests valid email formats accepted
+- Tests invalid formats rejected
+- Tests empty input handling
+
+feat(08-02): implement email validation
+
+- Regex pattern matches RFC 5322
+- Returns boolean for validity
+- Handles edge cases (empty, null)
+
+refactor(08-02): extract regex to constant (optional)
+
+- Moved pattern to EMAIL_REGEX constant
+- No behavior changes
+- Tests still pass
+```
+
+**Comparison with standard plans:**
+- Standard plans: 1 commit per task, 2-4 commits per plan
+- TDD plans: 2-3 commits for single feature
+
+Both follow same format: `{type}({phase}-{plan}): {description}`
+
+**Benefits:**
+- Each commit independently revertable
+- Git bisect works at commit level
+- Clear history showing TDD discipline
+- Consistent with overall commit strategy
+</commit_pattern>
+
+<gate_enforcement>
+## Gate Enforcement Rules
+
+When `workflow.tdd_mode` is enabled in config, the RED/GREEN/REFACTOR gate sequence is enforced for all `type: tdd` plans.
+
+### Gate Definitions
+
+| Gate | Required | Commit Pattern | Validation |
+|------|----------|---------------|------------|
+| RED | Yes | `test({phase}-{plan}): ...` | Test exists AND fails before implementation |
+| GREEN | Yes | `feat({phase}-{plan}): ...` | Test passes after implementation |
+| REFACTOR | No | `refactor({phase}-{plan}): ...` | Tests still pass after cleanup |
+
+### Fail-Fast Rules
+
+1. **Unexpected GREEN in RED phase:** If the test passes before any implementation code is written, STOP. The feature may already exist or the test is wrong. Investigate before proceeding.
+2. **Missing RED commit:** If no `test(...)` commit precedes the `feat(...)` commit, the TDD discipline was violated. Flag in SUMMARY.md.
+3. **REFACTOR breaks tests:** Undo the refactor immediately. Commit was premature — refactor in smaller steps.
+
+### Executor Gate Validation
+
+After completing a `type: tdd` plan, the executor validates the git log:
+```bash
+# Check for RED gate commit
+git log --oneline --grep="^test(${PHASE}-${PLAN})" | head -1
+# Check for GREEN gate commit  
+git log --oneline --grep="^feat(${PHASE}-${PLAN})" | head -1
+# Check for optional REFACTOR gate commit
+git log --oneline --grep="^refactor(${PHASE}-${PLAN})" | head -1
+```
+
+If RED or GREEN gate commits are missing, add a `## TDD Gate Compliance` section to SUMMARY.md with the violation details.
+</gate_enforcement>
+
+<end_of_phase_review>
+## End-of-Phase TDD Review Checkpoint
+
+When `workflow.tdd_mode` is enabled, the execute-phase orchestrator inserts a collaborative review checkpoint after all waves complete but before phase verification.
+
+### Review Checkpoint Format
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ TDD REVIEW — Phase {X}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+TDD Plans: {count} | Gate violations: {count}
+
+| Plan | RED | GREEN | REFACTOR | Status |
+|------|-----|-------|----------|--------|
+| {id} |  ✓  |   ✓   |    ✓     | Pass   |
+| {id} |  ✓  |   ✗   |    —     | FAIL   |
+
+{If violations exist:}
+⚠ Gate violations are advisory — review before advancing.
+```
+
+### What the Review Checks
+
+1. **Gate sequence:** Each TDD plan has RED → GREEN commits in order
+2. **Test quality:** RED phase tests fail for the right reason (not import errors or syntax)
+3. **Minimal GREEN:** Implementation is minimal — no premature optimization in GREEN phase
+4. **Refactor discipline:** If REFACTOR commit exists, tests still pass
+
+This checkpoint is advisory — it does not block phase completion but surfaces TDD discipline issues for human review.
+</end_of_phase_review>
+
+<context_budget>
+## Context Budget
+
+TDD plans target **~40% context usage** (lower than standard plans' ~50%).
+
+Why lower:
+- RED phase: write test, run test, potentially debug why it didn't fail
+- GREEN phase: implement, run test, potentially iterate on failures
+- REFACTOR phase: modify code, run tests, verify no regressions
+
+Each phase involves reading files, running commands, analyzing output. The back-and-forth is inherently heavier than linear task execution.
+
+Single feature focus ensures full quality throughout the cycle.
+</context_budget>

package/gsd-core/references/test-containers.md

@@ -0,0 +1,55 @@
+# Testcontainers — Real Dependencies in Integration Tests
+
+How-to reference for spinning up real databases/services (Postgres, Redis, etc.) in integration tests with Testcontainers. Read this when writing integration tests against a real dependency. Pairs with `db-test-isolation.md`.
+
+## Core rules
+
+1. **Pin exact image tags** — `postgres:16-alpine`, never `latest` (reproducibility).
+2. **Singleton container, started once** — one container per test run, reused across all test files/classes. Do **not** combine the singleton with per-class lifecycle annotations/extensions (they stop the container after each class and break the next one).
+3. **Wait on a real readiness signal, never `sleep`** — a health check, a log message, or a DB-ready probe.
+4. **`withReuse` is local-dev-only** — it keeps containers alive between runs (fast inner loop), but **Ryuk does not reap reused containers**, and CI wants fresh, reproducible environments. **Never enable reuse in CI.**
+5. **Run migrations in test setup** so schema drift surfaces immediately.
+
+## Canonical pattern (TypeScript/Node — ports to Java/Go/.NET)
+
+```ts
+// test/support/postgres.ts — one container, started once for the whole run
+import { PostgreSqlContainer, StartedPostgreSqlContainer } from '@testcontainers/postgresql';
+
+let container: StartedPostgreSqlContainer | undefined;
+
+export async function getDb(): Promise<StartedPostgreSqlContainer> {
+  if (!container) {
+    container = await new PostgreSqlContainer('postgres:16-alpine') // pinned tag, never :latest
+      .withDatabase('app_test')
+      // built-in wait for postgres; for custom services:
+      // .withWaitStrategy(Wait.forLogMessage(/ready to accept connections/))
+      .start();
+    // run migrations ONCE here, against the base/template DB
+  }
+  return container;
+}
+// Vitest/Jest: start in globalSetup, stop in globalTeardown — NOT in beforeEach.
+```
+
+Java/JUnit 5 equivalent: a `static` field started in a `static {}` block on an abstract base class every test class `extends` — and do **not** put `@Container`/`@Testcontainers` on it (that hands lifecycle to the extension, which stops it per class).
+
+## Cleanup
+
+Testcontainers labels its containers; **Ryuk** removes them when the run's process exits — an explicit `stop()` is optional. Reused containers are the exception (not reaped).
+
+## CI considerations
+
+- **Ryuk under Docker-in-Docker / restricted CI** sometimes fails. Mitigate: set `TESTCONTAINERS_RYUK_DISABLED=true` **and** add an explicit cleanup step — `docker container prune -f --filter "label=org.testcontainers=true"` (or stop containers in global teardown).
+- Cache Docker layers; prefer `alpine` images; cap memory on heavy services (e.g. Elasticsearch `ES_JAVA_OPTS=-Xms512m -Xmx1g`).
+- **First run pulls the image** — pre-pull images in CI, or set a generous `withStartupTimeout(...)`, so the first test doesn't time out on a cold pull.
+- **Parallelize at the file level**, not within a file, to bound container count and resource use.
+
+## Anti-patterns
+
+- `:latest` image tags (non-reproducible).
+- A fresh container per test (slow — use the singleton + per-test **data** isolation, see `db-test-isolation.md`).
+- `sleep(2000)` for readiness (flaky) — use a wait strategy.
+- `withReuse(true)` in CI (leaks containers; not reproducible).
+
+*Sources: testcontainers.com & Docker Testcontainers official guides; qaskills 2026 best practices.*

package/gsd-core/references/test-strategy.md

@@ -0,0 +1,75 @@
+# Testing Strategy — Shape Follows Architecture
+
+Reference for `/gsd:testing-strategy`. Decides WHAT to test, at WHICH level, and HOW MUCH — matched to the architecture (from the ADR / SKELETON). **Extends, not replaces,** the project's existing rigor in `TESTING-STANDARDS.md` (real-code-only, no-vacuous-assertions, typed surface, `fast-check` property tests, Stryker mutation ≥80%). Recommends; the user decides.
+
+## Core principles (the consensus)
+
+1. **Behavior over implementation — the strongest consensus.** Test through public APIs / observable behavior so tests survive refactoring; a test changes only when *behavior* changes. Default to **sociable** tests (real collaborators); **mock ONLY at architectural boundaries** (ports / external systems). Mockist/solitary tests are exactly the brittle, implementation-coupled tests everyone warns against.
+2. **Test each behavior ONCE, at the cheapest level that gives confidence.** Push tests down; drop a higher-level test once lower levels cover the condition. Avoid the **ice-cream cone** (mostly e2e) and **hourglass** (no integration) anti-patterns.
+3. **Coverage is a FLOOR, not a target.** High line coverage is a vanity metric ("a line ran" ≠ "a line is asserted"). Use **mutation testing** (Stryker — already in the project) on critical modules to prove the assertions actually check something; use coverage as the allow-list of what to mutate.
+4. **Shape FOLLOWS architecture — framed correctly.** Don't "pick the diamond/pyramid/trophy." The architecture determines where the testable behavior *lives* → the shape **emerges**. Reason in test **size** (Google): *small* (in-process, no I/O) / *medium* (localhost, real DB) / *large* (multi-machine, e2e).
+
+## Shape follows architecture (consume the ADR)
+
+Read the architecture decision (`.planning/adr/*.md` or SKELETON). Per subdomain / Axis-A rung:
+
+| Architecture (per subdomain) | Primary test level | Why |
+|---|---|---|
+| **Domain Model / rich core** | more **small (unit)** tests of the domain logic, through its public API | lots of pure logic, few dependencies — cheap and high-value to unit-test |
+| **Transaction Script / CRUD-over-DB** | more **medium (integration)** tests against a real DB | thin logic, DB-bound — little pure logic to isolate; confidence lives at the DB boundary |
+| **Hexagonal core** | unit-test the domain in isolation (no mocks — it's pure); integration-test the **adapters** against real systems | the architecture literally separates the two |
+| **Many integrations / external APIs** | medium integration tests at the ports; **contract tests** where a 3rd-party can't be seeded | confidence is in the integration, not mock existence |
+| **Bought / off-the-shelf (Generic)** | thin integration smoke at your adapter seam only | don't test the vendor's internals — test your seam |
+
+The resulting distribution is an **output** (pyramid-ish for logic-heavy, diamond/trophy-ish for integration-heavy) — never an input you pick.
+
+## When unit tests pay off (the gnarly bits)
+
+Pure, dependency-light, logic-dense code: **money/currency (integer minor units or exact decimal — NEVER binary float)**, complex conditionals / **state machines**, **parsers**, **algorithms**, pure functions. High branching, cheap to unit-test. Do **not** unit-test trivial glue, getters/setters, or framework code.
+
+## What NOT to test / avoiding duplicate coverage
+
+- Don't test the same behavior at unit AND integration AND e2e — each behavior once, at the cheapest level.
+- Don't test framework/library code, trivial accessors, or **mock behavior** (testing a mock means you violated behavior-testing).
+- Don't chase a coverage % as a goal; chase behavior coverage + mutation score on critical modules.
+
+## TDD — honestly
+
+The quality benefit is real, but the evidence favors **small, uniform increments** over *test-first specifically* (controlled studies found test-first vs test-after didn't differ; granularity did). So **mandate: behavior-level tests + small increments + a regression floor.** Keep the **RED step** (watch a test fail) so tests actually test something. Test-first vs test-after is a **knob** (`workflow.tdd_mode`), not dogma.
+
+## Persistent vs transient E2E
+
+- **Persistent:** a small **smoke / critical-user-journey** suite (auth, payment, core nav) in CI on every PR (<5 min). Keep it lean (≈50–200 well-chosen e2e tests) — e2e is slow/flaky; push coverage down to integration.
+- **Transient:** throwaway e2e to validate a freshly-built flow during the dev loop; **not** kept in CI. Once the behavior is covered more cheaply (integration), delete or demote it.
+
+## Output (`TEST-STRATEGY.md`)
+
+- Per subdomain/component: the recommended level emphasis (small/medium/large) + the architecture rung that justifies it.
+- The critical-path e2e **smoke list** (persistent).
+- What to unit-test (the gnarly bits) and what **not** to test.
+- Coverage stance (floor) + where mutation testing applies.
+- TDD stance (behavior + small increments; test-first knob).
+
+Feeds `add-tests`, `execute-phase`, and `plan-phase`.
+
+## Extends existing rigor (keep it all)
+
+`TESTING-STANDARDS.md` already enforces real-code-only, no-vacuous-assertions, the typed-surface mandate, `fast-check` property tests for bijective/invariant logic, and Stryker mutation ≥80% on critical modules. This skill adds the **strategic layer** on top — the shape, the what/what-not, the level-per-subdomain. Do not weaken any existing standard.
+
+## Test-infrastructure how-to references (read when writing the tests)
+
+When the strategy calls for real-dependency integration tests, auth, or e2e, load the focused how-to reference:
+- `@~/.claude/gsd-core/references/test-containers.md` — real DBs/services via Testcontainers (singleton pattern, pinned tags, CI/Ryuk).
+- `@~/.claude/gsd-core/references/db-test-isolation.md` — parallel-safe DB isolation (template DB, db/schema-per-worker, txn rollback).
+- `@~/.claude/gsd-core/references/auth-in-tests.md` — authenticate-once/storageState, token minting, multi-role, JWT vs cookie, one-account-per-worker.
+- `@~/.claude/gsd-core/references/realistic-test-data.md` — synthetic factories by default; anonymized/subset dumps only.
+- `@~/.claude/gsd-core/references/e2e-tiering.md` — persistent smoke vs transient e2e; keep e2e lean.
+- `@~/.claude/gsd-core/references/flaky-test-checklist.md` — fixed clock, seeded RNG, poll-don't-sleep, per-worker isolation.
+
+## Anti-patterns
+
+- Picking a shape (pyramid/diamond/trophy) as an input instead of letting architecture determine it.
+- Mockist/solitary tests coupled to implementation → brittle, break on refactor.
+- Coverage % as a goal; duplicate coverage across levels.
+- A fat, slow e2e suite as the primary safety net (ice-cream cone).
+- `float` for money.

package/gsd-core/references/thinking-models-debug.md

@@ -0,0 +1,44 @@
+# Thinking Models: Debug Cluster
+
+Structured reasoning models for the **debugger** agent. Apply these at decision points during investigation, not continuously. Each model counters a specific documented failure mode.
+
+Source: Curated from [thinking-partner](https://github.com/mattnowdev/thinking-partner) model catalog (150+ models). Selected for direct applicability to GSD debugging workflow.
+
+## Conflict Resolution
+
+**Fault Tree and Hypothesis-Driven are sequential:** Fault Tree FIRST (generate the tree of possible causes), Hypothesis-Driven SECOND (test each branch systematically). Fault Tree provides the map; Hypothesis-Driven provides the discipline to traverse it.
+
+## 1. Fault Tree Analysis
+
+**Counters:** Jumping to conclusions without systematically mapping failure paths.
+
+Before testing any hypothesis, build a fault tree: start with the observed symptom as the root node, then branch into all possible causes at each level (hardware, software, configuration, data, environment). Use AND/OR gates -- some failures require multiple conditions (AND), others have independent triggers (OR). This tree becomes your investigation roadmap. Prioritize branches by likelihood and testability, but do NOT prune branches just because they seem unlikely -- unlikely causes that are easy to test should be tested early.
+
+## 2. Hypothesis-Driven Investigation
+
+**Counters:** Making random changes and hoping something works -- the "shotgun debugging" anti-pattern.
+
+For each hypothesis from the fault tree, follow the strict protocol: PREDICT ("If hypothesis H is correct, then test T should produce result R"), TEST (execute exactly one test), OBSERVE (record the actual result), CONCLUDE (matched = SUPPORTED, failed = ELIMINATED, unexpected = new evidence). Never skip the PREDICT step -- without a prediction, you cannot distinguish a meaningful result from noise. Never change more than one variable per test -- if you change two things and the bug disappears, you don't know which change fixed it.
+
+## 3. Occam's Razor
+
+**Counters:** Pursuing elaborate explanations when simple ones have not been ruled out.
+
+Before investigating complex multi-component interaction bugs, race conditions, or framework-level issues, verify the simple explanations first: typo in variable name, wrong file path, missing import, incorrect config value, stale cache, wrong environment variable. These "boring" causes account for the majority of bugs. Only escalate to complex hypotheses AFTER the simple ones are eliminated. If your current hypothesis requires 3+ things to go wrong simultaneously, step back and look for a single-point failure.
+
+## 4. Counterfactual Thinking
+
+**Counters:** Failing to isolate causation by not asking "what if we changed just this one thing?"
+
+When you have a hypothesis about the root cause, construct a counterfactual: "If I change ONLY this one variable/config/line, the bug should disappear (or appear)." Execute the counterfactual test. If the bug persists after your targeted change, your hypothesis is wrong -- the cause is elsewhere. If the bug disappears, you have strong causal evidence. This is more powerful than correlation ("the bug appeared after deploy X") because it tests the mechanism, not just the timeline.
+
+---
+
+## When NOT to Think
+
+Skip structured reasoning models when the situation does not benefit from them:
+
+- **Obvious single-cause bugs** -- If the error message names the exact file, line, and cause (e.g., `TypeError: Cannot read property 'x' of undefined at foo.js:42`), fix it directly. Do not build a fault tree for a null reference with a stack trace.
+- **Reproducing a known fix** -- If you already know the root cause from a previous investigation or the user told you exactly what is wrong, skip hypothesis-driven investigation and go straight to the fix.
+- **Typos, missing imports, wrong paths** -- If Occam's Razor would immediately resolve it, apply the fix without invoking the full model. The model exists for when simple checks fail, not to gate simple checks.
+- **Reading error logs** -- Reading and understanding error output is normal debugging, not a "decision point." Only invoke models when you have multiple plausible hypotheses and need to choose which to test first.