diff --git a/conductor/code_styleguides/python.md b/conductor/code_styleguides/python.md index 706b0f9..f3b0ecc 100644 --- a/conductor/code_styleguides/python.md +++ b/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. diff --git a/conductor/product-guidelines.md b/conductor/product-guidelines.md index 75ed213..4c7f92a 100644 --- a/conductor/product-guidelines.md +++ b/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) diff --git a/conductor/tracks.md b/conductor/tracks.md index d60b87a..a2fd98f 100644 --- a/conductor/tracks.md +++ b/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) diff --git a/conductor/tracks/app_controller_curation_20260513/extraction_list.md b/conductor/tracks/app_controller_curation_20260513/extraction_list.md new file mode 100644 index 0000000..8882802 --- /dev/null +++ b/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`) diff --git a/conductor/tracks/app_controller_curation_20260513/metadata.json b/conductor/tracks/app_controller_curation_20260513/metadata.json new file mode 100644 index 0000000..31ba45e --- /dev/null +++ b/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." +} diff --git a/conductor/tracks/app_controller_curation_20260513/plan.md b/conductor/tracks/app_controller_curation_20260513/plan.md new file mode 100644 index 0000000..0cebd14 --- /dev/null +++ b/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) diff --git a/conductor/tracks/app_controller_curation_20260513/spec.md b/conductor/tracks/app_controller_curation_20260513/spec.md new file mode 100644 index 0000000..03574fe --- /dev/null +++ b/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.