Historical delivery metrics (M9)

Milestone 9 adds a metrics collection and structuring layer that derives delivery metrics from planning task front matter and writes normalized outputs under .a2c/metrics/.

Definitions

Metric	Definition (M9 first pass)
Lead time	completed_at - created_at when both are known
Cycle time	completed_at - work_started_at when both are known
Throughput	Number of tasks completed per calendar week bucket

Timestamp assumptions

• completed_at uses an explicit front matter field when set; otherwise updated_at when status is done.
• work_started_at uses created_at when set; for in_progress tasks without created_at, updated_at is used as a coarse proxy.
• Git history is not used in M9 (source: planning_only on every record).

Task front matter fields used by collection:

• status, created_at, updated_at, optional completed_at
• optional sprint_id, epic_id, tags

CLI usage

# Collect metrics from planning/tasks/
a2c metrics collect

# Show a human-readable summary
a2c metrics show

# Optional filters (M9 minimal)
a2c metrics show --sprint sprint-metrics
a2c metrics show --epic epic-metrics
a2c metrics show --tag backend

Example collect output:

Collected metrics for 4 tasks; 2 completed; 1 sprints aggregated.

Storage layout

Under .a2c/metrics/:

File	Contents
tasks.ndjson	One JSON object per line — per-task metrics
aggregates.ndjson	Sprint and weekly aggregate records
meta.yaml	Collection timestamp and counts

Example tasks.ndjson record

{
  "task_id": "task-metrics-done-b",
  "epic_id": "epic-metrics",
  "sprint_id": "sprint-metrics",
  "tags": ["metrics"],
  "created_at": "2026-06-03T12:00:00Z",
  "work_started_at": "2026-06-03T12:00:00Z",
  "completed_at": "2026-06-10T12:00:00Z",
  "lead_time_seconds": 604800,
  "cycle_time_seconds": 604800,
  "status_at_collection": "done",
  "source": "planning_only"
}

Example aggregates.ndjson record

{
  "group_kind": "sprint",
  "group_id": "sprint-metrics",
  "completed_tasks_count": 2,
  "throughput": 2.0,
  "avg_cycle_time_seconds": 619200.0,
  "median_cycle_time_seconds": 619200.0,
  "avg_lead_time_seconds": 619200.0,
  "median_lead_time_seconds": 619200.0
}

Downstream tools (including AI workflows) should read these structured files directly rather than scraping CLI output.

Limitations (M9)

• Planning-only timestamps; no git augmentation
• Coarse work_started_at proxy when status history is unavailable
• Weekly buckets use Monday–Sunday ISO-style windows from completed_at
• a2c metrics show prints summaries only; analytics dashboards are out of scope

Querying metrics (M10)

Milestone 10 adds a2c metrics query on top of collected .a2c/metrics/ files. Run a2c metrics collect first (or pass --collect on the query command).

Supported combinations

--metric	Meaning	Typical --group-by
throughput	Completed task count per group	sprint, week, month, epic
cycle-time	Avg/median/min/max cycle time (seconds)	sprint, week, month, epic
lead-time	Avg/median/min/max lead time (seconds)	sprint, week, month, epic

All listed groupings work with each metric. Filters are optional:

• --since / --until — ISO dates applied to completed_at
• --tag, --epic, --sprint — narrow the task set before aggregation

Output formats

--format	Behavior
table (default)	Human-readable columns plus a simple # trend bar
csv	Header row and one CSV row per group (stdout export)
json	JSON object with metric, group_by, and rows

Example commands

# Overall weekly throughput
a2c metrics collect
a2c metrics query --metric throughput --group-by week

# Per-sprint cycle time table
a2c metrics query --metric cycle-time --group-by sprint --format table

# Tag-filtered lead time
a2c metrics query --metric lead-time --group-by week --tag backend

# Export for spreadsheets or BI tools
a2c metrics query --metric cycle-time --group-by sprint --format csv > sprint_cycle_times.csv

Sample table output:

Metrics query: throughput grouped by sprint

group            count            avg              median           min              max              trend
sprint-metrics   2                2                2                2                2                ##

M10 scope

• Query, summarization, and lightweight terminal insight only
• No plotting libraries, dashboards, or IDE visualizations (future milestones)

Related

• cli.md — full command reference
• task-authoring.md — task intake workflow
• M9 task spec: tests/fixtures/workflows/task_m9_historical_delivery_metrics.body.md