manual_slop/conductor/archive/hot_reload_python_20260516/spec.md

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)