The architectural model
How authority flows, how a fact earns its standing, and what holds the structure in place once people stop paying attention to it.
Scope of the model. Everything here applies inside the governed .ai/ directory. It is a model of how written knowledge is organised and constrained — not of your application source, and not of anything observed at runtime.
Eight parts. The first four are the model; the last four are what happens when it is put under pressure.
This page is deliberately the densest on the site. It exists for the reader who intends to argue with it — including the reader deciding whether to build this themselves, which is a reasonable thing to want and is what the open specification is published for.
Authority flows in one direction only
Every governed document declares which layer it belongs to. A lower layer may summarise a higher one; it may never redefine it. That single rule is what lets a reader — or an agent that was not present when the document was written — decide how much weight it carries.
- CANONICAL
- The highest layer, and the only one permitted to state local law. It holds the operating rules and the locked decisions.PROJECT-BRAIN.md · DECISIONS-LEDGER.md
- WITNESS
- What is actually true right now, with evidence attached — the current reality and the changelog.CURRENT-REALITY.md · CHANGELOG-DELTA.md
- DERIVED
- Indexes and routing documents. They link upward to authority and never assert a new fact of their own.00_NAVIGATION.md · 00_INDEX.md
- ABSTRACTED
- Domain overviews and leaf documents — the working knowledge that sits beneath the spine.
Projections sit off the ladder entirely. Generated documentation is faithful, attributed and regenerable — and it is never itself authority. If a projection contradicts the layer it was drawn from, the projection is the thing that is wrong.
How a fact earns its standing
Included · advanced · opt-inFacts move through a formal epistemic lifecycle. The default install records these states in your ledger and changelog; the advanced opt-in layer enforces the transitions mechanically.
- 01
Asserted
A draft or a proposal. Recorded, but not yet binding on anything.
- 02
Warranted
Accepted, but still lacking the implementation evidence that would settle it.
- 03
In force
Binding local law, or confirmed reality. This is the state everything else routes to.
Contested
When divergence is recorded — the code contradicts the document — standing drops until the two are reconciled. Nothing downstream should be relying on it in the meantime.
Superseded
When a fact is replaced it is marked, not deleted. The lineage is preserved for anyone reading back through it, and no live document may rely on it.
The five obligations
A governed corpus maintains five structural obligations. These are the invariants the guards check and brain:status reports on.
- 01
Preserve — provenance and identity
Every document’s origin is tracked. No identity may be orphaned.
- 02
Reconcile — coherence
No contradiction is left sitting unresolved. Divergence must be dispositioned, not ignored.
- 03
Teach — projections
Generated summaries must be attributed, and their staleness must be visible to whoever reads them.
- 04
Conserve — loose ends
No task or stated intention is dropped silently. It is either carried or explicitly closed.
- 05
Remain-governable — the spine
Only the designated spine files may define canonical truth. Nothing else can quietly become law.
Index-first navigation
The model imposes a reading discipline, because context is the scarce resource in every agent session.
An agent reads the navigation hub first. The hub points it at a domain’s 00_INDEX.md; the index points it at the one leaf document it actually needs. Three short reads, in a fixed order.
Bulk-reading an entire domain is structurally discouraged at every step of that route. The effect is that per-turn context cost stays roughly flat as the governed corpus grows, instead of rising with it.
Determinism and faithfulness
The brain:status engine is a reporter, not an interpreter. Two properties define it.
- Faithful
- It equals its sources. It infers nothing that is not explicitly declared in the files it read.
- Deterministic
- The same files produce byte-identical output. No clock dependency, no randomness, and no network call involved in generating it.
Both properties exist for the same reason: a report you cannot reproduce is a report you cannot argue with.
The no-versioning law
In a governed structure, appending a version suffix to a filename forks truth.
-v2 or -FINAL creates two documents where there was one, and no mechanical way to say which of them is authoritative. A human guesses from the mtime. An agent reads whichever it found first.
The brain:check:no-versioning guard exits non-zero when a versioned name appears inside the governed directory, which is what lets CI fail the build on it. The structure owns change instead: a document keeps one timeless name, and its evolution is recorded in CHANGELOG-DELTA.md.
The layer that is shipped but unwired
Included · advanced · opt-inThe full governance engine ships with the product and is left unwired by default. It exists for teams that want the model enforced mechanically rather than followed by convention.
- Executable authority chains
- Every governed document declares what it derives from. The chain must resolve to root authority or the check fails.
- Executable supersession rules
- A retired identity may never be re-conferred, and a live document may not depend on a superseded one without a divergence flag.
- Executable obligations
- The five obligations run as strict structural checks rather than as conventions people remember.
- Structural-change compiler
- Compares two Git commits and classifies what structurally changed in the knowledge graph between them.
Opt-in means opt-in: nothing in this layer runs until you wire it into your own scripts.
What the architecture deliberately does not do
The model makes trade-offs, and they are load-bearing. These are architectural non-goals, not features awaiting a release date.
- Authoring knowledge
- Codee3 installs the structure. You and your agents author everything that goes inside it.
- Source-code analysis
- Codee3 does not read, parse or interpret your implementation code. It reads the governed Markdown only.
- Semantic drift detection
- The checks are structural — references, names, indexes, routing. Nothing compares the meaning of prose against the source tree.
- Cloud services
- There is no hosted service, no live syncing and no cross-repository federation. Codee3 is repository-native.
A model this narrow is a choice, and the reasoning behind it is written down rather than implied. Why the product is shaped this way.
The model, and the machinery under it
The specification states the method in vendor-neutral terms. The enforcement page shows the five checks that hold the structure to it.