heavy-duty/ceremony
7
0
Fork 2
Code Issues 1 Pull requests Projects Releases 8 Packages Wiki Activity Actions

labels-reconcile.sh decide_state() — blocked excludes state:needs-human, falling to state:addressing #180

New issue
Closed
opened 2026-07-25 09:04:01 +00:00 by dan-claude-bot · 1 comment
dan-claude-bot commented 2026-07-25 09:04:01 +00:00 (Migrated from github.com)
Copy link

Context

Minted by the armed default on discussion 122 — A at 2026-07-25T09:00Z if no ruling — which fired with no ruling posted; the decision record is on that thread. During the ceremony#111 freeze, rig#126 and rig#128 carried blocked and state:needs-human at once: each round had genuinely finished, so the state label was true about the round and false about the merge — and rig#126 was merged seven minutes after the reconciler wrote the green label.

The defect: decide_state() joins the two axes only through blockers() (L370–L379), and blockers() emits branch facts only — conflict, ci-red, unrequested (L322–L362). The hand-set blocked label is never consulted on this axis, so a frozen PR whose round completes lands on state:needs-human and lies about the one thing that label promises (LABELS.md L22: "this PR could be merged right now"). This is a decide-time omission, not a missing input — the same script already reads the label for the staleness skip at L672.

Spec

Decisions, made:

  • blocked becomes the second exclusion on state:needs-human, exactly parallel to needs-ruling (L381–L393): when round_state() says state:needs-human and has_label blocked, decide_state() returns state:addressing. One condition; nothing else in the function moves.
  • It is not a blockers() emission. BLOCKERS is machine-owned and the converge loop strips every entry the current facts do not re-derive; blocked is hand-set intent (triage sets it; anyone may correct it), so emitting it there would strip a live hold on the next 15-minute tick — the same trap #51 names for needs-ruling.
  • state:addressing is the accepted imprecision: under a directed hold the builder owes nothing here, but "a human could merge this now" is the promise that must not lie. A dedicated fifth state (option B on the discussion) stays a separate question — do not mint it in this PR.
  • LABELS.md gets one sentence on the PR-side blocked row (L68): the reconciler refuses state:needs-human while blocked stands — the PR falls to state:addressing.
  • No new label, no bootstrap row, no consumer action beyond the pin bump consumers already take at the next release.

Tasks

  • decide_state(): add the blocked exclusion beside the needs-ruling one, with the not-a-blocker rationale in its comment
  • LABELS.md: the one sentence on the PR-side blocked row
  • test/labels-reconcile.test.sh: mirror the needs-ruling block (L529–L553) for blocked — exclusion, not-a-latch, draft, and blockers()-ignorance cases
  • changelog.d fragment, per CONTRIBUTING.md

Acceptance criteria

  • Fixture with three head-current approvals, MERGEABLE=MERGEABLE, CHECKS=SUCCESS, LABELS="blocked" → decide_state() returns state:addressing; the same fixture with LABELS="" returns state:needs-human (control)
  • Clearing the label hands off again — an exclusion, not a latch
  • blockers() output is byte-identical with and without blocked
  • A draft carrying blocked still decides state:building
  • Deleting the new condition turns at least one test red
  • LABELS.md carries the sentence; the diff introduces no new label

Test plan

test/run.sh green. The cases that must fail: the exclusion test with the condition deleted; the blockers()-ignorance test if blocked is ever emitted as a blocker:*.

Dependencies

None — ready. Blocks nothing on the board. Ruling record: discussion 122.

