manual_slop/conductor/tracks/gui_decoupling_controller_20260302/plan.md

Implementation Plan: GUI Decoupling & Controller Architecture (gui_decoupling_controller_20260302)

Phase 1: Controller Skeleton & State Migration

• Task: Initialize MMA Environment activate_skill mma-orchestrator
• Task: Create app_controller.py Skeleton
  • WHERE: app_controller.py (New file)
  • WHAT: Create the AppController class. Initialize basic state structures (logs, metrics, flags).
  • HOW: Standard class definition.
  • SAFETY: Do not break existing GUI yet.
• Task: Migrate Data State from GUI
  • WHERE: gui_2.py:__init__ and app_controller.py
  • WHAT: Move variables like _comms_log, _tool_log, mma_streams, active_tickets to the controller.
  • HOW: Update GUI to reference self.controller.mma_streams instead of self.mma_streams.
  • SAFETY: Search and replace carefully; use py_check_syntax.
• Task: Conductor - User Manual Verification 'Phase 1: State Migration' (Protocol in workflow.md)

Phase 2: Logic & Background Thread Migration

• Task: Extract Background Threads & Event Queue
  • WHERE: gui_2.py (e.g., _init_ai_and_hooks, _process_event_queue)
  • WHAT: Move the AsyncEventQueue, asyncio worker thread, and HookServer initialization to the controller.
  • HOW: The GUI should just call self.controller.start_services() and read the _pending_gui_tasks queue.
  • SAFETY: Thread lifecycle management is critical. Ensure shutdown hooks are migrated.
• Task: Extract I/O and AI Methods
  • WHERE: gui_2.py (_cb_plan_epic, _flush_to_project, _cb_create_track)
  • WHAT: Move business logic methods to the controller.
  • HOW: GUI callbacks simply become lambda: self.controller.plan_epic(input).
  • SAFETY: Verify Hook API endpoints still work.
• Task: Conductor - User Manual Verification 'Phase 2: Logic Migration' (Protocol in workflow.md)

Phase 3: Test Suite Refactoring

• Task: Update conftest.py Fixtures
  • WHERE: tests/conftest.py
  • WHAT: Update app_instance fixture to mock/initialize the AppController instead of just App.
  • HOW: Adjust patch targets to hit app_controller.py where appropriate.
  • SAFETY: Run subset of tests continuously to fix import breaks.
• Task: Resolve Broken GUI Tests
  • WHERE: tests/test_gui_*.py
  • WHAT: Update test assertions that look for state on app_instance to look at app_instance.controller.
  • HOW: Surgical string replacements.
  • SAFETY: Ensure no false-positives.
• Task: Conductor - User Manual Verification 'Phase 3: Test Suite Refactoring' (Protocol in workflow.md)

Phase 4: Final Validation

• Task: Full Suite Validation & Warning Cleanup
  • WHERE: Project root
  • WHAT: uv run pytest
  • HOW: Ensure 100% pass rate.
  • SAFETY: Watch out for lingering thread closure issues.
• Task: Conductor - User Manual Verification 'Phase 4: Final Validation' (Protocol in workflow.md)