ed/manual_slop
Private
Public Access
0
0
Fork 0
Code Activity

Docstrings: SSDL + ASCII Layout Map for Preset Managers and Windows

Browse Source
This commit is contained in:
Edward R. Gonzalez
2026-06-13 16:30:34 -04:00
parent 1136273331
commit cb129aaed9
5 changed files with 213 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
conductor/tracks.md
+8
View File
@@ -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)*
conductor/tracks/sqlite_docs_gui_2_continued_20260613/plan.md
+58
View File
@@ -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**
conductor/tracks/sqlite_docs_gui_2_continued_20260613/spec.md
+58
View File
@@ -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.
conductor/tracks/sqlite_docs_gui_2_continued_20260613/state.toml
+24
View File
@@ -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" }
src/gui_2.py
+65
View File
@@ -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: