manual_slop/conductor/tracks/gui_decoupling_controller_20260302/spec.md

Track Specification: GUI Decoupling & Controller Architecture (gui_decoupling_controller_20260302)

Overview

gui_2.py currently operates as a Monolithic God Object (3,500+ lines). It violates the Data-Oriented Design heuristic by owning complex business logic, orchestrator hooks, and markdown file building. This track extracts the core state machine and lifecycle into a headless app_controller.py, turning the GUI into a pure immediate-mode view.

Architectural Constraints: The "Immediate Mode View" Contract

• No Business Logic in View: gui_2.py MUST NOT perform file I/O, AI API calls, or subprocess management directly.
• State Ownership: app_controller.py (or equivalent) owns the "Source of Truth" state.
• Event-Driven Mutations: The GUI must mutate state exclusively by dispatching events or calling controller methods, never by directly manipulating backend objects in the render loop.

Functional Requirements

• Controller Extraction: Create app_controller.py to handle all non-rendering logic.
• State Migration: Move state variables (_tool_log, _comms_log, active_tickets, etc.) out of App.__init__ into the controller.
• Logic Migration: Move background threads, file reading/writing (_flush_to_project), and AI orchestrator invocations to the controller.
• View Refactoring: Refactor gui_2.py to accept the controller as a dependency and merely render its current state.

Acceptance Criteria

• app_controller.py exists and owns the application state.
• gui_2.py has been reduced in size and complexity (no file I/O or AI calls).
• All existing features (chat, tools, tracks) function identically.
• The full test suite runs and passes against the new decoupled architecture.