# 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.