## Context Minted by the armed default on [discussion 122](https://github.com/heavy-duty/ceremony/discussions/122) — **A at 2026-07-25T09:00Z if no ruling** — which fired with no ruling posted; the decision record is on that thread. During the ceremony#111 freeze, [rig#126](https://github.com/heavy-duty/rig/pull/126) and [rig#128](https://github.com/heavy-duty/rig/pull/128) carried `blocked` and `state:needs-human` at once: each round had genuinely finished, so the state label was true about the round and false about the merge — and rig#126 was merged seven minutes after the reconciler wrote the green label. The defect: `decide_state()` joins the two axes only through `blockers()` ([L370–L379](https://github.com/heavy-duty/ceremony/blob/24255a97cd42a5e06c855b472819e066ee102031/actions/labels-reconcile/labels-reconcile.sh#L370-L379)), and `blockers()` emits branch facts only — conflict, ci-red, unrequested ([L322–L362](https://github.com/heavy-duty/ceremony/blob/24255a97cd42a5e06c855b472819e066ee102031/actions/labels-reconcile/labels-reconcile.sh#L322-L362)). The hand-set `blocked` label is never consulted on this axis, so a frozen PR whose round completes lands on `state:needs-human` and lies about the one thing that label promises ([LABELS.md L22](https://github.com/heavy-duty/ceremony/blob/24255a97cd42a5e06c855b472819e066ee102031/LABELS.md#L22): "this PR could be merged right now"). This is a decide-time omission, not a missing input — the same script already reads the label for the staleness skip at [L672](https://github.com/heavy-duty/ceremony/blob/24255a97cd42a5e06c855b472819e066ee102031/actions/labels-reconcile/labels-reconcile.sh#L672). ## Spec Decisions, made: - `blocked` becomes the second **exclusion** on `state:needs-human`, exactly parallel to `needs-ruling` ([L381–L393](https://github.com/heavy-duty/ceremony/blob/24255a97cd42a5e06c855b472819e066ee102031/actions/labels-reconcile/labels-reconcile.sh#L381-L393)): when `round_state()` says `state:needs-human` and `has_label blocked`, `decide_state()` returns `state:addressing`. One condition; nothing else in the function moves. - It is **not** a `blockers()` emission. `BLOCKERS` is machine-owned and the converge loop strips every entry the current facts do not re-derive; `blocked` is hand-set intent (triage sets it; anyone may correct it), so emitting it there would strip a live hold on the next 15-minute tick — the same trap #51 names for `needs-ruling`. - `state:addressing` is the accepted imprecision: under a directed hold the builder owes nothing here, but "a human could merge this now" is the promise that must not lie. A dedicated fifth state (option B on the discussion) stays a separate question — do not mint it in this PR. - LABELS.md gets one sentence on the PR-side `blocked` row ([L68](https://github.com/heavy-duty/ceremony/blob/24255a97cd42a5e06c855b472819e066ee102031/LABELS.md#L68)): the reconciler refuses `state:needs-human` while `blocked` stands — the PR falls to `state:addressing`. - No new label, no bootstrap row, no consumer action beyond the pin bump consumers already take at the next release. ## Tasks - [ ] `decide_state()`: add the `blocked` exclusion beside the `needs-ruling` one, with the not-a-blocker rationale in its comment - [ ] LABELS.md: the one sentence on the PR-side `blocked` row - [ ] `test/labels-reconcile.test.sh`: mirror the `needs-ruling` block ([L529–L553](https://github.com/heavy-duty/ceremony/blob/24255a97cd42a5e06c855b472819e066ee102031/test/labels-reconcile.test.sh#L529-L553)) for `blocked` — exclusion, not-a-latch, draft, and blockers()-ignorance cases - [ ] changelog.d fragment, per CONTRIBUTING.md ## Acceptance criteria - [ ] Fixture with three head-current approvals, `MERGEABLE=MERGEABLE`, `CHECKS=SUCCESS`, `LABELS="blocked"` → `decide_state()` returns `state:addressing`; the same fixture with `LABELS=""` returns `state:needs-human` (control) - [ ] Clearing the label hands off again — an exclusion, not a latch - [ ] `blockers()` output is byte-identical with and without `blocked` - [ ] A draft carrying `blocked` still decides `state:building` - [ ] Deleting the new condition turns at least one test red - [ ] LABELS.md carries the sentence; the diff introduces no new label ## Test plan `test/run.sh` green. The cases that must fail: the exclusion test with the condition deleted; the blockers()-ignorance test if `blocked` is ever emitted as a `blocker:*`. ## Dependencies None — `ready`. Blocks nothing on the board. Ruling record: [discussion 122](https://github.com/heavy-duty/ceremony/discussions/122).
claude-bot-andresmgsl commented 2026-07-25 09:06:07 +00:00 (Migrated from github.com)
Copy link

Claiming — starting now. Plan: add the blocked exclusion in decide_state() beside the needs-ruling one, the one LABELS.md sentence, mirror the needs-ruling test block for blocked (exclusion / not-a-latch / draft / blockers()-ignorance), and the changelog fragment. Draft PR shortly.

Claiming — starting now. Plan: add the `blocked` exclusion in `decide_state()` beside the `needs-ruling` one, the one LABELS.md sentence, mirror the needs-ruling test block for `blocked` (exclusion / not-a-latch / draft / blockers()-ignorance), and the changelog fragment. Draft PR shortly.
Sign in to join this conversation.
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
attention
blocked
blocker:ci-red
blocker:conflict
blocker:drill-pending
blocker:unrequested
bug
claimed
documentation
enhancement
epic
merge-next
needs-ruling
needs-triage
offsite
post-merge
ready
release
scope:docs
scope:guards
scope:labels
scope:release-flow
stale
state:addressing
state:bots-reviewing
state:building
state:needs-human
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#180
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?