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 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 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; both the queued (lgtm) and the self-authored sweep skip a held PR before fetching it (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:797-815).
• The SHA-hold sweep lists primary-repo kind/bug issues itself, adds literal hold plus a marker notice when no SHA is present, and removes hold 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 (src/pkg/github/client.go:2467-2532, src/pkg/github/client.go:2582-2604).
• 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.

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

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 does not collide with hive/<hive-id> provenance (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:250-285).

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 asks a question gets the question label and 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 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 — 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.

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 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 the literal hold it applied itself.
4. 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.
2. It is not merge-eligible or auto-merged. If CI is red and it is not outreach/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). 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 as deferred; the incident closes the PR is listed for repair again (#10528).
• 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 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. Changing a band label changes the repo card description; 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 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-off PUT /api/packs/level with release_level_holds: true, which touches 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).