jschoubben
1b5308c9cc
First pass of a design review, done by reading documents against code and against a raised mesh rather than against each other. Every error below was invisible to a proofread. **Statuses were stale, and nothing checked them.** Ten to-be documents said `designed` while naming working, lab-proven code — several with a *What was built* or *Raised, and observed* section. Added a `status-vs-code` check: naming a file is a claim that the file implements this, so a document that points at one has stopped being merely designed. It failed on all ten before it passed, per the rule this folder sets for its own checks. **The bundle carries three images, not two.** 07 reasoned about which substrate services go in and overlooked that the control plane is in there too — it is what the substrate exists to start, and there is nothing to fetch it with yet. Counted, not deduced. **The bootstrap uses four shapes, not six.** It listed `file` and `directory`, which substrate-first-node.lock never asks for. The claim that mattered — nothing is blocked on the host — was true either way, which is why the wrong count survived. **The eight capabilities were documented nowhere.** Implemented in internal/profile/detectors.go and enumerated in no document, including the one about the host that detects them. A vocabulary modules write against, readable only by reading the code. Now written down, with the seat/graphical-session distinction that is wrong in both directions if collapsed. **MinIO swept out of the to-be layer** per 0028. The gate now fails on one thing left deliberately: ADR 0024 is `proposed` while two documents rest on it and the feature it decides is built and lab-proven. Accepting a decision is not mine to do.
51 lines
2.9 KiB
Markdown
51 lines
2.9 KiB
Markdown
# 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
|
|
```
|
|
|
|
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/` and `01-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](../../02-DECISIONS/0006-the-substrate-and-the-control-plane.md):
|
|
*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.
|