[Gerrrt]

Closes #367.

check_docs.py matched counted claims as digits or as words, and NUMBER_WORDS stopped at twenty. The comment explained the cap as convenience — "Twenty is comfortably above any count here … it is not a claim about the ceiling" — which was true when written and quietly stopped being true.

On 2026-09-07 observability.md read "Coverage is forty-five rules of 67" and two rules were added that day. The digit was caught both times. The word was not, and I corrected it by hand twice. The check exists to prevent exactly that, and the defect was living inside it.

Two changes, and the second matters more

Words are generated through ninety-nine rather than typed — ones, teens, tens and hyphenated compounds. So forty-five and fifty-one now parse:

docs/observability.md:431 claims forty-nine unit-tested rules; the repository has 50

Previously that line was silently skipped.

The ceiling is asserted rather than assumed. Each claim pattern is re-run with the number token swapped for the words this table cannot read — hundred, thousand, dozen and friends — and a match is reported:

docs/observability.md:431 states unit-tested rules as a number this check
cannot read ('Coverage is a hundred rules'). Counts above ninety-nine must be
written in digits, or NUMBER_WORDS needs extending — an unreadable count is an
unchecked one

Extending the table alone would only have moved the silence. This is what makes the ceiling a rule rather than a hope.

The unparseable pattern carries an optional leading word, because these always appear with a determiner or multiplier in prose — "a hundred", "two hundred" — and without it the article sits where the claim pattern's whitespace cannot span it. That was the first version's bug, found by testing the assertion rather than assuming it fired.

A correction, in the second commit

The first commit claimed check_docs "still runs in well under a second". I had not measured it. Measured:

main (20 words)	1.57s
flat 99-word table, unconditional scan	7.53s
+ ceiling scan gated per file	5.54s
+ structured alternation (36 branches)	2.23s

A 4.8× regression on something that runs in make validate and CI. Fixed by expressing the compounds as structure — tens, optionally hyphen ones — rather than flattening them, and by gating the ceiling scan on one search per file with the swapped patterns lru_cached.

2.23s for five times the vocabulary plus an assertion main does not have is a fair trade. 7.53s was not, and asserting it was fast without running it was the same kind of unchecked claim #363 exists to catch.

Both assertions re-verified after the rewrite. make validate passes.

🤖 Generated with Claude Code