What ceremony is for, if the engine does the coordinating — enforcement vs coordination, and the conformance contract

[dan-claude-bot]

Moved here from issue #201 by triage, 2026-08-01, verbatim below the fold. #201 was minted as a design record with no acceptance criteria and the words "do not claim this" — which is a discussion, and TRIAGE.md says so in as many words: never mint an issue to "discuss" something. It also sat four days wearing blocked with no dependency to name, which is a board that lies. Triage minted it; triage moves it. Nothing is lost — the text is unchanged, the thread is the right home for it, and if it converges I mint the work with criteria.

Its authorship stands: filed from the sherpa session at @danmt's request. The buildable slice it named, #199, has since shipped — the labels sweep was narrowed to the events that carry queue-state changes, and #209 has now detached the sweep from PR-triggered runs entirely. Both moved the reconciler in the direction this record argues about, which makes the question live rather than academic.

Open question for @danmt and the fleet, on top of the four already listed below: is the conformance-fixture idea worth a real design pass now, or does crew's engine need another release of field time first?

---

📝 DRAFT — design record, not a buildable ticket

Filed from the sherpa session at danmt's request, out of a conversation that started as "why did CI go red" and became "what is this repo for". Do not claim this. There are no acceptance criteria, deliberately: the question it holds is what ceremony is, and answering that with a task list before the shape is agreed would encode a guess as a spec.

The immediate, buildable slice is #199. This issue exists so the larger question is not re-derived from scratch in a month.

The question danmt asked

"if its the engine that does all of this reconciliation and stuff, does it make sense to keep the ceremony? its role changes? or simply is better to move all the label stuff to the engine and ceremony describes roughly how the label stuff works?"

It arrived from the cost side — the fleet exhausted its 2,000 included Actions minutes and took CI down mid-round on three PRs (#199) — but the cost is a symptom. The structural observation underneath is sharper:

The reconciler polls every fifteen minutes to re-derive state that the engine already caused. state:building → bots-reviewing → addressing → needs-human, requesting reviewers, promoting blocked → ready — every one of those transitions happens because a box did something. Having GitHub sweep the whole board on a timer to notice is backwards.

The seam is not "ceremony vs engine". It is enforcement vs coordination

The useful question for each piece of machinery is: who does it have to be adversarial to?

Enforcement must stay in CI, because it gates a merge and must be hostile to the author. changelog-armed, changelog-monotonic, drill-recorded, docs-sync, the release doors — these say "this tree may not ship." The engine is the author. An engine enforcing its own gates is a builder marking its own work as passed, which is the one thing BUILDER.md forbids outright. These also have to work for a PR a human opens by hand, with no box involved anywhere.

Coordination belongs to the actor, because the actor already knows. Board state, reviewer requests, handoff, queue promotion — the engine caused every one, and it knows the instant it happens rather than up to fifteen minutes later.

That line is clean, and it does not shrink ceremony. It moves ceremony from running the machinery to defining it.

What ceremony becomes

• The role doctrine — BUILDER.md, REVIEWER.md, TRIAGE.md, LABELS.md. Already its most valuable content, and the reason a builder can be dropped into any governed repo and behave correctly.
• The taxonomy as a schema — labels.conf stays the definition; only its application moves.
• The release ceremony and its guards — unchanged, and the part that genuinely cannot live in an actor.
• The conformance contract — new, and the point of the whole exercise. See below.

The risk that decides whether this is an improvement or a regression

A specification with no enforcement drifts. This repo has said so about itself, and it is the sentence to hold onto here:

the ONE time it was caught is the time somebody happened to look, and that is not a gate, it is luck with good manners.

It happened twice in one day while this was being discussed: CONTRIBUTING.md still described the handoff contract #197 was retiring, and it was caught by a human reading a diff. If ceremony becomes prose and crew becomes the implementation, nothing checks that crew implements what ceremony says — and the failure mode is silent divergence between the document and the fleet, which is the same defect one level up.

The answer, and the reason this reorganization is worth doing at all: ceremony ships conformance fixtures. A suite describing the expected state transitions — given this board state, these labels must result — that any engine claiming to implement the ceremony must pass. ceremony owns the contract and the tests for it; crew owns the implementation and proves it conforms.

That is a stronger role than running a cron, and it is the thing that makes "a repo that describes the development workflow, which evolves, and the system evolves with it" true rather than aspirational.

The second risk, which is less obvious and more immediate

Board state would become coupled to fleet liveness.

Today the reconciler is the one part of the system that keeps working when the fleet is down — and this fleet was down for three days this week. state:needs-human is what notify.sh reads to ping the operator. Move state into the engine and a dead fleet means no label, no ping, and a board frozen exactly when someone most needs to see that it is frozen.

That is not fatal — a dead fleet is not acting on the board anyway — but it argues for keeping a thin CI backstop that reports divergence rather than driving state. Cheap, event-driven, and the difference between a board that is stale and one that is silently wrong.

What is already moving this way

Worth recording so this reads as a direction rather than a proposal: the handoff half is already in flight. #196 and heavy-duty/crew#91 move the round summary and the handoff acts from the builder to the engine. danmt's sketch of the fuller flow — agent marks ready, engine requests reviewers and sets the reviewing state, last verdict lands, engine sets addressing or needs-human and posts the handoff, builder posts the round reply, engine appends it and sets building — is a continuation of that, not a new direction.

Open questions, listed because they are open

• What exactly is a conformance fixture here? A JSON board state plus expected labels? A replayable event log? The answer determines whether this is a weekend or a quarter.
• Does the thin backstop drive anything, or only report? Reporting is safer and weaker. Driving reintroduces the split brain.
• What happens to a repo governed by ceremony but not worked by crew? Today the reconciler serves any repo that adopts the workflow. If coordination moves to the engine, adoption without crew means adoption without board state. That may be fine — it may also be the thing that keeps a thin reconciler alive.
• Does the engine's coverage extend to human-authored PRs? It can — the duty modules already sweep every repo in the registry regardless of author — but it is a requirement, not a freebie.

Dependencies

None; nothing is blocked on this. #199 is the buildable slice and is deliberately independent: subscribing to the events that already exist and relaxing the poll is worth doing whether or not this larger move ever happens, and it does not foreclose it.

[dan-claude-bot]

🧭 needs-ruling — is the conformance-fixture idea worth a real design pass now, or does crew's engine need another release of field time first?
Options: A — design pass now, starting with "what exactly is a fixture" B — defer to a named wake condition and revisit then C — drop it; coordination stays in ceremony's reconciler and crew's engine stays an optimistic writer over it
Recommend: B, because the reconciler changed shape twice today and its latest shape has zero consumer field hours — a conformance contract written now would be written against a moving target.
Blocked: Nothing stops. #199 and #209 both shipped and this record says so itself; every issue on the board continues, and no work anywhere waits on this answer.
Default: B at 2026-08-02T18:35Z if no ruling — deferring creates nothing, forecloses nothing, and one word on this thread reverses it.

Analysis

What has moved since this was filed

This record was moved here from #201 at 17:56Z today. In the ~40 minutes since, its subject moved twice more:

• 0.4.1 shipped at 18:15Z carrying checks_state — exclude the labels workflow's own runs from the rollup verdict (a displaced sweep sets blocker:ci-red on a green PR) #208 (checks_state stops grading the label machine's own runs) and labels.yml — detach the reconcile sweep from PR-triggered runs so queue displacement never lands a cancelled check on a PR #209 (the reconcile sweep detached from PR-triggered runs entirely). Both are structural changes to how the reconciler observes the board, and both landed today.
• No consumer has adopted it. crew's labels caller still pins @0.4.0, still carries the hourly cron, still has actions: read, and crew has no labels-sweep.yml. The migration has not started.

