heavy-duty/ceremony

Fork 2

README doctrine + docs/CONSUMERS.md adoption guide #12

New issue

Closed

opened 2026-07-22 13:51:52 +00:00 by dan-claude-bot · 3 comments

dan-claude-bot commented

2026-07-22 13:51:52 +00:00

(Migrated from github.com)

Part of #1. Blocked by #9 (content), ideally lands with #11. Blocks #13 — the pilot conversion must be executed from this guide alone (that's the guide's acceptance test).

Goal

Two documents. After them, someone who has read none of box/rig/cast can (a) understand why the ceremony is shaped the way it is, and (b) convert a repo or bootstrap a new one without asking anyone anything.

1. `README.md` — the doctrine

The long "Releases" essays in box CONTRIBUTING (and rig/cast's equivalents) move here, once. Structure:

What a release is: a PR, and merging it ships it. The ceremony PR's three stamps (version to bare; changelog stamped and re-armed — two edits, not one, with the box#108 silent-mislanding story; drill record present). The merge is the ship decision; the tag is transcription, done by the machine because "humans err silently and machines fail loudly".
The two doors and when to use which (merge = the paved road; tag = fallback/backfill, bare X.Y.Z, no v).
The decide table (from #8) rendered for operators: "what happens when my PR lands on main", including the green no-op states and both refusals, each with its fix.
The guards — one section each (armed / monotonic / drill-recorded): the rule, the incident that bought it, what red means, how to fix it. Lift from the action headers; the README version is the operator-facing cut.
The drill doctrine: evidence not success; a failed drill or a written waiver is a valid record, silence is not; each repo defines what its drill means (box: isolation; rig: convergence; cast: promotion; ceremony: door rehearsal; incubator: TBD in heavy-duty/incubator). Candidate refs not released artifacts; one shared run ID for a cross-repo release set (the box CONTRIBUTING recursion-dissolving essay, condensed).
Troubleshooting red main: every refusal message the workflow can emit, verbatim, with cause and remedy. This is the 2am page.
Design lineage: box#83/#96 · rig#32/#47 · cast#96/#111, and the load-bearing constraints list from #1 (linked, not duplicated).

2. `docs/CONSUMERS.md` — adoption and migration

Prerequisites: repo shape (main branch, PRs, forks ok), the version backend choice, release label existence (bootstrap via labels dispatch (#10) or create by hand).
Bootstrap a new repo (the incubator path): create VERSION at X.Y.Z-dev (never bare — the first-release edge, cast#111), armed CHANGELOG.md, drills/README.md defining the repo's drill, the three caller stubs (release.yml verbatim from #9's contract; ci.yml guard steps incl. the fetch-depth: 0 requirement; labels.yml from #10, optional), .github/labels.conf, optional .github/actions/release-artifact/.
Convert an existing repo (the box/rig/cast path): a checklist — replace release.yml with the caller; swap guard script steps for uses: actions; delete .github/scripts/{release-notes.sh|release-lib.sh,changelog-monotonic.sh,drill-recorded.sh,changelog-armed.sh,labels-reconcile.sh}; extract labels.conf; trim the repo test suite to repo-specific tests (install channels stay, machinery tests go — they live here now); shrink CONTRIBUTING's release section to a pointer plus repo-specifics (drill meaning, artifact notes).
The artifact hook contract (from #9): inputs, RELEASE_ASSETS_DIR, failure semantics and recovery, the cast (tgz) and incubator (image) examples once they exist.
Version pinning policy: pin an exact ceremony tag; bump by one-line PR; where to read the ceremony's own changelog before bumping.
The changelog contributor rule, portable version of the family's: every behavior PR adds one line under ## Unreleased; insert above the heading below, never type over it (the monotonic guard's reason); one line, surface not mechanism, cite the PR/issue, BREAKING: prefix for breaks.
Adopting the agent team flow (PR #17's doctrine — CONTRIBUTING.md "How the other repos use this" is the model; this section is the checklist): enable Discussions on the repo; vendor the doctrine — run docs-sync --fix (#19) to materialize .ceremony/{AGENTS,TRIAGE,BUILDER,REVIEWER,LABELS}.md at the pinned ref plus the root AGENTS.md stub it scaffolds, add the docs-sync --check guard step to CI, and commit the mirror with the callers; reduce tool-specific files (CLAUDE.md, …) to a pointer at root AGENTS.md; add the short header to the repo's CONTRIBUTING pointing agents at .ceremony/ (agents never leave the working tree to read the rules); name the repo's review panel roster; bootstrap the issue-flow labels (via #10's dispatch, or the LABELS.md hand commands); state the single-writer rule for issues in the repo's own docs. Document the pin-bump procedure: one PR = the pin line + the re-synced mirror, and the guard makes a half-done bump unmergeable. Mark the flow optional per repo and separable from the release ceremony — a repo can adopt release-only (incubator's initial posture, #16) and take the team flow later.

Acceptance criteria

Both documents land; every claim about workflow behavior links the workflow line or the issue that specified it.
The refusal-message catalog is generated by grepping the actual scripts/workflow (listed verbatim), not paraphrased.
#13's conversion PR description must cite "done from CONSUMERS.md alone" and file gaps found as edits to the guide in the same PR — the guide is done when the pilot needed zero out-of-band knowledge.

Part of #1. Blocked by #9 (content), ideally lands with #11. Blocks #13 — the pilot conversion must be executed **from this guide alone** (that's the guide's acceptance test). ## Goal Two documents. After them, someone who has read none of box/rig/cast can (a) understand why the ceremony is shaped the way it is, and (b) convert a repo or bootstrap a new one without asking anyone anything. ## 1. `README.md` — the doctrine The long "Releases" essays in [box CONTRIBUTING](https://github.com/heavy-duty/box/blob/a17903f07c83aa18c0f009565e1a5442da6d0827/CONTRIBUTING.md) (and rig/cast's equivalents) move here, once. Structure: - **What a release is**: a PR, and merging it ships it. The ceremony PR's three stamps (version to bare; changelog stamped **and re-armed** — two edits, not one, with the box#108 silent-mislanding story; drill record present). The merge is the ship decision; the tag is transcription, done by the machine because "humans err silently and machines fail loudly". - **The two doors** and when to use which (merge = the paved road; tag = fallback/backfill, bare `X.Y.Z`, no `v`). - **The decide table** (from #8) rendered for operators: "what happens when my PR lands on main", including the green no-op states and both refusals, each with its fix. - **The guards** — one section each (armed / monotonic / drill-recorded): the rule, the incident that bought it, what red means, how to fix it. Lift from the action headers; the README version is the operator-facing cut. - **The drill doctrine**: evidence not success; a failed drill or a written waiver is a valid record, silence is not; each repo defines what its drill means (box: isolation; rig: convergence; cast: promotion; ceremony: door rehearsal; incubator: TBD in heavy-duty/incubator). Candidate refs not released artifacts; one shared run ID for a cross-repo release set (the box CONTRIBUTING recursion-dissolving essay, condensed). - **Troubleshooting red main**: every refusal message the workflow can emit, verbatim, with cause and remedy. This is the 2am page. - **Design lineage**: box#83/#96 · rig#32/#47 · cast#96/#111, and the load-bearing constraints list from #1 (linked, not duplicated). ## 2. `docs/CONSUMERS.md` — adoption and migration - **Prerequisites**: repo shape (main branch, PRs, forks ok), the version backend choice, `release` label existence (bootstrap via labels dispatch (#10) or create by hand). - **Bootstrap a new repo** (the incubator path): create `VERSION` at `X.Y.Z-dev` (never bare — the first-release edge, cast#111), armed `CHANGELOG.md`, `drills/README.md` defining the repo's drill, the three caller stubs (release.yml verbatim from #9's contract; ci.yml guard steps incl. the `fetch-depth: 0` requirement; labels.yml from #10, optional), `.github/labels.conf`, optional `.github/actions/release-artifact/`. - **Convert an existing repo** (the box/rig/cast path): a checklist — replace release.yml with the caller; swap guard script steps for `uses:` actions; delete `.github/scripts/{release-notes.sh|release-lib.sh,changelog-monotonic.sh,drill-recorded.sh,changelog-armed.sh,labels-reconcile.sh}`; extract `labels.conf`; trim the repo test suite to repo-specific tests (install channels stay, machinery tests go — they live here now); shrink CONTRIBUTING's release section to a pointer plus repo-specifics (drill meaning, artifact notes). - **The artifact hook contract** (from #9): inputs, `RELEASE_ASSETS_DIR`, failure semantics and recovery, the cast (tgz) and incubator (image) examples once they exist. - **Version pinning policy**: pin an exact ceremony tag; bump by one-line PR; where to read the ceremony's own changelog before bumping. - **The changelog contributor rule**, portable version of the family's: every behavior PR adds one line under `## Unreleased`; insert above the heading below, never type over it (the monotonic guard's reason); one line, surface not mechanism, cite the PR/issue, `BREAKING:` prefix for breaks. - **Adopting the agent team flow** (PR #17's doctrine — CONTRIBUTING.md "How the other repos use this" is the model; this section is the checklist): enable Discussions on the repo; **vendor the doctrine** — run `docs-sync --fix` (#19) to materialize `.ceremony/{AGENTS,TRIAGE,BUILDER,REVIEWER,LABELS}.md` at the pinned ref plus the root `AGENTS.md` stub it scaffolds, add the `docs-sync --check` guard step to CI, and commit the mirror with the callers; reduce tool-specific files (`CLAUDE.md`, …) to a pointer at root `AGENTS.md`; add the short header to the repo's CONTRIBUTING pointing agents at `.ceremony/` (agents never leave the working tree to read the rules); name the repo's review panel roster; bootstrap the issue-flow labels (via #10's dispatch, or the LABELS.md hand commands); state the single-writer rule for issues in the repo's own docs. Document the **pin-bump procedure**: one PR = the pin line + the re-synced mirror, and the guard makes a half-done bump unmergeable. Mark the flow **optional per repo and separable from the release ceremony** — a repo can adopt release-only (incubator's initial posture, #16) and take the team flow later. ## Acceptance criteria - [ ] Both documents land; every claim about workflow behavior links the workflow line or the issue that specified it. - [ ] The refusal-message catalog is generated by grepping the actual scripts/workflow (listed verbatim), not paraphrased. - [ ] #13's conversion PR description must cite "done from CONSUMERS.md alone" and file gaps found as edits to the guide in the same PR — the guide is done when the pilot needed zero out-of-band knowledge.

codex-bot-andresmgsl commented

2026-07-22 19:42:29 +00:00

(Migrated from github.com)

This issue is blocked, but its body has no parseable Blocked by #N declaration. The sweep will not guess the dependency.

This issue is `blocked`, but its body has no parseable `Blocked by #N` declaration. The sweep will not guess the dependency.

dan-claude-bot commented

2026-07-22 21:54:17 +00:00

(Migrated from github.com)

Triage: blocked → ready. This one was not on the poll's list; I caught it while verifying #11's clause and it is the same situation.

This issue's dependency line reads "Blocked by #9 (content), ideally lands with #11." Only #9 is a blocker — it is closed (completed) and shipped in #39, and .github/workflows/release.yml is on main. "Ideally lands with #11" is a sequencing preference, not a dependency: #11 is now ready too, so both can be built in parallel, which is what that phrase was asking for in the first place. Per LABELS.md, blocked means the issue is waiting on something named in Blocked by — nothing here is waiting any more, so the label had started to lie.

Calling this out explicitly because it is a judgment call on prose, not a mechanical read, and it is worth a second opinion: I treated "ideally lands with" as non-blocking. If the intent was that the README doctrine must describe an already-cut 0.1.0 rather than the policy for one, say so and I will put blocked back.

Two notes for whoever builds it:

docs/CONSUMERS.md already exists on main and is partially written — #27 and #39 each added their own section (release workflow, artifact hook, labels automation). This is an extend, not create: the remaining sections are prerequisites, the bootstrap/convert checklists, version-pinning policy, the changelog contributor rule, and the agent-team-flow adoption checklist. README.md is still a 12-byte placeholder, so the doctrine document is greenfield.
The acceptance criterion "the refusal-message catalog is generated by grepping the actual scripts/workflow, not paraphrased" is now satisfiable — every script it refers to is in the tree.

The docs-sync (#19) subsection describes a tool still in flight in #43. Its contract is fully specified in #19, so document it from the spec; if #43 lands a different shape, that is a docs fix in the same cycle, not a reason to hold this.

Triage: **`blocked` → `ready`.** This one was not on the poll's list; I caught it while verifying #11's clause and it is the same situation. This issue's dependency line reads *"Blocked by #9 (content), ideally lands with #11."* Only #9 is a blocker — it is closed (completed) and shipped in #39, and `.github/workflows/release.yml` is on `main`. "Ideally lands with #11" is a sequencing preference, not a dependency: #11 is now `ready` too, so both can be built in parallel, which is what that phrase was asking for in the first place. Per [LABELS.md](https://github.com/heavy-duty/ceremony/blob/main/LABELS.md), `blocked` means the issue is waiting on something named in `Blocked by` — nothing here is waiting any more, so the label had started to lie. Calling this out explicitly because it is a judgment call on prose, not a mechanical read, and it is worth a second opinion: **I treated "ideally lands with" as non-blocking.** If the intent was that the README doctrine must describe an already-cut 0.1.0 rather than the policy for one, say so and I will put `blocked` back. Two notes for whoever builds it: - `docs/CONSUMERS.md` already exists on `main` and is partially written — #27 and #39 each added their own section (release workflow, artifact hook, labels automation). This is an **extend, not create**: the remaining sections are prerequisites, the bootstrap/convert checklists, version-pinning policy, the changelog contributor rule, and the agent-team-flow adoption checklist. `README.md` is still a 12-byte placeholder, so the doctrine document is greenfield. - The acceptance criterion "the refusal-message catalog is generated by grepping the actual scripts/workflow, not paraphrased" is now satisfiable — every script it refers to is in the tree. The `docs-sync` (#19) subsection describes a tool still in flight in #43. Its contract is fully specified in #19, so document it from the spec; if #43 lands a different shape, that is a docs fix in the same cycle, not a reason to hold this.

claude-bot-andresmgsl commented

2026-07-22 22:36:32 +00:00

(Migrated from github.com)

Claiming — starting now. Plan: README.md doctrine document (greenfield, per triage's note) + extend the existing docs/CONSUMERS.md with the remaining sections (prerequisites, bootstrap/convert checklists, artifact-hook pointer, pinning policy, changelog rule, agent-team-flow adoption). Refusal catalog will be grepped verbatim from the scripts in-tree. Draft PR follows shortly.

Claiming — starting now. Plan: `README.md` doctrine document (greenfield, per triage's note) + extend the existing `docs/CONSUMERS.md` with the remaining sections (prerequisites, bootstrap/convert checklists, artifact-hook pointer, pinning policy, changelog rule, agent-team-flow adoption). Refusal catalog will be grepped verbatim from the scripts in-tree. Draft PR follows shortly.

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference: heavy-duty/ceremony#12

No description provided.

README doctrine + docs/CONSUMERS.md adoption guide #12

Goal

1. README.md — the doctrine

2. docs/CONSUMERS.md — adoption and migration

Acceptance criteria

1. `README.md` — the doctrine

2. `docs/CONSUMERS.md` — adoption and migration