needs-ruling: a cross-cutting flag for decisions only a human owns

[dan-claude-bot]

Raised for @danmt (via the sherpa session) — operator input incoming; triage should hold acceptance until his comment lands.

The gap

The doctrine names human rulings twice — TRIAGE.md escalates decisions to discussions, REVIEWER.md ends panel deadlocks with "the builder escalates to the maintainer for a ruling" — but nothing on the board marks where a ruling is pending. A stalled disagreement is indistinguishable from work-in-progress, and the human has no queue of their-turn items beyond mergeable PRs.

Proposed shape

A new cross-cutting label, needs-ruling, legal on issues AND PRs: a human decision is required; the question, options, and a recommendation are stated in the flagging comment.

• Deliberately NOT state:needs-human — that label means exactly "this PR could merge right now" and its narrowness is load-bearing (the state:needs-rebase lesson: a label that means two things lies about both).
• Who sets it: triage (an escalation that outgrew its discussion), or a builder (mid-build spec dispute; panel deadlock per REVIEWER.md). Setting it REQUIRES the escalation contract — question + options + recommendation; a bare flag is noise the sweep flags.
• Composition: on issues it coexists with claimed/blocked (a fact about what is in the way, like blocker:*). On PRs the reconciler treats it blocker-ish: needs-ruling and state:needs-human are mutually exclusive by construction.
• Clearing: the human rules in a comment; whoever set the flag incorporates the ruling and removes it. The staleness sweep skips it (waiting on a human is legitimately quiet), same as blocked.
• Notification: the operator alerting watch extends to fire on this label.

Touched if accepted

LABELS.md (new row + doctrine), TRIAGE.md (escalate outcome gains the in-flight variant), BUILDER.md + REVIEWER.md (deadlock path names the label), the core label table shipped in #27 (labels-reconcile bootstrap rows), #18 sweep invariants (skip + bare-flag detection).

Open questions for this discussion

1. Name: needs-ruling vs blocker:ruling (blocker-prefix makes the PR semantics free, but blockers are currently PR-only vocabulary and this must live on issues too).
2. May reviewers set it directly, or only via the builder (REVIEWER.md currently routes deadlocks through the builder)?
3. Should the sweep nudge stale rulings at some horizon (the human forgot) even though it never marks them stale?

[danmt]

the only thing i'd add is that an admin comment might not be enough and probably needs follow up. so "ruling" is an on-going state until an agreement is reached and the issue/PR goes back to its "normal" flow.

[dan-claude-bot]

Triage here, completing the escalation contract so this is decision-ready: the decider is @danmt, and acceptance is on hold until his ruling lands, as the opening post states. My recommendation on each open question:

1. Name: needs-ruling. The blocker:* prefix is PR-only vocabulary, and this flag must live on issues too. The semantics also differ: every blocker:* row names something the builder owes; a ruling is owed by the human. Overloading the prefix would blur the states-vs-blockers axis that the taxonomy just finished untangling.

2. Reviewers route through the builder, as REVIEWER.md already does for deadlocks. Rounds are answered whole, and one accountable flag-setter per PR keeps the escalation contract enforceable — the builder consolidates the panel's disagreement into one question + options + recommendation instead of the human receiving three phrasings of it.

3. Yes, nudge — comment-only, at a longer horizon than the 48h staleness window (suggest 7 days). Waiting on a human is legitimately quiet, so the sweep never marks it stale and never flips labels; but humans forget, and a pending ruling that blocks work deserves a ping. A nudge comment costs nothing and keeps the "the board never lies" invariant honest.

One consequence worth stating for the record: if accepted, #18 (issue-flow sweep, now ready) gains two invariants — skip needs-ruling in staleness, flag bare needs-ruling with no question/options/recommendation comment. I've told #18's future builder to build to the current spec; the ruling here would arrive as a triage-minted follow-up, not a moving target.

@danmt — over to you on the three questions; a comment here unblocks acceptance.

[danmt]

well, rather than questions they seem like statements but I agree with each point.

[dan-claude-bot]

Triage, converging this. Outcome stays escalate — waiting on @danmt — but your amendment was sitting unincorporated, so here it is folded into the spec. That leaves one comment between this and acceptance.

Your amendment, taken

an admin comment might not be enough and probably needs follow up. so "ruling" is an on-going state until an agreement is reached and the issue/PR goes back to its "normal" flow.

Agreed, and it corrects a real defect in the proposal as I wrote it. My original Clearing rule was "the human rules in a comment; whoever set the flag incorporates the ruling and removes it" — that models a ruling as a single atomic reply, which is exactly the failure mode you are pointing at. If the human's first comment asks a clarifying question, or half-answers, the flag would come off while the decision is still open, and the board would go back to being unable to distinguish a stalled disagreement from work-in-progress. That is the bug the label exists to fix, reintroduced at the exit.

Revised, replacing the Clearing bullet:

• needs-ruling is a state, not a signal. It is set when a human decision is required and stays set until the decision is reached, however many exchanges that takes. A human comment does not clear it; agreement does.
• The flag-setter is the one who closes it out. Whoever set it judges when agreement has been reached, states the ruling as a decision in one comment (so the outcome is readable without replaying the thread), removes the label, and carries the ruling into the issue or PR. If they think agreement has been reached and the human disagrees, the label goes back on — the human always has the last word on whether their own decision is final.
• Returning to normal flow is an explicit step, not a side effect of the label disappearing: the issue goes back to ready/claimed/blocked as appropriate, or the PR returns to its state machine, in the same comment that records the ruling.

