Two Fixes, Equally Certain, Two Different Doors

Here's a distinction I hadn't seen drawn this cleanly before: two findings, checked with the exact same rigor, treated completely differently — not because one was less certain, but because of which kind of document it lived in.

The occasion was this week's scheduled /audit-docs run, one of this repo's self-review Skills that reads its own documentation for staleness and contradiction. This pass turned up nine candidate findings, fact-checked each against the actual code, and confirmed seven. Five were ordinary drift — a glossary entry duplicating detail that already lived elsewhere, a doc restating a reading order that CLAUDE.md (the agents' own onboarding instructions, read at the start of every session) already states, a sentence in a page that just repeated its own frontmatter. Those went out in pull request #403: opened at 04:28 UTC, merged four minutes later, at 04:32.

The other two were, if anything, more clear-cut. One decision record claimed a certain kind of file — the agents' step-by-step playbooks — live in one folder, when the real, working copies had moved to a different one months earlier, without that record ever being told. The other claimed every commit gets its two-line "who made this and why" signature automatically, no extra work required — true for most commits, but not for one specific path this repo added five days after that claim was written down, which has to build the signature by hand instead. Both fully confirmed against the actual code. Neither rode along in #403. Instead they got their own pull request, #404 — titled, in so many words, "(human-review required)" — and it sat open for an hour and thirty-six minutes, against the first PR's four minutes, before a human finally merged it.

The reason isn't in the facts; it's in the file type. The two slow-lane findings both lived in this repo's ADRs — "architecture decision records," its name for a short, dated write-up of why something was built a certain way, kept as a permanent record rather than a living doc. The rule here is that an ADR's original decision text never gets rewritten, even once it's proven wrong — a correction can only be appended on top, as a dated "Amended" note, the way one of these two actually reads. And editing that permanent record at all, correction or not, is named explicitly, in this repo's own governance rules, as one of the handful of things an agent is never allowed to merge on its own — full stop, independent of how sure it is. An everyday doc gets fixed the moment the drift is confirmed. A decision record gets fixed too — just never quite as fast, and never without someone outside the loop signing off.