docs(conductor): Complete Phase 1 of AppController curation (Audit & Guidelines)

conductor/code_styleguides/python.md

@@ -180,4 +180,12 @@ To minimize token usage and enhance visual scanning for human reviewers, heavily
 
 ## 14. Logical Region Blocks
 
-For extremely large files that violate the "Anti-OOP" rule by necessity (e.g., `App` class holding global UI state), use `#region: Section Name` and `#endregion: Section Name` tags to strictly organize methods and state properties. This establishes a predictable structure that MCP tools and agents can leverage for contextual masking.
+For extremely large files that violate the "Anti-OOP" rule by necessity (e.g., `App` class holding global UI state), use `#region: Section Name` and `#endregion: Section Name` tags (or `# --- Section Name ---` for visual grouping) to strictly organize methods and state properties. This establishes a predictable structure that MCP tools and agents can leverage for contextual masking.
+
+## 15. Modular Controller Pattern
+
+To prevent "God Object" bloat in core controllers (like `AppController`):
+- **Extract Logic:** Move all state-independent or purely utility logic to module-level functions.
+- **Dependency Injection:** Module-level functions that require class state should accept the instance as their first argument (e.g., `def my_extracted_logic(controller: AppController, ...)`).
+- **Handler Maps:** Replace massive `if/elif` blocks (like those in event dispatchers) with dictionaries mapping keys to module-level handler functions.
+- **Inner Class Extraction:** Never define nested classes or functions within methods. Move them to the module level.

conductor/product-guidelines.md

@@ -24,6 +24,7 @@
 - **Strict State Management:** There must be a rigorous separation between the Main GUI rendering thread and daemon execution threads. The UI should *never* hang during AI communication or script execution. Use lock-protected queues and events for synchronization.
 - **Comprehensive Logging:** Aggressively log all actions, API payloads, tool calls, and executed scripts. Maintain timestamped JSON-L and markdown logs to ensure total transparency and debuggability.
 - **Mandatory ImGui Verification:** All changes to the GUI (`gui_2.py`) MUST be verified using the custom AST linter (`scripts/check_imgui_scopes.py`) to ensure all ImGui scopes (begin/end, push/pop) are properly matched. Developers should prioritize the use of `src/imgui_scopes.py` context managers (`imscope`) over manual push/pop calls.
+- **Modular Controller Pattern:** To prevent "God Object" bloat in core controllers (like `AppController`), all state-independent or utility logic must be moved to module-level functions. Functions requiring class state should accept the instance as an explicit dependency (`def logic(controller: AppController, ...)`). Massive `if/elif` dispatch blocks must be refactored into handler maps (dictionaries) of module-level functions.
 - **Dependency Minimalism:** Limit external dependencies where possible. For instance, prefer standard library modules (like `urllib` and `html.parser` for web tools) over heavy third-party packages.
 
 ## Phase 5: Heavy Curation & Structural Integrity (MANDATORY)

conductor/tracks.md

@@ -113,6 +113,10 @@ This file tracks all major tracks for the project. Each track has its own detail
 9. [x] **Track: Structural Dependency Mapping (SDM) Docstrings**
 *Link: [./tracks/sdm_docstrings_20260509/](./tracks/sdm_docstrings_20260509/)*
 
+10. [~] **Track: AppController Curation & Structural Alignment**
+    *Link: [./tracks/app_controller_curation_20260513/](./tracks/app_controller_curation_20260513/)*
+    *Goal: Curate src/app_controller.py to match gui_2.py organization and enforce Python style conventions.*
+
 ---
 
 ## Remaining Backlog (Phases 3 & 4)

conductor/tracks/app_controller_curation_20260513/extraction_list.md

