From 5398b4eef004707b3041153a16bffc6191be8645 Mon Sep 17 00:00:00 2001 From: Ed_ Date: Tue, 12 May 2026 18:58:48 -0400 Subject: [PATCH] chore(conductor): Add new track 'GUI Refactor & Stabilization' --- conductor/tracks.md | 4 +++ .../index.md | 5 +++ .../metadata.json | 8 +++++ .../plan.md | 26 +++++++++++++++ .../spec.md | 33 +++++++++++++++++++ 5 files changed, 76 insertions(+) create mode 100644 conductor/tracks/gui_refactor_stabilization_20260512/index.md create mode 100644 conductor/tracks/gui_refactor_stabilization_20260512/metadata.json create mode 100644 conductor/tracks/gui_refactor_stabilization_20260512/plan.md create mode 100644 conductor/tracks/gui_refactor_stabilization_20260512/spec.md diff --git a/conductor/tracks.md b/conductor/tracks.md index 6198a2a..294298f 100644 --- a/conductor/tracks.md +++ b/conductor/tracks.md @@ -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 diff --git a/conductor/tracks/gui_refactor_stabilization_20260512/index.md b/conductor/tracks/gui_refactor_stabilization_20260512/index.md new file mode 100644 index 0000000..c333b89 --- /dev/null +++ b/conductor/tracks/gui_refactor_stabilization_20260512/index.md @@ -0,0 +1,5 @@ +# Track gui_refactor_stabilization_20260512 Context + +- [Specification](./spec.md) +- [Implementation Plan](./plan.md) +- [Metadata](./metadata.json) \ No newline at end of file diff --git a/conductor/tracks/gui_refactor_stabilization_20260512/metadata.json b/conductor/tracks/gui_refactor_stabilization_20260512/metadata.json new file mode 100644 index 0000000..3098bb2 --- /dev/null +++ b/conductor/tracks/gui_refactor_stabilization_20260512/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." +} \ No newline at end of file diff --git a/conductor/tracks/gui_refactor_stabilization_20260512/plan.md b/conductor/tracks/gui_refactor_stabilization_20260512/plan.md new file mode 100644 index 0000000..dc21a44 --- /dev/null +++ b/conductor/tracks/gui_refactor_stabilization_20260512/plan.md @@ -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) \ No newline at end of file diff --git a/conductor/tracks/gui_refactor_stabilization_20260512/spec.md b/conductor/tracks/gui_refactor_stabilization_20260512/spec.md new file mode 100644 index 0000000..f1ffa0b --- /dev/null +++ b/conductor/tracks/gui_refactor_stabilization_20260512/spec.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. \ No newline at end of file