Private
Public Access
chore(conductor): initialize sqlite_docs_gui_2_20260612 track
This commit is contained in:
@@ -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" }
|
||||
Reference in New Issue
Block a user