Retrieval systems are very good at the question they answer. The trouble is that people ask them a second question at the same time and do not notice they have done it.
Two different questions
Retrieval answers where. Given a query, which passages in this corpus resemble it? That is a well-posed problem with good solutions: inverted indexes, embeddings, hybrid rankers, rerankers.
Governance answers whether you may rely on it. Given a passage, is it in force? Was it superseded? Is it a decision, an observation, a summary, or somebody thinking out loud? Who is accountable for it, and when was it last checked?
No retrieval system answers the second question, because nothing in the retrieval pipeline has access to the information required. Ranking operates over the text. Standing is not a property of the text — it is a property of the text's relationship to an institution. A rejected proposal and an adopted decision can be word-for-word identical in style, length, confidence, and technical detail. They differ only in what happened afterwards, and what happened afterwards is not in the file unless somebody wrote it there.
Resemblance is the only signal available
Every retrieval mechanism in common use returns resemblance under a different definition.
- Grep returns lexical resemblance: this file contains your string. It has no opinion about whether the file matters.
- A semantic index returns embedding proximity: this chunk sits near your query in vector space. Proximity is a statement about wording and topic, not about standing.
- RAG with a reranker returns a model's judgement of topical fit. Better, and still a judgement about aboutness rather than authority.
- Agentic search — an agent choosing its own greps and file reads — returns whatever the agent's exploration happened to surface, which is heavily influenced by filenames and directory names that were chosen for human convenience.
In all four cases the ranking signal is "this looks like what you asked about". That is exactly what you want when the corpus is uniformly reliable, and exactly what misleads you when it is not. Software repositories are never uniformly reliable; they are archives that were never curated because curation had no owner.
Three questions no retriever answers
Put a concrete query to any retrieval stack — "how does authentication work here?" — and it will return the passages most about authentication. Then ask three follow-up questions of each returned passage and watch the system fall silent.
- Is this in force? The passage describes a token exchange. Is that what runs today, what ran in 2023, or what somebody proposed and nobody built? The ranker has no field to consult.
- Has this been replaced? If a newer document supersedes this one, the retriever will happily return both, or only the older one if the older one is better written. Supersession is a relationship between documents, and relationships are not in the embedding.
- What kind of claim is this? A hard constraint, an observation of current state, a summary of something else, or a suggestion. Each demands different treatment from a reader. None of them is distinguishable from the prose.
These are not edge cases. They are the first three things any competent engineer establishes before acting on a document they did not write, and they are established from context the engineer carries rather than from the document itself.
The important consequence is that no improvement to retrieval quality addresses them. A better embedding model, a better reranker, a larger index — each improves the accuracy of "what is this about?" and none of them touches "may I act on it?". Those are orthogonal axes, and effort spent on the first is frequently mistaken for progress on the second.
The failure is systematic, not random
Retrieval does not fail neutrally on an ungoverned corpus. It fails in a specific direction.
Detailed documents outrank terse ones. A rejected design that took two weeks to write is longer, richer in vocabulary, and better matched to any query about its subject than the single line in a decision log that killed it. Enthusiastic documents outrank cautious ones. Proposals, which are written to persuade, read as more authoritative than the record of what was actually built, which is usually written as a shrug.
So the systematic bias is toward the aspirational and away from the actual. The corpus's most confident, most complete, most quotable material is disproportionately the material describing things that did not happen. That bias compounds: an agent grounded in an aspirational document produces aspirational code, which is then reviewed against the same document.
Chroma's distractor finding sharpens this
Chroma's context rot research, which ran roughly 194,480 LLM calls across 18 models, found that semantically similar but irrelevant distractors degraded model performance more than random noise did. Filler text the model can dismiss is less harmful than plausible material it cannot.
That is precisely the shape of an ungoverned repository under retrieval. Retrieval's job is to maximise semantic similarity to the query. On a corpus containing superseded material, doing that job well means selecting for the highest-quality distractors available. The better your retriever, the more convincingly wrong the context it assembles — unless something in the corpus lets you exclude the material that no longer stands.
What it looks like inside an agent loop
Modern coding agents mostly do their own retrieval. They grep, they read files, they follow imports, they decide what to open next based on what they just read. That makes the problem less visible rather than smaller.
A typical sequence: the agent searches for a term, finds four files, opens the two with the most promising names, reads them, and forms a view. The two it did not open might have contained the correction. The two it did open are now the entirety of what it believes about the subject, and it will proceed with the confidence appropriate to having researched the question.
Nothing in that loop surfaces uncertainty. There is no step at which the agent notices that its two sources disagree with a third it never saw, or that one of them is three years old. The exploration terminates when the agent judges it has enough, and "enough" is judged on topical coverage, not on standing.
This is also why filename and directory conventions carry more weight than people expect. An agent choosing what to open next is heavily influenced by names, because names are the only signal available before reading. A directory called proposals/ does useful work. A directory called architecture/ containing a mix of adopted and abandoned designs does the opposite, and does it silently.
Governance does not replace retrieval
It would be a mistake to read any of this as an argument against retrieval. You still need to find things. Nothing about declaring authority helps you locate the right file in a repository with 900 documents.
The point is that the two mechanisms compose. A governed corpus is a better retrieval target, because it gives the retriever fields it can filter and weight on that it could not have derived from the prose:
- Exclude anything marked superseded, unless the query is explicitly historical.
- Rank documents declared canonical above documents declared derived, regardless of textual fit.
- Surface the confirmation date alongside every result, so age is visible at the point of use rather than discovered later.
- Follow declared supersession links from an old document to its replacement instead of returning the old one.
None of that requires a new retrieval technology. It requires the corpus to carry metadata that somebody wrote down and something keeps structurally intact.
What this means in practice
Codee3 does not perform vector search, does not rank documents, and does not read your source tree. It installs a governed .ai/ layer in which documents declare their authority class and confirmation date, routes the agent tools you already use to that layer, and ships guards that fail CI when the layer's structure breaks — versioned names, missing indexes, duplicate ordering prefixes, references to names that were retired.
That is a narrow claim, and deliberately so. Guards check structure. They do not verify that a document's contents match reality; no tool that never reads your code could. What the structure buys you is a corpus where standing is stated rather than guessed — which is what turns retrieval from a source of plausible material into a source of usable material.