review-constants-to-configs

Enter planning mode. Inventory all hardcoded constants and evaluate which should be promoted to the config registry. Use parallelism where possible.

Tools

Command	Purpose
query_config.ps1	Browse config registry — sections, groups, existing entries
query_config.ps1 -Usage <key>	Which files consume a config value

Step 1 — Inventory constants NOT in the config registry

Scan all src/ files (excluding src/lib/) for hardcoded constants:

• Named constants at file scope (e.g., TIMEOUT_MS := 5000)
• Magic numbers in function bodies that control behavior (timeouts, thresholds, sizes, intervals)
• Hardcoded pixel values, colors, dimensions
• Timer intervals passed to SetTimer
• Sleep durations that control timing behavior
• Buffer sizes, retry counts, polling intervals

Cross-reference each against query_config.ps1 to confirm it's not already in the registry.

Exclude from inventory:

• Windows API constants (WM_ messages, GDI flags, DllCall numeric args) — these are protocol, not tunables
• Array indices, loop bounds tied to data structure size
• Boolean flags (true/false)
• Values in src/lib/ (third-party)
• Constants that are already config-driven via cfg.*

Step 2 — Evaluate which should become config entries

Not every constant belongs in config. The bar is: would an end user reasonably want to change this?

Promote to config when:

• The value controls user-visible behavior (timing, appearance, thresholds)
• Different users/environments may need different values (e.g., slow machines need longer timeouts)
• The value was already asked about in issues or feedback
• Changing it requires editing source code today

Keep as hardcoded constant when:

• It's an implementation detail users shouldn't need to think about (internal buffer sizes, protocol constants)
• Changing it would likely break things (carefully tuned race condition windows, critical section timeouts)
• It's tightly coupled to other values that would also need to change (better to keep them together in code)
• It only makes sense in the context of the surrounding code (not meaningful as a standalone setting)

Keep as hardcoded but name it when:

• It's a magic number in a function body that should be a named constant for readability, but doesn't need to be user-configurable

Config Registry Requirements

For any constant promoted to config, specify:

• Section and Group — where it fits in the existing registry organization
• Key name — following existing naming conventions (check query_config.ps1 for patterns)
• Type — int, float, bool, string, color
• Default — the current hardcoded value
• Min/max — reasonable bounds to prevent broken configs
• Description — one-line explanation for the config editor

Use query_config.ps1 to understand the existing section/group structure before proposing new entries. New entries should fit naturally into existing sections where possible.

Plan Format

Section 1 — Full inventory (all constants found, categorized):

File	Lines	Constant	Current Value	Category
gui_paint.ahk	42	BORDER_WIDTH	2	Appearance
gui_state.ahk	15	GRACE_PERIOD_MS	150	Timing

Section 2 — Recommended promotions (constants → config entries):

Constant	File	Value	Config Key	Section	Type	Min/Max	Why Configurable
GRACE_PERIOD_MS	gui_state.ahk:15	150	GracePeriodMs	[Behavior]	int	50/500	Users report quick Alt-Tab too sensitive

Section 3 — Recommended naming only (magic number → named constant, not config):

File	Lines	Current	Proposed Name	Why Not Config
foo.ahk	88	Sleep(50)	POLL_INTERVAL_MS := 50	Internal polling detail

Order promotions by user impact: settings users are likely to want first.

Ignore any existing plans — create a fresh one.