wdi-method 0.3.0

package/kit/skills/wdi-review/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: wdi-review
+description: Use to review any corpus document at any time, and always before a gate on the four artifacts no doc_standards covers — the architecture spine, SRS, SDD, and SPEC. Reads the lens set from the component's risk_accepted, dispatches bmad-review, and stamps the V13 trace on those four only. Not for code review.
+---
+
+# WDI Review
+
+Five BMad skills review their own output through `doc_standards`. Four artifacts have no such trigger,
+and they are the most binding ones in the corpus. This skill covers exactly those four.
+
+It exists for two reasons `bmad-review` cannot serve on its own: the lens set is not a property of the
+artifact but of the component's `risk_accepted`, and defaulting to structure + prose silently drops the
+one lens that matters for behaviour; and `bmad-review` is class D — it writes nothing, so nothing proves
+it ran.
+
+You MUST NOT use this for code or diffs. That is `bmad-code-review` and the two-family Review Panel.
+
+## What it covers
+
+| Artifact | Trace lands in |
+|---|---|
+| `.how/_platform/ARCHITECTURE-SPINE.md` | `reviewed:` in its frontmatter |
+| `SRS-<pc>.md` + slots `02`–`05` | `reviewed:` in the SRS frontmatter |
+| `SDD-<pc>.md` + slots `01`–`06` | `reviewed:` in the SDD frontmatter |
+| `SPEC.md` | `spec_reviewed:` on the wave in `waves.yaml` |
+
+**The lens set comes from the component's `risk_accepted`, never from `mode` and never from the artifact
+type.** `delivery-flow-guide.md` owns the mapping and it MUST NOT be restated as a second copy here; what
+this skill owns is reading it and refusing to run a lighter set than it names.
+
+| `risk_accepted` | Lenses | And on the code |
+|---|---|---|
+| `low` | structure · prose · **edge-case-hunter** | a two-reviewer panel is required |
+| `medium` | structure · prose · **edge-case-hunter** | — |
+| `high` | structure · prose | — |
+
+`SPEC.md` always carries `edge-case-hunter`: it is the contract a builder works from, and a branch missed
+there surfaces as a bug at G5 instead.
+
+**V13 stamps only components at `risk_accepted` `low` or `medium`.** At `high` the owner has already said
+they accept the risk, and demanding the trace there is bookkeeping with no buyer.
+
+SPEC keeps its trace in the registry because `bmad-spec` is its sole author and overwrites hand
+edits. A trace written into `SPEC.md` disappears on the next run.
+
+**Anything in the corpus MAY be reviewed here, at any time** — a `DEC-`, minutes, an `OQ-`, a guide, a
+brief, a PRD, a `DESIGN.md`. What is restricted is the **stamp**, not the reading: only the four rows
+above have a trace V13 reads, and only they MAY be stamped.
+
+The five artifacts carrying `doc_standards` review themselves at finalize, so a review here is never
+required for them. Asking for one anyway is legitimate — after hand edits, before a gate, when a
+finding is suspected — and it MUST NOT leave a `reviewed:` block behind. A second trace on an
+artifact whose first review is automatic implies that first one was optional.
+
+## Step 1 — Read the lens set off the component
+
+Find the artifact's component, read its `risk_accepted` from `components.yaml`, and state the lens set in
+one line before dispatching. Do not ask the user which lenses to run — the field decides, and it is the
+owner's field.
+
+For an artifact with no component — a guide, minutes, the spine — use structure · prose.
+
+The adversarial lens is in no table. It MAY be added when the artifact touches money, personal data, or a
+third-party integration. It demands at least ten concrete findings and treats an empty result as a signal
+to re-check, so adding it to a routine review buys noise.
+
+## Step 2 — Dispatch
+
+Invoke `bmad-review` with the artifact path and the chosen lenses. Slots are part of the artifact:
+reviewing `SRS-<pc>.md` without `04-usecases/` and `05-scenarios/` reviews the kernel and misses
+where the branches live.
+
+## Step 3 — Resolve before stamping
+
+Findings MUST be resolved or explicitly deferred before the trace is written. A deferred finding
+MUST be filed through `wdi-question`, or opened as a `DEC-` through `wdi-decision` — never a note in the
+chat that dies with the session.
+
+You MUST NOT stamp an artifact whose findings are still open. A trace on unresolved findings is
+worse than no trace: V13 goes green and the gate opens on a review nobody acted on.
+
+## Step 4 — Stamp
+
+Write the trace, and nothing else:
+
+```yaml
+reviewed:
+  date: '<YYYY-MM-DD>'
+  sha: '<commit sha at review time>'
+  lenses: [structure, prose, edge-case-hunter]
+```
+
+- `sha` MUST be the commit the artifact was reviewed at. Without it staleness cannot be measured, only
+  felt — the same reason a structure map requires one. V13 no longer reads the stamping commit itself as
+  a change, so a fresh stamp does not make its own review look stale.
+- You MUST NOT write the trace unless `bmad-review` actually ran in this session. Filling it as a
+  formality turns V13 into a rubber stamp, which is worse than having no validator.
+- You MUST NOT touch `status:` while stamping. `status: reviewed` states a **stage**; the `reviewed:`
+  block states an **event**. Raising the status is a separate act.
+- You MUST NOT edit the artifact's content. Fixing a finding is the author's act, not the
+  reviewer's — say what is wrong and stop.
+
+## Rules
+
+- You MUST NOT stamp anything outside the four rows in the table. Brief, PRD, `DESIGN.md`,
+  `EXPERIENCE.md`, and research MAY be reviewed on request; the finding report is the whole output,
+  and no `reviewed:` block is written.
+- You MUST NOT stamp on behalf of a review someone else ran earlier. Re-run it; the run is cheap and
+  the claim is not.
+- When the artifact changed after the review, the trace is stale by definition. You MUST re-run
+  rather than bump the date.
+- When findings reveal the requirement itself is wrong rather than the writing, this stops being a
+  review. Route to `wdi-decision`, and let the `DEC-` change the artifact.
+
+## Output
+
+One short report: artifact, lenses run, findings by severity, what was resolved, what was deferred
+and where it landed, and whether the trace was written — with the reason when it was not.

