From 7791f2100ea8a4fbe36e886bc26b3f46bb43766c Mon Sep 17 00:00:00 2001 From: codex-bot-andresmgsl <304681515+codex-bot-andresmgsl@users.noreply.github.com> Date: Thu, 23 Jul 2026 17:52:14 +0000 Subject: [PATCH] docs: define the attention contract --- BUILDER.md | 4 ++++ CHANGELOG.md | 1 + LABELS.md | 27 +++++++++++++++++++++++++++ TRIAGE.md | 5 ++++- 4 files changed, 36 insertions(+), 1 deletion(-) diff --git a/BUILDER.md b/BUILDER.md index af5df4e..396c33d 100644 --- a/BUILDER.md +++ b/BUILDER.md @@ -49,6 +49,10 @@ triage bug, and the move is to say so on the issue, not to guess. ([#52](https://github.com/heavy-duty/ceremony/issues/52)) and `offsite` ([#68](https://github.com/heavy-duty/ceremony/issues/68)) exemptions already guard — a parked claim nobody can name is an abandoned one. +- **Pick up `attention` before anything else.** On your claim, first post a + short pickup comment and remove `attention`; the removal is the ack. A + demand on a parked claim is usually its unpark, so take the slot back under + the existing rule below rather than leaving the demand parked. - **Unparking is a claim like any other.** When the wait ends, the parked issue is work again and takes the slot. If you are already active elsewhere, finish or release that work first, and say which you did on diff --git a/CHANGELOG.md b/CHANGELOG.md index db62636..4b54474 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,7 @@ so entries say what changed, cite the issue, and stop. ## Unreleased +- `attention` doctrine — define its assignee-owned pickup, ack, queue and clock semantics across labels, triage, and builder roles (#85). - `attention` — add the issue-only, hand-set assignee-demand flag to the core label taxonomy (#84). - `issueflow-reconcile` — keep cross-repo references out of local dependency decisions and require triage to resolve cross-repo blockers by hand (#61). - `needs-ruling` — the cross-cutting flag for a pending human decision, excluded from `state:needs-human` and from the staleness sweep (#51). diff --git a/LABELS.md b/LABELS.md index 0140039..2136a92 100644 --- a/LABELS.md +++ b/LABELS.md @@ -140,6 +140,33 @@ repaired, and epic-completion and PR-side stale behavior are unchanged. The sweep tells the assignee once when every visible cross-referenced PR has closed; it only tells, and never clears the flag or changes the claim. +`attention` is issue-only and says a demand is parked on an issue for its +assignee. Anyone who needs that assignee's hands — triage, the operator, or a +sibling agent — sets it. The assignee alone clears it, as the first act of +pickup together with a short comment; that removal is the acknowledgement +and re-arms the flag for the next demand. If the session dies before the ack, +the still-visible flag launches the next pickup instead. An unanswered flag +is auditable evidence on the board. + +The flag is additive: it composes with `ready`, `claimed`, or `blocked` and +with `needs-ruling`, and never substitutes for queue state. It pauses no +clock. Unlike `offsite` and `needs-ruling`, which make silence legitimate, +unanswered `attention` is exactly the silence the 48-hour reclaim should +take. It is hand-set doctrine only: nothing in `actions/` sets, clears, +reads, or validates it, and no reconciler enforces the assignee requirement. +An `attention` issue without an assignee is therefore a board bug, not a +demand; anyone may assign it or remove the flag. + +The three signals are mutually distinct: `attention` means an assignee owes +a move; `needs-ruling` means a human owes a decision under +[the escalation contract and ladder](BUILDER.md#the-ruling-ask); and a bare +`@`-mention is an FYI that demands nothing and remains perfectly fine. A +demand that is itself a human decision carries `needs-ruling`, never both. +This distinction records the +[#16 missed-ruling incident](https://github.com/heavy-duty/ceremony/issues/16#issuecomment-5061051198) +and why the rejected mention poll is not returning: ordinary thread traffic +re-arms mentions, but only the writer can declare that a move is owed (#83). + ## Scope — which surface? (PRs and issues, any number) All scopes share one calm color, `#C5DEF5` — scopes locate, states alert. The diff --git a/TRIAGE.md b/TRIAGE.md index 2bfd8a3..6a05966 100644 --- a/TRIAGE.md +++ b/TRIAGE.md @@ -55,7 +55,10 @@ is the failure this whole flow exists to prevent. ([#50 D13–D14](https://github.com/heavy-duty/ceremony/issues/50)). You set the flag, so you also close it out ([LABELS.md](LABELS.md)): judge when agreement is reached, record the ruling as a decision in one comment, - remove the label, and return the issue to its flow in that same comment. + remove the label, and return the issue to its flow in that same comment; + when that ruling or any directive or answered builder question delivers + the assignee's next move in prose, set `attention` in the same comment. + This is not a substitute for minting work or for `needs-ruling`. 4. **Decline.** Real idea, wrong repo or wrong time. Say why plainly, link where it belongs if anywhere, close. A refusal with reasons is a good outcome; a zombie discussion is not.