diff --git a/conductor/tracks.md b/conductor/tracks.md index 405d9d4c..36dca311 100644 --- a/conductor/tracks.md +++ b/conductor/tracks.md @@ -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)* diff --git a/conductor/tracks/sqlite_docs_gui_2_20260612/metadata.json b/conductor/tracks/sqlite_docs_gui_2_20260612/metadata.json new file mode 100644 index 00000000..a61d9574 --- /dev/null +++ b/conductor/tracks/sqlite_docs_gui_2_20260612/metadata.json @@ -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" +} diff --git a/conductor/tracks/sqlite_docs_gui_2_20260612/plan.md b/conductor/tracks/sqlite_docs_gui_2_20260612/plan.md new file mode 100644 index 00000000..7f1f0dbd --- /dev/null +++ b/conductor/tracks/sqlite_docs_gui_2_20260612/plan.md @@ -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** diff --git a/conductor/tracks/sqlite_docs_gui_2_20260612/spec.md b/conductor/tracks/sqlite_docs_gui_2_20260612/spec.md new file mode 100644 index 00000000..421eabe8 --- /dev/null +++ b/conductor/tracks/sqlite_docs_gui_2_20260612/spec.md @@ -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. diff --git a/conductor/tracks/sqlite_docs_gui_2_20260612/state.toml b/conductor/tracks/sqlite_docs_gui_2_20260612/state.toml new file mode 100644 index 00000000..53ce0a1b --- /dev/null +++ b/conductor/tracks/sqlite_docs_gui_2_20260612/state.toml @@ -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" }