package/kit/skills/wdi-systematic-debugging/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: wdi-systematic-debugging
+description: Use when encountering any bug, test failure, build failure, or unexpected behavior, before proposing any fix. Covers root-cause investigation, hypothesis testing, and the escalation rule when repeated fixes fail.
+---
+
+# Systematic Debugging
+
+BMad has no debugging workflow — `bmad-build` assumes you already know what to build. This skill
+covers the gap: something is broken and the cause is unknown.
+
+## The Iron Law
+
+**NO FIX WITHOUT ROOT CAUSE INVESTIGATION FIRST.**
+
+You MUST complete Phase 1 before proposing any fix. A fix that treats a symptom is a failure even
+when the symptom disappears.
+
+## When to use
+
+Use for any technical issue: test failure, production bug, unexpected behavior, performance problem,
+build failure, integration failure.
+
+**Its home is G5, but its trigger is not positional.** Most invocations happen while coding, and
+that is why `AGENTS.md`, `bmad-build`, and the ship-story orchestration carry this rule in their
+worker context. What actually fires it is a pair of conditions — *something is broken* **and** *the
+cause is unknown* — so it MAY be invoked in any stage, by anyone, to investigate: a red
+`validate.py` while writing an SRS at G3, a `wdi-reconcile` report that makes no sense, a
+generator producing an empty timeline. None of those wait for G5, and none of them are a
+misuse of this skill.
+
+The second condition matters as much as the first. A test failing because of a missing import is not
+a trigger — you already know the cause. A test failing for a reason you cannot name is.
+
+Nor does the finding always land in code: three of the four `root_cause` categories send it back to
+`.what/` or `.how/` — see [Where the finding lands](#where-the-finding-lands).
+
+Use it *especially* when the pressure argues against it — an emergency, an "obvious one-line fix", a
+previous fix that did not hold. Systematic debugging is faster than guess-and-check, and the
+pressure cases are exactly where guessing costs the most.
+
+A simple-looking bug has a root cause too. You MUST NOT skip phases because the issue looks small.
+
+## Phase 1 — Root cause investigation
+
+1. **Read the error completely.** Full stack trace, line numbers, file paths, error codes. The
+   answer is often already in it.
+2. **Reproduce it.** Exact steps, every time. If it is not reproducible, gather more data — you
+   MUST NOT proceed on a guess.
+3. **Check what changed.** `git diff`, recent commits, new dependencies, config, environment.
+4. **Instrument the boundaries.** When more than one component is involved (browser → API →
+   service → database; CI → build → deploy), add logging at *each* boundary before proposing
+   anything: what enters, what exits, what config propagated. Run once to find *which* boundary
+   fails, then investigate only that one.
+5. **Trace the bad value backward** to where it originates — see
+   [references/root-cause-tracing.md](references/root-cause-tracing.md). Fix at the source, never
+   where the symptom surfaced.
+
+## Phase 2 — Pattern analysis
+
+1. Find working code in this repo that does the same kind of thing.
+2. Read the reference implementation **completely**. Skimming produces partial understanding, and
+   partial understanding produces the next bug.
+3. List every difference between working and broken, however small. You MUST NOT dismiss a
+   difference as irrelevant before testing it.
+4. Name the dependencies the broken path assumes: config, environment, state, ordering.
+
+## Phase 3 — Hypothesis
+
+1. State one hypothesis in writing: "X is the root cause because Y."
+2. Test it with the **smallest possible change**. One variable at a time.
+3. Worked → Phase 4. Did not work → form a *new* hypothesis. You MUST NOT stack a second fix on
+   top of a failed one.
+4. If you do not understand something, say so plainly and investigate further. Pretending to know
+   is what produces fix #4.
+
+## Phase 4 — Implementation
+
+1. **Write the failing test first.** Simplest reproduction that fails for the right reason. Run it
+   and confirm it fails before writing any fix. A fix without a test that failed first does not
+   stick and cannot be proven.
+2. **One fix, addressing the root cause.** No bundled refactoring, no "while I'm here" improvements.
+3. **Verify with evidence.** The test passes, no other test broke, and you have the command output
+   to show it. Claiming success without the output is prohibited.
+4. **If the fix fails, count your attempts.**
+   - Fewer than 3 → return to Phase 1 with what you now know.
+   - **3 or more → STOP. Do not attempt fix #4.**
+
+## Phase 5 — Record the finding
+
+An investigation that ends in chat has to be repeated. Before you close out — whether the fix landed
+or the three-fix rule stopped you — record what you found in `.control/registry/defects.yaml`. This
+is the only registry write this skill owns, and it exists so one question can be answered with a
+number rather than a memory: **how many of our defects turned out to be a wrong requirement rather
+than wrong code.**
+
+### Find the row, or open one
+
+A defect found by a tester is usually already there, carrying only `id`, `title`, `found_in`, and
+`reported`. Anyone MAY open such a row without running any skill, and an empty `root_cause` is a
+legitimate state meaning *not yet diagnosed* — you are the step that fills it, not the step that
+guards it. When no row exists, open one yourself, taking the next number in the `BUG-` sequence
+(`HOT-` when it arrived through the hotfix path).
+
+You MUST NOT require a row to exist before investigating. A defect nobody recorded is still a
+defect; refusing to work until the paperwork is right is how the file becomes a formality.
+
+### Write three fields, and only these three
+
+| Field | Where it comes from |
+|---|---|
+| `root_cause` | Your Phase 1–3 conclusion, in the four categories of the table above |
+| `violates` | The `FR-` or `UC-` the defect breaks. MUST be filled for `requirement` and `architecture`: a defect that violates something without naming what cannot be traced back to the corpus, and V20 fails it |
+| `fix` | `fastpath` for a pure code defect, the wave id otherwise. The table above already decides this — `requirement` and `architecture` MUST NOT be `fastpath` |
+
+You MUST NOT write a closure date. It is derived from the history of `defects.yaml` itself by
+`.constitution/scripts/timeline.py`, and a hand-written date would be a second home for one fact —
+the stored copy being the one that goes wrong.
+
+You MUST NOT edit `title`, `found_in`, or `reported`. Whoever opened the row owns those; correcting
+them silently erases what was actually reported.
+
+### `status: fixed` follows the route, not the merge
+
+The moment the patch merges is not the moment the defect closes. What closes it depends on the row's
+own `root_cause`:
+
+| `root_cause` | Closes when |
+|---|---|
+| `code` | The failing test from Phase 4 passes and the fix is merged |
+| `requirement` | The `FR-` or `UC-` in `violates` has actually changed — the code alone MUST NOT close it |
+| `architecture` | The `DEC-` is `accepted` and named on the row. V20 fails a `fixed` row without one |
+| `environment` | The handling is in place and the monitoring exists |
+
+Setting `fixed` before its row's condition is met is the failure this whole registry exists to
+prevent: it turns "we patched the code" into "the requirement was right all along".
+
+### When the three-fix rule stopped you
+
+You MUST still record. The rule triggering *is* the finding — `root_cause: architecture`, `violates`
+naming what the architecture broke, and the row left `open` until the `DEC-` exists. An escalation that
+leaves no trace looks identical to a bug that was never investigated.
+
+## The three-fix rule
+
+Three failed fixes is not three failed hypotheses — it is a signal that the architecture is wrong.
+
+Symptoms: each fix uncovers new coupling or shared state somewhere else; each fix needs "a bit of
+refactoring" to land; each fix creates a new symptom elsewhere.
+
+When this happens you MUST stop and raise it with the owner rather than continue. In this project's
+terms, the outcome is a `DEC-` — a correction of course is one too — not another patch.
+
+## Where the finding lands
+
+| What the root cause turns out to be | Where it goes |
+|---|---|
+| Genuine code defect, no artifact was wrong | Fast Path — fix, test, done |
+| A requirement was missing or wrong | Back to the Impact Matrix in `.constitution/document/delivery-flow-guide.md`; the FR/UC changes before the code does |
+| An architecture decision was wrong | `wdi-decision`, which wraps `bmad-correct-course`; MUST NOT be absorbed as a code patch |
+| Environmental, timing-dependent, or external | Document the investigation, implement handling (retry, timeout, clear error), add monitoring |
+
+These four categories are exactly the values of `root_cause` in `.control/registry/defects.yaml`.
+Phase 5 is where your verdict lands in that file.
+
+The last row is real but rare. Most "no root cause" conclusions are incomplete investigations —
+treat that verdict with suspicion in yourself.
+
+## Red flags — stop and return to Phase 1
+
+If you catch yourself thinking any of these, the process has already broken down:
+
+| Thought | Reality |
+|---|---|
+| "Quick fix now, investigate later" | The first fix sets the pattern. There is no later. |
+| "Just change X and see if it works" | That is guessing with extra steps. |
+| "It's probably X, let me fix that" | Seeing a symptom is not understanding a cause. |
+| "I'll skip the test and verify manually" | Untested fixes regress silently. |
+| "Several changes at once saves time" | You will not know which one worked, or what else broke. |
+| "The reference is long, I'll adapt the pattern" | Partial reading guarantees the next bug. |
+| "One more fix attempt" (after 2+) | Three failures means the architecture is the problem. |
+| "Emergency — no time for process" | Thrashing is slower. Always. |
+
+Signals from the owner that mean the same thing: *"stop guessing"*, *"is that actually
+happening?"*, *"will that show us anything?"*, *"we're stuck?"*
+
+## Supporting techniques
+
+| File | Use when |
+|---|---|
+| [references/root-cause-tracing.md](references/root-cause-tracing.md) | The error surfaces deep in a call stack and you must trace backward to the origin |
+| [references/defense-in-depth.md](references/defense-in-depth.md) | Root cause is found and you are deciding where validation belongs |
+| [references/condition-based-waiting.md](references/condition-based-waiting.md) | Flaky timing, arbitrary sleeps, race conditions |
+| [references/find-polluter.sh](references/find-polluter.sh) | A test passes alone but fails in the suite — bisects to find the polluting test |

package/kit/skills/wdi-systematic-debugging/references/condition-based-waiting.md

@@ -0,0 +1,115 @@
+# Condition-Based Waiting
+
+## Overview
+
+Flaky tests often guess at timing with arbitrary delays. This creates race conditions where tests pass on fast machines but fail under load or in CI.
+
+**Core principle:** Wait for the actual condition you care about, not a guess about how long it takes.
+
+## When to Use
+
+```dot
+digraph when_to_use {
+    "Test uses setTimeout/sleep?" [shape=diamond];
+    "Testing timing behavior?" [shape=diamond];
+    "Document WHY timeout needed" [shape=box];
+    "Use condition-based waiting" [shape=box];
+
+    "Test uses setTimeout/sleep?" -> "Testing timing behavior?" [label="yes"];
+    "Testing timing behavior?" -> "Document WHY timeout needed" [label="yes"];
+    "Testing timing behavior?" -> "Use condition-based waiting" [label="no"];
+}
+```
+
+**Use when:**
+- Tests have arbitrary delays (`setTimeout`, `sleep`, `time.sleep()`)
+- Tests are flaky (pass sometimes, fail under load)
+- Tests timeout when run in parallel
+- Waiting for async operations to complete
+
+**Don't use when:**
+- Testing actual timing behavior (debounce, throttle intervals)
+- Always document WHY if using arbitrary timeout
+
+## Core Pattern
+
+```typescript
+// ❌ BEFORE: Guessing at timing
+await new Promise(r => setTimeout(r, 50));
+const result = getResult();
+expect(result).toBeDefined();
+
+// ✅ AFTER: Waiting for condition
+await waitFor(() => getResult() !== undefined);
+const result = getResult();
+expect(result).toBeDefined();
+```
+
+## Quick Patterns
+
+| Scenario | Pattern |
+|----------|---------|
+| Wait for event | `waitFor(() => events.find(e => e.type === 'DONE'))` |
+| Wait for state | `waitFor(() => machine.state === 'ready')` |
+| Wait for count | `waitFor(() => items.length >= 5)` |
+| Wait for file | `waitFor(() => fs.existsSync(path))` |
+| Complex condition | `waitFor(() => obj.ready && obj.value > 10)` |
+
+## Implementation
+
+Generic polling function:
+```typescript
+async function waitFor<T>(
+  condition: () => T | undefined | null | false,
+  description: string,
+  timeoutMs = 5000
+): Promise<T> {
+  const startTime = Date.now();
+
+  while (true) {
+    const result = condition();
+    if (result) return result;
+
+    if (Date.now() - startTime > timeoutMs) {
+      throw new Error(`Timeout waiting for ${description} after ${timeoutMs}ms`);
+    }
+
+    await new Promise(r => setTimeout(r, 10)); // Poll every 10ms
+  }
+}
+```
+
+See `condition-based-waiting-example.ts` in this directory for complete implementation with domain-specific helpers (`waitForEvent`, `waitForEventCount`, `waitForEventMatch`) from actual debugging session.
+
+## Common Mistakes
+
+**❌ Polling too fast:** `setTimeout(check, 1)` - wastes CPU
+**✅ Fix:** Poll every 10ms
+
+**❌ No timeout:** Loop forever if condition never met
+**✅ Fix:** Always include timeout with clear error
+
+**❌ Stale data:** Cache state before loop
+**✅ Fix:** Call getter inside loop for fresh data
+
+## When Arbitrary Timeout IS Correct
+
+```typescript
+// Tool ticks every 100ms - need 2 ticks to verify partial output
+await waitForEvent(manager, 'TOOL_STARTED'); // First: wait for condition
+await new Promise(r => setTimeout(r, 200));   // Then: wait for timed behavior
+// 200ms = 2 ticks at 100ms intervals - documented and justified
+```
+
+**Requirements:**
+1. First wait for triggering condition
+2. Based on known timing (not guessing)
+3. Comment explaining WHY
+
+## Real-World Impact
+
+From debugging session (2025-10-03):
+- Fixed 15 flaky tests across 3 files
+- Pass rate: 60% → 100%
+- Execution time: 40% faster
+- No more race conditions

package/kit/skills/wdi-systematic-debugging/references/defense-in-depth.md

@@ -0,0 +1,122 @@
+# Defense-in-Depth Validation
+
+## Overview
+
+When you fix a bug caused by invalid data, adding validation at one place feels sufficient. But that single check can be bypassed by different code paths, refactoring, or mocks.
+
+**Core principle:** Validate at EVERY layer data passes through. Make the bug structurally impossible.
+
+## Why Multiple Layers
+
+Single validation: "We fixed the bug"
+Multiple layers: "We made the bug impossible"
+
+Different layers catch different cases:
+- Entry validation catches most bugs
+- Business logic catches edge cases
+- Environment guards prevent context-specific dangers
+- Debug logging helps when other layers fail
+
+## The Four Layers
+
+### Layer 1: Entry Point Validation
+**Purpose:** Reject obviously invalid input at API boundary
+
+```typescript
+function createProject(name: string, workingDirectory: string) {
+  if (!workingDirectory || workingDirectory.trim() === '') {
+    throw new Error('workingDirectory cannot be empty');
+  }
+  if (!existsSync(workingDirectory)) {
+    throw new Error(`workingDirectory does not exist: ${workingDirectory}`);
+  }
+  if (!statSync(workingDirectory).isDirectory()) {
+    throw new Error(`workingDirectory is not a directory: ${workingDirectory}`);
+  }
+  // ... proceed
+}
+```
+
+### Layer 2: Business Logic Validation
+**Purpose:** Ensure data makes sense for this operation
+
+```typescript
+function initializeWorkspace(projectDir: string, sessionId: string) {
+  if (!projectDir) {
+    throw new Error('projectDir required for workspace initialization');
+  }
+  // ... proceed
+}
+```
+
+### Layer 3: Environment Guards
+**Purpose:** Prevent dangerous operations in specific contexts
+
+```typescript
+async function gitInit(directory: string) {
+  // In tests, refuse git init outside temp directories
+  if (process.env.NODE_ENV === 'test') {
+    const normalized = normalize(resolve(directory));
+    const tmpDir = normalize(resolve(tmpdir()));
+
+    if (!normalized.startsWith(tmpDir)) {
+      throw new Error(
+        `Refusing git init outside temp dir during tests: ${directory}`
+      );
+    }
+  }
+  // ... proceed
+}
+```
+
+### Layer 4: Debug Instrumentation
+**Purpose:** Capture context for forensics
+
+```typescript
+async function gitInit(directory: string) {
+  const stack = new Error().stack;
+  logger.debug('About to git init', {
+    directory,
+    cwd: process.cwd(),
+    stack,
+  });
+  // ... proceed
+}
+```
+
+## Applying the Pattern
+
+When you find a bug:
+
+1. **Trace the data flow** - Where does bad value originate? Where used?
+2. **Map all checkpoints** - List every point data passes through
+3. **Add validation at each layer** - Entry, business, environment, debug
+4. **Test each layer** - Try to bypass layer 1, verify layer 2 catches it
+
+## Example from Session
+
+Bug: Empty `projectDir` caused `git init` in source code
+
+**Data flow:**
+1. Test setup → empty string
+2. `Project.create(name, '')`
+3. `WorkspaceManager.createWorkspace('')`
+4. `git init` runs in `process.cwd()`
+
+**Four layers added:**
+- Layer 1: `Project.create()` validates not empty/exists/writable
+- Layer 2: `WorkspaceManager` validates projectDir not empty
+- Layer 3: `WorktreeManager` refuses git init outside tmpdir in tests
+- Layer 4: Stack trace logging before git init
+
+**Result:** All 1847 tests passed, bug impossible to reproduce
+
+## Key Insight
+
+All four layers were necessary. During testing, each layer caught bugs the others missed:
+- Different code paths bypassed entry validation
+- Mocks bypassed business logic checks
+- Edge cases on different platforms needed environment guards
+- Debug logging identified structural misuse
+
+**Don't stop at one validation point.** Add checks at every layer.

package/kit/skills/wdi-systematic-debugging/references/find-polluter.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# Bisection script to find which test creates unwanted files/state
+# Usage: ./find-polluter.sh <file_or_dir_to_check> <test_pattern>
+# Example: ./find-polluter.sh '.git' 'src/**/*.test.ts'
+
+set -e
+
+if [ $# -ne 2 ]; then
+  echo "Usage: $0 <file_to_check> <test_pattern>"
+  echo "Example: $0 '.git' 'src/**/*.test.ts'"
+  exit 1
+fi
+
+POLLUTION_CHECK="$1"
+TEST_PATTERN="$2"
+
+echo "🔍 Searching for test that creates: $POLLUTION_CHECK"
+echo "Test pattern: $TEST_PATTERN"
+echo ""
+
+# Get list of test files (find . emits ./-prefixed paths, so accept the
+# pattern written with or without a leading ./)
+TEST_PATTERN="${TEST_PATTERN#./}"
+# find -path can't match '**/' against zero directory levels, so a pattern
+# like src/**/*.test.ts would skip src/top.test.ts; also try the pattern
+# with '**/' collapsed to cover files directly under the base directory.
+TEST_FILES=$(find . \( -path "./$TEST_PATTERN" -o -path "./${TEST_PATTERN//\*\*\//}" \) | sort -u)
+if [ -z "$TEST_FILES" ]; then
+  TOTAL=0
+else
+  TOTAL=$(printf '%s\n' "$TEST_FILES" | wc -l | tr -d ' ')
+fi
+
+echo "Found $TOTAL test files"
+echo ""
+
+COUNT=0
+for TEST_FILE in $TEST_FILES; do
+  COUNT=$((COUNT + 1))
+
+  # Skip if pollution already exists
+  if [ -e "$POLLUTION_CHECK" ]; then
+    echo "⚠️  Pollution already exists before test $COUNT/$TOTAL"
+    echo "   Skipping: $TEST_FILE"
+    continue
+  fi
+
+  echo "[$COUNT/$TOTAL] Testing: $TEST_FILE"
+
+  # Run the test
+  npm test "$TEST_FILE" > /dev/null 2>&1 || true
+
+  # Check if pollution appeared
+  if [ -e "$POLLUTION_CHECK" ]; then
+    echo ""
+    echo "🎯 FOUND POLLUTER!"
+    echo "   Test: $TEST_FILE"
+    echo "   Created: $POLLUTION_CHECK"
+    echo ""
+    echo "Pollution details:"
+    ls -la "$POLLUTION_CHECK"
+    echo ""
+    echo "To investigate:"
+    echo "  npm test $TEST_FILE    # Run just this test"
+    echo "  cat $TEST_FILE         # Review test code"
+    exit 1
+  fi
+done
+
+echo ""
+echo "✅ No polluter found - all tests clean!"
+exit 0