Case study • Guardrails

Reproducible Static Blog Guardrails

I turned a static blog into a reproducible engineering system with deterministic builds, curated index pinning, and a canonical CSS layer to eliminate cascade drift.

2026-02-08 • #devops #reproducibility #guardrails

This post is a case study of how a “simple static site” becomes a real engineering system when you treat output correctness as a contract — not a hope.

The failure mode: static sites drift quietly

  • CSS blocks get duplicated and the cascade starts behaving differently.
  • A generator overwrites an index page you meant to hand-curate.
  • A stray <style> sneaks into a stylesheet from copy/paste.
  • The build “works locally” but differs in CI or on Vercel.

These are drift problems. They’re usually invariants being violated — so I added guardrails.

Guardrail #1 — No HTML inside CSS

If a <style> tag ends up inside main.css, it can break parsers/minifiers and create unpredictable build differences.

The fix: a prebuild script that strips CSS comments (to avoid false positives) and fails on real <style> tags.

Script: scripts/check-css.mjs

Guardrail #2 — Canonical CSS layer to stop cascade drift

CSS drift happens when the same selector exists in multiple places. The last one wins — and your UI becomes unstable.

I introduced a canonical posts grid block that must exist exactly once and sit at the very bottom of the stylesheet, ending with: 

/* JLT_CANONICAL_POSTS_GRID_V1 */

Script: scripts/check-canonical-grid.mjs

Guardrail #3 — Curated index pinning

Sometimes you want editorial control. My /posts/ page is curated, so I pin the source of truth and prevent generators from overwriting it.

Guardrail #4 — Output contract verification

A successful build can still produce broken deployment output. I verify the output contract after build to ensure key pages and data exist in .vercel/output/static.

Copy/paste snippets

Run the full guardrail chain

npm run deploy:check

Run guards individually

node scripts/check-css.mjs
node scripts/check-canonical-grid.mjs

Debug canonical-grid locally (PowerShell)

$env:DEBUG="1"; node scripts/check-canonical-grid.mjs

What building this taught me

Static doesn’t mean simple. Static can be reproducible — if you enforce invariants, validate outputs, and keep the workflow intentionally boring.