@nklisch/pi-agile-workflow 0.15.3

package/skills/bug-scan/SKILL.md

@@ -0,0 +1,378 @@
+---
+name: bug-scan
+description: >
+  Deep multi-angle correctness bug hunt. Use when the user asks to "scan for bugs", "bug hunt", "deep
+  bug audit", "find hidden bugs", "find race conditions", or audit lurking correctness issues. Fans
+  parallel scanner agents across relevant domains such as concurrency, async, state, resource
+  leaks, time/numbers, error handling, data layer, and language footguns. Standalone mode writes a
+  scored report; gate mode binds to a release bundle and emits .work/active/stories/ items with
+  gate_origin:bugs. Distinct from gate-security, review, perf-design, and repo-eval.
+---
+
+# Bug-Scan
+
+You orchestrate a deep, multi-angle hunt for hard-to-find correctness bugs. You detect the
+stack, choose relevant bug domains, dispatch **one deep scanner agent per selected domain in parallel**, and
+either write a scored report (standalone) or produce items in `.work/active/stories/` (gate
+mode). Use a generic sub-agent prompted with the scanner posture from `../principles/references/subagents.md`. Domain selection is the
+scope-size gate: do not spawn a scanner for a domain just because it exists in the table. Each
+scanner loads only its domain's reference —
+that's the progressive-disclosure move that keeps each scanner focused and the
+orchestrator's context lean.
+
+Scanner strength is explicit: spawn one source-read-only scanner agent per
+selected domain with high inspection/reviewer reasoning. Use a generic sub-agent prompted with the scanner posture from `../principles/references/subagents.md`. Use extra-high reasoning only for
+concurrency, data-layer, or time bugs in high-risk domains, very large scopes,
+or repeat scans that previously missed issues. These are scanners, not fixers.
+- For the dynamic scanner prompt posture, load
+  `../principles/references/subagents.md`. If no suitable scanner subagent adapter is
+  available, use the same-host read-only analysis fallback.
+
+This skill hunts **correctness** bugs, not vulnerabilities, not perf, not style. Use the
+sibling skills for those.
+
+## Modes
+
+### Standalone (default)
+- `/agile-workflow:bug-scan` — scan the whole repo
+- `/agile-workflow:bug-scan <path>` — scope to a directory or glob (`src/api/`, `**/*.ts`)
+- `/agile-workflow:bug-scan --no-park` — write report only, skip backlog parking (any mode)
+
+Output:
+1. `bug-scan-report.md` at the repo root — domain scores, severity-grouped findings,
+   remediation directions, list of parked item ids.
+2. **One parked backlog item per finding** at `.work/backlog/bug-scan-<slug>.md` — minimal
+   frontmatter (`bug_origin: scan`, `bug_severity`, `bug_domain`, `bug_location`) so findings
+   are tracked in the substrate alongside the report. The user can elevate any of them later
+   via `/agile-workflow:scope`. Idempotent on re-runs (existing findings at the same
+   `file:line` are skipped). Suppress with `--no-park`.
+
+> Why not write standalone Criticals straight to `.work/active/stories/`? Standalone is
+> exploratory — the user invoked it to *see* what's there, not commit to fixing it. For
+> release-bound, must-fix-before-ship Criticals, use **gate mode**, which writes to active.
+
+### Gate mode
+- `/agile-workflow:bug-scan --release <version>` — scan only files touched by items bound
+  to that release
+- Auto-invoked by `/agile-workflow:release-deploy` during the quality-gate stage
+
+Output: items in `.work/active/stories/` (Critical/High → `stage: implementing`,
+Medium → `stage: drafting`, Low → backlog), each with `gate_origin: bugs`.
+
+The release ships when all bound items (including these) reach `stage: done` — same as
+gate-security.
+
+## Bug domains (and their references)
+
+The scanner agents each load exactly one of these. Each reference contains ~15-25 patterns
+with grep-style detection signals, "why hard to find" notes, examples, and fix directions.
+
+| Domain | Reference | When to load |
+|---|---|---|
+| Concurrency & races | [references/concurrency-races.md](references/concurrency-races.md) | Code uses threads, processes, goroutines, async runtimes, shared mutable state, locks, channels, atomics |
+| Async / promises | [references/async-promises.md](references/async-promises.md) | Code uses async/await, Promise/Future/Task, coroutines, event loops, non-blocking I/O |
+| State & closures | [references/state-closures.md](references/state-closures.md) | Code uses closures over loop vars, framework reactivity (React/Vue/Svelte/Solid), stores (Redux/Zustand/Pinia), TanStack Query |
+| Resource leaks | [references/resource-leaks.md](references/resource-leaks.md) | Code opens files/sockets/connections, subscribes, registers listeners, schedules timers, spawns threads/processes, acquires locks |
+| Time & numbers | [references/time-numbers.md](references/time-numbers.md) | Code handles dates/timestamps/durations, money, percentages, float comparisons, integer overflow risk |
+| Error handling | [references/error-handling.md](references/error-handling.md) | Code throws/catches/raises, returns Result/Either, uses defer/finally/with, calls fallible operations in sequence |
+| Data layer | [references/data-layer.md](references/data-layer.md) | Code touches a database, ORM, message queue, external service, or coordinates across processes |
+| Language footguns | [references/language-footguns.md](references/language-footguns.md) | Always relevant — the scanner reads only the section matching the detected language |
+
+## Phase 1: Stack discovery
+
+Detect what you're scanning:
+- **Languages** — file extensions, manifests (`package.json`, `tsconfig.json`, `pyproject.toml`,
+  `Cargo.toml`, `go.mod`, `pom.xml`, `build.gradle`, `*.csproj`, `Gemfile`).
+- **Frameworks** — React, Vue, Svelte, Next, Nuxt, Django, FastAPI, Rails, Spring, Actix, Axum,
+  Express, NestJS, Tokio, asyncio.
+- **Data layer** — Prisma, Drizzle, SQLAlchemy, Django ORM, ActiveRecord, Mongoose, Redis,
+  Kafka, NATS, SQS.
+- **Concurrency primitives** — goroutines, threads, asyncio.create_task, tokio::spawn, workers.
+- **Entry points** — API routes, CLI mains, background workers, cron, webhook handlers.
+
+Summarize the stack in 4-6 lines.
+
+## Phase 2: Domain selection
+
+Map detected stack features to the 8 domains. Mark each as **most relevant**, **relevant**,
+or **skip** based on what's in the code and the concrete scan scope. For a small
+path with no async, no data layer, and no external resources, skip those domains
+instead of launching empty scanners. For a broad release bundle or repo-wide
+audit, include every domain with real evidence in Phase 1.
+
+### Standalone mode
+**structured question tool checkpoint** (multi-select): show the 8 domains with relevance annotations,
+recommend 4-6 for a focused scan or all 8 for a full audit. Default to all "most relevant" +
+"relevant" if user doesn't choose.
+
+### Gate mode
+Skip the prompt. Default to all domains that touch any file in the bundle.
+
+## Phase 3: Fan-out scan
+
+For each selected domain, spawn **one parallel scanner agent in a single
+message** so they run concurrently.
+
+Use a generic sub-agent prompted with the scanner posture from `../principles/references/subagents.md` with high
+inspection/reviewer reasoning; escalate to extra-high only for high-risk
+domains, very large scopes, or repeat scans that previously missed issues. If a
+host cannot spawn the scanner role, use the same-host read-only analysis
+fallback.
+
+### Scope (passed into every scanner)
+
+- **Standalone**: the user's path arg, or the whole repo if no arg. Resolve to a concrete file
+  list with `git ls-files` (and the path filter, if any).
+- **Gate mode**: only files touched by items bound to the release. `--release`
+  auto-widens to ALL tiers (active + archive + releases). Include late-bound
+  archived stubs — their bodies may be pruned, but the item id still recovers
+  the bundle commits/files. Ignore only the release orchestration item
+  (`kind: release`).
+  ```bash
+  .work/bin/work-view --release <version> --paths | while IFS= read -r item; do
+    kind=$(grep -m1 '^kind:' "$item" | awk '{print $2}')
+    [ "$kind" = "release" ] && continue
+    id=$(grep -m1 '^id:' "$item" | awk '{print $2}')
+    git log --grep "$id" --format='%H' | xargs -I{} git diff-tree --no-commit-id --name-only -r {}
+  done | sort -u > /tmp/bundle-files-<version>.txt
+  ```
+  Capture already-tracked findings to feed back as "skip these":
+  ```bash
+  .work/bin/work-view --release <version> --gate bugs --paths
+  ```
+
+### Scanner brief template
+
+Each scanner gets:
+
+> You are a bug scanner agent for the **<domain>** domain. Use the
+> agile-workflow scanner contract: source-read-only, no fixes, no recursive
+> sub-agents.
+>
+> **Reference (load FIRST)**: `<absolute path to references/<domain>.md>`
+> Read the whole file. It contains the patterns to hunt for in this domain.
+>
+> **Scope** — scan ONLY these files:
+> ```
+> <file list>
+> ```
+>
+> **Stack profile** (from orchestrator):
+> ```
+> <stack summary>
+> ```
+>
+> **Already-tracked findings to skip** (gate mode only):
+> ```
+> <file:line / pattern pairs, or "none">
+> ```
+>
+> **Method**:
+> 1. Load the domain reference. Note the patterns and detection signals.
+> 2. Web-search 1-3 times for current pitfalls in this domain for the specific stack
+>    (e.g. "React 19 stale closure useEffect 2025", "Go 1.22 loop variable gotchas").
+> 3. Apply the reference's grep heuristics to the scope. Read flagged files. Confirm matches
+>    by reading the code — don't report on grep hits alone.
+> 4. For each confirmed bug, record:
+>    - **Title** (one line)
+>    - **Pattern** (which named pattern from the reference; or "new" if not in the reference)
+>    - **Severity** — see rubric below
+>    - **Location** (`file:line`)
+>    - **Evidence** (1-5 lines of the offending code, in a fenced block)
+>    - **Why it's a bug** (1-2 sentences — the specific failure mode)
+>    - **Remediation direction** (a direction, not a finished fix)
+>
+> **Severity rubric** — every finding gets one of:
+> | Severity | Meaning |
+> |---|---|
+> | Critical | Will cause data loss, corruption, hang, or wrong financial outcome under realistic load. Must fix before shipping. |
+> | High | Will cause incorrect behavior or crash under uncommon-but-real conditions (specific input, race window, error path). Must fix before shipping. |
+> | Medium | Real bug, hard to trigger or limited blast radius. Should fix; can defer with explicit acknowledgement. |
+> | Low | Edge case, latent bug, defensive-only. Backlog. |
+> | Info | Not a finding. Don't return Info entries. |
+>
+> **Rules**:
+> - Cite file:line for every finding.
+> - Don't report a pattern unless you read the surrounding code and confirmed the bug applies
+>   here. Grep hits alone are not findings.
+> - Don't fabricate. Empty findings list is a valid answer.
+> - Don't implement fixes. Findings only.
+> - Skip findings matching the already-tracked list.
+>
+> **Output format** — return a single markdown document with:
+> ```
+> ## Domain: <name>
+> ## Stack notes: <one-line> what's relevant
+> ## Findings
+>
+> ### Finding 1
+> - **Title**: ...
+> - **Pattern**: ...
+> - **Severity**: Critical | High | Medium | Low
+> - **Location**: `file:line`
+> - **Evidence**:
+>   ```<lang>
+>   <code>
+>   ```
+> - **Why it's a bug**: ...
+> - **Remediation direction**: ...
+> ```
+> Followed by:
+> ```
+> ## Summary
+> - Files scanned: <n>
+> - Patterns applied: <list>
+> - Findings: Critical=<n>, High=<n>, Medium=<n>, Low=<n>
+> ```
+
+### Wave coordination
+
+- Dispatch all selected scanners in a **single message** (parallel).
+- If a scanner returns an error, record it as a gap in the report — do not re-run blindly.
+- If a scanner returns >25 findings, ask it (via follow-up message) to keep only the top 25 by
+  severity (anything beyond suggests pattern over-matching).
+
+## Phase 4: Aggregate & dedupe
+
+Collect every scanner's findings. Then:
+
+1. **Dedupe** — if the same `file:line` appears in two domains, keep the higher-severity entry
+   and add a "also flagged by: <domain>" note.
+2. **Cluster** — group findings by file. A file with 5+ findings probably needs a single
+   broader "this module needs rework" item rather than 5 small items.
+3. **Sort** — by severity (Critical → High → Medium → Low), then by file.
+4. **Score each domain** 0-10 using the rubric below.
+
+### Domain scoring rubric
+
+| Score | Meaning |
+|---|---|
+| 0-1 | Critical findings present, multiple. Codebase is unsafe in this domain. |
+| 2-3 | One Critical or several High. Major work needed. |
+| 4-5 | Several Medium findings; one Critical/High at most. Hygiene gaps. |
+| 6-7 | Clean — only Low findings or one Medium. Standard quality. |
+| 8-9 | No findings + the code shows proactive defensive patterns (transaction boundaries,
+       AbortControllers, idempotency keys, explicit timeouts, etc.). |
+| 10  | Zero findings + comprehensive defensive design across the domain. |
+
+Floor: a Critical finding caps the domain score at 3. Multiple High caps at 5.
+
+Compute an overall score: weighted average where "most relevant" domains weigh 2x, "relevant"
+weigh 1x. Round to one decimal.
+
+## Phase 5: Output
+
+### Standalone mode
+
+Two outputs: a markdown report AND parked backlog items (unless `--no-park`).
+
+#### 5a. Park findings to backlog (default)
+
+Skip this step entirely if invoked with `--no-park`. Otherwise:
+
+1. **Verify substrate**. If `.work/CONVENTIONS.md` is missing, the project isn't on
+   agile-workflow yet — skip parking, note it in the report, and tell the user to run
+   `/agile-workflow:convert` if they want substrate tracking.
+
+2. **Build the existing-findings index** for idempotency:
+   ```bash
+   mkdir -p /tmp
+   : > /tmp/bugscan-existing.txt
+   for f in .work/backlog/bug-scan-*.md; do
+     [ -f "$f" ] || continue
+     grep -q '^bug_origin: scan$' "$f" || continue
+     loc=$(grep -m1 '^bug_location:' "$f" | awk '{print $2}')
+     [ -n "$loc" ] && echo "$loc $f" >> /tmp/bugscan-existing.txt
+   done
+   ```
+
+3. **Park each finding** as one file at `.work/backlog/bug-scan-<slug>.md` using the template
+   at [references/parked-item-template.md](references/parked-item-template.md). Skip any
+   finding whose `file:line` already appears in `/tmp/bugscan-existing.txt` and tally those
+   as "duplicates skipped". On slug collision, suffix `-2`, `-3`.
+
+4. **Commit** all parked files in one commit:
+   ```bash
+   git add .work/backlog/bug-scan-*.md
+   git commit -m "bug-scan: park <N> findings (<scope>)"
+   ```
+   If working tree was dirty before parking, commit only the new backlog files (`git add`
+   with explicit paths — never `git add -A`).
+
+#### 5b. Write the report
+
+Write to `bug-scan-report.md` in the repo root using the template at
+[references/report-template.md](references/report-template.md). Include:
+
+- Overall score (X.X/10)
+- Per-domain score table
+- Findings grouped by severity, each with its parked item id (or "not parked: --no-park"
+  or "not parked: no substrate")
+- "Top 3" callout for the most-critical findings
+- Domains skipped + why
+- Park summary: parked count, duplicates skipped, opt-outs
+
+#### 5c. Summarize to the user
+
+- Overall score
+- Severity counts (Critical / High / Medium / Low)
+- Top 3 critical findings (one line each, with `file:line`)
+- Path to the report
+- Parked count + duplicates skipped (or "parking skipped (--no-park)" / "parking skipped (no substrate)")
+- **structured question tool** (four options):
+  - "Elevate criticals to `stage:implementing` via `/agile-workflow:scope`"
+  - "Hand top finding to `/agile-workflow:fix` now"
+  - "Dive deeper into a specific domain"
+  - "Done for now — leave the parked items in backlog"
+
+### Gate mode
+
+For each finding above Info, create an item file in `.work/active/stories/` (or backlog for
+Low) using the template at [references/gate-item-template.md](references/gate-item-template.md).
+
+Severity → stage mapping:
+- **Critical** / **High** → `stage: implementing`
+- **Medium** → `stage: drafting`
+- **Low** → backlog file at `.work/backlog/`
+
+ID convention: `gate-bugs-<short-slug>` where slug describes the finding (e.g.
+`gate-bugs-stale-closure-in-cart-effect`).
+
+Commit:
+```bash
+git add .work/active/stories/ .work/backlog/
+git commit -m "gate-bugs: <N> findings for <version>"
+```
+
+Then report to the user (same format as gate-security):
+- Bundle version
+- Findings by severity
+- Items created (count + new ids)
+- Already-tracked duplicates skipped
+- Next step (release ships when bound items reach `stage: done`)
+
+## Guardrails
+
+- **The scanning happens in the scanner agents, not here.** Your job is stack discovery,
+  scanner dispatch, and result aggregation. Do not re-do a scanner's work in the
+  orchestrator's context — that throws away the progressive-disclosure win.
+- **Fan out selected domains.** Once Phase 2 has selected domains, run one
+  scanner per selected domain in parallel. Do not serialize them, and do not
+  spawn skipped domains.
+- **Always cite file:line.** Findings without locations are not findings.
+- **Don't fabricate.** A scanner returning zero findings for a domain is a valid result. Score
+  it honestly (7, not 10 — absence ≠ active hardening).
+- **Confirm grep hits.** Detection signals are starting points, not findings. Every reported
+  bug must have been read and understood in context.
+- **Respect scope.** If the user gave a path, don't expand. If gate mode, scan only the bundle.
+- **No fixes.** This skill produces findings/items only. Remediation goes through
+  `/agile-workflow:fix` or `/agile-workflow:implement`.
+- **Idempotent gate re-runs.** Pass already-tracked findings into scanner briefs so they skip
+  duplicates; double-check on item-write before creating files.
+- **Idempotent standalone re-runs.** Before parking, scan `.work/backlog/bug-scan-*.md` for
+  existing `bug_origin: scan` items, build a `file:line → id` index, and skip findings already
+  present. Tally and report the skip count. This keeps repeated `/agile-workflow:bug-scan`
+  invocations from flooding backlog with the same items.
+- **Standalone parks to backlog, never to active.** Even Critical findings in standalone mode
+  go to `.work/backlog/` — the user explicitly elevates them via `/agile-workflow:scope` if
+  they choose. The path to active is gate mode (release-bound, intentional).

