archive

conductor/archive/visual_dag_ticket_editing_20260306/spec.md

@@ -0,0 +1,95 @@
+# Track Specification: Visual DAG & Interactive Ticket Editing (visual_dag_ticket_editing_20260306)
+
+## Overview
+Replace linear ticket list with interactive node graph using ImGui Bundle node editor. Users can visually drag dependency lines, split nodes, or delete tasks before execution.
+
+## Current State Audit
+
+### Already Implemented (DO NOT re-implement)
+- **`imgui_bundle`**: Includes node editor capability
+- **`_render_ticket_dag_node()`**: Renders ticket nodes (simple tree view)
+- **`dag_engine.py`**: DAG validation, cycle detection (`has_cycle()`)
+
+### Gaps to Fill (This Track's Scope)
+- No true node editor integration for visual graph
+- No visual dependency lines between nodes
+- No drag-to-connect for creating dependencies
+- No edit validation before saving
+
+## Functional Requirements
+
+### FR1: Node Editor Integration
+- Use `imgui.node_editor` context for ticket visualization
+- Render each ticket as a node with:
+  - Title: ticket.id
+  - Color: based on status (todo=gray, running=yellow, blocked=red, done=green)
+  - Position: auto-layout or manual positioning
+
+### FR2: Visual Dependencies
+- Draw lines between nodes based on `depends_on` field
+- Arrow direction: from dependency to dependent
+- Line style: curved or straight
+
+### FR3: Interactive Editing
+- Drag nodes to reposition
+- Click-drag from output port to input port to create dependency
+- Right-click to remove dependency
+- Validate DAG (no cycles) before saving changes
+
+### FR4: DAG Validation
+- Use existing `dag_engine.TrackDAG.has_cycle()` 
+- Show error dialog if cycle detected
+- Prevent save if validation fails
+
+## Non-Functional Requirements
+
+| Requirement | Constraint |
+|-------------|------------|
+| Frame Rate | 60fps with 50+ nodes |
+| Response Time | <100ms for node interaction |
+
+## Architecture Reference
+
+### Key Integration Points
+
+| File | Lines | Purpose |
+|------|-------|---------|
+| `src/gui_2.py` | 1670-1700 | `_render_ticket_dag_node()` |
+| `src/dag_engine.py` | 30-50 | `TrackDAG`, `has_cycle()` |
+| `src/models.py` | 30-60 | `Ticket`, `depends_on` |
+
+### ImGui Node Editor Pattern
+```python
+import imgui_bundle.node_editor as ed
+
+# Begin node editor context
+ed.begin("Ticket DAG")
+# Create nodes
+for ticket in tickets:
+    ed.begin_node(ticket.id)
+    ed.set_node_position(ticket.id, x, y)
+    # ... render node content
+    ed.end_node()
+# Create links for dependencies
+for ticket in tickets:
+    for dep in ticket.depends_on:
+        ed.link(dep, ticket.id)
+ed.end()
+```
+
+## Dependencies
+- **Coordinates with**: `true_parallel_worker_execution_20260306` (for real-time status updates)
+
+## Out of Scope
+- Automatic layout algorithms (manual positioning for now)
+- Saving layout to disk
+- Zoom/pan controls
+
+## Acceptance Criteria
+- [ ] Node editor displays all tickets as connected nodes
+- [ ] Users can drag nodes to reposition
+- [ ] Users can create/remove dependencies via drag
+- [ ] Visual changes sync to backend Ticket state
+- [ ] DAG validity enforced (no cycles allowed)
+- [ ] 60fps maintained with 50+ nodes
+- [ ] 1-space indentation maintained