Mole bug patterns

Generic review belongs to Waza check; root-cause investigation of a live failure belongs to hunt.

Route before loading details

Choose only the reference families touched by the evidence. A whole-project audit should classify surfaces first instead of loading every incident narrative.

#	Recurring shape	First probe	Read
1	Deletion candidate built from a weak name signal	Inspect name, bundle-id, fallback globs, and failed-owner shortcuts	Deletion evidence and final sink
2	Existence or idleness decided by one probe	Enumerate every legitimate location and unknown outcome	Deletion evidence and final sink
3	Guard present on only one branch	Diff dry-run, real, direct, fallback, and final-sink paths	Deletion evidence and final sink
4	Unbounded external command	Count producer, consumer, inner-loop, and action bounds	Bounds, Shell, TTY, and parsing
5	Bash 3.2, errexit, or pipefail trap	Check empty arrays, `fn
6	TTY, stdin, or process-group theft	Inspect background workers and commands that may prompt	Bounds, Shell, TTY, and parsing
7	System output parsed as a stable API	Force locale, validate shape, and join on identifiers not headings	Bounds, Shell, TTY, and parsing
8	Persisted derived data outlives its algorithm	Trace schema, TTL, evidence fingerprint, and mutations	State, accounting, and progress
9	Two paths compute one number differently	Find every producer and choose one definition	State, accounting, and progress
10	Slow work looks frozen	Find operations over roughly one second outside feedback	State, accounting, and progress
11	Regression test cannot fail	Prove positive control and pre-fix red state	Test validity and refusal diagnostics
12	Gate cannot explain why it refused	Map each reason to one cause and a next action that fails on the broken state	Test validity and refusal diagnostics
13	Mutation target is also accepted as a discovery container	Compare the recursive scan-root namespace with every purge target basename	Deletion evidence and final sink
14	Owner metadata is treated as a complete, atomic inventory	Identify who writes it, whether absence is authoritative, and what locks mutation	Deletion evidence and final sink
15	Cancellation stops one helper but later work continues	Classify each 124 as skip, section budget, or sticky cancel before tracing callers	Bounds, Shell, TTY, and parsing
16	Async or cached data has no generation or freshness contract	Bind results to a request epoch and keep each sample's time, stale, and completeness fields together	State, accounting, and progress
17	Publication gate trusts ambiguous or pre-existing state	Require exact source/tag equality, one generated target, and an expected-absence ref lease	Test validity and refusal diagnostics
18	A sandbox well-known path is treated as app-private leftovers	Resolve Data/Downloads, Desktop, Pictures, Music, and Movies physically against $HOME	Deletion evidence and final sink

AGENTS.md and the path-scoped .claude/rules/ files keep each rule stated fully enough to obey plus its test anchor; the incident story lives in these references or in release-flow, and the rule bullet points to the section that holds it. Moving a story here is a merge, never the deletion of a rule that still constrains behavior.

Trace the complete mutation lifecycle

For cleanup, purge, optimize, analyze deletion, or uninstall work, review the complete chain rather than the reported branch:

discover or plan
  -> cheap irreversible filters
  -> owner and open-handle probes
  -> size or metadata work
  -> final owner re-probe
  -> parent and target identity rebind
  -> deletion or Trash sink
  -> accounting, cancellation, and user output

At every transition, answer:

• Does live or unknown state fail closed?
• Are timeouts classified by probe, sizing, removal, or section scope, with unknown evidence refusing deletion and cancellation stopping later mutation?
• Are probe and sink bound to the same physical parent and target?
• Do dry-run and real mode start from the same eligible plan without reusing stale authorization?
• Are cheap missing, protected, whitelisted, and compiled-model filters ahead of recursive probes?
• Does one cumulative deadline cover the dynamic scan scope, with checkpoints in nested loops?
• Do refused, filtered, timed-out, or failed items stay out of cleaned counts and reclaimed bytes?
• Can large candidates avoid per-item size work without making the reported total false?

Do not trade final-sink rebinding or fail-closed owner checks for speed. Optimize absent targets, duplicated discovery probes, report-only work, and wrong-scope scans first.

Working contract

• Before proposing a remedy, apply the Product Decision Filter in AGENTS.md: a new flag, environment variable, or visible retry message is a product change, even when the underlying fix is a safety improvement. Use the existing state/accounting reference when deciding what belongs in the normal summary.
• A sandbox well-known directory is user data until physical resolution proves otherwise. Data/Downloads is usually ~/Downloads under another name.
• A refusal next step that succeeds on the broken state is not a next step. Do not relax the gate to make the message nicer.
• Sweep siblings by call-site shape, not filename or helper name. Report checked N / defective M / not applicable K.
• A recurring fix ships with a regression or source invariant that fails against the pre-fix code.
• Treat tests as production consumers only after proving the production helper ran. Negative assertions require a positive trace.
• A cancellation regression makes the next candidate otherwise eligible, then proves its probe and sink never run. Making every candidate fail for the same reason is a false sticky-cancellation test.
• Absence-sensitive tests use an isolated HOME or fixture root; a shared setup_file home is not isolation.
• Reproduce CI through MOLE_TEST_NO_AUTH=1 ./scripts/test.sh when possible. If invoking Bats directly with jobs, preserve --no-parallelize-within-files; files share state and raw bats --jobs 6 file.bats changes semantics.
• Treat specialist or AI reports as leads. Read the implementation, callers, fallback branches, and final sink yourself.

Verification bar

Use the hotspot commands in the matching .claude/rules/ file (routed from AGENTS.md); do not guess a narrower verifier. A typical Shell safety change finishes with:

./scripts/check.sh --format
MOLE_TEST_NO_AUTH=1 bats tests/<area>.bats
MOLE_TEST_NO_AUTH=1 ./scripts/test.sh
go test ./...
MOLE_TEST_NO_AUTH=1 MOLE_DRY_RUN=1 ./mole clean --dry-run

Never infer a production defect from a function name, comment, string, fixture, or _test.go match. Confirm the live call path and verify red-green before reporting the class fixed.