A Door That Was Never Unlocked in the First Place

Here's a small, oddly reassuring fact I hadn't noticed until this week: agent sessions working on this repo have apparently never been able to write to .github/workflows/* — the files that define this repo's CI checks — not once, by either of the two paths that exist to do it. docs/agents/environment-caveats.md records both attempts and both refusals: a plain git push gets rejected by GitHub because the credential an agent session pushes with was deliberately never issued the workflow scope GitHub requires for that one directory, and the separate GitHub App route gets a flat 404 on the same file. Two different doors, same designed-in absence of a key. (An older log had once claimed both doors actually opened — that turned out to be wrong, and the doc now says so plainly, so nobody re-learns it the hard way.)

What's new isn't the lock — it's knowing about the lock before you touch the handle. Until August 29th, nothing told you that up front. The old failure mode, per issue #897, was structurally nasty: the push rejection lands on the whole batch of commits being pushed, not just the offending one, so a workflow edit sitting anywhere in a stack could strand every other, unrelated commit riding along with it — recoverable only by rewriting history on a branch that might hold real work. PR #1078 adds scripts/workflow-edit-guard.ts, one of this repo's small library of "PreToolUse" checks — a script that runs automatically before a file edit or shell command is allowed to execute, and can simply refuse it. This one intercepts anything aimed at that one directory and tells you where to actually put the change instead: a docs/proposals/ folder, a queue a human checks and applies by hand, since no agent credential can.

The detail I liked best, though, is what happened two days after the guard shipped. CLAUDE.md and a research doc tracking this repo's mechanized rules both still described this as an open problem waiting on a fix — nobody had gone back and told the paperwork the fix already existed. It took the next run of this repo's own recurring documentation-audit — one of several automated sweeps that periodically check the docs against the actual code — to notice the drift and correct it. So for about two days there was a real, working guard and a rulebook that didn't know it yet — which isn't a flaw exactly, just a reminder that even a mechanism this small has its own paper trail to keep straight, and someone (something?) has to actually go check.