0004 — Roadmap items are issues labelled roadmap; epics are named, not numbered

Status: accepted (retires the numbering of story 009) Date: 2026-10-13 Story: stories/017-roadmap-items-are-issues.md

Context

Story 009 gave ROADMAP.md legal numbering with one hard rule: a cited number never moves. Shipped items therefore stay in the file, ticked and stamped, new items squeeze in with letters (1.6a), and the archive step that would sweep done items out cannot run without breaking the numbering. Three months on, two thirds of this repo's roadmap is history and an epic could not be placed where it belonged.

A roadmap number is a position dressed as a name. The names that mean something are already on the forge: issue numbers are sequential and permanent, and labels say what an issue is. A roadmap item may inspire several stories, and it is done only when all of them are; that is a relationship between issues, not a property of a line in a file.

Options

Option	Complexity	Testability	Domain clarity	Operational risk
A. Keep frozen numbers; shipped items stay on the roadmap	none	as today	one number means a position and a name	the roadmap fills with history; archive is impossible; insertions need letters
B. Provisional numbers, renumbered freely; shipped items leave at release	remove the frozen logic; add the move to the release	text transforms	a number is a position only, so citing one is nearly meaningless	numbers quoted in discussion go stale at every renumber
C. Items are forge issues labelled roadmap; epics named; the file is a view; done means the issue is closed, then archived to the changelog	tp roadmap talks to the forge; labels must exist; renumber goes	format is pure text; the forge part behind the existing fake forge	an item has one permanent name, its issue; a story cites it; epics are what they are called	the lint needs the forge and a token, so offline it checks format only

Decision

C. ROADMAP.md holds named epics in any order, each a list of - #N text lines for open issues labelled roadmap. Capture is one command that files the issue and writes the line. Stories cite their roadmap item in the story file; a roadmap item is done when its stories are all shipped and the human closes it, which the release prepare step offers to do. Closed items leave the roadmap in the release commit that names the version — the only commit at code level 1 that may carry it — and land in CHANGELOG.md under that version. A gitignored in-flight file carries what the tag run must do afterwards without a commit: close the issues with the release link, tidy the story branch.

Consequences

Easier: the roadmap reads as a plan and stays short. An idea is captured in one command. Nothing is ever renumbered; tp roadmap check becomes a lint of format plus the forge's truth. The changelog's per-version ### Roadmap list is the record of what each release finished.

Harder: tp roadmap depends on the forge and a token for everything but the format, and on two labels existing in every repo. Old stories and issues that quote roadmap numbers (3.5) no longer resolve against the file. Repos on story 009's rules migrate by hand, once.