@@ -0,0 +1,64 @@
+# AppController Extraction List
+
+## 1. Move to `src/models.py`
+- `GenerateRequest` (BaseModel)
+- `ConfirmRequest` (BaseModel)
+
+## 2. Extraction to Module Level (Functions taking `controller: AppController`)
+
+### From `create_api`
+- `get_api_key`
+- `health`
+- `get_gui_state`
+- `get_mma_status`
+- `post_gui`
+- `get_api_session`
+- `post_api_session`
+- `get_api_project`
+- `get_performance`
+- `get_diagnostics`
+- `status`
+- `generate`
+- `stream`
+- `pending_actions`
+- `confirm_action`
+- `list_sessions`
+- `get_session`
+- `delete_session`
+- `get_context`
+- `token_stats`
+
+### From `_process_pending_gui_tasks` (Handlers)
+- `_handle_refresh_api_metrics`
+- `_handle_set_ai_status`
+- `_handle_set_mma_status`
+- `_handle_ai_response`
+- `_handle_mma_state_update`
+- `_handle_set_value`
+- `_handle_click`
+- `_handle_drag`
+- `_handle_right_click`
+- `_handle_select_list_item`
+- `_handle_ask_dialog`
+- `_handle_custom_callback`
+- `_handle_mma_step_approval`
+- `_handle_mma_spawn_approval`
+- `_handle_ticket_started`
+- `_handle_ticket_completed`
+- `_handle_bead_updated`
+
+### From `cb_load_prior_log`
+- `_resolve_log_ref`
+
+## 3. Extraction to Module Level (Independent Utilities)
+- `parse_symbols` (Already module level)
+- `get_symbol_definition` (Already module level)
+- `_extract_tool_name`
+- `_offload_entry_payload`
+
+## 4. Classes to Top-Level
+- `ConfirmDialog`
+- `MMAApprovalDialog`
+- `MMASpawnApprovalDialog`
+- `AutoStepDialog` (From `_process_pending_gui_tasks`)
+- `AutoSpawnDialog` (From `_process_pending_gui_tasks`)

conductor/tracks/app_controller_curation_20260513/metadata.json

@@ -0,0 +1,7 @@
+{
+  "track_id": "app_controller_curation_20260513",
+  "title": "AppController Curation & Structural Alignment",
+  "status": "in_progress",
+  "initialized": "2026-05-13",
+  "goal": "Curate src/app_controller.py to match gui_2.py organization and enforce Python style conventions."
+}

conductor/tracks/app_controller_curation_20260513/plan.md

@@ -0,0 +1,19 @@
+# Implementation Plan: AppController Curation
+
+## Phase 1: Structural Audit & Conventions Update
+- [x] Task: Audit `src/app_controller.py` against `gui_2.py` organization and the Python Style Guide. [checkpoint: audit_complete]
+- [~] Task: Identify methods for extraction to module level (Anti-OOP enforcement).
+- [ ] Task: Update `conductor/code_styleguides/python.md` or `product-guidelines.md` if any new nuances are discovered in `gui_2.py`.
+- [ ] Task: Conductor - User Manual Verification 'Phase 1: Structural Audit' (Protocol in workflow.md)
+
+## Phase 2: Refactoring & Curation
+- [ ] Task: Apply 1-space indentation and remove excessive blank lines in `src/app_controller.py`.
+- [ ] Task: Clean up and organize `AppController.__init__` state declarations.
+- [ ] Task: Implement missing type hints and SDM tags.
+- [ ] Task: Extract identified logic to module-level functions.
+- [ ] Task: Conductor - User Manual Verification 'Phase 2: Refactoring & Curation' (Protocol in workflow.md)
+
+## Phase 3: Validation & Regression Testing
+- [ ] Task: Run the full test suite in batches of 4 files per test run.
+- [ ] Task: Fix any regressions or type errors discovered during testing.
+- [ ] Task: Conductor - User Manual Verification 'Phase 3: Validation & Regression Testing' (Protocol in workflow.md)

conductor/tracks/app_controller_curation_20260513/spec.md

@@ -0,0 +1,21 @@
+# Specification: AppController Curation & Structural Alignment
+
+## Context
+Following the successful cleanup and refactoring of `gui_2.py`, the same organizational patterns and AI-optimized coding conventions must be applied to `src/app_controller.py`. This module is a critical part of the Manual Slop architecture, acting as the bridge between the GUI and the underlying AI/MCP systems.
+
+## Goals
+1. **Structural Parity:** Reorganize `src/app_controller.py` to match the structure and quality of `gui_2.py`.
+2. **Standardization:** Enforce the AI-Optimized Python Style Guide (1-space indent, minimal blank lines, type hints, SDM tags).
+3. **Refactoring:** Identify and extract logic that violates the 5-level nesting limit or is better suited as module-level functions.
+4. **Validation:** Ensure full system integrity via the comprehensive test suite, run in batches of 4.
+
+## Scope
+- `src/app_controller.py`: Primary target for refactoring and curation.
+- `conductor/code_styleguides/python.md`: Potential updates if new nuances are found.
+- `conductor/product-guidelines.md`: Potential updates based on structural findings.
+
+## Constraints
+- **Indentation:** Must be exactly 1 space.
+- **Scoping:** Use `imscope` for any ImGui-related calls if present (though `app_controller` should ideally be logic-focused, some status rendering might exist).
+- **Anti-OOP:** Move state-independent methods to module level.
+- **Type Safety:** 100% type hint coverage for all modified sections.