review-static-coverage

---
name: review-static-coverage-e6dd8f9e6f85
description: Find gaps in static analysis where new checks could prevent classes of bugs
user-invocable: true
disable-model-invocation: true
---
Enter planning mode. Deep-review production code patterns to find gaps where static analysis checks (`tests/check_*.ps1`) could prevent whole classes of bugs. Use maximum parallelism — spawn explore agents for independent areas.

**Scope**: Static analysis pre-gate checks only. NOT AHK test coverage (see `review-test-coverage`), NOT query tools, NOT check speed (see `review-static-speed`).

## The Bar for a New Check

A proposed check must clear ALL of these:

1. **Prevents a class, not an instance** — catches a pattern that can recur, not a one-off bug
2. **Statically detectable** — regex/parsing on source files is sufficient. If it needs runtime info, skip it.
3. **Low false positive rate** — a check that fires on 50 lines but only 2 are real problems creates noise that erodes trust in the pre-gate
4. **Worth the maintenance** — a check that fires once a year isn't worth maintaining. Focus on patterns that are easy to introduce accidentally during normal development.

## Current Check Inventory

**Standalone checks** (complex enough to warrant their own process):
- `check_warn.ps1` — warn directive enforcement

**Batch checks** (grouped to share file cache and reduce PowerShell overhead):
- `check_batch_simple.ps1` — lightweight pattern checks (switch globals, IPC constants, DllCall types, IsSet patterns, cfg properties, duplicate functions, dead code detection, config registry integrity, etc.)
- `check_batch_functions.ps1` — function-level checks
- `check_batch_directives.ps1` — directive-level checks
- `check_batch_guards.ps1` — guard pattern checks
- `check_batch_patterns.ps1` — code pattern checks
- `check_batch_tests.ps1` — test file checks

**Enforcement tools** (in `tools/`, run as pre-gate checks):
- `query_global_ownership.ps1 -Check` — ownership manifest enforcement
- `query_function_visibility.ps1 -Check` — private function boundary enforcement

## Where to Look for Gaps

Explore the production code for patterns that are:
- **Error-prone by nature** — easy to get wrong during normal development
- **Silent when broken** — no runtime error, just wrong behavior
- **Repetitive** — the same pattern appears in many files, so a check amortizes well

Categories to investigate:
- **Resource management** — GDI+ create without delete, DllCall handle leaks, unclosed file handles
- **Concurrency** — `Critical "On"` without matching `Critical "Off"` on all exit paths
- **AHK v2 gotchas** — patterns that are valid syntax but wrong semantics (e.g., v1 patterns that compile but misbehave in v2)
- **API contracts** — functions called with wrong argument counts or types, especially DllCall
- **Data flow** — globals read before initialization, config keys used but not in registry

## Placement Guidance

When proposing a new check, specify where it fits:

- **Add to existing batch** — if the check is short (<50 lines of logic), benefits from the shared file cache, and fits the batch's theme. This is the default for simple pattern checks.
- **New standalone** — if the check is complex (>100 lines), needs its own specialized parsing, or has significantly different performance characteristics than batch siblings.
- **New batch** — only if there are 3+ related sub-checks that share a specialized cache or parsing step not needed by existing batches.

## Validation

For each proposed check:

1. **Cite the pattern**: "I found this pattern in `file.ahk` lines X–Y" — show real code that the check would flag (or correctly skip).
2. **False positive analysis**: Run the proposed regex/logic mentally against the codebase. How many hits? How many are true positives? A >80% true positive rate is the minimum.
3. **Counter-argument**: "What would make this check unnecessary?" — Is the pattern already prevented by coding conventions? Is it rare enough that code review catches it?
4. **Observed vs inferred**: Did you find actual instances of this bug pattern, or infer it could happen from code structure?

## Plan Format

| Pattern | Detection Method | False Positive Est. | Placement | Justification |
|---------|-----------------|--------------------|-----------|--------------|
| Missing `Critical "Off"` on early return | Regex: `Critical "On"` then `return` without intervening `Critical "Off"` | Low — pattern is structural | `check_batch_guards.ps1` | Easy to miss during edits, silent corruption |

For each proposed check, include:
- A sketch of the detection logic (regex pattern or parsing approach)
- Example true positive and true negative from actual codebase
- Which existing batch it belongs in (or why standalone)

Order by value: high-frequency silent bugs first, rare edge cases last.

Ignore any existing plans — create a fresh one.