conductor(archive): move 39 completed tracks (2026-05 to 2026-06) to archive/

2026-06-03 00:09:52 -04:00
parent 0ffeccc7d3
commit 594f14f943
160 changed files with 94 additions and 21 deletions
@@ -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 [checkpoint: 294217c]
+- [x] Task: Develop custom AST linter for ImGui scope/indentation in `scripts/check_imgui_scopes.py`. c359961
+- [x] Task: Write tests for the new AST linter to ensure it catches unclosed scopes and indentation mismatches. c359961
+- [x] Task: Expand API hooks in `src/api_hooks.py` to better simulate complex UI interactions (e.g., specific widget clicks, drag operations). a3b117d
+- [x] Task: Write tests for the new API hooks. a3b117d
+- [x] Task: Conductor - User Manual Verification 'Linting & Verification Foundations' (Protocol in workflow.md) 294217c
+
+## Phase 2: Targeted Sub-agent Test Framework [checkpoint: 972ff1b]
+- [x] Task: Design and implement a focused test suite structure in `tests/` specifically for rapid sub-agent GUI verification without full E2E overhead. 7c0ce9d
+- [x] Task: Migrate or create at least 3 high-value tests for the main panel rendering paths into this new suite. 7c0ce9d
+- [x] Task: Verify the targeted suite runs quickly and reliably. 7c0ce9d
+- [x] Task: Conductor - User Manual Verification 'Targeted Sub-agent Test Framework' (Protocol in workflow.md) 972ff1b
+
+## Phase 3: Piecemeal Refactoring - Main Panels (Part 1) [checkpoint: f3e307f]
+- [x] Task: Audit `gui_2.py` main panel rendering functions to identify the most critical scoping issues based on recent commits. 325970e
+- [x] Task: Refactor the first identified critical panel rendering path in `gui_2.py` to use `imgui_scopes.py` patterns. 325970e
+- [x] Task: Run targeted sub-agent tests and the custom AST linter against the modified panel. Fix any failures. 325970e
+- [x] Task: Conductor - User Manual Verification 'Piecemeal Refactoring - Main Panels (Part 1)' (Protocol in workflow.md) f3e307f
+
+## Phase 4: Piecemeal Refactoring - Main Panels (Part 2) [checkpoint: f79cdb9]
+- [x] Task: Refactor the second identified critical panel rendering path in `gui_2.py` to use `imgui_scopes.py` patterns. dd44582
+- [x] Task: Run targeted sub-agent tests and the custom AST linter against the modified panel. Fix any failures. dd44582
+- [x] Task: Run the full E2E test suite to ensure no broad regressions were introduced. dd44582
+- [x] Task: Conductor - User Manual Verification 'Piecemeal Refactoring - Main Panels (Part 2)' (Protocol in workflow.md) f79cdb9
@@ -0,0 +1,30 @@
+# Implementation Plan: Modular Context Composition UI
+
+## Objective
+Refactor the monolithic `_render_context_composition_panel` in `src/gui_2.py` into smaller, semantic methods to improve readability, maintainability, and reduce the complexity of the main GUI orchestrator.
+
+## Key Files & Context
+- `src/gui_2.py`: The target for refactoring.
+- `src/imgui_scopes.py`: Used for scoped ImGui blocks.
+
+## Implementation Steps
+
+### Phase 1: Infrastructure & Background Tasks
+- [ ] Task: Extract file stats background worker logic into `_update_context_file_stats()`.
+- [ ] Task: In `_render_context_composition_panel`, ensure state variables (`_file_stats_cache`, etc.) are initialized once.
+
+### Phase 2: Extract Sub-Panels
+- [ ] Task: Extract the batch action bar logic into `_render_context_batch_actions()`.
+- [ ] Task: Extract the grouped files tree table logic into `_render_context_files_table()`.
+- [ ] Task: Extract the screenshots section into `_render_context_screenshots()`.
+- [ ] Task: Extract the context presets section into `_render_context_presets()`.
+
+### Phase 3: Assembly & Verification
+- [x] Task: Reassemble `_render_context_composition_panel` by calling the new sub-methods.
+- [x] Task: Run the custom AST linter to ensure all scopes are correctly closed.
+- [x] Task: Run fast render tests to verify no regressions in the context panel.
+
+## Verification & Testing
+- **AST Linting**: `uv run python scripts/check_imgui_scopes.py src/gui_2.py`
+- **Fast Render Tests**: `uv run pytest tests/test_gui_fast_render.py`
+- **Manual Verification**: Open the Context Composition panel, verify batch actions work, files are correctly grouped and listed, and presets can be saved/loaded.
@@ -0,0 +1,34 @@
+# Implementation Plan: Clean Theme Abstraction
+
+## Objective
+Decouple the NERV theme logic and FX from `src/gui_2.py` by introducing a semantic theme layer in `src/theme_2.py`. This will remove scattered `is_nerv_active()` checks and keep the ImGui hierarchy clean.
+
+## Key Files & Context
+- `src/theme_2.py`: The primary theming interface.
+- `src/gui_2.py`: The main GUI module containing the "cruft".
+- `src/theme_nerv.py` & `src/theme_nerv_fx.py`: NERV-specific colors and effects.
+- `src/imgui_scopes.py`: Context managers for ImGui scopes.
+
+## Implementation Steps
+
+### Phase 1: Semantic Theme Layer Foundations
+- [ ] Task: In `src/theme_2.py`, define semantic color functions (e.g., `ai_text_color()`, `alert_color()`, `warning_color()`) that return theme-specific colors.
+- [ ] Task: In `src/theme_2.py`, implement context manager helpers (e.g., `ai_text_style()`, `alert_style()`) that wrap `imscope.style_color`.
+- [ ] Task: In `src/theme_2.py`, add a `render_post_fx(width, height, ai_status, crt_enabled)` hook that encapsulates CRT and Alert pulsing effects.
+- [ ] Task: Move `CRTFilter`, `AlertPulsing`, and `StatusFlicker` instances from `App` class to `src/theme_2.py` (private module state).
+
+### Phase 2: Refactor `gui_2.py`
+- [ ] Task: In `gui_2.py`, remove all NERV-specific filter/flicker/alert instances from `__init__`.
+- [ ] Task: In `_gui_func`, replace the NERV FX rendering block with a single call to `theme.render_post_fx()`.
+- [ ] Task: Systematically replace scattered `if is_nerv_active(): push_style_color(...)` blocks with the new semantic style context managers.
+- [ ] Task: Standardize status indicators (e.g., "PIPELINE PAUSED", "LIVE") to use semantic theme colors rather than manual `vec4` overrides.
+
+### Phase 3: Verification & Cleanup
+- [ ] Task: Run the custom AST linter to ensure no unclosed scopes were introduced during refactoring.
+- [ ] Task: Run fast render tests to ensure UI stability.
+- [ ] Task: Verify that both NERV and standard themes still render correctly (visual verification).
+
+## Verification & Testing
+- **AST Linting**: `uv run python scripts/check_imgui_scopes.py src/gui_2.py`
+- **Fast Render Tests**: `uv run pytest tests/test_gui_fast_render.py`
+- **Manual Verification**: Toggle NERV theme and verify CRT filter, alert pulsing, and DATA highlights are still active and correctly colored.
@@ -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.