@nklisch/pi-agile-workflow 0.15.3

package/skills/bug-scan/references/language-footguns.md

@@ -0,0 +1,219 @@
+# Language-Specific Footguns — Bug Reference
+
+> **When to load this reference**: scanning code in a specific language for footguns that aren't
+> captured by the cross-cutting bug references. Load the section that matches the detected language.
+
+## How to use
+- Scanner reads only the section(s) matching the codebase's languages.
+- Each pattern is "watch for this in this language" — pure language-level surprises. Concurrency, async, state, resources, time/numbers, errors, and data/distributed footguns live in sibling references.
+- Format per pattern: signature → why hard to find → fix direction.
+
+## JavaScript / TypeScript
+*scanner: load if `.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs` present.*
+
+### 1. Loose equality and `null`/`undefined` coercion
+- `value == 0`, `"0" == false`, `null == undefined` is `true`. Coercion makes wrong matches look intentional.
+- Fix: `===`/`!==`; explicit `x === null || x === undefined`.
+
+### 2. `JSON.stringify` drops fields / throws on BigInt
+- `JSON.stringify({fn: () => 1, big: 1n, u: undefined})` — functions/`undefined` vanish silently; `BigInt` throws on the offending payload only.
+- Fix: pre-validate shape; custom replacer for BigInt; never serialize class instances directly.
+
+### 3. Object spread is shallow
+- `{...state, nested: state.nested}` then mutating `next.nested.x`. State updates look immutable but share inner refs.
+- Fix: `structuredClone`, recursive copy, or spread each nested level explicitly.
+
+### 4. `Array.sort()` lexicographic on numbers
+- `[10, 2, 1].sort()` → `[1, 10, 2]`. Tests with small data pass; production sees ordering bugs.
+- Fix: always pass `(a, b) => a - b`.
+
+### 5. `this` rebinding when methods become callbacks
+- `setTimeout(obj.method, 0)`, `arr.map(this.handler)`. Works when called directly; only callback paths break.
+- Fix: arrow functions, `.bind(this)`, or arrow class fields.
+
+### 6. TS `as` assertion / `any` contagion
+- `value as User`, `JSON.parse(s) as Config`, `as unknown as T`. Compiler trusts you; runtime mismatches surface as `undefined` accesses later. `any` poisons every expression it touches.
+- Fix: runtime validators (zod, io-ts); prefer `unknown` + type guards over `any`.
+
+### 7. Optional chaining swallowing required calls
+- `obj?.callback()` when callback was supposed to fire. Silent no-op masks misconfiguration.
+- Fix: assert presence at the boundary; reserve `?.` for genuinely-optional reads.
+
+### 8. `for...in` on arrays, integer-key promotion in objects
+- `for (const k in arr)` yields string keys (incl. inherited); `{2:'b', 1:'a'}` reorders integer-like keys first.
+- Fix: `for...of`; `Map` when insertion order matters.
+
+## Python
+*scanner: load if `.py`, `.pyi`, `pyproject.toml`, `requirements*.txt` present.*
+
+### 1. Mutable default arguments
+- `def f(x=[]):` — default created once at def-time and shared across calls.
+- Fix: `def f(x=None): x = [] if x is None else x`.
+
+### 2. Late binding in closures over loop vars
+- `[lambda: i for i in range(3)]` — all return `2`. Lambdas look independent; only invocation reveals shared binding.
+- Fix: default-arg capture `lambda i=i:` or `functools.partial`.
+
+### 3. `is` vs `==` interning lies
+- `x is 256` works, `x is 257` may not. Small-int and short-string interning makes `is` appear correct in tests.
+- Fix: `==` for value compare; `is` only for `None`, `True`, `False`, sentinels.
+
+### 4. `bool` is an `int`
+- `isinstance(True, int)` true; `sum([True, True])` is `2`; `dict[True]` and `dict[1]` collide.
+- Fix: check `bool` before `int` in isinstance chains; coerce explicitly.
+
+### 5. Shared class attribute mistaken for instance
+- `class C: items = []` then `self.items.append(x)` mutates the class-level list across all instances.
+- Fix: assign in `__init__`; `field(default_factory=list)` for dataclasses.
+
+### 6. `[[0]*3]*3` shared inner lists
+- `grid = [[0]*3]*3; grid[0][0] = 1` flips column 0 across all rows.
+- Fix: `[[0]*3 for _ in range(3)]`.
+
+### 7. `lru_cache` on instance methods leaks `self`
+- `@lru_cache` on `def method(self, ...)` holds strong refs to every `self`; memory grows with instance count.
+- Fix: `cached_property` per-instance; or module-level cache keyed on hashable inputs only.
+
+### 8. Naive `datetime.utcnow()` (deprecated 3.12+)
+- `datetime.utcnow()`, `datetime.utcfromtimestamp(t)` return naive datetimes that look like UTC but compare wrong against aware ones.
+- Fix: `datetime.now(datetime.UTC)` (3.11+) or `datetime.now(timezone.utc)`.
+
+### 9. Pickle of untrusted data → arbitrary code execution
+- `pickle.loads(network_bytes)`, `joblib.load(user_file)`. Any deserialization from network/uploads/queues.
+- Fix: JSON / msgpack / protobuf at untrusted boundaries; pickle only inside trusted process boundaries.
+
+## Go
+*scanner: load if `.go`, `go.mod`, `go.sum` present.*
+
+### 1. Loop variable capture (pre-1.22 modules)
+- `for _, v := range items { go func() { use(v) }() }` in a module declaring `go 1.21` or older. Go 1.22+ fixed semantics, but only for modules that declare `go 1.22`+.
+- Fix: bump `go.mod`; or shadow with `v := v` inside loop.
+
+### 2. Typed-nil interface
+- `var e *MyErr = nil; var err error = e; err != nil` → `true`. Interface has non-nil type tag with nil pointer; `err == nil` checks fail.
+- Fix: return untyped `nil` when there's no error; never assign typed-nil to an interface variable.
+
+### 3. `defer` in a long-running loop
+- `for _, f := range files { fp, _ := os.Open(f); defer fp.Close() }` — defers don't fire until the function returns; FDs accumulate.
+- Fix: extract loop body into a function so `defer` scopes correctly; or close explicitly.
+
+### 4. Slice append aliasing
+- `b := append(a, x)` may mutate `a`'s tail if `cap(a) > len(a)`. Behavior depends on capacity, not visible code.
+- Fix: `slices.Clone(a)` before append; or pre-copy with `append([]T(nil), a...)`.
+
+### 5. `range` over map is randomized
+- `for k, v := range m` produces a different order each run. Tests asserting order pass intermittently.
+- Fix: collect keys, sort, iterate.
+
+### 6. Receive from closed channel returns zero value
+- `v := <-ch` after `close(ch)` returns `0`/empty silently — looks like a real message.
+- Fix: `v, ok := <-ch` or `for v := range ch`.
+
+### 7. Send to nil channel blocks forever
+- `var ch chan int; ch <- 1`. Lazily-initialized channels or unset struct fields are common sources.
+- Fix: initialize before use; use nil channels deliberately only inside `select` to disable a case.
+
+### 8. Mixed pointer/value receivers on the same type
+- Half the methods `func (s Foo)`, half `func (s *Foo)`. Method sets differ for `Foo` vs `*Foo`; interface satisfaction quietly fails for one but not the other.
+- Fix: pick one receiver kind per type and stick to it.
+
+## Rust
+*scanner: load if `.rs`, `Cargo.toml`, `Cargo.lock` present.*
+
+### 1. `unwrap()` / `expect()` in production paths
+- `.unwrap()` outside tests / one-shot CLI prelude. Code compiles cleanly; panics surface only on the unhappy path. Library crates especially.
+- Fix: propagate with `?`; convert to typed errors; reserve `expect` for invariants with explanatory message.
+
+### 2. `clone()` to silence the borrow checker
+- `.clone()` chains on `Vec`/`String`/`Arc` in hot loops. Code correct but copies large data; only profilers reveal allocator pressure.
+- Fix: borrow with `&`; use `Cow<'_, T>`; restructure ownership; `Arc::clone` is cheap but still atomic.
+
+### 3. `move` closures capturing more than expected
+- `move || { use(&x); use(&y) }` where only `x` was meant to move. Compiles; consumes both, "use of moved value" elsewhere.
+- Fix: clone before move; capture only what's needed (`let x = x.clone(); move || ...`).
+
+### 4. `RefCell` / re-entrant `Mutex` runtime conflicts
+- `cell.borrow_mut()` while a `borrow()` is alive; nested `lock()` same thread. Type system can't catch interior-mutability conflicts; panic/deadlock under specific call sequences.
+- Fix: shorten borrow scopes; restructure to avoid reentrancy; `try_borrow_mut`.
+
+### 5. `?` coercing through `From` to wrong error type
+- `value?` where multiple `From<E>` impls exist; the wrong one wins.
+- Fix: explicit `.map_err`; narrower error enums; `thiserror` with disambiguated `#[from]`.
+
+### 6. `if let` temporary lifetimes past `else` (pre-2024 edition)
+- `if let Some(x) = mutex.lock()?.get() { ... } else { mutex.lock(); /* deadlock */ }` — pre-2024 editions keep the temporary guard alive until after `else`.
+- Fix: bind temporary to `let` and drop explicitly; or move to Rust 2024 edition.
+
+### 7. `unsafe { ... }` scoping more than the unsafe call
+- Large `unsafe` blocks wrapping mostly-safe code. Whole block is reviewer-blessed; only the actually-unsafe op needs scrutiny.
+- Fix: shrink unsafe scope to the minimal expression; document invariants per call.
+
+## Java / Kotlin
+*scanner: load if `.java`, `.kt`, `.kts`, `pom.xml`, `build.gradle*` present.*
+
+### 1. `equals` without matching `hashCode`
+- Overridden `equals` with default `hashCode`, or only one. Works in `List.contains`; breaks in `HashMap`/`HashSet`.
+- Fix: always override both; use records, `@AutoValue`, or Kotlin `data class` (without inheritance).
+
+### 2. `==` on boxed numerics (Java); reference equality on objects
+- `Integer a = 200, b = 200; a == b` → `false` (outside `-128..127` cache).
+- Fix: `.equals()` for boxed types; primitives where possible. (Kotlin `==` calls `equals`; `===` is reference.)
+
+### 3. `ConcurrentModificationException` from iterator + mutation
+- `for (X x : list) { list.remove(x); }`.
+- Fix: `Iterator.remove()`, `removeIf`, copy-to-new-list, or `CopyOnWriteArrayList`.
+
+### 4. `Optional.get()` without `isPresent`
+- `opt.get()` reachable without prior presence check; chains using `Optional` as if nullable.
+- Fix: `orElse`, `orElseThrow`, `ifPresent`, `map`/`flatMap`.
+
+### 5. `compareTo` overflow / inconsistent with equals
+- Comparators using subtraction (`a.x - b.x`) overflow; non-antisymmetric implementations.
+- Fix: `Integer.compare(a, b)`; `Comparator.comparing(...)`.
+
+### 6. Kotlin platform types — silent NPE
+- `val name: String = javaObj.getName()` where Java return is unannotated (`String!`). Compiler can't enforce nullability across the Java boundary.
+- Fix: declare result as `String?` and check; wrap Java calls with explicit null handling.
+
+### 7. Kotlin `lateinit` uninitialized access
+- `lateinit var foo: Foo` accessed before assignment → `UninitializedPropertyAccessException`. DI-like patterns and tests without framework are common sources.
+- Fix: constructor injection; `by lazy`; `::foo.isInitialized` only when justified.
+
+### 8. Kotlin `data class` inheritance / mutable hash keys
+- `data class Sub(val extra: Int) : Base(...)` ignores Base fields in generated equals/hashCode; `data class` with `var` mutable in `HashMap`.
+- Fix: avoid inheritance from data classes; keep fields `val`.
+
+## C / C++
+*scanner: load if `.c`, `.cc`, `.cpp`, `.cxx`, `.h`, `.hpp`, `CMakeLists.txt`, `Makefile` present.*
+
+### 1. Returning pointer / reference to local
+- `T* foo() { T x; return &x; }`, `const T& bar() { return T{}; }`, `string_view` over a local. Works "by accident" until stack frame is reused or optimizer changes.
+- Fix: return by value (NRVO), smart pointer, or output buffer parameter.
+
+### 2. Use-after-move
+- `f(std::move(x)); g(x);` — `x` is valid-but-unspecified. Type system permits the second use.
+- Fix: scope variables tightly; only assign or destroy after move; clang-tidy `bugprone-use-after-move`.
+
+### 3. Iterator / pointer invalidation on container mutation
+- Loop over `vector` that `push_back`s; cached `.data()` across reallocation. Works while capacity holds; reallocation silently invalidates.
+- Fix: collect changes then apply; reserve capacity; index-based loops with care.
+
+### 4. Implicit narrowing conversions
+- `int i = 1.9;`, `uint32_t x = -1;`, `int16_t y = some_int;`. Brace-init `{}` warns; assignment doesn't.
+- Fix: prefer `{}` initialization to surface narrowing; explicit `static_cast`; `-Wconversion`.
+
+### 5. Signed/unsigned mixing
+- `for (size_t i = 0; i < v.size() - 1; ++i)` when `v.size() == 0` underflows to huge value.
+- Fix: pick one signedness per arithmetic chain; `std::ssize`; bounds-check before subtraction.
+
+### 6. Missing virtual destructor on polymorphic base
+- Base with virtual functions but no virtual dtor; `delete` via base pointer. Derived destructor doesn't run → leaks, partial destruction UB.
+- Fix: add `virtual ~Base() = default;`, or protect dtor and restrict deletion to derived.
+
+### 7. `auto` deducing value when reference intended
+- `for (auto x : container)` copies; `auto y = obj.large_member();` copies large/non-copyable types.
+- Fix: `auto&` / `const auto&` for non-mutating loops; `decltype(auto)` when forwarding return type.
+
+### 8. Strict-aliasing / type-punning via cast
+- `float f = *reinterpret_cast<float*>(&someInt);`. Works at `-O0`; UB under `-O2`; optimizer assumes types don't alias.
+- Fix: `std::memcpy` for type punning; `std::bit_cast` (C++20); unions are NOT portable for this in C++.

