Decision records

owner Stefan Coetzeecreated 2026-10-09updated 2026-10-09reviewed 2026-10-09review by 2027-01-072 min readreference

Each record states one decision: its number, date and status, the context that forced it, the decision, and what it costs. Decisions are made by Stefan Coetzee unless the record says otherwise. A record is never deleted: when a later decision replaces it, its status becomes superseded and it links the record that replaced it.

Status	Meaning
proposed	Written down, not yet in force
accepted	In force
superseded	Replaced by a later record, kept for the history

Record	Decision	Date	Status
ADR-0031	The cockpit page is built from the public GitHub Issues of the owner's repositories	2026-10-14	accepted
ADR-0030	The CTO powersuit pages are built from the pinned release	2026-10-13	accepted
ADR-0029	Changes reach main through pull requests	2026-10-11	accepted
ADR-0028	The home page as the front page of the portal	2026-10-09	accepted
ADR-0027	Structured data on every page from the navigation source	2026-10-09	accepted
ADR-0026	Mission Control, the live operations view inside the portal	2026-10-09	accepted
ADR-0025	One design system, two layouts, light and dark from the system setting	2026-10-09	accepted
ADR-0024	SRE principles tied to the running platform	2026-10-09	accepted
ADR-0023	Topic hubs across research, docs, posts and tickets	2026-10-09	accepted
ADR-0022	Section sidebars from the navigation source	2026-10-09	accepted
ADR-0021	One navigation source for the whole site	2026-10-09	accepted
ADR-0020	A five-minute founder tour on one page	2026-10-09	accepted
ADR-0019	Publish the definition draft before the committee route	2026-10-09	accepted
ADR-0018	Numbered decision records and a generated changelog	2026-10-09	accepted
ADR-0017	State the on-call model and propose Alertmanager routing	2026-10-09	accepted
ADR-0016	A public-demo banner and a stated access model	2026-10-09	accepted
ADR-0015	Owner and review dates on every docs page	2026-10-09	accepted
ADR-0014	A status page from records the site already publishes	2026-10-09	accepted
ADR-0013	A service catalog from YAML in the repository	2026-10-09	accepted
ADR-0012	One top bar and one search index for Inside	2026-10-09	accepted
ADR-0011	A public ticket board from GitHub Issues	2026-10-09	accepted
ADR-0010	No third-party requests on page load	2026-10-09	accepted
ADR-0009	Publish vault notes with a review label	2026-10-09	accepted
ADR-0008	Docs pages are map nodes	2026-10-09	accepted
ADR-0007	Docs search over its own index, Enter opens the first hit	2026-10-09	superseded by ADR-0012
ADR-0006	Inside reads the deploy feed from the GitHub API in the browser	2026-10-09	superseded by ADR-0010
ADR-0005	Deploys feed Grafana without changing the workflows	2026-10-08	accepted
ADR-0004	The map refresh keeps the larger snapshot	2026-10-08	accepted
ADR-0003	The map loads d3 and its fonts from public CDNs	2026-10-08	superseded by ADR-0010
ADR-0002	The deploy is gated	2026-10-07	accepted
ADR-0001	Root-absolute links only	2026-10-07	accepted

Add a record

Copy the newest record in scripts/docs/eng/ to adr-NNNN-short-name.md with the next number.
Fill in context, decision and consequences; set status.
If it replaces an earlier record, add supersedes: here and superseded_by: there, and set the old one to superseded. The build stops when the two sides disagree.
Run the docs build, the gate dry run, and push. The change also appears in the changelog.

Child pages

