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

LABELS.md / TRIAGE.md / BUILDER.md — the attention contract #85

New issue
Closed
opened 2026-07-23 17:21:17 +00:00 by dan-claude-bot · 2 comments
dan-claude-bot commented 2026-07-23 17:21:17 +00:00 (Migrated from github.com)
Copy link

Part of #83. Blocked by #84 (same file, and a contract must not describe a label the taxonomy does not yet list). From discussion #82, approved by @danmt.

All line references pinned at 87f2432.

Context

#84 makes the label exist. This makes it mean something: who may set it, who must clear it, what it is not, and what nothing does about it. Without this, attention is a colored word — and the failure mode is specific and known, because the family already lived it with state:needs-rebase: a label whose contract is folklore gets applied to two different situations and then lies about both (LABELS.md L41-L45).

The incident that bought the label is on #16: a ruling that authorized the last open acceptance criterion of a claimed issue, addressed to its assignee by name, unowned for over an hour because every duty loop in this fleet reads state and none reads prose. #83 carries that story; this file carries the rules.

Spec

Decisions. Do not reopen them in the PR.

  • D1 — the contract, in LABELS.md, next to offsite's paragraph (L131-L140): attention says a demand is parked on this issue for its assignee. Anyone who needs that assignee's hands sets it — triage, the operator, a sibling agent. The assignee alone clears it, and clearing is the ack.
  • D2 — issue-only. PRs have the state machine and the review-request channel; a second wake there would restate state:addressing and eventually disagree with it.
  • D3 — additive, never a substitute. It composes with ready/claimed/blocked and with needs-ruling. The queue invariant ignores it by construction.
  • D4 — it pauses no clock. Unlike offsite (#68) and needs-ruling (#52), which record silence that is legitimate, an unanswered attention is silence that is not: the 48h reclaim should take that claim, and does. Say this explicitly — the reader who knows the other two flags will assume the third behaves like them.
  • D5 — the ack is the removal, and it is the session's first act, together with a short pickup comment. Rationale to state: the removal re-arms the wake for the next demand, an unanswered flag is auditable evidence on the board, and a session that dies before acking is simply relaunched, because the flag is still up.
  • D6 — an attention without an assignee is a board bug, not a demand. Anyone may assign or remove it. Nothing enforces this.
  • D7 — the three-way distinction, stated once: attention — an assignee owes a move; needs-ruling — a human owes a decision, under the escalation contract and ladder (BUILDER.md, the ruling ask); a bare @-mention — an FYI that demands nothing, which stays perfectly fine and must not be deprecated by this change. A demand that is itself a human decision carries needs-ruling; it does not carry both.
  • D8 — no machinery, and say so. Nothing in actions/ sets, clears, reads or validates attention (#84 asserts that with tests). The doc states it, for the same reason BUILDER.md's claim-counting sentence does: so nobody later builds enforcement believing it was specified here and dropped.
  • D9 — triage's side, one sentence in TRIAGE.md: when the next move on an issue belongs to its assignee and triage delivered that move in prose — a ruling closed out, a directive, an answered builder question that unblocks work — triage sets attention in the same comment. It is not a substitute for minting work, and it is not needs-ruling.
  • D10 — the builder's side, in BUILDER.md's Claiming section (L39-L63): an attention on your claim is picked up as D5 says. Tie it to the parked claim that already lives there — a demand landing on a parked claim is usually the unpark, and unparking takes the slot back under the existing rule (L52-L61). Do not restate the parked-claim rule; reference it.

Tasks

  • LABELS.md — the contract paragraph (D1–D6), placed with the other cross-cutting flag prose, plus the three-way distinction (D7) wherever it reads as one sentence rather than a new stanza.
  • TRIAGE.md — one sentence for D9, inside an existing duty (the escalate outcome's close-out, or backlog hygiene), not as a new section.
  • BUILDER.md — D10 in Claiming, adjacent to the park declaration.
  • CHANGELOG.md — one line under ## Unreleased, inserted above the heading below it.

Acceptance criteria

  • An agent who reads only LABELS.md can answer, without asking: who sets it, who clears it, when the clearing happens, whether it goes on PRs, and whether it pauses the reclaim clock.
  • The needs-ruling / attention / bare-mention distinction is present and mutually exclusive: no reader could conclude that a human decision should be parked with attention, or that an FYI needs a label.
  • LABELS.md states that the machine never sets, clears or reads the flag, and that no reconciler path enforces the assignee requirement.
  • LABELS.md states that attention grants no clock exemption, and contrasts it with offsite and needs-ruling so the analogy a reader would otherwise draw is closed off.
  • TRIAGE.md names setting attention as part of delivering a move to an assignee in prose, in one sentence.
  • BUILDER.md tells the assignee to ack by removing the label as the first act of the pickup, and connects an incoming demand to unparking without restating the parked-claim rule.
  • The diff touches LABELS.md, TRIAGE.md, BUILDER.md, CHANGELOG.md and nothing else — no actions/ change, no FLEET.md change (that is #86), no second label.
  • The #16 incident and the rejected mention-poll are cited once, so the file records why the label exists and why the obvious alternative is not coming back.

Test plan

  • test/run.sh green and the lint scripts clean — this carries no executable behavior, so the run proves the edit broke nothing that reads the tree.
  • docs-sync --check: all three files are in docs/VENDORED.txt, so every governed repo's .ceremony/ mirror drifts on merge and refreshes at its next docs-sync --fix. Say so in the PR body.
  • The read-through cases that must fail: a reader who concludes that attention buys a claim more time before reclaim; a reader who parks a human decision on it instead of needs-ruling; a reader who thinks a bare mention is now discouraged. If the wording admits any of the three, it is wrong.
  • Every permalink pinned to a SHA, never main.

Dependencies

Blocked by #84. Blocks #86. Part of #83.

Part of #83. Blocked by #84 (same file, and a contract must not describe a label the taxonomy does not yet list). From discussion [#82](https://github.com/heavy-duty/ceremony/discussions/82), approved by @danmt. All line references pinned at [`87f2432`](https://github.com/heavy-duty/ceremony/tree/87f243299d17b1a3831c3345fa11fa638eb21b1d). ## Context #84 makes the label exist. This makes it mean something: who may set it, who must clear it, what it is not, and what nothing does about it. Without this, `attention` is a colored word — and the failure mode is specific and known, because the family already lived it with `state:needs-rebase`: a label whose contract is folklore gets applied to two different situations and then lies about both ([LABELS.md L41-L45](https://github.com/heavy-duty/ceremony/blob/87f243299d17b1a3831c3345fa11fa638eb21b1d/LABELS.md#L41-L45)). The incident that bought the label is on [#16](https://github.com/heavy-duty/ceremony/issues/16#issuecomment-5061051198): a ruling that authorized the last open acceptance criterion of a `claimed` issue, addressed to its assignee by name, unowned for over an hour because every duty loop in this fleet reads state and none reads prose. #83 carries that story; this file carries the rules. ## Spec Decisions. Do not reopen them in the PR. - **D1 — the contract, in `LABELS.md`, next to `offsite`'s paragraph ([L131-L140](https://github.com/heavy-duty/ceremony/blob/87f243299d17b1a3831c3345fa11fa638eb21b1d/LABELS.md#L131-L140)):** `attention` says a demand is parked on this issue for its **assignee**. Anyone who needs that assignee's hands sets it — triage, the operator, a sibling agent. The **assignee alone** clears it, and clearing is the ack. - **D2 — issue-only.** PRs have the state machine and the review-request channel; a second wake there would restate `state:addressing` and eventually disagree with it. - **D3 — additive, never a substitute.** It composes with `ready`/`claimed`/`blocked` and with `needs-ruling`. The queue invariant ignores it by construction. - **D4 — it pauses no clock.** Unlike `offsite` ([#68](https://github.com/heavy-duty/ceremony/issues/68)) and `needs-ruling` ([#52](https://github.com/heavy-duty/ceremony/issues/52)), which record silence that is legitimate, an unanswered `attention` is silence that is not: the 48h reclaim should take that claim, and does. Say this explicitly — the reader who knows the other two flags will assume the third behaves like them. - **D5 — the ack is the removal, and it is the session's first act,** together with a short pickup comment. Rationale to state: the removal re-arms the wake for the next demand, an unanswered flag is auditable evidence on the board, and a session that dies before acking is simply relaunched, because the flag is still up. - **D6 — an `attention` without an assignee is a board bug**, not a demand. Anyone may assign or remove it. Nothing enforces this. - **D7 — the three-way distinction, stated once:** `attention` — an assignee owes a **move**; `needs-ruling` — a human owes a **decision**, under the escalation contract and ladder ([BUILDER.md, the ruling ask](https://github.com/heavy-duty/ceremony/blob/87f243299d17b1a3831c3345fa11fa638eb21b1d/BUILDER.md)); a bare `@`-mention — an **FYI that demands nothing**, which stays perfectly fine and must not be deprecated by this change. A demand that is itself a human decision carries `needs-ruling`; it does not carry both. - **D8 — no machinery, and say so.** Nothing in `actions/` sets, clears, reads or validates `attention` (#84 asserts that with tests). The doc states it, for the same reason [BUILDER.md's claim-counting sentence](https://github.com/heavy-duty/ceremony/blob/87f243299d17b1a3831c3345fa11fa638eb21b1d/BUILDER.md#L52-L61) does: so nobody later builds enforcement believing it was specified here and dropped. - **D9 — triage's side, one sentence in `TRIAGE.md`:** when the next move on an issue belongs to its assignee and triage delivered that move in prose — a ruling closed out, a directive, an answered builder question that unblocks work — triage sets `attention` in the same comment. It is not a substitute for minting work, and it is not `needs-ruling`. - **D10 — the builder's side, in `BUILDER.md`'s Claiming section ([L39-L63](https://github.com/heavy-duty/ceremony/blob/87f243299d17b1a3831c3345fa11fa638eb21b1d/BUILDER.md#L39-L63)):** an `attention` on your claim is picked up as D5 says. Tie it to the parked claim that already lives there — a demand landing on a parked claim is usually the **unpark**, and unparking takes the slot back under the existing rule ([L52-L61](https://github.com/heavy-duty/ceremony/blob/87f243299d17b1a3831c3345fa11fa638eb21b1d/BUILDER.md#L52-L61)). Do not restate the parked-claim rule; reference it. ## Tasks - [ ] `LABELS.md` — the contract paragraph (D1–D6), placed with the other cross-cutting flag prose, plus the three-way distinction (D7) wherever it reads as one sentence rather than a new stanza. - [ ] `TRIAGE.md` — one sentence for D9, inside an existing duty (the escalate outcome's close-out, or backlog hygiene), not as a new section. - [ ] `BUILDER.md` — D10 in Claiming, adjacent to the park declaration. - [ ] `CHANGELOG.md` — one line under `## Unreleased`, inserted **above** the heading below it. ## Acceptance criteria - [ ] An agent who reads only `LABELS.md` can answer, without asking: who sets it, who clears it, when the clearing happens, whether it goes on PRs, and whether it pauses the reclaim clock. - [ ] The `needs-ruling` / `attention` / bare-mention distinction is present and mutually exclusive: no reader could conclude that a human decision should be parked with `attention`, or that an FYI needs a label. - [ ] `LABELS.md` states that the machine never sets, clears or reads the flag, and that no reconciler path enforces the assignee requirement. - [ ] `LABELS.md` states that `attention` grants **no** clock exemption, and contrasts it with `offsite` and `needs-ruling` so the analogy a reader would otherwise draw is closed off. - [ ] `TRIAGE.md` names setting `attention` as part of delivering a move to an assignee in prose, in one sentence. - [ ] `BUILDER.md` tells the assignee to ack by removing the label as the first act of the pickup, and connects an incoming demand to unparking without restating the parked-claim rule. - [ ] The diff touches `LABELS.md`, `TRIAGE.md`, `BUILDER.md`, `CHANGELOG.md` and nothing else — no `actions/` change, no `FLEET.md` change (that is #86), no second label. - [ ] The [#16 incident](https://github.com/heavy-duty/ceremony/issues/16#issuecomment-5061051198) and the rejected mention-poll are cited once, so the file records why the label exists and why the obvious alternative is not coming back. ## Test plan - `test/run.sh` green and the lint scripts clean — this carries no executable behavior, so the run proves the edit broke nothing that reads the tree. - `docs-sync --check`: all three files are in [`docs/VENDORED.txt`](https://github.com/heavy-duty/ceremony/blob/87f243299d17b1a3831c3345fa11fa638eb21b1d/docs/VENDORED.txt), so every governed repo's `.ceremony/` mirror drifts on merge and refreshes at its next `docs-sync --fix`. Say so in the PR body. - The read-through cases that must fail: a reader who concludes that `attention` buys a claim more time before reclaim; a reader who parks a human decision on it instead of `needs-ruling`; a reader who thinks a bare mention is now discouraged. If the wording admits any of the three, it is wrong. - Every permalink pinned to a SHA, never `main`. ## Dependencies Blocked by #84. Blocks #86. Part of #83.
github-actions[bot] commented 2026-07-23 17:45:47 +00:00 (Migrated from github.com)
Copy link

Every issue named by Blocked by is closed. The sweep is moving this issue to ready.

<!-- issueflow:blockers-cleared --> Every issue named by `Blocked by` is closed. The sweep is moving this issue to `ready`.
codex-bot-andresmgsl commented 2026-07-23 17:51:28 +00:00 (Migrated from github.com)
Copy link

Claimed by @codex-bot-andresmgsl. Starting the attention doctrine contract now; draft PR will follow after the first tested checkpoint.

Claimed by @codex-bot-andresmgsl. Starting the `attention` doctrine contract now; draft PR will follow after the first tested checkpoint.
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#85
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?