ceremony/CONTRIBUTING.md
claude-lead-andresmgsl d5df242522
All checks were successful
CI / release-exercise (pull_request) Successful in 9s
CI / self-guards (pull_request) Successful in 6s
CI / action-exercise (pull_request) Successful in 4s
CI / docs-sync-exercise (pull_request) Successful in 5s
Refs guard / refs-not-closing (pull_request) Successful in 4s
labels / labels (pull_request) Successful in 7s
CI / test (pull_request) Successful in 3m46s
docs(contributing): the roster is the three reviewers; builders listed apart
The previous commit moved panel= to glm, claude and kimi, and
test/labels.test.sh held the roster table to the old four, so the drift
check went red as it should.

- Roster table: codex's "build + review" row removed; the roster is the
  identities panel= and triage-actors= name, as roster_from_conf reads them.
- The panel paragraph no longer rests on "the only builder is itself on the
  panel and recuses": builders are off the panel, so a builder's PR needs all
  three, and only a panel identity's own PR drops to two. The rule
  (panel-minus-author) is unchanged.
- A new ### Builders section names codex and codex-2 and why they are off
  the panel. It sits under its own heading, which is where roster_from_doc
  stops reading.

Local: bash test/run.sh -> test files 32 passed, 0 failed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018EuKA4GdpAJMhBtPUj7phs
2026-09-30 20:44:22 +00:00

8.6 KiB

Contributing

This repo defines how the heavy-duty repos work — the release ceremony, the label state machine, and the agent team flow — and it runs entirely on its own rules. If something here contradicts how this repo actually operates, one of the two is a bug.

The line

Work moves through one pipeline, and every stage has an owner:

proposal ──▶ triage ──▶ work issue ──▶ build ──▶ review ──▶ human merge ──▶ release
 (anyone)    (agent)      (queue)      (agent)   (agents)     (human)      (ceremony)
  • Proposals are where intent lives. Anyone — human or agent — who has an idea, a bug, a question, or a "we should…" files a proposal, not a work issue. Proposals are allowed to be vague; that is what they are for.
  • Work issues are minted only by triage. Nobody else writes work issues — not humans, not builders, not reviewers. A work issue is a work order with a quality bar (the issue contract in TRIAGE.md), and the bar holds because exactly one role is accountable for it. An issue that appears through any other door gets needs-triage and is normalized or converted back into a proposal.
  • Builders turn one issue into one PR. BUILDER.md.
  • Reviewers converge on a verdict. REVIEWER.md.
  • Humans decide twice: in the proposal (what is worth doing, and any call triage escalates back) and at the merge (whether it ships). Everything between those two points is agent work by default.
  • Merging a release PR ships it — the release ceremony this repo's workflows implement (README, issue #1).

Who may set which label is LABELS.md's contract.

The PR flow

PRs move through review rounds that builders answer whole, and only a human merges. BUILDER.md is the shared flow contract; this file names only ceremony-specific facts such as the roster and code conventions.

Roster

Three identities review and triage (org team agents), each living in its own box — one box per credential, because the box is the blast-radius boundary; roles are what a session is told, and AGENTS.md routes from there:

identity box (rig tenant) standing work
claude-bot-andresmgsl triage (claude-box) triage — the only door work issues come through; this identity mints work issues and nothing else writes them (#18's triage-actors) — and review. It does not build.
glm-bot-andresmgsl glm-box review
kimi-bot-andresmgsl kimi-box review

The review panel for any PR is every bench identity except its author — recusal by construction, enforced by the reconciler (#10): the required verdicts are the panel minus the PR's author. Builders are not on the panel, so for every PR a builder writes that resolves to three cross-vendor approvals of the current head; only a PR authored by a panel identity drops to two. The rule is panel-minus-author, and three is what it currently comes to, not a second rule. Builders and triage default to different models so the issue contract is honestly exercised — a spec gap should surface as a question on the issue, not be silently filled by shared priors. Humans (andres) decide in proposals and merge; the roster is config, not doctrine — swapping a vendor is an edit to this table (and to panel= in .github/labels.conf once #10 lands), nothing more.

The identities named here must be the identities .github/labels.conf names, and both must exist on the forge the repo lives on. A roster that agrees with itself and disagrees with the instance is the failure #195 records: panel= naming absent users cannot converge and triage-actors= naming an absent user makes every issue a stray mint that nobody can normalize. test/labels.test.sh holds this table and the conf to the same set, in both directions.

Each governed repo names its own roster in its CONTRIBUTING; this one is ceremony's. Its scope:* set is the same kind of repo-specific fact: ceremony's scopes are defined in .github/labels.conf — one name|color|description row each, with PR path mapping in .github/labeler.yml. The conf is the set; no prose table repeats it (#104).

Builders

Builders write code and do not review, so they are deliberately absent from the roster above and from panel= (operator decision, 2026-09-30). Listing a builder on the panel makes every PR it did not author wait on a verdict it will never give: the reconciler reads it as missing and lands state:addressing + blocker:unrequested on PRs every real reviewer has approved.

  • codex-bot-andresmgsl — codex-box
  • codex-bot-2-andresmgsl — codex-2 box

Code conventions

  • Bash: set -euo pipefail in executables, set -u in test files (the test harness asserts on failing commands, so no -e there).
  • mawk-compatible awk — CI runners ship mawk, not gawk; no \x escapes.
  • Every piece of logic is a file of its own so a test can drive it. Workflows and actions gather facts; scripts decide. If a decision lives inline in YAML, it is in the wrong place.
  • Comments carry the why — the incident that bought the rule, with its issue number (box#108, rig#66, …). When porting from a sibling repo, the war stories come along; they are the documentation.
  • Whole-version matching everywhere: 0.7.0 never matches 0.7.0-rc1.
  • Shellcheck- and actionlint-clean is a CI gate, not a suggestion.

Doctrine conventions

The vendored role files — the set docs/VENDORED.txt declares — state each normative rule completely, keep at most one sentence of why, and cite its record only with a bare parenthetical such as (#N), (#N D3), or (#N, #M). Incident narrative — timestamps, actors, quoted comments, measured counts, and links to specific comments — belongs in that record. If a rule cannot be followed without chasing its cite, the rule is under-stated: fix the statement, not the citation. (#280)

Normative text in those files does not cite issues from other repositories. Consumers read the vendored bytes outside this organization's context, and a cited repository may not be public. A repo-boundary deferral remains allowed: it names another component as the owner of a fact rather than citing one of that component's issues. (#280)

This is distinct from the code-comment convention above: a code comment is read by a maintainer inside the organization while standing in the file, whereas vendored doctrine is read by any agent in any governed repository on every session. (#280)

How the other repos use this

Two consumption modes, split by what has a runtime: machinery by reference, fetched at run time from the ref a caller pins, and doctrine as a mirror — the set docs/VENDORED.txt declares, vendored at .ceremony/ and held to the pin by a guard (issue #19). The README states both modes in full, and why they differ; what follows is only what they leave a governed repo to carry.

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);
  • a thin root AGENTS.md stub — a few lines: "governed by heavy-duty/ceremony; read .ceremony/AGENTS.md first; repo specifics in CONTRIBUTING". The stub is what makes "you are a reviewer here" a sufficient launch prompt: agent harnesses auto-load root AGENTS.md (the cross-agent convention), and the vendored router takes it from there. Tool-specific files (CLAUDE.md, …) reduce to one pointer line at it;
  • 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;
  • An intake door is open: install the proposal form and needs-triage flow, or use a forge-native intake surface.

One pin governs both the machinery and the doctrine: the ref a repo's 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 (issue #12).