jochen
a28da1734b
ADR 0244 sorts the mesh's concepts into ten domains (ADR 0006's contexts carry over as domains), keeps machine and node as distinct words, and makes the glossary the authority with every retired word on its replacement's Not: line. To-be 49 draws the domains; the glossary is reorganised by them, its two contradictions removed and the missing words added. words.py now fails on a retired word in running prose and on a word defined twice, so the rule is enforced rather than believed; the 63 documents it failed on are reworded here, and research 034 is kept as the record of the words it studied.
5.5 KiB
Checks
python3 00-META/checks/records.py structure: links, citations, supersession, topics
python3 00-META/checks/index.py the reading order in 02-DECISIONS/README.md is current
python3 00-META/checks/index.py --write regenerate it
python3 00-META/checks/words.py the glossary's retired words are not used, and no word is defined twice
python3 00-META/checks/words.py --list tools the words the catalogue's copy must list
Non-zero exit on any problem, so it can be a gate rather than a report.
Why this exists. Until now nothing in this repository was verified by anything but reading,
which is how a superseded decision stayed live in the constitution for days and in
01-to-be/README.md alongside it. Both were found by a person looking. how-we-build §5 says
an unenforced rule is indistinguishable from a wrong one, and costs more, because people
believe it — this repository was carrying several.
Every check here failed on something real before it passed. A check that has never failed is indistinguishable from one that cannot.
| Check | Asserts | Found |
|---|---|---|
links |
every relative link resolves | — (run ad hoc during authoring; now permanent) |
rests-on |
decisions: and extends: name records that exist and are accepted |
the class behind both incidents |
live-citation |
a governing document citing a superseded record names its replacement in the same paragraph | 01-to-be/README.md citing ADR 0022 as live guidance |
supersession |
if A says it was superseded by B, B says it supersedes A | ADR 0012 never declared that it superseded 0011 |
numbering |
the number in the filename is the number in the heading | — |
topics |
every record names a topic the index knows | — |
| (index.py) | the written reading order matches what the records say | — |
status-vs-code |
a to-be document naming specific code is not still designed |
ten documents, several with a What was built section, describing lab-proven code |
What is deliberately not checked
02-DECISIONS/and01-RESEARCH/may cite superseded records freely. A decision record discusses history; research records what was observed. Flagging those would produce noise on correct documents, and a check that cries wolf gets suppressed — which costs more than not having it.03-DESIGN/00-as-is/may rest on a superseded record. It describes what runs, and what runs was built under whatever was decided at the time (ADR 0006: as-is describing a superseded decision is exactly what as-is is for).- Whether a citation's prose is still true. Only whether the record it points at is live. A document can cite an accepted record and describe it wrongly, and nothing here notices.
So "governing" means 00-META/ and 03-DESIGN/01-to-be/ — the documents that tell somebody
what to do.
Adding a check
State what incident it would have caught, and make it fail before you make it pass. A check whose failure has never been observed is a guess about its own correctness.
cycle.py
The development cycle, checked (ADR 0080):
a to-be design names a decision, an in-progress/implemented design names its owning code, a
located/fixed issue names its owner, a fixed/resolved issue says what fixed it, a graduated
research overview says what it became, and no two issue records share a number (issue 155 — the
number is how a record is cited, and main lags every open pull request, so two people reading it
allocate the same one). And a core issue — one opened from 2026-10-07 whose located-in names a core
repository — resolves only with replay: (an id in mesh-lab's replays register) or replay-none: saying
why none is possible (ADR 0237);
it failed on a resolved core issue carrying neither before it passed. python3 00-META/checks/cycle.py
words.py
One word per thing, checked (ADR 0244).
It reads the glossary's Not: lines (the retired words, each with its scope) and Identifier until
renamed lines, and fails on a retired word or a bare identifier in running prose — what is left once code,
quotations, struck-through text, link targets, comments and frontmatter are taken out — in 00-META/,
03-DESIGN/, AGENTS.md, README.md, and research and issues dated from 2026-10-07. Decision records are
never checked. It also fails when a glossary head word heads two entries or is also retired.
words-allowed.md names a document that could not be reworded at once, with a date, or
a graduated research effort kept as written. With MESH_CATALOG_DIR set it compares the catalogue's copy
of the tools' retired words (retired-words) with the glossary.
It failed on something real before it passed: 581 uses of retired words in 63 documents on its first run, besides the glossary itself and research 034 — "the host" for the node-engine in 30 designs, "control plane" in 10, the glossary's own entry for the tool runner — and two glossary contradictions (the "console", the deprecated broker's seat), fixed in the change that added it. Homonyms (plan, gate, tier, ask, store, record, check) are not checked by it: a word list cannot tell one sense from another, so they are reviewed.