This directory is two things at once, and the mix is deliberate rather than untidy.
- The prose docs — the roadmap, the consumer guide, the responsible-tech audit, the verification runbook, and the JSON Schema.
- The published site and feed —
index.html,feed.xml,changes.json,sources.json,status.json, and one feed per jurisdiction. These are generated bymake publish(sentinel publish --out docs/) and committed.
Because this is the only place GitHub Pages will serve it from, on the only path available to us.
- Branch-based Pages serves exactly two source paths:
/or/docs. Not/dist. Serving/would publish the entire source tree as a website, so/docsis the only real option. - Actions-based Pages could serve any directory — and it will never run here. This repository's owner has an account-wide GitHub Actions spending limit. A workflow-driven Pages deploy is not a deployment path; it is a promise nobody can keep. So the Actions Pages workflow was deleted rather than left in the repo looking like it works.
- Therefore the published bytes are committed, and Pages serves them straight from the branch: no build step, no CI run, no billing dependency. A feed that only exists once somebody else's billing system agrees to run a job is a feed that does not exist.
Enabling it is a repository setting, not a job: Settings → Pages → Source: "Deploy from a branch" → Branch: main, Folder: /docs.
Do not hand-edit the generated files. make publish overwrites them, and a hand-edit to a published feed is a change no human reviewed reaching an organisation that acts on it — the exact failure this project is built to refuse (make no-unreviewed-in-feed asserts the committed changes.json holds the property).
Generated by make publish |
Written by a human |
|---|---|
index.html — the site, and the Pages entry point |
README.md — this file |
feed.xml — RSS 2.0, all jurisdictions |
CONSUMERS.md — the integrator guide. Start here. |
changes.json — the versioned JSON feed |
ROADMAP.md — the build plan, M0–M5 |
sources.json — the v2 inventory: every registered candidate, exact attempt eligibility, and every named gap |
RESPONSIBLE-TECH-AUDITS.md — the risks, named and addressed |
status.json — persisted watch health; generation time is not success |
schema/status-v1.schema.json — the normative status contract |
feed-us-xx.xml / changes-us-xx.json — one pair per jurisdiction |
VERIFYING.md — the human verification runbook |
.nojekyll — see below |
schema/changes-v2.schema.json — the normative shape of changes.json |
THRESHOLD-EVIDENCE.md — what the removal threshold is and is not measured from |
The rule is simply that make publish owns exactly the filenames in the left column and touches nothing else. Any other .md in this directory is prose, written by a person, and safe to edit.
Without it, Pages runs the directory through Jekyll, which silently drops any file or directory whose name begins with an underscore and reports nothing. The published surface is data an organisation acts on; a deploy step that quietly removes files from it is precisely the kind of unwitnessed failure this repo exists to refuse. sentinel publish writes the file so that nobody has to remember it, and a merge-blocking test asserts it is there.
make serve # serves docs/ under the /id-churn-sentinel/ SUBPATH, as Pages willNot python -m http.server inside docs/. That serves the site at the root of a domain — the one configuration Pages will never use, and the one in which a root-absolute link (href="/feed.xml") looks perfectly correct and then 404s for every consumer on deploy day. Every link the site emits is relative, and test_every_link_on_the_page_is_subpath_safe keeps it that way.
See CONSUMERS.md. In short, and with nothing switched on:
curl -s https://raw.githubusercontent.com/ChelseaKR/id-churn-sentinel/main/docs/changes.json