chore(conductor): initialize sqlite_docs_gui_2_20260612 track

2026-06-12 21:12:49 -04:00
parent 6aafac5d2f
commit 99e7b6e87f
5 changed files with 224 additions and 0 deletions
@@ -22,6 +22,7 @@ Tracks that are unblocked and ready to start. Ordered by **dependency** (blocked
 | 5 | A | [MCP Architecture Refactor (Sub-MCP Extraction)](#track-mcp-architecture-refactor-sub-mcp-extraction) | spec ✓, plan pending | test_infrastructure_hardening_20260609 (merged), data_oriented_error_handling, data_structure_strengthening |
 | 6 | D | [Public API Result Migration](#track-public-api-result-migration-followup) | placeholder; not yet specced | data_oriented_error_handling (deprecated `send()`) |
 | 7 | — | [UI Polish (Five Issues)](#track-ui-polish-five-issues) | spec ✓, plan ✓, ready to start | (none — independent) |
+| 7a | B | [SQLite-Granularity Inline Docs for gui_2.py](#track-sqlite-granularity-inline-docs-for-gui_2py) | spec ✓, plan ✓, ready to start | (none — independent) |
 | 8 | — | [Bootstrap gencpp Python Bindings](#track-bootstrap-gencpp-python-bindings) | spec TBD | (none — independent) |
 | 9 | — | [Tree-Sitter Lua MCP Tools](#track-tree-sitter-lua-mcp-tools) | spec TBD | (none — independent) |
 | 10 | — | [GDScript Language Support Tools](#track-gdscript-language-support-tools) | spec TBD | (none — independent) |
@@ -492,6 +493,11 @@ Lightweight chronology; full spec/plan/state per track is in the linked folder.
 #### Track: RAG Phase 4 Stress Test Fix `[x] — fixed 16412ad5`
 *Status: 2026-06-06 — Surfaced during post-v2 verification. Resolved: real bug, NOT a test flake. Root cause: ChromaDB collection dimension mismatch across test runs. The persistent on-disk collection (`tests/artifacts/live_gui_workspace/.slop_cache/chroma_test_stress/`) was created by a previous run with Gemini embeddings (3072-dim); the current run uses local SentenceTransformers (384-dim). `index_file()` upserts silently corrupt the collection, then `search()` fails with `Collection expecting embedding with dimension of 3072, got 384` and the AI request never reaches 'done' status, timing out the 50*0.5s = 25s poll loop. Fix: `RAGEngine._init_vector_store` now calls `_validate_collection_dim` which inspects the first existing vector's dim, compares to the current provider's output, and recreates the collection on mismatch (with a stderr warning). Regression tests added: `test_rag_collection_dim_mismatch_recreates_collection` and `test_rag_collection_dim_match_preserves_collection` in `tests/test_rag_engine.py`. This also fixes a real user-facing bug: switching embedding providers in the GUI previously caused silent corruption. Commit 16412ad5.*

+#### Track: SQLite-Granularity Inline Docs for gui_2.py `[track-created: sqlite_docs_gui_2_20260612]`
+*Link: [./tracks/sqlite_docs_gui_2_20260612/](./tracks/sqlite_docs_gui_2_20260612/), Spec: [./tracks/sqlite_docs_gui_2_20260612/spec.md](./tracks/sqlite_docs_gui_2_20260612/spec.md), Plan: [./tracks/sqlite_docs_gui_2_20260612/plan.md](./tracks/sqlite_docs_gui_2_20260612/plan.md)*
+
+*Goal: Add SQLite-granularity docstrings with embedded ASCII layouts and DAG relationships for `src/gui_2.py` panel-by-panel. Ensure zero functional regression. 5 phases: app lifecycle & setup, discussion panel, context panel, settings/hubs, and diagnostics/modals.*
+
 #### Track: Intent-Based Scripting Languages Survey `[COMPLETE: 213e4994]`
 *Link: [./tracks/intent_dsl_survey_20260612/](./tracks/intent_dsl_survey_20260612/), Spec: [./tracks/intent_dsl_survey_20260612/spec.md](./tracks/intent_dsl_survey_20260612/spec.md), Plan: [./tracks/intent_dsl_survey_20260612/plan.md](./tracks/intent_dsl_survey_20260612/plan.md), Report: [./tracks/intent_dsl_survey_20260612/report_v1.2.md](./tracks/intent_dsl_survey_20260612/report_v1.2.md), v1.1: [./tracks/intent_dsl_survey_20260612/report_v1.1.md](./tracks/intent_dsl_survey_20260612/report_v1.1.md), v1.0: [./tracks/intent_dsl_survey_20260612/report.md](./tracks/intent_dsl_survey_20260612/report.md), Review: [./tracks/intent_dsl_survey_20260612/reportreview.md](./tracks/intent_dsl_survey_20260612/reportreview.md)*

@@ -0,0 +1,14 @@
+{
+  "track_id": "sqlite_docs_gui_2_20260612",
+  "name": "SQLite-Granularity Inline Docs for gui_2.py",
+  "created": "2026-06-12",
+  "priority": "B (documentation)",
+  "status": "active",
+  "type": "documentation",
+  "domain": "UI/UX",
+  "blocked_by": [],
+  "deliverable": "src/gui_2.py",
+  "spec_path": "conductor/tracks/sqlite_docs_gui_2_20260612/spec.md",
+  "plan_path": "conductor/tracks/sqlite_docs_gui_2_20260612/plan.md",
+  "state_path": "conductor/tracks/sqlite_docs_gui_2_20260612/state.toml"
+}
@@ -0,0 +1,73 @@
+# SQLite-Granularity Inline Docs for gui_2.py — Implementation Plan
+
+> **For agentic workers:** Use task-by-task execution. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Implement SQLite-granularity docstrings with embedded ASCII layouts and DAG relationships for `src/gui_2.py` panel-by-panel. Ensure zero functional regression.
+
+---
+
+## File Structure
+
+| File | Action | Purpose |
+|---|---|---|
+| `src/gui_2.py` | Modify | Add SQLite-style docstrings with ASCII wireframes to all main classes, methods, and functions. |
+| `conductor/tracks/sqlite_docs_gui_2_20260612/state.toml` | Modify | Track implementation state. |
+| `conductor/tracks.md` | Modify | Register the new track. |
+
+---
+
+# Phase 1: App Lifecycle & Setup
+
+## Task 1.1: Document App class constructor and lifecycle entry points
+- [ ] **Step 1: Document `App.__init__`**
+  Add docstring detailing setup sequence (event listeners, thread initialization, window default states, preset loading).
+- [ ] **Step 2: Document `App.run`**
+  Add docstring detailing hello_imgui initialization, window setup, styling profile setup, and running loop entrance.
+- [ ] **Step 3: Document `App._gui_func`**
+  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`**
+  Add docstring detailing file cache flush, background worker termination, profile dump, and clean exit procedures.
+- [ ] **Step 5: Verify syntax and run existing tests**
+  Run: `pytest tests/test_gui_window_controls.py`
+  Expected: Success.
+
+## Task 1.2: Document state preservation, undo/redo, and profiles
+- [ ] **Step 1: Document `App._take_snapshot` and `_apply_snapshot`**
+- [ ] **Step 2: Document `App._capture_workspace_profile` and `_apply_workspace_profile`**
+- [ ] **Step 3: Document `App._handle_undo` and `_handle_redo`**
+- [ ] **Step 4: Verify syntax and run tests**
+  Run: `pytest tests/`
+
+---
+
+# Phase 2: Discussion Panel & Controls
+
+## Task 2.1: Document discussion entry renderer
+- [ ] **Step 1: Document `render_discussion_entry`**
+  Add detailed docstring. Include an ASCII layout map showing how individual bubbles appear (role select, token stats, edit buttons, expand/collapse toggles).
+- [ ] **Step 2: Document `render_discussion_entry_controls`**
+  Add detailed docstring. Include ASCII map of discussion bottom-bar controls (Truncate, Keep Pairs, Compress, Save).
+- [ ] **Step 3: Verify syntax and run discussion tests**
+  Run: `pytest tests/test_log_management_ui.py` (or other relevant UI tests)
+
+---
+
+# Phase 3: Context Panel & AST Inspector
+
+## Task 3.1: Document context composition panels
+- [ ] **Step 1: Document `render_context_composition_panel`**
+  Include ASCII showing Context Preset loading, batch action headers, Collapsible Directory grouped tree, and screenshot list.
+- [ ] **Step 2: Document `render_context_files_table`**
+  Include ASCII layout showing file row controls (Def, Sig, Hide, Slice editor triggers).
+- [ ] **Step 3: Document `render_ast_inspector_modal`**
+  Include ASCII layout of the tree-sitter AST inspector modal.
+- [ ] **Step 4: Verify syntax and run tests**
+
+---
+
+# Phase 5: Complete Verification & Final Wrap
+
+## Task 5.1: Register track and update status
+- [ ] **Step 1: Update `conductor/tracks.md`**
+  Add this track to the Project Tracks inventory list under active phase 8/9 tracks.
+- [ ] **Step 2: Mark track as complete in state.toml**
@@ -0,0 +1,87 @@
+# Track: SQLite-Granularity Inline Docs for gui_2.py
+
+**Status:** Spec approved 2026-06-12
+**Initialized:** 2026-06-12
+**Owner:** Tier 2 Tech Lead
+**Priority:** Medium (Documentation / UX Maintenance)
+
+---
+
+## 1. Overview
+This track introduces **SQLite-style inline documentation** to the codebase's main user interface orchestrator: `src/gui_2.py` (~285KB, ~5400 lines). We will enrich the file's primary entry points, classes, and render modules with strict, descriptive docstrings detailing functional responsibilities, state mutations, parent/child relationships in the immediate-mode rendering DAG, threading limits, and accurate **ASCII layout sketches**.
+
+This track follows the brainstorming guidelines: it focuses purely on building clear, long-form inline documentation panel-by-panel rather than modifying runtime logic.
+
+---
+
+## 2. Goals (Priority Order)
+
+| Priority | Goal | Rationale |
+|---|---|---|
+| **A** | Document App class constructor & lifecycle entry points (`__init__`, `run`, `_gui_func`, `shutdown`). | Establishes the core window lifecycle and thread-boundaries. |
+| **A** | Document the Discussion panel renderer & controls (`render_discussion_entry`, controls, etc.) with layout sketches. | The discussion area is the main interface hub; documenting it clarifies its complex interactive parts. |
+| **A** | Document the Context panel & AST inspector (`render_context_composition_panel`, `render_context_files_table`, modals). | Clarifies how context files are listed, annotated, and passed downstream. |
+| **B** | Document project/AI settings panels and managers (presets, personas, provider options). | Maps config mutations to disk state. |
+| **B** | Document diagnostics, tool analytics, command palette, and approval popups. | Documents helper utilities and security clutch hooks. |
+
+---
+
+## 3. The Documentation Convention
+Every target class, method, or function in `src/gui_2.py` gets a Python docstring (`"""`) structured as follows:
+
+1. **Functional Purpose:** Summary of the component's job.
+2. **Parameters & Inputs:** Specific types (especially the `app: App` argument).
+3. **State Mutations:** Tracked variables mutated within the GUI scope (e.g. `app.show_windows`).
+4. **Immediate-Mode DAG Context:**
+   - **Called by:** Parent render loop node.
+   - **Calls:** Child render functions.
+5. **ASCII Layout Sketch:** Exact visual mockup of the panel layout using box-drawing characters and bracket notations (e.g. `[Button]`, `[x] Checkbox`).
+6. **Thread Boundaries:** Confirming synchronous main-thread execution within the ImGui window frame.
+
+---
+
+## 4. Phased Breakdown
+
+### Phase 1: App Lifecycle & Setup
+- `App.__init__`
+- `App.run`
+- `App._gui_func`
+- `App.shutdown`
+- Profile state preservation and undo/redo loops.
+
+### Phase 2: Discussion Panel & Controls
+- `render_discussion_entry`
+- `render_discussion_entry_controls`
+- `truncate_entries`
+- Thinking parser.
+
+### Phase 3: Context Panel & AST Inspector
+- `render_context_composition_panel`
+- `render_context_files_table`
+- `render_ast_inspector_modal`
+- Batch actions.
+
+### Phase 4: Settings & Hubs
+- `render_project_settings_hub`
+- `render_projects_panel`
+- `render_paths_panel`
+- `render_ai_settings_hub`
+- `render_agent_tools_panel`
+- `render_provider_panel`
+- `render_persona_selector_panel`
+- Tool preset manager.
+
+### Phase 5: Diagnostics, Analytics & Modals
+- `render_diagnostics_panel`
+- `render_cache_panel`
+- `render_usage_analytics_panel`
+- `render_token_budget_panel`
+- `render_log_management`
+- Command Palette panels.
+- Approve modals (HITL).
+
+---
+
+## 5. Verification Criteria
+1. **Syntax Integrity:** Run `py_check_syntax` on modified files after every edit to confirm correct AST construction.
+2. **Regression Check:** Run `pytest tests/` after each phase. The addition of documentation must not alter execution paths, types, or throw warnings.
@@ -0,0 +1,44 @@
+# Track state for sqlite_docs_gui_2_20260612
+# Updated as tasks complete
+
+[meta]
+track_id = "sqlite_docs_gui_2_20260612"
+name = "SQLite-Granularity Inline Docs for gui_2.py"
+status = "active"
+current_phase = 1
+last_updated = "2026-06-12"
+
+[blocked_by]
+
+[phases]
+phase_1 = { status = "pending", checkpoint_sha = "", name = "App Lifecycle & Setup" }
+phase_2 = { status = "pending", checkpoint_sha = "", name = "Discussion Panel & Controls" }
+phase_3 = { status = "pending", checkpoint_sha = "", name = "Context Panel & AST Inspector" }
+phase_4 = { status = "pending", checkpoint_sha = "", name = "Settings & Hubs" }
+phase_5 = { status = "pending", checkpoint_sha = "", name = "Diagnostics, Analytics & Modals" }
+
+[tasks]
+# Phase 1: App Lifecycle & Setup
+t1_1 = { status = "pending", commit_sha = "", description = "Document App.__init__" }
+t1_2 = { status = "pending", commit_sha = "", 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
+t2_1 = { status = "pending", commit_sha = "", description = "Document render_discussion_entry" }
+t2_2 = { status = "pending", commit_sha = "", description = "Document render_discussion_entry_controls" }
+t2_3 = { status = "pending", commit_sha = "", description = "Document thinking parser and remaining discussion rendering" }
+
+# Phase 3: Context Panel & AST Inspector
+t3_1 = { status = "pending", commit_sha = "", description = "Document render_context_composition_panel and context_files_table" }
+t3_2 = { status = "pending", commit_sha = "", description = "Document render_ast_inspector_modal" }
+t3_3 = { status = "pending", commit_sha = "", description = "Document remaining context helpers and modals" }
+
+# Phase 4: Settings & Hubs
+t4_1 = { status = "pending", commit_sha = "", description = "Document project settings, paths, and AI settings hubs" }
+t4_2 = { status = "pending", commit_sha = "", description = "Document agent tools, provider panel, system prompts, and personas" }
+t4_3 = { status = "pending", commit_sha = "", description = "Document preset managers and editors" }
+
+# Phase 5: Diagnostics, Analytics & Modals
+t5_1 = { status = "pending", commit_sha = "", description = "Document diagnostics, usage analytics, and cache panels" }
+t5_2 = { status = "pending", commit_sha = "", description = "Document command palette panels and logic" }
+t5_3 = { status = "pending", commit_sha = "", description = "Document approval modals and final index" }