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:
parent
d2aa8f1c3b
commit
0d49ba4da3
3 changed files with 34 additions and 16 deletions
|
|
@ -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).
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in a new issue