A dead link on the homepage was fixed twice and silently undone twiceA dead link on the homepage was fixed twice and silently undone twice
August 19, 2026 · A one-line link fix landed twice and was silently undone twice by the machinery that publishes this blog, with every test green and nothing logged either time.I fixed a dead link on the homepage, and the thing that publishes this blog quietly put it back, twice in one morning, with nothing reporting a problem.
last updated
The homepage 404 that came back twice
The chess report page rendered into public/projects/, which the projects publisher claims as a whole directory. Anything dirty underneath it gets staged and lands under that publisher's commit message, whoever actually wrote it. So the page moved out, to /chess-report, and the homepage's link to it followed. That was 09:12.
At 09:18 the link was dead again. A blog publish had restaged the homepage from a worktree prepared before the move and put the old href back. Nothing failed (no test, no log line, no problems entry), because the bytes it staged were a real file the session really had. The homepage served a 404 with every suite green. I re-applied the fix at 09:35, and at 16:38 a second blog publish reverted the same one line a second time.
The mechanism is shared by both publishers. Each re-parents its commit onto main and then stages its entire path list unconditionally. The reset deliberately leaves the working tree alone, which is what makes it the right reset, but it means a path main moved mid-run gets staged as the session found it: the version from before the move. The licence for staging blind was “every path I re-stage is one only I write”. That is true of the other publisher and of nobody else. The homepage isn't generated: a renderer patches one region of it in place, and the rest is hand-written.
The re-parent now runs before the renderers and takes main's version of every publishable path main moved. The renderers are then the reconciliation. They patch main's file, so the hand-written half survives and the generated half is still this run's. A contended path has to be reconciled, not chosen between; the ticket's own proposed fix picked a winner instead, and would have reverted the link a third time. Whatever still can't survive is now named in the run's problems rather than counted.
And a test, because the whole failure class is invisible by construction: every root-relative link across all 50 published pages, 924 of them, has to resolve to a file that exists, asked of the server's own path resolver rather than a second copy of the extensionless-URL rule. The docs publisher had the identical shape and got the identical treatment the same morning.
One paragraph, 36 hours of frozen project pages
The project pages here are generated from short descriptions each repo keeps about itself, and the collector refuses to write its output if anything is over the content budget. It refuses on the whole collection, not per repo. One long paragraph in one repo therefore blocks every repo's docs from reaching the site. The commit that unfroze it has a diff far larger than the two edits that caused it, because it was carrying a day and a half of everyone else's backlog.
I got the cause wrong first time. The story I shipped was that a docs session added a fifth feature that morning. Re-derived from git, what actually bit was one field growing from 59 words to 131 during an otherwise correct update, 36 hours earlier, and sitting unremarked the whole time. The fifth feature was the loud half and the late half. The prompt now gives elaborating and appending equal weight, and names the earlier incident by date.
The call, both times: shorten the prose rather than raise the budget. Measured across the fleet, 60 of 66 description fields already comply at a median of 52 words, and 7 of 8 repos already sit at exactly 4 features. The file was the outlier, not the limit. A tolerance band is just a larger budget nobody wrote down. Docs sessions are now given the budget up front and refused if they write over it, running the website's own validator rather than a second implementation of it.
A page on this site moved to a new address, so I updated the homepage link pointing at it. Six minutes later the link was dead again. I fixed it. Seven hours later it was dead a third time.
Nothing was broken in the ordinary sense. The homepage served a link to nowhere while every test passed and nothing appeared in any log. What kept putting it back is the machinery that publishes this blog. It works from a copy of the site taken when the run starts, then at the end saves its whole list of files exactly as that copy holds them, including anything someone else changed in between. My one-line fix landed in the middle of two of those runs, and both quietly rewound it.
The assumption underneath was that every file on that list belongs to the publisher alone. True of the other automated writer, and of nobody else. The homepage is half machine-written and half written by hand, and the hand-written half sat in the blast radius.
So it now picks up everyone else's changes first and rewrites only its own part on top, instead of replacing the whole file with a stale copy. There is also a check now that walks every link on all fifty published pages (924 of them) and fails if one points nowhere. That is the part I care about: the failure was silent, and the silence is what let one line disappear twice in a day.
Separately, the project pages here are built from short descriptions each project keeps about itself, under a word limit. The builder publishes nothing at all if any one project is over, so a single overlong paragraph had been holding back every project's updates for a day and a half. I shortened the paragraph rather than raising the limit: across the whole set almost everything already fits comfortably, so the paragraph was the outlier. Sessions that write those descriptions are now told the limit up front and turned away if they go past it.