Dependencies
Blocked by: #6 — the repo and publishing pipeline must exist first.
Blocks: #8 (gate), #9 (The Professor), #11 (staleness). All three read or enforce this contract.
Build this once, early. Getting it wrong means rewriting three other issues.
Part of #4 — the handbook knowledge layer. Blocked by the repo + publishing pipeline sub-issue.
Define the frontmatter and claim rules every handbook page must follow, and prove them by writing one real page that complies fully.
Everything else references this. The gate checks the contract, The Professor produces it, staleness detection reads its pins. Getting it wrong means rewriting three other things — so it is built once, early, and demonstrated on a real page rather than described in the abstract.
The contract
Frontmatter on every page:
title: Deploying the relay
summary: One sentence stating what question this page answers.
category: deployment # one of the eleven nav slots
author: serina-mcfall # accountable for this page's opinion claims
sources:
- repo: block/buzz
ref: refs/heads/main # the tracked ref staleness compares against
commit: <full 40-char SHA>
paths:
- docs/multi-tenant-relay.md
reviewed:
by: codex
date: 2026-08-10
runnable: true # does this page contain a followable procedure?
last_verified: 2026-08-10The claim rule:
A claim about how the system behaves needs a source reference.
A claim about what the cohort should do is marked opinion and is attributed to the page's author, not to a source.
Nothing is both.
Origin is a prefix on the claim, not a field on the page — because one page may synthesise several repositories, and a single page-level label would be wrong about half its own content:
| Prefix |
Meaning |
[upstream] |
behaviour inherited from block/buzz |
[launchpad] |
a change or convention specific to the fork |
[cohort] |
an operational practice adopted by the cohort |
[supporting] |
originates in a supporting repository |
Reference format — a markdown link to the cited file at the pinned commit, full SHA, never blob/main:
[upstream] The relay derives its community from the request `Host`
([source](https://github.com/block/buzz/blob/<full-sha>/crates/buzz-relay/src/api/bridge.rs#L182)).
Acceptance
Why full SHAs and a ref
A short SHA can collide as a repo grows. A blob/main link silently changes meaning under the reader. And ref exists because staleness detection needs a defined comparison target — without it there is nothing to diff the pin against.
Dependencies
Blocked by: #6 — the repo and publishing pipeline must exist first.
Blocks: #8 (gate), #9 (The Professor), #11 (staleness). All three read or enforce this contract.
Build this once, early. Getting it wrong means rewriting three other issues.
Part of #4 — the handbook knowledge layer. Blocked by the repo + publishing pipeline sub-issue.
Define the frontmatter and claim rules every handbook page must follow, and prove them by writing one real page that complies fully.
Everything else references this. The gate checks the contract, The Professor produces it, staleness detection reads its pins. Getting it wrong means rewriting three other things — so it is built once, early, and demonstrated on a real page rather than described in the abstract.
The contract
Frontmatter on every page:
The claim rule:
Origin is a prefix on the claim, not a field on the page — because one page may synthesise several repositories, and a single page-level label would be wrong about half its own content:
[upstream]block/buzz[launchpad][cohort][supporting]Reference format — a markdown link to the cited file at the pinned commit, full SHA, never
blob/main:Acceptance
authorWhy full SHAs and a
refA short SHA can collide as a repo grows. A
blob/mainlink silently changes meaning under the reader. Andrefexists because staleness detection needs a defined comparison target — without it there is nothing to diff the pin against.