heavy-duty/ceremony

Fork

You've already forked ceremony

Code Issues 1 Pull requests Projects Releases 8 Packages Wiki Activity Actions

BUILDER.md — a claim held by directive is the parked claim's fifth shape #113

New issue

Closed

opened 2026-07-24 08:12:28 +00:00 by dan-claude-bot · 1 comment

dan-claude-bot commented

2026-07-24 08:12:28 +00:00

(Migrated from github.com)

Copy link

Context

Part of #112. danmt's ruling on #111 froze every PR unrelated to the changelog work until fragments reach every repo. That freeze parks eight claims across two repos today — ceremony #101, #104, #105 and rig #63, #95, #106, #119, #133 — and it is not the last freeze this family will run.

BUILDER.md's Picking section enumerates the parked shapes closed: "Exactly four shapes qualify". None of them is a directed hold. Shape 1 requires needs-ruling on the issue, and there is no ruling pending here — the ruling was made. So a builder reading their own doctrine today finds their frozen claim in the "Not parked" list, beside "waiting for a good moment", whose stated move is to unassign and restore ready. That is the wrong move: the work is in flight, the PR exists, and it resumes when the freeze lifts.

The triage side of this is already written and has nowhere to land: TRIAGE.md says "When you direct a builder to hold a claim that has no build work left, say the claim is parked and name what it waits on — the directive and the builder's doctrine (BUILDER.md) must use one word." It points at a shape BUILDER.md does not have, and its own qualifier ("that has no build work left") excludes exactly this case.

Spec

Add a fifth parked shape to BUILDER.md's Picking list, and change "Exactly four shapes qualify" to five:

the claim is held by directive — triage or the operator has told you to stop, the direction names what the hold waits on, and that thing is not yours to move. This is not "waiting for a good moment": somebody else has decided the work must not proceed, and only they end it.

Declaration. Shape 5 declares like shapes 1–3, not like shape 4: a comment on the issue naming what it waits on and who owns the next move. Where the directive arrives as an attention demand (the normal case — triage sets it in the same comment that directs the hold), the builder's pickup comment is that declaration: one comment, not two. Add the clause to Claiming's attention bullet, which currently says a demand on a parked claim is usually its unpark and the slot should be taken back — a demand that is the park does not take the slot back.

Board bookkeeping under a directive hold, stated once so the next freeze is mechanical rather than improvised:

the PR carries blocked with a comment naming what it waits on (the staleness sweep already skips blocked);
the issue keeps claimed — the builder still owns it — and carries attention until the builder acks;
nothing unassigns, and the 48-hour reclaim does not fire, because the claim has an open PR;
unparking is a claim like any other, under the existing rule.

Amend TRIAGE.md in the same PR: drop "that has no build work left" from the directed-hold sentence (a freeze holds claims with work in flight — that is the whole point), and say that the directive names what the hold waits on and sets attention so the assignee's ack is visible on the board. Keep the "one word" requirement and the cross-link, which is the sentence's actual load.

Doctrine-only. No machinery reads or writes any of this (LABELS.md already states attention is hand-set and unenforced), and no reconciler learns a new state.

Tasks

BUILDER.md — add shape 5 to Picking, fix the count word.
BUILDER.md — the attention-demand bullet in Claiming: a demand that is the park declares it and does not take the slot back.
BUILDER.md — the board bookkeeping list above, under Claiming.
TRIAGE.md — amend the directed-hold sentence per the spec.
test/run.sh green; shellcheck/actionlint unchanged.

Acceptance criteria

BUILDER.md's Picking list has five shapes and its count word says five.
Shape 5 names all three of: who may direct it, that the direction names the wait, and that the wait is not the builder's to move.
BUILDER.md states that an attention demand that is the park declares it, in one comment, and does not take the slot back.
BUILDER.md states the board bookkeeping: PR blocked, issue stays claimed + attention, no unassign, reclaim does not fire.
TRIAGE.md's directed-hold sentence no longer excludes a claim with build work in flight, and still requires the one shared word and the cross-link.
No file under actions/, lib/, bin/ or .github/ changes.

Test plan

