Module productivity 

Productivity stats tracking for task completions, streaks, and velocity metrics.

Responsibilities:

• Track daily task completions and calculate streaks
• Record milestone achievements (10, 50, 100, etc.)
• Calculate velocity metrics (tasks per day/week)
• Persist stats to .ralph/cache/productivity.jsonc

Not handled here:

• Queue/task management (see crate::queue)
• Notification delivery (see crate::notification)
• Celebration rendering (see crate::celebrations)

Invariants/assumptions:

• Stats file is JSON with schema version for migrations
• Timestamps are RFC3339 format
• All operations are atomic (read-modify-write with file locking)

Structs

CompletedTaskRef

Reference to a completed task

CompletionResult

Result of recording a task completion

DayStats

Stats for a single day

EstimationMetrics

Estimation accuracy metrics for tasks with both estimated and actual minutes.

Milestone

A milestone achievement

ProductivityEstimationReport

Productivity estimation report

ProductivityStats

Root productivity data structure

ProductivityStreakReport

Productivity streak report

ProductivitySummaryReport

Productivity summary report

ProductivityVelocityReport

Productivity velocity report

SessionSummary

Session summary for display after run loop

StreakInfo

Streak tracking information

TaskEstimationPoint

Single task estimation data point.

VelocityMetrics

Velocity metrics for a given time period

Functions

build_estimation_report

Build an estimation report from tasks

build_streak_report

Build a streak report

build_summary_report

Build a summary report

build_velocity_report

Build a velocity report

calculate_estimation_metrics

Calculate estimation accuracy metrics from completed tasks. Only includes tasks that have both estimated_minutes and actual_minutes set.

calculate_velocity

Calculate velocity metrics for the given number of days.

date_key_add_days

Return date_key offset by delta_days.

format_date_key

Format a time::Date as a date key (YYYY-MM-DD).

format_duration

Format a duration in seconds to a human-readable string

load_productivity_stats

Load productivity stats from cache directory

mark_milestone_celebrated

Mark a milestone as celebrated

next_milestone

Get the next milestone threshold

parse_date_key

Parse a date key (YYYY-MM-DD) into a time::Date.

previous_date_key

Return the previous day’s date key.

print_estimation_report_text

Print estimation report in text format

print_streak_report_text

Print streak report in text format

print_summary_report_text

Print summary report in text format

print_velocity_report_text

Print velocity report in text format

record_task_completion

Record a task completion and update stats

record_task_completion_by_id

Record a task completion by ID and title (for cases where Task isn’t available)

save_productivity_stats

Save productivity stats to cache directory

update_streak

Update streak based on completion date