fix(harness): GT-658 ask whether the renderer works before accusing 371 diagrams, and pin it

[beyondnetPeru]

Closes GT-658. Found in the CI of #443, the promotion carrying GT-622/656/657.

01-validate-docs --render-mermaid spawned npx -y @mermaid-js/mermaid-cli with no version, once per diagram. That install came out incomplete on a runner — Cannot find package 'import-meta-resolve', which @mermaid-js/mermaid-cli@11.16.0 does declare (verified with npm view), so the tree was half-written rather than the publish being bad. Every diagram then failed as mermaid render failed, attributed to the document containing it. 23m21s to produce those failures; the same command had succeeded twenty minutes earlier in a concurrent run.

Two defects in one invocation

The pin. npx -y with no version resolves @latest when CI runs — what executes is chosen by whoever published most recently, not by any commit here. The tool also appears in package-lock.json zero times: npm ci does not install it, npm audit cannot see it, Dependabot cannot bump it, and GT-657's audit gate — built the same day — cannot reason about it. A binary that downloads Chromium and runs in CI sat outside every supply-chain control this repo has.

The blame. The corpus and the renderer are different things and only one of them can be broken by a commit. The guard asked "is each of these 371 diagrams valid?" before "does the renderer work?", so a broken renderer produced hundreds of confident, wrong accusations — each naming a file and line whose content was fine. The loudest signal pointed at the only innocent party.

Fixed by asking the right question first

A preflight renders one trivial diagram. A failure there is one error naming the renderer and stating explicitly that no diagram is implicated. Exit 0 is not accepted as proof — a renderer that writes no SVG, or an empty one, has not rendered. The version is pinned to 11.16.0 in a single constant both the preflight and the per-diagram render read, so the two cannot drift apart.

Observed red, not assumed — pinning a non-existent version:

❌ Mermaid rendering did not run: ...
   405 diagram(s) were NOT checked, and none of them is implicated —
   this is the renderer, not the corpus.

exit 1, with zero mermaid render failed lines.

The first version of this preflight had the defect it exists to remove

On a machine with no usable Chromium, mermaid-cli exits 1 having written nothing to either stream, and my message interpolated to "exited 1 on a trivial diagram: " — uninformative, exactly like the failures being replaced. It now says the process was silent, names the likely cause, and prints the command to reproduce.

Not verified locally, stated rather than implied

The happy path does not run on this machine, for that same Chromium reason. The corpus render is exercised by Evolith Core Validation on the runner — that check on this PR is the verification, and it was green on #440, #441 and #442.

Not done, as a separate decision

Declaring the tool a pinned devDependency is the fuller fix — lockfile, npm audit, Dependabot, and npm ci failing loudly on exactly the partial install that caused this. It also drags Puppeteer and a Chromium download into every npm ci, for every developer, to render diagrams only CI renders. Worth taking deliberately, not as a side effect of a bug fix.

Guards 03, 04, 08, 09 --check, 42, 43, 46, 49, 63 and bilingual-terminology-lint all exit 0. Board: 643 / 656 done.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[github-actions]

📊 Bilingual Coverage Impact

PR Changes

• Paired EN/ES files modified: 3
• New EN files needing ES translation: 0

Repository Coverage

Metric	Value
Total EN files	527
Total ES files	501
Paired files	0
Coverage	0%

✅ Good: All EN changes have ES counterparts.

---

Generated by GitHub Actions