# 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