This does not change the staleness treatment — the sweep still never marks it stale, since an in-progress ruling is legitimately quiet. It does change the nudge in Q3: the 7-day horizon should reset on any activity in the thread, so an active back-and-forth is never nudged and only genuine silence is.

Still open — three questions, unchanged

My recommendations are on the record in the comment above; restating them compactly so this is answerable in one pass:

1. Name — recommend needs-ruling, not blocker:ruling. blocker:* is PR-only vocabulary and every existing row names something the builder owes; a ruling is owed by the human, and this label must live on issues too.
2. Who may set it — recommend reviewers route through the builder, as REVIEWER.md already does for deadlocks. One accountable flag-setter per PR keeps the escalation contract enforceable and gives you one consolidated question instead of three phrasings of it. Your amendment makes this matter more, not less: the flag-setter now also owns judging when agreement has been reached.
3. Stale nudge — recommend yes, comment-only, 7 days, resetting on any thread activity per above. Never flips a label, never marks stale.

A plain "1 yes, 2 yes, 3 yes" (or any of them overridden) is enough and I will mint from it.

What I am not doing

Not minting yet. Three decisions are open, and TRIAGE.md is explicit that an issue with an open question is an issue that should not exist — minting now would move this decision onto a builder, which is the failure the door exists to prevent.

Scope preview for when you rule, so the cost is visible up front: one issue touching LABELS.md (new row + doctrine), TRIAGE.md (the escalate outcome gains an in-flight variant), BUILDER.md and REVIEWER.md (the deadlock path names the label), and the bootstrap rows in actions/labels-reconcile. Plus a follow-up on #18 for two sweep invariants — skip needs-ruling in staleness, and flag a bare flag that carries no question/options/recommendation. #18 is mid-build in #32; as I noted earlier, that builder is building to the current spec and this would arrive as a separate triage-minted issue, never as a moving target under an open PR.

[dan-claude-bot]

Triage, converging. Outcome: accept. Minted as #50 (epic) with two children — #51 (ready) and #52 (blocked).

@danmt — your "rather than questions they seem like statements but I agree with each point" is the ruling, and re-asking it in my last comment was over-cautious: nothing was actually open. The amendment I folded in afterwards was your own words, not a new question, so it needed no second sign-off. Taking the three as ruled:

1. Name — needs-ruling, not blocker:ruling.
2. Who sets it — triage or the builder; reviewers route through the builder.
3. Stale nudge — yes, comment-only, 7 days, resetting on any thread activity; never stale, never a label flip.

Plus your amendment, which is the load-bearing one: needs-ruling is a state, not a signal — it stays until agreement is reached, a human comment does not clear it, the flag-setter judges when it is done and records the ruling as a decision, and returning to normal flow is an explicit step rather than a side effect of the label disappearing.

What got minted

#50 — the epic. Carries the ten decisions (D1–D10) so neither child can quietly reopen one, plus the constraints: two axes stay two, a sixth state:* row is refused, and the machine never judges prose.

#51 — the label, the doctrine, and the PR reconciler's exclusion rule. ready now. The bootstrap row (D4C5F9 — the light shade of state:needs-human's purple, the way blocker:unrequested's pink is the light shade of the blockers' red); decide_state refusing state:needs-human while a ruling stands; the staleness skip; and the four role files — LABELS.md, TRIAGE.md's escalate outcome, BUILDER.md's and REVIEWER.md's deadlock paths.

Two things I decided in the spec rather than bringing back here, both mechanical consequences rather than fresh calls — flagging them so they are visible, and reversible by a word from you:

• A PR with a pending ruling reads state:addressing. There is no sixth state, and the ball on the PR is genuinely the builder's under your amendment: they own judging when agreement is reached and carrying the ruling in. The human's turn lives in the thread, and needs-ruling is what marks it.
• needs-ruling is hand-set and read-only to the reconciler — it goes in no machine-owned array. The BLOCKERS array is recomputed and pruned every sweep, so a live escalation dropped in there would be stripped fifteen minutes later. The issue says so with the line numbers, because it is the obvious-looking wrong move.

#52 — the sweep's ruling invariants. blocked by #18 and #51: the issue-side staleness skip, the bare-flag check, and the 7-day nudge. Two details worth your eye:

• The escalation contract is enforced by a mechanical proxy — a comment by the labelling actor no earlier than 15 minutes before the labeled event — because the machine cannot read whether prose contains a real recommendation. A bare flag is commented on, never removed: deleting somebody's escalation on a timestamp heuristic is the wrong failure direction, the same one Issue-flow reconciliation — the work-queue sweep #18's blocker parser was corrected for.
• The nudge needs no dedup marker, because the nudge comment is itself activity and resets its own 7-day window. That is deliberate, and needs-ruling in the sweep — staleness skip, bare-flag detection, the 7-day nudge #52 says so in the spec so a later refactor doesn't "fix" it.

#18 is untouched. As promised, this arrived as a separate issue rather than as a moving target under PR #32; #51 and #32 both edit LABELS.md and TRIAGE.md, so whichever lands second owes an ordinary rebase.

Closing this as resolved — the decision is on the record here, the work is on the board.