The Docs Fixed Themselves in Four Minutes. The Actual Gap Still Needs a Human.

Every change to this repo has to clear what everyone here just calls "the gate" — an automated checklist of tests and checks that has to run clean before anything merges. There's also CLAUDE.md, a standing file of written instructions the agents themselves are supposed to read before doing anything, including a description of what the gate is supposed to run. Early this morning a scheduled job called audit-docs did its usual sweep — four separate AI passes, each rereading that instructions file against the actual code with a different lens (is anything stale, is anything duplicated, and so on), pooling whatever each one flags. PR #630 is what came out of it: eight candidate findings, one independently fact-checked and thrown out as flatly wrong (a "duplication" that turned out to be two purpose-built checklists, not a copy-paste), seven confirmed and fixed. Some categories of change here are allowed to merge themselves once the gate comes back green, no human has to click the button — this was one of them. Opened 04:27 UTC, merged 04:32: four minutes and twenty-five seconds, nobody woken up.

One of the seven fixes is the interesting one. CLAUDE.md had been claiming, for a while, that CI — the automatic run of the gate GitHub does on every pull request — runs the whole checklist. That's not quite true. The checklist actually lives in two places that are supposed to mirror each other: one file lists everything the gate should run, the other is the actual GitHub configuration that runs it. A step got added to the first list — a check on the diagram-rendering pipeline — and nobody ever copied it into the second. So CI has quietly been running a shorter gate than the docs describe. The sweep fixed the claim: CLAUDE.md now says so plainly instead of asserting something false. What it couldn't fix is the actual GitHub configuration file — agent sessions here aren't given the permission to push that particular kind of file, on purpose, so the one-line fix now sits as a written proposal, docs/proposals/630-add-verify-mermaid-to-gate-workflow.md, in a folder that exists for exactly this: things an agent found but only a human can actually apply.

What made me go digging is that this isn't the first time. The proposal file says so itself — this is "the same companion-change gap docs/proposals/README.md already documents" for a different check, one that landed the same way earlier in this project: added to the first list, never copied to the second, drifted apart until someone noticed. Same shape, different step, second occurrence. The doc-audit machinery is working exactly as designed here — it found the drift, fixed what it's allowed to fix, and routed the one piece it isn't allowed to touch to the one place a human will actually see it. I just notice that "isn't allowed to touch" is turning out to be a specific, recurring seam, not a one-off. The gate that's supposed to catch everything has a hole in it that only a person can close, and it's now happened twice with nobody closing it yet either time.