That is the whole of my recommendation. A conformance contract is a description of the transitions an engine must produce; writing one against machinery that changed shape twice in a single day, whose newest shape has not run in a single consumer repo, encodes today's accident as tomorrow's spec. Field hours are the input the design pass is missing, and they are cheap — they accrue by waiting.

What a ruling for A would implicitly concede

Worth naming, because it is the load-bearing thing this thread does not separate: whether coordination moves to the engine at all has not been decided. The record argues the enforcement/coordination seam persuasively, but it argues it — nobody has ruled it. The conformance contract only pays for itself if coordination moves; it is the safety net for that migration, not an independent good. So a ruling for A concedes the migration in principle and then asks how to test it.

If that is the call you want to make, make it explicitly and I will mint against it. If you want the migration question put to you on its own terms first, say so and this becomes an outcome-2 "ask" instead of this ruling — I would rather re-ask than have you rule on a bundled question.

The case for each

A — design pass now. The strongest argument is the record's own: a specification with no enforcement drifts, and it happened twice in one day while the record was being written. Every week without the contract is a week of prose that nothing checks. Against it: the first open question — is a fixture a JSON board state or a replayable event log? — is the difference between a weekend and a quarter, and answering it against machinery this fresh is guesswork wearing a schema.

B — defer, with a named wake condition. Costs nothing, forecloses nothing, and buys the one input that is currently missing. Its cost is the zombie risk, so the wake condition must be concrete rather than "later" — I propose the earliest of: crew tags its next release; the first observed instance of the reconciler overwriting a state crew's engine wrote (the split-brain the record predicts, which would be the field evidence that settles the seam); or 2026-09-01. I will bring it back here at whichever fires, with what the field time actually taught.

C — drop it. Honest and cheap if you read the reorganization as not happening. Its cost is that #196 and heavy-duty/crew#91 have already moved the handoff half, so C leaves the fleet mid-migration with no contract and no plan to finish — the split brain, permanently. I do not recommend it, and I list it only because the options must be exhaustive: if the answer is "ceremony keeps running the machinery", that is a legitimate answer and it should be sayable in one word.

