Everyone knows /docs rots. The interesting question is not why people fail to maintain it, but why maintenance is the only mechanism anyone has ever proposed.
Rot is the default, not the exception
Consider what a conventional documentation tree actually is. A folder of prose, written at various times by various people, describing a system that has since changed. Each file makes assertions. None of the files says who is accountable for its assertions, when they were last checked, what they were derived from, or whether they have been replaced.
Given that, drift is not a failure of the system — it is the system operating exactly as designed. There is no state in which the tree is known to be current, because currency was never represented. There is only a tree that is presumed current until somebody is burned by it.
This reframes the usual blame. Teams are not undisciplined. They are being asked to hold an invariant that nothing in the tooling represents, checks, or even names. Every other invariant in software engineering that anyone actually holds — type correctness, test coverage, formatting, dependency licensing — is held by a mechanism, not by intention. Documentation is the one place where we still expect intention to be enough.
Projections and authority
The confusion at the root of this is that documentation performs two incompatible jobs at once.
Sometimes a document is the authority: it is where a constraint is actually established, and nothing else says it. "All monetary amounts are stored as integer minor units" is a rule that exists because someone wrote it down. If that file is deleted, the rule is gone.
Sometimes a document is a projection: a summary derived from authorities elsewhere, written for readability. An architecture overview, a getting-started guide, a domain README. These are useful and should exist. But they are restatements, and restatements go stale the moment the source moves.
In an ordinary /docs folder these two live side by side and look identical. That is the actual defect. A projection presented as authority is a claim with no warrant behind it, and there is no way for a reader to tell which one they have picked up. A governed structure makes the distinction explicit: derived documents declare themselves derived and link upward to what they summarise, and on conflict the source wins by rule rather than by argument.
Three fields that are almost always missing
Most of the difference between a rotting document and a governable one comes down to three declarations at the top of the file.
- Authority class
- What kind of statement is this? A locked constraint, an observation of current state with evidence attached, a derived index, a domain overview. Without this, everything reads as equally binding, which in practice means nothing does.
- Confirmation date
- When was this last checked against reality by a person? Distinct from the git modification time, which changes when someone fixes a typo and tells you nothing about whether the content still holds.
- Lineage
- What does this descend from, and what has replaced it? Superseded documents should say what superseded them and be kept, not deleted, so that a reader who arrives via an old link is redirected rather than misled.
These are cheap to write and almost never present. Their absence is what makes documentation ungovernable: with no declared class you cannot resolve conflicts, with no confirmation date you cannot triage, and with no lineage you cannot tell obsolete from current.
Writing more of it does not help
The standard response to documentation problems is to produce more documentation. It is worth being explicit about why that fails, because the intuition behind it is reasonable and the outcome is reliably negative.
Volume raises maintenance load linearly and raises the probability that any given document is current not at all. Ten documents about a subsystem do not describe it ten times as well as one; they describe it once, in ten partially conflicting ways, of which some number are out of date. The reader's job gets harder, not easier, because now they must reconcile rather than read.
There is a second-order effect that is worse. Once a documentation tree is large enough that nobody has read all of it, contributors stop editing existing documents and start adding new ones — because finding and updating the right existing document requires knowing what exists, and creating a new file does not. The tree becomes append-only. Append-only trees never improve; they only get larger and more contradictory.
The exception is documentation with a declared owner and a declared class, because those two fields make updating cheaper than adding. If a reader can see that a specific document is the canonical statement about a subject, the natural move is to edit it. If every document looks equally plausible, the natural move is to write another one.
What a verified date does — and what it does not
A confirmation date deserves precision, because it is easy to overclaim.
What Verified-At does is make staleness visible and inspectable. A document confirmed eleven months ago announces its own risk. A reviewer scanning a directory can see at a glance which documents nobody has looked at since the migration. An agent reading a document with an old confirmation date has an explicit signal it would otherwise have had to guess at.
What it does not do is prove that the contents are correct. A date is a record that a human asserted the document was current on that day. If they were mistaken, or careless, or updated the date without rereading, the date is wrong and nothing will catch it. A confirmation date bounds how much trust is reasonable; it does not establish trust.
This distinction matters because the alternative — a tool that reads your prose and your source code and tells you where they disagree — does not exist in any form that works. Semantic comparison between natural-language claims and implementation is unsolved. Anything claiming otherwise is either doing keyword matching or is describing a roadmap. Making age visible is a small, honest, achievable thing, and it is worth more than a confident claim that cannot be delivered.
Ownership is not about blame
Of the three missing fields, ownership attracts the most resistance, usually on the grounds that assigning an owner to a document creates a person to blame when it is wrong. That is a reasonable worry about a real failure pattern, and it is the wrong conclusion.
An owner is not the person responsible for the document being correct at all times. That is an impossible obligation and nobody accepts it. An owner is the person or role who should be asked when reality changes — the routing address for a question, not the guarantor of an answer.
Its practical value shows up during change. Somebody is replacing the message queue. Which documents are affected? Without ownership, the answer requires reading everything and guessing. With ownership, there is a short list of roles to notify, and the notification is cheap. The document gets updated because someone specific was told it needed updating, which is a completely different situation from everybody vaguely knowing the docs are behind.
Role-level ownership works better than individual ownership for exactly the reason people leave. A document owned by "the payments team" survives a resignation. A document owned by a name that no longer appears in the contributor list is not owned at all, and worse, it looks owned.
Structure is the part that can be mechanised
If truth cannot be checked mechanically, something adjacent can: the structural integrity of the knowledge layer.
A folder holding documents with no index is a folder no reader can navigate without loading everything in it. Two sibling files sharing an ordering prefix means an ambiguous reading order. A file named billing-v2.md has forked truth by declaring a successor while leaving the predecessor in place. A concept renamed in one place but still referenced by its old name in nine others has broken the graph.
Each of these is decidable by a script with no understanding of content whatsoever. That is the narrow, defensible territory. Codee3's guards run in CI and fail the build on exactly these conditions inside the governed .ai/ directory: version-suffixed names, missing indexes, duplicate sibling ordering prefixes, unresolved references to retired names, and the validity of skills routing.
That is the whole scope. The guards will not tell you a document has become false, because they never read your code and could not know. What they prevent is the slower, more boring failure: a knowledge layer that decays structurally until nobody can navigate it, at which point its accuracy stops mattering because nobody is reading it anyway. Whether a check fails a build or merely appears on a report is not a detail — see enforcement versus reporting.