cwilliams5/review-static-coverage

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.