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

2026-05-13 18:03:22 -04:00
parent a81b2088ba
commit 511aabbd0d
7 changed files with 125 additions and 1 deletions
@@ -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`)
@@ -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."
+}
@@ -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)
@@ -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.