Synced from Hive. This page is pulled from hivecommons/hive@v5 during the docs build. Edit the canonical source in the Hive repository.

Hive Labels and Control Signals

This is the operator view of Hive labels: if you add or remove a label, this is what the v5 code does. It also calls out non-label controls that look like labels from the dashboard.

How labels reach agents

Most hard gates run before an agent sees work. GitHub issue enumeration reads labels in this order: standing meta issues are excluded first, then hold labels move the item to the Hold list, then exempt labels and the issue-level hard-suppress labels (needs-human, needs-direction, needs-decision, needs-spec; hardSuppressIssueLabels in src/pkg/github/labels.go) filter it out, so no agent kick names, and no kick claims, a parked issue, then project.issue_filter.require_labels admits or rejects the issue, and only then is it actionable (src/pkg/github/client.go:955-1045). Pull requests use the same hold-first enumeration for the PR Hold list (src/pkg/github/client.go:1110-1165). That means kick prompts, dashboard actionable counts, planning-from-label, and contributor offers normally inherit the same gate.

Some sweeps bypass that enumeration and list items themselves, but every one of them gates on the same hold predicate as enumeration (Client.IsHeldLabels / Client.isHeld, src/pkg/github/client.go:1964-1972, src/pkg/github/client.go:2674-2676), so the generic hold substrings and the exact dashboard hive-pause/<hive-id> label hold everywhere:

