CANON.md + VOCAB.md + README.md. The entire governance of a software system in three files.
Five days into canonic-machine, and I kept solving the same problem.
Every new repository needed governance. Every time I set it up, I asked the same three questions: What does this scope believe? What do the words mean? How does someone use it? Three questions. Three files. The same three files. In every repo. Every time.
CANON.md — the declaration. VOCAB.md — the definitions. README.md — the instructions.
Today the pattern got a name. The Triad.
The Discovery
It happened across three repos simultaneously. Commit 61e5a79 in LEDGER. Commit 79bc277 in OS. Commit 09ca2c9 in PAPER. Three repositories, three commits, the same realization crystallizing in parallel: the minimum viable governance unit is exactly three files.
Not two. Not four. Three.
CANON.md tells you what the scope believes. Its axiom. Its constraints. The things that must be true for anything downstream to be valid. This is the constitution.
VOCAB.md tells you what the words mean. Every term defined. Every definition traceable. No ambiguity. When someone says “LEDGER,” this file tells you whether they mean a financial record, an append-only log, or a metaphor. In governed systems, metaphors kill.
README.md tells you how it works. Not philosophy. Not theory. Instructions. If you can’t run it from the README, it isn’t governed. It’s a memo.
Why Three Is Right
Two files and you have a declaration without a language, or a language without instructions. The system is ambiguous. Ambiguity in governance is not a feature — it’s a vulnerability. Ambiguity is where bad actors operate and honest mistakes hide.
Four files and you’re over-specifying. The fourth file is always a symptom of the first three being incomplete. If you need a fourth governance file, one of your first three is wrong.
Three is the minimum for closure. Like a three-legged stool. Like a syllogism. Like the three points that define a plane. Remove any leg and the stool falls. Add a fourth and you’ve built a chair — but a chair is furniture, not mathematics.
The Passport Analogy
Think of the Triad as a passport for code.
CANON.md is your identity. Who you are. What you believe. The photo page.
VOCAB.md is your language. Which words mean what. The issuing country’s alphabet. The shared vocabulary that makes the identity legible across borders.
README.md is your intent. Where are you going? What are you carrying? What do you plan to do when you arrive? The customs declaration.
Every scope carries its passport. Every downstream scope can read it. Every validator can check it. The governance is portable, legible, and minimal. Three files. No more. No less.
What This Enables
With the Triad in place, every new repository in canonic-machine is governed from the moment of creation. Not governed eventually. Not governed when someone gets around to it. Governed now. The first commit contains three files, and those three files are the governance.
Five days ago, I created CANON.md and called it a compiler insight. Today, the compiler has a grammar. Three files. Three questions. One pattern. Every scope. No exceptions.
Figures
| Context | Type | Data |
|---|---|---|
| post | flow-chain | nodes: CANON.md → VOCAB.md → README.md |
CANNON — Three files. Complete governance.