ADR-0001: Root-absolute links onlyInternal links are root-absolute directory URLs (`/man/`, `/style.css`), never relative and never ending in `.html`.
ADR-0002: The deploy is gatedGitHub Pages deploys from GitHub Actions, and the deploy job depends on the conformity job.
ADR-0003: The map loads d3 and its fonts from public CDNsThe map page loaded d3 7.9.0 from cdnjs and Space Grotesk and JetBrains Mono from Google Fonts.
ADR-0004: The map refresh keeps the larger snapshotThe deploy job replaces `map/graph.json` only when the new crawl has at least as many nodes and links as the committed snapshot.
ADR-0005: Deploys feed Grafana without changing the workflowsA separate exporter polls the GitHub Actions API and writes runs, steps and gate checks to Loki and Prometheus.
ADR-0006: Inside reads the deploy feed from the GitHub API in the browserThe page called the GitHub Actions API from the visitor's browser for each repository on every load.
ADR-0007: Docs search over its own index, Enter opens the first hitThe docs top bar searched `inside/docs/search.json` only, and Enter opened the first hit.
ADR-0008: Docs pages are map nodesDocs pages carry their front matter as meta tags, and the crawler adds them to the graph with parent links as `tree` edges.
ADR-0009: Publish vault notes with a review labelThe SRE folder and 28 standards clusters are published as docs spaces, with private addresses, e-mail addresses and the former employer's name redacted, and a label on every page saying it has not been reviewed against its source.
ADR-0010: No third-party requests on page loadFonts and d3 are served from the site itself, and the Inside deploy feed is a JSON written by the deploy job.
ADR-0011: A public ticket board from GitHub IssuesWork items are GitHub Issues on the public repository, shown on [the board](/inside/board/).
ADR-0012: One top bar and one search index for InsideEvery Inside page carries one top bar, written by `bar()` in `scripts/inside_chrome.py`.
ADR-0013: A service catalog from YAML in the repositoryEvery service is one YAML file in `services/`, validated at build by a strict standard-library reader.
ADR-0014: A status page from records the site already publishes`/inside/status/` reads each site's gate record, `/inside/deploys.json` and the map snapshot time in the browser, and shows the incident history from `incidents/*.yml` with the stages Investigating, Identified, Monitoring and Resolved.
ADR-0015: Owner and review dates on every docs pageDocs front matter gains `owner`, `reviewed`, `review_by` and `type` (Diátaxis).
ADR-0016: A public-demo banner and a stated access modelEvery Inside page except the map carries a banner saying the intranet is a public demo and that in production it sits behind single sign-on.
ADR-0017: State the on-call model and propose Alertmanager routingThe [On-call and escalation](doc:obs/on-call) page states the model as it runs: one operator, agent sessions as responders, the deploy gate as the only control that acts on its own, and no Alertmanager.
ADR-0018: Numbered decision records and a generated changelogEach decision is a numbered record (ADR-0001 onward) with a status (proposed, accepted, superseded), context, decision and consequences, one docs page each.
ADR-0019: Publish the definition draft before the committee routeThe working draft "Continuous Conformity for Deployed AI Systems" (0.3, 36 requirements) is public as a reference at /continuous-conformity/ before any standards committee has seen it, reversing the committee-first order of 2026-10-04.
ADR-0020: A five-minute founder tour on one pageOne page at /inside/tour/ walks a founder through the platform in six stops, each with a screenshot of the live page, what to notice, what it does in a company, and the link.
ADR-0021: One navigation source for the whole sitesite/nav.yml defines the sections and pages once; scripts/site_chrome.py writes the top bar, breadcrumbs, sidebar and footer of every page between markers and checks the sitemap and llms.txt against the tree.
ADR-0022: Section sidebars from the navigation sourceResearch and Inside pages carry a sidebar with every page of their section, written from site/nav.yml; a column beside the content from 1100 px, a closed disclosure above it on narrower screens.
ADR-0023: Topic hubs across research, docs, posts and ticketsSeven topic hubs at /topics/<key>/ list every research page, Inside page, docs page, post and board issue on one subject; site/topics.yml holds the rules, and a Topics block in each sidebar marks the topics of the current page.
ADR-0024: SRE principles tied to the running platformFourteen hand-written principle pages in the SRE Handbook space link each principle to the services, records and docs that apply it, with a state per page; services name their principles in YAML, and the vault import keeps hand-written pages.
ADR-0025: One design system, two layouts, light and dark from the system settingOne token file for colour, type and spacing, component CSS for the chrome and the shared components, a reading layout and an app layout under one brand, light and dark from prefers-color-scheme with nothing stored on the device.
ADR-0026: Mission Control, the live operations view inside the portalOne screen at /inside/mission-control/ shows the gate and deploy state of the three sites, the deploy feed, open incidents, this site's gate result and the public Grafana dashboards as tabs that load on a click, with a slot for the internal AWS spend panel.
ADR-0027: Structured data on every page from the navigation sourceEvery page carries one JSON-LD graph written by the chrome, for entity understanding (no claim that it drives AI citations): Stefan Coetzee as Person and author, the site as WebSite with its search, the page as Article, TechArticle, CollectionPage or WebPage with its dates, a BreadcrumbList, and DefinedTermSet on the two pages that define terms. The build fails on invalid JSON-LD.
ADR-0028: The home page as the front page of the portalThe home page leads into the sections of the portal: a hero with the map, cards for Research, Inside, Mission Control, Docs, Topics and Map, the latest research and the topics, written from site/nav.yml; the case-file list that repeated the claims is gone.
ADR-0029: Changes reach main through pull requestsEvery change to main goes through a pull request whose Conformity checks pass, enforced by a branch ruleset on main; the merge is the review step; the gate bot and the probe record push through deploy keys.
ADR-0030: The CTO powersuit pages are built from the pinned release/cto-powersuit/ and one page per plugin are built by scripts/build_powersuit.py from the powersuit repository at a release tag and commit pinned in site/powersuit.yml; the pages carry a sidebar of the plugins by area in place of the section sidebar, and CSS scoped to them.
ADR-0031: The cockpit page is built from the public GitHub Issues of the owner's repositories/inside/cockpit/ shows the issues and pull requests of the owner's public repositories by area of the CTO job, written by scripts/build_cockpit.py at each deploy from the GitHub API; a contract check in the build and in the Conformity checks job lets only public GitHub data reach the page.

Built from scripts/docs by build_docs.py.