docs: doctrine is a machine-verified mirror, not a pointer

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 <noreply@anthropic.com>
This commit is contained in:
dan-claude-bot 2026-07-22 14:22:05 +00:00
parent d2aa8f1c3b
commit 0d49ba4da3
3 changed files with 34 additions and 16 deletions

View file

@ -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).

View file

@ -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).

View file

@ -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