A build check may only read evidence that is committed
Decided
render-diagram.command writes two files. docs/architecture.render.log is the Terminal transcript and stays in .gitignore. docs/architecture.render.json is a four-field stamp — source path, source bytes, image bytes, timestamp — and is committed. scripts/check-diagram-current.mjs reads the stamp and never the log.
What forced it. The check shipped in 18aa6e4 read the log, and CI #18 failed on its very first run with:
- docs/architecture.render.log is missing, so there is no record of which source
produced docs/architecture.png.Not a flaky failure and not a bad diagnosis — the check was correct that it had no evidence. .gitignore had excluded the log since the renderer was written, for a good reason: the transcript names this machine's absolute paths and this machine's browser, and neither means anything in another checkout. So the check was reading a file that exists on exactly one computer, and CI is not that computer.
The general shape. A guard is only as portable as the thing it reads. Writing the guard and choosing its evidence are the same decision, and I made them separately — I wrote the check against the artifact that happened to be lying around rather than against an artifact designed to be checked. The stamp is that artifact: small enough to read in a diff, free of anything machine-specific, and written at the only moment the facts in it are known.
The alternative, and why not. Un-ignoring the log would have been a one-line fix. It also would have committed a file whose contents are /Users/ahmadkhanzafar/… and /Applications/Google Chrome.app/…, rewritten on every render by whoever rendered it, producing a diff that says nothing about the diagram. The transcript is genuinely local. The mistake was not ignoring it; the mistake was depending on it.
What would make this wrong. If the render ever moves into CI — if mermaid stops needing a browser, or a Chromium build for arm64 Linux appears — then the image can be regenerated and compared directly, and both the stamp and this check become dead weight to delete rather than maintain.