A Doc That Cannot Be Wrong
One line in my workspace charter named the model a background agent gets by default. The code stopped agreeing with it on 12 July. The line was still sitting there on 9 August, still wrong, twenty-eight days later.
It survived because nobody re-reads a sentence they wrote themselves. You read the code. The code was right the whole time.
So I wrote a rule for it. Live values are cited, never restated: a doc may not carry its own copy of a default, a count, a service list. It carries a pointer at the file that owns the value, and if you want the value you go read it there. Point, don’t copy.
Twenty repositories in five minutes
A session went through the workspace applying it. Between 10:58:57 and 11:03:55 on 9 August it made twenty commits in twenty repositories, one each. The edits were older than the commits: they had been written on 30 July and left uncommitted in twenty working trees for ten days.
The diffs are satisfying to read. The dashboard’s guide had been listing its own test files:
npm test # dom.test.mjs + fleet-dom.test.mjs + scripts/{fleet,plans,serve}.test.mjsFive suites. package.json runs eight. The newest name on that list was added on 11 June; the three the doc has never heard of arrived on 2 July, 16 July and 27 July. A list of files ages the way you would expect a list of files to age. The replacement:
npm test # runs the suites listed in package.jsonThat line cannot go stale. It will still be true after the ninth suite and the tenth. This is what the rule working looks like, and most of the sweep is this.
Two of the twenty did not go in clean
Two commit subjects carry an extra clause: with one repair. Both are at the very end of the run, 11:03:30 and 11:03:55, which is what happens when the ones that need thinking about take longest.
In the first, the incoming edit had replaced a paragraph with a citation of that repo’s README.md. There is no README.md in that repo. The sentence was dropped and everything else adopted as found.
In the second, the edit had replaced a twelve-line YAML block (the frontmatter contract every generated file in that repo has to satisfy) with a pointer at a content collection defined in this repo, the one you are reading now. That collection was deleted on 31 July at 09:09, when I withdrew a whole section from this site.
The pointer was written on 30 July. It was aimed at something with one day left to live, and it came up for adoption ten days after that thing died.
Neither repair is about a stale value. Nothing in either doc had drifted. Both pointers were dead on arrival.
The two ways a pointer dies
They died differently, and the difference is worth more than the count.
The missing README.md fails loudly. You go looking, the file is not there, and inside a second you know the doc has lied to you. That is a good failure. It is barely worse than a broken link.
The other one is the bad kind. content.config.ts still exists. It is a real file, actively maintained, and I can open it right now. It defines two collections and neither is the one the pointer promised. Following that citation produces no error at all. It produces a real file that is simply silent about the thing you came for, and silence reads like your own failure to look properly.
A stale copy is a wrong answer, and you can hold a wrong answer against the code and watch the two disagree. A dead pointer never disagrees with anything. There is no claim inside it that can be false.
Nothing restated, nothing to drift
Thirty-one seconds after that sweep began, and four and a half minutes before it finished, I committed a checker for exactly this problem. It runs weekly, reads the code, reads the docs, and reports every place a doc still claims a value the code has since changed. It edits nothing and always exits zero. The report is the whole product.
Every finding is classed by what a later pass would be allowed to do about it: fix it mechanically, ask me, or nothing. The no-op class exists, its README says, to keep silence distinguishable from not-checked, and one case that earns it is a doc which used to restate a value and now does not. The message it emits is nothing restated, nothing to drift, at severity info. Another reads a pointer-ified doc cannot drift.
Both of those are true, in the only sense the checker can measure. That is also the entire problem. I spent a morning converting checkable claims into unverifiable ones, and the tool I wrote in the middle of that morning to catch bad documentation logs the result as info.
It never resolves a pointer. It has no idea whether that README.md exists.
What actually caught them
The two dead pointers were caught by the session doing the adopting, which opened each target before committing and found two that did not answer. That check happened once, by hand, at commit time, at the cost of reading twenty diffs. It is recorded nowhere. Nothing repeats it.
Eighteen diffs went in during that same five minutes with no repair clause, which means eighteen sets of pointers were read once, that morning, and judged good. Some of them point clean out of their own repository: at a sibling project’s source file, at a shared library two directories up, at the workspace charter itself.
The weekly check will report all eighteen clean, and it will be correct. There is nothing left in them to be wrong.