manual_slop/conductor/archive/track_progress_viz_20260306/spec.md

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

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