• Auto-merge sweeps reach it through the Transport.IsHeldLabels seam; the queued (lgtm) sweep skips a held PR before fetching it, and the self-authored sweep skips held PRs plus needs-human before merging (src/pkg/github/automerge/automerge_sweep.go:23-38, src/pkg/github/automerge/automerge_sweep.go:959-964, src/pkg/github/automerge/automerge_sweep.go:966-1004, src/pkg/github/automerge/automerge_sweep.go:1029-1046).
• The task-list sweep skips a held issue before its exempt / issue needs-human gate, so a held issue is never commented on, relabelled, or closed by it (src/pkg/github/task_list_sweep.go:848-854).
• The SHA-hold sweep lists primary-repo kind/bug issues itself, adds literal hold plus a marker notice when no SHA is present (for reporters in issue_filter.reporter_trust trusted associations it adds the soft issues.sha_hold_trusted_label, default needs-sha, instead, #12002), and removes hold only when the current hold is its own: the newest hold label event is a labeled by the App bot and an App-authored SHA-hold notice was posted at or after it (EnforceSHAHold / shaHoldIsOwn in src/pkg/github/client.go).
• PR-request watching applies server-side PR holds after a PR is opened; the agent’s --label hold flag is deliberately discarded by the wrapper (src/pkg/github/pr_request_watcher.go:452-524, bin/hive-open-pr.sh:142-150).

The “respect hold labels” text in policy templates names the enforced set (hold, on-hold, hold/review, hive-pause/<hive-id>, any label containing hold, plus do-not-merge as exempt) but is a prompt-level backstop. The hard gate is the enumerator or sweep named in the table.

Label axes

Hive-authored labels answer different questions. Read them as independent axes, not as one taxonomy: an issue can carry one label from each axis at the same time, and swapping a label on one axis never changes what the others mean.

Origin sources

The <source> is the component that created the issue, never the person or hive that operates it. One label per issue; when a caller already supplies an origin/* label (an agent passing --label origin/…, a forge consumer), that label is kept and no second one is added (config.WithOriginLabel).

Work-source sinks other than GitHub (Jira, Linear) carry no GitHub labels and are outside the axis.

Some hive-authored labels look like provenance but are read as signals, so they stay outside origin/* on purpose: hive/selfreport is the dedupe key the self-report joiner searches (label:hive/selfreport in src/pkg/github/fleet_report.go) and the hub relay re-applies it — it is deprecated in favour of origin/selfreport, which every new selfreport also carries, and will be removed once the joiner searches the origin label instead; hive/advisory makes an issue a standing meta issue that enumeration excludes (src/pkg/github/standing_issues.go); hive/<hive-id> is retired (#12539): nothing writes it any more, the origin marker in the body says which hive wrote an item, and the boot sweep strips leftovers (see the reference row). hive/sentinel, hive/fleet and fleet are only consulted by the good-first-issue exclusion list (src/pkg/gfi/gfi.go) and are no longer written by this code base.

Categories

• Informational / display-only changes how Hive explains an item, not whether agents can act.
• Workflow / status marks a process state such as reviewer outcome or rebase need.
• Gate / permit admits, blocks, or releases a specific workflow.
• Hold / suppress removes work from agent/contributor/merge lanes until cleared.
• Contributor eligibility / routing affects /contribute offers or agent lane choice.
• Human approval / acknowledgement records that a human accepted a direction or design.

Reference table

Stage labels (stage/NNN-*): the pipeline state machine

Operator request (#12429): “the labeling of issues and prs has to give hints as to what stage the work is in … the labels must be clear and reflect the state machine … this needs to be dead simple.” The hive therefore owns ONE ordered, mutually exclusive stage/NNN-slug family shared by issues and PRs, an orthogonal role/* family that answers “would the hive auto-merge this?”, an orthogonal author/* family that answers “who wrote this?”, and one red health marker (stage/stalled) that says nobody is working the item. Exactly one stage/* stage label per open item; closed, merged or superseded items carry none (terminal = no stage). (stage/regressed was retired in #12534: the review loop 050 → 060 → 072 → 070 → 050 is the intended cycle, so a backward move is recorded as a one-line stage comment and in the dashboard’s transition history, not as a label.)

The engine lives in src/pkg/stagelabels (the table, the reconciler plan, the persisted stage timing) and src/pkg/github/automerge/automerge_stage_labels.go (the mapping from each automerge lane’s per-PR reason to a stage, applied once per sweep cycle under the hive:stage_labels REST caller). Labels come from the PR list payload the sweep already fetched and are written only when the planned set differs from the current one, so an unchanged item costs nothing.

One writer. Every stage write — the PR lanes, the issue reconciler (src/pkg/github/issue_stage_labels.go) and the claim-ledger hooks that mirror a new claim onto the issue — goes through stagelabels.Enforce / EnforceStage (#12512). When a write is due, Enforce re-reads the item first and plans from that fresh label set, so a stage another writer placed since the cycle’s snapshot (a contributor claim landing seconds after the reconciler staged the issue 010) is replaced rather than joined, and any item found carrying two stage/NNN-* labels is healed on the spot (healed in the reconcile log lines). The claim hooks always re-read: they know the stage a claim implies but not what the lanes think of the author tier or health, which they keep. The hub’s label writes are also journaled against the item’s updated_at from that read: the mutation journal otherwise treats “remove stage/020 from #N” as applied forever, so a label another writer put back could never come off again — the reconciler kept logging the remove while GitHub kept the label (hivecommons/hive#12443).

Issue stages and PR stages are disjoint. The stage table marks each stage Issue or PR (never both): 010–040 are issue stages, 050–100 are PR stages. Enforce clamps every write to the item’s kind (Stage.For(stagelabels.IssueItem | PRItem)): a PR stage asked of an issue becomes 040-covered-by-pr, an issue stage asked of a PR clears the stage, and the reconcile log line carries clamped=true with the stage that was asked for. An issue’s pipeline therefore ends at 040 while its PR is open; the covering PR’s own stage is recorded in the issue’s stage reason (open PR #N covers it (PR at 060-reviewed), in /data/stage-labels.json and the dashboard), never as a second label. Before this rule the reconciler mirrored the PR’s stage onto the issue, which is how hivecommons/hive#12451 came to wear stage/010-actionable + stage/040-covered-by-pr + stage/050-review-pending at once and #12483 (covered by a PR that merely referenced it) a lone stage/050-review-pending (#12451).

Numbering rules

• Sparse, zero-padded, 3 digits. GitHub sorts labels lexically, so the padding is what keeps stage/100-… after stage/090-….
• 100 is always the merge queue. New stages are inserted between existing numbers (e.g. 035), never above 100.
• Renaming or inserting a stage = edit ONE table, stagelabels.Table. Stages are keyed in code by Go identifiers (ReviewPending, MergeQueue, …); the label string (number + slug), description, dwell and colour are all derived from that row. The reconciler treats any stage/* label not in the current table as stale and removes it, so a renumber ripples to every open item on the next cycle; the old labels can then be deleted from the repo.
• Colours: every stage/NNN-* label is the same hive amber #f5a623 (the colour the retired 🐝 covered by PR used) so the eye tracks the family across lists; stage/stalled #d73a4a is red; role/* is neutral grey #6e7781 except role/trusted #0e8a16; author/human is the same grey, author/clanker purple #8250df, author/hive blue #1d76db; dco shares role/trusted’s green and no-dco shares stage/stalled’s red (same constants, so the pair reads as one family). The retired stage/regressed is stripped from any item the sweep sees and is no longer provisioned. The ensure-label step creates missing labels and PATCHes the colour of an existing one only when it differs from the table, once per repo per process — a PATCH keeps the label on every PR wearing it, so an existing pill is recoloured, never removed and re-added.

The table

Dwell thresholds are overridable per slug under governor.labels.stage.dwell (review-pending: 1h, 0 = never). The whole family is switched by governor.labels.stage.enabled (default true); both are on the Settings → Labels tab.

How an issue’s stage is decided

The enumeration cycle already sorts every open issue into a work bucket (actionable, live claim, in-progress start mark, covered by an open PR, filtered …) before the scanner kicks anything. src/pkg/github/issue_stage_labels.go (SyncIssueStageLabels, REST caller hive:issue_stage_labels) runs once per cycle after the claim guards and the in-progress sweep, so the buckets are final, and maps each row (#12436):

Labels come from the issue list payload the cycle already fetched — no per-issue GETs — and are written only when the planned set differs from the current one. While an open PR covers the issue (040), stage/stalled belongs to the PR and is not written on the issue; for the issue’s own stages (010–030) the dwell is still measured from stage entry, because the list payload carries no comment count or activity timestamp the hive did not bump itself (updated_at moves on every hive write, #12491) — the PR engine’s no-activity clock and stalled.require_quiet below do not apply to issues. When the issue falls back between its own stages (a claim or kick lapsed with no PR: 030 → 010) it gets one explanatory comment and a history hop in the store. The claim relay (hive-open-issue claim) writes stage/020-claimed / stage/030-pr-in-progress directly alongside hive/claimed-by-<who> so the label is right as soon as the claim lands; hive-open-pr --issues swaps 030 for 040 when the PR opens. An agent comment that escalates (opens with needs-decision/needs-direction/…, “parking this”, “Triage (x): not a … defect”) or a label request carrying only escalation labels is not a start signal: it records no agent claim and never stages the issue 030. Every stage write outside the reconciler (claim relay, claim release, in-progress sweep, PR-claim sync) goes through a fresh read so the mutation journal keys it to the item’s updated_at — a label a human removed is re-applied, not replayed as “already applied”; close-on-merge strips every hive-owned label from an issue it closes. Timing shares the PR engine’s state file (/data/stage-labels.json, issues and PRs share a number space per repo); an issue’s record never holds a PR stage, so a PR falling 100 → 060 does not read as the issue regressing.

How a PR’s stage is decided

The automerge sweep already computes one reason per PR per lane each cycle (self-authored, trusted-author, contributor lane — see hive-merge.md). automerge_stage_labels.go maps that reason, the review-swarm verdict for the head, and the author tier the lane actually used to admit the PR:

When several lanes see the same PR the self-authored lane outranks the trusted-author lane, which outranks the contributor lane; the trusted-author lane’s bare untrusted-author-role is a weak opinion the contributor lane refines. A weak opinion (any admission reason — “this lane cannot vouch for the author”) is only written once every lane enabled for the repository has reported on the PR in the same reconcile pass. Two drivers run the lanes against one process-wide tracker (the engine’s own ticker and the main loop’s queued sweep), so one pass can drain a maintainer PR’s trusted-author observation and the next hold only the contributor lane’s no-claim; an incomplete pass is treated as no opinion rather than written as 090 and flipped back a minute later.

A maintainer’s own PR is therefore not a 090 case at all: with auto_merge.trusted_authors on (the hive’s default spoke config — require_role: merger, require_github_permission: true), the trusted-author lane admits an authorized_users owner/merger with write/maintain/admin permission and merges the PR itself once CI is green, no CHANGES_REQUESTED review is outstanding and no hold/do-not-merge/ needs-human label is present. Only the lane’s own reasons (CI pending or red, conflicting, label:needs-rebase) hold it at 050/072; a human /lgtm+/approve is never required.

Human hand-offs: 072 / 050 / 085 / 060 / 090

A lane stops at admission or at a hold before it looks at CI, so “a human must act” alone says nothing about whether the merge button is safe. For every such hand-off the engine gathers what the lane skipped — the reviewer verdict for the current head, a digest of the head’s checks (tide and the other merge-metadata contexts excluded) and its DCO context, the sentinel-alert / hold / do-not-merge* / needs-decision labels, the conflict reason and the contributor lane’s soak — and stagelabels.RouteHuman decides, in this order (#12528):

The entry comments are posted once per stage visit (a flip 085 ↔ 090 is a new visit) and never as a GitHub review: the hive does not approve on a maintainer’s behalf, so prow/tide see nothing until a person acts. The check digest costs two REST calls per head and is cached 10 minutes; it is read only for human-routed PRs.

role/* — would the hive auto-merge this?

One per PR, derived from what the lane used for admission (registry tier, claim-marker tier=, trusted-author list, App-authored), recomputed with the stage but written only on change:

Renamed from author/<tier> (#12581). The old prefix conflated trust with authorship: author/trusted sat on PRs a maintainer pushed by hand and on PRs a contributor’s hive opened under that contributor’s login. Trust is now role/*; author/* says who wrote it (next section). Migration is automatic: every reconcile that writes a PR removes a retired author/trusted|contributor|newcomer|untrusted and adds the role/* equivalent in the same write; stagelabels.RoleOf still reads the old spelling until then so a claim hook never drops the tier. The role names are not configurable.

dco / no-dco — the hive-owned sign-off signal

One per PR, written by the stage pass from the PR’s commits — not copied from any CI context or bot label (#12542). On each new head the pass reads the PR’s commits once (cached per head in the stage store) and counts the non-merge commits without a Signed-off-by: trailer:

The pair is mutually exclusive. A missing sign-off is the one author-side gate the hive decides without waiting for CI or a reviewer verdict: the PR goes to stage/071-needs-author (human) / stage/072-returned-to-contributor (clanker) — 070-fixing when self-authored — with reason dco-missing on the first evaluation of the head, and, for an author/clanker PR, the 072 nudge / relay fix-pr task names the exact fix — git rebase --signoff HEAD~<n> && git push --force-with-lease where <n> is the PR’s commit count (a human-authored PR simply waits at 071 wearing no-dco; see “Stage 07x by author kind”). Signing and force-pushing produces a new head, which is re-read and returns the PR to the normal path. A PR with no non-merge commits, or whose commits could not be read, is unknown: its existing DCO pills are left alone and no stage decision is made from DCO.

The labels are written on every managed repo; the 072 routing is per repo. It applies only where the repo actually enforces DCO — detected when a dco / DCO context is in the branch’s required checks or reported on the PR head (the DCO GitHub App, Prow’s plugin) during the lane’s CI walk, no extra API call — or where governor.labels.stage.dco.required says so:

governor:
  labels:
    stage:
      dco:
        required:          # "owner/repo", bare repo, or "*"; overrides detection
          hivecommons/hive: true
          acme/playground: false

On an ungated repo an unsigned head keeps the lane’s stage, carries no-dco as information only, and the nudge does not ask for a rebase.

Prow’s dco-signoff: yes / dco-signoff: no (the Prow dco plugin’s hard-coded names) are retired on hive-managed repos: once the hive has read a head’s commits it removes them, so a PR shows exactly one DCO pill. Readers (stagelabels.DCOFromLabels, used by the merge-eligible export) still honour the legacy pair when neither hive label is present, so nothing breaks while Prow’s plugin is being switched off. GitHub cannot colour one label name two ways, which is why the red case is no-dco rather than a red dco.

author/* — who wrote this PR?

One per PR, mutually exclusive, decided by pkg/authorkind from evidence the hive already leaves on a PR. It is orthogonal to role/*: a trusted contributor whose own hive opened the PR carries role/trusted + author/clanker. Unlike the pipeline labels it stays on merged and closed PRs — who wrote a PR is a fact about it, not pipeline state, and the hub’s revert-rate-by-author-kind drill-down (#12428) reads it.

Detection rules, first match wins (authorkind.Explain returns the rule name, logged at debug as stage labels: author kind):

1. author login is the hive’s App login ([bot] suffix tolerated) → author/hive
2. an agent/<lane> ownership stamp is on the PR → author/hive (stamps the same pass strips as strays from a non-App PR, #12545, are ignored first)
3. “ in the body: <id> is this hive’s hive_id → author/hive; another hive → author/clanker
4. the visible — hive: attribution trailer (what the hub’s ReconcilePRAttribution stamps on every relay-reported PR) → author/clanker
5. the 🐝 **Hive Agent** identity footer from gh-wrapper.sh → author/clanker
6. the login has a contributor profile on this hive (runs a relay that targets it) → author/clanker (weakest signal; only reached with no marker)
7. a non-App [bot] login (dependabot, …) → no author/* label
8. otherwise → author/human

Names are configurable so a repo can spell them its own way; each must keep the author/ prefix (so the reconciler still owns it) and the three must differ:

governor:
  labels:
    author:
      human: author/human      # default
      clanker: author/clanker  # default
      hive: author/hive        # default

Stage 07x by author kind

A red PR — CI red, changes requested, DCO missing or conflicting — lands in one of three stages that mean the same thing (“the author must act”) and are reached and left through the same lane transitions. The author kind (author/*, derived by the engine as stageObservation.AuthorKind) picks the label, and with it the tracker word and whether the hive has anyone to interrupt:

Only a clanker PR has a hive on the other end, so only 072 gets the nudge comment, the relay interrupt and adoption; a human PR at 071 just sits there until someone pushes a new head (and then stalls per the dwell table like any other stage). A hive-authored PR never reaches 071/072: it is 070. Should an author/hive PR still carry 071 or 072 (kind learned late), the next sweep re-derives it to 070; a human-authored PR found at 072 (pre-071 labels) is moved to 071 the same way. 071 and 072 are “author-blocked” everywhere the rules below name 072 — dwell/stall, needs-rebase → 07x, regression checks and the tracker’s CI / Review column, which prints the stage word next to the author-kind icon.

stage/stalled — “nobody is working this”

On a PR, stage/stalled means no activity by anyone but the hive for the stage’s dwell: no head push, no comment, no review or reviewer verdict, no CI status change and no label change for the time in the table (governor.labels.stage.dwell.<slug> overrides it; 0 = never). On an issue in its own stages (010–030) it still means “sat in the stage past the dwell” (see above): the issue list payload has no activity signal the hive does not bump itself.

• Never while the item is waiting on the hive. Required checks still running, or 050-review-pending with no reviewer verdict for the current head, are waits on the hive’s own lanes, not on a person — so they cannot stall whatever the elapsed time (specimen: #12417, 6h at 050 with CI green and no verdict, wrongly marked stalled). At 050 the label is possible only once the verdict exists and nobody acted on it for the dwell.
• Cleared at once on any activity. The next cycle that sees a new head, a new comment, a new review submission (an Approve / Request changes with only a body counts: the comment counters miss it) or a changed verdict/CI/label set removes it. The automerge engine’s own comments (stage notes, nudges, regression lines, rebase requests, stale-approval and hold-release notes) and the hive app’s own reviews do not count, whether posted before or after the cycle’s reconcile; a comment from another hive process (the reviewer swarm’s review comment, a merge note) is indistinguishable from a person’s in the comment counter and does — so a stall can only come later than the rule says, never earlier.
• No updated_at. “Last activity” is derived from the head SHA, the PR’s comment counters, the review submissions the lanes list (not every lane path lists them; a review seen by none is caught by the next cycle that does) and the verdict/CI/label digest the lanes already fetched — never updated_at, which GitHub bumps for the hive’s own writes (#12491). A change is dated by the cycle that first observes it (at most one sweep interval late; the list payload carries no commit or comment timestamps). State lives in /data/stage-labels.json; no extra API calls.
• governor.labels.stage.stalled.require_quiet: false restores the older rule (dwell measured from entering the stage); waiting on the hive still never stalls. The review queue’s stage.stalled / stage.past_dwell and the hive_held count follow the same dwell overrides and require_quiet setting as the label.
• Only a stall in 080-awaiting-merge-admission is explained in a comment (“, stage 080-…: no activity for 30m0s: <lane reason>), because that stall is the hive’s fault, not the author’s.
• When the hive is the holder — an item past its dwell while waiting on the hive — the PR gets no label. The engine logs one warning per item (stage labels: PR waits on the hive past the stage dwell — reviewer lane needs attention), counts it in /api/review/queue as hive_held, and the review-queue entry carries stage.waiting_on_hive + stage.past_dwell (rendered as a red “waiting on hive Xh” pill). That is the signal to look at reviewer capacity/cadence, not at the author.
• Backward moves (e.g. 100 → 070 because a new head went red) are not labels. The hive posts one short idempotent comment carrying “ — stage 100-merge-queue → 070-fixing: check-failing:unit — and records the hop in the item’s history (stage.history[] on the review-queue entry, newest last, capped at 12). Leaving a repair stage (070/071/072/074) for 050/060 is the repair route itself and is not commented.
• Filter label:stage/stalled across repos = every PR a person has walked away from, plus every issue that sat in 010–030 past its dwell.

Off the happy path: 072 → nudge → 074 → takeover

When a clanker-authored contributor PR goes red the hive does not just relabel it (a human-authored one goes to stage/071-needs-author and waits) (full flow in hive-merge.md):

1. stage/072-returned-to-contributor and ONE “ comment @-mentioning the author with the failing checks / review asks and “reply here or push a new head”. Re-posted only for a new head; re-nudged once more after governor.labels.stage.contributor_nudge.renudge_interval (default = the stage’s 24h dwell, i.e. at stage/stalled), then no more — cap: 2 nudges per head. mode= records how the relay side was handled so the comment itself answers “did their agent get interrupted?”. governor.labels.stage.contributor_nudge.enabled: false turns the comment and the relay task off; the stage label still moves.
2. Relay contributors (the author has a contributor profile and a live relay connection) also receive the diagnosis in their relay session as a fix-pr task with priority: interrupt. Presence = a relay heartbeat within governor.labels.stage.presence_window (default 15m); an offline or external author gets the GitHub comment only (mode=comment). The hub picks the delivery mode from what the relay advertised at DECLARE:
   • mode=spawn — the relay declared parallel_sessions and max_parallel_fixes (its HIVE_MAX_PARALLEL_FIXES, default 1, only when the backend has a headless entry point): a bounded parallel sub-session fixes the red PR while the primary session keeps its task.
   • mode=preempt — no parallel capability: the primary agent is told to park its current issue (WIP committed/stashed; the claim and lease stay alive), fix the PR on its existing branch with the same sign-off, print HIVE_FIX_PR_DONE <task_id> (or HIVE_FIX_PR_FAILED <task_id> <reason>), then resume. A headless primary cannot be interrupted, so the relay defers the fix and runs it before its next ready.
   • mode=queued — the contributor is over their fix budget (below); the task waits server-side and the PR carries stage 072 + the comment only. Protocol fields and client behaviour: contributor-relay.md § fix-pr tasks. The interrupt machinery in this step and the adoption in the next are for author/clanker PRs only — there is a hive on the other end to interrupt or stand in for. author/human and author/hive PRs follow the same stage transitions and simply wait at 071 for a push or a comment: no nudge, no adoption, no extra comment (Stage 07x by author kind).
3. If the author stays unavailable the hive adopts the PR (governor.labels.stage.adoption.enabled, default true). “Unavailable” is decided against the contributor’s live presence on the hub at every sweep, not a snapshot taken when the nudge went out (hivecommons/hive#12527: the author’s relay was polling for work during the nudge and dropped off 30 minutes later; a snapshot-based grace kept the PR at 072 indefinitely). The marker records which rule fired:
   • reason=contributor-offline — the author has a contributor profile here and no relay heartbeat within governor.labels.stage.presence_window: adopted governor.labels.stage.adoption.after_offline (default 15m) after the later of its last heartbeat and the first nudge;
   • reason=contributor-unregistered — no profile here (another hive, or a relay that never registered, posted the PR): adopted governor.labels.stage.adoption.after_unregistered (default 15m) after the first nudge;
   • reason=grace-elapsed — the relay is online but the nudge went unanswered for governor.labels.stage.contributor_grace_online (default 2h); and, on a hub that reports no presence at all, the nudge-time graces (contributor_grace_online 2h / contributor_grace_offline 15m after a comment-only nudge). A PR carrying hold, do-not-merge or do-not-merge/hold is never adopted (a human parked it; one log line, the stage stays 072). How the hive takes over depends on whether it can push to the PR’s own branch (governor.labels.stage.adoption.in_place, default true):
   • in place (mode=in-place) — the head is in the base repo, or the fork allows edits by maintainers (maintainer_can_modify, resolved with one GET pulls/N at adoption time): the hive posts ONE comment, moves the PR to `stage/074-adopted-by-hive` and files it in `ci-failing.json` as its own (`"adopted": true`, `reachable_action: push`, conflicted rows included — ordinarily only hive-authored conflict PRs are listed) so the scanner's FIX-BEFORE-NEW kick rebases and fixes CI **on the PR's branch**. No superseding PR, no `hive/adopt-<n>` branch; the PR then runs the normal `050 → 100` path. The hive's own pushes keep the adoption (the stage stays 074). A push by anyone else means the contributor is back: the hive yields — ONE note, the adoption is forgotten and the PR is back on the ordinary 072 flow (a fresh nudge for the new head; it may be adopted again under the same rules).
   • supersede (mode=supersede) — the fork forbids maintainer edits, or in_place: false:
   • pushes hive/adopt-<n> in the base repo at the contributor’s head SHA (the fork’s commits, authorship and Signed-off-by preserved byte for byte — “sign-off survives the squash”);
   • opens an App PR from it against the same base, titled like the original, whose body starts Supersedes #N (adopted after CI went red and the contributor was unavailable; original commits by @author preserved), carries the original’s Closes/Fixes/Resolves lines and instructs the fix agent to rebase on the base and fix CI on that branch without opening another PR;
   • posts ONE comment on the original and moves it to `stage/074-adopted-by-hive` (its linked issue mirrors the stage). The hub drops the PR from the contributor's fix queue (either mode). The superseding PR is App-authored and red with the same failures, so the existing machinery takes over: it lands in `ci-failing.json` and the scanner's FIX-BEFORE-NEW kick (the route every red hive-authored PR takes, [hive-merge.md](https://github.com/hivecommons/hive/blob/v5/src/docs/hive-merge.md#stage-labels)) rebases and fixes it on `hive/adopt-<n>`; it then runs the normal `050 → 100` path. No second takeover mechanism exists. One adoption attempt per contributor head, whatever the outcome. While in 074 the hive polls the superseder at most every 10 minutes: merged → one note and the original is closed; closed unmerged (a maintainer declined) → the adoption is forgotten and the original returns to 072 (not a regression).
4. A new head from the author at any point before adoption re-arms the nudge (grace restarts) or, if green, returns the PR to the normal 050 → 100 path; no adoption. After a superseding adoption the author can still push a new head on the original and say so on the superseder; after an in-place adoption their push makes the hive yield (above). The contribute page’s “PRs awaiting rework” list for a relay shows adopting (contributor offline) on a nudged PR whose relay connection is stale, and adopted by hive once the PR is in 074.
5. Backpressure — the per-contributor fix budget. Capacity = the relay’s advertised max_parallel_fixes (fix sub-sessions beside the primary), clamped by contribute.max_parallel_fixes (default 2); an unadvertised relay has capacity 1 (preempt mode). At most that many fix-pr tasks are in flight per contributor; the rest wait in a per-contributor FIFO (oldest PR first, a human changes-requested before CI-red) carrying stage 072 and the GitHub comment only. Preempt mode allows ONE preemption at a time and never preempts again until the parked task has resumed and run for contribute.min_focus_window (default 30m). Failures with the same cause (same failing check + error signature) are coalesced into one task listing every affected PR. A queued PR whose adoption grace expires goes to 074 instead of interrupting — the hive absorbs the overflow, not the human. Queue depth / in-flight is exposed as fix_queue on the contributor profile API and on the contribute page; the hub logs one line per enqueue/dequeue (fixqueue: … event=…).
6. Governing rule of the contributor fix scheduler, verbatim from the operator: “contributors should clean up their mess before taking on new stuff.” Every ordering decision — task boundary, dequeue, a new-issue claim via the relay or the contribute page — checks the contributor’s red-PR queue first: queued fix-pr tasks are handed out oldest first (even to a relay that advertises no fix-pr support, as an ordinary task) and a fresh issue is served only when that queue is empty. The contribute page shows “You have N PRs to fix first” and offers those PRs before new issues. Preemption of in-progress work still obeys the single-preempt + focus-window rule; this ordering applies at task-boundary time.
7. Capacity ≥ 2: fixes are dispatched immediately as parallel sub-sessions, up to the advertised count so the primary session keeps going and is never preempted; further failures queue, and each finished fix session (task_complete/task_failed for the fix’s task_id) frees a slot that is refilled automatically with the next queued fix-pr.

All seven steps ship with the stage engine and the contribute hub (hivecommons/hive#12436).

Modifiers, not stages

These existing labels qualify a stage and may coexist with any stage label; the reconciler never touches them: hold / hold/*, needs-human, blocked, needs-rebase, hive/likely-done, hive/partially-addressed, hive/verified-open, hive/claimed-by-<who> (the grey “who” modifier a stage cannot carry), lgtm, role/*, author/*, dco / no-dco, and the agent provenance labels.

hive/partially-addressed and hive/verified-open are merged-PR evidence, not stages, and stay coherent with the stage model: both describe what a PR that already merged did (or did not) finish, while the stage says where the issue is now. An issue wearing them is back in the pipeline — 010 once nothing covers it, 020/030/040 as new work starts — and the two labels tell the next kick and the close-on-merge sweep how to treat it: do not re-verify, do not label hive/likely-done from the same stale claim, implement the remainder (src/pkg/scheduler/kickmessage.go, src/pkg/github/prclaims.go, src/pkg/github/task_list_sweep.go, src/cmd/hive/verifyonce.go). They are not a second stage and are not retired.

hive/claimed-by-<who>: one rule for the suffix

<who> names the party accountable for the claim, derived from the claim marker by claims.ClaimedByLabel (src/pkg/claims/claimedby.go):

A backend or model name (copilot, claude, codex, gemini, pi) is never a suffix: it names the tool, not who answers for the work. A hive-agent claim whose name is a backend falls back to hive/claimed-by-agent; a human/contributor claim with no usable login gets no label. The suffix keeps the login’s case and is reduced to [A-Za-z0-9_-]; session= / hive= are not inputs. The writers all go through the helper — the claim relay (hive-open-issue claim, src/pkg/github/issue_inprogress.go) and the claim-ledger hooks (src/cmd/hive/claimswire.go, Client.ApplyClaimedByLabel), which add the claim’s own label and strip only backend-named hive/claimed-by-* labels when a claim lands (another party’s principal label is kept), and remove the holder’s label — only the holder’s — when the ledger releases or hands the claim over. The ledger maintains at most one live claim per (repo, issue); thus, co-party hive/claimed-by-* labels on the same issue arise only from hand-applied labels or persistent debris left by an earlier holder, never from the ledger modeling concurrent co-parties. The issue reconciler heals the one malformed form a hand-applied label can introduce: a backend-named suffix is swapped for the live holder’s login (dropped when the issue carries no live claim); a label naming a principal is never touched, so an issue may carry one label per party (a person’s and a contributor’s) while both claims are live.

Migration from retired labels

🐝 covered by PR (and its pre-#11888 spelling hive/covered-by-pr), the bare claimed label and hive/in-progress are retired: their meaning is carried by stage/040-covered-by-pr, stage/020-claimed and stage/020-claimed / stage/030-pr-in-progress. Claim detection never read those labels — it uses the “ marker comment (claim_source=marker), assignees and the ledger — so removing them changes no gate. On the first cycle after upgrade the reconciler removes them from every open item it writes a stage for, so open items lose claimed / hive/in-progress / 🐝 covered by PR and gain their stage label; the repo-level labels can be deleted afterwards. The legacy writers are gone: the claim relay and ledger mirror write stage/020-claimed / stage/030-pr-in-progress, the PR-claim sync writes stage/040-covered-by-pr, and the in-progress sweep still recognises hive/in-progress as a trigger for one migration cycle so a lapsed mark from an older spoke is cleared rather than orphaned. hive/claimed-by-<who> is kept as the grey “who” modifier.

Prow’s dco-signoff: yes / dco-signoff: no are retired the same way (#12542): the stage pass removes them from an open PR as soon as it has read that head’s commits and written dco / no-dco; readers accept the legacy pair until then. The Prow dco plugin itself must be disabled for the org in the Prow plugins.yaml (hivecommons/infra) or it will keep re-adding them.

Matching rules

• GitHub generic holds are case-insensitive substring matches against hold, on-hold, hold/review, plus configured non-hive-pause/ extra holds. A label such as threshold contains hold and therefore holds (src/pkg/github/client.go:1894-1932).
• hive-pause/<hive-id> is case-insensitive exact match, not substring, so it never collided with the retired hive/<hive-id> provenance label (src/pkg/github/client.go:1898-1932).
• Exempt labels use case-insensitive equality or prefix for permanent/configured labels, but the prefix check uses the original label string (src/pkg/github/client.go:2030-2048).
• Contributor skip labels are lowercased and matched with path.Match glob syntax; invalid globs fall back to exact case-insensitive matching (src/pkg/config/config.go:4658-4708).
• Lane routing lowercases labels and matches lane/routing tokens by segment, so agent/scanner can route to scanner; PR agent/ ownership paths are stricter and should be treated as case-sensitive operationally. The wrapper writes agent/<lane> from HIVE_AGENT, so the label always carries a routable token (src/pkg/classify/classifier.go:249-276, bin/gh-wrapper.sh:1068-1113).
• Planning and triage labels are exact label names after normalization; defaults are prefixed (hive-plan, hive-design) so ordinary plan or capitalized Epic taxonomy does not trigger planning (src/pkg/config/config.go:400-460, src/pkg/classify/triage.go:66-84).
• Linear holds use GitHub-like case-insensitive substring matching with defaults plus work_source.linear.hold_labels (src/pkg/worksource/linear.go:344-355).
• Jira holds use exact, case-sensitive equality against configured work_source.jira.hold_labels; there is no built-in Jira default (src/pkg/worksource/jira.go:50-68, src/pkg/worksource/jira.go:302-330).
• GitHub Projects work source carries labels through but does not implement a hold-label gate (src/pkg/worksource/github_projects.go:370-405).

Config that changes label behavior

• github.self_authorization_hold, project.repo_policies[].self_authorization_hold, and HIVE_SELF_AUTHORIZATION_HOLD change #5117 holds. When all are unset, the default follows the live ACMM level: on through L5, off at L6 Fully Autonomous.
• Hive-wide ACMM level controls level holds; per-repo ACMM overrides do not make PRs skip the level hold.
• governor.labels.exempt, governor.labels.automerge, and project.issue_filter.require_labels decide exempt/admit/queue behavior.
• project.issue_filter.reporter_trust.* (admission by reporter), github.reporter_trust_hold, project.repo_policies[].reporter_trust_hold, and HIVE_REPORTER_TRUST_HOLD (the matching merge hold) are the #9665 reporter-trust gate. Off unless reporter_trust.enabled: true; the hold follows that switch unless set on its own. Both are edited under Settings → Labels (who is trusted, which triage label) and Settings → Repos (the hold).
• planning.plan_from_label, planning.plan_labels, planning.design_labels, and planning.design_approved_label control planning labels, with the L5+ planning floor.
• runs.triage.enabled, runs.triage.spec_labels, and runs.triage.fix_labels control run triage labels.
• governor.question_autoclose.* (HIVE_QUESTION_AUTOCLOSE, HIVE_QUESTION_AUTOCLOSE_HOURS) closes answered question issues; see Question auto-close.
• governor.claims.*, review.human_decision_label, hub.contribute_*, dashboard.issue_bands.*, and HIVE_ACTIONABLE_PRIORITY_LABELS control the display/contributor/ranking labels above, including contributor label allow/deny filters and per-repo narrowing.
• work_source.linear.hold_labels and work_source.jira.hold_labels are non-GitHub label-equivalent gates with the different matching rules described above.
• Not labels: project.paused_repos pauses an entire repo; contributor queue holds can park owner/repo#N without changing GitHub labels.

Question auto-close

Off by default (#9584). When on, a question issue the hive has answered is closed after a short window unless the person who asked objects, so answered questions stop inflating the open-issue count and being rescanned every sweep.

governor:
  question_autoclose:
    enabled: true          # or HIVE_QUESTION_AUTOCLOSE=true
    hours: 4               # or HIVE_QUESTION_AUTOCLOSE_HOURS; default 4
    labels: [question, kind/question]   # default; what marks a question
    human_label: needs-human            # default; added when the author objects

How it works:

1. The scanner kick gains a short answer contract: an issue that only asks a question gets the question label and ONE answer comment, which ends with a hidden “ marker and the line “If this doesn’t answer your question, react 👎 to this comment and the issue will stay open.” The footer text is built by Hive and passed through the mention sanitizer.
2. Hive watches question-labelled issues from the normal issue pass. When the last comment on one is a marked answer posted by the hive’s own identity (the GitHub App bot login <app-slug>[bot] or project.ai_author), it schedules a close at answer time + hours. The schedule lives in /data/question-autoclose.json, so a restart keeps the original deadline. The marker is plain text, so a marked comment from any other account (a person or another bot pasting it) is ignored and never starts the clock; with no hive identity known, nothing is auto-closed.
3. At the deadline Hive re-reads the issue. A 👎 from the issue author on the answer keeps it open and adds human_label. Otherwise the issue is closed with state_reason: completed and no extra comment, so the answer stays the last thing Hive said.

A schedule is cancelled (never acted on) when anyone comments after the answer, the issue is closed by someone else, the question label is removed, or a bug, enhancement, hold or human_label label appears. Bugs (bug, kind/bug, human-filed bug reports), enhancements/features and held issues are never auto-closed. A cancelled or finished answer is remembered for 30 days so the same answer is never scheduled twice; a new answer after a follow-up starts a new window.

Dashboard

The Governor dialog’s Features tab has a “Question Auto-Close” section: a switch for enabled and a field for hours (GET/PUT /api/config/governor/question-autoclose, owner-only, same pointer/only-what-you-send contract as the other governor-config sections). Turning it on there shows a read-only live-schedule table underneath — one row per answered issue currently waiting out its objection window (repo/issue, answered-at, closes-at), backed by GET /api/config/governor/question-autoclose/schedule. The table is read-only: labels/human_label still need hive.yaml.

Hive activity monitor

The dashboard renders every open issue and PR’s stage as one unified tracker strip in the Hive activity monitor section (GET /api/stage-tracker): Open → 010 → 020 → 030/040 (PR in progress) → 050/060 (CI / Review) → 080/100 (Merge gate) → merged, with 060/080/100 lit as “Ready for auto merge” (tooltip: not yet admitted vs admitted, merging), 070/072/074 as the lit CI / Review step named after the side stage, and 085/090 as Merge gate lit “Needs human decision” / “Ready for human merge”. 070 “Fixing” is the author’s move (a needs-rebase chip says what is being fixed — needs-rebase always lands at 070/072, never at 050/060). An issue with exactly one covering PR is a single entry whose strip is driven by the PR’s stage from 030 on; with two or more covering PRs the issue’s own strip stops at 020 Claimed and each PR nests beneath as an indented sub-row ([author/*-coloured icon] #N title plus its own strip from PR in progress on), and PRs linked to a listed issue have no top-level row (nested_under). stage/stalled and the store’s regressed marker (the retired stage/regressed label’s successor) appear as chips and colour the since value; the stage store’s per-item transition history (last eight hops) is in the row tooltip. See dashboard.md.

Lifecycle examples

Strategist-filed direction to a PR

1. Strategist files an issue with [strategist]/agent/strategist. It is actionable but lower-ranked as hive-filed.
2. A maintainer adds approved-direction, assigns a human, or comments. Label or assignee also improves ranking; a comment only satisfies #5117.
3. An agent opens a PR citing the issue. If the acknowledgement existed before PR creation, no #5117 hold is applied. At L3-L5, the separate level hold can still apply.
4. If acknowledgement is added after a PR already has hold, remove the PR hold too.

Holding an issue

1. Add hold/on-hold/hold/review, or use dashboard ⏸ Hold to add hive-pause/<hive-id>.
2. Enumeration moves it to the Hold list. It leaves agent kicks and the contributor queue.
3. Caveat: the task-list and SHA sweeps do their own listing but honour the same hold predicate; SHA-hold lifts only the literal hold it applied itself.
4. Hard-suppress reconcile (#12002): every issues.hard_suppress_reconcile_interval (default 30m, unstick step of the eval loop), Hive lists open hold/blocked issues in its repos and lifts a label only when the newest event for it is a labeled by the App bot (for hold, also paired with the notice) **and** a cross-referencing PR merged after that event. It posts one note carrying. Disable with issues.lift_hive_hard_suppress: false.
5. Remove the hold label or click ▶ Release; it is reconsidered on the next enumeration.

Holding a PR

1. The PR receives hold from a human, the level gate, #5117, holdguard, or SHA-related policy, or receives needs-human from a human/escalation workflow.
2. It is not merge-eligible or auto-merged; self-authored and queued auto-merge sweeps treat needs-human like a live hold label. If CI is red and it is not a held outreach PR or escalated, its owning agent may still be asked to fix CI without removing the hold.
3. If the branch moves while held and then the hold is lifted, holdguard re-adds hold; removing it again is the fresh approval.

Escalation

1. Red CI across the distinct-SHA budget applies PR needs-human; automated fix dispatch stops.
2. Reviewer lane may add reviewer-passed and remove/un-escalate needs-human, or add reviewer-recommend-close.
3. A human can remove needs-human after addressing the root cause; the ledger resets after the grace period.

Non-label equivalents

• Human comments and assignees can acknowledge hive-filed directions for #5117; assignees also affect ranking.
• Hidden comment markers carry state that no label does. records an issue claim, dedupes a published finding, marks an overlap notice, starts the question auto-close clock, and is stamped on the single comment a fix lane leaves on a PR it defers to shared incident `#<n>` (`DEFER_TO_INCIDENT` from `bin/hive-baseline-check.sh`), so "every PR incident `#<n>` broke" stays greppable after the fix lands ([#10441](https://github.com/hivecommons/hive/issues/10441)). One marker per PR per incident; it is never edited or removed while the incident is open. While incident `#<n>` is open, the governor records it as `deferred_incident` on the PR's `ci-failing.json` row and the kick builders keep that PR out of every CI-FAILING / FIX-BEFORE-NEW repair list, naming it only as deferred; once the incident closes the PR is listed for repair again ([#10528](https://github.com/hivecommons/hive/issues/10528)). When the incident closes (not as "not planned"), the shared-CI rerun sweep re-runs the failed jobs of each still-open PR carrying that marker — the newest failed or timed-out run per workflow on the PR head — using the hive's own credential, then stamps on the PR so it is re-run at most once per incident; disable with shared_ci_rerun.enabled: false (#12253).
• Paused repos (project.paused_repos) stop whole-repo write/merge/enumeration paths without labels.
• Contributor queue holds such as active leases, cooldowns, dependencies, and quota guard holds suppress contributor offers without touching GitHub labels.
• Jira/Linear labels map only where the work-source adapter supports them: Linear skips held work using substring hold labels; Jira skips exact configured hold labels; GitHub Projects currently imports labels but does not use a hold gate.

Repo-card legend vocabulary

The repository-card legend is a UI vocabulary, not a second scheduler. Unclaimed, claimed, needs-triage, needs-human, and confirm-and-close issue bands are computed client-side from labels/assignees, the snapshot’s human_acknowledged flag (the cheap half of the #5117 acknowledgment: approved-direction or a human assignee, no comment scan), and dashboard.issue_bands; PR bands are computed client-side from held/needs-human labels, merge verdicts, CI, review links, draft state, and the same waiting/stale display config. Non-winning states stay as badges. State glyphs such as ⛔, ❓, 👤, ✓, role badges, stale 🕒, PR ✓/◐/⚠, held ⏸, failing CI ✗ CI, conflicts ⑂, reviewed 💬, auto-merge 🔀, and review-class badges explain the same data the table above names. A PR carrying the configured sentinel alert label (sentinel.label, default sentinel-alert, case-insensitive) is drawn as a red sentinel pill that wins over the held, needs-human and merge colours; the legend explains that Hive will not merge it until a maintainer removes the label and that trusted-author PRs, which normally get only a sentinel comment, are usually not red. Changing a band label changes the repo card description only; it does not make an item held, exempt, mergeable, or actionable.

Documented inconsistencies and follow-ups

Issue #8924 recorded the sharp edges of this page’s first version; #8927 aligned the code: auto-merge sweeps, the task-list sweep, and the SHA-hold sweep now gate on the enumeration hold predicate (so hive-pause/<hive-id> holds everywhere), SHA-hold lifts only its own hold, policy templates name the enforced hold set, and agent/<role> is always the lane name. Two behaviours remain deliberate rather than fixed:

• Level-hold and #5117 disabled-policy auto-release are different. The self-authored auto-merge sweep may still release its own #5117 self-authorization holds, but ACMM level-applied holds are never auto-released by a sweep or level change. They are released by a human removing hold, or by a deliberate one-off PUT /api/packs/level with release_level_holds: true, which touches only Hive App level-hold notices whose latest hold event was by the App.
• hive-open-pr discards every --label value, including hold, because the PR-request watcher applies holds server-side (bin/hive-open-pr.sh:142-150, src/docs/hive-open-pr.md).