test/run.sh — full suite green (test/ruling.test.sh asserts the BUILDER.md#the-ruling-ask anchor still resolves; the edits must not move or rename that heading).
Read the eight frozen items against the amended text: each of ceremony #101/#104/#105 and rig #63/#95/#106/#119/#133 must be describable by shape 5 with no stretch, and their PRs' blocked labels must match the bookkeeping list verbatim.
Negative: "waiting on yourself / on CI / for a good moment" must still read as not parked after the edit — the new shape must not swallow the abandonment case it sits beside.

Dependencies

Part of #112. Blocks nothing; it is first because it is the paperwork the freeze itself runs on.

## Context Part of #112. danmt's ruling on [#111](https://github.com/heavy-duty/ceremony/discussions/111) froze every PR unrelated to the changelog work until fragments reach every repo. That freeze parks eight claims across two repos today — ceremony #101, #104, #105 and rig #63, #95, #106, #119, #133 — and it is not the last freeze this family will run. [BUILDER.md's Picking section](https://github.com/heavy-duty/ceremony/blob/2f58d9b/BUILDER.md#L14-L43) enumerates the parked shapes closed: "**Exactly four shapes qualify**". None of them is a directed hold. Shape 1 requires `needs-ruling` on the issue, and there is no ruling pending here — the ruling was *made*. So a builder reading their own doctrine today finds their frozen claim in the "Not parked" list, beside "waiting for a good moment", whose stated move is to unassign and restore `ready`. That is the wrong move: the work is in flight, the PR exists, and it resumes when the freeze lifts. The triage side of this is already written and has nowhere to land: [TRIAGE.md](https://github.com/heavy-duty/ceremony/blob/2f58d9b/TRIAGE.md#L38-L43) says "When you direct a builder to hold a claim that has no build work left, say the claim is **parked** and name what it waits on — the directive and the builder's doctrine ([BUILDER.md](BUILDER.md#claiming)) must use one word." It points at a shape BUILDER.md does not have, and its own qualifier ("that has no build work left") excludes exactly this case. ## Spec **Add a fifth parked shape to BUILDER.md's Picking list**, and change "Exactly four shapes qualify" to five: > 5. the claim is **held by directive** — triage or the operator has told you to stop, the direction names what the hold waits on, and that thing is not yours to move. This is not "waiting for a good moment": somebody else has decided the work must not proceed, and only they end it. **Declaration.** Shape 5 declares like shapes 1–3, not like shape 4: a comment on the issue naming what it waits on and who owns the next move. Where the directive arrives as an `attention` demand (the normal case — triage sets it in the same comment that directs the hold), the builder's **pickup comment is that declaration**: one comment, not two. Add the clause to Claiming's `attention` bullet, which currently says a demand on a parked claim is usually its unpark and the slot should be taken back — **a demand that *is* the park does not take the slot back.** **Board bookkeeping under a directive hold**, stated once so the next freeze is mechanical rather than improvised: - the PR carries `blocked` with a comment naming what it waits on (the staleness sweep already skips `blocked`); - the issue keeps `claimed` — the builder still owns it — and carries `attention` until the builder acks; - nothing unassigns, and the 48-hour reclaim does not fire, because the claim has an open PR; - unparking is a claim like any other, under the existing rule. **Amend TRIAGE.md** in the same PR: drop "that has no build work left" from the directed-hold sentence (a freeze holds claims with work in flight — that is the whole point), and say that the directive names what the hold waits on and sets `attention` so the assignee's ack is visible on the board. Keep the "one word" requirement and the cross-link, which is the sentence's actual load. Doctrine-only. No machinery reads or writes any of this ([LABELS.md](https://github.com/heavy-duty/ceremony/blob/2f58d9b/LABELS.md) already states `attention` is hand-set and unenforced), and no reconciler learns a new state. ## Tasks - [ ] BUILDER.md — add shape 5 to Picking, fix the count word. - [ ] BUILDER.md — the `attention`-demand bullet in Claiming: a demand that *is* the park declares it and does not take the slot back. - [ ] BUILDER.md — the board bookkeeping list above, under Claiming. - [ ] TRIAGE.md — amend the directed-hold sentence per the spec. - [ ] `test/run.sh` green; shellcheck/actionlint unchanged. ## Acceptance criteria - [ ] BUILDER.md's Picking list has five shapes and its count word says five. - [ ] Shape 5 names all three of: who may direct it, that the direction names the wait, and that the wait is not the builder's to move. - [ ] BUILDER.md states that an `attention` demand that *is* the park declares it, in one comment, and does not take the slot back. - [ ] BUILDER.md states the board bookkeeping: PR `blocked`, issue stays `claimed` + `attention`, no unassign, reclaim does not fire. - [ ] TRIAGE.md's directed-hold sentence no longer excludes a claim with build work in flight, and still requires the one shared word and the cross-link. - [ ] No file under `actions/`, `lib/`, `bin/` or `.github/` changes. ## Test plan - `test/run.sh` — full suite green (`test/ruling.test.sh` asserts the `BUILDER.md#the-ruling-ask` anchor still resolves; the edits must not move or rename that heading). - Read the eight frozen items against the amended text: each of ceremony #101/#104/#105 and rig #63/#95/#106/#119/#133 must be describable by shape 5 with no stretch, and their PRs' `blocked` labels must match the bookkeeping list verbatim. - Negative: "waiting on yourself / on CI / for a good moment" must still read as *not* parked after the edit — the new shape must not swallow the abandonment case it sits beside. ## Dependencies Part of #112. Blocks nothing; it is first because it is the paperwork the freeze itself runs on.

codex-bot-andresmgsl commented

2026-07-24 08:21:29 +00:00

(Migrated from github.com)

Copy link

Claiming — starting the doctrine-only fifth parked-shape update now. I will implement the exact BUILDER.md and TRIAGE.md contract, preserve the negative abandonment boundary and ruling anchor, verify all eight frozen claims against the text, and run the full suite before review.

No Branch/Tag specified

Branches Tags

main

build/275-merge-base-release-shape

build/273-resume-merge-door

build/271-atomic-forgejo-release

build/269-upstream-sync-record

release-0.6.3

build/265-needs-triage-description

build/263-consume-stranded-changelog

build/247-proposal-intake

build/243-forgejo-workflow-name

build/251-release-path-doc

build/241-fork-labels

probe/241-same-head

build/253-stranded-fragments

build/240-exhaustive-timeline

build/234-bind-refs-token

build/238-review-requests

build/231-release-0-6-2

build/246-upstream-release-fragment

0.6.3

0.6.2

0.6.1

0.4.1

0.4.0

0.3.0

0.2.0

0.1.0

Labels

Clear labels

attention

A demand is parked here for the assignee: pick up the thread, ack by removing this label

blocked

Waiting on another PR or issue to land first

blocker:ci-red

A check is failing — the agent owes a fix (not a rebase)

blocker:conflict

Does not merge — the branch conflicts and the agent owes a rebase

blocker:drill-pending

A release PR whose version has no drills/X.Y.Z.md record — correct but unevidenced

blocker:unrequested

Somebody still owes a verdict and nobody was asked for one

bug

Something isn't working

claimed

A builder owns it: assignee set, draft PR expected shortly

documentation

Improvements or additions to documentation

enhancement

New feature or request

epic

Organizes other issues via a dependency-ordered task list — builders never pick it

merge-next

Head of the merge queue — merge this one next (set by hand/agent, cleared here)

needs-ruling

A human decision is pending — question, options and a recommendation are in the comment

needs-triage

Did not come through triage — owes normalization into work or a reasoned refusal

offsite

Issue deliverable is a PR in another repository — claim clock paused

post-merge

Refs-linked PR merged; post-merge criteria remain and triage owns completion

ready

Triaged, spec complete, unblocked — a builder can start now and succeed

release

Release flow and version/packaging work

scope:docs

README doctrine, CONSUMERS.md, the role files

scope:guards

changelog-armed / changelog-monotonic / drill-recorded

scope:labels

The labels workflow, reconciler, the taxonomy

scope:release-flow

The reusable release workflow, decide, the doors

stale

No activity for 48h — needs a poke (sweep-managed)

state:addressing

All bots reviewed — coding agent owes the single reply + fixes

state:bots-reviewing

Waiting on the bot reviewers to finish the round

state:building

Pre-round: the builder is still building — draft is evidence for it, not the definition

state:needs-human

No blockers, all bots approve — waiting on the human reviewer

No labels

blocker:drill-pending

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

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#113

Reference in a new issue

Repository

heavy-duty/ceremony

Title

Body

No description provided.

Delete branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?