Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/changed-18468-hive-gate-labels.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- The hive no longer applies `hold` itself: a PR its ACMM level gate holds for review now gets `ready-for-review`, and items blocked on a human decision (reporter trust, self-authorization, the hold guard's re-hold, owner-only decisions) get `decision-needed`; both block merging exactly like `hold`, carry a label description saying who acts next, and are renameable via `governor.labels.ready_for_review` / `governor.labels.decision_needed`. A `hold` a person adds still means hands-off. On boot the hive swaps the `hold` labels it can prove it applied (App label event plus its gate notice) for the new labels and leaves every other `hold` alone; the SHA-hold sweep now gives every reporter `needs-sha` instead of `hold`.
3 changes: 3 additions & 0 deletions src/cmd/hive/github_client_config.go
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,9 @@ func (b *boot) applyGitHubClientConfigHooks(client *github.Client) {
client.SetAuthorKindLabels(func() authorkind.Names { return b.cfg.Governor.Labels.Author.Names() })
client.SetLinearScopeTeams(b.cfg.Governor.WorkSource.Linear.Teams)
client.SetHoldLabels(b.githubHoldLabels())
// The gate labels the hive applies instead of `hold`
// (hivecommons/hive#18468): process-wide, like github.HoldLabels.
github.SetHiveGateLabelNames(b.cfg.Governor.Labels.ReadyForReviewLabelOrDefault(), b.cfg.Governor.Labels.DecisionNeededLabelOrDefault())
// Umbrella issues no automated claim may take and no claim stages
// (governor.claims.never_claim_labels, default `epic`).
client.SetNeverClaimLabels(b.cfg.Governor.Claims.EffectiveNeverClaimLabels())
Expand Down
30 changes: 30 additions & 0 deletions src/cmd/hive/hive_gate_labels_18468_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
package main

import (
"testing"

"github.com/hivecommons/hive/pkg/github"
"github.com/hivecommons/hive/pkg/holdguard"
)

// hivecommons/hive#18468: the hive's gate labels block a merge exactly like
// a person's `hold`, and the hold guard re-holds with decision-needed.
func TestHiveGateLabelsBlockMergeLikeHold(t *testing.T) {
for _, label := range []string{"hold", github.DefaultReadyForReviewLabel, github.DefaultDecisionNeededLabel} {
if got := automergeBlockLabelReason([]string{"kind/bug", label}, true); got != "label:hold" {
t.Errorf("automergeBlockLabelReason(%q) = %q, want label:hold", label, got)
}
}
if got := automergeBlockLabelReason([]string{"not-ready-for-review"}, true); got != "" {
t.Errorf("look-alike label blocked with %q", got)
}
}

func TestHoldGuardNeverReappliesHold(t *testing.T) {
if holdguard.ReHoldLabel == github.LegacyHiveHoldLabel {
t.Fatal("the hold guard re-applies hold; the hive must never apply hold itself")
}
if holdguard.ReHoldLabel != github.DefaultDecisionNeededLabel {
t.Fatalf("holdguard.ReHoldLabel = %q, want %q", holdguard.ReHoldLabel, github.DefaultDecisionNeededLabel)
}
}
16 changes: 15 additions & 1 deletion src/cmd/hive/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -2150,7 +2150,7 @@ func (b *boot) bootAgentsWith(deps bootAgentsDeps) {
// the direct `gh pr create` path — the request-file route grants no extra
// privilege. A denied request is quarantined, never opened.
// holdLabel (F6): at hold-gated ACMM levels (L3/L4/L5) every agent-opened
// PR must carry the "hold" label so the merge gate holds it for human
// PR must carry the ready-for-review gate label ("hold" before #18468) so the merge gate holds it for human
// approval. Outreach content aimed at a repository the hive does not
// manage is public speech into someone else's project, so it remains
// human-reviewed at L6 too; outreach PRs into the agent's own repos are
Expand Down Expand Up @@ -6150,6 +6150,20 @@ func (b *boot) runLoopWith(deps runLoopDeps) {
b.dashSrv.AddSystemAlert(holdMigrationFailedAlertID, "warning", holdMigrationFailedAlertMessage(b.cfg.HiveID, reportPath))
}
}
// hivecommons/hive#18468: the hive no longer applies `hold` itself.
// Swap the holds its own gates applied (App label event + gate
// notice) for ready-for-review / decision-needed, and make sure both
// labels exist with their descriptions. A person's `hold` is never
// touched. Off the boot path: it is bounded per repo and a failure
// only leaves old holds in place (still blocking) until next boot.
go func(ghClient *github.Client) {
res, err := ghClient.MigrateHiveAppliedHolds(b.ctx)
if err != nil {
b.logger.Warn("hive gate label migration incomplete; unmigrated hive holds keep blocking and retry next boot", "error", err, "relabeled", res.Relabeled, "skipped", res.Skipped)
return
}
b.logger.Info("hive gate label migration complete", "relabeled", res.Relabeled, "skipped", res.Skipped)
}(b.ghClient)
// Provenance-only migration. Retired reviewer labels map to agent/reviewer;
// redundant lane-origin labels are removed. Nothing reads origin/* as a gate,
// so a failure here only leaves old names on open items; the marker is not
Expand Down
2 changes: 1 addition & 1 deletion src/cmd/hive/main_helpers.go
Original file line number Diff line number Diff line change
Expand Up @@ -284,7 +284,7 @@ func enforceHoldGuard(
}
store.MarkCommented(repo, pr.Number)
}
if err := writer.AddLabels(ctx, pr.Repo, pr.Number, []string{holdguard.ReHoldLabel}); err != nil { // writeback:gated
if err := writer.AddLabels(ctx, pr.Repo, pr.Number, []string{github.DecisionNeededLabelName()}); err != nil { // writeback:gated
// Commented but not re-held: the snapshot stays on the OLD head,
// so next tick re-detects the drift (comment deduped) and retries
// the label. Never re-arm before the label sticks.
Expand Down
10 changes: 8 additions & 2 deletions src/cmd/hive/merge_eligibility.go
Original file line number Diff line number Diff line change
Expand Up @@ -281,7 +281,8 @@ func sentinelTrustedAuthorFunc(cfg *config.Config, ghClient *github.Client) func
var mergeEligiblePath = "/var/run/hive-metrics/merge-eligible.json"

// acmmHoldGatedMinLevel / acmmHoldGatedMaxLevel bracket the ACMM levels whose
// merge policy is "hold-gated" — every agent-opened PR gets a "hold" label and
// merge policy is "hold-gated" — every agent-opened PR gets the ready-for-review
// gate label (the literal "hold" before hivecommons/hive#18468) and
// no agent merges (see src/pkg/config/packs/level-{3,4,5}.yaml). L1/L2 are
// "manual" (agents open no PRs) and L6 is "auto-merge on green CI, no hold
// label", so both fall outside this range. Used by the F6 hold-label decider.
Expand All @@ -291,7 +292,7 @@ const (
)

// shouldHoldAgentPR decides whether a freshly opened agent PR must carry the
// "hold" label. The general ACMM hold gate applies to every role at L3-L5.
// ready-for-review gate label. The general ACMM hold gate applies to every role at L3-L5.
// Outreach adds one level-independent reason: a PR that targets a repository
// OTHER than the ones the outreach agent is working on behalf of (ownsRepo
// false) is public speech into somebody else's project and stays
Expand Down Expand Up @@ -777,6 +778,11 @@ func automergeBlockLabelReason(labels []string, trusted bool) string {
return "label:" + lower
case lower == "hold" || strings.Contains(lower, "hold"):
return "label:hold"
case github.IsHiveGateLabel(trimmed):
// The hive's own gate labels (ready-for-review, decision-needed;
// hivecommons/hive#18468) block exactly like `hold`, so they
// report the same reason the lanes and stage engine key on.
return "label:hold"
}
}
return ""
Expand Down
6 changes: 4 additions & 2 deletions src/docs/hive-open-pr.md
Original file line number Diff line number Diff line change
Expand Up @@ -132,8 +132,10 @@ one deliberate exception:
(`bin/hive-open-pr.sh:149`). No warning is printed, on purpose: `--label hold`
is in every hold-gated policy template, so it arrives on essentially every
agent PR, and "ignoring unrecognized flag `--label`" would read to an agent
mid-run as "your PR will not be held" — the opposite of the truth. The `hold`
label does land, but not because of the flag: the PR-request watcher applies it
mid-run as "your PR will not be held" — the opposite of the truth. The PR is
held, but not because of the flag, and not with `hold`: the PR-request watcher
applies the `ready-for-review` gate label (`decision-needed` for the #5117 and
reporter-trust gates; the hive never applies `hold` itself, #18468)
server-side from authoritative ACMM config after the PR is created
(`src/pkg/github/pr_request_watcher.go:452-524`), and treats a failure to apply it
as a failed request, not a cosmetic miss. Every **other** label in the flag's
Expand Down
14 changes: 8 additions & 6 deletions src/docs/labels-and-control-signals/glossary-and-operations.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,9 @@ The plain-words comment the delegate posts has four lines — **Hive decided** (
| `contributor-lane:sentinel-blocked`, `sentinel`, `sentinel-alert`, `sentinel-blocked` | security-sensitive files changed; a maintainer must approve | Security-sensitive files changed. The hive never merges until a maintainer reviews and removes the sentinel label. |
| `dco`, `dco-missing` | a commit is missing its sign-off | A commit on the branch is missing its Developer Certificate of Origin sign-off; the author must sign it off. |
| `effect-unknown` | the hive did not say why | The hive could not tell from the lane reason why the decision has not taken effect. |
| `hold` | on hold; the hive does nothing until it is released | The item is on hold. The hive does nothing with it until a person releases the hold. |
| `hold` | on hold; the hive does nothing until it is released | The item is on hold. The hive does nothing with it until a person releases the hold. Only a person applies `hold`; the hive never applies or removes one ([#18468](https://github.com/hivecommons/hive/issues/18468)). |
| `ready-for-review` | the hive's work is done; waiting on a maintainer's review | The hive applied it (ACMM level gate). It blocks merging like `hold`; a maintainer reviews the PR and removes the label to let it merge. |
| `decision-needed` | the hive is blocked on a human decision | The hive applied it (reporter trust, #5117 self-authorization, holdguard re-hold, owner-only decision) and its comment says what to decide. It blocks merging like `hold`; a maintainer decides and removes it. |
| `label:needs-human`, `needs-human`, `requires_human` | waiting for human input; inspect whether it is a label or a review verdict | For an issue's `needs-human` label, an eligible maintainer command clears it on the ordinary un-park path regardless of provenance; keep `hold` if work must remain stopped. A PR's `requires_human` swarm verdict is answered by exact-head approval as described in the review reference; it is not itself a label to remove. Other gates and label-driven repository policy remain authoritative. |
| `no-effect` | the decision hasn't taken effect | The hive recorded this decision, but what it was supposed to cause has not happened within the expected time. |
| `no-new-commit` | no new commit has been pushed | The hive gave direction, but no new commit has been pushed yet. |
Expand Down Expand Up @@ -133,7 +135,7 @@ Some sweeps list items themselves. They still use the same hold predicate (`Clie

- Auto-merge sweeps use `Transport.IsHeldLabels`. The queued (`lgtm`) sweep skips a held PR before fetching it; the self-authored sweep skips held PRs and `needs-human` before merge (`src/pkg/github/automerge/automerge_sweep.go:23-38`, `src/pkg/github/automerge/automerge_sweep.go:954-959`, `src/pkg/github/automerge/automerge_sweep_loop.go:13-48`, `src/pkg/github/automerge/automerge_sweep_loop.go:73-92`).
- The task-list sweep skips held issues before its exempt / issue `needs-human` gate. It does not comment on, relabel or close them (`src/pkg/github/task_list_sweep.go:848-854`).
- The SHA-hold sweep lists primary-repo `kind/bug` issues itself. Without a SHA it adds literal `hold` and a marker notice; trusted reporter associations instead get soft `issues.sha_hold_trusted_label` (default `needs-sha`, #12002). It removes only its own current hold: the newest label event must be a `labeled` by the App bot with an App-authored SHA-hold notice at or after it (`EnforceSHAHold` / `shaHoldIsOwn` in `src/pkg/github/client.go`).
- The SHA-hold sweep lists primary-repo `kind/bug` issues itself. Without a SHA it adds `issues.sha_hold_trusted_label` (default `needs-sha`) and a marker notice for every reporter; it never applies `hold` (#18468; before that, untrusted reporters got literal `hold`, #12002). It removes only its own current hold: the newest label event must be a `labeled` by the App bot with an App-authored SHA-hold notice at or after it (`EnforceSHAHold` / `shaHoldIsOwn` in `src/pkg/github/client.go`).
- PR-request watching applies server-side holds after creation; the wrapper discards an agent's `--label hold` (`src/pkg/github/pr_request_watcher.go:452-524`, `bin/hive-open-pr.sh:142-150`).

Policy templates also say to respect `hold`, `on-hold`, `hold/review`, `hive-pause/<hive-id>`, any label containing `hold`, and exempt `do-not-merge`. That instruction is a prompt-level backstop; enumeration and sweep checks are the hard enforcement.
Expand Down Expand Up @@ -200,7 +202,7 @@ The dashboard renders every open issue and PR's stage as one unified tracker str
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.
4. If acknowledgement is added after a PR already has `decision-needed` (or a pre-#18468 `hold`), remove that label too.

### Holding an issue

Expand All @@ -212,9 +214,9 @@ The dashboard renders every open issue and PR's stage as one unified tracker str

### 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.
1. The PR receives `hold` from a human, `ready-for-review` from the level gate, or `decision-needed` from #5117, reporter trust or holdguard, 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. If a human lifted the gate after the current head arrived (for example a Renovate rebase earlier during the hold), proven by GitHub's server-stamped force-push event or by the hive having seen that head while the PR was still held (never the commit date or SHA-keyed check-suite/status times), that lift already covers the current head and holdguard does not re-hold (#13603).
3. If the branch moves while held and then the hold is lifted, holdguard re-adds `decision-needed` (`hold` before #18468); removing it again is the fresh approval. If a human lifted the gate after the current head arrived (for example a Renovate rebase earlier during the hold), proven by GitHub's server-stamped force-push event or by the hive having seen that head while the PR was still held (never the commit date or SHA-keyed check-suite/status times), that lift already covers the current head and holdguard does not re-hold (#13603).

### Escalation

Expand All @@ -238,5 +240,5 @@ The repository-card legend is a UI vocabulary, not a second scheduler. Unclaimed

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.
- 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 `ready-for-review`, 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 `ready-for-review` 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`).
Loading
Loading