package/skills/bug-scan/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Bug Scan"
+  short_description: "Use Bug Scan for repo workflows"
+  default_prompt: "Use $bug-scan for this repository."
+policy:
+  allow_implicit_invocation: false

package/skills/bug-scan/references/async-promises.md

@@ -0,0 +1,119 @@
+# Async / Promise / Coroutine — Bug Reference
+
+> **When to load this reference**: when scanning code with async/await, Promise/Future/Task,
+> coroutines, event loops, or non-blocking I/O. Goroutines/channels live in concurrency-races.md.
+
+## Detection signals
+- JS/TS: `async function`, `\bawait\b`, `Promise\.(all|allSettled|race|any)`, `\.then\(`, `\.catch\(`,
+  `setTimeout`, `setInterval`, `new Promise\(`, `\.forEach\(.*async`, `async \(.*\) =>`, top-level `await`.
+- Python: `async def`, `\bawait\b`, `asyncio\.(gather|create_task|run|wait|shield)`, `trio\.open_nursery`,
+  `anyio\.`, `loop\.run_in_executor`, `time\.sleep` inside `async def`, `requests\.` inside `async def`.
+- Rust: `\.await`, `tokio::spawn`, `tokio::select!`, `async fn`, `async move`, `block_on`,
+  `futures::join!`, `try_join!`, `std::thread::sleep` inside async, `std::sync::Mutex` near `.await`.
+- Swift: `Task \{`, `await `, `actor `, `MainActor`, `withCheckedContinuation`, `Task.detached`.
+- C#: `async Task`, `async void`, `\.Result\b`, `\.Wait\(`, `\.GetAwaiter\(\)\.GetResult`, `ConfigureAwait`.
+- Kotlin: `suspend fun`, `launch \{`, `async \{`, `GlobalScope`, `runBlocking`, `withContext`,
+  `SupervisorJob`, `suspendCoroutine` (vs Cancellable).
+
+## Patterns
+
+### 1. Unhandled promise rejection / swallowed error
+- **Signature**: `.then(…)` chain with no `.catch`; `async` function called without `await` or `.catch`; rejected promise stored to variable and ignored.
+- **Why hard to find**: Node logs "UnhandledPromiseRejection" but does not crash by default in browsers / many runtimes. Failure path is the absence of a log.
+- **Where to look**: top-level handlers, event listeners that call async fns, library boundaries.
+- **Example**: `el.addEventListener('click', async () => doStuff())` — rejection is lost.
+- **Fix direction**: wrap with `try/catch` or attach `.catch`; install global `unhandledrejection` handler.
+- **Language variants**: Python `Task` exception lost unless `await`ed or accessed via `.exception()`; Rust `JoinHandle` errors silent until `.await`; C# `async void` throws to `SynchronizationContext` → process crash.
+
+### 2. Fire-and-forget task lost to the void
+- **Signature**: `asyncio.create_task(f())` / `tokio::spawn(f())` / `Task { … }` with no handle retained; no timeout, no cancellation source, no error surface.
+- **Why hard to find**: works fine until load; under pressure tasks accumulate, GC may collect Python tasks (warning only), Rust task leaks live forever.
+- **Where to look**: background workers, "send notification later" code, telemetry flushes.
+- **Example**: `asyncio.create_task(send_email(u))` inside a request handler.
+- **Fix direction**: hold reference (`self._tasks.add(t); t.add_done_callback(self._tasks.discard)`), bound queue, attach timeout + error log.
+
+### 3. Serial `await` in a loop instead of `Promise.all`
+- **Signature**: `for (const x of xs) { await f(x); }` when each call is independent.
+- **Why hard to find**: correct results, just N× slower; only shows up in latency metrics.
+- **Where to look**: hot paths, list-fetching code, migration scripts.
+- **Example**: `for (const id of ids) results.push(await fetch(id))`.
+- **Fix direction**: `Promise.all(ids.map(fetch))`; bound concurrency with `p-limit` / semaphore if N large.
+- **Language variants**: Python `asyncio.gather`, Rust `futures::join_all` / `buffer_unordered`, Kotlin `awaitAll`.
+
+### 4. `forEach` with async callback (promises ignored)
+- **Signature**: `arr.forEach(async x => await f(x))` — `forEach` ignores returned promises.
+- **Why hard to find**: outer function "completes" before any work finishes; downstream sees empty/partial state with no error.
+- **Where to look**: refactors from sync to async, `.forEach` over fetches.
+- **Fix direction**: use `for…of` with `await`, or `Promise.all(arr.map(f))`. ESLint `no-misleading-character-class` / `no-floating-promises` (TS).
+
+### 5. Missing `await` on an async call
+- **Signature**: `const x = fetchUser()` where `fetchUser` returns a Promise; `if (asyncCheck())` — truthy because Promise is truthy.
+- **Why hard to find**: silent in JS without TS-strict / `@typescript-eslint/no-floating-promises`; logs show `[object Promise]` or `<Future pending>`.
+- **Where to look**: conditionals, comparisons, JSON serialization, assignment.
+- **Fix direction**: enable `no-floating-promises`, type the return; Python `RuntimeWarning: coroutine was never awaited` — promote to error in CI.
+
+### 6. `Promise.all` rejecting where partial success was intended
+- **Signature**: `Promise.all([…])` over independent best-effort work.
+- **Why hard to find**: passes happy-path tests; under a single transient failure the whole batch is reported as failed.
+- **Where to look**: dashboard widgets, fan-out reads, notification dispatch.
+- **Fix direction**: `Promise.allSettled` + per-result handling. Python: `asyncio.gather(..., return_exceptions=True)`.
+
+### 7. Race in user-input handler (stale-overwriting-fresh)
+- **Signature**: handler kicks off `await fetch(query)`; later response sets state, but a newer keystroke has already completed.
+- **Why hard to find**: depends on network jitter; results may look right most of the time, then flicker stale.
+- **Where to look**: search-as-you-type, autocomplete, tab switchers, dependent dropdowns.
+- **Fix direction**: capture request id / `AbortController`; on resolve check `if (id !== currentId) return`; in React, cleanup in `useEffect`.
+
+### 8. Cancellation not propagated
+- **Signature**: long-running task with no `AbortSignal` / `CancellationToken` / cooperative `ensure_active()` / `select!` on cancel branch.
+- **Why hard to find**: caller moves on (closed tab, dropped future), worker keeps running, holding locks/DB conns.
+- **Where to look**: streaming endpoints, retry loops, polling intervals, Tokio MPSC `send` (NOT cancel-safe — message lost on drop).
+- **Fix direction**: thread `AbortSignal` through; Python: catch `asyncio.CancelledError` and re-raise after cleanup; Rust: prefer cancel-safe primitives or `tokio::select!` with explicit branches.
+
+### 9. Blocking work inside an async function
+- **Signature**: `time.sleep` / `requests.get` / sync `fs.readFileSync` / `std::thread::sleep` / heavy CPU loop inside `async def` / `async fn`.
+- **Why hard to find**: single-threaded event loop stalls; *all* concurrent tasks pause; symptoms look like network slowness.
+- **Where to look**: legacy lib calls in async handlers, JSON parse of huge payloads, bcrypt/argon2 calls, image processing.
+- **Fix direction**: Python `await asyncio.to_thread(f)` or `run_in_executor`; Node worker thread / `setImmediate`; Rust `tokio::task::spawn_blocking`; C# `Task.Run` for CPU.
+
+### 10. Holding a non-async lock across `await`
+- **Signature**: `threading.Lock` / `std::sync::Mutex` acquired, then `.await` while held.
+- **Why hard to find**: works under low contention; deadlocks/serializes under load; Rust will compile fine but break `Send` for tokio.
+- **Where to look**: caches with locks, singletons, connection pools.
+- **Fix direction**: use `asyncio.Lock` / `tokio::sync::Mutex` / Kotlin `Mutex`; or drop guard before `await`.
+
+### 11. C# blocking on async (`.Result` / `.Wait()`)
+- **Signature**: `someAsync().Result`, `.Wait()`, `.GetAwaiter().GetResult()` from a synchronization-context thread (UI / classic ASP.NET).
+- **Why hard to find**: classic deadlock — continuation needs the captured context, thread is blocked waiting.
+- **Where to look**: legacy callers of async libs, constructors, property getters.
+- **Fix direction**: async-all-the-way; library code uses `ConfigureAwait(false)`; never `async void` except event handlers.
+
+### 12. Swift actor reentrancy assumption
+- **Signature**: actor method reads state, `await`s something, then writes state assuming nothing changed.
+- **Why hard to find**: actor protects against data races, NOT against state mutation across suspension; tests that don't interleave miss it.
+- **Where to look**: balance/quota checks, cache fill ("check-then-load"), counters.
+- **Fix direction**: re-verify invariants after every `await`; pre-store and reuse the in-flight `Task` to dedupe; move state writes before `await`.
+
+### 13. Kotlin: `GlobalScope` / broken structured concurrency
+- **Signature**: `GlobalScope.launch`; manual `Job()` passed to child; `withContext(SupervisorJob())`; `try/catch` swallowing `CancellationException`.
+- **Why hard to find**: parent cancels, child keeps running; or cancellation no longer propagates; zombie coroutines on Android leak ViewModel scopes.
+- **Where to look**: Android ViewModels, repository singletons, retry loops that catch `Throwable`.
+- **Fix direction**: scope to lifecycle (`viewModelScope`); rethrow `CancellationException`; avoid `suspendCoroutine` — prefer `suspendCancellableCoroutine`.
+
+### 14. React/Vue/Svelte: state update after unmount
+- **Signature**: `useEffect(() => { fetch().then(setX) }, [])` — no cleanup; component unmounts before resolve.
+- **Why hard to find**: warning appears intermittently; in production silently leaks closures + may overwrite newer view state.
+- **Where to look**: data-loading effects, subscriptions, intervals.
+- **Fix direction**: `AbortController` in cleanup, or `let cancelled = false; return () => { cancelled = true }`; Svelte: use `onDestroy` / `$effect` cleanup; Vue: `onUnmounted`.
+
+### 15. `Promise.race` leaving losers running
+- **Signature**: `Promise.race([fetch(a), fetch(b)])` used as timeout; loser request keeps running, may resolve with side effects.
+- **Why hard to find**: works functionally; leaks sockets, file handles, may trigger duplicate side effects (writes, analytics).
+- **Where to look**: ad-hoc timeouts, "first available source" patterns.
+- **Fix direction**: pass `AbortSignal` to the losers (`AbortSignal.any`); prefer `Promise.any` for first-success semantics; cancel explicitly.
+
+### 16. `await` in a `finally` masking the original error
+- **Signature**: `try { … } finally { await cleanup() }` where `cleanup` throws.
+- **Why hard to find**: original error vanishes, replaced by cleanup error with unrelated stack.
+- **Where to look**: transaction rollbacks, file close, lock release.
+- **Fix direction**: catch inside `finally`, log+swallow cleanup error, let original propagate; or use `AggregateError`.

