docs(gui_2): Add SQLite-granularity docstrings for App init, run, _gui_func, and shutdown

conductor/tracks/sqlite_docs_gui_2_20260612/plan.md

@@ -19,15 +19,15 @@
 # Phase 1: App Lifecycle & Setup
 
 ## Task 1.1: Document App class constructor and lifecycle entry points
-- [ ] **Step 1: Document `App.__init__`**
+- [x] **Step 1: Document `App.__init__`** (99e7b6e)
   Add docstring detailing setup sequence (event listeners, thread initialization, window default states, preset loading).
-- [ ] **Step 2: Document `App.run`**
+- [x] **Step 2: Document `App.run`** (99e7b6e)
   Add docstring detailing hello_imgui initialization, window setup, styling profile setup, and running loop entrance.
-- [ ] **Step 3: Document `App._gui_func`**
+- [x] **Step 3: Document `App._gui_func`** (99e7b6e)
   Add docstring detailing main viewport render loop dispatch, hotkey intercepts (palette, reloading), layout presets, and viewport frame rendering. Include a high-level ASCII mockup of the entire dock layout.
-- [ ] **Step 4: Document `App.shutdown`**
+- [x] **Step 4: Document `App.shutdown`** (99e7b6e)
   Add docstring detailing file cache flush, background worker termination, profile dump, and clean exit procedures.
-- [ ] **Step 5: Verify syntax and run existing tests**
+- [x] **Step 5: Verify syntax and run existing tests** (99e7b6e)
   Run: `pytest tests/test_gui_window_controls.py`
   Expected: Success.
 

conductor/tracks/sqlite_docs_gui_2_20260612/state.toml

