manual_slop/conductor/tracks/hot_reload_python_20260510/spec.md

Track Specification: Hot Reload Python Codebase

Overview

Add file system watching capability to automatically reload/restart the Manual Slop application when source files are modified during development. This eliminates the manual stop/restart cycle when iterating on the codebase.

Current State Audit (as of 4940913e)

Already Implemented (DO NOT re-implement)

• gui_2.py: Main application entry with App class, run() method, and imgui-bundle integration
• src/app_controller.py: Application controller with state management
• pyproject.toml: Project configuration with [project.scripts] for manual-slop entry point
• scripts/: Helper scripts for various dev tasks

Gaps to Fill (This Track's Scope)

1. No hot reload mechanism: No watchdog/inotify-based file watching to trigger app restart
2. Manual restarts required: Developers must stop and restart the app after every code change
3. No dev iteration helper: No integration with existing dev tooling (watchgod, hupper, or py --watch)

Goals

1. Watch source files (*.py) in src/, scripts/, and root directories
2. Automatically restart the running application when Python files change
3. Provide a CLI flag or environment variable to enable/disable hot reload mode
4. Debounce rapid file changes to prevent restart storms
5. Preserve application state where possible during reload

Functional Requirements

• File system watcher using watchgod (lightweight, pure Python, no C extensions)
• Watch patterns: src/**/*.py, scripts/**/*.py, *.py in project root
• Debounce window: 300ms to coalesce rapid file changes (e.g., save-all)
• CLI flag: --watch or MANUAL_SLOP_WATCH=1 environment variable
• Graceful shutdown before restart, preserving logs
• Restart via subprocess with same arguments

Non-Functional Requirements

• Must not block the main thread
• Memory overhead < 5MB
• Restart latency < 1 second after file change settles
• Compatible with Windows (PowerShell environment)

Architecture Reference

• docs/guide_architecture.md#threading-model
• pyproject.toml#project.scripts

Out of Scope

• Hot reload within the same process (AST-level code swapping)
• Watching non-Python files
• Cross-machine or container-based file watching
• IDE integration (VSCode, etc.)