package/skills/bug-scan/references/concurrency-races.md

@@ -0,0 +1,148 @@
+# Concurrency & Race Conditions — Bug Reference
+
+> **When to load this reference**: when scanning code that uses threads, processes, goroutines,
+> async runtimes, shared mutable state, locks, channels, atomics, or any inter-thread/inter-task
+> communication.
+
+## Detection signals (where to start)
+- Synchronization primitives: `sync.Mutex`, `sync.RWMutex`, `Lock(`, `RLock`, `synchronized`, `Arc<Mutex`, `parking_lot`, `std::mutex`, `pthread_`, `NSLock`, `DispatchQueue`.
+- Task spawn / scheduling: `go func`, `tokio::spawn`, `thread::spawn`, `Thread(`, `threading.`, `multiprocessing.`, `asyncio.gather`, `asyncio.create_task`, `Promise.all`, `Promise.race`, `new Worker(`, `worker_threads`, `ExecutorService`, `CompletableFuture`.
+- Channels / queues: `make(chan`, `<-`, `select {`, `mpsc::`, `crossbeam`, `queue.Queue`, `BlockingQueue`.
+- Atomics / memory: `atomic.`, `AtomicInteger`, `AtomicReference`, `volatile`, `static mut`, `memory_order_`, `Ordering::Relaxed`, `unsafe`.
+- Shared state markers: `Send`, `Sync`, `@GuardedBy`, `@ThreadSafe`, `dispatch_once`, `__thread`, module-level mutables.
+- Hot files: caches, session managers, connection pools, rate limiters, schedulers, leader-election code, file-write helpers.
+
+## Patterns
+
+### 1. Check-then-act (TOCTOU)
+- **Signature**: `if !exists(x) { create(x) }`, `if cache.get(k) is None: cache[k] = ...`, `os.path.exists` then `open`, `SELECT ... then INSERT`.
+- **Why hard to find**: looks like ordinary control flow; only one window of vulnerability between two innocuous calls.
+- **Where to look**: file create helpers, "ensure_" / "get_or_create" / "find_or_init", auth/session bootstrap, idempotent endpoints, DB upserts written as two statements.
+- **Example**:
+  ```python
+  if user_id not in sessions:        # check
+      sessions[user_id] = Session()  # act — two threads can both pass the check
+  ```
+- **Fix direction**: collapse to one atomic op (`setdefault`, `LoadOrStore`, `putIfAbsent`, DB unique constraint + `ON CONFLICT`, `O_CREAT|O_EXCL`).
+- **Language variants**: Go → `sync.Map.LoadOrStore`; Java → `ConcurrentHashMap.computeIfAbsent`; Rust → `entry().or_insert_with`; Node → `fs.writeFile(... 'wx')`; SQL → unique index + upsert.
+
+### 2. Non-atomic read-modify-write on shared state
+- **Signature**: `counter++`, `total += x`, `list.append` on a module-level list (post-GIL Python), `map[k] = map[k] + 1`.
+- **Why hard to find**: source line looks atomic; bug surfaces only under contention or load tests.
+- **Where to look**: metrics counters, in-memory tallies, free-list updates, retry counters, ID generators.
+- **Example**:
+  ```go
+  var hits int
+  go func() { hits++ }()  // racy — read, increment, write are three ops
+  ```
+- **Fix direction**: use atomics (`atomic.AddInt64`, `AtomicInteger.incrementAndGet`, `fetch_add`), a lock, or message-pass through a channel/actor.
+- **Language variants**: Python 3.13 free-threading (PEP 703) removes the GIL safety net — `+=`, `dict[k]=...`, and `list.append` are no longer guaranteed atomic; audit shared module state.
+
+### 3. Double-checked locking / unsafe publication
+- **Signature**: `if instance is None: with lock: if instance is None: instance = X()`, lazy singletons.
+- **Why hard to find**: looks correct; partially-constructed object may be visible to a reader without happens-before.
+- **Where to look**: singleton getters, lazy caches, JNI/CGo glue, ObjC `+sharedInstance` rolled by hand.
+- **Example**:
+  ```java
+  if (cfg == null) { synchronized(L) { if (cfg == null) cfg = new Cfg(); } }  // cfg must be volatile
+  ```
+- **Fix direction**: declare the field `volatile` / `AtomicReference` (Java), use `OnceLock`/`OnceCell` (Rust), `sync.Once` (Go), `dispatch_once` (Swift/ObjC), module-import time init (Python).
+
+### 4. Memory visibility / missing happens-before
+- **Signature**: a writer thread sets a `done`/`ready` flag; reader spins on it without `volatile`, `atomic`, or a release/acquire pair.
+- **Why hard to find**: works on x86 due to strong ordering; fails on ARM/Apple Silicon or under aggressive JIT/compiler reordering.
+- **Where to look**: shutdown flags, "ready" signals, `while (!stopped)` loops, lock-free queues, custom spinlocks, `static mut` in Rust.
+- **Example**:
+  ```cpp
+  bool ready=false; int v=0;
+  // Thread A: v=42; ready=true;
+  // Thread B: while(!ready); use(v);   // both must be std::atomic with acquire/release
+  ```
+- **Fix direction**: use language-blessed atomics with appropriate ordering (`SeqCst` default, `Acquire`/`Release` if you know the model); in Java make fields `volatile` or use `j.u.c.atomic`; in Go use `atomic.LoadX`/`StoreX` or a channel.
+
+### 5. Lock ordering / cyclical deadlock
+- **Signature**: function F locks A then B; function G locks B then A.
+- **Why hard to find**: only deadlocks when both paths run concurrently; tests usually take one path at a time.
+- **Where to look**: any module with ≥2 mutexes; account/transfer code, parent↔child object graphs, bidirectional relationships, "swap" or "merge" operations.
+- **Example**:
+  ```go
+  // transfer(a,b): a.Lock(); b.Lock();   transfer(b,a) inverts — deadlock
+  ```
+- **Fix direction**: impose a global lock order (sort by address/ID), use a single coarser lock, use `try_lock` with back-off, or restructure to lock-free messaging.
+
+### 6. Lock held during callback / I/O / await
+- **Signature**: `lock.acquire(); callback(); lock.release()`, `mutex.lock(); http.get(...)`, holding a Tokio `MutexGuard` across `.await`.
+- **Why hard to find**: callback may reenter, block, or call back into the same module, producing deadlock or pathological latency.
+- **Where to look**: event emitters, observer/listener fan-out, plugin systems, async functions that take a `std::sync::Mutex`, Swift `@MainActor` work that calls completion handlers.
+- **Example**:
+  ```rust
+  let g = m.lock().unwrap();
+  client.get(url).await;  // holds lock across await — task starvation / deadlock
+  ```
+- **Fix direction**: copy needed data out, drop the guard before the slow op, or use `tokio::sync::Mutex` (still avoid long holds); never invoke unknown user code under a lock.
+
+### 7. Iteration during concurrent mutation
+- **Signature**: `for k,v in map.items():` while another thread writes; `range m` in Go without a lock; `for (Entry e : map.entrySet())` on a non-concurrent map.
+- **Why hard to find**: throws `ConcurrentModificationException` only sometimes; in Go produces silent corruption or panic.
+- **Where to look**: stats dumpers, snapshot endpoints, cache eviction sweeps, GC-like cleanup loops.
+- **Fix direction**: copy under lock then iterate the copy, use `ConcurrentHashMap`/`sync.Map`, or use snapshot iterators (`CopyOnWriteArrayList`).
+
+### 8. Wait/notify / condition-variable misuse
+- **Signature**: `if cond: wait()` (should be `while`), `notify_one()` when multiple waiters need wake, missing predicate check after wake.
+- **Why hard to find**: spurious wakeups are rare; missed signals only fire under specific interleavings.
+- **Where to look**: hand-rolled bounded queues, producer/consumer code, `Condvar`, `Object.wait/notify`, `threading.Condition`, `pthread_cond_t`.
+- **Fix direction**: always `while (!predicate) wait()`, prefer `notify_all` when in doubt, or replace with a channel / `BlockingQueue` / semaphore.
+
+### 9. Atomicity violation across multiple atomic ops
+- **Signature**: `if map.contains(k) { map.get(k) }`, `atomic.Load` followed by `atomic.Store`, `ConcurrentHashMap.get` then `put`.
+- **Why hard to find**: each individual op is atomic, so static analysis and review give a false sense of safety.
+- **Where to look**: "get or update" code, balance/inventory math on atomics, two-step state transitions.
+- **Fix direction**: use a CAS loop (`compareAndSet`, `compare_exchange`), `compute`/`merge` style atomic combinators, or take a lock spanning the full sequence.
+
+### 10. Cancellation / interruption leaving partial state
+- **Signature**: `try: work() except CancelledError: ...` without rollback; `ctx.Done()` mid-write; Go `context` cancel during multi-step DB write; Swift `Task.cancel`.
+- **Why hard to find**: only fires when a timeout/cancel races with a critical section.
+- **Where to look**: HTTP handlers with deadlines, batch jobs, transactional flows that mix DB + cache + external API, `defer`/`finally` blocks that themselves do I/O.
+- **Fix direction**: make critical sections atomic (single tx), guard cleanup with `shield`/`uninterruptible`, persist intent before doing work so cancel-recovery is well-defined.
+
+### 11. Channel deadlock / goroutine leak via blocked send/receive
+- **Signature**: send to unbuffered channel with no receiver; receive from a channel that is never closed; `select` whose only ready case is `<-ctx.Done()` that never fires.
+- **Why hard to find**: goroutines leak silently; only visible via pprof, RSS growth, or `runtime.NumGoroutine`.
+- **Where to look**: fan-out workers without `WaitGroup`, request-scoped goroutines without `context`, "fire and forget" launches, Rust `tokio::spawn` whose `JoinHandle` is dropped.
+- **Fix direction**: always pair sends with bounded receivers, close channels from the sender side, propagate `context.Context`, and use `errgroup` / `JoinSet` for structured concurrency.
+
+### 12. `select` with `default` busy-loop / starvation
+- **Signature**: Go `select { case x:=<-ch: ... ; default: }` inside a `for`; Rust `try_recv` polled in a tight loop; JS `while(!done)` with `setImmediate`.
+- **Why hard to find**: code "works" but pins a CPU; starves siblings on the same runtime.
+- **Where to look**: hand-rolled pollers, retry loops, scheduler shims, custom event loops.
+- **Fix direction**: drop `default` and block on the channel, add a `time.After` / `tokio::time::sleep`, or restructure as event-driven.
+
+### 13. Caching: stampede / thundering herd / double-fill
+- **Signature**: many concurrent misses for the same key each trigger a backend fetch; `if cache.miss: load_from_db()` with no in-flight coalescing.
+- **Why hard to find**: behaves fine under low load; collapses the backing store under traffic spikes or cold start.
+- **Where to look**: memoization decorators, HTTP middleware caches, CDN-fronted endpoints, session/JWT lookups.
+- **Fix direction**: single-flight / request coalescing (`singleflight.Group`, `asyncio` future cache, Caffeine `AsyncLoadingCache`), jittered TTLs, lock-on-key, probabilistic early expiration.
+
+### 14. Send/Sync violations and !Send across await (Rust)
+- **Signature**: `Rc<...>` shared across threads; `RefCell` behind `Arc`; `MutexGuard`, `*mut T`, or non-`Send` future held across `.await` on a multi-threaded runtime.
+- **Why hard to find**: compiler usually catches `!Send`, but trait-object boundaries (`Box<dyn Future>`), conditional compilation, and `unsafe impl Send` can hide it.
+- **Where to look**: `unsafe impl Send for ...`, `tokio::spawn` of large async blocks, FFI handles, `Pin<Box<dyn Future>>` returned from traits, async-trait macros.
+- **Fix direction**: replace `Rc/RefCell` with `Arc/Mutex` (or `tokio::sync::Mutex` if held across await), restrict to `LocalSet` / single-thread runtime, narrow guard scope, audit every `unsafe impl Send`.
+
+### 15. Reentrancy and re-entering the same lock
+- **Signature**: a method takes a lock then calls a virtual/overridden method that takes the same lock; recursive locking on non-reentrant mutex (`std::sync::Mutex`, `pthread_mutex_t` default).
+- **Why hard to find**: works if the second call ends up on a different instance; deadlocks only on certain object graphs.
+- **Where to look**: framework templates, ORM lifecycle hooks, ObjC KVO observers, signals/slots, `Drop` impls that lock.
+- **Fix direction**: split critical sections so callbacks run outside; use a re-entrant mutex only as a stopgap; restructure ownership.
+
+### 16. Background task lifetime escapes parent scope
+- **Signature**: spawning a task that captures `self` / request-scoped state then outlives it; `setTimeout(fn, 0)` in a handler that finishes; `tokio::spawn` not joined.
+- **Why hard to find**: works in tests because the process stays alive; production crashes are use-after-free or stale-data writes.
+- **Where to look**: request handlers, React `useEffect` async work, Swift `Task { ... }` not stored, fire-and-forget logging/metrics flushes.
+- **Fix direction**: structured concurrency (`errgroup`, `TaskGroup`, `JoinSet`, `AbortController`), explicit join/cancel on parent exit, tie task lifetime to a `context.Context`.
+
+### 17. Lost update on optimistic concurrency without version check
+- **Signature**: `row = SELECT ...; row.x += 1; UPDATE SET x = row.x WHERE id = ?` with no `version`/`updated_at` predicate.
+- **Why hard to find**: classic last-writer-wins; only manifests as silent data drift.
+- **Where to look**: counters, inventory, balances, "edit settings" endpoints, ETL merge jobs.
+- **Fix direction**: add a `version` column + `WHERE version = ?` and retry on 0 rows; or `UPDATE ... SET x = x + 1`; or `SELECT ... FOR UPDATE`.