0009 — A done roadmap item stays, ticked, until its epic is done; the epic leaves whole
Status: accepted (supersedes 0004 on when an item leaves the file; the rest of 0004 stands) Date: 2026-11-15 Story: stories/040-a-roadmap-epic-ticks-its-items-as-they-close-and.md
Context
ADR 0004 took an item out of ROADMAP.md in the release that closed its
issue, so the file would not fill with history as story 009's had. In
use that removes what a reader of an epic under way wants most: how far
along it is. An epic of nine items with seven done reads as an epic of
two, and the changelog gets a ### Roadmap line per item, none of which
says what the epic delivered. The workaround in this repo was to leave
finished items' issues open, which makes the forge wrong instead.
The history 0004 objected to is a problem only once it is all history.
Options
| Option | Complexity | Testability | Domain clarity | Operational risk |
|---|---|---|---|---|
| A. Keep 0004: an item leaves when its issue closes | none | as today | the file shows only what is left, not progress | issues are held open to keep an epic readable |
| B. Tick done items and keep them for good | less than today: no archive | text | the file is a plan and a history | the file fills with history, 0004's complaint |
| C. Tick a done item while its epic has an open one; remove the epic whole when it has none, leaving one changelog line | archive works per epic; a tick becomes legal | text transforms, the forge behind the existing fake | an epic is the unit that is delivered and the unit that leaves | an epic that is never finished keeps its ticks; that is a true reading of it |
Decision
C. An item is - [ ] #N text while its issue is open and
- [x] #N text once it is closed; a bare - #N text still reads as
open. tp roadmap check reports a tick that disagrees with the forge.
tp roadmap archive and the release tick the closed items, and remove
an epic, heading, description and items, only when every item in it is
closed. A removed epic leaves one line under the version's
### Roadmap: its name and the first sentence of its description. An
epic with no items is not finished and stays.
Consequences
Easier: an epic shows its progress; a closed issue can be closed when it is done; the changelog says what was delivered, once.
Harder: the changelog no longer lists the items an epic was made of;
they are on the forge, closed. A changes/<n>.roadmap.md fragment now
holds an epic's line and is named for the epic's first item only to
give the file a name, so the release renders it without #n; a
fragment written by the old archive and not yet released loses its
#n in the changelog. An epic's description now has a reader outside
the file, so its first sentence should say what the epic delivers.