From 0d49ba4da34a57334fa67b76a86f6155dd27ad27 Mon Sep 17 00:00:00 2001 From: dan-claude-bot Date: Wed, 22 Jul 2026 14:22:05 +0000 Subject: [PATCH] docs: doctrine is a machine-verified mirror, not a pointer MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Workflows are consumed by reference because GitHub materializes them at run time; docs have no runtime — agents read the working tree — so the agent-facing set (TRIAGE, BUILDER, REVIEWER, LABELS) vendors into each governed repo at .ceremony/, byte-identical to the pinned ref and guarded by docs-sync --check in CI (#19). Role files made self-contained for vendored reading. Co-Authored-By: Claude Fable 5 --- BUILDER.md | 4 +++- CONTRIBUTING.md | 38 +++++++++++++++++++++++++++----------- REVIEWER.md | 8 ++++---- 3 files changed, 34 insertions(+), 16 deletions(-) diff --git a/BUILDER.md b/BUILDER.md index 830f9ad..a1680f1 100644 --- a/BUILDER.md +++ b/BUILDER.md @@ -45,7 +45,9 @@ triage bug, and the move is to say so on the issue, not to guess. ## The review round -From here the PR flow in [CONTRIBUTING.md](CONTRIBUTING.md) governs: +(If you are reading this as `.ceremony/BUILDER.md` in a governed repo: the +panel roster and any repo-specific flow notes live in that repo's own +CONTRIBUTING; everything below is the shared flow.) 1. Mark ready-for-review; request **the whole panel** (the roster is in the repo's CONTRIBUTING). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d280b37..aa23948 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -80,23 +80,39 @@ repo names its own roster in its CONTRIBUTING. ## How the other repos use this -A governed repo (box, rig, cast, incubator, …) does not copy these documents. -It carries: +Two consumption modes, split by what has a runtime: -- a short header in its own CONTRIBUTING: *"this repo is governed by - [heavy-duty/ceremony](https://github.com/heavy-duty/ceremony) at the ref - pinned in `.github/workflows/release.yml` — agents read CONTRIBUTING.md, - LABELS.md, TRIAGE.md, BUILDER.md and REVIEWER.md there before acting"* — +- **Machinery is consumed by reference.** Workflows and actions are fetched + by GitHub at run time from the ref the caller pins — no copy exists in the + consumer. +- **Doctrine is consumed as a machine-verified mirror.** A document's only + "runtime" is an agent reading the working tree of the repo it stands in — + a doc that requires a cross-repo fetch before it governs is a doc that + sometimes goes unread. So the agent-facing set — **TRIAGE.md, BUILDER.md, + REVIEWER.md, LABELS.md** — is vendored into each governed repo at + **`.ceremony/`**, byte-identical to this repo at the pinned ref, by the + sync tool (issue #19). A CI guard diffs the mirror against the pin on + every PR: hand-editing a vendored file, or bumping the pin without + re-syncing, goes red. It is a copy that cannot drift — which is the only + kind of copy this org allows. + +A governed repo (box, rig, cast, incubator, …) therefore carries: + +- `.ceremony/` — the vendored doctrine (machine-written; never edited by + hand; agents read it from the checkout, no network, no other repo); +- the thin workflow callers (release, labels) pinned to a ceremony tag, plus + the `docs-sync --check` guard step in CI; +- a short header in its own CONTRIBUTING pointing agents at `.ceremony/`, followed by only what is genuinely per-repo: - the **review panel roster**, - the **`scope:*` label set** (`.github/labels.conf` + `.github/labeler.yml`), - the **drill meaning** (`drills/README.md`), - the repo's own code conventions; -- the thin workflow callers (release, labels) pinned to a ceremony tag; - **Discussions enabled**, so the triage door exists. One pin governs both the machinery and the doctrine: the ref a repo's -workflows call is the ref its agents read. Bumping the pin is a one-line PR -and is how a process change rolls out — deliberately, per repo, reviewed. -The full adoption checklist lives in [docs/CONSUMERS.md](docs/CONSUMERS.md) -(issue #12). +workflows call is the ref its `.ceremony/` mirror is verified against. +Bumping the pin is one PR — the pin line plus the re-synced mirror, checked +by the same guard — and is how a process change rolls out: deliberately, per +repo, reviewed. The full adoption checklist lives in +[docs/CONSUMERS.md](docs/CONSUMERS.md) (issue #12). diff --git a/REVIEWER.md b/REVIEWER.md index 9e41f68..17ac893 100644 --- a/REVIEWER.md +++ b/REVIEWER.md @@ -27,10 +27,10 @@ In order of authority: spec. Check every criterion; a PR that ships less than the issue says is a request-changes even if the code is beautiful. 2. **The repo's load-bearing constraints** — the rules bought with - incidents (in this repo: issue #1's constraint list; in a governed repo: - its CONTRIBUTING and this repo's README). A change that "simplifies away" - a constraint gets request-changes with a link to the incident that made - the rule. + incidents (in ceremony itself: issue #1's constraint list; in a governed + repo: its own CONTRIBUTING plus ceremony's README). A change that + "simplifies away" a constraint gets request-changes with a link to the + incident that made the rule. 3. **The code itself** — correctness first, then tests (does the test plan's floor exist? do the failure cases actually fail?), then conventions. Changelog line present for behavior changes; comments carry why, not