WAYS OF WORKING · DEMO 06 NINO CHAVEZ
Some load-bearing facts are invisible to search: the code compiles, the types pass, and the behavior is still wrong. This is the file that holds them — and the machinery that keeps the file honest.
Invariant #10 · shipped twice before it was written down
A direct .from('auth.users') silently returns nothing — no error, no throw, just an empty result. Invisible to the typechecker. Once it zeroed every captain email app-wide.
→ or scroll to advance · ← to go back
02 THE PROBLEM
Search answers "where is X?" It cannot answer "does X matter?" — and the costliest facts in a codebase are exactly the ones where existence and meaning diverge. The registry's own opening taxonomy:
Looks alive, is dead
A column that is written but never read. Every grep finds it; nothing consumes it. Agents keep it in sync with reality forever, for nothing.
Looks meaningful, isn't
A flag whose two values are indistinguishable to the runtime. Code branches on it; both branches behave the same.
Looks safe, is prod
An environment where "local" silently means "production." On this project: dev writes an isolated database — but every script, build, and un-overridden machine still writes prod.
Each of these makes an agent — or a human — confidently wrong. The code compiles. The tests that exist pass. The damage is quiet.
03 CASE STUDY
Invariant #10, quoted from the registry: the platform's auth schema isn't exposed to the query layer, so a direct query resolves against a table that doesn't exist — and returns an empty result instead of an error.
First shipping
The captains service queried it directly — and zeroed every captain email app-wide. No exception, no failed request. Just empty data, everywhere.
Second shipping
Months apart, the retention service made the same move — and silently fell through to a weaker fallback path. Same landmine, different crater.
Why twice
Because nothing could catch it: invisible to the typechecker, no runtime throw, and the first fix lived only in one file's history. Knowledge that lives in a diff is knowledge the next session doesn't have.
The second shipping is the argument for the registry: a lesson that isn't written somewhere durable will be re-learned at full price.
04 THE MECHANISM
One file. One line per landmine in an index read at session start; a detailed entry read before touching the named subsystem. The economics are written into the file's own header:
"Re-deriving these facts from source costs context budget every session — a grep returns 60 lines of matches you then read 300 lines of source to interpret, to extract 4 facts. An entry here is the conclusion, pre-paid once. [...] this registry is the only artifact that lets session N+1 spend three lines of context where session N spent three hundred." docs/INVARIANTS.md, verbatim
This is the same token-economics argument as demo 04, applied to knowledge instead of behavior: an agent's context window is a budget, and re-derivation is the most expensive way to spend it. Topology stays out — search finds where things are just fine. The registry holds only what search gets wrong.
05 THE SPLIT
The narrative why
The registry itself: what the landmine is, why it's dangerous, what it cost. Prose, amendable, human-written.
The immutable why-we-decided
Architecture decision records. Frozen at decision time — the registry cites them, never restates them.
The generated currently-true
A derived status page: each checkable invariant reported COMPLIANT or NON-COMPLIANT, with evidence and the commit it was checked at. Never hand-edited.
| inv-auth-guard-build-skip | [OK] COMPLIANT | INVARIANT #2 — auth guards in hooks.server.ts must short-circuit on `building` before auth logic, or the prerender crawler bakes a 303 that breaks POSTs at runtime. |
the check patterns live only in the derive catalog — never duplicated into prose, so they can't drift apart
06 ENFORCEMENT
Mechanically-checkable invariants are declared once in a catalog. A derive run generates the status page from it — and the same catalog runs as a CI test, so breaking an invariant fails the build immediately, not at the next manual audit. That's demo 03's Level 3 applied to knowledge.
And then it goes one turtle deeper. A meta-test guards the registry itself — its docstring, verbatim:
"The registry must be honest about itself. [The registry] claims enforcement [...] if a catalog entry is renamed/deleted or a referenced test is removed, the doc keeps asserting enforcement that no longer exists. That is the one way the registry can still lie. This meta-guard closes it: it is the registry-about-the-registry." invariants-registry-integrity.test.ts, verbatim
The same discipline pinned demo 05's autonomy gate — invariant #13 asserts the gate's behavior per subtype, so a refactor can't silently widen what an agent is allowed to build.
07 IN PRACTICE
The trigger is discovery
When a session steps on a new landmine, adding the entry is part of the fix — not a documentation chore for later. The file has been amended thirty times; it grows at the speed mistakes are made.
Entries get amended, not stale
When the dev environment split off its own database, the "local means prod" entry was amended the same day — the fact changed shape, so the registry did. An entry that no longer matches reality is worse than no entry.
Trust is tiered
Test-backed entries are trusted without re-verifying — that's the point of enforcement. Prose-only entries are marked verified-against a commit, and re-confirmed against current source before anything relies on them.
08 HONEST LIMITS
Only the mechanical subset is law
The CI catalog covers what a check can express. The rest is prose — durable, cited, but ultimately advisory. A rule that can't be checked is a rule that can be skipped under pressure.
It lags uncommitted work
The registry describes the repo as of its last amendment. Mid-flight changes can contradict it — which is why entries carry the commit they were verified against, and why "confirm the cited artifacts" is part of the reading protocol.
It runs on discipline
Nothing forces a session to add the landmine it just discovered. The habit is held up by the project's standing instructions — prose again, one level up. Turtles eventually end at a human keeping the habit.
09 YOUR VERSION OF THIS
If you never touch code
Every team has landmines — the report that's "current" but hand-edited, the field two systems interpret differently. Keep one page of them, one line each, and read it before touching anything named on it.
If you're technical
Start the file the second time something ships broken for the same reason. Separate the why (prose) from the currently-true (derived) — and never hand-edit the derived part.
If you build systems
Make the checkable subset a CI test from the same declaration the docs are generated from. Then guard the guard: a meta-test that fails when the registry claims enforcement that no longer exists.