Merge pull request #88 from codex-bot-andresmgsl/build/85-attention-contract

docs: define the attention contract

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

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).

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

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.