package/skills/bug-scan/references/parked-item-template.md

@@ -0,0 +1,103 @@
+# Parked Bug-Scan Item Template
+
+> Used by `bug-scan` in **standalone mode** to park each finding into `.work/backlog/<id>.md`.
+> Lighter than the gate-mode item template — backlog items have no `stage:` field and minimal
+> structure. The user elevates anything they want to action via `/agile-workflow:scope`.
+
+## File location
+
+All standalone findings (Critical → Low) go to `.work/backlog/<id>.md`.
+
+> **Why all severities go to backlog (even Critical):** standalone is exploratory ("scan and
+> see what's there"). The user decides what to action. For release-bound, must-fix-before-ship
+> Criticals, use **gate mode** (`bug-scan --release <version>`) which writes to
+> `.work/active/stories/` instead.
+
+## ID convention
+
+`bug-scan-<short-slug>` — slug describes the finding briefly (kebab-case, ≤ 40 chars after prefix).
+
+Examples:
+- `bug-scan-stale-closure-cart-effect`
+- `bug-scan-tx-not-rolled-back-on-error`
+- `bug-scan-await-in-foreach-callback`
+- `bug-scan-goroutine-leak-blocked-send`
+
+On collision (same slug exists), suffix with `-2`, `-3`, etc.
+
+## Frontmatter + body template
+
+```yaml
+---
+id: bug-scan-<short-slug>
+created: YYYY-MM-DD          # today's local date
+tags: [bug, <domain-tag>]    # plus optional severity tag, see below
+bug_origin: scan             # how this entered the backlog
+bug_severity: critical | high | medium | low
+bug_domain: concurrency | async | state | resource-leak | time-numbers | error-handling | data-layer | language-footgun
+bug_location: <file>:<line>  # canonical location for idempotency
+---
+
+# <one-line title>
+
+**Location**: `<file>:<line>` · **Severity**: <severity> · **Pattern**: <named pattern or "new">
+
+<one-paragraph capture: what the bug is, why it's a bug, and a one-sentence remediation direction>
+
+```<lang>
+<1-5 lines of offending code as evidence>
+```
+```
+
+## Domain tag mapping
+
+Same as the gate-item template:
+
+| Domain | Tag |
+|---|---|
+| Concurrency & races | `concurrency` |
+| Async / promises | `async` |
+| State & closures | `state` |
+| Resource leaks | `resource-leak` |
+| Time & numbers | `time-numbers` |
+| Error handling | `error-handling` |
+| Data layer | `data-layer` |
+| Language footguns | `language-footgun` |
+
+All carry the umbrella `bug` tag. Optionally add `critical` / `high` to `tags:` for the
+two highest severities so `grep -l "critical" .work/backlog/` surfaces them fast.
+
+## Idempotency (re-run protection)
+
+Before parking, scan existing backlog files:
+
+```bash
+grep -rl "^bug_origin: scan$" .work/backlog/ 2>/dev/null | while read -r f; do
+  loc=$(grep -m1 '^bug_location:' "$f" | awk '{print $2}')
+  [ -n "$loc" ] && echo "$loc $f"
+done > /tmp/bugscan-existing.txt
+```
+
+For each new finding, check the (file, line, pattern) triple against
+`/tmp/bugscan-existing.txt`. If present, **skip** — do not re-park. Tally the skip count and
+include it in the report's summary.
+
+If the existing file is older than 30 days and the finding still applies, refresh its
+`created` to today and append a "(still applies as of YYYY-MM-DD)" line to the body.
+Otherwise leave it alone.
+
+## Rules
+
+- One finding = one parked file. No bundling.
+- `bug_origin: scan` is required — distinguishes standalone-parked items from gate-produced
+  items (`gate_origin: bugs`) and from user-parked ideas (no `bug_origin` field).
+- `bug_location` is required — drives idempotency.
+- `created` is today's ISO date.
+- Keep the body to one paragraph + the code snippet. Detailed analysis belongs in the report,
+  not in every backlog file (backlog files get skimmed; the report gets read).
+- After parking all items, commit in a single commit: `bug-scan: park <N> findings (<scope>)`.
+
+## Opt-out
+
+If the user invokes with `--no-park`, skip this entire phase. Write only the report. Note
+the skipped count in the report's summary so it's transparent the substrate was bypassed.

package/skills/bug-scan/references/report-template.md

@@ -0,0 +1,115 @@
+# Bug-Scan Report Template
+
+> Used by `bug-scan` in **standalone mode** to write `bug-scan-report.md` at repo root.
+> Fill the placeholders. Drop sections with zero entries.
+
+```markdown
+# Bug-Scan Report
+
+**Generated**: <ISO-date>
+**Scope**: <"whole repo" OR path glob>
+**Files scanned**: <N>
+**Overall score**: **<X.X/10>**
+
+## Stack profile
+
+- Languages: <list>
+- Frameworks: <list>
+- Data layer: <list>
+- Concurrency primitives: <list>
+- Notable entry points: <list>
+
+## Domain scores
+
+| Domain | Relevance | Score | Findings (C/H/M/L) |
+|---|---|---|---|
+| Concurrency & races | most | X/10 | 0/1/2/3 |
+| Async / promises | most | X/10 | 0/0/1/2 |
+| State & closures | relevant | X/10 | 0/0/0/1 |
+| Resource leaks | most | X/10 | 1/0/1/0 |
+| Time & numbers | relevant | X/10 | 0/0/0/2 |
+| Error handling | most | X/10 | 0/2/1/0 |
+| Data layer | most | X/10 | 0/1/3/1 |
+| Language footguns | relevant | X/10 | 0/0/2/4 |
+
+**Overall**: <X.X/10> — weighted average (most-relevant 2x, relevant 1x).
+
+## Top 3 critical findings
+
+1. **<title>** — `<file:line>` (<domain>, <severity>)
+2. **<title>** — `<file:line>` (<domain>, <severity>)
+3. **<title>** — `<file:line>` (<domain>, <severity>)
+
+## Findings by severity
+
+### Critical (<n>)
+
+#### <title>
+- **Domain**: <domain>
+- **Pattern**: <pattern name from reference, or "new">
+- **Location**: `<file:line>`
+- **Parked**: `bug-scan-<slug>` *(or `not parked: --no-park` / `not parked: no substrate` /
+  `duplicate of bug-scan-<slug>` if skipped via idempotency)*
+- **Evidence**:
+  ```<lang>
+  <1-5 lines of offending code>
+  ```
+- **Why it's a bug**: <1-2 sentences — the specific failure mode>
+- **Remediation direction**: <direction, not finished fix>
+- *Also flagged by*: <other domain, if duplicate>
+
+<repeat for each Critical>
+
+### High (<n>)
+
+<same shape>
+
+### Medium (<n>)
+
+<same shape>
+
+### Low (<n>)
+
+<same shape — can be compressed to one-liners if many>
+
+## Domains skipped
+
+| Domain | Why |
+|---|---|
+| <domain> | <e.g. "no async code in scope", "no DB usage detected"> |
+
+## Backlog parking summary
+
+| Metric | Count |
+|---|---|
+| Findings parked this run | <n> |
+| Duplicates skipped (already in backlog) | <n> |
+| Refreshed (existing item, still applies, `created` updated to today) | <n> |
+| Opt-out (`--no-park`) | true / false |
+| Substrate present | true / false |
+
+> All parked items live at `.work/backlog/bug-scan-*.md` with `bug_origin: scan`. Elevate any
+> of them to active stories via `/agile-workflow:scope <id>`. Find them all with:
+> `grep -l '^bug_origin: scan$' .work/backlog/*.md`.
+
+## Scanner gaps
+
+> If any scanner returned an error or inconclusive results, list it here.
+> The user can re-run that domain alone if they want.
+
+- <domain>: <what went wrong, or "—" if all clean>
+
+## Next steps
+
+- Hand the Criticals to `/agile-workflow:fix <id>` for immediate repair.
+- `/agile-workflow:scope` to promote findings into tracked items.
+- Re-run after fixes to verify resolution.
+```
+
+## Rules
+
+- Always include the stack profile even if short.
+- Show the domain table even when most rows are zero — empty rows signal coverage.
+- Group findings by severity, then by domain within each severity.
+- Sort within a severity group by file path (predictable diff-friendly).
+- Don't repeat the same finding under multiple severities — pick the highest and cross-link.

package/skills/bug-scan/references/resource-leaks.md

@@ -0,0 +1,199 @@
+# Resource Leaks — Bug Reference
+
+> **When to load this reference**: when scanning code that opens files, connects to anything, subscribes/observes, registers listeners, schedules timers, spawns threads/processes, acquires locks/semaphores, or otherwise consumes a finite resource pool.
+
+## Detection signals
+
+grep heuristics (combine with negative-lookahead for matching cleanup):
+
+- `open\(` / `fopen` / `os.Open` without nearby `close`/`with`/`defer`/`use`
+- `connect\(` / `Dial\(` / `new WebSocket` / `EventSource\(` / `createConnection`
+- `subscribe\(` / `\.on\(` / `addEventListener\(` (especially with inline `=> {}`)
+- `setInterval\(` / `setTimeout\(` / `requestAnimationFrame` without paired `clear*`
+- `new (Worker|Thread|ResizeObserver|IntersectionObserver|MutationObserver|AbortController)`
+- `go func\(` / `Thread\.start` / `tokio::spawn` / `asyncio\.create_task` / `spawn\(` / `fork\(` / `Popen\(`
+- `pool\.(acquire|get|checkout)` / `Semaphore.*acquire` / `Lock\.lock`
+- `\.begin\(\)` / `startTransaction` / `tx, _ :=` without paired `Commit|Rollback`
+- Missing `defer .*\.Close\(\)` after handle acquisition (Go); JS/TS `useEffect` body opens a resource but `return` is absent
+
+## Patterns
+
+### 1. File opened without RAII / context manager / defer
+- **Signature**: handle acquired then used without language-idiomatic auto-close.
+- **Why hard to find**: works fine until exception path or high throughput exhausts FDs.
+- **Where to look**: report generators, log writers, CSV/JSON loaders, image pipelines.
+- **Example**: `f = open(p); data = f.read(); parse(data); f.close()` — exception in `parse` leaks `f`.
+- **Fix direction**: `with open(p) as f:` (Py), try-with-resources (Java), `defer f.Close()` (Go), `using`/`await using` (C#, TS 5.2+), RAII (Rust/C++), `try/finally` (JS); Swift `defer { try? f.close() }`; C `goto cleanup`; Node streams need `'error'`+`'close'` handlers.
+
+### 2. DB connection acquired, early return before release
+- **Signature**: `conn = pool.acquire(); ...; pool.release(conn)` with branches in between.
+- **Why hard to find**: pool exhaustion appears only under sustained error rate.
+- **Where to look**: repository layers, request handlers, retry loops.
+- **Example**: `conn = await pool.connect(); res = await conn.query(sql); pool.release(conn)` — `query` throws → leak.
+- **Fix direction**: try/finally; `async with pool.acquire()`; `defer conn.Release()`; scoped helpers (`pool.withConnection(fn)`); Go `sql.DB` auto-manages but `Rows` needs `defer rows.Close()`; HikariCP needs try-with-resources.
+
+### 3. Transaction begun but neither committed nor rolled back on early return
+- **Signature**: `tx = db.begin(); ...; tx.commit()` with no `tx.rollback()` in catch / defer.
+- **Why hard to find**: lock contention and idle-in-transaction grow slowly; only surface under load.
+- **Where to look**: multi-step writes, saga steps, validation between writes.
+- **Example**: `tx = await db.begin(); await tx.insert(x); validate(x); await tx.commit()` — `validate` throws → idle tx holds row locks.
+- **Fix direction**: `try { ...; await tx.commit() } catch { await tx.rollback(); throw }`; Go `defer tx.Rollback()` after Begin (Commit makes Rollback a no-op).
+
+### 4. HTTP client / Axios / Session recreated per request
+- **Signature**: `new HttpClient()` / `axios.create()` / `requests.Session()` inside hot loop or handler.
+- **Why hard to find**: leaks ephemeral ports + sockets in TIME_WAIT; manifests as ENOBUFS / EADDRNOTAVAIL.
+- **Where to look**: utility functions called repeatedly, lambdas, per-request middleware.
+- **Example**: handler does `await axios.get(url)` (creates new agent) instead of reusing a module-level instance.
+- **Fix direction**: hoist client to module scope; reuse `http.Client` (Go), `HttpClient` (.NET — never per-request), pooled `requests.Session` (Py).
+
+### 5. WebSocket / SSE / EventSource not closed on unmount
+
+- **Signature**: `new WebSocket(url)` inside component / route handler without paired `.close()`.
+- **Why hard to find**: SPA navigation leaks connections per route visit; backend FD pressure.
+- **Where to look**: React/Vue/Svelte effects, hooks, route components.
+- **Example**: `useEffect(() => { const ws = new WebSocket(u); ws.onmessage = ... }, [])` — no cleanup.
+- **Fix direction**: `return () => ws.close()` from effect; Vue `onUnmounted`; Svelte `onDestroy`; Angular `takeUntilDestroyed`.
+
+### 6. addEventListener without removeEventListener (and anonymous fn)
+
+- **Signature**: `el.addEventListener('x', () => {...})` — anonymous arrow, no removal handle.
+- **Why hard to find**: GC keeps target reachable via listener closure; multiplies per mount.
+- **Where to look**: window/document listeners from components, custom hooks, third-party widget integrations.
+- **Example**: `window.addEventListener('resize', () => setW(window.innerWidth))` — anon arrow, can't remove.
+- **Fix direction**: name the handler, `return () => window.removeEventListener('resize', handler)`; or use `AbortController` `signal` + abort on cleanup.
+
+### 7. setInterval / setTimeout / requestAnimationFrame not cleared
+
+- **Signature**: `setInterval(fn, ms)` / `setTimeout(fn, ms)` without `clearInterval` / `clearTimeout`.
+- **Why hard to find**: long-lived timers reference component state, prevent GC, fire after unmount.
+- **Where to look**: polling, debouncing, animations, retry-with-backoff.
+- **Example**: `useEffect(() => { setInterval(poll, 1000) }, [])` — id discarded, never cleared.
+- **Fix direction**: capture id; `return () => clearInterval(id)`; for RAF, `cancelAnimationFrame(raf)`.
+
+### 8. Subscription teardown discarded (RxJS / Observable / EventEmitter)
+
+- **Signature**: `obs.subscribe(fn)` without assigning to a variable; `emitter.on(...)` without paired `off`.
+- **Why hard to find**: subscription persists across component lifetime; closure roots a tree of state.
+- **Where to look**: Angular components, Redux observable epics, EventEmitter wiring.
+- **Example**: `this.user$.subscribe(u => this.user = u)` in component — no `unsubscribe` in `ngOnDestroy`.
+- **Fix direction**: `takeUntilDestroyed()` (Angular 16+); store `Subscription` and unsubscribe; Node `emitter.once` or `emitter.off(name, handler)`.
+
+### 9. Async generator never returned / closed
+
+- **Signature**: `for await (const x of gen())` exited via break/throw without `return()`/`finally`.
+- **Why hard to find**: driver task / pending I/O lingers; Python warns `coroutine was never awaited`.
+- **Where to look**: streaming endpoints, paginated iterators, server-sent generators.
+- **Example**: `async function *stream() { const r = await openReader(); yield ... }` — caller breaks; reader never closed.
+- **Fix direction**: `try { yield ... } finally { reader.close() }`; Python `async with aclosing(gen)`; explicit `await gen.return()`.
+
+### 10. Goroutine blocked on send to unbuffered channel
+
+- **Signature**: `go func(){ ch <- result }()` where parent may return before receiving.
+- **Why hard to find**: leak is per-request; only visible via runtime/goroutine count, pprof, or `uber/goleak`.
+- **Where to look**: timeout patterns, first-result-wins races, fan-out with early return.
+- **Example**: launch goroutine that writes to result channel; parent times out via `select` → sender blocks forever.
+- **Fix direction**: buffer the channel (`make(chan T, 1)`); pass a `context.Context` with cancel; use `errgroup` or `sync.WaitGroup`.
+
+### 11. Python tempfile created with delete=False, never unlinked
+
+- **Signature**: `NamedTemporaryFile(delete=False)`, `mkstemp()`, `mkdtemp()` without `os.unlink` / `shutil.rmtree`.
+- **Why hard to find**: `/tmp` slowly fills; only noticed when disk full.
+- **Where to look**: file-upload handlers, ML preprocessing, PDF/image conversion.
+- **Example**: `f = NamedTemporaryFile(delete=False); f.write(data); process(f.name)` — no cleanup on success or error.
+- **Fix direction**: `try/finally: os.unlink(f.name)`; prefer `delete=True` with `with`; use `tempfile.TemporaryDirectory()`.
+
+### 12. child_process / subprocess never killed on parent shutdown
+
+- **Signature**: `spawn` / `Popen` / `exec.Command(...).Start()` without `.kill()` on shutdown.
+- **Why hard to find**: orphan processes survive parent; accumulate over restarts.
+- **Where to look**: dev servers, FFmpeg/imagemagick wrappers, language-server hosts.
+- **Example**: `const proc = spawn('ffmpeg', args)` — parent crashes; ffmpeg lingers.
+- **Fix direction**: SIGTERM/SIGINT handlers that kill children; process-group kill; Python `atexit` + `proc.terminate()`; Go `Cmd.SysProcAttr.Setpgid` then kill group.
+
+### 13. Worker thread / Web Worker never terminated
+
+- **Signature**: `new Worker(...)` / `new Thread(...)` without `terminate()` / `join()` on tear-down.
+- **Why hard to find**: workers hold their own heap; per-tab and per-component leaks multiply.
+- **Where to look**: heavy computation offloaded from UI, parallel pipelines.
+- **Example**: `useEffect(() => { const w = new Worker(url); w.postMessage(x) }, [])` — no `w.terminate()`.
+- **Fix direction**: return cleanup that calls `terminate()`/`close()`; Node `worker_threads` should be pooled and reused.
+
+### 14. Native handle held via finalizer-only cleanup
+
+- **Signature**: relies on GC / `__del__` / finalizer to release FDs, sockets, mmaps.
+- **Why hard to find**: works in tests; under load GC lag exhausts handles before finalizers run.
+- **Where to look**: wrappers around C libraries, `ctypes`/JNI/N-API bindings.
+- **Example**: Python class wraps `os.open(fd)` and closes in `__del__` — never called in ref-cycle.
+- **Fix direction**: explicit `close()` / `Dispose()` / `Drop`; context-manager protocol; never depend on finalizer for finite resources.
+
+### 15. Lock acquired in one branch, released only in another
+
+- **Signature**: conditional `lock.acquire()` not mirrored by guaranteed release.
+- **Why hard to find**: deadlock only on specific branch with exception.
+- **Where to look**: cache fill paths, double-checked initialization, retry logic.
+- **Example**: `if (stale) { lock.acquire(); fetch(); }; lock.release()` — release runs even when not acquired (or vice versa).
+- **Fix direction**: scope guard (`with lock:`, `defer mu.Unlock()`, `std::lock_guard`, Java try-finally); don't branch on acquire.
+
+### 16. Semaphore permit acquired, exception before release
+
+- **Signature**: `sem.acquire()` then risky operation then `sem.release()` without finally.
+- **Why hard to find**: permits monotonically deplete; eventually all callers block.
+- **Where to look**: rate limiters, bounded concurrency wrappers, connection guards.
+- **Example**: `await sem.acquire(); await callApi(); sem.release()` — `callApi` throws → permit lost.
+- **Fix direction**: `try { ... } finally { sem.release() }`; Python `async with sem:`; Java `Semaphore` in try/finally.
+
+### 17. AbortController created per render, not aborted
+
+- **Signature**: `const ctrl = new AbortController()` inside render/effect without `ctrl.abort()` in cleanup.
+- **Why hard to find**: each render registers more listeners on the signal; closures pin state.
+- **Where to look**: data-fetching hooks, search-as-you-type, infinite scroll.
+- **Example**: `useEffect(() => { fetch(url, { signal: new AbortController().signal }) }, [url])` — orphaned controllers.
+- **Fix direction**: `const ctrl = new AbortController(); ...; return () => ctrl.abort()`; one controller per effect run.
+
+### 18. Cache without eviction, keyed by user input
+
+- **Signature**: `Map`/`dict` populated by user-supplied keys without TTL, LRU bound, or invalidation.
+- **Why hard to find**: looks like a perf optimization; only OOMs at scale or with adversarial input.
+- **Where to look**: memoization helpers, request-deduplication caches, dataloader-ish patterns at module scope.
+- **Example**: `const cache = new Map(); function get(key){ if(!cache.has(key)) cache.set(key, compute(key)); return cache.get(key) }`.
+- **Fix direction**: bounded LRU (`lru-cache`, `functools.lru_cache(maxsize=N)`, Caffeine, Guava), `WeakMap` keyed by lifetime, TTL eviction.
+
+### 19. Listener on long-lived global from short-lived component
+
+- **Signature**: short-lived object registers callback on a singleton/global without dropping it on destroy.
+- **Why hard to find**: global retains tree of component state; classic "detached DOM" pattern.
+- **Where to look**: stores/buses, document/window, EventBus singletons, third-party SDK globals (analytics, posthog, sockets).
+- **Example**: modal subscribes `bus.on('refresh', this.refresh)` — bus outlives modal, `this` rooted forever.
+- **Fix direction**: pair every `on` with `off` in destroy; use `WeakRef` or weak listener; expose `dispose()` API.
+
+### 20. ResizeObserver / IntersectionObserver / MutationObserver not disconnected
+
+- **Signature**: `new ResizeObserver(cb)` / `new IntersectionObserver(...)` without `.disconnect()`.
+- **Why hard to find**: observer keeps target node + callback closure alive even after DOM removal.
+- **Where to look**: virtualized lists, layout-aware components, lazy-image loaders.
+- **Example**: `const ro = new ResizeObserver(...); ro.observe(el)` in effect, no cleanup.
+- **Fix direction**: `return () => ro.disconnect()`; or `unobserve(el)` if observer is shared; ESLint `no-leaked-resize-observer`.
+
+### 21. IndexedDB transaction goes async without being awaited
+
+- **Signature**: `db.transaction(...).objectStore(...).put(...)` followed by `await unrelatedPromise` mid-tx.
+- **Why hard to find**: IDB auto-commits a tx that becomes idle; subsequent ops in same tx throw `TransactionInactiveError`.
+- **Where to look**: offline-first apps, sync engines, PWA storage layers.
+- **Example**: `const tx = db.transaction('s', 'rw'); await fetch(...); tx.objectStore('s').put(x)` — tx closed before put.
+- **Fix direction**: complete all IDB work synchronously after the request; chain via `tx.complete`/`tx.oncomplete`; or use `idb` library's `tx.done`.
+
+### 22. ORM/ODM cursor / streaming iterator not closed
+
+- **Signature**: `cursor = collection.find(...)` / `db.Query(...)` / `session.stream(...)` without explicit close.
+- **Why hard to find**: holds server-side cursor, connection, and snapshot until timeout; replica lag spikes.
+- **Where to look**: export endpoints, batch jobs, MongoDB streams, Postgres `stream()`/`cursor()`.
+- **Example**: Go `rows, _ := db.Query(...)` — caller forgets `defer rows.Close()`; connection never returns to pool.
+- **Fix direction**: `defer rows.Close()` (Go), `with cursor:` / `for x in cursor: ... ; cursor.close()` (Py), `try-with-resources` (JDBC), `await cursor.close()` (Mongo Node driver).
+
+### 23. Streams: readable not drained / writable not ended
+
+- **Signature**: `stream.on('data', ...)` without `'end'`/`'error'`, or `writable.write(x)` without `.end()`.
+- **Why hard to find**: backpressure stalls pipelines; FDs retained until process exit.
+- **Where to look**: file copies, HTTP proxies, compression pipelines, S3 uploads.
+- **Example**: `fs.createReadStream(p).pipe(transform)` — `transform` never piped to a sink; FD held.
+- **Fix direction**: `pipeline(readable, transform, writable, cb)` (Node `stream/promises`); handle `'error'` to trigger destroy; explicit `writable.end()`.