There is a comfortable assumption underneath most repository-context tooling: that if an agent could see everything, it would know everything. The two are not the same thing, and the distance between them is where a large share of agent failures live.
A context window is a buffer, not a filing cabinet
A context window is a flat sequence of tokens. It has no internal hierarchy, no notion of which passage outranks which, and no memory of where anything came from once it is in there. A binding architectural constraint written last week and an abandoned spike from two years ago occupy the same kind of space and carry the same kind of weight.
Everything in the window is, structurally speaking, equally true. The model can be told otherwise — "the following is authoritative, the following is a draft" — but that instruction is itself just more tokens, competing with everything else for attention. Nothing in the mechanism enforces the ranking.
This is why "just give it more context" stops working earlier than people expect. Adding text raises the volume of undifferentiated material. It does not add the one thing the agent is missing, which is a way to tell what it is allowed to rely on. A repository with 400 Markdown files does not become legible when all 400 fit in the window; it becomes a larger pile of statements with no declared standing. The measured consequences of that pile are covered in context rot, and why a bigger window does not fix authority.
The five properties that turn a statement into knowledge
A statement becomes something you can act on when it carries five things that raw text does not:
- Identity. A stable name that survives edits, so that the thing can be referred to, superseded, or cited without ambiguity. "The auth rule" is not an identity.
DEC-0042is. - Warrant. The reason the statement is entitled to be believed. A decision has a decision behind it. An observation has evidence behind it. A guess has neither, and should say so.
- An owner. Someone or some role accountable for it. Not to assign blame, but because an unowned statement has no path back to reality when reality changes.
- Declared authority. An explicit classification of what kind of statement this is — a law, an observation of current state, a derived summary, an overview. Without this, everything reads as assertion.
- Reconciliation. A defined moment at which the statement was last checked against the world, and a defined process for what happens when it is found wrong.
None of these are exotic. Legal systems, accounting systems, and clinical records all have them, because all three are institutions that must act on statements written by people who have since left. A software repository is exactly the same kind of institution and almost never has any of them.
Warrant is the field everyone skips
Of the five, warrant is the one that gets left out even by teams who are otherwise careful. Identity is easy to see the point of. Dates are easy. Ownership is a familiar concept. Warrant — the reason a statement is entitled to be believed — feels redundant at the moment of writing, because the author knows the reason and cannot imagine not knowing it.
The distinction it captures is between three things that look identical on the page. "Requests must be idempotent" might be a constraint imposed by a payment provider, in which case it is not negotiable and the warrant is a contract. It might be a decision the team made in 2023 after an incident, in which case it is revisable and the warrant is that decision. Or it might be a preference somebody typed because it seemed sensible, in which case it has no warrant at all.
These three demand completely different behaviour from a reader. The first cannot be worked around; the second can be reopened with an argument; the third should probably not have been written as a rule. Yet all three render as the same imperative sentence, and an agent given all three will treat them identically — usually as hard constraints, because imperative sentences read as hard constraints.
Recording warrant is a single clause: because of the provider's API contract, or per decision 0042, or by convention with no strong reason. The clause is what lets a later reader — human or agent — know whether they are permitted to argue.
Similarity is not relevance
The most common substitute for authority is similarity. Retrieval systems find text that resembles the query and place it in the window. This works well enough that it hides how different resemblance and relevance actually are.
Suppose an agent is asked to add a rate limiter. Semantic search over the repository returns a detailed 3,000-word design document for a rate limiter — because it is, by any measure of textual similarity, the single most relevant document in the corpus. It is also the design the team evaluated in March and explicitly rejected, and the file was never deleted because deleting things feels destructive.
The similarity score is near-perfect. The relevance is negative: the document actively leads to the wrong implementation, and it leads there confidently, because it is well written and detailed. Well-written obsolete material is more dangerous than badly written obsolete material, because it earns more trust from both readers and rankers.
Relevance is conferred by standing, not by wording. Standing is a property the corpus has to declare; no distance metric recovers it. This is the argument developed at length in retrieval is not truth.
Humans supply the missing metadata without noticing
Repositories work for humans because humans carry the missing fields in their heads. A developer who opens notes/new-billing-approach.md knows within two seconds that Priya wrote it during the pricing discussion, that the discussion went a different way, and that nobody has looked at the file since. None of that is in the file. All of it is in the reader.
This is why the problem is invisible until agents arrive. The repository was never a complete account of itself; it was always a partial record that a group of informed readers completed from memory. The completion step was so automatic that nobody counted it as work.
An agent starts every session with none of it. It has no recollection of the pricing discussion, no sense of which files people quietly stopped trusting, no instinct that a file's directory name signals its status. It reads what is written. When what is written omits standing, the agent invents a plausible standing, because producing an answer is what it is for.
What declaring it actually looks like
The remedy is unglamorous. Each document that is meant to be relied on carries a small header stating what kind of document it is, when it was last confirmed against reality, and what it descends from. Documents that are summaries say they are summaries and link upward to what they summarise. Documents that are proposals say they are proposals. Documents that have been replaced say what replaced them and are kept rather than quietly deleted.
A worked version of this is a small set of authority classes — canonical for locked local law, witness for what is observably true now with evidence attached, derived for indexes and routing that must never redefine what they point at. The exact vocabulary matters less than the fact that it exists and is used consistently.
This is a modest amount of writing. What makes it hold is that nothing keeps it consistent by good intentions. Names get versioned, folders lose their indexes, a retired concept keeps being referenced by its old name in nine places. Codee3 installs the structure and ships zero-dependency Node guards that fail CI when those specific structural properties break — version-suffixed names, missing indexes, duplicate ordering prefixes, references to retired names. The guards check the shape of the knowledge layer. They do not, and cannot, tell you whether what you wrote in it is true.
The failure mode is quiet
None of this produces an error message. An agent that builds against a rejected design does not crash; it produces working code implementing the wrong thing, with a confident summary attached. The cost surfaces weeks later as a series of small corrections that nobody attributes to a missing header on a Markdown file.
That quietness is why the distinction between context and knowledge is worth being pedantic about. Context is bytes in a window: abundant, cheap, and getting cheaper. Knowledge is bytes plus standing, and standing is the part that has to be written down by someone who knows it, because there is nowhere else for it to come from.