ADR-007. A measured number is derived, never typed

Status: accepted, 6 September 2026. Still in force.

Context

This repository’s thesis is that you measure instead of assuming. Its own documents did not follow it.

The README announced 366 unit tests and 46 mutations. Measured at the same instant: 420 tests and 73 mutations. A commit message announced 373 for 376. A counter read only instance.v1 and announced “25 modules written out of 30 planned” above a list of 46 lines, and the control that exists to refuse a stale counter declared it conformant, because it compared the block to what the script produced, and the script produced the wrong number.

Then the rule was applied to the README alone, and an audit of 0.3.0 found eight false counters elsewhere in docs/: “41 Day-2 candidates” where the measurement says 40, “40 AUTO” where it says 39, “out of 46 modules” where the collection carries 50, “575 unit tests” and “49 unit tests” frozen on the day the sentence was written.

Two scripts carried the same table of these findings in their docstrings, with different numbers in each: 595/158 in one, 577/151 in the other. Neither was wrong the day it was written.

Added 8 September 2026, and it corrects nothing above: it records the same failure reaching the mechanism from a side the record did not describe. The block was regenerated from a source that no longer measured the repository. A unit test ran generate --module instance_server_info and let its report land in build/reports, where a full generation writes its own; the file reads the same and says something else. The README then published “23 modules written out of 52 planned”, and readme:check declared it conformant, for the same reason as in 2026-09-06: it compares the block to what the script produces, and the script was reading the poisoned file. The writer also carried no dependency on the measurement it published, while the checker did.

Also 8 September 2026, and this one the control could not see at all. The same README carried, fourteen lines below a derived block announcing 6 jobs, a hand-written table row reading “four jobs, plus a weekly trigger”. Two counts of the same thing, contradicting each other in one file. The control looked for digits, and this counter was spelled out in letters; docs/scorecard.md and the README both said “four workflow scanners” where mise run security runs three. Alongside them, two claims that are not numbers at all and that nothing compares to anything: mise run check described as “what a pull request has to pass”, when CI runs several jobs and check is what one of them replays; and a galaxy.yml comment stating that the documentation site was not published yet, months after it went online. Both had been true the day they were written.

Decision

Every measured number in a published document lives inside a derived block, written by scripts/readme_counters.py and refused by mise run readme:check when it no longer matches the measurement. scripts/chiffres.py refuses a measured counter written outside such a block, in every watched document and not only the README.

A derived block must be computable offline. A number that depends on a run, what a real target actually played, does not go in one; mise run coverage:example publishes it separately, and says “no run recorded” rather than “0 %” when there is none.

Numbers about the past, meaning what a document used to say, what an audit found, how many defects a first fuzzing pass turned up, go in a decision record, which carries its date. mise run histoire refuses them in a code comment.

Consequences

Three places may hold a number, and each says something different: an assertion, which goes red when the fact changes; a derived block, regenerated from the measurement; a decision record, which is dated and never updated. A sentence in a comment is none of the three.

Regenerating a derived block without reading its diff cancels the whole mechanism, in exactly the way regenerating a golden without reading its diff does.

What this record does not decide

Whether the measured thing is worth measuring. That is the report’s business, and ADR-002 names its denominator.