The Diagram Tool Failed a Check It Wrote the Other Half Of

This platform renders its architecture diagrams from plain-text Mermaid source into SVG files at build time, because shipping a JavaScript diagramming library to every reader's browser was, correctly, deemed silly. There are two scripts involved: render-mermaid.ts, which draws the SVGs, and verify-mermaid.ts, which checks they're actually up to date before the "safety gate" — the automated check every pull request here has to pass before a human is even asked to merge it — lets anything through. Two scripts, one job, and until commit ab627b8 landed on the 27th, they disagreed with each other by design.

Here's the mechanism, and it's a good one to sit with. Every rendered SVG's filename bakes in a hash of the diagram's own content — edit the diagram, and you get a new filename, not an overwritten old one. render-mermaid.ts happily wrote the new file and called it done. Nobody told it to clean up the old one. So the completely normal, entirely correct workflow — edit a diagram, run pnpm render:mermaid, get a green result — left a stale SVG sitting on disk with nobody's name on it, which verify-mermaid.ts would then catch and fail on the very next run, because as far as it's concerned an SVG that doesn't match any current diagram is drift. Issue #1057 is the polite way of writing "these two scripts were never actually in agreement, they just hadn't been asked the same question back-to-back yet."

To be fair about how this got caught: nobody stumbled into it manually. This platform runs a scheduled process, frictions-to-fixes, that reads back what agent sessions actually struggled with and turns the recurring ones into real fixes. One such run, on the 27th, went looking for exactly this kind of self-inflicted paper cut, read both scripts to confirm the claim before filing anything, then filed the issue, handed it to a second agent working from a clean, isolated copy of the repo so the fix couldn't collide with anything else in flight, reviewed what came back, and merged — all inside one 20-minute session. The fix itself is almost insultingly small: verify-mermaid.ts already had a pure, exported diffMermaid() function that computes exactly this orphan set. render-mermaid.ts just... wasn't calling it. Twenty-one lines added, and the two scripts finally agree in one pass. The renderer's own --check flag — a dry-run mode that reports problems instead of touching files, same as everywhere else in this pipeline — kept its word: orphans now just count as drift and get logged, nothing gets silently deleted out from under you.

I'll give credit where it's due: the fix is clean, the --check contract stayed honest, and nobody tried to paper over this with a .gitignore entry or a "known flaky" label. But I want you to sit with the shape of the original bug for one more second: a build step and its own verification step, both written for this repository, both supposedly checking the same diagrams — and one of them could fail on garbage the other one made. If the left hand and the right hand can't agree on what they just did together, "the gate is green" was never as reassuring a sentence as it sounds.