ceremony-ci-probe/drills/README.md

# Drills

What a drill means in this repo: an **end-to-end rehearsal of both doors of
the release workflow on a disposable repo**. The contract suite proves every
decision offline — facts → decide → notes against fixtures, the merge door's
step sequence replayed in release-exercise.yml — but the doors themselves
only ever run live: gating on a real push event, the tag create, the
publish, the `-dev` re-arm (release.yml's "what is honestly untested"). The
drill is where they run live *before* a version rests on them.

## The rehearsal

1. Create a scratch **private** repo. It is disposable by design — it gets
   deleted at the end.
2. Install the docs/CONSUMERS.md caller stubs, pinned to the release
   candidate ref. A branch ref works: refs are static identifiers — the
   family's own drill doctrine.

   **Except for the first release** (learned drilling 0.1.0, #11): the
   stubs' consumer path fetches ceremony at `CEREMONY_SELF_REF` — the very
   ref the first drill exists to rehearse creating — so the pure pinned
   path cannot run before some `X.Y.Z` ref exists, and a branch named like
   the tag must NOT be created on the canonical repo to paper over it (it
   would shadow the tag for every consumer until someone remembers to
   delete it). The first drill instead pins the callers to a fork ref
   carrying the candidate tree with `CEREMONY_SELF_REF` rewritten to the
   candidate SHA in every pin carrier, and records that one-line deviation
   in its record. From the second release on, this paragraph is moot.
3. Give it a fixture `VERSION` / `CHANGELOG.md` / `changelog.d/` /
   `drills/` in the armed state (`X.Y.Z-dev`, the fragments directory with
   its `README.md` marker plus at least one fragment for the ceremony to
   consume).
4. Exercise both doors, one probe at a time:

   1. a merge-door ceremony publishes exactly one release and re-arms main
      to `-dev`;
   2. a mislabeled ordinary PR is a green NOTICE no-op;
   3. a bare-version PR without the `release` label refuses;
   4. a re-run of the completed ceremony refuses;
   5. a tag-door release from a manual tag;
   6. a mismatched tag refuses.

   Every refusal must refuse **creating nothing** — a probe that leaves a
   tag or a release behind on a refusal path is a failed probe.

## The record

One file per version, `drills/X.Y.Z.md` — the shape the siblings use: what
was run, where, the result of each probe, failures written down plainly. The
record is the evidence; the scratch repo is the evidence's scaffolding and
is deleted afterwards.

`actions/drill-recorded` refuses any bare-version tree whose record is
missing or blank. A waived drill is still a record: the file says WAIVED and
why — a maintainer's call, visible and reviewable in the release PR's diff,
never a silent skip.