chore(conductor): Add new track 'GUI Refactor & Stabilization'

2026-05-12 18:58:48 -04:00
parent ea001e66f7
commit 5398b4eef0
5 changed files with 76 additions and 0 deletions
@@ -58,6 +58,10 @@ This file tracks all major tracks for the project. Each track has its own detail
    *Link: [./tracks/gui_architecture_refinement_20260512/](./tracks/gui_architecture_refinement_20260512/)*
    *Goal: Reduce nesting and compactness of ImGui code in `gui_2.py`, and formalize ImGui Defer patterns.*

+13. [ ] **Track: GUI Refactor & Stabilization**
+    *Link: [./tracks/gui_refactor_stabilization_20260512/](./tracks/gui_refactor_stabilization_20260512/)*
+    *Goal: Refactor gui_2.py to fix regressions and enforce better imgui scoping patterns.*
+
 ---

 ## Hot Reload Feature
@@ -0,0 +1,5 @@
+# Track gui_refactor_stabilization_20260512 Context
+
+- [Specification](./spec.md)
+- [Implementation Plan](./plan.md)
+- [Metadata](./metadata.json)
@@ -0,0 +1,8 @@
+{
+  "track_id": "gui_refactor_stabilization_20260512",
+  "type": "refactor",
+  "status": "new",
+  "created_at": "2026-05-12T00:00:00Z",
+  "updated_at": "2026-05-12T00:00:00Z",
+  "description": "Refactor gui_2.py to fix regressions and enforce better imgui scoping patterns using imgui_scopes.py."
+}
@@ -0,0 +1,26 @@
+# Implementation Plan: GUI Refactor & Stabilization
+
+## Phase 1: Linting & Verification Foundations
+- [ ] Task: Develop custom AST linter for ImGui scope/indentation in `scripts/check_imgui_scopes.py`.
+- [ ] Task: Write tests for the new AST linter to ensure it catches unclosed scopes and indentation mismatches.
+- [ ] Task: Expand API hooks in `src/api_hooks.py` to better simulate complex UI interactions (e.g., specific widget clicks, drag operations).
+- [ ] Task: Write tests for the new API hooks.
+- [ ] Task: Conductor - User Manual Verification 'Linting & Verification Foundations' (Protocol in workflow.md)
+
+## Phase 2: Targeted Sub-agent Test Framework
+- [ ] Task: Design and implement a focused test suite structure in `tests/` specifically for rapid sub-agent GUI verification without full E2E overhead.
+- [ ] Task: Migrate or create at least 3 high-value tests for the main panel rendering paths into this new suite.
+- [ ] Task: Verify the targeted suite runs quickly and reliably.
+- [ ] Task: Conductor - User Manual Verification 'Targeted Sub-agent Test Framework' (Protocol in workflow.md)
+
+## Phase 3: Piecemeal Refactoring - Main Panels (Part 1)
+- [ ] Task: Audit `gui_2.py` main panel rendering functions to identify the most critical scoping issues based on recent commits.
+- [ ] Task: Refactor the first identified critical panel rendering path in `gui_2.py` to use `imgui_scopes.py` patterns.
+- [ ] Task: Run targeted sub-agent tests and the custom AST linter against the modified panel. Fix any failures.
+- [ ] Task: Conductor - User Manual Verification 'Piecemeal Refactoring - Main Panels (Part 1)' (Protocol in workflow.md)
+
+## Phase 4: Piecemeal Refactoring - Main Panels (Part 2)
+- [ ] Task: Refactor the second identified critical panel rendering path in `gui_2.py` to use `imgui_scopes.py` patterns.
+- [ ] Task: Run targeted sub-agent tests and the custom AST linter against the modified panel. Fix any failures.
+- [ ] Task: Run the full E2E test suite to ensure no broad regressions were introduced.
+- [ ] Task: Conductor - User Manual Verification 'Piecemeal Refactoring - Main Panels (Part 2)' (Protocol in workflow.md)
@@ -0,0 +1,33 @@
+# Track Specification: GUI Refactor & Stabilization
+
+## Overview
+This track addresses recent regressions and entropy introduced into `./src/gui_2.py` by AI agents. Python's whitespace sensitivity makes managing complex `imgui` UI hierarchies difficult. The goal is to incrementally refactor `gui_2.py` to enforce better `imgui` scoping patterns (utilizing `imgui_scopes.py`), fix existing regressions, and implement robust linting and verification mechanisms to prevent future regressions.
+
+## Functional Requirements
+- **Piecemeal Refactoring**: Refactor `gui_2.py` in extremely small, isolated increments, focusing on one panel or rendering path at a time. Focus initially on main panel rendering paths recently modified.
+- **Scope Enforcement**: Integrate and enforce the use of `imgui_scopes.py` for all UI pair patterns (e.g., Begin/End, PushStyle/PopStyle) to mitigate indentation-related logic errors.
+- **Enhanced Verification**:
+  - **Expanded API Hooks**: Introduce new hooks to accurately simulate user interactions and verify internal UI state changes.
+  - **Custom AST Linter**: Develop a custom linting rule or script (potentially extending `ai_style_formatter.py` or creating a new tool) to validate `imgui` indentation and scope pairing.
+  - **Targeted Sub-agent Tests**: Create fast, focused test suites that sub-agents can run to verify specific UI rendering logic without executing the full E2E test suite.
+
+## Non-Functional Requirements
+- **Stability Over Speed**: The primary directive is heavy verification for every incremental change. 
+- **Code Style**: Strict adherence to the 1-space indentation rule and the `imscope` defer patterns defined in the project style guide.
+
+## Scope
+### In Scope
+- Refactoring `gui_2.py` rendering paths (especially main panels).
+- Integrating `imgui_scopes.py` into `gui_2.py`.
+- Creating new testing hooks, focused UI tests, and a custom AST linter for `imgui`.
+
+### Out of Scope
+- Migrating the GUI to another language (e.g., C, Odin, Go).
+- Modifying non-GUI-related application logic unless directly required for UI stability.
+
+## Acceptance Criteria
+- `gui_2.py` utilizes `imgui_scopes.py` for primary UI panels.
+- A custom linter successfully detects improper `imgui` scope usage and indentation issues.
+- New API hooks successfully simulate complex UI interactions.
+- A targeted test suite for UI logic runs quickly and reliably.
+- All refactoring passes the existing and new automated test suites.