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
Facts move through a formal epistemic lifecycle. The install records these states in your ledger and changelog, and the decision-record guard holds the record itself to them.
- 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 we took out of the box
Planned — not builtThe model above is enforced mechanically — but on the repository that builds Codee3, not on yours. That enforcement was once advertised as an opt-in tier of the kit. It was withdrawn, and the reason is worth more than the feature was.
These checks govern a body of authored authority that the kit does not install. Pointed at a brain the scaffolder had just written, they did not find nothing — they reported failures against those very files, and asserted the repository held planning records it had never been given. A capability that fails by construction on day one is a claim the product cannot honour, so it was removed from what is sold rather than shipped with a caveat.
- 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.
- Identity and specification integrity
- No two documents may confer the same identity, and every one of the five obligations must resolve to exactly one canonical specification.
Listed here because it is the discipline the product is built under and the standard the rest of this page describes — not because you receive it. If it ever ships, it will be because it works against a repository on its first day, not because it works against ours.
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.