diff --git a/conductor/tracks.md b/conductor/tracks.md index 5540a727..c75fef91 100644 --- a/conductor/tracks.md +++ b/conductor/tracks.md @@ -23,6 +23,7 @@ Tracks that are unblocked and ready to start. Ordered by **dependency** (blocked | 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 ✓, complete | (none — independent) | +| 7b | B | [Continued SQLite-Granularity Inline Docs for gui_2.py](#track-continued-sqlite-granularity-inline-docs-for-gui_2py) | spec ✓, plan ✓, in progress | (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) | @@ -502,6 +503,13 @@ Lightweight chronology; full spec/plan/state per track is in the linked folder. *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: Continued SQLite-Granularity Inline Docs for gui_2.py `[in-progress: sqlite_docs_gui_2_continued_20260613]` +*Link: [./tracks/sqlite_docs_gui_2_continued_20260613/](./tracks/sqlite_docs_gui_2_continued_20260613/), Spec: [./tracks/sqlite_docs_gui_2_continued_20260613/spec.md](./tracks/sqlite_docs_gui_2_continued_20260613/spec.md), Plan: [./tracks/sqlite_docs_gui_2_continued_20260613/plan.md](./tracks/sqlite_docs_gui_2_continued_20260613/plan.md)* + +*Status: 2026-06-13 — IN PROGRESS. Continuing the SQLite-style docstring initiative for preset managers, editors, persona selectors, and the command palette modal.* + +*Goal: Document preset managers/editors, persona selectors/editors, provider panel, and command palette in `src/gui_2.py` and `src/command_palette.py` with embedded SSDL and ASCII layouts.* + #### 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_continued_20260613/plan.md b/conductor/tracks/sqlite_docs_gui_2_continued_20260613/plan.md new file mode 100644 index 00000000..86f99179 --- /dev/null +++ b/conductor/tracks/sqlite_docs_gui_2_continued_20260613/plan.md @@ -0,0 +1,58 @@ +# SQLite-Granularity Inline Docs for gui_2.py (Continued) — Implementation Plan + +> **For agentic workers:** Use task-by-task execution. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Implement SQLite-granularity docstrings with embedded SSDL and ASCII layouts for the remaining layout/tool preset managers, persona editors/selectors, provider settings, and command palette in `src/gui_2.py` and `src/command_palette.py`. Ensure zero functional regression. + +--- + +## File Structure + +| File | Action | Purpose | +|---|---|---| +| `src/gui_2.py` | Modify | Add docstrings with SSDL & ASCII wireframes to preset managers, persona editor/selector, and provider panels. | +| `src/command_palette.py` | Modify | Add docstrings with SSDL & ASCII wireframes to `render_palette_modal`. | +| `conductor/tracks/sqlite_docs_gui_2_continued_20260613/state.toml` | Modify | Track implementation state. | +| `conductor/tracks.md` | Modify | Register the continued track. | + +--- + +# Phase 1: Preset Managers & Editors + +## Task 1.1: Document Preset Managers +- [ ] **Step 1: Document `render_save_preset_modal`** + Add ASCII Layout Map showing the Save Layout Preset modal layout. +- [ ] **Step 2: Document `render_preset_manager_content`** + Add ASCII Layout Map showing the Split Pane editor with presets sidebar, Name/Scope inputs, pop-out preview button, text editor, and action buttons. +- [ ] **Step 3: Document `render_preset_manager_window`** + Add ASCII Layout Map showing the window container wrapper. +- [ ] **Step 4: Document `render_tool_preset_manager_content`** + Add ASCII Layout Map showing the complex split pane layout containing categories & tools with radio toggles (Off/Auto/Ask) and bias profiles list/editor. +- [ ] **Step 5: Document `render_tool_preset_manager_window`** + Add ASCII Layout Map showing the window container wrapper. +- [ ] **Step 6: Verify syntax and run existing tests** + Run: `pytest tests/test_gui_window_controls.py` + Expected: Success. + +--- + +# Phase 2: Personas, Providers & Command Palette + +## Task 2.1: Document Personas & Providers +- [ ] **Step 1: Document `render_persona_editor_window`** + Add ASCII Layout Map showing the Persona Editor modal split pane layout (list sidebar and detailed configuration panel with preferred models and system prompt box). +- [ ] **Step 2: Document `render_persona_selector_panel`** + Add ASCII Layout Map showing the persona selection combo and Manage Personas button. +- [ ] **Step 3: Document `render_provider_panel`** + Add ASCII Layout Map showing the LLM Provider configuration list box, capabilities, parameters sliders, and gemini_cli configuration. +- [ ] **Step 4: Verify syntax and run tests** + +## Task 2.2: Document Command Palette +- [ ] **Step 1: Document `render_palette_modal` in `src/command_palette.py`** + Add docstring with SSDL and ASCII Layout Map for the fuzzy search query input and scored results list view. +- [ ] **Step 2: Verify syntax and run tests** + Run: `pytest tests/` (full batch run check) + +## Task 2.3: Register track and update status +- [ ] **Step 1: Update `conductor/tracks.md`** +- [ ] **Step 2: Mark track as complete in state.toml** diff --git a/conductor/tracks/sqlite_docs_gui_2_continued_20260613/spec.md b/conductor/tracks/sqlite_docs_gui_2_continued_20260613/spec.md new file mode 100644 index 00000000..343385a1 --- /dev/null +++ b/conductor/tracks/sqlite_docs_gui_2_continued_20260613/spec.md @@ -0,0 +1,58 @@ +# Track: Continued SQLite-Granularity Inline Docs for gui_2.py + +**Status:** Spec approved 2026-06-13 +**Initialized:** 2026-06-13 +**Owner:** Tier 2 Tech Lead +**Priority:** Medium (Documentation / UX Maintenance) + +--- + +## 1. Overview +This track continues the work of `sqlite_docs_gui_2_20260612` by adding SQLite-style inline documentation to the remaining, previously skipped preset managers, configuration panels, editors, and the command palette modal in `src/gui_2.py` and `src/command_palette.py`. We enrich these functions with strict, descriptive docstrings detailing functional responsibilities, SSDL operational DAGs, and detailed ASCII layout maps. + +--- + +## 2. Goals (Priority Order) + +| Priority | Goal | Rationale | +|---|---|---| +| **A** | Document Preset Managers and Windows (`render_save_preset_modal`, `render_preset_manager_content`, `render_preset_manager_window`, `render_tool_preset_manager_content`, `render_tool_preset_manager_window`). | Essential for mapping layout and tool preset configurations. | +| **A** | Document Persona Editor & Selectors (`render_persona_editor_window`, `render_persona_selector_panel`). | Maps the agent profile settings, preferred models, and bias profiles. | +| **B** | Document Provider settings (`render_provider_panel`). | Maps LLM hyper-parameters, token limits, and Gemini CLI pathing. | +| **B** | Document Command Palette modal (`render_palette_modal` in `src/command_palette.py`). | Establishes the interactive command query interface and keyboard boundaries. | + +--- + +## 3. The Documentation Convention +Every target function gets a Python docstring (`"""`) structured as follows: + +1. **Functional Purpose:** Summary of the component's job. +2. **Parameters & Inputs:** Specific types. +3. **Immediate-Mode DAG Context:** + - **Called by:** Parent render loop node. + - **Calls:** Child render functions. +4. **ASCII Layout Map:** Exact visual mockup of the panel layout using box-drawing characters and bracket notations (e.g. `[Button]`, `[x] Checkbox`, `(o) Radio`). +5. **Thread Boundaries:** Confirming synchronous main-thread execution within the ImGui window frame. + +--- + +## 4. Phased Breakdown + +### Phase 1: Preset Managers & Editors +- `render_save_preset_modal` +- `render_preset_manager_content` +- `render_preset_manager_window` +- `render_tool_preset_manager_content` +- `render_tool_preset_manager_window` + +### Phase 2: Personas, Providers & Command Palette +- `render_persona_editor_window` +- `render_persona_selector_panel` +- `render_provider_panel` +- `render_palette_modal` (in `src/command_palette.py`) + +--- + +## 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_continued_20260613/state.toml b/conductor/tracks/sqlite_docs_gui_2_continued_20260613/state.toml new file mode 100644 index 00000000..60d0f0f4 --- /dev/null +++ b/conductor/tracks/sqlite_docs_gui_2_continued_20260613/state.toml @@ -0,0 +1,24 @@ +# Track state for sqlite_docs_gui_2_continued_20260613 +# Updated as tasks complete + +[meta] +track_id = "sqlite_docs_gui_2_continued_20260613" +name = "Continued SQLite-Granularity Inline Docs for gui_2.py" +status = "active" +current_phase = 2 +last_updated = "2026-06-13" + +[blocked_by] + +[phases] +phase_1 = { status = "completed", checkpoint_sha = "", name = "Preset Managers & Editors" } +phase_2 = { status = "in_progress", checkpoint_sha = "", name = "Personas, Providers & Command Palette" } + +[tasks] +# Phase 1: Preset Managers & Editors +t1_1 = { status = "completed", commit_sha = "", description = "Document Preset Managers and Windows (render_save_preset_modal, render_preset_manager_content, render_preset_manager_window, render_tool_preset_manager_content, render_tool_preset_manager_window)" } + +# Phase 2: Personas, Providers & Command Palette +t2_1 = { status = "pending", commit_sha = "", description = "Document Personas & Providers (render_persona_editor_window, render_persona_selector_panel, render_provider_panel)" } +t2_2 = { status = "pending", commit_sha = "", description = "Document Command Palette (render_palette_modal in src/command_palette.py)" } +t2_3 = { status = "pending", commit_sha = "", description = "Register track and update status in tracks.md" } diff --git a/src/gui_2.py b/src/gui_2.py index 46ffeac5..29b82234 100644 --- a/src/gui_2.py +++ b/src/gui_2.py @@ -2798,6 +2798,15 @@ def render_save_preset_modal(app: App) -> None: """Renders the popup modal for saving the current ImGui window layout preset. SSDL: `[I:preset_inputs] => [B:save_cancel]` + + ASCII Layout Map: + +---------------------------------------------------------+ + | Save Layout Preset [X] | + +---------------------------------------------------------+ + | Preset Name: | + | | | | + | [Save] [Cancel] | + +---------------------------------------------------------+ """ if not app._show_save_preset_modal: return imgui.open_popup("Save Layout Preset") @@ -2827,6 +2836,23 @@ def render_preset_manager_content(app: App, is_embedded: bool = False) -> None: and the preset prompt content text editor. SSDL: `[I:presets_list] -> [B:new_preset] -> [I:editor_meta] -> [I:editor_textbox] => [B:save_delete]` + + ASCII Layout Map: + +---------------------------------------------------------+ + | [New Preset] | + | --- | + | | preset-a | Editing Prompt Preset: preset-a | + | | preset-b | --- | + | | Name: |preset-a| | + | | Scope: (o) Global ( ) Project | + | | --- | + | | Prompt Content: [Pop out MD Preview] + | | +--------------------------------+ | + | | | You are a coding assistant... | | + | | +--------------------------------+ | + | ------------------------------------------------------- | + | [Save] [Delete] [Close] | + +---------------------------------------------------------+ """ avail = imgui.get_content_region_avail() if not hasattr(app, "_prompt_md_preview"): app._prompt_md_preview = False @@ -2920,6 +2946,13 @@ def render_preset_manager_window(app: App, is_embedded: bool = False) -> None: """Renders the window container for the Prompt Presets Manager. SSDL: `[I] -> [I:window] => [I:preset_manager_content]` + + ASCII Layout Map: + +=================== Prompt Presets Manager =============+ + | | + | [ Renders render_preset_manager_content here ] | + | | + +========================================================+ """ if not app.show_preset_manager_window and not is_embedded: return if not is_embedded: @@ -2934,6 +2967,31 @@ def render_tool_preset_manager_content(app: App, is_embedded: bool = False) -> N """Renders the tool presets and tool capability profiles editor layout. SSDL: `[I:tool_presets] -> [B:new_tool_preset] -> [I:capability_toggles] -> [I:tools_list] => [B:save_delete]` + + ASCII Layout Map: + +---------------------------------------------------------+ + | [New Preset] | + | --- | + | | preset-a | Editing Tool Preset: preset-a | + | | preset-b | --- | + | | Name: |preset-a| | + | | Scope: (o) Global ( ) Project | + | | --- | + | | > Categories & Tools | + | | Filter: [All v] | + | | v file_io | + | | +----------------------------+ | + | | | read_file ( ) Off ( ) Auto (o) Ask | + | | | write_file ( ) Off ( ) Auto (o) Ask | + | | +----------------------------+ | + | | > Bias Profiles | + | | +------------------------------+ | + | | | [New Profile] | Name: |bias| | | + | | | profile-a | --- | | + | | +------------------------------+ | + | ------------------------------------------------------- | + | [Save] [Delete] [Close] | + +---------------------------------------------------------+ """ avail = imgui.get_content_region_avail() if not hasattr(app, "_tool_split_v"): app._tool_split_v = 0.4 @@ -3134,6 +3192,13 @@ def render_tool_preset_manager_window(app: App, is_embedded: bool = False) -> No """Renders the window container for the Tool Preset Manager. SSDL: `[I] -> [I:window] => [I:tool_preset_manager_content]` + + ASCII Layout Map: + +==================== Tool Preset Manager ===============+ + | | + | [ Renders render_tool_preset_manager_content here ] | + | | + +========================================================+ """ if not app.show_tool_preset_manager_window and not is_embedded: return if not is_embedded: