@nklisch/pi-agile-workflow 0.15.3

package/skills/bug-scan/references/data-layer.md

@@ -0,0 +1,167 @@
+# Data Layer & Distributed Systems — Bug Reference
+
+> **When to load this reference**: when scanning code that touches a database (SQL or NoSQL),
+> an ORM, a message queue, an external service, or coordinates work across processes/services.
+
+## Detection signals
+- SQL / query shapes: `SELECT .* FROM`, `UPDATE .* SET`, `DELETE FROM`, `INSERT INTO`, `BEGIN`, `COMMIT`, `ROLLBACK`, `FOR UPDATE`, `LOCK TABLE`, raw string concat into queries (`f"SELECT ... {x}"`, `"... " + var`).
+- Transaction blocks: `.transaction(`, `@Transactional`, `with db.atomic`, `session.begin`, `BEGIN;`, `tx.Begin()`, `conn.beginTransaction`.
+- ORM call sites: `.findAll(`, `.findMany(`, `.includes(`, `.preload(`, `.eager_load(`, `.joins(`, `.select_related(`, `.prefetch_related(`, `lazy=`, `relationship(`, `belongsTo(`, `hasMany(`, `@OneToMany`, `@ManyToOne`.
+- ORM model files: `models.py`, `*.entity.ts`, `schema.prisma`, `*/models/*.rb`, `drizzle/schema.ts`.
+- Iteration over query results: `for row in qs:` followed by `row.related.something`, `users.map(u => u.posts)`, template loops with `{{ obj.related.field }}`.
+- Migrations: `migrations/`, `alembic/`, `prisma migrate`, `knex migrate`, `ALTER TABLE`, `DROP COLUMN`, `ADD COLUMN NOT NULL`.
+- Distributed primitives: `retry`, `withRetry`, `backoff`, `CircuitBreaker`, `kafka`, `rabbitmq`, `sqs`, `pubsub`, `webhook`, `consumer.poll`, `producer.send`, `outbox`, `saga`.
+- Time/clock: `now()`, `Date.now()`, `time.Now()`, `System.currentTimeMillis`, `Instant.now()` used for ordering or correlation across services.
+- Cache layer: `Redis.`, `memcache`, `\.invalidate(`, `\.del(`, `cache.get`, `getOrSet`, `SETEX`, `EXPIRE`.
+- Hot files: repositories, DAOs, query helpers, batch jobs, webhook receivers, queue consumers, retry helpers, cache wrappers.
+
+## Data Layer Patterns
+
+### 1. N+1 query
+- **Signature**: a query producing a list, then a loop touching a related field — `for u in users: print(u.posts)`, `users.map(u => u.profile)`, template `{% for x in qs %}{{ x.author.name }}{% endfor %}`.
+- **Why hard to find**: each individual query is cheap; total cost only visible under realistic data volume. ORMs lazy-load silently.
+- **Where to look**: list endpoints, admin pages, serializers, GraphQL resolvers without DataLoader, template render paths, JSON serialization of nested objects.
+- **Example**:
+  ```python
+  users = User.objects.all()
+  return [{ "name": u.name, "posts": [p.title for p in u.posts.all()] } for u in users]
+  ```
+- **Fix direction**: eager-load relations (`select_related` / `prefetch_related`, Prisma `include`, Drizzle relational query, SQLAlchemy `joinedload` / `selectinload`, ActiveRecord `includes`); for GraphQL use DataLoader-style batching.
+- **Variants**: Prisma — silent N+1 when iterating without `include`; Drizzle — no auto-eager-load, must use relational queries; SQLAlchemy — `lazy="select"` default; Django — `.only()` without `select_related` triggers per-row fetch; ActiveRecord — `each` + association = trap.
+
+### 2. Missing or wrong index
+- **Signature**: `WHERE col = ?` on a non-indexed column; `LIKE '%foo%'` (unanchored); `ORDER BY` on non-indexed column; partial index whose predicate doesn't match the query.
+- **Why hard to find**: works fine in dev with small tables; full-scan latency scales with row count and bites at production scale.
+- **Where to look**: schema/migration files, query planner output, slow-query logs, columns used in `WHERE` / `JOIN` / `ORDER BY` not listed in `CREATE INDEX`, partial indexes (`WHERE deleted_at IS NULL`) used by queries that don't reuse the same predicate.
+- **Fix direction**: add covering / composite index matching query shape; verify with `EXPLAIN` / `EXPLAIN ANALYZE`; for partial indexes, ensure callers include the predicate verbatim.
+- **Variants**: Postgres partial index requires matching `WHERE` in query; MySQL leftmost-prefix rule for composite indexes; Mongo compound index order matters; case-insensitive search needs functional index or `citext`.
+
+### 3. Transaction held across external I/O
+- **Signature**: `BEGIN` (or `@Transactional`) wrapping an HTTP call, S3 upload, email send, queue publish, or sleep.
+- **Why hard to find**: works under low load; under load the held row/page locks cascade into pool exhaustion and deadlock spikes.
+- **Where to look**: service methods that mix DB writes with `fetch(`, `requests.`, `httpClient.`, `SES.send`, `s3.putObject`, `kafka.send` inside one transactional boundary.
+- **Example**: charging a payment gateway inside `@Transactional` — gateway succeeds, DB rollback leaves money taken without record.
+- **Fix direction**: do external work outside the transaction; use the **transactional outbox** (write event row in the same tx, deliver async) for at-least-once; compensate on failure rather than relying on rollback.
+
+### 4. Wrong isolation level / missing row lock
+- **Signature**: read-modify-write across two statements at `READ COMMITTED` without `SELECT ... FOR UPDATE`; check-then-insert without unique constraint; balance update via `UPDATE accounts SET balance = ? WHERE id = ?` after a non-locking `SELECT`.
+- **Why hard to find**: phantom reads, lost updates, write skew — only show under concurrent traffic.
+- **Where to look**: financial ledgers, inventory decrement, counter increments, "reserve a slot" code, get-or-create flows.
+- **Fix direction**: prefer single-statement atomic updates (`UPDATE ... SET balance = balance - ?`); when not possible, use `SELECT ... FOR UPDATE` or bump isolation to `REPEATABLE READ` / `SERIALIZABLE`; add unique constraints for idempotency.
+- **Variants**: MySQL default `REPEATABLE READ` allows write skew; Postgres `SERIALIZABLE` retries on serialization failure (handle `40001`); SQLite single-writer hides the bug locally.
+
+### 5. ORM lazy-load at render time
+- **Signature**: serializer / template accesses `.related` outside the session/request scope; DetachedInstanceError; `LazyInitializationException`; queries logged during view render.
+- **Why hard to find**: bug appears only after session close (background job, async response, serialization in another thread).
+- **Where to look**: DRF serializers, Jinja/Django templates, Hibernate `@OneToMany(fetch = LAZY)` accessed post-session, FastAPI response models, Rails view partials.
+- **Fix direction**: eager-load in the query that produced the object; or convert to plain DTO before crossing the scope boundary; SQLAlchemy `expire_on_commit=False` + explicit loads; Hibernate `JOIN FETCH`.
+
+### 6. Mass UPDATE / DELETE without correct WHERE
+- **Signature**: `UPDATE users SET ...` with no `WHERE`, or `WHERE 1=1`, or predicate built from a possibly-empty filter list (`WHERE id IN ({ids})` where `ids` is `[]` and templates to `IN ()` or `IN (1)`).
+- **Why hard to find**: tests with seeded data pass; the empty-filter branch only hits at runtime with an unexpected input.
+- **Where to look**: admin actions, bulk endpoints, cleanup jobs, query builders that interpolate user-supplied lists, ORM `.update()` on an unfiltered queryset.
+- **Fix direction**: refuse to execute when filter is empty; require explicit confirmation flag for full-table operations; in Django, `Model.objects.update(...)` on the manager is a known footgun — force `.filter(...)` first.
+
+### 7. SQL injection via string concatenation
+- **Signature**: f-strings / template literals / `+` building SQL with user input; `cursor.execute(f"... {user_input}")`; `db.raw('SELECT ... ' + name)`; dynamic `ORDER BY` from query param.
+- **Why hard to find**: parameterized queries elsewhere create false sense of safety; injection often hides in `ORDER BY`, `LIMIT`, table/column names where placeholders don't work.
+- **Where to look**: any raw SQL helper, search endpoints, reporting/CSV exports, dynamic sort/filter, admin-only tooling (still privilege-escalation surface).
+- **Fix direction**: parameterized queries everywhere; for identifiers, use an allow-list mapping, not interpolation. Cross-ref `security-auth.md`.
+
+### 8. Cursor / connection not closed; pool exhaustion
+- **Signature**: streaming query (`cursor.execute` + iterate) without `with` / `try/finally`; long-lived sessions; connection acquired before slow work; `defer conn.Close()` missing; connection leak in error paths.
+- **Why hard to find**: leak rate is small; pool drains over days, then sudden total stall.
+- **Where to look**: streaming exports, batch processors, error branches that early-return without releasing, request handlers that fetch a connection then await external I/O.
+- **Fix direction**: context-manager / `try-with-resources` always; acquire connection as late as possible, release as early as possible; set pool `maxLifetime` and `leakDetectionThreshold`; monitor in-use vs idle counts.
+
+### 9. Bulk insert without batching; non-backwards-compatible migration
+- **Signature**: `for row in rows: db.insert(row)` for 100k rows; one giant transaction; `ALTER TABLE ... DROP COLUMN` or `NOT NULL` added in same release as code that still reads/writes the column.
+- **Why hard to find**: works fine in staging with small datasets; in prod causes lock storms, replication lag, or hard failures during rolling deploy.
+- **Where to look**: ETL/import scripts, seed jobs, `migrations/` adjacent to recent app code changes that drop/rename columns or change nullability.
+- **Fix direction**: batch inserts (chunks of 500-5000), use `COPY` / `INSERT ... ON CONFLICT` / bulk APIs; for migrations follow expand-contract: add nullable column → backfill → ship code that writes both → ship code that reads new → drop old. Never drop a column in the same release as the code that stops writing it.
+
+## Distributed Systems Patterns
+
+### 10. Retry without idempotency
+- **Signature**: `withRetry(() => chargeCard(...))`, `for attempt in range(3): post(...)`, queue consumer that reprocesses on exception, no `Idempotency-Key` header, no dedup table.
+- **Why hard to find**: happy path is fine; only manifests when the first attempt actually succeeded but the response was lost (timeout, 502, network partition).
+- **Where to look**: payment / charge / refund, email / SMS send, order placement, webhook delivery, queue consumers with at-least-once semantics, any `POST` wrapped in retry.
+- **Fix direction**: caller generates an idempotency key (UUIDv4 per logical intent, NOT per HTTP attempt); server stores `(key → response)` in same transaction as the side effect; replay returns stored response. Use natural keys where possible (order ID, request ID).
+
+### 11. Retry storm / thundering herd
+- **Signature**: fixed retry delay, no jitter, all clients retrying on the same wall-clock boundary, cron `* * * * *` firing identical work, cache-miss stampede after expiry.
+- **Why hard to find**: looks like a sudden upstream outage caused by your own retries; metrics show synchronized spikes.
+- **Where to look**: retry helpers without jitter, `setTimeout(retry, 1000)` style, cron-driven jobs across many instances, post-outage reconnect floods.
+- **Fix direction**: exponential backoff **with full jitter** (`sleep = random(0, base * 2^attempt)`); cap max retries; circuit-break after N consecutive failures; stagger cron with random offset; for caches, use single-flight / probabilistic early refresh.
+
+### 12. Retry-After ignored / DOS upstream
+- **Signature**: 429 / 503 response with `Retry-After` header but code retries on its own schedule; rate-limit headers (`X-RateLimit-Reset`, `RateLimit-Reset`) unread.
+- **Why hard to find**: works during normal traffic; under upstream pressure, your retries amplify the outage.
+- **Where to look**: HTTP client wrappers, third-party SDK calls (Stripe, Slack, GitHub, OpenAI), webhook senders.
+- **Fix direction**: honor `Retry-After` (delta-seconds or HTTP-date); combine with circuit breaker; never retry faster than the server requests.
+
+### 13. No circuit breaker / cascade failure
+- **Signature**: upstream timeout, downstream keeps calling, request queue depth climbs, threads/goroutines all blocked on the dead dependency, healthy traffic starves.
+- **Why hard to find**: looks like a problem with your own service; root cause is one slow dependency.
+- **Where to look**: every cross-service / cross-network call without a `CircuitBreaker`, `Polly`, `resilience4j`, `gobreaker`, or equivalent; SDKs that default to infinite retries.
+- **Fix direction**: wrap remote calls in a circuit breaker (closed / open / half-open); shed load fast (fail-fast) when open; set tight per-call timeouts; bulkhead pools so one dependency can't drain all workers.
+
+### 14. Timeouts not propagated (deadline leak)
+- **Signature**: caller has 5s budget, calls downstream with no timeout or its own 30s timeout; gRPC `context.Context` not threaded; HTTP server cancels but worker keeps running; `AbortController` never wired.
+- **Why hard to find**: upstream gave up but downstream still computes/writes — orphan work, double-write, wasted resources.
+- **Where to look**: service-to-service handlers, background goroutines spawned per request, async tasks fired without cancellation tokens, ORM queries with no statement timeout.
+- **Fix direction**: thread the deadline (Go `context`, .NET `CancellationToken`, JS `AbortSignal`, gRPC deadlines); set DB `statement_timeout`; on cancellation, abort downstream work; budget time across the call graph.
+
+### 15. Clock skew assumed away
+- **Signature**: ordering events by `Date.now()` from multiple machines, leases / TTLs using local clock, "is this token expired" by comparing two services' clocks, sequence numbers derived from timestamp.
+- **Why hard to find**: NTP usually keeps drift small; bugs surface during NTP outages, VM live-migration, or container clock jumps.
+- **Where to look**: distributed locks, leader election, audit logs ordered across services, JWT / OAuth expiry checks, dedup windows.
+- **Fix direction**: use logical clocks (Lamport, vector clocks) or monotonic IDs for ordering; allow ± skew margin on expiry checks; for leases use a single source of time (the holder, or the coordinator).
+
+### 16. Leader election split-brain
+- **Signature**: two nodes both believe they're leader during partition; fencing token absent; "I'm leader if I held the lock 5s ago" without renewal/expiry check.
+- **Why hard to find**: requires a real partition or GC pause to reproduce; tests almost never cover it.
+- **Where to look**: custom leader code, ZooKeeper/etcd/Consul integrations, Redis-based locks (Redlock pitfalls), cron singletons.
+- **Fix direction**: use a consensus system (etcd, ZooKeeper, Consul); always pass a **fencing token** to downstream writes so the stale leader's writes are rejected; on lease loss, stop work immediately.
+
+### 17. At-least-once consumer without dedup
+- **Signature**: SQS / Kafka / RabbitMQ consumer that processes message then commits offset; "exactly once" claimed but not implemented; no dedup table, no idempotency key on message.
+- **Why hard to find**: redelivery is rare; duplicates show up as double-charge, double-email, double-record-created — often noticed only by users.
+- **Where to look**: queue consumers, webhook receivers, Kafka stream processors, event-sourcing projections.
+- **Fix direction**: treat all delivery as at-least-once; dedup by message ID in a unique-keyed table (commit dedup row + side effect in same transaction); or use idempotent operations (upserts, set-not-add).
+
+### 18. Out-of-order delivery breaking event sourcing
+- **Signature**: events processed in arrival order, not in causal/sequence order; partition key not chosen to preserve per-entity order; consumer assumes monotonic version.
+- **Why hard to find**: most partitions deliver in order; reorder happens on rebalance, retry, or fan-out.
+- **Where to look**: Kafka consumers with multiple partitions per entity, SQS standard queues (not FIFO), pub/sub fan-out, projection rebuilds.
+- **Fix direction**: partition by entity ID so per-entity order is preserved; include a sequence number / version on each event; consumer rejects stale versions; use FIFO queues where strict order matters.
+
+### 19. Read-your-writes failure on eventually-consistent store
+- **Signature**: write to leader / primary, immediate read from replica / cache; user submits form and the new value doesn't appear; DynamoDB `ConsistentRead=false`, S3 list-after-write, read replica lag.
+- **Why hard to find**: passes in dev with single node; in prod the replica lag window is just long enough for the user to refresh.
+- **Where to look**: post-write redirects, "view your submission" pages, search-after-index, cache-invalidate-then-read.
+- **Fix direction**: read from primary after a write within a session; use `ConsistentRead=true`; sticky-session on a read-your-writes token; or render the just-written value from the response, don't re-fetch.
+
+### 20. Cache stampede / dogpile
+- **Signature**: TTL expires, N concurrent requests all miss, all recompute, all write back — origin gets hammered.
+- **Why hard to find**: invisible until traffic crosses a threshold; logs show synchronized origin spikes at TTL boundaries.
+- **Where to look**: cache wrappers (`getOrSet`, `remember`), hot-key reads (homepage, feature flags), Redis caches with sharp TTLs.
+- **Fix direction**: single-flight / request coalescing (one fetch fills for all waiters); probabilistic early refresh (XFetch / "stale-while-revalidate"); jitter TTLs; for very hot keys, refresh in background. Cross-ref `concurrency-races.md`.
+
+### 21. Webhook receiver not idempotent
+- **Signature**: webhook handler creates row / sends email per request, no dedup on event ID; provider retries on 5xx or timeout; signature verified but ID not stored.
+- **Why hard to find**: providers (Stripe, GitHub, Shopify) explicitly send retries on any non-2xx or slow response; bug shows as duplicate side effects after a brief outage.
+- **Where to look**: `/webhooks/...` routes, event handlers, third-party integration endpoints.
+- **Fix direction**: persist event ID with unique constraint before doing work; on duplicate, return 200 with no side effect; return 2xx fast (under provider timeout) and process async if work is slow.
+
+### 22. "Distributed transaction" implemented as sequential calls
+- **Signature**: `chargeCard(); createOrder(); sendConfirmation();` with no rollback path; "if step 3 fails we'll log it"; 2PC named but not actually two-phase; saga without compensation.
+- **Why hard to find**: happy path works; partial failures leave the system inconsistent — money taken with no order, order with no notification.
+- **Where to look**: orchestration code, multi-service workflows, checkout / signup flows, anything touching ≥ 2 systems.
+- **Fix direction**: saga with explicit **compensating actions** for each step; transactional outbox to publish next step; idempotent steps so retry is safe; persist saga state so a restart can resume.
+
+### 23. Stale cache invalidation (wrong region / partial)
+- **Signature**: invalidate one cache layer but not another (CDN vs origin vs in-process); invalidate one region of a multi-region cache; "wait, cache uses different key shape than read".
+- **Why hard to find**: stale data shows up only to users routed to the missed region or layer; varies by geography or load balancer routing.
+- **Where to look**: multi-tier cache (CDN + Redis + in-process), multi-region deployments, cache key construction code, fan-out invalidation.
+- **Fix direction**: invalidate at the lowest layer that all readers share; pub/sub invalidation events across all instances/regions; cache key includes version stamp so write bumps the version (read can't see stale).

package/skills/bug-scan/references/error-handling.md

@@ -0,0 +1,197 @@
+# Error Handling & Control Flow — Bug Reference
+
+> **When to load this reference**: when scanning code that throws/catches/raises, returns
+> Result/Either/Option types, uses `defer`/`finally`/`with`, calls fallible operations
+> in sequence, or maintains state across operations that can fail.
+
+Async error handling (unawaited rejections, swallowed promise errors, AbortError) lives in
+`async-promises.md`. Concurrent state corruption lives in `concurrency.md`.
+
+## Detection signals
+
+- Broad catches: `catch\s*\(\s*\w*\s*\)\s*\{`, `except\s*:`, `except\s+Exception`, `except\s+BaseException`, `rescue\s*$`, `catch\s*\(Throwable`, `catch\s*\(Exception\s+\w+\)`
+- Silent swallows: `catch.*\{\s*\}`, `except.*:\s*pass`, `_\s*=\s*err`, `// ignore`, `# nosec`, `if err != nil \{\s*return\s*\}` (no wrap, no log)
+- Bang/unwrap: `\.unwrap\(\)`, `\.expect\(`, `\.unwrap_or_else\(\|_\|`, `!!`, `as!`, `try!`, `Result\.get`, `Optional\.get\(\)`
+- Panic/abort: `panic\(`, `panic!\(`, `process\.exit`, `os\.exit`, `std::process::abort`, `fatalError\(`, `assert\(false`
+- Finally/defer: `finally\s*\{[^}]*return`, `finally\s*\{[^}]*throw`, `defer\s+\w+\(`, `defer\s+func\(\)`, `recover\(\)` outside `defer`
+- Lost context: `raise\s+\w+\(.+\)\s*$` (no `from`), `fmt\.Errorf\(".*"\s*,\s*err\)` without `%w`, `throw new Error\(.*\.message`
+- Sentinels: `return -1`, `return None  #`, `return null;  //`, magic numbers in error positions
+- Retry: `for\s*\{`, `while\s+True:`, `while\s*\(true\)` containing fallible call without sleep/backoff/counter
+
+## Patterns
+
+### 1. Pokemon catch — "gotta catch 'em all"
+- **Signature**: `try { ... } catch (_) {}`, `except: pass`, `catch (Throwable t) { log(t); }`, `except BaseException:`.
+- **Why hard to find**: tests pass, logs may even show the exception, but `KeyboardInterrupt`, `SystemExit`, `OutOfMemoryError`, `AssertionError` (programming bugs) are silently absorbed alongside the I/O error you actually wanted to handle.
+- **Where to look**: top-level request handlers, plugin loaders, "defensive" wrappers around third-party calls, anywhere a developer wrote "just don't crash."
+- **Example**: `try: do_work() except: log("oops")` — masks a typo'd attribute access forever.
+- **Fix direction**: catch the narrowest type that you have a recovery story for; let everything else propagate. If you must catch broadly at a boundary, re-raise after logging and never catch `BaseException`.
+- **Language variants**: Python (`except:` or `except BaseException:`), Java (`catch (Throwable)`), JS (`catch` with no filter), Ruby (`rescue` with no class), Swift (`catch { }` without pattern).
+
+### 2. Broad catch + log-and-continue with broken invariants
+- **Signature**: `except Exception as e: log(e); # function returns normally with half-built object`.
+- **Why hard to find**: the function "succeeds," callers see no error, but the returned object is missing fields or its database row is in a tombstoned state. Bugs surface far from the cause.
+- **Where to look**: constructors, builder methods, multi-field setters, ORM `save` paths with derived fields.
+- **Example**: builder catches a validation error in step 3 of 5, returns the partially-populated object as if valid.
+- **Fix direction**: catch → log → re-raise, OR catch → mark object invalid / roll back partial mutations before returning. Never let a caller observe a half-built result via the "happy" return path.
+- **Language variants**: universal; particularly common in Python `__init__`, Go constructors that return `(T, error)` and then return `T` zero-value on err.
+
+### 3. `finally` overwrites the return value
+- **Signature**: `try: return x finally: return y`, JS `try { return a; } finally { return b; }`, Java `try { return ok; } finally { return fallback; }`.
+- **Why hard to find**: looks correct line-by-line; control flow is genuinely surprising — `finally`'s return wins.
+- **Where to look**: cleanup code that "just to be safe" returns a default; transaction commit helpers.
+- **Example**: function returns success even though `try` raised, because `finally` returned `False`.
+- **Fix direction**: never `return` (or `break`/`continue`) from `finally`; set a variable inside try and return after.
+- **Language variants**: Python, JS/TS, Java, C#. Go's `defer` cannot do this (defers don't return), but a deferred function can overwrite named returns — `defer func() { err = nil }()` is the same class of bug.
+
+### 4. `finally` raises and loses the original exception
+- **Signature**: `finally:` block that calls `conn.close()` or `f.flush()` which itself throws.
+- **Why hard to find**: traceback shows only the cleanup error; the real bug (the original exception) vanishes. Connection leaks compound it.
+- **Where to look**: resource cleanup paths, `__exit__` methods, Go deferred `Close()` calls.
+- **Example**: db query throws `IntegrityError`, `finally: conn.close()` raises `NameError` because conn was never assigned — only the `NameError` propagates.
+- **Fix direction**: initialize resource vars to `None`/`nil` before `try`; guard cleanup with `is not None`; wrap cleanup itself in try/except and log secondary errors without raising. In Python 3, `__context__` preserves chain — verify it's actually being logged.
+- **Language variants**: Python (`finally`), Java (try-with-resources mostly fixes this — flag manual `finally { close }`), Go (`defer f.Close()` discarding error), C# (`using` good, manual `finally` bad).
+
+### 5. Multi-step operation, no transaction, no compensation
+- **Signature**: sequence of side-effecting calls (`charge_card`; `create_order`; `send_email`) with no rollback if step N fails.
+- **Why hard to find**: happy path is fine; failures produce orphaned charges, ghost orders, duplicate emails. Surfaces as customer support tickets, not stack traces.
+- **Where to look**: checkout flows, signup flows, anywhere two systems of record are mutated, file-system + DB combos.
+- **Example**: payment succeeds, DB insert fails on unique constraint → customer charged with no order.
+- **Fix direction**: wrap in a transaction where possible; otherwise use saga / outbox pattern with explicit compensation per step; make steps idempotent so retry is safe.
+- **Language variants**: universal. Particularly toxic in microservice call chains.
+
+### 6. Confirm-after-commit with no rollback
+- **Signature**: `db.commit(); send_confirmation(...)` where confirmation failure has no recovery.
+- **Why hard to find**: the DB row exists, the user never gets the email/webhook, and the system has no record that the side-channel failed.
+- **Where to look**: order confirmations, webhook dispatch, audit-log writes after commit.
+- **Example**: order committed, SES throws; user thinks order failed and re-orders; second order also commits.
+- **Fix direction**: outbox pattern — write the "needs confirmation" row in the same transaction; a separate worker drains it with retries and idempotency keys.
+- **Language variants**: universal; especially common with Stripe, SES, SNS, Kafka producers.
+
+### 7. Re-raise loses original cause/stack
+- **Signature**: Python `raise NewError("wrap")` (no `from e`); JS `throw new Error('wrap: ' + e.message)`; Java `throw new RuntimeException("wrap")` without cause arg.
+- **Why hard to find**: code looks like it's "translating" errors helpfully; debugging discovers the inner stack is gone, you only see the outer frame.
+- **Where to look**: exception-translation layers, repository wrappers around driver exceptions, API boundaries.
+- **Example**: `except ValueError: raise AppError("bad input")` — caller has no idea which field, which line, which driver code raised.
+- **Fix direction**: Python `raise AppError(...) from e`; JS `throw new Error(msg, { cause: e })`; Java `new RuntimeException(msg, e)`; Rust use `source()` chain via `thiserror`/`anyhow`.
+- **Language variants**: every language with exceptions.
+
+### 8. Go: `return err` without wrapping
+- **Signature**: `if err != nil { return err }` repeated up the stack with no context added.
+- **Why hard to find**: top-level log shows `EOF` or `connection refused` with zero indication of which call site, which user, which record.
+- **Where to look**: any Go function with multiple fallible calls in sequence.
+- **Example**: `os.Open` deep in a tree returns plain `EOF`; caller logs "EOF" and the on-call engineer has nothing.
+- **Fix direction**: `return fmt.Errorf("loading user %d: %w", id, err)` — `%w` preserves the chain for `errors.Is`/`errors.As`.
+- **Language variants**: Go-specific. Rust analog: bare `?` without `.context(...)` from `anyhow`.
+
+### 9. Go: shadowed `err` in nested block
+- **Signature**: outer `var err error` (or `err :=`), inner block uses `:=` introducing a new `err`. Outer stays `nil`.
+- **Why hard to find**: code reads naturally; `go vet -vettool=shadow` catches some cases, default `go vet` does not.
+- **Where to look**: `if x, err := f(); err != nil { ... }` inside a function that also has an outer `err`. Loops that capture `err` from a closure.
+- **Example**: `err := outerCall(); if err == nil { v, err := innerCall(); _ = v }` — outer `err` from any later branch is unset because the inner `err` shadowed and was discarded.
+- **Fix direction**: rename inner var, use `=` instead of `:=`, or run `shadow` analyzer in CI.
+- **Language variants**: Go (most common). JS `let` shadowing in nested blocks is similar but usually caught by linters.
+
+### 10. Go: `defer` evaluates args at defer-time, not call-time
+- **Signature**: `defer fmt.Println(time.Now())`, `defer log.Printf("dur=%v", time.Since(start))` where `start` was captured by value but the *computation* `time.Since(...)` is the argument.
+- **Why hard to find**: looks like the deferred line will run at function exit — and the function call does — but argument expressions are evaluated immediately. `time.Now()` is the *defer* timestamp, not exit time.
+- **Where to look**: timing/logging defers, defers logging mutable state.
+- **Example**: `defer log.Printf("user=%v", user)` logs the user pointer at defer time; if `user` is reassigned later, the *value* logged is the early one (or for pointers, the late one — both confusing).
+- **Fix direction**: wrap in a closure: `defer func() { log.Printf("dur=%v", time.Since(start)) }()`.
+- **Language variants**: Go-specific. Swift `defer` evaluates at scope-exit (different semantics) — flag developers porting Go habits.
+
+### 11. Go: `recover()` outside the deferred function
+- **Signature**: `recover()` called directly in a function body, or inside a function called *from* a `defer` (one stack frame too deep).
+- **Why hard to find**: looks like it should catch panics; doesn't. Process crashes anyway.
+- **Where to look**: middleware wrappers, goroutine entry points, custom panic handlers.
+- **Example**: `func safe() { if r := recover(); r != nil { ... } }; defer safe()` — `recover` must be in the deferred function itself.
+- **Fix direction**: call `recover` *directly* in the deferred closure: `defer func() { if r := recover(); r != nil { ... } }()`. Also: every goroutine needs its own recover; panics don't cross goroutine boundaries.
+- **Language variants**: Go-specific.
+
+### 12. Rust: `.unwrap()` / `.expect()` on attacker-controlled input
+- **Signature**: `.unwrap()` on a `parse()`, `from_str()`, header lookup, env var, JSON deserialize, or array index driven by request data.
+- **Why hard to find**: unit tests pass with happy input; fuzzed or malicious input triggers panic; in a multi-threaded server one bad request can poison shared mutexes (`PoisonError`).
+- **Where to look**: HTTP handlers, deserialization layers, CLI arg parsing, indexing into `Vec`/slices with user-provided offsets.
+- **Example**: `let id: u64 = req.param("id").unwrap().parse().unwrap();` — any non-numeric `id` crashes the worker.
+- **Fix direction**: propagate with `?`, return a typed error, or use `.ok_or(...)` / `.map_err(...)`. Reserve `expect` for invariants you can prove (and write the proof in the message).
+- **Language variants**: Swift `!`/`try!`/`as!`, Kotlin `!!`, Java `Optional.get()`, JS `JSON.parse` thrown into untyped flow.
+
+### 13. Rust: `?` in `main` returning `Box<dyn Error>` loses detail
+- **Signature**: `fn main() -> Result<(), Box<dyn Error>> { ... ? ... }` with no error formatter.
+- **Why hard to find**: output is one line, no chain, no backtrace by default.
+- **Where to look**: CLI tools and examples; small services that grew up.
+- **Example**: a file-not-found error 6 calls deep prints as `No such file or directory (os error 2)` with no path, no operation.
+- **Fix direction**: use `anyhow::Result` + `.context(...)` at boundaries; or `eyre`/`color-eyre`; enable `RUST_BACKTRACE`; print the chain via `{:?}` of `anyhow::Error`.
+- **Language variants**: Rust-specific.
+
+### 14. JS/TS: throwing non-Error values
+- **Signature**: `throw "bad input"`, `throw { code: 500 }`, `reject("nope")`, `throw 42`.
+- **Why hard to find**: `instanceof Error` checks fail; `.stack`/`.message` are undefined; type-narrowed `catch (e: unknown)` code paths are skipped or crash.
+- **Where to look**: legacy code, hand-rolled validators, libraries that "rejected" with strings.
+- **Example**: `catch (e) { logger.error(e.message); }` logs `undefined` and you lose the original value entirely.
+- **Fix direction**: always throw `Error` subclasses; if you must accept anything, normalize at catch sites with `e instanceof Error ? e : new Error(String(e))`.
+- **Language variants**: JS/TS. Python `raise "x"` is a SyntaxError so this class is JS-specific.
+
+### 15. JS/TS: try wrapping too much — adjacent code swallowed
+- **Signature**: `try { const j = JSON.parse(s); doStuff(j); render(j); } catch (e) { return null; }`.
+- **Why hard to find**: developer meant to catch parse errors only; bugs in `doStuff`/`render` also return `null` and are reported as "data missing."
+- **Where to look**: any `try` that wraps both an obviously-fallible call and "normal" code.
+- **Example**: a `TypeError` from `doStuff(j)` returns `null`; UI shows empty state forever.
+- **Fix direction**: shrink the `try` to *only* the fallible operation; handle the parsed value outside.
+- **Language variants**: universal; particularly bad in JS/TS where `catch` is untyped.
+
+### 16. Python: `except Exception` re-raised without `from`
+- **Signature**: `except Exception as e: raise CustomError("oops")` — note the missing `from e`.
+- **Why hard to find**: Python 3 implicitly sets `__context__`, but explicit `from None` or assignment can suppress it; even with implicit chaining the traceback shows "During handling of the above exception, another exception occurred" which many devs mistake for noise.
+- **Where to look**: framework boundaries, ORM wrappers, service-layer translation.
+- **Example**: SQLAlchemy `IntegrityError` swallowed; caller gets `CustomError("oops")`; root cause invisible in Sentry filters.
+- **Fix direction**: `raise CustomError("oops") from e`. Ensure your logger formats `__cause__` and `__context__`.
+- **Language variants**: Python.
+
+### 17. Logged-but-not-propagated
+- **Signature**: `try: do() except E: log.error(e)` with no `raise`, no return-value change, no retry queue, no alert.
+- **Why hard to find**: log line exists somewhere; caller's contract says "succeeded"; downstream code proceeds as if the operation worked.
+- **Where to look**: background jobs, scheduled tasks, "best-effort" code paths, event handlers.
+- **Example**: webhook delivery fails, logged at WARN; the parent loop marks the event "processed" and moves on.
+- **Fix direction**: decide explicitly — fail loudly, schedule retry, dead-letter, or document "best-effort" in the function contract. Logs are not error handling.
+- **Language variants**: universal.
+
+### 18. Partial mutation then raise — invariant broken
+- **Signature**: object mutates field A, then calls a fallible operation that throws, leaving field B unchanged. Object is now in a state the type system says is impossible.
+- **Why hard to find**: subsequent reads observe the corrupted state; the function that caused it is long gone.
+- **Where to look**: setters that derive multiple fields, in-place collection mutations, `__setstate__`, ORM `save` overrides, struct-update sequences.
+- **Example**: `self.balance -= amount; self.ledger.append(tx)` where `append` raises (OOM, full disk) — balance debited, no record.
+- **Fix direction**: compute new state into locals first, swap atomically at the end (functional-core / commit-at-end). Or use a real transaction. Or store a snapshot and restore on except.
+- **Language variants**: universal; especially insidious in OOP languages with mutable objects.
+
+### 19. Sentinel return values silently ignored
+- **Signature**: function returns `-1`, `None`, `null`, `""`, `nil`, `0` on error; callers use the value without checking.
+- **Why hard to find**: type system permits it; tests with happy values pass; the `-1` flows into arithmetic, indexing, or comparisons producing wrong-but-plausible results.
+- **Where to look**: C/C++ APIs returning errno-style codes, legacy Java returning `null`, JS functions returning `undefined`, Python returning `None` on "not found."
+- **Example**: `int n = read(fd, buf, sz);` then loop uses `n` as length — `-1` interpreted as huge unsigned value.
+- **Fix direction**: use `Result`/`Either`/`Optional`/exceptions; if stuck with sentinels, lint for unchecked return values (`-Wunused-result`, `errcheck`).
+- **Language variants**: C, C++, Go (`(T, error)` pair but ignored `error`), Java, JS.
+
+### 20. Comparing errors by message string
+- **Signature**: `if str(e) == "user not found":`, `if err.Error() == "EOF"`, `if (err.message.includes("timeout"))`.
+- **Why hard to find**: works in dev; breaks when library updates wording, when locale changes (Windows + non-English), when message includes a path/id.
+- **Where to look**: retry logic that classifies errors, test assertions, error-translation layers.
+- **Example**: code retries when `err.Error() == "connection refused"` — driver upgrade changes wording to `"dial: connection refused"` and retries silently stop.
+- **Fix direction**: use typed errors / `errors.Is` / `errors.As` (Go), exception subclasses (Python/Java), `instanceof` chains (JS), error codes (POSIX `errno`).
+- **Language variants**: universal.
+
+### 21. Retry without max attempts or backoff
+- **Signature**: `while True: try: do() except: continue`, `for { if err := f(); err != nil { continue } }`.
+- **Why hard to find**: works during transient blips; on a persistent failure (auth revoked, deleted resource, schema mismatch) it becomes a tight CPU loop or self-DDoS of the dependency.
+- **Where to look**: HTTP clients, database call sites, message-broker consumers, custom retry decorators.
+- **Example**: token expired permanently; retry loop hammers IdP at 100k req/s and tokens are now rate-limited org-wide.
+- **Fix direction**: bounded attempts + exponential backoff + jitter + circuit breaker; distinguish transient (429, 5xx, timeout) from terminal (4xx auth, 404) and never retry terminal.
+- **Language variants**: universal; lean on libraries (`tenacity`, `backoff`, `cenkalti/backoff`, `tokio-retry`).
+
+### 22. Asserts disabled in production hide invariant checks
+- **Signature**: `assert user.is_valid()`, `assert!(invariant)` used for runtime checks; Python `-O` strips them, C `NDEBUG` strips them, Rust `debug_assert!` only fires in debug.
+- **Why hard to find**: dev/CI runs catch issues; production silently proceeds with invariants violated.
+- **Where to look**: input validation that uses `assert`, "this can't happen" checks, security-relevant pre-conditions.
+- **Example**: `assert tenant_id == request.tenant_id` — stripped in prod build; cross-tenant leak.
+- **Fix direction**: use real conditionals + raise/return for runtime invariants; reserve assert for true never-can-happen sanity checks.
+- **Language variants**: Python (`-O`), C/C++ (`NDEBUG`), Rust (`debug_assert!`), Swift (`assert` vs `precondition`).

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

@@ -0,0 +1,94 @@
+# Gate-Bugs Item Template
+
+> Used by `bug-scan` in **gate mode** to convert each finding into a substrate item under
+> `.work/active/stories/` (or `.work/backlog/` for Low). Mirrors the gate-security pattern.
+
+## File location
+
+- Critical / High → `.work/active/stories/<id>.md` with `stage: implementing`
+- Medium → `.work/active/stories/<id>.md` with `stage: drafting`
+- Low → `.work/backlog/<id>.md` (not stage-managed)
+
+## ID convention
+
+`gate-bugs-<short-slug>` where slug describes the finding briefly.
+
+Examples:
+- `gate-bugs-stale-closure-cart-effect`
+- `gate-bugs-tx-not-rolled-back-on-error`
+- `gate-bugs-await-in-foreach-callback`
+- `gate-bugs-goroutine-leak-on-blocked-send`
+
+Keep slugs ≤ 40 chars after the prefix. If you hit the same slug twice, suffix `-2`, `-3`.
+
+## Frontmatter + body template
+
+```yaml
+---
+id: gate-bugs-<short-slug>
+kind: story
+stage: implementing      # Critical or High
+                         # OR drafting for Medium
+                         # OR (omit, in backlog/) for Low
+tags: [bug, <domain-tag>]
+parent: null
+depends_on: []
+release_binding: <version>
+gate_origin: bugs
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+---
+
+# <one-line title>
+
+## Severity
+Critical | High | Medium | Low
+
+## Domain
+<concurrency | async | state | resource-leak | time-numbers | error-handling | data-layer | language-footgun>
+
+## Pattern
+<named pattern from references/<domain>.md — or "new" if not catalogued>
+
+## Location
+`<file>:<line>`
+
+## Evidence
+\`\`\`<lang>
+<short code snippet, 1-5 lines>
+\`\`\`
+
+## Why it's a bug
+<1-2 sentences — the specific failure mode under realistic conditions>
+
+## Remediation direction
+<what should change — direction, not a finished fix>
+
+## Also flagged by
+<other domain(s), if this same location was flagged elsewhere; otherwise omit section>
+```
+
+## Domain tag mapping
+
+| 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 items also carry the umbrella `bug` tag, so the substrate can grep "all bug findings"
+in one filter.
+
+## Rules
+
+- One finding = one item. Do not bundle. Even if two findings share a file, separate them.
+- `release_binding` must match the release version that invoked the gate.
+- `gate_origin: bugs` is required — that's how `release-deploy` identifies these items as
+  gate output and how re-runs detect duplicates.
+- Set `created` and `updated` to today's ISO date.
+- After creating all items, commit them in a single commit: `gate-bugs: <N> findings for <version>`.