Engineering note · culture
Ten guards, ten scars
Our platform test suite is — guards, every one of which fails the build, and every one of which exists because something specific went wrong. Here is the incident behind each — because a guard without its scar is just a lint rule.
One design rule first, because it explains all ten: every guard runs with no database, no browser, no server and no keys. A guard that needs infrastructure is a guard that gets skipped the day the infrastructure is down — which is disproportionately the day you needed it. Anything that would normally require a live system takes its dependency as a parameter, so the contract can be proved against a stub.
01The legacy-name ban
The old platform's name must not appear anywhere in the new repo — not in a path, not in a comment, checked case-insensitively. (The guard's own banned-word pattern is written split in half so the guard passes its own scan.)
Scar: a rebuild that keeps typing its predecessor's name never finishes leaving it. Copy-pasted snippets carry old assumptions in through the naming, one identifier at a time.
02The parity ledger
Each rebuilt OS carries a ledger of every legacy feature: done, pending, or dropped. The guard rejects a wave marked DONE that still contains pending rows, a feature marked dropped without the founder's sign-off recorded beside it, and a row marked done whose own text admits otherwise. It also prints the open questions, so an automated session sees what is waiting on a human instead of quietly deciding it.
Scar: the rebuild ledger is the document most worth lying to yourself in. The guard makes the two available lies mechanical instead of a matter of discipline.
03Shell integrity
An OS owns its configuration and its data calls. It does not own the chrome. If an OS needs new shell behaviour, the behaviour goes into the shared shell behind configuration — where every OS gets it — and the guard fails any OS that grows shell-shaped code of its own.
Scar: the legacy platform died of exactly this. Per-OS pages that began as configuration grew into forks of the shell — nineteen dashboards, nineteen copies of the same modal code, and a fix that reached one of them.
04The driver boundary
The shared data layer stays a registry, and every mutation verb stays namespaced to its OS. The full story has its own note.
Scar: on a flat verb table, the second OS to define stock-save silently overwrites the first, both lanes' tests pass, and the bug ships as one vertical's booking mutating another's stock.
05Migration replay
Every migration lives under a namespace, numbers never repeat within one, a migration only touches tables its namespace owns, and the whole history replays from zero. Details in One database, nineteen worlds.
Scar: an ownerless migration file once created two platform tables it had no business creating, and the applied ledger once carried the same number twice — one file, applied as two versions.
06Job heartbeats
A scheduled job cannot finish — in success or in failure — without writing down that it ran. The job runner takes its heartbeat writer as a parameter, so the property is proved against a stub on every test run, not only when a database happens to be up.
Scar: a data-retention cron on the legacy platform failed silently for months. The heartbeat property is worth more than any single job it protects.
07Push degradation
A notification system has three ways of going quietly wrong that all look like success from the caller's side: nobody configured the keys, nobody subscribed, and the one device that subscribed has since uninstalled. The guard proves every result shape maps to a sentence an operator can act on, and that the unconfigured path never pretends otherwise — no keys required to prove it.
Scar: a desk pressed “assign” and was told the crew had been told. They had not.
08Companion-app i18n
The crews' phone app deliberately does not load the desktop shell — so it owns its own strings, and nothing structural stops it drifting back to English one screen at a time. The guard proves three things statically: every user-facing phrase goes through the translation function, every key has a French entry, and the dictionary carries no key the app never asks for — because a dictionary full of dead entries is one nobody trusts enough to prune.
Scar: the bilingual row on that app sat at amber for a whole build wave, drifting screen by screen, precisely because no machine was watching.
09Tour coverage
Every OS declares a guided tour, every step has a readable title and body, and every step's selector matches something that exists. The founder's standing rule: a UI change is not finished until the tour it affects updates in the same commit — and the second half of that is exactly what a written rule cannot enforce, so a machine does.
Scar: rename a module and the nav still works, every verifier still passes, and the tour quietly points at nothing. Nobody finds out until a new operator's first day — the one day it had to work.
10The clearance gate
A regulated submission flow has two refusals that mean different things — “switched off here” and “does not exist” — and normally you would need two differently-configured servers to see both. So the decision is a pure function, and the guard checks its whole truth table on every test run. The claim that matters most is the negative one: there is no configuration under which it fakes a success.
Scar: a clearance an operator believes was filed, and was not, is a vessel arriving without papers.
The pattern across all ten: the dangerous failures were never loud. They were the quiet ones that looked like success — the cron that said nothing, the push that resolved fine, the verb that overwrote cleanly, the tour that pointed at nothing. Guards exist to make quiet failures loud at build time, which is the cheapest place a failure will ever be.
Check what you can
The guard count loads from eng-facts.json with its probe date. Two of the guards' effects are visible from outside: this site's bilingual discipline (the EN/FR toggle above switches every string, scanned by the same kind of machinery), and the guided tours in any OS demo on the walkthrough.