decisions - CyrilB1531/lodestar GitHub Wiki

Architecture decision records — index

Seven records, one per axis of the project's trajectory: what it targets, what it may read, how it is laid out, what it writes rather than delegates, what proves it, which reference each stemmer follows, and where it knowingly differs from that reference. One row per file. The status and date columns are copied from each file's own **Status:** … · **Date:** … line — correct the record to correct this table, not the other way around.

A record states an axis. A tool, a numerical mechanism or a shape the code already shows is not an axis, and does not earn a record: it belongs in the tool's own documentation, in the XML comment on the member, in ../guides/performance.md when it is a measurement, or in ../equivalence.md when it is a divergence. That rule is what #1103 applied.

index.yaml is the mechanical layer beneath the table. Each record declares supersedes, amends and applies in its own frontmatter; tools/regen_adr_index.py reverses those edges, because an immutable record cannot name the decision that later amended it, and tools/check_adr_index_sync.py refuses any drift. All seven lists are empty today: an amendment to one of these records is a new record, which is what immutability means here — a record is never edited, and may only be deleted, as tools/check_adr_immutable.py enforces.

#	Title	Status	Date	Relationships
`0001`	The foundations: target frameworks, comparison unit, persistence and versioning	accepted	2026-09-20	—
`0002`	Provenance and the allowed references	accepted	2026-09-20	—
`0003`	The package layout: tiers, boundaries and edges	accepted	2026-09-20	—
`0004`	What is written here and what is delegated	accepted	2026-09-20	—
`0005`	The proof standard and the oracle each family is frozen from	accepted	2026-09-20	—
`0006`	The stemmers' references	accepted	2026-09-20	—
`0007`	The deliberate divergences	accepted	2026-09-20	—

What `accepted` means here

All seven carry accepted. None has been rejected or withdrawn — a status this table would otherwise need a second word for.

The numbering restarted at 0001

These seven replace the 147 records of the first numbering, written between 2026-08-01 and 2026-09-18 and deleted on 2026-09-20. A number below therefore names a different record from the one it named before that date: 0003 was Code provenance and license in the first numbering and is The package layout in this one. Read an old citation — in CHANGELOG.md, in docs/superpowers/, or in a commit message — against the tree it was written in:

git show 53af23c2:docs/decisions/0072-omega-is-an-input-not-a-seed.md

docs/decisions/.numbering-epoch carries the epoch this directory numbers in, and .next-adr skips any checkout or ref declaring another one, so a branch opened before the restart cannot push the next number back into the 0148 range.

What each record absorbed

The first numbering's 75 axis records were merged into these seven; its other 72 stated a mechanism and were deleted, their content moved to the tool, the guide or the equivalence row that carries it. Each record's own tables name the first-numbering record every case came from.