@@ -19,8 +19,8 @@ phase_5 = { status = "pending", checkpoint_sha = "", name = "Diagnostics, Analyt
 
 [tasks]
 # Phase 1: App Lifecycle & Setup
-t1_1 = { status = "pending", commit_sha = "", description = "Document App.__init__" }
+t1_1 = { status = "completed", commit_sha = "99e7b6e8", description = "Document App.__init__" }
-t1_2 = { status = "pending", commit_sha = "", description = "Document App.run, _gui_func, shutdown" }
+t1_2 = { status = "completed", commit_sha = "99e7b6e8", description = "Document App.run, _gui_func, shutdown" }
 t1_3 = { status = "pending", commit_sha = "", description = "Document App state preservation, undo/redo, profiles" }
 
 # Phase 2: Discussion Panel & Controls

src/gui_2.py

@@ -303,9 +303,23 @@ class App:
  """The main ImGui interface orchestrator for Manual Slop."""
 
  def __init__(self) -> None:
-  # Initialize controller and delegate state
   """
-    [C: src/mcp_client.py:_DDGParser.__init__, src/mcp_client.py:_TextExtractor.__init__]
+  Initializes core app dependencies (controller, history, performance monitor,
+  command palette, workspace manager) and registers app callback handlers.
+
+  State Mutations:
+    self.controller, self.perf_monitor, self.history,
+    self.show_command_palette, self.workspace_manager.
+
+  DAG Render Context:
+    Called by: main() at startup
+    Calls: AppController.init_state(), AppController.start_services(),
+           WorkspaceManager.load_all_profiles()
+
+  Threading & Safety:
+    Must run synchronously on the Main Thread during app startup.
+
+  [C: src/mcp_client.py:_DDGParser.__init__, src/mcp_client.py:_TextExtractor.__init__]
   """
   # --- Core Dependencies & State ---
   from src.startup_profiler import startup_profiler
@@ -595,9 +609,17 @@ class App:
 
  def run(self) -> None:
   """
+  Initializes the ImGui runner (HelloImGui) and starts the main application loop.
+  Loads system themes, default styling metrics, fonts, and sets up window docking layouts.
 
-    Initializes the ImGui runner and starts the main application loop.
+  DAG Render Context:
-    [C: simulation/sim_base.py:run_sim, src/mcp_client.py:get_git_diff, src/project_manager.py:get_git_commit, src/rag_engine.py:RAGEngine._search_mcp, src/shell_runner.py:run_powershell, tests/conftest.py:kill_process_tree, tests/conftest.py:live_gui, tests/test_conductor_abort_event.py:test_conductor_abort_event_populated, tests/test_conductor_engine_v2.py:test_conductor_engine_dynamic_parsing_and_execution, tests/test_conductor_engine_v2.py:test_conductor_engine_run_executes_tickets_in_order, tests/test_extended_sims.py:test_ai_settings_sim_live, tests/test_extended_sims.py:test_context_sim_live, tests/test_extended_sims.py:test_execution_sim_live, tests/test_extended_sims.py:test_tools_sim_live, tests/test_external_editor_gui.py:get_vscode_processes, tests/test_external_editor_gui.py:test_vscode_launches_with_diff_view, tests/test_gui_custom_window.py:test_app_window_is_borderless, tests/test_headless_simulation.py:module, tests/test_headless_verification.py:test_headless_verification_error_and_qa_interceptor, tests/test_headless_verification.py:test_headless_verification_full_run, tests/test_mock_gemini_cli.py:run_mock, tests/test_orchestration_logic.py:test_conductor_engine_run, tests/test_parallel_execution.py:test_conductor_engine_pool_integration, tests/test_sim_ai_settings.py:test_ai_settings_simulation_run, tests/test_sim_context.py:test_context_simulation_run, tests/test_sim_execution.py:test_execution_simulation_run, tests/test_sim_tools.py:test_tools_simulation_run]
+    Called by: main()
+    Calls: hello_imgui.run(), _profiled_setup_style(), _profiled_post_init(), _load_fonts()
+
+  Threading & Safety:
+    Invokes the blocking GUI loop on the Main Thread.
+
+  [C: simulation/sim_base.py:run_sim, src/mcp_client.py:get_git_diff, src/project_manager.py:get_git_commit, src/rag_engine.py:RAGEngine._search_mcp, src/shell_runner.py:run_powershell, tests/conftest.py:kill_process_tree, tests/conftest.py:live_gui, tests/test_conductor_abort_event.py:test_conductor_abort_event_populated, tests/test_conductor_engine_v2.py:test_conductor_engine_dynamic_parsing_and_execution, tests/test_conductor_engine_v2.py:test_conductor_engine_run_executes_tickets_in_order, tests/test_extended_sims.py:test_ai_settings_sim_live, tests/test_extended_sims.py:test_context_sim_live, tests/test_extended_sims.py:test_execution_sim_live, tests/test_extended_sims.py:test_tools_sim_live, tests/test_external_editor_gui.py:get_vscode_processes, tests/test_external_editor_gui.py:test_vscode_launches_with_diff_view, tests/test_gui_custom_window.py:test_app_window_is_borderless, tests/test_headless_simulation.py:module, tests/test_headless_verification.py:test_headless_verification_error_and_qa_interceptor, tests/test_headless_verification.py:test_headless_verification_full_run, tests/test_mock_gemini_cli.py:run_mock, tests/test_orchestration_logic.py:test_conductor_engine_run, tests/test_parallel_execution.py:test_conductor_engine_pool_integration, tests/test_sim_ai_settings.py:test_ai_settings_simulation_run, tests/test_sim_context.py:test_context_simulation_run, tests/test_sim_execution.py:test_execution_simulation_run, tests/test_sim_tools.py:test_tools_simulation_run]
   """
   if "--headless" in sys.argv:
    print("Headless mode active")
@@ -939,9 +961,20 @@ class App:
 
  def shutdown(self) -> None:
   """
+  Cleanly shuts down the app's background tasks, saves workspace layout configurations,
+  forces a save of dirty registries/caches, and terminates the active thread pools.
 
-    Cleanly shuts down the app's background tasks and saves state.
+  State Mutations:
-    [C: tests/conftest.py:app_instance, tests/conftest.py:mock_app]
+    runner_params settings are flushed to disk (imgui.save_ini_settings_to_disk).
+
+  DAG Render Context:
+    Called by: HelloImGui on exit.
+    Calls: AppController.shutdown()
+
+  Threading & Safety:
+    Executes synchronously on the Main Thread.
+
+  [C: tests/conftest.py:app_instance, tests/conftest.py:mock_app]
   """
   try:
    if hasattr(self, 'runner_params') and self.runner_params.ini_filename:
@@ -1023,11 +1056,39 @@ class App:
   os.makedirs("tests/artifacts", exist_ok=True)
   with open("tests/artifacts/temp_callback_output.txt", "w") as f:
    f.write(data)
-   # ---------------------------------------------------------------- helpers
-
-    # ---------------------------------------------------------------- gui
 
  def _gui_func(self) -> None:
+  """
+  Main immediate-mode render loop callback executed on every frame.
+  Dispatches keyboard shortcuts, renders the background shader, custom title bar,
+  main dockspace, and handles popups/modals.
+
+  State Mutations:
+    self.show_command_palette (toggled via Ctrl+Shift+P)
+    self._hot_reload_error (updated on Ctrl+Alt+R)
+
+  DAG Render Context:
+    Called by: HelloImGui runner loop on every frame.
+    Calls: render_main_interface(), render_custom_title_bar(),
+           _toggle_command_palette(), _trigger_hot_reload()
+
+  ASCII Layout Map:
+    +---------------------------------------------------------+
+    | [Menu: manual slop] [Windows] [Project] [Layout]   [x]  |
+    +--------------------+-------------------+----------------+
+    | Project / Files    | Discussion Hub    | Operations     |
+    |                    |                   |                |
+    | [x] file1.py (Sig) | [User]            | [Spawn Agent]  |
+    | [x] file2.py (Def) | I want you to...  |                |
+    |                    |                   |                |
+    | +----------------+ | [AI]              | [Exec clutch]  |
+    | | Presets        | | Analyzing code... |                |
+    | +----------------+ |                   |                |
+    +--------------------+-------------------+----------------+
+
+  Threading & Safety:
+    Must run synchronously on the Main Thread.
+  """
   # One-shot: log when immapp first hands control to our render callback. The
   # span init -> here is window/GL/context creation + the font/style/post_init
   # callbacks (all opaque C++); the span here -> mark_first_frame_rendered is