Skip to content
1 change: 1 addition & 0 deletions changelog.d/fixed-18387-needs-triage-relabel-loop.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- **The hive no longer fights a repository's own triage tooling over `needs-triage`.** Once an issue was claimed or covered by a pull request (020, 030, 040) the issue stage sweep took `needs-triage` off on every pass, so in a repository whose own tooling owns that label β€” Prow's `require-matching-label` action re-adds it to every issue without a `triage/*` label β€” the two removed and re-added it without end: 312 removals on 16 `projectbluefin/utah` issues in one night, each also starting a GitHub Actions run there. The hive now removes the label at most once per issue; if anything puts it back (another tool or a person), it leaves it on that issue from then on, logs one INFO line naming the repo, issue and label, and remembers the yield in the stage store, so a restart does not restart the loop. Issues whose label never comes back β€” hive-filed self-reports included β€” lose a stale `needs-triage` once claimed exactly as before ([#18387](https://github.com/hivecommons/hive/issues/18387)).
2 changes: 1 addition & 1 deletion src/docs/dashboard-sections/activity-monitor.md
Original file line number Diff line number Diff line change
Expand Up @@ -142,7 +142,7 @@ A draft PR (GitHub draft bit or `do-not-merge/work-in-progress`) reads **Draft

An Open issue waiting on a maintainer's triage reads **Triage needed Β· since 28m** β€” the `needs-triage` chip, or a 000-new row the reporter-trust gate holds (`new.next_mover: maintainer`, triage gate *next*) before the awaiting label has landed; the server stamps the `needs-triage` modifier on such a row so the chevron word, the chip and the inline **Accept triage** lead are the same as the label case ([#15437](https://github.com/hivecommons/hive/issues/15437) read *New Β· since 28m* with the ask only in the caption). The caption is exactly **Triage needed β€” accept or close** on every held row (015 and 000-new alike β€” the 015 lane reason `triage needed: carries needs-triage` is not appended, so the row does not say *triage* three times); the chevron hover keeps the next-mover / next-pass narration and the gate list.

At most one health chip sits over the strip's cap, with `+N` for the rest: `stalled`, `regressed`, `hold`, `needs-human`, `needs-decision` (β€œneeds human decision”), `needs-triage` (β€œtriage needed”), `needs-rebase`, `blocked` or `draft`. At 015 the chevron already names triage; before claim, a lingering `needs-triage` can be a chip (010/017/045). At 020+ it is stale and omitted from chip/stage text: `stale_labels` supplies a muted *Stale label* tooltip until the sweep removes it ([#14586](https://github.com/hivecommons/hive/issues/14586)).
At most one health chip sits over the strip's cap, with `+N` for the rest: `stalled`, `regressed`, `hold`, `needs-human`, `needs-decision` (β€œneeds human decision”), `needs-triage` (β€œtriage needed”), `needs-rebase`, `blocked` or `draft`. At 015 the chevron already names triage; before claim, a lingering `needs-triage` can be a chip (010/017/045). At 020+ it is stale and omitted from chip/stage text: `stale_labels` supplies a muted *Stale label* tooltip until the sweep removes it ([#14586](https://github.com/hivecommons/hive/issues/14586)). The sweep removes it once; if anything puts it back, the hive leaves it on that issue and the tooltip stays ([#18387](https://github.com/hivecommons/hive/issues/18387)).

A genuine backward hop sets `regressed`; the first forward hop clears it. Lapsed claims 020β†’010, 030↔020 flicker and 040β†’010 after a partial merge are not regressions. A regression parked on a person is red. Otherwise it is a muted dashed **stage reset** β€” **stage reset by push** when a new head caused the fall ([#17335](https://github.com/hivecommons/hive/issues/17335)) β€” yields to other modifiers and does not enter **Needs attention**: β€œthe hive is handling it β€” no action needed; clears on the next forward step.” See [The regressed marker](../labels-and-control-signals.md#the-regressed-marker-when-it-is-set-when-it-clears).

Expand Down
2 changes: 1 addition & 1 deletion src/docs/labels-and-control-signals/reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -882,7 +882,7 @@ On by default (`governor.first_timer_welcome.enabled: false` opts out), hive lea

With `reporter_trust.enabled: true`, an issue whose reporter's GitHub `author_association` is outside the trusted set (default `OWNER`, `MEMBER`, `COLLABORATOR`) and whose login is not in `trusted_logins` is not actionable until it carries one of these labels. On the first excluded scan, core `github.Client.fetchIssues` posts one marked explanation comment and applies `needs-triage` (or `awaiting_label`); later scans do not repeat the comment. This is a poller-side write, not an agent prompt, and is capped at 10 new notices per poll.

When the triage label appears, the same poll loop removes `needs-triage` only if the marker records that Hive added it, then the issue enters the backlog. Independently of the marker, the stage sweep removes `needs-triage` once the issue reaches 020 or later (claiming settles triage; see `stage/015-triage-needed` below) β€” this is what retires the `needs-triage` that `fleetreport` stamps on hive-filed self-reports at filing. Trusted reporters' issues pass untouched.
When the triage label appears, the same poll loop removes `needs-triage` only if the marker records that Hive added it, then the issue enters the backlog. Independently of the marker, the stage sweep removes `needs-triage` once the issue reaches 020 or later (claiming settles triage; see `stage/015-triage-needed` below) β€” this is what retires the `needs-triage` that `fleetreport` stamps on hive-filed self-reports at filing. It does so at most once per issue: if anything puts the label back afterwards (a repository's own triage tooling, such as Prow's `require-matching-label` action, or a person), the hive leaves it on that issue from then on and logs one line saying so (hivecommons/hive#18387). The label coming back is only judged while the issue sits at 020 or later, so a claim released back to 015 does not count. The yield lives on the issue's stage record: an issue that drops out of staging entirely (closed, or no stage derived) loses that record, and if it re-enters staging the hive may remove the label once more. Trusted reporters' issues pass untouched.

Runs after holds/exempts and before `require_labels`, so the ordinary allow-list still applies afterwards. Hive- and bot-filed issues are not judged here (#5117 owns them). Counted as "needs triage" on the repo card, not as a generic filter refusal.

Expand Down
4 changes: 2 additions & 2 deletions src/docs/labels-and-control-signals/stage-labels.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@ referenced it) a lone `stage/050-review-pending`
| Label | Applies to | Meaning | Expected dwell (then `stage/stalled`) |
|---|---|---|---|
| `stage/010-actionable` | issue | triaged; eligible for the hive to pick up. A human-filed issue without `needs-triage` counts as triaged by its trusted reporter | 24h |
| `stage/015-triage-needed` | issue | actionable, but no maintainer has looked at it yet. Derived instead of 010 only when the reporter-trust gate is holding the issue: it carries the awaiting label `needs-triage` (`reporter_trust.awaiting_label` default) or sits in the #9665 gate's `reporter_triage` bucket. Who filed it is never consulted β€” issues from hive agents and from trusted humans are triaged by construction and stay 010. A **display and tracking state, not a gate**: the scanner and relay claim a 015 issue exactly as a 010 one (the reporter-trust gate withholds `needs-triage` issues separately, and that is unchanged), and 015 lights the activity monitor's *Actionable* column as "Triage needed". `015 β†’ 010` (a maintainer triages) is never a regression; `010 β†’ 015` is a reclassification. Because 015 is not a gate, a claim settles triage: whenever the sweep (or an out-of-cycle claim fact) writes a stage of 020 or later β€” 020, 030, 040 or a PR-mirrored stage β€” it removes `needs-triage` in the same label write, and an open issue already at 020+ still wearing it is reconciled on the next sweep; the label survives at 010, 017, 018 and 045, which the table lets fall back to 015 (hivecommons/hive#14586). The Open column is untouched: an issue with no stage stays "Open" | 24h |
| `stage/015-triage-needed` | issue | actionable, but no maintainer has looked at it yet. Derived instead of 010 only when the reporter-trust gate is holding the issue: it carries the awaiting label `needs-triage` (`reporter_trust.awaiting_label` default) or sits in the #9665 gate's `reporter_triage` bucket. Who filed it is never consulted β€” issues from hive agents and from trusted humans are triaged by construction and stay 010. A **display and tracking state, not a gate**: the scanner and relay claim a 015 issue exactly as a 010 one (the reporter-trust gate withholds `needs-triage` issues separately, and that is unchanged), and 015 lights the activity monitor's *Actionable* column as "Triage needed". `015 β†’ 010` (a maintainer triages) is never a regression; `010 β†’ 015` is a reclassification. Because 015 is not a gate, a claim settles triage: whenever the sweep (or an out-of-cycle claim fact) writes a stage of 020 or later β€” 020, 030, 040 or a PR-mirrored stage β€” it removes `needs-triage` in the same label write, and an open issue already at 020+ still wearing it is reconciled on the next sweep; the label survives at 010, 017, 018 and 045, which the table lets fall back to 015 (hivecommons/hive#14586). The hive removes it at most once per issue: if anything puts it back (a repository's own triage tooling such as Prow's `require-matching-label`, or a person), the hive leaves it on that issue from then on, logs that once, and remembers the yield across restarts (hivecommons/hive#18387). The Open column is untouched: an issue with no stage stays "Open" | 24h |
| `stage/017-possible-existing` | issue | **Possibly exists Β· needs author.** The prior-art gate found something that looks like the request already (knowledge bead, setting, merged PR, closed issue, doc or code) and parked the issue with the findings; the author confirms the gap (`/hive decision proceed β€” <gap>`) or closes it (`/hive decision exists`, label `already-exists`). The label itself is the park signal and an issue-level hard suppress, so no agent claims it; clanker-filed parks auto-close after `runs.triage.prior_art.bot_close_ttl`; hive-filed issues never wear it ([#13575](https://github.com/hivecommons/hive/issues/13575)) | none |
| `stage/018-open-for-discussion` | issue | **Open for discussion.** An open issue labelled `proposal`, `kind/design` or `architecture discussion` with no live claim, or an unlabelled one whose title opens with `[RFC]` or `RFC:` (case-insensitive, after any leading emoji): what is left on it is a discussion, not agent work, so it is derived here instead of 010 / 015 and the activity monitor's *Actionable* column reads "Open for discussion", the caption naming the label. The stage reason is `open for discussion: <label>`, or `open for discussion: rfc title` when only the title marks it ([#18141](https://github.com/hivecommons/hive/issues/18141)). **Not a gate**: the claim gate does not refuse these labels, so a person's `/claim`, the contribute relay or an agent claim stages it 020 / 030 as on any issue; parks, holds, `blocked` and a covering PR outrank it as they do 010. Removing the label returns the issue to plain 010 derivation (never a regression), and a covering `Refs #N` PR that merges and leaves `hive/partially-addressed` lands it back here as progress ([#17150](https://github.com/hivecommons/hive/issues/17150)) | none |
| `stage/020-claimed` | issue | a live claim by anyone β€” a human, a relay contributor or a hive agent's `hive-open-issue claim` / start mark β€” with no PR evidence yet (replaces `claimed`, `hive/in-progress`) | 2h |
Expand Down Expand Up @@ -145,7 +145,7 @@ stateDiagram-v2
s010 --> s045: needs-human / park label (agent escalates)
s010 --> s015: needs-triage added (reclassification)
s015 --> s010: maintainer triages: triage/accepted, hive/verified-open or approved-direction added, or needs-triage removed (not a regression)
s015 --> s020: scanner / relay claim (015 is not a gate; needs-triage removed in the same write)
s015 --> s020: scanner / relay claim (015 is not a gate; needs-triage removed in the same write, once β€” left on if anything puts it back)
s015 --> s045: needs-human / park label (agent escalates)
s010 --> s018: discussion label added to an unclaimed issue, or it is retitled as an RFC (reclassification)
s018 --> s010: discussion label and RFC title removed (not a regression)
Expand Down
55 changes: 52 additions & 3 deletions src/pkg/github/issue_stage_labels.go
Original file line number Diff line number Diff line change
Expand Up @@ -224,6 +224,43 @@ func issueUntriaged(in IssueStageInput) (untriaged bool, why string) {
return false, ""
}

// triageClearAllowed is the one decision on whether the hive may take the
// reporter-trust awaiting label off an issue whose stage settled triage
// (hivecommons/hive#18387). The hive removes it at most once per issue: a
// repository's own triage tooling (Prow's require-matching-label, another
// bot, a person) may own the same label and re-add it seconds later, and
// removing it again on every pass only feeds a remove / re-add loop. So:
// label absent β†’ nothing to remove; already yielded β†’ leave it; removed
// once and back now β†’ yield (yieldNow) and leave it; otherwise β†’ remove.
func triageClearAllowed(rec stagelabels.Record, labels []string) (remove, yieldNow bool) {
switch {
case !issueHasLabel(labels, triageAwaitingLabel), rec.TriageClearYielded:
return false, false
case !rec.TriageClearedAt.IsZero():
return false, true
}
return true, false
}

// settleTriageClear applies triageClearAllowed to key's stage record: on a
// fresh yield it marks the record (persisted with the store, so the yield
// survives a restart) and logs it once. remove says whether the stage
// write may take the label off; yielded is what
// IssueFacts.TriageClearYielded carries to the deriver. The issue sweep
// and the FactSink's enrichment both call it, so the two paths cannot
// disagree.
func settleTriageClear(store *stagelabels.Store, key, repo string, number int, labels []string, logger *slog.Logger) (remove, yielded bool) {
if store == nil {
return issueHasLabel(labels, triageAwaitingLabel), false
}
rec, _ := store.Get(key)
remove, yieldNow := triageClearAllowed(rec, labels)
if yieldNow && store.MarkTriageClearYielded(key) && logger != nil {
logger.Info("issue stage labels: "+triageAwaitingLabel+" came back after the hive removed it; leaving it on this issue", "repo", repo, "issue", number, "label", triageAwaitingLabel)
}
return remove, rec.TriageClearYielded || yieldNow
}

// IssueStageFor classifies one enumerated issue: it resolves the hive's
// label families into stageengine.Facts (issueFactsFrom) and asks the
// engine (stageengine.DeriveIssue) for the stage. covered reports whether
Expand Down Expand Up @@ -565,6 +602,7 @@ func SyncIssueStageLabelsWith(ctx context.Context, client *Client, result *Actio
stage, covered, reason := d.Stage, d.Covered, d.Reason
var want stagelabels.Desired
var tr stagelabels.Transition
var triageYielded bool
if stage == stagelabels.None {
store.ForgetStage(key)
} else {
Expand All @@ -580,9 +618,19 @@ func SyncIssueStageLabelsWith(ctx context.Context, client *Client, result *Actio
// Decision.Clear takes it off in the stage write, and the
// pre-plan here must see the same write as due so an issue
// whose stage label is already right is still reconciled
// (hivecommons/hive#14586).
if stage.SettlesTriage() && issueHasLabel(in.Labels, triageAwaitingLabel) {
want.Clear = []string{triageAwaitingLabel}
// (hivecommons/hive#14586). Only once per issue, though: a
// label that came back after that removal belongs to another
// writer and stays (hivecommons/hive#18387). The yield is only
// judged at a stage that settles triage: at 010/015 (say,
// after a claim release) the label is legitimately back, and
// a sticky yield must not be booked from that read.
triageYielded = rec.TriageClearYielded
if stage.SettlesTriage() {
clearTriage, yielded := settleTriageClear(store, key, in.Repo, in.Number, in.Labels, logger)
triageYielded = yielded
if clearTriage {
want.Clear = []string{triageAwaitingLabel}
}
}
}
if stage == stagelabels.PRInProgress || stage == stagelabels.CoveredByPR {
Expand Down Expand Up @@ -632,6 +680,7 @@ func SyncIssueStageLabelsWith(ctx context.Context, client *Client, result *Actio
facts.Ref.Owner, facts.Ref.Repo = owner, name
facts.ObservedAt = now
facts.Issue.Stalled = want.Stalled
facts.Issue.TriageClearYielded = triageYielded
pending = append(pending, issueStagePending{in: in, key: key, want: want, tr: tr, covered: covered, reason: reason, facts: facts})
}
// The write: one ReconcileBatch for the pass. The reconciler re-reads
Expand Down
Loading
Loading