tp roadmap

ROADMAP.md is the plan: named epics in any order, each a list of items, and every item an open issue on the release remote's forge labelled roadmap (story 017, ADR 0004). The forge is the truth about what exists and what is done; the file is the grouped view of it, and tp roadmap check keeps the two in step. tp check runs the same lint whenever ROADMAP.md exists.

Command	Does	Prints
`tp roadmap check`	lints the format, then every item against the forge	`ROADMAP.md:LINE: finding` per finding, exit 1; else the item count
`tp roadmap add TITLE... [--epic NAME]`	files an issue labelled `roadmap` (creating the label if the repo lacks it) and appends `- #N TITLE` to the epic, the last one by default	`#N url`, then the epic it went under
`tp roadmap archive`	moves every item whose issue is closed out of the file: at code level 0 into `CHANGELOG.md`'s `[Unreleased]` section, as a `### Roadmap` list; at level 1 and up into a fragment each, `changes/<n>.roadmap.md`, which the batch release gathers into the version's `### Roadmap` list (#142)	one line per item moved, naming where it went

Format

# Roadmap

## Release workflow

What the epic is about, in a sentence or two.

- #12 Custom step ordering
- #31 Deletes the merged story branch: once the tag is published,
  the local branch goes too.

## Secrets

An epic is a ## heading with a name; its items are the - #N text lines beneath it, the issue number first and free text after it, which may run on over indented lines. The text need not match the issue's title: the issue is the identity, the text is what the roadmap says about it. Nothing is numbered, ticked or stamped.

A story that serves a roadmap item says so with a **Roadmap:** #N line under its status; tp story issue carries it into the story's issue. One roadmap item may inspire several stories, and it is done only when they all are.

Lint

Rule	Finding
items are `- #N text`	`item has no issue`, `#N has no text`
items sit under a `##` heading	`#N is outside any epic`
nothing is numbered or ticked (story 009's format)	`numbered item`, `numbered heading`, `ticked item`
the issue exists on the forge	`#N does not exist on the forge`
the issue is labelled `roadmap`	`#N is not labelled roadmap`
the issue is open	`#N is done — run: tp roadmap archive`
every open `roadmap` issue is in the file	`uncaptured: #N title`, the first 5, then `... and N more uncaptured issues`

Without the forge (no token, offline) the format rules run and the rest is reported as skipped. tp check shows the same findings, with done and uncaptured items as warnings.

Done means closed

A roadmap item leaves the file when its issue is closed. tp roadmap archive does it on demand; tp release does it in the release commit, so the item lands under the version that finished it, and offers to close an open item whose stories have all shipped or ship in that release. At code level 1 and up the [Unreleased] section may hold nothing (the batch's CHANGELOG comes from fragments), so both write a changes/<n>.roadmap.md fragment instead, committed with the story that finished the item; the release renders the roadmap fragments as the version's ### Roadmap list, after the Keep a Changelog sections, and they bump nothing. See the release workflow.

Migrating from numbered roadmaps

A roadmap in story 009's format fails the format lint. Migrate once, by hand: ticked items go into the changelog under their stamped versions as ### Roadmap lists, each open item becomes an issue with tp roadmap add, and the epics keep their names and lose their numbers.