hopefully done refining

conductor/tracks/track_progress_viz_20260306/spec.md

@@ -1,34 +1,111 @@
 # Track Specification: Track Progress Visualization (track_progress_viz_20260306)
 
 ## Overview
-Progress bars and percentage completion for active tracks and tickets.
+Progress bars and percentage completion for active tracks and tickets. Better visualization of DAG execution state.
 
 ## Current State Audit
 
-### Already Implemented
-- **`models.Track`**: Has tickets list
-- **`project_manager.get_all_tracks()`**: Returns track progress
-- **GUI**: Shows ticket status but no progress bar
+### Already Implemented (DO NOT re-implement)
 
-### Gaps to Fill
-- No visual progress bar
+#### 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
-- Progress bar showing % complete
-- Ticket count: X/Y completed
-- ETA estimation based on average time per ticket
 
-## Key Integration Points
-| File | Purpose |
-|-----|---------|
-| `src/gui_2.py` | Progress bar rendering |
-| `src/dag_engine.py` | Completion calculation |
+### 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
-- [ ] Percentage accurate
-- [ ] Counts match actual tickets
-- [ ] ETA calculation works
-- [ ] 1-space indentation
+- [ ] Progress bar renders correctly
+- [ ] Percentage accurate (X/Y completed)
+- [ ] Ticket breakdown displayed
+- [ ] ETA estimation works
+- [ ] Updates on ticket status change
+- [ ] 1-space indentation maintained