Repository navigation
Description
What the file says it is, and what it is
docs/roadmap.md opens: "This file is the shape of the work — what is outstanding, and why it is in this order. Whether a thing is started, blocked or done is on its issue. Two places holding the same checkbox is how a checkbox stops being true."
It is 2,791 lines. Everything still to buy carries eleven dated paragraphs — 2026-09-11, 09-13 twice, 09-17 twice, 09-18, 09-19 twice, 09-20 — narrating each purchase, arrival and fit, before the table they describe. The Infrastructure entry for #92 runs to some sixty lines and includes the wrong-account bug, the .part fragments and the zsh glob. The #102 entry is longer. Every one of those sentences was true and worth writing on the day; together they are the journal the header says the issues are for, kept in the one file that promised not to be one.
Two costs, both already paid once:
- Drift. docs(roadmap): six sentences the last week made false, and three residuals given their issue numbers #536 fixed "six sentences the last week made false" in this file; docs(roadmap): smaug is built and the pool is not #487 and docs/roadmap.md still says smaug is unconfigured and its firewall rules unwritten #486 fixed more the week before. Dated narrative goes stale by construction, and
check_docs.pycan count claims but cannot read a paragraph. - Legibility. A reader who wants the shape of the work — the header's promise — reads past a month of purchase history to find it. The milestones on GitHub now carry that shape (seven, each with a close condition), which the file predates.
What to decide
- What the file is for, in one sentence that the header can keep: the ordered shape of open work, or the estate's changelog. Not both.
- Where the history goes if it leaves: a
docs/changelog.mdin the same voice, the ADRs' own dated notes (many of these paragraphs are amendments in all but location), or the closed issues, which already hold most of it verbatim. - What a roadmap entry is allowed to contain once the file is the shape: a link, the gate, the order, and why — and the rule that a Done entry moves rather than accretes.
- Whether the Everything still to buy section survives at all now that the buy table is two rows and
check_buy_listties it to the README.
Done when
The header's sentence is true of the file below it, the history it carried is findable somewhere with a date, and the file is short enough that the next drift fix is one line rather than six.
Activity
docs(roadmap): the file is the shape of the open work again, and its …
Merge origin/main into #577: the new decisions take their place in th…
Merge origin/main into #577: the UPS ADR is 0049, here too
Merge pull request #584 from Gerrrt/gerrrt/roadmap-purpose-history-47…
Merge origin/main into the remote-path branch: the roadmap is a diffe…