# Track Specification: Hot Reload Python Codebase

## Overview

Implement selective, state-preserving hot-reload for the Manual Slop `./src` Python codebase. This follows the "data in stable memory, code in reloadable modules" pattern. The initial target is `src/gui_2.py`, with a delegation pattern that decouples render logic from the stable `App` class.

## Current State Audit (as of 3414625)

### Already Implemented (DO NOT re-implement)

- **HotModule dataclass** (`src/hot_reloader.py:8-12`) — Fields: `name`, `file_path`, `state_keys`, `delegation_targets`
- **HotReloader core** (`src/hot_reloader.py:14-67`) — Registry (`HOT_MODULES`), `register()`, `capture_state()`, `restore_state()`, `reload()`, `reload_all()`
- **Delegation pattern design** (`docs/superpowers/specs/2026-05-14-hot-reloader-design.md`) — Full architecture documented

### Gaps to Fill (This Track's Scope)

1. **No GUI trigger** — No `Ctrl+Alt+R` keyboard handler in `App.run()` (gui_2.py:268-332) and no "Hot Reload" button in MMA dashboard (gui_2.py:4664-4695)
2. **No src.gui_2 registration** — `HotReloader.HOT_MODULES` is empty; no module is registered
3. **No delegation wrappers** — All `_render_xxx` methods are bound to `App` class; must be refactored to module-level functions with thin App wrappers
4. **No visual error tint** — No overlay on `HotReloader.is_error_state == True`
5. **No state_keys inventory** — The full list of App attrs to preserve hasn't been cataloged

## Goals

- Manual trigger via `Ctrl+Alt+R` keyboard shortcut and GUI "Hot Reload" button
- State preservation across reloads using `copy.deepcopy` capture/restore
- Silent fallback on failure with visual error tint overlay
- Delegation pattern: module-level render functions, thin App delegation wrappers
- Extensible registry for future hot modules (ai_client.py, etc.)

## Functional Requirements

1. `HotReloader.register()` registers modules with state_keys and delegation_targets
2. `Ctrl+Alt+R` captured in main loop triggers `HotReloader.reload_all(app)`
3. MMA dashboard contains a "Hot Reload" button calling same
4. Failed reload renders red-tint overlay on viewport and restores pre-reload state
5. `src.gui_2` registered as first hot module with complete state_keys and delegation_targets list
6. All `App._render_xxx` methods refactored to module-level `render_xxx(app)` functions

## Non-Functional Requirements

- <1ms overhead per frame when not reloading
- Error tint uses ImGui draw list (no GPU shaders)
- State capture uses `copy.deepcopy` for isolation
- All errors logged to `HotReloader.last_error` with full traceback

## Architecture Reference

- `docs/superpowers/specs/2026-05-14-hot-reloader-design.md` — Full architecture
- `docs/guide_architecture.md` — Thread domains, event system
- `src/hot_reloader.py` — Existing core implementation
- `src/gui_2.py:App.run` (lines 268-332) — Main loop, keyboard capture target
- `src/gui_2.py:_render_mma_dashboard` (lines 4664-4695) — Button placement

## Out of Scope

- Automatic file watching (manual trigger only)
- Hot-reloading of C extensions or native code
- Cross-platform reload support (Windows focus)
- Adding ai_client.py as hot module (future extensibility)