Housekeeping

The four questions in the record below stay open under B; they are the design pass's agenda, not blockers on this ruling. The 7-day nudge applies from this comment, and per the ladder I will fire the stated default rather than let this sit — deferring by default is the outcome that costs least if I am wrong. @danmt

[dan-claude-bot]

🧭 12h re-read — B still holds, and this morning strengthened it.

Anchored to the escalation at 2026-08-01T18:35:55Z; it is now 2026-08-02T09:26Z, 14h50m in. Re-reading the default against what has landed, rather than firing it stale at 18:35Z:

• Nothing has shipped since. main is still 80da0a8, 0.4.1 is still the newest tag, and no PR is open. So the reconciler's latest shape has ~15 hours of consumer field time — not more. That was B's whole premise and it has only aged in B's favour.
• One thing arrived overnight that bears on it, and it points the same way. #219 was filed 08:02Z and closed 08:46Z: heavy-duty/rig now runs on forgejo.heavyduty.builders, where the reconcilers cannot run at all — they shell out to gh, gh speaks /api/v3, Forgejo serves /api/v1. I verified the consequence independently on that instance's own task API: rig's labels workflow there is 161 runs, 161 failures, zero successes between 2026-08-01 18:56Z and 2026-08-02 09:15Z, while its other three workflows are green. A conformance contract written this week would be written against a reconciler that may be about to grow a second forge backend — the moving target B names, moving again. The routing question underneath it is escalated separately on #220.
• No new doubt of the kind that converts a timed default into a hard block. Deferring still creates nothing and forecloses nothing, and one word here still reverses it.

Default: stands as written — B at 2026-08-02T18:35Z. If it fires I will say so here in the comment that records it, and B owes a named wake condition, so I will name one rather than defer into fog: whichever lands first of crew's next release, or the first Forgejo-capable reconciler. Say the word and it is your wake condition instead, or your ruling. @danmt

[dan-claude-bot]

✅ Decision — the stated default B fired, and it is deferral with a named wake, not a drop

Anchored to the escalation at 2026-08-01T18:35:55Z and its 12h re-read, which re-stated Default: B at 2026-08-02T18:35Z unchanged. No ruling arrived, so B fired at that instant. This comment records it 18 hours late; nothing acted on the gap — no issue was minted, no fixture designed, no builder held — so the delay costs the record its punctuality and nothing else. The rung past 24h puts the pick with triage either way, and B is the pick: the conformance-fixture design pass is deferred to a named wake condition.

@danmt overturns this with one word here at any time; deferral forecloses nothing.

B's premise, re-measured today rather than restated

The premise was "a conformance contract written now would be written against a moving target". Both halves have moved, and both point the same way:

• Field hours now exist, and they are ~1 day old. crew has adopted the two-caller split — labels.yml and labels-sweep.yml both pin @0.4.1, where at the escalation crew pinned @0.4.0 and had no sweep caller at all. That is the migration starting, exactly as B wanted it to before anyone writes a schema.
• And the target moved again this morning. 0.5.0 shipped at 12:40Z carrying three changes to the very transitions a conformance contract would describe: per-author required sets (actions/labels-reconcile + BUILDER.md/REVIEWER.md — per-author review panels: labels.conf gains panel[<login>]=, resolved at the one point the required set is computed #224), draft losing to a standing verdict in decide_state (Draft outranks the review round in decide_state, so a re-drafted PR mid-round reads state:building #205), and the escalation selector the needs-ruling ladder reads (lib/ruling.sh — the shape check grades the earliest in-window comment, so a round reply outranks the escalation beside it #226). A contract drafted yesterday would already be describing a machine that no longer exists — and crew's adoption of 0.5.0 is crew#320, still in review.

What has changed that the escalation could not have known, and it sharpens the wake

There may be two reconcilers before there is one contract. The Forgejo copy of this repo is building a two-backend forge shim under its operator's ruling — lib/forge.sh selecting a github or forgejo backend, every reconciler call site ported onto it, in panel round there now. Discussion #220 carries the measurements and the routing decision. A conformance contract is a description of the transitions an implementation must produce; the useful moment to write one is when there are two implementations to hold to it, not one that is mid-fork.

What B does not concede, restated because it is load-bearing

Whether coordination moves to the engine at all is still unruled. The record argues the enforcement/coordination seam; nobody has decided it. B defers the safety net for that migration, not the migration, and picking B is not triage deciding the seam by attrition. If you want that question put on its own terms, say so and I will ask it as its own thread rather than bundle it here.

The wake condition, concretely

Whichever of these lands first, I bring this record back — reopened here, with what the field time actually taught:

1. crew tags its next release (its newest tag is still 0.1.0), or
2. a second reconciler implementation exists — the Forgejo forge-shim PR merges on that instance, or
3. 2026-09-01, absolutely.

Closing the discussion so the board does not carry an open thread that is waiting on a date. The record survives closed and is the first thing the wake reopens.

Triage, 2026-08-03.