archiving tracks

conductor/archive/track_progress_viz_20260306/spec.md

@@ -0,0 +1,111 @@
+# Track Specification: Track Progress Visualization (track_progress_viz_20260306)
+
+## Overview
+Progress bars and percentage completion for active tracks and tickets. Better visualization of DAG execution state.
+
+## Current State Audit
+
+### Already Implemented (DO NOT re-implement)
+
+#### Track Model (src/models.py)
+- **`Track` dataclass**: Has `tickets: list[Ticket]` field
+- **`Ticket.status`**: "todo" | "in_progress" | "completed" | "blocked"
+
+#### Track Listing (src/project_manager.py)
+- **`get_all_tracks()`**: Returns list of track metadata with progress
+- **Progress calculation exists**: Counts completed vs total tickets
+
+#### DAG Engine (src/dag_engine.py)
+- **`TrackDAG`**: Manages ticket dependency graph
+- **Status tracking via `update_task_status()`**
+
+### Gaps to Fill (This Track's Scope)
+- No visual progress bar in GUI
+- No percentage completion display
+- No ETA estimation
+- No ticket breakdown display
+
+## Architectural Constraints
+
+### Accurate State
+- Progress MUST reflect actual ticket status
+- Count completed, in_progress, blocked, todo separately
+
+### Efficient Updates
+- Status changes trigger immediate UI update
+- No polling - event-driven via MMA state updates
+
+## Architecture Reference
+
+### Key Integration Points
+
+| File | Lines | Purpose |
+|------|-------|---------|
+| `src/gui_2.py` | 2650-2750 | MMA Dashboard - add progress display |
+| `src/project_manager.py` | 289-320 | `get_all_tracks()` - progress data |
+| `src/dag_engine.py` | 50-80 | Status tracking |
+
+### Progress Calculation
+```python
+def calculate_progress(tickets: list[Ticket]) -> dict:
+ total = len(tickets)
+ completed = sum(1 for t in tickets if t.status == "completed")
+ in_progress = sum(1 for t in tickets if t.status == "in_progress")
+ blocked = sum(1 for t in tickets if t.status == "blocked")
+ todo = sum(1 for t in tickets if t.status == "todo")
+ percentage = (completed / total * 100) if total > 0 else 0
+ return {
+  "total": total, "completed": completed, "in_progress": in_progress,
+  "blocked": blocked, "todo": todo, "percentage": percentage
+ }
+```
+
+## Functional Requirements
+
+### FR1: Progress Bar
+- Visual progress bar using `imgui.progress_bar()`
+- Show 0-100% completion
+- Color based on progress (red < 25%, yellow < 75%, green >= 75%)
+
+### FR2: Percentage Text
+- Display "X% complete" below bar
+- Show "X/Y tickets completed"
+
+### FR3: Ticket Breakdown
+- Show counts: completed, in_progress, blocked, todo
+- Use colored indicators per status
+
+### FR4: ETA Estimation
+- Track average time per completed ticket
+- Estimate remaining time: `avg_time * remaining_tickets`
+- Display as "ETA: ~Xm"
+
+## Non-Functional Requirements
+
+| Requirement | Constraint |
+|-------------|------------|
+| Update Latency | <100ms after status change |
+| Memory | <100 bytes for ETA state |
+
+## Testing Requirements
+
+### Unit Tests
+- Test progress calculation accuracy
+- Test ETA estimation logic
+
+### Integration Tests
+- Complete tickets, verify progress updates
+- Verify ETA recalculates
+
+## Out of Scope
+- Historical progress tracking
+- Progress export
+- Multi-track comparison
+
+## Acceptance Criteria
+- [ ] Progress bar renders correctly
+- [ ] Percentage accurate (X/Y completed)
+- [ ] Ticket breakdown displayed
+- [ ] ETA estimation works
+- [ ] Updates on ticket status change
+- [ ] 1-space indentation maintained