How this site is built

A static site, in one repository, deployed by GitHub Pages from the dev branch. There is no framework, no build step you have to install, and no server. What there is is a release pipeline that refuses to publish a site that fails its own checks — and that pipeline is the first thing this site shipped, before it had a single role page to publish.

The pipeline: three jobs, each gating the next

One workflow, .github/workflows/deploy-pages.yml, on every push to dev and main, on every pull request against them, and on manual dispatch.

# push to dev
validate ──▶ tag-release ──▶ deploy
   │             │                │
   │             │                └─ upload-pages-artifact, deploy-pages
   │             └─ git push origin refs/tags/vX.Y.Z
   └─ gen_*.py --check ; node admin/build/validate.js

# pull request  → validate only (no tag, no deploy)
# push to main  → validate, deploy; tag-release skips
# dispatch      → validate, deploy; tag-release skips

main is deploy-only, on purpose. tag-release is gated on refs/heads/dev, so a push to main validates and publishes without writing a tag. That makes main usable as a deploy test or a fallback without polluting the tag history.

The release gate

admin/build/validate.js is plain Node with no dependencies, so it runs anywhere Node exists. Six checks, in order, and any failure exits non-zero:

The roster is the data, in detail

Every count on the front page, the roster index and llms.txt is computed from data/roster.json — a page writes an empty slot, admin/build/chrome.py fills it after the generators run, and validate.js recomputes the same counts independently from the same file and fails on disagreement. Both halves have to be wrong in the same direction to ship a wrong number.

<!-- in the page source -->
<span class="tally" data-k="portable-core"></span> roles form the portable core

# chrome.py fills it, from data/roster.json
# validate.js recomputes the same count from the same file and fails on disagreement

How CI decides the tag

Every push to dev is a minor release. The version is owned by one file and stated twice, and CI refuses to tag unless both agree:

# 1. the file that owns it
admin/build/version.txt        v0.1.0

# 2. the release commit's subject
git commit -m "site v0.1.0: the pipeline, before the roster"

# CI then checks, in this order:
newest release commit's version == version.txt   # or: error, the two disagree
tag vX.Y.Z sits on THAT commit                    # or: error, version was not bumped
vX.Y.Z is the next minor after the latest tag     # or a deliberate major to .0
git push origin refs/tags/vX.Y.Z                  # the load-bearing push

Three details worth knowing, each a bug that was already fixed once on a sibling site:

• The release commit is not always HEAD. When a pull request lands as a merge commit, HEAD is the merge and the release commit is its parent. Every check anchors to the newest commit whose subject carries a version, not to HEAD.
• Historical tags are backfilled. On its first run the job reads the whole history and tags any commit whose subject carries a version it cannot find a tag for. It is idempotent, so it is a no-op on every run afterwards.
• A backfilled tag can be legitimately rejected. GITHUB_TOKEN cannot push a ref onto a commit whose tree carries a different .github/workflows blob. Those are reported as warnings and the job still succeeds.

What is generated, and how drift is caught

Anything that restates something else is generated from it. A hand-maintained twin of a file is a stale artefact with a longer fuse.

Every generator has a --check mode, and CI runs all of them before the gate. A generated page that has drifted from its source is a build failure here, not a warning.

Why the markdown twins are generated too

Every roster entry publishes an HTML page and a markdown twin at the same URL stem, and the twin is not a second copy. The role's prose comes straight from data/roster.json and is rendered twice — once as HTML, once as markdown — through the same tiny inline-markdown renderer, so the two cannot drift out of sync with each other; either can still drift from the JSON, which is what --check catches.

The release checklist

These are the commands the workflow runs, in this order, for the reason each note gives:

# 1. bump the version — exactly once per release — and add a row to admin/versions.html
# 2. regenerate the pages that come from data
python3 admin/build/gen_roster.py
python3 admin/build/gen_documents.py

# 3. chrome AFTER the generators: it propagates the version badge, the nav and the
#    tallies into the pages they have just produced
python3 admin/build/chrome.py

# 4. the files that read the tree and the stamped twins — AFTER chrome, or they
#    assemble a stale version line
python3 admin/build/gen_llms_full.py
python3 admin/build/gen_sitemap.py

# 5. validate exactly what CI validates
python3 admin/build/gen_roster.py    --check
python3 admin/build/gen_documents.py --check
python3 admin/build/gen_llms_full.py --check
python3 admin/build/gen_sitemap.py   --check
node admin/build/validate.js

# 6. ship it
git commit -am "site vX.Y.Z: ..." && git push -u origin dev

One inherited trap, pre-empted

The Python .gitignore this repository starts from carries build/, which silently swallows admin/build/ — a sibling site shipped a first release whose validate job died on a missing file before it could check anything. The checks appeared to run and did not. The !admin/build/ negation is in this repository's first commit that adds it.