Authority-Graded Repository Knowledge
- Version
- 0.1
- Status
- Open specification
- Author
- Codee3
- Licence to adopt
- None required
A repository records what a system does. It rarely records what may be relied on. This specification describes the minimum structure required for repository knowledge to be safely relied on by a person or an agent that was not present when it was written.
On status. Open specification, authored by Codee3. Not an industry standard. It is published so that a team can adopt it by hand, without buying anything and without adopting Codee3. Everything in sections one through seven is implementable with a text editor and a naming convention.
Four classes. One question each.
A class is a property a document declares about itself, not a folder it lives in. The same document, graded differently, has different standing — so the grading is the decision, and it is made once, by the author, in the header.
The same document, graded
---
Authority-Class: CANONICAL
Verified-At: 2026-07-02
Supersedes: queue-choice · 2025-11-14
---
# DECISIONS LEDGER
.ai/DECISIONS-LEDGER.md
Precedence
- CANONICALwins any conflict
- WITNESSyields to canonical
- ABSTRACTEDyields to canonical
- DERIVEDyields to canonical
All four definitions as continuous text
- CANONICAL
- A decision or constraint that binds. Other documents may describe it, index it or summarise it, but may not contradict it. Where a conflict exists between a CANONICAL document and any other class, the CANONICAL document wins. A CANONICAL document may not be derived from a summary, and may not be silently edited to mean something else — a change of meaning is a supersession event, with a record.
- WITNESS
- An observation of present reality, attributed and dated. WITNESS documents are how a knowledge layer stays connected to the system it describes. They do not bind future decisions; they report the current state and cite what they observed. A WITNESS document may not be treated as a decision. Observing that something is the case is not the same as deciding it should remain the case.
- DERIVED
- Navigation and summary. A DERIVED document exists to route a reader to the authoritative document, and must be reconstructible from the documents it points at. If a DERIVED document and its source disagree, the source is correct and the derived document is broken. A DERIVED document may never introduce a fact that exists nowhere else. The moment an index becomes the only place a constraint is written down, the hierarchy has inverted and the structure is no longer governable.
- ABSTRACTED
- Explanatory material scoped to one domain. ABSTRACTED documents carry the working detail a reader needs once routed to the right place. They sit below canon and may be revised freely, provided they do not contradict a CANONICAL document. An ABSTRACTED document may not quietly become the authority for a decision. If it starts constraining behaviour, that constraint belongs in a CANONICAL record.
Verified-At: making staleness visible
A document declares the date its content was last confirmed against reality.
The value of `Verified-At` is entirely in what it makes visible. Its honesty depends on the discipline of the people and agents maintaining it. A specification can require the field; it cannot make anyone tell the truth in it.
What it does
- A reader can see, without asking anyone, how old the last confirmation is.
- An agent can weight a document by the age of its confirmation rather than treating every file as equally current.
- A reviewer can find the documents nobody has looked at since a major change.
What it does not
- It does not prove the content is correct. A document verified yesterday can still be wrong.
- It does not prove the content still matches the source code. Nothing in this specification compares prose against an implementation.
- It does not update itself. A date that is maintained carelessly is worse than no date, because it converts an unknown into a false assurance.
Four laws, and the reason for each
Local-first truth
The governed knowledge lives in the repository, beside the code, under the same version control.
BecauseKnowledge held in an external service is governed by that service. It cannot be branched with a change, reviewed in the same pull request, or read by a tool that only has the working tree. Knowledge that cannot travel with the code will diverge from it.
No versioned successor names
No governed document may carry a version suffix — no `v2`, `mk2`, `FooV2`, `api-v2`. One timeless name per concept; evolution is recorded in history, not in the filename.
BecauseA version suffix declares a successor and forks truth. Once `architecture.md` and `architecture-v2.md` both exist, every reader must work out which one governs, and every reference becomes ambiguous. The knowledge layer owns change: the name stays, the content evolves, the history records what happened.
Index-first navigation
A reader enters through an index, reads the index, then drills into the one leaf they need. A domain is never bulk-read.
BecauseRetrieval quality degrades as the amount of loaded material grows, and irrelevant-but-similar material is actively misleading rather than merely wasteful. Routing through an index keeps the loaded set small and deliberate. This is a cost discipline and an accuracy discipline at the same time.
Root canon wins
Indexes and summaries are derived. Where a derived document conflicts with the canonical record, the canonical record is correct and the derived document is broken.
BecauseWithout a declared precedence order, conflicts are resolved by whichever document the reader happened to load first. A stated hierarchy makes conflict resolution deterministic and makes broken derivation detectable rather than merely confusing.
Eight properties, of which six can be checked by a script
The split matters more than the list. An invariant a machine can verify is a gate; an invariant that requires judgement is a review practice. Presenting both as though they were the same thing is how governance products end up overstating their reach.
Mechanically checkable · 6
- Every governed document declares its authority class
- A document with no declared class has no standing and must be treated as ungoverned.Checkable: the field is present and holds a recognised value.
- Every concept has exactly one timeless identity
- No two governed documents may claim to be the current record of the same concept, and no governed name may carry a version suffix.Checkable: scan governed names for version-suffix patterns.
- Every folder holding governed documents has an index
- A folder with documents and no index cannot be navigated index-first, so its contents are unreachable by the intended discipline.Checkable: presence of an index file per document-bearing folder.
- Structural ordering is unambiguous
- No two siblings may share an ordering prefix. Ambiguous order makes routing non-deterministic.Checkable: sibling prefixes are unique.
- Every reference to a governed fact resolves
- When a governed fact is renamed, no surviving mention of the retired name may remain. A reference that no longer resolves is a silent lie.Checkable: a registry declares each governed fact, its path and its rename history; surviving mentions of retired names are detectable.
- All agent surfaces route to one governed source
- Per-tool instruction files must redirect to the governed layer rather than each holding an independent copy.Checkable: each known instruction file contains a redirect to the governed root.
Requires judgement · 2
- Derived documents link upward and never redefine canon
- A derived document must be reconstructible from its sources.Partially checkable. Whether a summary faithfully represents its source is a judgement, not a scan.
- Supersession is recorded, not performed by deletion
- A replaced fact is marked superseded and retained with its successor named. Deleting it destroys the reasoning that produced the successor.Partially checkable. The presence of a record is checkable; its accuracy is not.
Provenance, standing, supersession and lineage
- Provenance
- Where a fact came from — the document, decision or observation it originates in. A fact with no provenance cannot be audited, only believed.
- Standing
- The current state of a fact: in force, contested, or superseded. Standing is what a reader actually needs and what an ungoverned repository never states.
- Supersession
- The formal replacement of a fact by a successor. The superseded fact is preserved and marked, with the successor named. Supersession is an event with a record, not an edit.
- Lineage
- The chain from a current fact back through its supersessions to its origin. Lineage is what a version suffix destroys: `api-v2.md` implies a predecessor without recording the relationship, the reason, or the date.
These four together are the difference between a folder of Markdown and a governable knowledge layer. None of them require tooling to adopt. All of them require discipline to maintain.
Why repository knowledge needs authority, not just storage or retrieval
Every repository already stores knowledge. It is in the README, in a /docs folder, in an architecture note somebody wrote during a migration, in four different agent instruction files, in a plan that was superseded but never deleted. Storage is not the missing piece.
Retrieval is not the missing piece either. A search engine — lexical, semantic, or an agent running grep — will find the text. What it returns is the text that most resembles the query. Resemblance is not standing. The most similar document to a question about the payment system may be a detailed specification for a payment provider the team explicitly rejected.
The missing piece is authority: a declared, machine-readable answer to the question may I rely on this? Without it, every reader — human or agent — has to reconstruct standing from circumstantial evidence: the filename, the folder, the git history, who they can ask. Humans do this badly and slowly. Agents, starting from an empty context window every session, cannot do it at all.
Authority is not correctness. A document can declare itself binding and be wrong. What declared authority provides is the ability to tell the difference between a document that claims to bind and a document that does not — and to detect, mechanically, when that claim has structurally broken.
What this specification does not attempt to solve
- Factual correctness
- Nothing here establishes that a document is true. Declared authority tells you what a document claims about its own standing, not whether the claim is warranted.
- Agreement between prose and source code
- This specification does not compare documentation against an implementation. A document can satisfy every invariant and describe a system that no longer exists.
- Runtime or production behaviour
- Nothing here observes a running system. Governed repository knowledge is not monitoring, testing, or a safety mechanism for production.
- Authoring the knowledge
- The specification describes the shape knowledge must take. It does not produce the knowledge. Somebody — a person, or an agent under supervision — still has to decide what is true and write it down.
- Making agents reason correctly
- A shared governed source removes one class of failure: reasoning from material whose standing is unknown. It does not make two agents reach the same conclusion, and it does not make either conclusion right.
How Codee3 implements this specification
Codee3 is the reference implementation. Everything below is one way of satisfying the specification; the specification does not require it.
| Clause | Implementation |
|---|---|
| Local-first truth | A governed directory `.ai/` written into the repository, version-controlled with the code. |
| Declared authority class | Every scaffolded document carries an `Authority-Class` header. Five spine documents cover the recurring roles: operating laws, present reality, locked decisions, sequenced work, and append-only history. |
| Verified-At | A `Verified-At` header on governed documents, set and maintained by the author. |
| No versioned successor names | A guard that fails on version-suffixed names inside the governed directory. |
| Every folder indexed / unambiguous order | A guard that requires an index in every document-bearing folder and rejects duplicate sibling ordering prefixes. |
| References resolve | A registry of governed facts with rename history, plus a guard that fails when a retired name still has surviving mentions. A blast-radius command lists every document referencing a fact before it is renamed. |
| One destination for all agent surfaces | A command that detects supported AI coding tools and writes a removable redirect block into each instruction file, pointing them at the governed directory. |
| Index-first navigation | A navigation hub as the mandatory entry point, with per-folder indexes beneath it. |
Codee3 enforces the invariants marked mechanical. The invariants marked partially checkable are recorded and reviewable, and the advanced opt-in layer turns more of them into executable checks — but no part of the product establishes factual correctness or compares prose against source code.