018. Roadmap format: GitHub Milestones plus Project Horizon field

Date: 2026-07-18
Status: Accepted

Decision

In the context of needing an operator-facing roadmap that shows what we are driving at now versus next versus later, groups open Features/Stories into deliverable milestones, and is backed by explicit inter-issue dependencies (story #222, Sprint 4 retro action A8),
facing a choice between GitHub-native mechanisms and a generated or hand-maintained document on the Starlight site or in the LikeC4 model, where cheap-to-maintain and close-to-the-backlog are the deciding criteria,
we decided for GitHub as the system of record, in three native pieces with no build artifact:
- Named Milestones as durable deliverable units (e.g. “Query API GA”, “QA env live”); open milestones are the roadmap.
- A Project single-select field Horizon = Now / Next / Later on Project #1 (rag-sample planning) that buckets issues into the three-state view. The default board groups by Horizon (the now/next/later glance); a second saved view groups by Milestone (the deliverable breakdown).
- Native issue dependencies (blocked-by / blocking) as the first-class edges, surfaced as a “Blocked by” badge on each card so a horizon ordering that violates a dependency is visible.
and neglected
- Three Milestones literally named Now/Next/Later (horizons are the milestones) — cheapest, but collapses “what” and “when” onto one axis and loses the named deliverable milestones the dashboard row promises
- Mermaid Gantt/timeline page on the Starlight site — implies start/end dates the backlog does not carry (invented dates rot), and drifts unless generated, where generation adds a build+refresh cost that duplicates issue data
- A LikeC4 roadmap view — an architecture-modeling tool used off-label; dependencies would be modeled separately from the issues, guaranteeing drift
- A hand-maintained roadmap doc — highest drift of all
to achieve a roadmap whose data lives on the issues themselves: no sync step, no generated file to regenerate, and dependencies captured once as GitHub relationships that feed both the tooling and any future visual,
accepting that the view depends on GitHub Projects v2 (already the ticketing system per org ADR 005) and that the Horizon field is set per issue by hand, and that there is no dated timeline layout until the backlog carries dates.

Consequences

A generated Mermaid dependency DAG committed to the Starlight site (via a make roadmap target querying gh) is deferred; revisit only if the native Project view proves insufficient after the edges are populated.
No change to the app repo; this is a planning-repo tooling decision that builds on org ADR 005 (GitHub Issues and Projects).