Admin & engineering
How this site is built, validated, tagged and deployed. It is hand-written static HTML with programmatically injected chrome, gated by a pre-release validator, on the same pipeline as pki.sgit.ai and the rest of the network — because a site arguing for verifiable provenance should be reproducible by anybody who clones it.
The pipeline
push to dev | +-- 1. validate node admin/build/validate.js | version agreement · internal links · canonical/CNAME · | key-leak tripwire · instrument labelling | a failure stops the release: no tag, no publish | +-- 2. tag-release v{release}.{major}.{minor} | version.txt must agree with the release commit's subject | the bump must be the next minor (or a deliberate major) | historical releases are backfilled from commit subjects | +-- 3. deploy GitHub Pages, from the tagged commit
Pull requests run validation only — branch work is gated before it ever reaches the release branch. A push to main is deploy-only, so main can serve as a deploy test or fallback.
What the validator checks
| # | Check | Why it exists |
|---|---|---|
| 1 | Version agreement | version.txt against every page's nav badge, this site's versions table, llms.txt, llms-full.txt and index.md — and each release appears in the table exactly once, because a blanket version-bump sed that touches the history table produces duplicates, which shipped once on a sibling site |
| 2 | Internal links | Every relative href and src resolves to a file in the tree. Fragments and query strings are stripped — this site ships a resolver whose links carry a query, which the inherited check would have failed |
| 3 | Canonical host | Every rel="canonical" and og:url points at the host in CNAME, and every page declares one |
| 4 | Key-leak tripwire | Detail →. The prefix may be discussed; key material may not exist. Read keys must be exactly 64 hex characters, and the write prefix followed by eight or more key-shaped characters fails the build in any file, always |
| 5 | Instrument labelling | New for this site. Every instrument page must carry a LAW / STANDARD / FRAMEWORK label and a republishable mark in its header. This is a condition, not a style rule → |
standards was recommended conditionally: the evidence is against the word — the material is roughly 72% law, 20% framework and 8% actual standards — and the recommendation was to keep it only if the three-way distinction became the front page's first substantive claim and every instrument page carried the label.
A condition that lives in a brief is a condition somebody forgets on the fourth instrument. A condition in the pre-release gate is one the build enforces. That is the difference between a stated intention and a property of the site, and it is the same argument this site makes about everything else.
Release process
- Bump
admin/build/version.txt— exactly once per release — and add a row to the versions table; update comms. python3 admin/build/chrome.py— propagates the version badge and any nav or footer change to every page, and stamps the text twins.node admin/build/validate.js— must print OK.git commit -am "site vX.Y.Z: ..." && git push origin dev
The commit subject is load-bearing: CI reads the version out of it and refuses to tag if it disagrees with version.txt.
Repository layout
| Path | What it is |
|---|---|
admin/build/chrome.py | The single definition of the nav and footer, applied across every page. Pages are hand-written; the chrome is not hand-maintained, which is what stops a thirty-page site from drifting |
admin/build/validate.js | The pre-release gate. Five checks, no dependencies |
admin/build/version.txt | Owns the version. The only place it is edited by hand |
assets/site.css | The shared stylesheet — the sgit.ai design language, ported from pki.sgit.ai with an indigo accent and a block of additions this site needs: instrument labels, republishability marks, provision cards, hash chips and the ghosting convention |
briefs/ | The source documents, verbatim. The raw markdown is the source of truth; /documents/ is presentation |
<instrument>/ | One folder per instrument, the same eight sections each. The shape → |
<instrument>/<instrument>.json | The per-instrument endpoint, constructible from the slug |
tools/resolver.js | The citation resolver. Sixty lines, no dependencies, no build step — the tool's code lives in the repo precisely so it is inspectable |
Reproducing a claim from this site
Two of the site's own assertions are checkable in one command each, which is the point:
# a positional hash is sha256 of the address, truncated
$ printf 'eu-ai-act/art-026-para-05' | shasum -a 256 | cut -c1-16
d8fc6df65f292bf3
# the whole instrument, as data
$ curl -s https://standards.sgit.ai/eu-ai-act/eu-ai-act.json | jq '.provenance.known_weaknesses'