Name every behaviour in a ledger, and the test that proves it #67

Parent

#21

What to build

A ledger that names every behaviour this repository guarantees, and for each one the test that fails when it stops being true.

Today a behaviour can lose its proof without anything saying so. The coverage ratchet notices a line that stops running, but not a test file that was renamed, emptied or deleted while the code it covered stayed in place, and nothing connects a sentence in the documentation to the test that makes it true.

• docs/requirements.md holds one row per behaviour: a greppable id, one sentence saying what a contributor or a consumer can rely on, and the test file that proves it.
• Ids are cited from the code and tests that implement them, so a comment naming an id resolves to a row rather than to nothing.
• A test holds the ledger honest: every row parses; every named file exists, is a test file and contains at least one test; ids are unique; the document states how many rows it holds and the count matches; and every id cited anywhere in the tree resolves to a row.
• The first rows are what the repository already enforces: the ADR contract, the link contract, the manifest gate, the boundary gate, the pull request title check, the package-contents check, the em-dash ban, the test harness guards and the coverage ratchet. The compiler's behaviours join as they land.

This is the companion of the rule ledger in #29, and deliberately not the same thing: that one lists the rules a tool enforces, this one lists the behaviours a person depends on.

Acceptance criteria

• Renaming a test file that a row names fails the ledger test, and the failure names the row.
• Emptying a test file that a row names fails it as well, so an existence check alone cannot pass.
• Citing an id that no row carries fails it.
• The row count the document states and the number of rows it holds must agree.
• Every behaviour the repository enforces today has a row.

Blocked by

None (can start immediately).