manual_slop/conductor/tracks/gui_architecture_refinement_20260512/plan.md

Plan: GUI Architecture Refinement & AI-Friendliness

Track ID: gui_architecture_refinement_20260512 Status: [~] Draft

Objective

Reduce nesting and improve compactness of ImGui code in gui_2.py to make it more AI-friendly. Formalize the "defer/scope" patterns (inspired by Go's defer and Ryan Fleury's macros) in the project style guides to prevent PopID / End leaks.

Background & Motivation

The main GUI render loop (_gui_func__abusrd_try_scope) has grown to over 600 lines with deep nesting. Raw imgui.begin() and imgui.end() calls are prone to leaks if an early return occurs or if the return value of begin is ignored. While imscope context managers solve the leak issue, they still introduce nesting. We need a way to keep the code extremely flat (0-1 levels of nesting) while maintaining safety.

Proposed Solution

1. Update Style Guides (python.md & workflow.md)

Introduce a new section explicitly defining the "ImGui Defer Patterns":

• The Context Manager Pattern: Use with imscope.window("Name"): to automatically handle End(). This adds only 1 space of indentation (per project rules).
• The Flat Dispatch Pattern: To avoid nesting multiple windows, use dispatch helpers like self._render_window_if_open(name, render_func) which encapsulate the state-checking, Begin, End, and execution logic.

2. Implement Flat Dispatch Helper

Create a helper method in App:

 def _render_window_if_open(self, name: str, render_func: Callable[[], None], flag_condition: bool = True) -> None:
  if not flag_condition or not self.show_windows.get(name, False): return
  with imscope.window(name, self.show_windows[name]) as (exp, opened):
   self.show_windows[name] = bool(opened)
   if exp: render_func()

3. Refactor gui_2.py

• Extract inline hub definitions (e.g., "Operations Hub", "Discussion Hub", "AI Settings") from _gui_func__abusrd_try_scope into dedicated methods (_render_operations_hub, etc.).
• Replace the massive if self.show_windows.get... blocks in _gui_func__abusrd_try_scope with a flat sequence of _render_window_if_open calls.
• Rename _gui_func__abusrd_try_scope to a cleaner name (e.g., _gui_func_body) once stabilized.

Implementation Steps

1. Edit conductor/code_styleguides/python.md to add "ImGui Defer Patterns" under the "AI-Agent Specific Conventions" or "Anti-OOP" section.
2. Edit conductor/workflow.md to reference the mandatory use of imscope or dispatch helpers for ImGui code.
3. Add _render_window_if_open to gui_2.py.
4. Extract _render_operations_hub, _render_discussion_hub, and _render_ai_settings_hub in gui_2.py.
5. Flatten _gui_func__abusrd_try_scope using the new helper.

Verification & Testing

• Ensure the app launches successfully without PopID errors.
• Verify that toggling windows via the menu still opens and closes them correctly.
• Run uv run pytest tests/test_gui_startup_smoke.py and uv run pytest tests/test_gui_window_controls.py.