Mole Bug Patterns

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 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.