From 7a0e13d61ba6f90666eabf581c75c6b9b4e8f71a Mon Sep 17 00:00:00 2001 From: Andy Anderson Date: Mon, 16 Nov 2026 17:32:42 -0500 Subject: [PATCH 1/6] =?UTF-8?q?=F0=9F=90=9B=20hive=20never=20applies=20hol?= =?UTF-8?q?d=20itself;=20gates=20use=20ready-for-review=20/=20decision-nee?= =?UTF-8?q?ded=20(#18468)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A hold placed by a person still means hands-off: the hive never implements, decomposes, relays or merges a held item and never removes the label. The hive's own gates no longer overload hold: - ACMM level gate (and cross-repo outreach) -> ready-for-review - #5117 self-authorization, #9665 reporter trust, holdguard re-hold, owner-only delegated decision -> decision-needed - SHA-hold sweep -> needs-sha for every reporter Both gate labels block merges exactly like hold (exact-match members of the hold set), are created with descriptions saying who acts next, are reserved from agents, and are renameable via governor.labels.ready_for_review / decision_needed. A boot migration swaps hold for the gate label only when the newest hold event is the App's and an App-authored gate notice is on the thread; every other hold is left alone. Fixes #18468 Signed-off-by: Andy Anderson --- changelog.d/changed-18468-hive-gate-labels.md | 1 + src/cmd/hive/github_client_config.go | 3 + src/cmd/hive/hive_gate_labels_18468_test.go | 30 +++ src/cmd/hive/main.go | 16 +- src/cmd/hive/main_helpers.go | 2 +- src/cmd/hive/merge_eligibility.go | 10 +- src/docs/hive-open-pr.md | 6 +- .../glossary-and-operations.md | 14 +- .../labels-and-control-signals/reference.md | 51 ++-- src/hive.yaml.example | 2 + src/pkg/config/config.go | 38 +++ src/pkg/config/hive_gate_labels_18468_test.go | 20 ++ src/pkg/config/issues.go | 5 +- src/pkg/dashboard/api_packs_acmm_hook_test.go | 6 +- .../api_repo_item_decide_delegated.go | 2 +- .../api_repo_item_decide_delegated_test.go | 2 +- src/pkg/dashboard/bands.go | 2 +- .../dashboard/settings_parity_allowlist.txt | 2 + .../delegatedecision/hold_label_18468_test.go | 58 ++++ src/pkg/delegatedecision/llm.go | 6 +- src/pkg/delegatedecision/policy.go | 34 ++- .../github/automerge/automerge_stage_human.go | 4 +- .../automerge/automerge_stage_labels.go | 9 +- .../github/automerge/automerge_sweep_test.go | 6 +- .../automerge/reporter_trust_release.go | 39 ++- .../automerge/reporter_trust_release_test.go | 50 ++-- .../automerge/self_authorization_release.go | 8 +- .../self_authorization_release_test.go | 12 +- src/pkg/github/client.go | 104 +++---- src/pkg/github/coverage_boost_test.go | 35 --- src/pkg/github/hive_gate_label_migration.go | 187 +++++++++++++ src/pkg/github/hive_gate_labels.go | 146 ++++++++++ src/pkg/github/hive_gate_labels_test.go | 254 ++++++++++++++++++ src/pkg/github/issue_request_label.go | 4 +- src/pkg/github/pr_decision_operator.go | 2 +- src/pkg/github/pr_level_hold.go | 28 +- src/pkg/github/pr_level_hold_pending_test.go | 18 +- src/pkg/github/pr_level_hold_test.go | 8 +- src/pkg/github/pr_reporter_trust.go | 30 ++- src/pkg/github/pr_reporter_trust_release.go | 10 +- src/pkg/github/pr_request_watcher.go | 16 +- src/pkg/github/pr_request_watcher_test.go | 7 +- src/pkg/github/pr_self_authorization.go | 16 +- src/pkg/github/pr_self_authorization_test.go | 6 +- src/pkg/github/reporter_trust_test.go | 4 +- src/pkg/github/sha_hold_soft_test.go | 28 +- src/pkg/holdguard/holdguard.go | 20 +- .../policies/defaults/architect-holdgated.md | 6 +- .../defaults/ci-maintainer-holdgated.md | 6 +- src/pkg/policies/defaults/guide-holdgated.md | 6 +- src/pkg/policies/defaults/outreach-full.md | 2 +- .../policies/defaults/quality-holdgated.md | 6 +- .../policies/defaults/scanner-holdgated.md | 2 +- .../policies/defaults/sec-check-holdgated.md | 6 +- .../policies/defaults/strategist-holdgated.md | 6 +- src/pkg/policies/outreach_claims_test.go | 2 +- src/pkg/stagelabels/hold.go | 14 +- src/pkg/stagelabels/human.go | 8 +- src/policies/architect-holdgated.md | 6 +- src/policies/ci-maintainer-holdgated.md | 6 +- src/policies/guide-holdgated.md | 6 +- src/policies/outreach-full.md | 2 +- src/policies/quality-holdgated.md | 6 +- src/policies/scanner-holdgated.md | 2 +- src/policies/sec-check-holdgated.md | 6 +- src/policies/strategist-holdgated.md | 6 +- 66 files changed, 1141 insertions(+), 324 deletions(-) create mode 100644 changelog.d/changed-18468-hive-gate-labels.md create mode 100644 src/cmd/hive/hive_gate_labels_18468_test.go create mode 100644 src/pkg/config/hive_gate_labels_18468_test.go create mode 100644 src/pkg/delegatedecision/hold_label_18468_test.go create mode 100644 src/pkg/github/hive_gate_label_migration.go create mode 100644 src/pkg/github/hive_gate_labels.go create mode 100644 src/pkg/github/hive_gate_labels_test.go diff --git a/changelog.d/changed-18468-hive-gate-labels.md b/changelog.d/changed-18468-hive-gate-labels.md new file mode 100644 index 0000000000..cf13e8a696 --- /dev/null +++ b/changelog.d/changed-18468-hive-gate-labels.md @@ -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`. diff --git a/src/cmd/hive/github_client_config.go b/src/cmd/hive/github_client_config.go index b9908ca338..8ff3bad3e9 100644 --- a/src/cmd/hive/github_client_config.go +++ b/src/cmd/hive/github_client_config.go @@ -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()) diff --git a/src/cmd/hive/hive_gate_labels_18468_test.go b/src/cmd/hive/hive_gate_labels_18468_test.go new file mode 100644 index 0000000000..1d96f5bcb0 --- /dev/null +++ b/src/cmd/hive/hive_gate_labels_18468_test.go @@ -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) + } +} diff --git a/src/cmd/hive/main.go b/src/cmd/hive/main.go index af8950203b..cbf5f8dc20 100644 --- a/src/cmd/hive/main.go +++ b/src/cmd/hive/main.go @@ -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 @@ -6144,6 +6144,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 diff --git a/src/cmd/hive/main_helpers.go b/src/cmd/hive/main_helpers.go index 56cf0ff913..cb2f0ad606 100644 --- a/src/cmd/hive/main_helpers.go +++ b/src/cmd/hive/main_helpers.go @@ -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. diff --git a/src/cmd/hive/merge_eligibility.go b/src/cmd/hive/merge_eligibility.go index 0bb984043a..9917668631 100644 --- a/src/cmd/hive/merge_eligibility.go +++ b/src/cmd/hive/merge_eligibility.go @@ -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. @@ -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 @@ -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 "" diff --git a/src/docs/hive-open-pr.md b/src/docs/hive-open-pr.md index 06c77fe7be..55c685ad9b 100644 --- a/src/docs/hive-open-pr.md +++ b/src/docs/hive-open-pr.md @@ -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 diff --git a/src/docs/labels-and-control-signals/glossary-and-operations.md b/src/docs/labels-and-control-signals/glossary-and-operations.md index 64a5606d00..fefc5877bd 100644 --- a/src/docs/labels-and-control-signals/glossary-and-operations.md +++ b/src/docs/labels-and-control-signals/glossary-and-operations.md @@ -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. | @@ -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/`, any label containing `hold`, and exempt `do-not-merge`. That instruction is a prompt-level backstop; enumeration and sweep checks are the hard enforcement. @@ -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 @@ -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 @@ -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/` holds everywhere), SHA-hold lifts only its own `hold`, policy templates name the enforced hold set, and `agent/` 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`). diff --git a/src/docs/labels-and-control-signals/reference.md b/src/docs/labels-and-control-signals/reference.md index c602e1381c..ec4e2508e6 100644 --- a/src/docs/labels-and-control-signals/reference.md +++ b/src/docs/labels-and-control-signals/reference.md @@ -86,11 +86,11 @@ This reference replaces the former nine-column table with one headed entry per c Any label containing a configured hold substring is held; held issues/PRs leave agent kicks, PR merge lanes, and the task-list sweep. Held red PRs still route back to their owning agent for CI repair, with instructions not to remove the hold. -**Who applies it:** Human, Hive level gate, #5117 gate, holdguard, SHA-hold. +**Who applies it:** A person. The hive never applies `hold` itself ([#18468](https://github.com/hivecommons/hive/issues/18468)): a `hold` means "do not merge / do not act", and the hive never implements, decomposes, relays or merges a held item, and never removes the label. When one of the hive's own gates needs a person it applies [`ready-for-review` or `decision-needed`](#ready-for-review-decision-needed) instead. Builds before #18468 applied literal `hold` from the level gate, #5117, reporter trust, holdguard, owner-only delegated decisions and SHA-hold; the boot migration swaps those (see below). **Checked by:** GitHub enumeration, auto-merge sweeps, task-list sweep. **When:** Enumeration and sweeps. -**Release or override.** Remove the matching label; Hive releases only literal `hold` it applied itself (level gate, #5117, SHA-hold) +**Release or override.** A person removes the label. Hive does not remove a `hold`; the one exception is the SHA-hold sweep lifting a `hold` an older build of that sweep applied, once a SHA appears. **Configuration and implementation.** Built-in `HoldLabels`; dashboard exact hold via `Client.SetHoldLabels` (`src/pkg/github/client.go:1317`, `src/pkg/github/client.go:3314-3369`, `src/pkg/scheduler/policy_overlays.go:210-220`) @@ -108,39 +108,56 @@ Exact, hive-scoped dashboard hold. It is not provenance and intentionally avoids **Configuration and implementation.** Canonicalized from hive id (`src/pkg/github/client.go:3371-3380`, `src/pkg/github/client.go:3386-3392`, `src/docs/dashboard.md:80-96`) -#### `hold` from ACMM level gate +#### `ready-for-review`, `decision-needed` + +**Applies to:** Issues, PRs. **Kind:** Hard merge gate, applied by the hive. + +The labels the hive applies instead of `hold` ([#18468](https://github.com/hivecommons/hive/issues/18468)). Each blocks merges and agent work exactly like `hold` (exact-match members of the hold set: `github.IsHiveGateLabel`, read by `HasHoldLabelWith`, the merge-eligibility classifier and the stage engine), and each is created with a GitHub label description saying who acts next: + +| Label | Description | Applied by | +|---|---|---| +| `ready-for-review` | Hive's work is done; a maintainer reviews, then removes this label to let it merge. | The ACMM level gate (L3-L5, and cross-repo outreach at every level). | +| `decision-needed` | Hive is blocked on a human decision; a maintainer decides (see hive's comment). | The #5117 self-authorization gate, the #9665 reporter-trust gate (with `needs-human`), the holdguard re-hold, and an owner-only delegated decision (with `needs-owner`). | + +Every gate posts its existing notice comment saying why. Agents cannot add or remove either label through the relay. + +**Migration.** On boot, Hive creates both labels (with their descriptions) in each active repository and swaps a literal `hold` for the matching gate label only when the newest `hold` event is a `labeled` by the Hive App **and** an App-authored gate notice is on the thread (level-hold notice → `ready-for-review`; reporter-trust, #5117, holdguard or owner-only decision notice → `decision-needed`). It adds the gate label before removing `hold` and leaves one `` comment. A `hold` a person applied (or re-applied) is never touched. Bounded to 50 items per repository per boot (`src/pkg/github/hive_gate_label_migration.go`). + +**Configuration and implementation.** `governor.labels.ready_for_review` (default `ready-for-review`), `governor.labels.decision_needed` (default `decision-needed`); blank or `hold` keeps the default (`src/pkg/github/hive_gate_labels.go`). + +#### `ready-for-review` from ACMM level gate **Applies to:** PRs. **Kind:** Hard merge gate. -Agent PRs at L3-L5 get literal `hold`; `outreach` PRs whose target repo is not one the hive manages (cross-repo outreach) are held at every level, while same-repo outreach PRs follow the level. The watcher, not the policy prompt, applies it from the PR's target repo (`config.AgentOwnsRepo`). +Agent PRs at L3-L5 get `ready-for-review` (literal `hold` before #18468); `outreach` PRs whose target repo is not one the hive manages (cross-repo outreach) are held at every level, while same-repo outreach PRs follow the level. The watcher, not the policy prompt, applies it from the PR's target repo (`config.AgentOwnsRepo`). **Who applies it:** Hive App. **Checked by:** PR-request watcher, self-authored auto-merge release. **When:** PR creation, later self-authored auto-merge release. -**Release or override.** Auto-release only when current policy no longer requires the level hold, latest hold event was by the App, and the release path runs; otherwise a human removes it +**Release or override.** A maintainer reviews and removes `ready-for-review`; a deliberate one-off `release_level_holds` during an ACMM level change removes only `ready-for-review` labels whose latest event was by the App beside a level-hold notice **Configuration and implementation.** Hive-wide ACMM and agent (`src/pkg/github/pr_request_watcher.go:452-524`, `src/pkg/github/pr_level_hold.go:16-124`) -#### `hold` from #5117 self-authorization +#### `decision-needed` from #5117 self-authorization **Applies to:** PRs. **Kind:** Hard merge gate. -A PR whose only rationale is unacknowledged hive-filed issues gets literal `hold`. Acknowledging the issue later does not remove an existing PR hold by itself. At ACMM L6 (Autonomous), the unset default is off; lower levels default on. +A PR whose only rationale is unacknowledged hive-filed issues gets `decision-needed` (literal `hold` before #18468). Acknowledging the issue later does not remove an existing PR hold by itself. At ACMM L6 (Autonomous), the unset default is off; lower levels default on. **Who applies it:** Hive App. **Checked by:** PR-request watcher and self-authorization release. **When:** PR creation; evaluated only when no level hold applies. -**Release or override.** Acknowledge the issue and remove the PR `hold`; disabled policy release can remove Hive's own hold. At L6, that release path also clears existing Hive-applied #5117 holds when no explicit config keeps the policy on. +**Release or override.** Acknowledge the issue and remove the PR's `decision-needed`; disabled policy release can remove Hive's own `decision-needed` (never a `hold`). At L6, that release path also clears existing Hive-applied #5117 holds when no explicit config keeps the policy on. **Configuration and implementation.** `github.self_authorization_hold`, per-repo `project.repo_policies[].self_authorization_hold`, `HIVE_SELF_AUTHORIZATION_HOLD` (`src/pkg/github/pr_self_authorization.go:14-226`, `src/pkg/github/pr_request_watcher.go:452-524`) -#### `hold` from #9665 reporter trust +#### `decision-needed` from #9665 reporter trust **Applies to:** PRs **not authored by the hive**. **Kind:** Hard merge gate. -A PR whose rationale traces to an issue filed by an untrusted reporter gets literal `hold` at **every** ACMM level, including L6, plus `needs-human` (so it surfaces as waiting on a person, #10773) and a marked notice (`` + ``) naming the untrusted reporter and stating that the hold concerns the issue reporter, not the PR author. The rationale is **only the linked issues**: closing-keyword links (`Fixes`/`Closes`/`Resolves`) and the request's declared issues — bare `#N` mentions are not consulted, and a link that resolves to a pull request is skipped rather than judged (hivecommons/hive#15020: `Refs #15009 (closed by #15017)` made the gate judge sibling PR #15017 and attribute a `CONTRIBUTOR` who had merely commented). +A PR whose rationale traces to an issue filed by an untrusted reporter gets `decision-needed` (literal `hold` before #18468) at **every** ACMM level, including L6, plus `needs-human` (so it surfaces as waiting on a person, #10773) and a marked notice (`` + ``) naming the untrusted reporter and stating that the hold concerns the issue reporter, not the PR author. The rationale is **only the linked issues**: closing-keyword links (`Fixes`/`Closes`/`Resolves`) and the request's declared issues — bare `#N` mentions are not consulted, and a link that resolves to a pull request is skipped rather than judged (hivecommons/hive#15020: `Refs #15009 (closed by #15017)` made the gate judge sibling PR #15017 and attribute a `CONTRIBUTOR` who had merely commented). A hive-filed issue (`[selfreport]`, app or AI author) counts as trusted. The gate is **skipped entirely for hive-authored PRs** (App bot, `project.ai_author`, `author/hive`): the hive is the author, so the reporter's trust says nothing about whether its own fix may merge; it still applies to contributor PRs and to PRs opened under a shared PAT account. Any one untrusted citation holds. Evaluated even at hold-gated levels, because the notice is what stops promotion to L6 from releasing the label. @@ -148,17 +165,17 @@ A hive-filed issue (`[selfreport]`, app or AI author) counts as trusted. The gat **Checked by:** PR-request watcher, level-hold release. **When:** PR creation; re-checked by the level-hold release path. -**Release or override.** A human removes `hold` on a contributor PR; Hive never auto-releases it there. On a **hive-authored** PR still wearing a hive-set reporter-trust hold (newest `hold` event labeled by the App bot with the notice at or after it — a person's hold is left alone), the stage-label pass releases `hold` (and `needs-human` when the notice says the gate added it), posts one `` comment and logs `stage labels: releasing self-imposed reporter-trust hold`. +**Release or override.** A human removes `decision-needed` on a contributor PR; Hive never auto-releases it there. On a **hive-authored** PR still wearing a hive-set reporter-trust `decision-needed` (newest event for it labeled by the App bot with the notice at or after it — a person's `hold` is left alone), the stage-label pass releases `decision-needed` (and `needs-human` when the notice says the gate added it), posts one `` comment and logs `stage labels: releasing self-imposed reporter-trust hold`. The pass also records the hold's provenance (`by`, `source`, `reason`, `since`) on the stage store, so the tracker pill reads *Held by hive · reporter trust (issue #N by @X, contributor)* and the stage entry comment names who set the hold and why (a hold is a gate on the PR's real stage, not a stage of its own — [#17327](https://github.com/hivecommons/hive/issues/17327)). Holdguard re-holds on a new head SHA. **Configuration and implementation.** `github.reporter_trust_hold` (nil follows `reporter_trust.enabled`), per-repo `project.repo_policies[].reporter_trust_hold`, `HIVE_REPORTER_TRUST_HOLD` (`src/pkg/github/pr_reporter_trust.go`, `src/pkg/github/pr_level_hold.go`, `src/pkg/github/automerge/reporter_trust_release.go`) -#### `hold` from holdguard +#### `decision-needed` from holdguard **Applies to:** PRs. **Kind:** Hard merge gate. -If the head SHA changes while held, lifting the hold causes Hive to comment and re-apply literal `hold`; the next human removal is the fresh approval. Exception (#13603): when a human (not a Hive account, not a bot) removed the gate label after the current head arrived on the branch, they reviewed the current head, so the lift clears without a comment or re-hold. The head is accepted only on evidence a contributor cannot forge: the server-stamped `head_ref_force_pushed` timeline event that produced it (dated before the lift), or the hive itself having observed that exact head on the PR while the gate was still on (`observed_held_head_sha` in the holdguard ledger). +If the head SHA changes while held, lifting the hold causes Hive to comment and re-apply `decision-needed` (literal `hold` before #18468); the next human removal is the fresh approval. Exception (#13603): when a human (not a Hive account, not a bot) removed the gate label after the current head arrived on the branch, they reviewed the current head, so the lift clears without a comment or re-hold. The head is accepted only on evidence a contributor cannot forge: the server-stamped `head_ref_force_pushed` timeline event that produced it (dated before the lift), or the hive itself having observed that exact head on the PR while the gate was still on (`observed_held_head_sha` in the holdguard ledger). Commit committer dates and SHA-keyed `check_suite` / `status` times are never used; a push after the lift, or a head the hive never saw while held, still re-holds. @@ -166,15 +183,15 @@ Commit committer dates and SHA-keyed `check_suite` / `status` times are never us **Checked by:** Holdguard ledger. **When:** Governor holdguard pass. -**Release or override.** Human removes the re-applied hold +**Release or override.** Human removes the re-applied `decision-needed` **Configuration and implementation.** Built-in `holdguard.ReHoldLabel` (`src/pkg/holdguard/holdguard.go:1-43`) -#### `hold` from SHA-hold +#### `hold` from SHA-hold (before #18468) **Applies to:** Issues. **Kind:** Hard issue hold. -Human-filed primary-repo `kind/bug` without a 7-40 hex SHA gets `hold` and a notice carrying ``; once a SHA appears in body/comments, Hive removes `hold` only if the current hold is its own (newest `hold` event labeled by the App bot, paired with an App-authored notice at or after it). A human's hold, a re-hold, or another subsystem's hold stays. Reporters whose author association is trusted (`issue_filter.reporter_trust.trusted_associations`, default OWNER/MEMBER/COLLABORATOR) get the soft `needs-sha` row below instead, and a SHA-hold `hold` already on such an issue is swapped for it (#12002). +Since [#18468](https://github.com/hivecommons/hive/issues/18468) the sweep gives every reporter the `needs-sha` label below and never applies `hold`; an untrusted reporter's issue stays out of automatic work through the reporter-trust gate. Before that, human-filed primary-repo `kind/bug` without a 7-40 hex SHA got `hold` and a notice carrying ``; once a SHA appears in body/comments, Hive removes `hold` only if the current hold is its own (newest `hold` event labeled by the App bot, paired with an App-authored notice at or after it). A human's hold, a re-hold, or another subsystem's hold stays. Reporters whose author association is trusted (`issue_filter.reporter_trust.trusted_associations`, default OWNER/MEMBER/COLLABORATOR) get the soft `needs-sha` row below instead, and a SHA-hold `hold` already on such an issue is swapped for it (#12002). The hard-suppress reconcile also lifts this `hold` once a PR referencing the issue merges after it was applied. @@ -198,7 +215,7 @@ Trusted-reporter `kind/bug` without a SHA gets this soft label plus the same ``) is not // renameable. Author AuthorLabelsConfig `yaml:"author"` + // ReadyForReview is the gate label the hive applies when its work on a + // PR is done and a maintainer must review it (the ACMM level gate at + // L3-L5). Defaults to DefaultReadyForReviewLabel. The hive never + // applies `hold` itself (hivecommons/hive#18468): a person's `hold` + // means hands-off. Blank or `hold` keeps the default. + ReadyForReview string `yaml:"ready_for_review,omitempty"` + // DecisionNeeded is the gate label the hive applies when it is blocked + // on a human decision (reporter trust, self-authorization, the hold + // guard, an owner-only delegated decision). Defaults to + // DefaultDecisionNeededLabel. Blank or `hold` keeps the default. + DecisionNeeded string `yaml:"decision_needed,omitempty"` +} + +// Default hive gate label names (hivecommons/hive#18468); they match +// github.DefaultReadyForReviewLabel / github.DefaultDecisionNeededLabel. +const ( + DefaultReadyForReviewLabel = "ready-for-review" + DefaultDecisionNeededLabel = "decision-needed" +) + +// ReadyForReviewLabelOrDefault returns governor.labels.ready_for_review or +// its default. `hold` is never returned: the hive must not apply it. +func (c LabelsConfig) ReadyForReviewLabelOrDefault() string { + return gateLabelOrDefault(c.ReadyForReview, DefaultReadyForReviewLabel) +} + +// DecisionNeededLabelOrDefault returns governor.labels.decision_needed or +// its default. `hold` is never returned: the hive must not apply it. +func (c LabelsConfig) DecisionNeededLabelOrDefault() string { + return gateLabelOrDefault(c.DecisionNeeded, DefaultDecisionNeededLabel) +} + +func gateLabelOrDefault(v, def string) string { + v = strings.TrimSpace(v) + if v == "" || strings.EqualFold(v, "hold") { + return def + } + return v } // AuthorLabelsConfig is governor.labels.author: the label names for the diff --git a/src/pkg/config/hive_gate_labels_18468_test.go b/src/pkg/config/hive_gate_labels_18468_test.go new file mode 100644 index 0000000000..305755fee8 --- /dev/null +++ b/src/pkg/config/hive_gate_labels_18468_test.go @@ -0,0 +1,20 @@ +package config + +import "testing" + +// hivecommons/hive#18468: the gate label names are configurable, and no +// configuration can make the hive apply `hold` itself. +func TestHiveGateLabelConfigNeverResolvesToHold(t *testing.T) { + var l LabelsConfig + if l.ReadyForReviewLabelOrDefault() != DefaultReadyForReviewLabel || l.DecisionNeededLabelOrDefault() != DefaultDecisionNeededLabel { + t.Fatalf("defaults = %q/%q", l.ReadyForReviewLabelOrDefault(), l.DecisionNeededLabelOrDefault()) + } + l = LabelsConfig{ReadyForReview: " hold ", DecisionNeeded: "HOLD"} + if l.ReadyForReviewLabelOrDefault() != DefaultReadyForReviewLabel || l.DecisionNeededLabelOrDefault() != DefaultDecisionNeededLabel { + t.Fatalf("hold override resolved to %q/%q, want the defaults", l.ReadyForReviewLabelOrDefault(), l.DecisionNeededLabelOrDefault()) + } + l = LabelsConfig{ReadyForReview: "awaiting-review", DecisionNeeded: "awaiting-decision"} + if l.ReadyForReviewLabelOrDefault() != "awaiting-review" || l.DecisionNeededLabelOrDefault() != "awaiting-decision" { + t.Fatalf("overrides = %q/%q", l.ReadyForReviewLabelOrDefault(), l.DecisionNeededLabelOrDefault()) + } +} diff --git a/src/pkg/config/issues.go b/src/pkg/config/issues.go index 0db8f12d51..486301f7f3 100644 --- a/src/pkg/config/issues.go +++ b/src/pkg/config/issues.go @@ -47,8 +47,9 @@ type IssuesConfig struct { // SHAHoldTrustedLabel is the soft label the SHA-hold sweep applies to a // bug filed by a reporter in issue_filter.reporter_trust's trusted // associations (OWNER/MEMBER/COLLABORATOR by default) when no commit SHA - // is present. Unset uses DefaultSHAHoldTrustedLabel; "hold" restores the - // legacy hard hold for every reporter. + // is present. Unset uses DefaultSHAHoldTrustedLabel. Since + // hivecommons/hive#18468 the sweep applies this label to every reporter + // and never applies `hold`; "hold" is treated as unset. SHAHoldTrustedLabel *string `yaml:"sha_hold_trusted_label,omitempty" json:"sha_hold_trusted_label,omitempty"` // LiftHiveHardSuppress enables the reconcile that lifts a `hold`/`blocked` // label hive itself applied once a PR referencing the issue has merged diff --git a/src/pkg/dashboard/api_packs_acmm_hook_test.go b/src/pkg/dashboard/api_packs_acmm_hook_test.go index 1b19c8d3f4..0a8d99e39f 100644 --- a/src/pkg/dashboard/api_packs_acmm_hook_test.go +++ b/src/pkg/dashboard/api_packs_acmm_hook_test.go @@ -337,17 +337,17 @@ func newLevelHoldGuardDashboardServer(t *testing.T, withHold bool) (*Server, *le return } _, _ = w.Write([]byte(`[ - {"number":11,"title":"level hold","html_url":"https://github.com/testorg/testrepo/pull/11","labels":[{"name":"hold"}]}, + {"number":11,"title":"level hold","html_url":"https://github.com/testorg/testrepo/pull/11","labels":[{"name":"ready-for-review"}]}, {"number":12,"title":"plain human hold","html_url":"https://github.com/testorg/testrepo/pull/12","labels":[{"name":"hold"}]}, {"number":13,"title":"paused","html_url":"https://github.com/testorg/testrepo/pull/13","labels":[{"name":"hive-pause/test"}]} ]`)) case r.Method == http.MethodGet && r.URL.Path == "/repos/testorg/testrepo/issues/11/comments": _, _ = w.Write([]byte(`[{"id":101,"body":"\nheld","user":{"login":"hive[bot]"}}]`)) case r.Method == http.MethodGet && r.URL.Path == "/repos/testorg/testrepo/issues/11/events": - _, _ = w.Write([]byte(`[{"event":"labeled","created_at":"2026-10-01T14:00:00Z","actor":{"login":"hive[bot]"},"label":{"name":"hold"}}]`)) + _, _ = w.Write([]byte(`[{"event":"labeled","created_at":"2026-10-01T14:00:00Z","actor":{"login":"hive[bot]"},"label":{"name":"ready-for-review"}}]`)) case r.Method == http.MethodGet && r.URL.Path == "/repos/testorg/testrepo/issues/12/comments": _, _ = w.Write([]byte(`[{"id":102,"body":"human hold","user":{"login":"alice"}}]`)) - case r.Method == http.MethodDelete && r.URL.Path == "/repos/testorg/testrepo/issues/11/labels/hold": + case r.Method == http.MethodDelete && r.URL.Path == "/repos/testorg/testrepo/issues/11/labels/ready-for-review": calls.removes++ calls.removedNumber = 11 w.WriteHeader(http.StatusOK) diff --git a/src/pkg/dashboard/api_repo_item_decide_delegated.go b/src/pkg/dashboard/api_repo_item_decide_delegated.go index ea5500c9b4..e98c1d8c7e 100644 --- a/src/pkg/dashboard/api_repo_item_decide_delegated.go +++ b/src/pkg/dashboard/api_repo_item_decide_delegated.go @@ -517,7 +517,7 @@ func (s *Server) decideDelegatedOne(ctx context.Context, repoFull string, number // and write nothing (hivecommons/hive#15099). if in.Kind == delegatedecision.KindIssue { if b := s.delegatedBlocker(ctx, repoFull, number, s.delegatedCommentTexts(ctx, repoFull, number)); b != nil { - held := slices.Contains(in.Labels, delegatedecision.LabelHold) + held := delegatedecision.HeldByLabels(in.Labels) res := blockerNoEffectResult(rowActionTarget(repoFull, rowActionTargetIssue, number), *b, held, s.blockerOptionsContext()) d := delegatedecision.Decision{Verdict: delegatedecision.VerdictRefused, Rule: "blocker:" + b.Kind, Text: res.Outcome, Rationale: res.Outcome, KeepsPark: true} notes := []string{"blocked: " + b.Short + "; nothing written"} diff --git a/src/pkg/dashboard/api_repo_item_decide_delegated_test.go b/src/pkg/dashboard/api_repo_item_decide_delegated_test.go index 2d8ab6358d..fbd1d94675 100644 --- a/src/pkg/dashboard/api_repo_item_decide_delegated_test.go +++ b/src/pkg/dashboard/api_repo_item_decide_delegated_test.go @@ -132,7 +132,7 @@ func TestDelegatedDecisionOwnerOnlyLabelsAndKeepsPark(t *testing.T) { t.Fatalf("code=%d job=%+v", w.Code, job) } joined := strings.Join(mock.added, ",") - if !strings.Contains(joined, delegatedecision.LabelNeedsOwner) || !strings.Contains(joined, delegatedecision.LabelHold) || strings.Contains(joined, github.HumanAckLabel) { + if !strings.Contains(joined, delegatedecision.LabelNeedsOwner) || !strings.Contains(joined, delegatedecision.LabelDecisionNeeded) || strings.Contains(joined, delegatedecision.LabelHold) || strings.Contains(joined, github.HumanAckLabel) { t.Fatalf("added = %v", mock.added) } if len(mock.comments) != 1 || strings.Contains(mock.comments[0], "/hive decision") || !strings.Contains(mock.comments[0], "owner action required") || !strings.Contains(mock.comments[0], "stays") { diff --git a/src/pkg/dashboard/bands.go b/src/pkg/dashboard/bands.go index 0539c4315f..0649ef0f11 100644 --- a/src/pkg/dashboard/bands.go +++ b/src/pkg/dashboard/bands.go @@ -564,7 +564,7 @@ func holdLabels(labels []string, hiveID string) []string { out := make([]string, 0) for _, label := range labels { lower := strings.ToLower(label) - if lower == canonical || lower == "do-not-merge" || strings.HasPrefix(lower, "do-not-merge/") || containsAnyHoldLabel(lower, holdLabelSpellings) { + if lower == canonical || lower == "do-not-merge" || strings.HasPrefix(lower, "do-not-merge/") || containsAnyHoldLabel(lower, holdLabelSpellings) || github.IsHiveGateLabel(label) { out = append(out, label) } } diff --git a/src/pkg/dashboard/settings_parity_allowlist.txt b/src/pkg/dashboard/settings_parity_allowlist.txt index 13584038be..aa4b3f446d 100644 --- a/src/pkg/dashboard/settings_parity_allowlist.txt +++ b/src/pkg/dashboard/settings_parity_allowlist.txt @@ -287,7 +287,9 @@ governor.health.healthcheck_interval # TODO #11854 governor.labels.author.clanker # label-name override; yaml-only (#12581) governor.labels.author.hive # label-name override; yaml-only (#12581) governor.labels.author.human # label-name override; yaml-only (#12581) +governor.labels.decision_needed # label-name override; yaml-only (#18468) governor.labels.exempt[] # TODO #11854 +governor.labels.ready_for_review # label-name override; yaml-only (#18468) governor.labels.stage.dco.required. # TODO #12542 governor.litellm.api_key_env # TODO #11854 governor.litellm.api_key_file # TODO #11854 diff --git a/src/pkg/delegatedecision/hold_label_18468_test.go b/src/pkg/delegatedecision/hold_label_18468_test.go new file mode 100644 index 0000000000..20b7b2b068 --- /dev/null +++ b/src/pkg/delegatedecision/hold_label_18468_test.go @@ -0,0 +1,58 @@ +package delegatedecision + +import "testing" + +// hivecommons/hive#18468: the delegate never applies `hold`; an owner-only +// item gets decision-needed, which the hold rail reads like `hold`. +func TestOwnerOnlyAppliesDecisionNeededNotHold(t *testing.T) { + d := Run(Input{Kind: KindIssue, Number: 11, Title: "Workflow fails: GITHUB_TOKEN lacks packages:write"}) + if d.Verdict != VerdictOwnerOnly { + t.Fatalf("verdict = %s, want owner-only", d.Verdict) + } + var added []string + for _, a := range d.Actions { + if a.Kind == ActionLabelsAdd { + added = append(added, a.Labels...) + } + } + if hasLabel(added, LabelHold) || !hasLabel(added, LabelDecisionNeeded) || !hasLabel(added, LabelNeedsOwner) { + t.Fatalf("labels added = %v, want needs-owner + decision-needed and never hold", added) + } +} + +func TestHoldRailReadsHoldAndDecisionNeeded(t *testing.T) { + for _, labels := range [][]string{{LabelHold}, {LabelDecisionNeeded}, {"Decision-Needed"}} { + if !HeldByLabels(labels) { + t.Errorf("HeldByLabels(%v) = false, want held", labels) + } + d := Run(Input{Kind: KindIssue, Number: 11, Title: "Workflow fails: GITHUB_TOKEN lacks packages:write", Labels: labels}) + for _, a := range d.Actions { + if a.Kind == ActionLabelsAdd || a.Kind == ActionLabelsRemove { + t.Errorf("held by %v: delegate wrote labels %+v", labels, a) + } + } + } + if HeldByLabels([]string{"needs-owner"}) { + t.Error("needs-owner alone is not a hold") + } +} + +func TestDelegateNeverLiftsGateOrHold(t *testing.T) { + for _, label := range []string{LabelHold, LabelDecisionNeeded} { + d := ApplyRails(Decision{Verdict: VerdictDirection, Actions: []Action{{Kind: ActionLabelsRemove, Labels: []string{label}}}}, Rails{}) + for _, a := range d.Actions { + if a.Kind == ActionLabelsRemove { + t.Errorf("removing %q survived the rails: %+v", label, d.Actions) + } + } + } +} + +func TestLLMMayNotAddHold(t *testing.T) { + if hasLabel(LLMLabels, LabelHold) { + t.Fatalf("LLMLabels = %v; the model must never add hold", LLMLabels) + } + if hasLabel(LLMRemovableLabels, LabelDecisionNeeded) { + t.Fatalf("LLMRemovableLabels = %v; the model must never lift decision-needed", LLMRemovableLabels) + } +} diff --git a/src/pkg/delegatedecision/llm.go b/src/pkg/delegatedecision/llm.go index c7d6315694..653fc38a79 100644 --- a/src/pkg/delegatedecision/llm.go +++ b/src/pkg/delegatedecision/llm.go @@ -54,7 +54,9 @@ var LLMVerdicts = []Verdict{ } // LLMLabels is the label set the model may add. -var LLMLabels = []string{LabelNeedsOwner, LabelHold, LabelTriageAccepted, LabelFlakyTest, LabelNeedsDecision} +// It never includes `hold`: a hold is a person's to set (hivecommons/hive#18468); +// the model asks for a human with decision-needed instead. +var LLMLabels = []string{LabelNeedsOwner, LabelDecisionNeeded, LabelTriageAccepted, LabelFlakyTest, LabelNeedsDecision} // LLMRemovableLabels is the label set the model may remove (a hold it asks // to remove is still refused by ApplyRails). The park label is not in it: @@ -413,7 +415,7 @@ const ( // goes through ApplyRails. A runner or validation error falls back to the // rules' reversible default and is returned for the caller to note. func RunWithLLM(ctx context.Context, in Input, c LLMContext, runner TurnRunner) (Decision, LLMOutcome, error) { - rails := Rails{Held: hasLabel(in.Labels, LabelHold), PersonAuthored: in.PersonAuthored()} + rails := Rails{Held: HeldByLabels(in.Labels), PersonAuthored: in.PersonAuthored()} rules := Decide(in) if runner == nil || rails.Held || !IsReversibleDefault(rules) { return ApplyRails(rules, rails), LLMNotConsulted, nil diff --git a/src/pkg/delegatedecision/policy.go b/src/pkg/delegatedecision/policy.go index 7cb2913fec..0fee26304c 100644 --- a/src/pkg/delegatedecision/policy.go +++ b/src/pkg/delegatedecision/policy.go @@ -47,7 +47,7 @@ const PolicyText = `Owner-delegate policy (how the owner decides; the hive appli - Be decisive; except for the safety rails below, never ask the owner a question back. Pick the option that keeps work moving and is reversible. - PRs: prefer an adequate human/contributor PR over a hive duplicate — if both exist and the contributor's is mergeable and current, recommend a human comparison of issue coverage, checks and review approval; keep the hive PR open and parked until adequacy is confirmed, and never close it solely on an issue reference. Otherwise supersede the contributor's with the hive's and close theirs with credit. Approve small, necessary, low-risk changes (CI pins, RBAC read-only adds, warning text, workflow hygiene) once the sentinel finding is checked and explained as intended. Sensitive-path sentinel alerts on trusted-author PRs: approve with a one-line "reviewed, intended" rationale. Clear reporter-trust holds when the fixing PR is sound. - Contributors offline: adopt now in supersede mode — do not wait for a deadline (hivecommons/hive#13975). -- Issues: dedupe aggressively (close the newer duplicate with "Duplicate of #N", cross-link overlaps); secrets / PAT / org-permission items are owner-only → label needs-owner + hold with one comment stating the exact owner action, and stop opening more failure issues for that root cause; flaky tests → quarantine with retry + a deflake task rather than block; CI hygiene gate proposals (actionlint, duplication ratchets, link-checker allowlists) → approve as ratchets (baseline, fail only on increases; warning-only briefly, then enforce); design proposals with concrete acceptance criteria → accept as proposed with explicit defaults; "review backlog items blocked on their PR" → never auto-close when the PR closes unmerged (drop the relation, comment, re-triage); a fleet self-report whose remedy is the operator's (an expired provider login, credentials, disk, network, App setup on the reporting spoke) is not code work → tell that spoke's owner(s) exactly what to do, no approved-direction, no implementer, keep it out of the actionable set, and never post the same direction twice; a hive-filed proposal is paid for by evidence → approve it when it cites an incident it would have prevented or prior instances of the same class fixed one at a time, otherwise decline it for now (comment the reason, close as not planned; re-propose with evidence) — a person's proposal is never declined this way; a hive advisory (a dedupe checklist, a triage note) is never work for a person → the hive ticks its items as they close and closes it as completed when all are resolved; while items remain open nothing is written. +- Issues: dedupe aggressively (close the newer duplicate with "Duplicate of #N", cross-link overlaps); secrets / PAT / org-permission items are owner-only → label needs-owner + decision-needed with one comment stating the exact owner action, and stop opening more failure issues for that root cause; flaky tests → quarantine with retry + a deflake task rather than block; CI hygiene gate proposals (actionlint, duplication ratchets, link-checker allowlists) → approve as ratchets (baseline, fail only on increases; warning-only briefly, then enforce); design proposals with concrete acceptance criteria → accept as proposed with explicit defaults; "review backlog items blocked on their PR" → never auto-close when the PR closes unmerged (drop the relation, comment, re-triage); a fleet self-report whose remedy is the operator's (an expired provider login, credentials, disk, network, App setup on the reporting spoke) is not code work → tell that spoke's owner(s) exactly what to do, no approved-direction, no implementer, keep it out of the actionable set, and never post the same direction twice; a hive-filed proposal is paid for by evidence → approve it when it cites an incident it would have prevented or prior instances of the same class fixed one at a time, otherwise decline it for now (comment the reason, close as not planned; re-propose with evidence) — a person's proposal is never declined this way; a hive advisory (a dedupe checklist, a triage note) is never work for a person → the hive ticks its items as they close and closes it as completed when all are resolved; while items remain open nothing is written. - Record the decision as a "/hive decision " comment on the item (and the auto-merge queue approval on the PR head when the decision is to release a PR), remove stage/085-needs-decision, add triage/accepted where applicable, and stamp the delegated-decision marker so it is auditable. - Safety rails: never merge a PR (the auto-merge engine does that per repo settings); never act on an item carrying hold; never grant org membership, secrets or permissions (always the owner); leave an item untouched when the question is a policy or scope change to the hive itself (settings, governance docs, security posture) — post "hive recommends: …; owner to confirm" instead and keep 085.` @@ -165,9 +165,17 @@ const ( LabelAdoptSupersede = "adoption/supersede" // RuleCapabilityGap is the recommend-only rule for a blocker no decision // can clear: the GitHub App lacks a permission (hivecommons/hive#15099). - RuleCapabilityGap = "capability-gap" - LabelNeedsOwner = "needs-owner" - LabelHold = "hold" + RuleCapabilityGap = "capability-gap" + LabelNeedsOwner = "needs-owner" + // LabelHold is a person's "do not merge / do not act" label. The + // delegate reads it (the hold rail) but never adds or lifts it + // (hivecommons/hive#18468). + LabelHold = "hold" + // LabelDecisionNeeded is the hive's own gate label for an item blocked + // on a human decision (github.DefaultDecisionNeededLabel). The delegate + // applies it instead of `hold`; it blocks merges like `hold` and the + // delegate never lifts it either. + LabelDecisionNeeded = "decision-needed" LabelTriageAccepted = "triage/accepted" LabelFlakyTest = "flaky-test" LabelNeedsDecision = "stage/085-needs-decision" @@ -482,7 +490,7 @@ func ownerOnlyDecision(in Input, rationale string) Decision { return Decision{ Verdict: VerdictOwnerOnly, Rule: "owner-only", Text: text, Rationale: rationale, KeepsPark: true, Actions: []Action{ - {Kind: ActionLabelsAdd, Labels: []string{LabelNeedsOwner, LabelHold}}, + {Kind: ActionLabelsAdd, Labels: []string{LabelNeedsOwner, LabelDecisionNeeded}}, {Kind: ActionRecommendOnly, Text: text}, }, } @@ -649,11 +657,11 @@ func ownerAction(in Input) string { t := strings.ToLower(in.Title + " " + in.Question) switch { case strings.Contains(t, "org") && (strings.Contains(t, "member") || strings.Contains(t, "permission")): - return "grant or adjust the organization membership/permission named in the title, then remove `hold` and `needs-owner`" + return "grant or adjust the organization membership/permission named in the title, then remove `decision-needed` and `needs-owner`" case strings.Contains(t, "scope") || strings.Contains(t, "pat") || strings.Contains(t, "token"): - return "rotate or re-scope the token named in the title in the hive's secret store, then remove `hold` and `needs-owner`" + return "rotate or re-scope the token named in the title in the hive's secret store, then remove `decision-needed` and `needs-owner`" default: - return "set or rotate the secret named in the title, then remove `hold` and `needs-owner`" + return "set or rotate the secret named in the title, then remove `decision-needed` and `needs-owner`" } } @@ -1031,7 +1039,7 @@ func ApplyRails(d Decision, r Rails) Decision { out.Refusals = append(out.Refusals, fmt.Sprintf("%s: not in the allowed action set", a.Kind)) continue } - if a.Kind == ActionLabelsRemove && hasLabel(a.Labels, LabelHold) { + if a.Kind == ActionLabelsRemove && (hasLabel(a.Labels, LabelHold) || hasLabel(a.Labels, LabelDecisionNeeded)) { out.Refusals = append(out.Refusals, "labels-remove hold: the delegate never lifts a hold") continue } @@ -1054,7 +1062,13 @@ func ApplyRails(d Decision, r Rails) Decision { // Run is Decide followed by ApplyRails with the hold rail read from the labels. func Run(in Input) Decision { - return ApplyRails(Decide(in), Rails{Held: hasLabel(in.Labels, LabelHold), PersonAuthored: in.PersonAuthored()}) + return ApplyRails(Decide(in), Rails{Held: HeldByLabels(in.Labels), PersonAuthored: in.PersonAuthored()}) +} + +// HeldByLabels is the hold rail: a person's `hold`, or the decision-needed +// gate label the hive applied when it handed the item to a person. +func HeldByLabels(labels []string) bool { + return hasLabel(labels, LabelHold) || hasLabel(labels, LabelDecisionNeeded) } // CommentBody renders the comment the delegate posts for a decision: the diff --git a/src/pkg/github/automerge/automerge_stage_human.go b/src/pkg/github/automerge/automerge_stage_human.go index b35c48774e..1c378be3e1 100644 --- a/src/pkg/github/automerge/automerge_stage_human.go +++ b/src/pkg/github/automerge/automerge_stage_human.go @@ -517,14 +517,14 @@ func decisionActions(obs stageObservation, e stagelabels.Evidence) ([]string, bo actions = append(actions, "Resolve the sentinel alert and have a maintainer clear its label.") } for _, label := range e.Holds { - if label == "hold" && e.Hold.SelfImposed() { + if (label == hgithub.LegacyHiveHoldLabel || hgithub.IsHiveGateLabel(label)) && e.Hold.SelfImposed() { // The hive's own hold: name the gate and the two choices, so // the operator is not left reading "hold +1" (hivecommons/hive#15020). reason := strings.TrimSpace(e.Hold.Reason) if reason == "" { reason = "its own gate" } - actions = append(actions, "The hive set `hold` itself for "+reason+". **Release** it (dashboard row menu → Release hold, or remove the `hold` label) and the lane merges on its next pass once the other gates are clear, or **keep** it until a maintainer has reviewed the issue's reporter; `/hive approve` does not remove it.") + actions = append(actions, "The hive set `"+label+"` itself for "+reason+". **Release** it (dashboard row menu → Release hold, or remove the `"+label+"` label) and the lane merges on its next pass once the other gates are clear, or **keep** it until a maintainer has reviewed the issue's reporter; `/hive approve` does not remove it.") continue } actions = append(actions, "Resolve the reason for `"+label+"`, then have a maintainer remove that label; `/hive approve` does not remove it.") diff --git a/src/pkg/github/automerge/automerge_stage_labels.go b/src/pkg/github/automerge/automerge_stage_labels.go index 64458bb614..628f909a75 100644 --- a/src/pkg/github/automerge/automerge_stage_labels.go +++ b/src/pkg/github/automerge/automerge_stage_labels.go @@ -960,16 +960,19 @@ func (c *Engine) ApplyStageLabels(ctx context.Context) (StageLabelResult, error) verdict = replacement obs.Reason = replacement.Reason } - if hasLabelFold(obs.Labels, "hold") && !verdict.Terminal { + if holdLabel := wornHoldLabel(obs.Labels); holdLabel != "" && !verdict.Terminal { // Who held it and why rides the row (hivecommons/hive#15020); // a reporter-trust hold the hive put on its own PR is lifted // here — the hive is the author, the reporter's trust is moot. - prov, notice, err := c.holdProvenance(ctx, obs.Owner, obs.Repo, obs.Number) + // Only the gate's own decision-needed label is ever lifted: a + // `hold` is a person's (or awaits the #18468 migration) and is + // never removed by the hive. + prov, notice, err := c.holdProvenance(ctx, obs.Owner, obs.Repo, obs.Number, holdLabel) if err != nil { c.debug("stage labels: hold provenance unreadable", "repo", obs.Display, "pr", obs.Number, "error", err) } hiveAuthored := pass.AuthorIsApp || obs.AuthorKind == authorkind.Hive - if hiveAuthored && prov.SelfImposed() && prov.ReporterTrust() { + if hiveAuthored && prov.SelfImposed() && prov.ReporterTrust() && strings.EqualFold(holdLabel, hgithub.DecisionNeededLabelName()) { released, err := c.releaseSelfImposedReporterTrustHold(ctx, obs, prov, notice) if err != nil { c.warn("stage labels: could not release self-imposed reporter-trust hold", "repo", obs.Display, "pr", obs.Number, "error", err) diff --git a/src/pkg/github/automerge/automerge_sweep_test.go b/src/pkg/github/automerge/automerge_sweep_test.go index eebfeeebbd..00b3f40f63 100644 --- a/src/pkg/github/automerge/automerge_sweep_test.go +++ b/src/pkg/github/automerge/automerge_sweep_test.go @@ -2627,7 +2627,7 @@ func TestSweepSelfAuthoredAutoMergesReleasesSelfAuthorizationHoldWhenDisabled(t var removed []int var comments []string api := newSelfAuthoredAutoMergeAPI(t, []selfAuthoredPR{{ - number: 11, author: testHiveAppBotLogin, extraLabels: []string{"hold"}, + number: 11, author: testHiveAppBotLogin, extraLabels: []string{hgithub.DefaultDecisionNeededLabel}, mergeableState: "clean", statusState: "success", checkStatus: "completed", checkConclusion: "success", }}, &merged) defer api.Close() @@ -2643,11 +2643,11 @@ func TestSweepSelfAuthoredAutoMergesReleasesSelfAuthorizationHoldWhenDisabled(t case r.Method == http.MethodGet && r.URL.Path == "/repos/acme/widget/issues/11/events": json.NewEncoder(w).Encode([]map[string]any{{ "event": "labeled", - "label": map[string]string{"name": "hold"}, + "label": map[string]string{"name": hgithub.DefaultDecisionNeededLabel}, "actor": map[string]string{"login": testHiveAppBotLogin}, "created_at": "2026-09-11T11:59:59Z", }}) - case r.Method == http.MethodDelete && r.URL.Path == "/repos/acme/widget/issues/11/labels/hold": + case r.Method == http.MethodDelete && r.URL.Path == "/repos/acme/widget/issues/11/labels/"+hgithub.DefaultDecisionNeededLabel: removed = append(removed, 11) w.WriteHeader(http.StatusOK) json.NewEncoder(w).Encode([]map[string]any{}) diff --git a/src/pkg/github/automerge/reporter_trust_release.go b/src/pkg/github/automerge/reporter_trust_release.go index a06d6302fd..d227f6e36b 100644 --- a/src/pkg/github/automerge/reporter_trust_release.go +++ b/src/pkg/github/automerge/reporter_trust_release.go @@ -18,13 +18,22 @@ import ( // (hivecommons/hive#15020). const reporterTrustReleaseMarker = "" -// holdProvenance reads who set the `hold` label a PR wears and why: the -// newest `hold` label event names the actor and the time; a hive-set hold +// holdProvenance reads who set the hold-class label a PR wears (holdLabel: +// the decision-needed gate label or a literal `hold`) and why: the newest +// event for that label names the actor and the time; a hive-set hold // is attributed to the reporter-trust gate when the gate's notice comment // (hivecommons/hive#9665) is on the thread and no later unlabel event has // cleared it. The second result is the gate's notice when one was read. // nil, nil when nothing about the hold could be read. -func (c *Engine) holdProvenance(ctx context.Context, owner, repo string, number int) (*stagelabels.HoldProvenance, *hgithub.ReporterTrustHoldNotice, error) { +func (c *Engine) holdProvenance(ctx context.Context, owner, repo string, number int, holdLabel string) (*stagelabels.HoldProvenance, *hgithub.ReporterTrustHoldNotice, error) { + prov, notice, err := c.readHoldProvenance(ctx, owner, repo, number, holdLabel) + if prov != nil && !strings.EqualFold(holdLabel, hgithub.LegacyHiveHoldLabel) { + prov.Label = holdLabel + } + return prov, notice, err +} + +func (c *Engine) readHoldProvenance(ctx context.Context, owner, repo string, number int, holdLabel string) (*stagelabels.HoldProvenance, *hgithub.ReporterTrustHoldNotice, error) { if c == nil || c.gh == nil || c.transport == nil { return nil, nil, nil } @@ -37,7 +46,7 @@ func (c *Engine) holdProvenance(ctx context.Context, owner, repo string, number if n, ok := hgithub.ReporterTrustNoticeFromComments(comments, appBot); ok { notice = &n } - latest, err := c.latestHoldLabelEvent(ctx, owner, repo, number) + latest, err := c.latestLabelEvent(ctx, owner, repo, number, holdLabel) if err != nil { return nil, notice, err } @@ -60,7 +69,7 @@ func (c *Engine) holdProvenance(ctx context.Context, owner, repo string, number } // The hive set it. The reporter-trust notice explains it when it is the // hive's reason on record (posted around the label, never before an - // intervening unlabel — latestHoldLabelEvent already ruled that out). + // intervening unlabel — latestLabelEvent already ruled that out). if notice != nil && !notice.PostedAt.Before(since.Add(-reporterTrustNoticeSlack)) { return notice.Finding.HoldProvenance(since), notice, nil } @@ -90,10 +99,17 @@ func (c *Engine) listAllIssueComments(ctx context.Context, owner, repo string, n return all, nil } -// latestHoldLabelEvent returns the newest labeled / unlabeled event for the -// literal `hold` label, nil when there is none. -func (c *Engine) latestHoldLabelEvent(ctx context.Context, owner, repo string, number int) (*gh.IssueEvent, error) { - return c.latestLabelEvent(ctx, owner, repo, number, "hold") +// wornHoldLabel names the hold-class label whose provenance the stage pass +// reads: the decision-needed gate label the reporter-trust gate applies +// (hivecommons/hive#18468), else a literal `hold`, else "". +func wornHoldLabel(labels []string) string { + if gate := hgithub.DecisionNeededLabelName(); hasLabelFold(labels, gate) { + return gate + } + if hasLabelFold(labels, hgithub.LegacyHiveHoldLabel) { + return hgithub.LegacyHiveHoldLabel + } + return "" } // latestLabelEvent returns the newest labeled / unlabeled event for the @@ -129,7 +145,8 @@ func (c *Engine) latestLabelEvent(ctx context.Context, owner, repo string, numbe // put on a PR it authored itself (hivecommons/hive#15020): the hive is the // author, so the issue reporter's trust is not what decides whether its own // fix merges. prov must be a hive-set reporter-trust hold (the caller checked -// SelfImposed && ReporterTrust) and the PR hive-authored. Removes `hold`, and +// SelfImposed && ReporterTrust) and the PR hive-authored. Removes the +// decision-needed gate label (never a literal `hold`), and // `needs-human` when the gate's notice says it added it, and leaves a short // comment. Holds a person set are never touched: the caller only reaches // this with prov.By == "hive". @@ -137,7 +154,7 @@ func (c *Engine) releaseSelfImposedReporterTrustHold(ctx context.Context, obs st if c == nil || c.gh == nil || prov == nil || !prov.SelfImposed() || !prov.ReporterTrust() { return false, nil } - remove := []string{"hold"} + remove := []string{hgithub.DecisionNeededLabelName()} if notice != nil && notice.Finding.OwnsNeedsHuman && hasLabelFold(obs.Labels, "needs-human") { remove = append(remove, "needs-human") } diff --git a/src/pkg/github/automerge/reporter_trust_release_test.go b/src/pkg/github/automerge/reporter_trust_release_test.go index ac740ffcc6..c09a80b518 100644 --- a/src/pkg/github/automerge/reporter_trust_release_test.go +++ b/src/pkg/github/automerge/reporter_trust_release_test.go @@ -32,9 +32,19 @@ func reporterTrustNoticeComment(at string) map[string]any { } func holdEvent(event, actor, at string) map[string]any { + return labelEventFor("hold", event, actor, at) +} + +// gateEvent is a label event for the decision-needed gate label the +// reporter-trust gate applies since hivecommons/hive#18468. +func gateEvent(event, actor, at string) map[string]any { + return labelEventFor(hgithub.DefaultDecisionNeededLabel, event, actor, at) +} + +func labelEventFor(label, event, actor, at string) map[string]any { return map[string]any{ "event": event, - "label": map[string]string{"name": "hold"}, + "label": map[string]string{"name": label}, "actor": map[string]string{"login": actor}, "created_at": at, } @@ -106,7 +116,7 @@ func TestHoldProvenance(t *testing.T) { http.NotFound(w, r) } }) - got, notice, err := c.holdProvenance(context.Background(), "acme", "widget", 15020) + got, notice, err := c.holdProvenance(context.Background(), "acme", "widget", 15020, "hold") if err != nil { t.Fatal(err) } @@ -122,11 +132,11 @@ func TestHoldProvenance(t *testing.T) { func TestHoldProvenanceErrors(t *testing.T) { var nilEngine *Engine - if prov, notice, err := nilEngine.holdProvenance(context.Background(), "acme", "widget", 1); prov != nil || notice != nil || err != nil { + if prov, notice, err := nilEngine.holdProvenance(context.Background(), "acme", "widget", 1, "hold"); prov != nil || notice != nil || err != nil { t.Fatalf("nil engine = (%v, %v, %v), want no-op", prov, notice, err) } c, _ := releaseEngine(t, func(w http.ResponseWriter, r *http.Request) { http.Error(w, "boom", http.StatusInternalServerError) }) - if _, _, err := c.holdProvenance(context.Background(), "acme", "widget", 1); err == nil || !strings.Contains(err.Error(), "listing comments") { + if _, _, err := c.holdProvenance(context.Background(), "acme", "widget", 1, "hold"); err == nil || !strings.Contains(err.Error(), "listing comments") { t.Fatalf("err = %v, want listing-comments failure", err) } c, _ = releaseEngine(t, func(w http.ResponseWriter, r *http.Request) { @@ -136,13 +146,13 @@ func TestHoldProvenanceErrors(t *testing.T) { } http.Error(w, "boom", http.StatusInternalServerError) }) - if _, notice, err := c.holdProvenance(context.Background(), "acme", "widget", 1); err == nil || !strings.Contains(err.Error(), "listing issue events") || notice == nil { + if _, notice, err := c.holdProvenance(context.Background(), "acme", "widget", 1, "hold"); err == nil || !strings.Contains(err.Error(), "listing issue events") || notice == nil { t.Fatalf("(%v, %v), want listing-issue-events failure with the notice still returned", notice, err) } } func TestReleaseSelfImposedReporterTrustHoldGuards(t *testing.T) { - obs := stageObservation{Owner: "acme", Repo: "widget", Number: 15020, Labels: []string{"hold", "needs-human"}} + obs := stageObservation{Owner: "acme", Repo: "widget", Number: 15020, Labels: []string{hgithub.DefaultDecisionNeededLabel, "needs-human"}} c, _ := releaseEngine(t, func(w http.ResponseWriter, r *http.Request) { t.Errorf("unexpected %s %s", r.Method, r.URL.Path) }) for name, prov := range map[string]*stagelabels.HoldProvenance{ "nil": nil, @@ -158,11 +168,11 @@ func TestReleaseSelfImposedReporterTrustHoldGuards(t *testing.T) { } func TestReleaseSelfImposedReporterTrustHoldErrors(t *testing.T) { - obs := stageObservation{Owner: "acme", Repo: "widget", Number: 15020, Labels: []string{"hold", "needs-human"}} + obs := stageObservation{Owner: "acme", Repo: "widget", Number: 15020, Labels: []string{hgithub.DefaultDecisionNeededLabel, "needs-human"}} prov := &stagelabels.HoldProvenance{By: "hive", Source: "reporter-trust", Reason: "reporter trust (issue #15017 by @Karibhou, contributor)"} c, _ := releaseEngine(t, func(w http.ResponseWriter, r *http.Request) { http.Error(w, "boom", http.StatusInternalServerError) }) - if released, err := c.releaseSelfImposedReporterTrustHold(context.Background(), obs, prov, nil); released || err == nil || !strings.Contains(err.Error(), "removing hold label") { - t.Fatalf("(%v, %v), want removing-hold-label failure", released, err) + if released, err := c.releaseSelfImposedReporterTrustHold(context.Background(), obs, prov, nil); released || err == nil || !strings.Contains(err.Error(), "removing decision-needed label") { + t.Fatalf("(%v, %v), want removing-decision-needed-label failure", released, err) } c, _ = releaseEngine(t, func(w http.ResponseWriter, r *http.Request) { if r.Method == http.MethodDelete { @@ -187,14 +197,14 @@ func TestApplyStageLabels_ReleasesSelfImposedReporterTrustHold(t *testing.T) { api.labels[d.Name] = d.Color } api.issueComments = map[int][]map[string]any{15020: {reporterTrustNoticeComment("2026-10-20T17:14:18Z")}} - api.issueEvents = map[int][]map[string]any{15020: {holdEvent("labeled", testHiveAppBotLogin, "2026-10-20T17:14:14Z")}} + api.issueEvents = map[int][]map[string]any{15020: {gateEvent("labeled", testHiveAppBotLogin, "2026-10-20T17:14:14Z")}} srv := newStageAPI(t, api) defer srv.Close() clock := &contributorLaneClock{at: time.Date(2026, 10, 20, 17, 40, 0, 0, time.UTC)} e, _, store := newStageEngine(t, srv.URL, clock) ctx := context.Background() - pr := stagePR(15020, "hold", "needs-human", "author/hive", "role/trusted", "stage/085-needs-decision") + pr := stagePR(15020, hgithub.DefaultDecisionNeededLabel, "needs-human", "author/hive", "role/trusted", "stage/085-needs-decision") pr.User = &gh.User{Login: gh.Ptr(testHiveAppBotLogin), Type: gh.Ptr("Bot")} e.recordStage(stageLaneSelf, "acme/widget", "acme", "widget", pr, "label:hold", false, nil) res, err := e.ApplyStageLabels(ctx) @@ -204,7 +214,7 @@ func TestApplyStageLabels_ReleasesSelfImposedReporterTrustHold(t *testing.T) { if res.Skipped != 1 || res.Comments != 1 { t.Fatalf("result = %+v, want the row skipped after the release with one comment", res) } - if strings.Join(api.removed, ",") != "hold,needs-human" || len(api.added) != 0 { + if strings.Join(api.removed, ",") != hgithub.DefaultDecisionNeededLabel+",needs-human" || len(api.added) != 0 { t.Fatalf("removed=%v added=%v, want hold and needs-human released and nothing staged yet", api.removed, api.added) } if len(api.comments) != 1 || !IsReporterTrustReleaseComment(api.comments[0]) || !strings.Contains(api.comments[0], "reporter trust (issue #15017 by @Karibhou, contributor)") || !strings.Contains(api.comments[0], "The hive is this PR's author") { @@ -217,7 +227,7 @@ func TestApplyStageLabels_ReleasesSelfImposedReporterTrustHold(t *testing.T) { // Next pass, the hold gone: the PR stages normally and nothing is // released again (the events now end in the hive's own unlabel). api.reset() - api.issueEvents[15020] = append(api.issueEvents[15020], holdEvent("unlabeled", testHiveAppBotLogin, "2026-10-20T17:40:01Z")) + api.issueEvents[15020] = append(api.issueEvents[15020], gateEvent("unlabeled", testHiveAppBotLogin, "2026-10-20T17:40:01Z")) pr = stagePR(15020, "author/hive", "role/trusted", "stage/085-needs-decision") pr.User = &gh.User{Login: gh.Ptr(testHiveAppBotLogin), Type: gh.Ptr("Bot")} e.recordStage(stageLaneSelf, "acme/widget", "acme", "widget", pr, "queued", false, nil) @@ -230,7 +240,7 @@ func TestApplyStageLabels_ReleasesSelfImposedReporterTrustHold(t *testing.T) { } } for _, removed := range api.removed { - if removed == "hold" || removed == "needs-human" { + if removed == hgithub.DefaultDecisionNeededLabel || removed == "hold" || removed == "needs-human" { t.Fatalf("removed %q again on an unheld PR: %v", removed, api.removed) } } @@ -291,14 +301,14 @@ func TestApplyStageLabels_ReporterTrustHoldOnContributorPRIsNamed(t *testing.T) api.labels[d.Name] = d.Color } api.issueComments = map[int][]map[string]any{21: {reporterTrustNoticeComment("2026-10-20T17:14:18Z")}} - api.issueEvents = map[int][]map[string]any{21: {holdEvent("labeled", testHiveAppBotLogin, "2026-10-20T17:14:14Z")}} + api.issueEvents = map[int][]map[string]any{21: {gateEvent("labeled", testHiveAppBotLogin, "2026-10-20T17:14:14Z")}} srv := newStageAPI(t, api) defer srv.Close() clock := &contributorLaneClock{at: time.Date(2026, 10, 20, 17, 40, 0, 0, time.UTC)} e, _, store := newStageEngine(t, srv.URL, clock) ctx := context.Background() - pr := stagePR(21, "hold", "needs-human", "author/human", "role/contributor", "stage/050-review-pending") + pr := stagePR(21, hgithub.DefaultDecisionNeededLabel, "needs-human", "author/human", "role/contributor", "stage/050-review-pending") pr.User = &gh.User{Login: gh.Ptr("shared-pat-account")} e.recordStage(stageLaneContributor, "acme/widget", "acme", "widget", pr, "excluded-label:hold", false, nil) e.noteStageRole("acme", "widget", 21, stagelabels.RoleContributor) @@ -306,7 +316,7 @@ func TestApplyStageLabels_ReporterTrustHoldOnContributorPRIsNamed(t *testing.T) t.Fatal(err) } for _, removed := range api.removed { - if removed == "hold" || removed == "needs-human" { + if removed == hgithub.DefaultDecisionNeededLabel || removed == "hold" || removed == "needs-human" { t.Fatalf("the gate's hold on a PR the hive did not author was released: %v", api.removed) } } @@ -321,15 +331,15 @@ func TestApplyStageLabels_ReporterTrustHoldOnContributorPRIsNamed(t *testing.T) } } for _, want := range []string{ - "the `hold` label was set by the hive itself: reporter trust (issue #15017 by @Karibhou, contributor)", - "The hive set `hold` itself for reporter trust (issue #15017 by @Karibhou, contributor). **Release** it", + "the `decision-needed` label was set by the hive itself: reporter trust (issue #15017 by @Karibhou, contributor)", + "The hive set `decision-needed` itself for reporter trust (issue #15017 by @Karibhou, contributor). **Release** it", "or **keep** it", } { if !strings.Contains(decision, want) { t.Fatalf("085 comment lacks %q:\n%s", want, decision) } } - if strings.Contains(decision, "the `hold` label is set") { + if strings.Contains(decision, "the `decision-needed` label is set") || strings.Contains(decision, "the `hold` label is set") { t.Fatalf("085 comment still prints the bare hold line:\n%s", decision) } } diff --git a/src/pkg/github/automerge/self_authorization_release.go b/src/pkg/github/automerge/self_authorization_release.go index 61a6d88cd9..760b749cf4 100644 --- a/src/pkg/github/automerge/self_authorization_release.go +++ b/src/pkg/github/automerge/self_authorization_release.go @@ -52,8 +52,10 @@ func (c *Engine) releaseSelfAuthorizationHoldIfEligible(ctx context.Context, dis if !currentSelfAuthHold { return false, nil } - if _, err := c.gh.Issues.RemoveLabelForIssue(ctx, owner, repo, number, url.PathEscape("hold")); err != nil && !isGitHubStatus(err, http.StatusNotFound) { - return false, fmt.Errorf("removing hold label: %w", err) + // Only the #5117 gate's own decision-needed label is removed; a + // literal `hold` is never lifted by the hive (hivecommons/hive#18468). + if _, err := c.gh.Issues.RemoveLabelForIssue(ctx, owner, repo, number, url.PathEscape(hgithub.DecisionNeededLabelName())); err != nil && !isGitHubStatus(err, http.StatusNotFound) { + return false, fmt.Errorf("removing %s label: %w", hgithub.DecisionNeededLabelName(), err) } comment := &gh.IssueComment{Body: gh.Ptr(selfAuthorizationReleaseComment)} if _, _, err := c.gh.Issues.CreateComment(ctx, owner, repo, number, comment); err != nil { @@ -106,7 +108,7 @@ func (c *Engine) currentHoldWasAppliedBySelfAuthorization(ctx context.Context, o return false, fmt.Errorf("listing issue events: %w", err) } for _, event := range events { - if event == nil || event.GetLabel().GetName() == "" || !strings.EqualFold(event.GetLabel().GetName(), "hold") { + if event == nil || event.GetLabel().GetName() == "" || !strings.EqualFold(event.GetLabel().GetName(), hgithub.DecisionNeededLabelName()) { continue } if event.GetEvent() != "labeled" && event.GetEvent() != "unlabeled" { diff --git a/src/pkg/github/automerge/self_authorization_release_test.go b/src/pkg/github/automerge/self_authorization_release_test.go index 6be0dee522..a6ea058422 100644 --- a/src/pkg/github/automerge/self_authorization_release_test.go +++ b/src/pkg/github/automerge/self_authorization_release_test.go @@ -137,7 +137,7 @@ func TestReleaseSelfAuthorizationHoldListEventsError(t *testing.T) { func selfAuthHoldEvents() []map[string]any { return []map[string]any{{ "event": "labeled", - "label": map[string]string{"name": "hold"}, + "label": map[string]string{"name": hgithub.DefaultDecisionNeededLabel}, "actor": map[string]string{"login": testHiveAppBotLogin}, "created_at": "2026-09-11T11:59:59Z", }} @@ -157,7 +157,7 @@ func TestReleaseSelfAuthorizationHoldRemoveLabelError(t *testing.T) { } }) released, err := c.releaseSelfAuthorizationHoldIfEligible(context.Background(), "acme/widget", "acme", "widget", 11) - if released || err == nil || !strings.Contains(err.Error(), "removing hold label") { + if released || err == nil || !strings.Contains(err.Error(), "removing decision-needed label") { t.Fatalf("(%v, %v), want removing-hold-label failure and no release", released, err) } } @@ -210,11 +210,11 @@ func TestReleaseSelfAuthorizationHoldPaginatesCommentsAndEvents(t *testing.T) { fmt.Fprint(w, `[null, {"event":"assigned","created_at":"2026-09-11T11:00:00Z"}, {"event":"labeled","label":{"name":"quality"},"created_at":"2026-09-11T11:00:01Z"}, - {"event":"reopened","label":{"name":"hold"},"created_at":"2026-09-11T11:00:02Z"}]`) + {"event":"reopened","label":{"name":"decision-needed"},"created_at":"2026-09-11T11:00:02Z"}]`) return } json.NewEncoder(w).Encode(selfAuthHoldEvents()) - case r.Method == http.MethodDelete && r.URL.Path == "/repos/acme/widget/issues/11/labels/hold": + case r.Method == http.MethodDelete && r.URL.Path == "/repos/acme/widget/issues/11/labels/"+hgithub.DefaultDecisionNeededLabel: removed = true json.NewEncoder(w).Encode([]map[string]any{}) case r.Method == http.MethodPost && r.URL.Path == "/repos/acme/widget/issues/11/comments": @@ -246,12 +246,12 @@ func TestReleaseSelfAuthorizationHoldSkipsWhenLatestHoldEventIsUnlabeled(t *test // nothing must be released. json.NewEncoder(w).Encode([]map[string]any{{ "event": "labeled", - "label": map[string]string{"name": "hold"}, + "label": map[string]string{"name": hgithub.DefaultDecisionNeededLabel}, "actor": map[string]string{"login": testHiveAppBotLogin}, "created_at": "2026-09-11T11:00:00Z", }, { "event": "unlabeled", - "label": map[string]string{"name": "hold"}, + "label": map[string]string{"name": hgithub.DefaultDecisionNeededLabel}, "actor": map[string]string{"login": testHiveAppBotLogin}, "created_at": "2026-09-11T11:30:00Z", }}) diff --git a/src/pkg/github/client.go b/src/pkg/github/client.go index 519939f971..c396369d22 100644 --- a/src/pkg/github/client.go +++ b/src/pkg/github/client.go @@ -308,7 +308,7 @@ type Client struct { // StartPRRequestWatcher. prAuthz PRRequestAuthorizer // prHoldLabel decides, at PR-creation time, whether a freshly-opened PR must - // carry the "hold" label (F6). It receives the authoring agent and the PR's + // carry the ready-for-review gate label (F6; "hold" before #18468). It receives the authoring agent and the PR's // target repo so role-specific safety rules (for example, mandatory human // review of outreach content aimed at a repo the hive does not manage) can // be enforced alongside the authoritative ACMM level. It is consulted @@ -3800,6 +3800,12 @@ func HasHoldLabelWith(labels, extraHoldLabels []string) bool { } for _, label := range labels { lower := strings.ToLower(label) + // The hive's own gate labels (ready-for-review, decision-needed; + // hivecommons/hive#18468) block exactly like `hold`, matched exactly + // so a look-alike such as `not-ready-for-review` is not a hold. + if IsHiveGateLabel(label) { + return true + } // Provenance labels (hive/) are never hold labels, whatever the // hive ID happens to contain. The substring rule below otherwise // reads hive/hosted-...-placeHOLDer-r05x as "hold" and parks every @@ -4620,19 +4626,20 @@ const shaHoldComment = shaHoldMarker + "\n" + "You can find it by running:\n```\ngit rev-parse --short HEAD\n```\n\n" + "Or check the bottom of the console UI for the version string.\n\n" + shaHoldLegacyNoticeSentence + " " + - "Simply add a comment with the SHA and the hold will be automatically removed._" + "Simply add a comment with the SHA and the label will be automatically removed._" type SHAHoldConfig struct { PrimaryRepo string AIAuthor string InternalAuthors []string // TrustedAssociations are the GitHub author associations (OWNER, MEMBER, - // COLLABORATOR, ...) whose missing SHA gets TrustedLabel instead of the - // hard `hold` (hivecommons/hive#12002): the SHA request is a - // reproduction aid, not a maintainer park. + // COLLABORATOR, ...) that got TrustedLabel instead of the hard `hold` + // (hivecommons/hive#12002). Since #18468 every reporter gets TrustedLabel + // and the sweep no longer consults this; it is kept for callers. TrustedAssociations []string - // TrustedLabel is the soft label for trusted reporters. Empty (or "hold") - // keeps the legacy hard hold for every reporter. + // TrustedLabel is the label the sweep applies while a SHA is missing. + // Empty (or "hold") uses defaultSHAHoldLabel: the sweep never applies + // `hold` (hivecommons/hive#18468), for any reporter. TrustedLabel string } @@ -4645,23 +4652,24 @@ type SHAHoldResult struct { Softened int `json:"softened"` } -// shaHoldSoftLabel returns the soft label to apply to this reporter's issue, -// or "" when the hard `hold` applies. -func (cfg SHAHoldConfig) shaHoldSoftLabel(association string) string { +// defaultSHAHoldLabel is the label the SHA sweep applies when none is +// configured (config.DefaultSHAHoldTrustedLabel). +const defaultSHAHoldLabel = "needs-sha" + +// shaHoldLabel returns the label the sweep applies to an issue missing a SHA. +// It is never `hold`: a `hold` means a person said hands-off, and the hive +// no longer applies one itself (hivecommons/hive#18468). Before #18468 an +// untrusted reporter's issue got the hard `hold`; the sweep now gives every +// reporter this label and swaps any `hold` it applied itself for it. An +// untrusted reporter's issue still stays out of automatic work through the +// reporter-trust gate (issue_filter.reporter_trust) until a maintainer +// admits it. +func (cfg SHAHoldConfig) shaHoldLabel() string { label := strings.TrimSpace(cfg.TrustedLabel) - if label == "" || strings.EqualFold(label, "hold") { - return "" + if label == "" || strings.EqualFold(label, LegacyHiveHoldLabel) { + return defaultSHAHoldLabel } - association = strings.TrimSpace(association) - if association == "" { - return "" - } - for _, trusted := range cfg.TrustedAssociations { - if strings.EqualFold(strings.TrimSpace(trusted), association) { - return label - } - } - return "" + return label } func (c *Client) EnforceSHAHold(ctx context.Context, cfg SHAHoldConfig) (*SHAHoldResult, error) { @@ -4701,46 +4709,15 @@ func (c *Client) EnforceSHAHold(ctx context.Context, cfg SHAHoldConfig) (*SHAHol hasSHA = c.checkCommentsForSHA(ctx, owner, repo, issue.GetNumber(), author) } - if soft := cfg.shaHoldSoftLabel(issue.GetAuthorAssociation()); soft != "" { - c.enforceSoftSHAHold(ctx, owner, repo, issue.GetNumber(), author, soft, labels, held, hasSHA, result) - continue - } - - switch { - case hasSHA && held: - // Only release a hold this sweep applied. A human's `hold`, a hold - // applied by another Hive subsystem through the same App (the - // dashboard hold on a hive with no id), or any non-literal hold - // spelling (`on-hold`, `hive-pause/`) is left for its owner - // to lift (#8927). - ok, err := c.shaHoldIsOwn(ctx, owner, repo, issue.GetNumber()) - if err != nil { - c.logger.Warn("SHA-UNHOLD skipped: could not verify hold provenance", "repo", repo, "issue", issue.GetNumber(), "error", err) - result.Skipped++ - continue - } - if !ok { - c.logger.Info("SHA-UNHOLD skipped: current hold was not applied by the SHA-hold sweep", "repo", repo, "issue", issue.GetNumber(), "author", author) - result.Skipped++ - continue - } - c.unhold(ctx, owner, repo, issue.GetNumber()) - result.Unheld++ - c.logger.Info("SHA-UNHOLD", "repo", repo, "issue", issue.GetNumber(), "author", author) - case !hasSHA && !held: - c.hold(ctx, owner, repo, issue.GetNumber()) - result.Held++ - c.logger.Info("SHA-HOLD", "repo", repo, "issue", issue.GetNumber(), "author", author) - default: - result.Skipped++ - } + c.enforceSoftSHAHold(ctx, owner, repo, issue.GetNumber(), author, cfg.shaHoldLabel(), labels, held, hasSHA, result) } return result, nil } -// enforceSoftSHAHold is the trusted-reporter branch of EnforceSHAHold -// (hivecommons/hive#12002). It never applies the hard `hold`: a missing SHA +// enforceSoftSHAHold is EnforceSHAHold's one branch (trusted reporters since +// hivecommons/hive#12002, every reporter since #18468). It never applies the +// hard `hold`: a missing SHA // gets the soft label plus the usual notice, a provided SHA lifts the soft // label, and a hard `hold` this sweep applied before the soft path existed is // swapped for the soft label. A `hold` from anyone else is left alone. @@ -4817,19 +4794,6 @@ func (c *Client) checkCommentsForSHA(ctx context.Context, owner, repo string, nu return false } -func (c *Client) hold(ctx context.Context, owner, repo string, number int) { - _, _, err := c.client.Issues.AddLabelsToIssue(ctx, owner, repo, number, []string{"hold"}) - if err != nil { - c.logger.Warn("failed to add hold label", "repo", repo, "issue", number, "error", err) - } - - comment := &gh.IssueComment{Body: gh.Ptr(shaHoldComment)} - _, _, err = c.client.Issues.CreateComment(ctx, owner, repo, number, comment) - if err != nil { - c.logger.Warn("failed to post SHA hold comment", "repo", repo, "issue", number, "error", err) - } -} - func (c *Client) unhold(ctx context.Context, owner, repo string, number int) { _, err := c.client.Issues.RemoveLabelForIssue(ctx, owner, repo, number, "hold") if err != nil { diff --git a/src/pkg/github/coverage_boost_test.go b/src/pkg/github/coverage_boost_test.go index 114ab4dbb8..e691abc544 100644 --- a/src/pkg/github/coverage_boost_test.go +++ b/src/pkg/github/coverage_boost_test.go @@ -139,41 +139,6 @@ func TestSetBaseURL_InvalidURL(t *testing.T) { // hold / unhold — error paths // -------------------------------------------------------------------------- -func TestHold_AddLabelError(t *testing.T) { - org, repo := "org", "repo" - mux := http.NewServeMux() - mux.HandleFunc(fmt.Sprintf("/repos/%s/%s/issues/1/labels", org, repo), func(w http.ResponseWriter, r *http.Request) { - w.WriteHeader(http.StatusInternalServerError) - }) - mux.HandleFunc(fmt.Sprintf("/repos/%s/%s/issues/1/comments", org, repo), func(w http.ResponseWriter, r *http.Request) { - w.WriteHeader(http.StatusCreated) - json.NewEncoder(w).Encode(map[string]any{"id": 1}) - }) - server := httptest.NewServer(mux) - defer server.Close() - - c := newTestClient(t, server, org, []string{repo}) - // Should not panic — logs warning - c.hold(context.Background(), org, repo, 1) -} - -func TestHold_CommentError(t *testing.T) { - org, repo := "org", "repo" - mux := http.NewServeMux() - mux.HandleFunc(fmt.Sprintf("/repos/%s/%s/issues/1/labels", org, repo), func(w http.ResponseWriter, r *http.Request) { - json.NewEncoder(w).Encode([]map[string]any{{"name": "hold"}}) - }) - mux.HandleFunc(fmt.Sprintf("/repos/%s/%s/issues/1/comments", org, repo), func(w http.ResponseWriter, r *http.Request) { - w.WriteHeader(http.StatusInternalServerError) - }) - server := httptest.NewServer(mux) - defer server.Close() - - c := newTestClient(t, server, org, []string{repo}) - // Should not panic — logs warning - c.hold(context.Background(), org, repo, 1) -} - func TestUnhold_RemoveLabelError(t *testing.T) { org, repo := "org", "repo" mux := http.NewServeMux() diff --git a/src/pkg/github/hive_gate_label_migration.go b/src/pkg/github/hive_gate_label_migration.go new file mode 100644 index 0000000000..01537a8887 --- /dev/null +++ b/src/pkg/github/hive_gate_label_migration.go @@ -0,0 +1,187 @@ +package github + +import ( + "context" + "fmt" + "net/http" + "net/url" + "strings" + + gh "github.com/google/go-github/v72/github" + + "github.com/hivecommons/hive/pkg/delegatedecision" + "github.com/hivecommons/hive/pkg/holdguard" +) + +// hiveGateRelabelMarker marks the one comment the migration leaves on an +// item whose hive-applied `hold` it swapped (hivecommons/hive#18468). +const hiveGateRelabelMarker = "" + +// maxHiveGateRelabelsPerRepo bounds one boot's migration per repository so +// a repo with a long tail of old holds cannot spend the shared API budget in +// one burst; the rest migrate on the next boot. +const maxHiveGateRelabelsPerRepo = 50 + +// hiveGateRelabelPageSize is the page size for the held-item listing. +const hiveGateRelabelPageSize = 100 + +// HiveGateLabelMigrationResult counts what one migration run did. +type HiveGateLabelMigrationResult struct { + Relabeled int `json:"relabeled"` + // Skipped counts `hold` labels left alone: a person applied them, or + // nothing on the thread proves which hive gate applied them. + Skipped int `json:"skipped"` + Errors []string `json:"errors,omitempty"` +} + +// MigrateHiveAppliedHolds swaps the literal `hold` the hive's own gates +// applied before hivecommons/hive#18468 for the gate label that says who acts +// next, across the active repositories, and makes sure both gate labels +// exist with their descriptions. +// +// A `hold` is migrated only on two pieces of evidence, the same pair the +// level-hold and #5117 releases require: the newest `hold` label event is a +// `labeled` by the hive's App, and an App-authored notice from one of the +// hive's gates is on the thread. Anything else is a person's `hold` (or one +// the hive cannot attribute) and is never touched. The SHA-hold sweep's +// `hold` is left to that sweep. +// +// The gate label is added before `hold` is removed, so the item is never +// unblocked in between, and one short comment explains the swap. +func (c *Client) MigrateHiveAppliedHolds(ctx context.Context) (HiveGateLabelMigrationResult, error) { + var res HiveGateLabelMigrationResult + if c == nil || c.client == nil { + return res, ErrNoGitHubClient + } + if strings.TrimSpace(c.appBotLogin) == "" { + // Without the App login no `hold` can be proven hive-applied. + return res, nil + } + for _, repoRef := range c.activeRepos() { + if err := c.EnsureHiveGateLabels(ctx, repoRef); err != nil { + res.Errors = append(res.Errors, fmt.Sprintf("%s: ensuring gate labels: %v", repoRef, err)) + } + c.migrateRepoHiveHolds(ctx, repoRef, &res) + } + if len(res.Errors) > 0 { + return res, fmt.Errorf("hive gate label migration: %d error(s); first: %s", len(res.Errors), res.Errors[0]) + } + return res, nil +} + +func (c *Client) migrateRepoHiveHolds(ctx context.Context, repoRef string, res *HiveGateLabelMigrationResult) { + owner, repo := c.splitRepo(repoRef) + opts := &gh.IssueListByRepoOptions{ + State: "open", + Labels: []string{LegacyHiveHoldLabel}, + ListOptions: gh.ListOptions{PerPage: hiveGateRelabelPageSize}, + } + done := 0 + for { + items, resp, err := c.client.Issues.ListByRepo(ctx, owner, repo, opts) + if err != nil { + res.Errors = append(res.Errors, fmt.Sprintf("%s: listing held items: %v", repoRef, err)) + return + } + for _, item := range items { + if item == nil || !hasExactLabel(extractLabels(item.Labels), LegacyHiveHoldLabel) { + continue + } + if done >= maxHiveGateRelabelsPerRepo { + return + } + migrated, err := c.migrateOneHiveHold(ctx, owner, repo, item.GetNumber()) + if err != nil { + res.Errors = append(res.Errors, fmt.Sprintf("%s#%d: %v", repoRef, item.GetNumber(), err)) + continue + } + if migrated { + res.Relabeled++ + done++ + } else { + res.Skipped++ + } + } + if resp == nil || resp.NextPage == 0 { + return + } + opts.Page = resp.NextPage + } +} + +func (c *Client) migrateOneHiveHold(ctx context.Context, owner, repo string, number int) (bool, error) { + byApp, _, err := c.latestHoldLabelEventByApp(ctx, owner, repo, number) + if err != nil { + return false, err + } + if !byApp { + // A person put (or last re-put) this `hold` on: hands-off. + return false, nil + } + comments, err := c.listIssueComments(ctx, owner, repo, number) + if err != nil { + return false, err + } + label, relabeledBefore := c.hiveHoldGateLabelFromComments(comments) + if label == "" { + return false, nil + } + repoRef := owner + "/" + repo + if _, _, err := c.client.Issues.AddLabelsToIssue(ctx, owner, repo, number, []string{label}); err != nil { + return false, fmt.Errorf("adding %s: %w", label, err) + } + if _, err := c.client.Issues.RemoveLabelForIssue(ctx, owner, repo, number, url.PathEscape(LegacyHiveHoldLabel)); err != nil && !githubStatusError(err, http.StatusNotFound) { + return false, fmt.Errorf("removing hold: %w", err) + } + if !relabeledBefore { + if _, _, err := c.client.Issues.CreateComment(ctx, owner, repo, number, &gh.IssueComment{Body: gh.Ptr(hiveGateRelabelComment(label))}); err != nil && c.logger != nil { + // The label swap is the substance; the comment is the courtesy. + c.logger.Warn("hive gate label migration: swapped hold but could not comment", "repo", repoRef, "number", number, "label", label, "error", err) + } + } + if c.logger != nil { + c.logger.Info("hive gate label migration: swapped hive-applied hold", "repo", repoRef, "number", number, "label", label) + } + return true, nil +} + +// hiveHoldGateLabelFromComments maps the hive gate notice on a thread to the +// gate label that replaces its `hold`: the level gate's notice to +// ready-for-review, every decision gate's notice to decision-needed. A +// decision gate wins over the level gate, the same precedence the level-hold +// release uses. "" when no App-authored gate notice is present. The second +// result reports whether this migration already commented. +func (c *Client) hiveHoldGateLabelFromComments(comments []*gh.IssueComment) (string, bool) { + level, decision, relabeled := false, false, false + for _, comment := range comments { + if comment == nil || !c.isTrustedAppBotCommentAuthor(comment) { + continue + } + body := comment.GetBody() + switch { + case strings.Contains(body, hiveGateRelabelMarker): + relabeled = true + case IsReporterTrustHoldNotice(body), IsSelfAuthorizationHoldNotice(body), + strings.Contains(body, holdguard.CommentHeadingPhrase), + strings.Contains(body, delegatedecision.MarkerPrefix) && strings.Contains(body, "owner action required"): + decision = true + default: + if _, ok := levelHoldAgentFromNotice(body); ok { + level = true + } + } + } + switch { + case decision: + return DecisionNeededLabelName(), relabeled + case level: + return ReadyForReviewLabelName(), relabeled + } + return "", relabeled +} + +func hiveGateRelabelComment(label string) string { + _, desc, _ := hiveGateLabelDefinition(label) + return fmt.Sprintf("%s\nThe hive swapped the `hold` it had applied here for `%s`: %s The hive no longer applies `hold` itself; a `hold` a person adds still means hands-off (hivecommons/hive#18468).", + hiveGateRelabelMarker, label, desc) +} diff --git a/src/pkg/github/hive_gate_labels.go b/src/pkg/github/hive_gate_labels.go new file mode 100644 index 0000000000..0c2fa37cf3 --- /dev/null +++ b/src/pkg/github/hive_gate_labels.go @@ -0,0 +1,146 @@ +package github + +import ( + "context" + "strings" + "sync" +) + +// Hive gate labels (hivecommons/hive#18468). +// +// `hold` means "do not merge / do not act" in most projects, and a `hold` a +// person adds still means exactly that to the hive: hands-off, never +// implemented, decomposed, relayed or merged, and never removed by the hive. +// The hive itself no longer applies `hold`. When one of its own gates needs a +// person it applies one of two self-explanatory labels instead, each of which +// blocks merges exactly like `hold` (exact-match members of the hold set, see +// HasHoldLabelWith): +// +// - ready-for-review: the hive's work is done and the PR waits for a +// maintainer to review it (the ACMM level gate at L3-L5). +// - decision-needed: the hive is blocked on a human decision (the +// reporter-trust and self-authorization gates, the hold guard's re-hold +// after a branch moved under an approval, an owner-only delegated +// decision). +// +// Both names are configurable through governor.labels.ready_for_review and +// governor.labels.decision_needed; SetHiveGateLabelNames installs them. +const ( + DefaultReadyForReviewLabel = "ready-for-review" + DefaultDecisionNeededLabel = "decision-needed" + + // ReadyForReviewLabelDescription / DecisionNeededLabelDescription are the + // GitHub label descriptions: each says who acts next. + ReadyForReviewLabelDescription = "Hive's work is done; a maintainer reviews, then removes this label to let it merge." + DecisionNeededLabelDescription = "Hive is blocked on a human decision; a maintainer decides (see hive's comment)." + + readyForReviewLabelColor = "0e8a16" + decisionNeededLabelColor = "d93f0b" + + // LegacyHiveHoldLabel is the literal `hold` the hive's gates applied + // before #18468. The hive never writes it again; MigrateHiveAppliedHolds + // swaps the ones it can prove it applied for the gate label above. + LegacyHiveHoldLabel = "hold" +) + +var hiveGateLabelNames = struct { + sync.RWMutex + ready string + decision string +}{ready: DefaultReadyForReviewLabel, decision: DefaultDecisionNeededLabel} + +// SetHiveGateLabelNames installs the configured gate label names. A blank +// (or `hold`) name keeps the default: the hive must never apply `hold`. +func SetHiveGateLabelNames(readyForReview, decisionNeeded string) { + readyForReview = sanitizeGateLabelName(readyForReview, DefaultReadyForReviewLabel) + decisionNeeded = sanitizeGateLabelName(decisionNeeded, DefaultDecisionNeededLabel) + hiveGateLabelNames.Lock() + defer hiveGateLabelNames.Unlock() + hiveGateLabelNames.ready = readyForReview + hiveGateLabelNames.decision = decisionNeeded +} + +func sanitizeGateLabelName(name, def string) string { + name = strings.TrimSpace(name) + if name == "" || strings.EqualFold(name, LegacyHiveHoldLabel) { + return def + } + return name +} + +// ReadyForReviewLabelName is the label the ACMM level gate applies. +func ReadyForReviewLabelName() string { + hiveGateLabelNames.RLock() + defer hiveGateLabelNames.RUnlock() + return hiveGateLabelNames.ready +} + +// DecisionNeededLabelName is the label the hive's decision gates apply. +func DecisionNeededLabelName() string { + hiveGateLabelNames.RLock() + defer hiveGateLabelNames.RUnlock() + return hiveGateLabelNames.decision +} + +// HiveGateLabels returns the configured gate labels, ready-for-review first. +func HiveGateLabels() []string { + return []string{ReadyForReviewLabelName(), DecisionNeededLabelName()} +} + +// IsHiveGateLabel reports whether label is one of the configured gate labels +// or one of their defaults (exact, case-insensitive). The defaults stay +// recognised after a rename so a label applied under the old name keeps +// blocking until a person removes it. +func IsHiveGateLabel(label string) bool { + label = strings.TrimSpace(label) + if label == "" { + return false + } + for _, gate := range append(HiveGateLabels(), DefaultReadyForReviewLabel, DefaultDecisionNeededLabel) { + if strings.EqualFold(label, gate) { + return true + } + } + return false +} + +// HasHiveGateLabel reports whether labels carry a hive gate label. +func HasHiveGateLabel(labels []string) bool { + for _, label := range labels { + if IsHiveGateLabel(label) { + return true + } + } + return false +} + +// hiveGateLabelDefinition returns the colour and description for a gate label. +func hiveGateLabelDefinition(name string) (color, description string, ok bool) { + switch { + case strings.EqualFold(name, ReadyForReviewLabelName()) || strings.EqualFold(name, DefaultReadyForReviewLabel): + return readyForReviewLabelColor, ReadyForReviewLabelDescription, true + case strings.EqualFold(name, DecisionNeededLabelName()) || strings.EqualFold(name, DefaultDecisionNeededLabel): + return decisionNeededLabelColor, DecisionNeededLabelDescription, true + } + return "", "", false +} + +// EnsureHiveGateLabels creates the gate labels in repo when they are +// missing, with the description that says who acts next. It runs once per +// repository from the boot migration (MigrateHiveAppliedHolds); a label that +// still does not exist when a gate fires is auto-created by GitHub on the +// AddLabels call, without the description (an existing label is never +// rewritten: a maintainer may have chosen their own colour or wording). +func (c *Client) EnsureHiveGateLabels(ctx context.Context, repo string) error { + if c == nil || c.client == nil { + return ErrNoGitHubClient + } + var firstErr error + for _, label := range HiveGateLabels() { + color, desc, _ := hiveGateLabelDefinition(label) + if err := c.EnsureIssueLabel(ctx, repo, label, color, desc); err != nil && firstErr == nil { + firstErr = err + } + } + return firstErr +} diff --git a/src/pkg/github/hive_gate_labels_test.go b/src/pkg/github/hive_gate_labels_test.go new file mode 100644 index 0000000000..c2c9af5ca7 --- /dev/null +++ b/src/pkg/github/hive_gate_labels_test.go @@ -0,0 +1,254 @@ +package github + +// hivecommons/hive#18468: the hive never applies `hold` itself; its gates use +// ready-for-review / decision-needed, which block exactly like `hold`; a +// person's `hold` still blocks everything and is never touched by the hive. + +import ( + "context" + "encoding/json" + "io" + "log/slog" + "net/http" + "net/http/httptest" + "strconv" + "strings" + "sync" + "testing" +) + +func TestHiveGateLabelsBlockExactlyLikeHold(t *testing.T) { + for _, labels := range [][]string{ + {"hold"}, + {DefaultReadyForReviewLabel}, + {DefaultDecisionNeededLabel}, + {"kind/bug", "Ready-For-Review"}, + } { + if !HasHoldLabel(labels) { + t.Errorf("HasHoldLabel(%v) = false, want held", labels) + } + var nilClient *Client + if !nilClient.isHeld(labels) { + t.Errorf("isHeld(%v) = false, want held", labels) + } + } + for _, labels := range [][]string{ + {"not-ready-for-review"}, + {"decision-needed-later"}, + {"kind/bug"}, + } { + if HasHiveGateLabel(labels) { + t.Errorf("HasHiveGateLabel(%v) = true; gate labels match exactly", labels) + } + } +} + +func TestSetHiveGateLabelNamesNeverAcceptsHold(t *testing.T) { + t.Cleanup(func() { SetHiveGateLabelNames("", "") }) + SetHiveGateLabelNames("hold", " HOLD ") + if ReadyForReviewLabelName() != DefaultReadyForReviewLabel || DecisionNeededLabelName() != DefaultDecisionNeededLabel { + t.Fatalf("names = %q/%q, want the defaults: the hive must never apply hold", ReadyForReviewLabelName(), DecisionNeededLabelName()) + } + SetHiveGateLabelNames("awaiting-review", "awaiting-decision") + if !HasHoldLabel([]string{"awaiting-review"}) || !HasHoldLabel([]string{"awaiting-decision"}) { + t.Fatal("configured gate labels must block like hold") + } + if !HasHoldLabel([]string{DefaultReadyForReviewLabel}) { + t.Fatal("a default-named gate label applied before a rename must keep blocking") + } + if got := reporterTrustHoldLabels(); got[0] != "awaiting-decision" { + t.Fatalf("reporter-trust labels = %v, want the configured decision label", got) + } +} + +func TestHiveGateLabelsAreReservedFromAgents(t *testing.T) { + for _, label := range []string{"hold", DefaultReadyForReviewLabel, DefaultDecisionNeededLabel} { + if !reservedLabelForAgents(label, "lgtm") { + t.Errorf("reservedLabelForAgents(%q) = false; agents must not set or lift it", label) + } + } +} + +func TestHiveGateLabelDescriptionsSayWhoActsNext(t *testing.T) { + for _, label := range HiveGateLabels() { + _, desc, ok := hiveGateLabelDefinition(label) + if !ok || !strings.Contains(desc, "maintainer") { + t.Errorf("%s description = %q, want it to name the maintainer as the next actor", label, desc) + } + if len([]rune(desc)) > githubLabelDescriptionMax { + t.Errorf("%s description is %d runes, over GitHub's %d", label, len([]rune(desc)), githubLabelDescriptionMax) + } + } +} + +// A person's `hold` on a PR that also carries an App level-hold notice is not +// a pending level hold: only ready-for-review is ever released. +func TestPendingLevelHoldsIgnoresAPersonsHold(t *testing.T) { + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.Header().Set("Content-Type", "application/json") + switch { + case r.Method == http.MethodGet && r.URL.Path == "/repos/acme/widget/pulls": + _ = json.NewEncoder(w).Encode([]map[string]any{{ + "number": 11, "title": "fix", "body": "safe change", + "labels": []map[string]string{{"name": "hold"}}, + }}) + default: + t.Fatalf("unexpected request: %s %s (a held-only PR must not be inspected for release)", r.Method, r.URL.String()) + } + })) + t.Cleanup(srv.Close) + c := NewClientForTest(srv.URL, "acme", nil, slog.New(slog.NewTextHandler(io.Discard, nil))) + c.SetAppBotLogin(testHiveAppBotLogin) + c.SetRepos([]string{"acme/widget"}) + pending, err := c.PendingLevelHolds(context.Background()) + if err != nil || len(pending) != 0 { + t.Fatalf("PendingLevelHolds = (%v, %v), want none", pending, err) + } +} + +// migrationFake serves one repository's held items for MigrateHiveAppliedHolds. +type migrationFake struct { + mu sync.Mutex + items map[int]migrationItem + added map[int][]string + removed map[int][]string + comments map[int][]string + created []string +} + +type migrationItem struct { + holdActor string + comments []map[string]any +} + +func appComment(body string) map[string]any { + return map[string]any{"body": body, "user": map[string]string{"login": testHiveAppBotLogin}, "created_at": "2026-11-01T12:00:05Z"} +} + +func (f *migrationFake) serve(t *testing.T) *httptest.Server { + t.Helper() + f.added, f.removed, f.comments = map[int][]string{}, map[int][]string{}, map[int][]string{} + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.Header().Set("Content-Type", "application/json") + f.mu.Lock() + defer f.mu.Unlock() + path := r.URL.Path + switch { + case r.Method == http.MethodGet && strings.HasPrefix(path, "/repos/acme/widget/labels/"): + _ = json.NewEncoder(w).Encode(map[string]string{"name": strings.TrimPrefix(path, "/repos/acme/widget/labels/")}) + return + case r.Method == http.MethodGet && path == "/repos/acme/widget/issues": + if r.URL.Query().Get("labels") != "hold" { + t.Errorf("listing labels = %q, want hold", r.URL.Query().Get("labels")) + } + out := []map[string]any{} + for n := range f.items { + out = append(out, map[string]any{"number": n, "labels": []map[string]string{{"name": "hold"}}}) + } + _ = json.NewEncoder(w).Encode(out) + return + } + rest := strings.TrimPrefix(path, "/repos/acme/widget/issues/") + numStr, tail, _ := strings.Cut(rest, "/") + n, err := strconv.Atoi(numStr) + item, ok := f.items[n] + if err != nil || !ok { + t.Fatalf("unexpected request: %s %s", r.Method, r.URL.String()) + } + switch { + case r.Method == http.MethodGet && tail == "events": + _ = json.NewEncoder(w).Encode([]map[string]any{{ + "event": "labeled", "created_at": "2026-11-01T12:00:00Z", + "actor": map[string]string{"login": item.holdActor}, "label": map[string]string{"name": "hold"}, + }}) + case r.Method == http.MethodGet && tail == "comments": + _ = json.NewEncoder(w).Encode(item.comments) + case r.Method == http.MethodPost && tail == "comments": + var c map[string]string + _ = json.NewDecoder(r.Body).Decode(&c) + f.comments[n] = append(f.comments[n], c["body"]) + _ = json.NewEncoder(w).Encode(map[string]any{"id": 1}) + case r.Method == http.MethodPost && tail == "labels": + var labels []string + _ = json.NewDecoder(r.Body).Decode(&labels) + f.added[n] = append(f.added[n], labels...) + _ = json.NewEncoder(w).Encode([]map[string]string{}) + case r.Method == http.MethodDelete && strings.HasPrefix(tail, "labels/"): + if len(f.added[n]) == 0 { + t.Errorf("#%d: hold removed before the gate label was added", n) + } + f.removed[n] = append(f.removed[n], strings.TrimPrefix(tail, "labels/")) + _ = json.NewEncoder(w).Encode([]map[string]string{}) + default: + t.Fatalf("unexpected request: %s %s", r.Method, r.URL.String()) + } + })) + t.Cleanup(srv.Close) + return srv +} + +func TestMigrateHiveAppliedHoldsOnlyTouchesHiveAppliedHolds(t *testing.T) { + const ( + levelHeld = 1 + reporterHeld = 2 + humanHeld = 3 + unattributed = 4 + humanOverApp = 5 + ) + f := &migrationFake{items: map[int]migrationItem{ + levelHeld: {holdActor: testHiveAppBotLogin, comments: []map[string]any{appComment(levelHoldNotice("quality"))}}, + reporterHeld: {holdActor: testHiveAppBotLogin, comments: []map[string]any{appComment(levelHoldNotice("quality")), appComment(ReporterTrustNoticeBody(ReporterTrust{Held: true, Issue: 9, Repo: "acme/widget", Reporter: "stranger"}))}}, + humanHeld: {holdActor: "alice", comments: []map[string]any{appComment(levelHoldNotice("quality"))}}, + unattributed: {holdActor: testHiveAppBotLogin, comments: []map[string]any{appComment("routine status")}}, + // A person's comment that quotes the notice is not provenance. + humanOverApp: {holdActor: testHiveAppBotLogin, comments: []map[string]any{{"body": levelHoldNotice("quality"), "user": map[string]string{"login": "mallory"}}}}, + }} + srv := f.serve(t) + c := NewClientForTest(srv.URL, "acme", nil, slog.New(slog.NewTextHandler(io.Discard, nil))) + c.SetAppBotLogin(testHiveAppBotLogin) + c.SetRepos([]string{"acme/widget"}) + + res, err := c.MigrateHiveAppliedHolds(context.Background()) + if err != nil { + t.Fatalf("MigrateHiveAppliedHolds: %v", err) + } + if res.Relabeled != 2 || res.Skipped != 3 { + t.Fatalf("result = %+v, want 2 relabeled, 3 left alone", res) + } + if got := f.added[levelHeld]; len(got) != 1 || got[0] != DefaultReadyForReviewLabel { + t.Errorf("level hold added %v, want [ready-for-review]", got) + } + if got := f.added[reporterHeld]; len(got) != 1 || got[0] != DefaultDecisionNeededLabel { + t.Errorf("reporter-trust hold added %v, want [decision-needed]", got) + } + for _, n := range []int{levelHeld, reporterHeld} { + if got := f.removed[n]; len(got) != 1 || got[0] != "hold" { + t.Errorf("#%d removed %v, want [hold]", n, got) + } + if got := f.comments[n]; len(got) != 1 || !strings.Contains(got[0], hiveGateRelabelMarker) || !strings.Contains(got[0], "hands-off") { + t.Errorf("#%d comments %v, want one relabel explanation", n, got) + } + } + for _, n := range []int{humanHeld, unattributed, humanOverApp} { + if len(f.added[n]) != 0 || len(f.removed[n]) != 0 || len(f.comments[n]) != 0 { + t.Errorf("#%d was touched (added=%v removed=%v comments=%v); a hold the hive cannot prove it applied is hands-off", n, f.added[n], f.removed[n], f.comments[n]) + } + } + for _, label := range f.added[levelHeld] { + if label == "hold" { + t.Fatal("the migration applied hold") + } + } +} + +func TestMigrateHiveAppliedHoldsWithoutAppLoginTouchesNothing(t *testing.T) { + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + t.Fatalf("unexpected request without an App login: %s %s", r.Method, r.URL.String()) + })) + t.Cleanup(srv.Close) + c := NewClientForTest(srv.URL, "acme", nil, slog.New(slog.NewTextHandler(io.Discard, nil))) + c.SetRepos([]string{"acme/widget"}) + if res, err := c.MigrateHiveAppliedHolds(context.Background()); err != nil || res.Relabeled != 0 { + t.Fatalf("(%+v, %v), want a no-op", res, err) + } +} diff --git a/src/pkg/github/issue_request_label.go b/src/pkg/github/issue_request_label.go index 268f66a403..34a1c41f58 100644 --- a/src/pkg/github/issue_request_label.go +++ b/src/pkg/github/issue_request_label.go @@ -111,7 +111,9 @@ func reservedLabelForAgents(label, autoMergeLabel string) bool { return true } } - return false + // The hive's gate labels (hivecommons/hive#18468) are set by its own + // gates and lifted by a person; an agent neither adds nor removes them. + return IsHiveGateLabel(name) } func agentRecordableHiveStateLabel(label string) bool { diff --git a/src/pkg/github/pr_decision_operator.go b/src/pkg/github/pr_decision_operator.go index 8f0e30e6e2..aa2f891a92 100644 --- a/src/pkg/github/pr_decision_operator.go +++ b/src/pkg/github/pr_decision_operator.go @@ -417,7 +417,7 @@ func (c *Client) RecordOperatorPullRequestApprovalWith(ctx context.Context, repo return PullRequestApprovalEvent{}, errors.New("approval target changed since the decision; gather and validate again") } if opts.VerifyActorWrite { - if labelPresent(labels, "hold") || opts.GuardSentinelLabel != "" && labelPresent(labels, opts.GuardSentinelLabel) { + if labelPresent(labels, LegacyHiveHoldLabel) || HasHiveGateLabel(labels) || opts.GuardSentinelLabel != "" && labelPresent(labels, opts.GuardSentinelLabel) { return PullRequestApprovalEvent{}, errors.New("approval target gained a hold or sentinel; delegate must not release it") } permission, _, err := c.client.Repositories.GetPermissionLevel(ctx, owner, name, actor) diff --git a/src/pkg/github/pr_level_hold.go b/src/pkg/github/pr_level_hold.go index 78d77ec246..fb8a5da199 100644 --- a/src/pkg/github/pr_level_hold.go +++ b/src/pkg/github/pr_level_hold.go @@ -23,12 +23,12 @@ func levelHoldNotice(agent string) string { agent = strings.TrimSpace(agent) return fmt.Sprintf(`%s > [!IMPORTANT] -> **Held for human review by the hive's ACMM level gate.** +> **Ready for review: held for a maintainer by the hive's ACMM level gate.** > > This PR was opened by the %q agent while Hive policy required a human checkpoint for that agent. Agent PRs are held at ACMM L3–L5; an `+"`outreach`"+` PR that targets a repository this hive does not manage is held at every level because it publishes project-facing communication into someone else's project. > -> Hive will keep the `+"`hold`"+` label until a human removes it. Operators can make a deliberate one-off release during an ACMM level change with `+"`release_level_holds=true`"+`, but level changes never release this hold automatically.`, - levelHoldMarker(agent), agent) +> The hive's work on this PR is done. Hive will keep the `+"`%s`"+` label until a maintainer reviews the PR and removes it; it blocks merging the same way `+"`hold`"+` does. Operators can make a deliberate one-off release during an ACMM level change with `+"`release_level_holds=true`"+`, but level changes never release this hold automatically.`, + levelHoldMarker(agent), agent, ReadyForReviewLabelName()) } func levelHoldMarker(agent string) string { @@ -100,9 +100,9 @@ type LevelHoldPR struct { Agent string `json:"agent,omitempty"` } -// PendingLevelHolds lists open PRs across active repositories whose hold label -// is attributable to the ACMM level gate and whose latest hold-label event was -// the Hive App applying that hold. Human re-holds are not considered pending +// PendingLevelHolds lists open PRs across active repositories whose +// ready-for-review label is attributable to the ACMM level gate and whose +// latest event for that label was the Hive App applying it. Human re-holds are not considered pending // level holds; they are a human's to remove. func (c *Client) PendingLevelHolds(ctx context.Context) ([]LevelHoldPR, error) { if c == nil { @@ -118,7 +118,10 @@ func (c *Client) PendingLevelHolds(ctx context.Context) ([]LevelHoldPR, error) { return nil, fmt.Errorf("listing open pull requests for %s/%s: %w", owner, repo, err) } for _, pr := range prs { - if pr == nil || !HasHoldLabel(extractPRLabels(pr.Labels)) { + // Only the level gate's own label is ever released here; a + // `hold` (a person's, or a pre-#18468 one awaiting migration) + // is never touched. + if pr == nil || !hasExactLabel(extractPRLabels(pr.Labels), ReadyForReviewLabelName()) { continue } meta, ok, comments, err := c.levelHoldMetadataAndCommentsForPR(ctx, owner, repo, pr.GetNumber()) @@ -135,7 +138,7 @@ func (c *Client) PendingLevelHolds(ctx context.Context) ([]LevelHoldPR, error) { if blocked { continue } - appHeld, err := c.latestHoldLabelEventWasByApp(ctx, owner, repo, pr.GetNumber()) + appHeld, _, err := c.latestLabelEventByApp(ctx, owner, repo, pr.GetNumber(), ReadyForReviewLabelName()) if err != nil { return nil, err } @@ -152,7 +155,7 @@ func (c *Client) PendingLevelHolds(ctx context.Context) ([]LevelHoldPR, error) { return pending, nil } -// ReleaseLevelHoldsOnce removes the literal hold label from the level-held PRs +// ReleaseLevelHoldsOnce removes the ready-for-review gate label from the level-held PRs // currently pending across active repositories and comments with the operator // and target level that authorized this deliberate one-off release. func (c *Client) ReleaseLevelHoldsOnce(ctx context.Context, level int, actor string) ([]LevelHoldPR, error) { @@ -169,7 +172,7 @@ func (c *Client) ReleaseLevelHoldsOnce(ctx context.Context, level int, actor str } for _, pr := range pending { owner, repo := c.splitRepo(pr.Repo) - if _, err := c.client.Issues.RemoveLabelForIssue(ctx, owner, repo, pr.Number, url.PathEscape("hold")); err != nil && !githubStatusError(err, http.StatusNotFound) { + if _, err := c.client.Issues.RemoveLabelForIssue(ctx, owner, repo, pr.Number, url.PathEscape(ReadyForReviewLabelName())); err != nil && !githubStatusError(err, http.StatusNotFound) { return pending, fmt.Errorf("removing level hold label on %s#%d: %w", pr.Repo, pr.Number, err) } body := fmt.Sprintf("hold released by operator %s when raising to L%d", actor, level) @@ -260,11 +263,6 @@ func hasSelfAuthorizationNotice(comments []*gh.IssueComment, appBotLogin string) return false } -func (c *Client) latestHoldLabelEventWasByApp(ctx context.Context, owner, repo string, number int) (bool, error) { - ok, _, err := c.latestHoldLabelEventByApp(ctx, owner, repo, number) - return ok, err -} - // latestHoldLabelEventByApp reports whether the newest `hold` label event on // the issue or PR is a `labeled` by the App bot, and when that event happened // so a caller can pair it with the notice the App posted alongside it. A diff --git a/src/pkg/github/pr_level_hold_pending_test.go b/src/pkg/github/pr_level_hold_pending_test.go index 33dfee69df..d69afc254f 100644 --- a/src/pkg/github/pr_level_hold_pending_test.go +++ b/src/pkg/github/pr_level_hold_pending_test.go @@ -72,7 +72,7 @@ func TestReleaseLevelHoldsOnceSurfacesLabelRemovalError(t *testing.T) { "number": 11, "title": "fix", "body": "safe change", - "labels": []map[string]string{{"name": "hold"}}, + "labels": []map[string]string{{"name": DefaultReadyForReviewLabel}}, }}) case r.Method == http.MethodGet && r.URL.Path == "/repos/acme/widget/issues/11/comments": _ = json.NewEncoder(w).Encode([]map[string]any{{ @@ -84,9 +84,9 @@ func TestReleaseLevelHoldsOnceSurfacesLabelRemovalError(t *testing.T) { "event": "labeled", "created_at": "2026-09-15T12:00:00Z", "actor": map[string]string{"login": testHiveAppBotLogin}, - "label": map[string]string{"name": "hold"}, + "label": map[string]string{"name": DefaultReadyForReviewLabel}, }}) - case r.Method == http.MethodDelete && r.URL.Path == "/repos/acme/widget/issues/11/labels/hold": + case r.Method == http.MethodDelete && r.URL.Path == "/repos/acme/widget/issues/11/labels/"+DefaultReadyForReviewLabel: w.WriteHeader(http.StatusInternalServerError) default: t.Fatalf("unexpected request: %s %s", r.Method, r.URL.String()) @@ -111,7 +111,7 @@ func TestReleaseLevelHoldsOnceSurfacesCommentError(t *testing.T) { "number": 11, "title": "fix", "body": "safe change", - "labels": []map[string]string{{"name": "hold"}}, + "labels": []map[string]string{{"name": DefaultReadyForReviewLabel}}, }}) case r.Method == http.MethodGet && r.URL.Path == "/repos/acme/widget/issues/11/comments": _ = json.NewEncoder(w).Encode([]map[string]any{{ @@ -123,9 +123,9 @@ func TestReleaseLevelHoldsOnceSurfacesCommentError(t *testing.T) { "event": "labeled", "created_at": "2026-09-15T12:00:00Z", "actor": map[string]string{"login": testHiveAppBotLogin}, - "label": map[string]string{"name": "hold"}, + "label": map[string]string{"name": DefaultReadyForReviewLabel}, }}) - case r.Method == http.MethodDelete && r.URL.Path == "/repos/acme/widget/issues/11/labels/hold": + case r.Method == http.MethodDelete && r.URL.Path == "/repos/acme/widget/issues/11/labels/"+DefaultReadyForReviewLabel: w.WriteHeader(http.StatusOK) case r.Method == http.MethodPost && r.URL.Path == "/repos/acme/widget/issues/11/comments": w.WriteHeader(http.StatusInternalServerError) @@ -152,7 +152,7 @@ func TestPendingLevelHoldsSkipsWhenSelfAuthorizationNoticeAlreadyPosted(t *testi "number": 11, "title": "fix", "body": "safe change", - "labels": []map[string]string{{"name": "hold"}}, + "labels": []map[string]string{{"name": DefaultReadyForReviewLabel}}, }}) case r.Method == http.MethodGet && r.URL.Path == "/repos/acme/widget/issues/11/comments": _ = json.NewEncoder(w).Encode([]map[string]any{ @@ -192,7 +192,7 @@ func TestPendingLevelHoldsBlockedBySelfAuthorizationHoldActive(t *testing.T) { "number": 11, "title": "fix", "body": "Closes #581", - "labels": []map[string]string{{"name": "hold"}}, + "labels": []map[string]string{{"name": DefaultReadyForReviewLabel}}, }}) case r.Method == http.MethodGet && r.URL.Path == "/repos/acme/widget/issues/11/comments": _ = json.NewEncoder(w).Encode([]map[string]any{{ @@ -240,7 +240,7 @@ func TestPendingLevelHoldsSurfacesSelfAuthorizationNoticeError(t *testing.T) { "number": 11, "title": "fix", "body": "Closes #581", - "labels": []map[string]string{{"name": "hold"}}, + "labels": []map[string]string{{"name": DefaultReadyForReviewLabel}}, }}) case r.Method == http.MethodGet && r.URL.Path == "/repos/acme/widget/issues/11/comments": _ = json.NewEncoder(w).Encode([]map[string]any{{ diff --git a/src/pkg/github/pr_level_hold_test.go b/src/pkg/github/pr_level_hold_test.go index acd6f3a16e..45ff32bc2b 100644 --- a/src/pkg/github/pr_level_hold_test.go +++ b/src/pkg/github/pr_level_hold_test.go @@ -46,7 +46,7 @@ func (s *levelHoldServer) start(t *testing.T) *httptest.Server { "number": 11, "title": "fix", "body": body, - "labels": []map[string]string{{"name": "hold"}}, + "labels": []map[string]string{{"name": DefaultReadyForReviewLabel}}, }}) case r.Method == http.MethodGet && r.URL.Path == "/repos/acme/widget/issues/11/comments": author := s.commentAuthor @@ -93,14 +93,14 @@ func (s *levelHoldServer) start(t *testing.T) *httptest.Server { "event": "labeled", "created_at": "2026-09-15T12:00:00Z", "actor": map[string]string{"login": author}, - "label": map[string]string{"name": "hold"}, + "label": map[string]string{"name": DefaultReadyForReviewLabel}, }}) case r.Method == http.MethodPost && r.URL.Path == "/repos/acme/widget/issues/11/labels": var labels []string _ = json.NewDecoder(r.Body).Decode(&labels) s.labelsAdded = append(s.labelsAdded, labels...) _ = json.NewEncoder(w).Encode([]map[string]string{}) - case r.Method == http.MethodDelete && r.URL.Path == "/repos/acme/widget/issues/11/labels/hold": + case r.Method == http.MethodDelete && r.URL.Path == "/repos/acme/widget/issues/11/labels/"+DefaultReadyForReviewLabel: s.removes++ w.WriteHeader(http.StatusOK) default: @@ -119,7 +119,7 @@ func newLevelHoldClient(t *testing.T, s *levelHoldServer) *Client { } func heldPRFixture() *gh.PullRequest { - return &gh.PullRequest{Number: gh.Ptr(11), Title: gh.Ptr("fix"), Body: gh.Ptr("safe change"), Labels: []*gh.Label{{Name: gh.Ptr("hold")}}} + return &gh.PullRequest{Number: gh.Ptr(11), Title: gh.Ptr("fix"), Body: gh.Ptr("safe change"), Labels: []*gh.Label{{Name: gh.Ptr(DefaultReadyForReviewLabel)}}} } func TestSweepDoesNotReleaseLevelHoldAfterPromotion(t *testing.T) { diff --git a/src/pkg/github/pr_reporter_trust.go b/src/pkg/github/pr_reporter_trust.go index 03096974aa..0f8975b843 100644 --- a/src/pkg/github/pr_reporter_trust.go +++ b/src/pkg/github/pr_reporter_trust.go @@ -41,7 +41,8 @@ import ( type ReporterTrust struct { // OwnsNeedsHuman proves this gate, not an earlier escalation, added the label. OwnsNeedsHuman bool - // Held is true when the PR must carry "hold" regardless of ACMM level. + // Held is true when the PR must carry the decision-needed gate label + // regardless of ACMM level (it carried `hold` before #18468). Held bool // Issue is the untrusted-reporter issue that decided it. Zero when Held is false. Issue int @@ -266,11 +267,20 @@ func (r ReporterTrust) NeedsHumanReason() string { } // reporterTrustHoldLabels is the label set a reporter-trust hold applies. -// "hold" is the enforcement; needs-human is the signal that puts the PR in -// front of a maintainer (hivecommons/hive#10773) — without it a green, held -// PR sits silently because nothing tells anyone it is waiting on them. +// The decision-needed gate label is the enforcement (it blocks merges like +// `hold`, which the hive never applies itself: hivecommons/hive#18468); +// needs-human is the signal that puts the PR in front of a maintainer +// (hivecommons/hive#10773) — without it a green, held PR sits silently +// because nothing tells anyone it is waiting on them. func reporterTrustHoldLabels() []string { - return []string{"hold", issueNeedsHumanLabel} + return []string{DecisionNeededLabelName(), issueNeedsHumanLabel} +} + +// hasReporterTrustHoldLabel reports whether labels carry the label a +// reporter-trust hold enforces with: the decision-needed gate label, or the +// literal `hold` an older build applied (still read, never written). +func hasReporterTrustHoldLabel(labels []string) bool { + return hasExactLabel(labels, DecisionNeededLabelName()) || hasExactLabel(labels, LegacyHiveHoldLabel) } // reporterTrustNotice is the comment left on a held PR. The person clearing @@ -283,8 +293,8 @@ func reporterTrustNotice(finding ReporterTrust) string { > > The untrusted **reporter**, not this PR's author, is @%s. The PR's rationale traces to %s#%d, filed by @%s (GitHub association: %s). The hold concerns that issue reporter, not the PR author. This hive holds unaccepted work requested by untrusted issue reporters so that it never merges without a maintainer looking at it, whatever the hive's autonomy level (hivecommons/hive#9665). > -> Nothing here is a review of the change. To release the hold, a maintainer removes the `+"`hold`"+` label; Hive will not remove it on its own. The `+"`%s`"+` label marks it as waiting on a person. To trust this reporter in future, add them under **Settings → Labels → Reporter trust**.`, - reporterTrustMarker(finding), finding.NeedsHumanReason(), finding.Reporter, finding.Repo, finding.Issue, finding.Reporter, associationOrUnknown(finding.Association), issueNeedsHumanLabel) +> Nothing here is a review of the change. To release the hold, a maintainer removes the `+"`%s`"+` label; Hive will not remove it on its own. The `+"`%s`"+` label marks it as waiting on a person. To trust this reporter in future, add them under **Settings → Labels → Reporter trust**.`, + reporterTrustMarker(finding), finding.NeedsHumanReason(), finding.Reporter, finding.Repo, finding.Issue, finding.Reporter, associationOrUnknown(finding.Association), DecisionNeededLabelName(), issueNeedsHumanLabel) } // ReporterTrustNoticeBody renders the notice for a finding (exported for the @@ -345,7 +355,7 @@ func (c *Client) recordReporterTrustEscalation(repo string, number int, reason s // human-only reason, and releases only this gate's ledger entry. The existing // label-event release path removes needs-human after a human removes hold. func (c *Client) reconcileReporterTrustSignal(ctx context.Context, repo string, pr *gh.PullRequest, labels []string) ([]string, string) { - if !hasExactLabel(labels, "hold") && !hasExactLabel(labels, issueNeedsHumanLabel) { + if !hasReporterTrustHoldLabel(labels) && !hasExactLabel(labels, issueNeedsHumanLabel) { c.recordReporterTrustEscalation(repo, pr.GetNumber(), "") return labels, "" } @@ -366,7 +376,7 @@ func (c *Client) reconcileReporterTrustSignal(ctx context.Context, repo string, if !ok { return labels, "" } - if hasExactLabel(labels, "hold") { + if hasReporterTrustHoldLabel(labels) { reason := finding.escalationReason() c.recordReporterTrustEscalation(repo, pr.GetNumber(), reason) if !hasExactLabel(labels, issueNeedsHumanLabel) { @@ -497,7 +507,7 @@ func (c *Client) reporterTrustHeldPRReason(ctx context.Context, owner, repo stri // fetch; old notices without needs-human remain eligible for enrichment. candidate := false for _, label := range labels { - candidate = candidate || label == issueNeedsHumanLabel || label == "hold" + candidate = candidate || label == issueNeedsHumanLabel || label == LegacyHiveHoldLabel || strings.EqualFold(label, DecisionNeededLabelName()) } if !candidate { return "" diff --git a/src/pkg/github/pr_reporter_trust_release.go b/src/pkg/github/pr_reporter_trust_release.go index 18cb7eee10..a6bec02155 100644 --- a/src/pkg/github/pr_reporter_trust_release.go +++ b/src/pkg/github/pr_reporter_trust_release.go @@ -58,8 +58,14 @@ func (c *Client) clearReleasedReporterTrustNeedsHuman(ctx context.Context, repo if event == nil || (event.GetEvent() != "labeled" && event.GetEvent() != "unlabeled") { continue } - switch strings.ToLower(event.GetLabel().GetName()) { - case "hold": + name := strings.ToLower(event.GetLabel().GetName()) + if name == strings.ToLower(DecisionNeededLabelName()) { + // The reporter-trust gate's label since #18468; the literal + // `hold` it applied before is read the same way. + name = LegacyHiveHoldLabel + } + switch name { + case LegacyHiveHoldLabel: if event.GetEvent() == "labeled" && (holdApplied == nil || !event.GetCreatedAt().Before(holdApplied.GetCreatedAt().Time)) { holdApplied = event } diff --git a/src/pkg/github/pr_request_watcher.go b/src/pkg/github/pr_request_watcher.go index 7a81b56ec9..48bb630a62 100644 --- a/src/pkg/github/pr_request_watcher.go +++ b/src/pkg/github/pr_request_watcher.go @@ -164,7 +164,7 @@ type PRRequestAuthorizer func(agent string, fileUID int) error // // holdLabel (F6) decides server-side, from the authoring agent and authoritative // hive config (the ACMM level), whether a freshly-opened PR must carry the -// "hold" label. It is applied AFTER the PR is created, on the path that +// ready-for-review gate label (the literal "hold" before #18468). It is applied AFTER the PR is created, on the path that // actually runs — unlike the gh-wrapper.sh tail, which was dead code (it sat // after `exec hive-open-pr`), so hold-gated PRs were being opened unlabeled. A // nil holdLabel means "never hold". @@ -575,7 +575,7 @@ func (c *Client) handleOnePRRequest(ctx context.Context, path string, nowFn func resp.DuplicateTree = res.DuplicateTree resp.DuplicateReason = res.DuplicateReason - // F6: apply the ACMM "hold" label server-side, from authoritative config, on + // F6: apply the ACMM gate label (ready-for-review; "hold" before #18468) server-side, from authoritative config, on // the path that actually runs. At hold-gated levels (L3/L4/L5) every // agent-opened PR must be human-approved before merge; the label is what the // merge gate keys on. The old gh-wrapper.sh `args+=("--label" "hold")` was @@ -633,10 +633,18 @@ func (c *Client) handleOnePRRequest(ctx context.Context, path string, nowFn func resp.ReporterTrustHeld = reporter.Held } if !res.IsDuplicate() && (holdByLevel || selfAuth.Held || reporter.Held) { - holdLabels := []string{"hold"} + // The hive never applies `hold` itself (hivecommons/hive#18468): a + // person's `hold` means hands-off, and the hive's own gates say who + // acts next. The level gate's PR is done and waits for review; the + // #5117 and #9665 gates wait for a human decision. Both labels block + // merges exactly like `hold`. + holdLabels := []string{ReadyForReviewLabelName()} + if selfAuth.Held { + holdLabels = []string{DecisionNeededLabelName()} + } if reporter.Held { // A reporter-trust hold is a human-only decision at every level, so - // it raises needs-human with the hold (hivecommons/hive#10773). + // it raises needs-human with the gate label (hivecommons/hive#10773). holdLabels = reporterTrustHoldLabels() reporter.OwnsNeedsHuman = !res.AlreadyExisted } diff --git a/src/pkg/github/pr_request_watcher_test.go b/src/pkg/github/pr_request_watcher_test.go index f133eecd53..3f3a509529 100644 --- a/src/pkg/github/pr_request_watcher_test.go +++ b/src/pkg/github/pr_request_watcher_test.go @@ -271,9 +271,14 @@ func TestPRRequestWatcher_HoldLabelApplied(t *testing.T) { if created != 1 { t.Fatalf("expected the PR to be created once, got %d", created) } + // The level gate applies ready-for-review, never `hold` + // (hivecommons/hive#18468). gotHold := false for _, l := range added { - if l == "hold" { + if l == LegacyHiveHoldLabel { + t.Fatalf("watcher applied %q; the hive must never apply hold itself (labels seen: %v)", l, added) + } + if l == DefaultReadyForReviewLabel { gotHold = true } } diff --git a/src/pkg/github/pr_self_authorization.go b/src/pkg/github/pr_self_authorization.go index 2e64a42c63..fd569230ff 100644 --- a/src/pkg/github/pr_self_authorization.go +++ b/src/pkg/github/pr_self_authorization.go @@ -83,7 +83,8 @@ func (c *Client) isKnownNonHumanAuthor(user *gh.User) bool { // SelfAuthorization is the gate's finding for one PR request. type SelfAuthorization struct { - // Held is true when the PR must carry "hold" regardless of ACMM level. + // Held is true when the PR must carry the decision-needed gate label + // regardless of ACMM level (it carried `hold` before #18468). Held bool // Issue is the agent-filed issue that decided it, for the log and the // explanatory comment. Zero when Held is false. @@ -278,7 +279,7 @@ func splitRepoRef(repo, defaultOwner string) (string, string) { return strings.TrimSpace(defaultOwner), repo } -// selfAuthorizationNotice is the comment left on a held PR. A "hold" label with +// selfAuthorizationNotice is the comment left on a held PR. A gate label with // no explanation reads as a malfunction, and the person who has to clear it // needs to know what would clear it. func selfAuthorizationNotice(finding SelfAuthorization) string { @@ -288,8 +289,8 @@ func selfAuthorizationNotice(finding SelfAuthorization) string { > > This PR's only tracked rationale is %s#%d, which the hive filed itself — %s. An agent-filed issue does not, on its own, establish that anyone agreed to the direction (hivecommons/hive#5117). > -> The change may well be right; nothing here is a review of it. To release the hold, acknowledge the direction on that issue — comment on it, assign yourself, or add the `+"`%s`"+` label — and remove the `+"`hold`"+` label here.`, - SelfAuthorizationNoticeMarker, finding.Repo, finding.Issue, finding.Reason, HumanAckLabel) +> The change may well be right; nothing here is a review of it. To release the hold, acknowledge the direction on that issue — comment on it, assign yourself, or add the `+"`%s`"+` label — and remove the `+"`%s`"+` label here.`, + SelfAuthorizationNoticeMarker, finding.Repo, finding.Issue, finding.Reason, HumanAckLabel, DecisionNeededLabelName()) } // SelfAuthorizationNoticeMarker marks comments created by the #5117 @@ -460,5 +461,10 @@ func isHoldLabelEvent(event *gh.IssueEvent) bool { if event.GetEvent() != "labeled" && event.GetEvent() != "unlabeled" { return false } - return strings.EqualFold(event.GetLabel().GetName(), "hold") + // The #5117 gate applies decision-needed (hivecommons/hive#18468); the + // literal `hold` it applied before is still read so an older hold's + // history is judged the same way. Mixing the two only makes the check + // more conservative: a person's later `hold` is the latest event. + name := event.GetLabel().GetName() + return strings.EqualFold(name, DecisionNeededLabelName()) || strings.EqualFold(name, LegacyHiveHoldLabel) } diff --git a/src/pkg/github/pr_self_authorization_test.go b/src/pkg/github/pr_self_authorization_test.go index 5150327ab9..db06c19e72 100644 --- a/src/pkg/github/pr_self_authorization_test.go +++ b/src/pkg/github/pr_self_authorization_test.go @@ -428,7 +428,7 @@ func TestPRRequestWatcher_HoldsSelfAuthorizedPR(t *testing.T) { c.ProcessPRRequestsOnce(context.Background()) - if applied := srv.applied(); len(applied) != 1 || applied[0] != "hold" { + if applied := srv.applied(); len(applied) != 1 || applied[0] != DefaultDecisionNeededLabel { t.Fatalf("labels applied = %v, want [hold]", applied) } comments := srv.postedComments() @@ -480,7 +480,7 @@ func TestPRRequestWatcher_DefaultConfigStillHoldsSelfAuthorizedPR(t *testing.T) } c.ProcessPRRequestsOnce(context.Background()) - if applied := srv.applied(); len(applied) != 1 || applied[0] != "hold" { + if applied := srv.applied(); len(applied) != 1 || applied[0] != DefaultDecisionNeededLabel { t.Fatalf("labels applied = %v, want [hold] by default", applied) } if comments := srv.postedComments(); len(comments) != 1 || !strings.Contains(comments[0], SelfAuthorizationNoticeMarker) { @@ -592,7 +592,7 @@ func TestPRRequestWatcher_HoldGatedLevelSkipsTheLookup(t *testing.T) { } c.ProcessPRRequestsOnce(context.Background()) - if applied := srv.applied(); len(applied) != 1 || applied[0] != "hold" { + if applied := srv.applied(); len(applied) != 1 || applied[0] != DefaultDecisionNeededLabel { t.Fatalf("labels applied = %v, want [hold] from the level alone", applied) } srv.mu.Lock() diff --git a/src/pkg/github/reporter_trust_test.go b/src/pkg/github/reporter_trust_test.go index a0a7188659..c3ef0b7318 100644 --- a/src/pkg/github/reporter_trust_test.go +++ b/src/pkg/github/reporter_trust_test.go @@ -790,8 +790,8 @@ func TestPRRequestWatcher_HoldsUntrustedReporterPRAtL6(t *testing.T) { func assertReporterTrustHoldLabels(t *testing.T, applied []string) { t.Helper() - if len(applied) != 2 || applied[0] != "hold" || applied[1] != "needs-human" { - t.Fatalf("labels applied = %v, want [hold needs-human]", applied) + if len(applied) != 2 || applied[0] != DefaultDecisionNeededLabel || applied[1] != "needs-human" { + t.Fatalf("labels applied = %v, want [decision-needed needs-human]", applied) } } diff --git a/src/pkg/github/sha_hold_soft_test.go b/src/pkg/github/sha_hold_soft_test.go index fed7a3d603..bd9b2ce47b 100644 --- a/src/pkg/github/sha_hold_soft_test.go +++ b/src/pkg/github/sha_hold_soft_test.go @@ -89,12 +89,13 @@ func TestEnforceSHAHold_TrustedReporterGetsSoftLabel(t *testing.T) { want: SHAHoldResult{Held: 1}, }, { - name: "untrusted reporter still gets the hard hold", - association: "NONE", - labels: []wireLabel{{Name: "kind/bug"}}, - wantAdded: []string{"hold"}, - want: SHAHoldResult{Held: 1}, - // hold() posts its notice too. + // hivecommons/hive#18468: the hive never applies `hold` + // itself, so an untrusted reporter gets needs-sha too. + name: "untrusted reporter gets needs-sha, never hold", + association: "NONE", + labels: []wireLabel{{Name: "kind/bug"}}, + wantAdded: []string{"needs-sha"}, + want: SHAHoldResult{Held: 1}, wantComments: 1, }, { @@ -162,18 +163,15 @@ func TestEnforceSHAHold_TrustedReporterGetsSoftLabel(t *testing.T) { } } -func TestSHAHoldConfig_SoftLabelDisabledByHoldOrEmpty(t *testing.T) { +func TestSHAHoldConfig_LabelIsNeverHold(t *testing.T) { for _, label := range []string{"", "hold", " HOLD "} { cfg := SHAHoldConfig{TrustedAssociations: []string{"MEMBER"}, TrustedLabel: label} - if got := cfg.shaHoldSoftLabel("MEMBER"); got != "" { - t.Errorf("TrustedLabel %q: soft label = %q, want hard hold", label, got) + if got := cfg.shaHoldLabel(); got != defaultSHAHoldLabel { + t.Errorf("TrustedLabel %q: label = %q, want %q (never hold)", label, got, defaultSHAHoldLabel) } } - cfg := SHAHoldConfig{TrustedAssociations: []string{"MEMBER"}, TrustedLabel: "needs-sha"} - if got := cfg.shaHoldSoftLabel("member"); got != "needs-sha" { - t.Errorf("member soft label = %q", got) - } - if got := cfg.shaHoldSoftLabel(""); got != "" { - t.Errorf("blank association soft label = %q", got) + cfg := SHAHoldConfig{TrustedLabel: "awaiting-sha"} + if got := cfg.shaHoldLabel(); got != "awaiting-sha" { + t.Errorf("configured label = %q, want awaiting-sha", got) } } diff --git a/src/pkg/holdguard/holdguard.go b/src/pkg/holdguard/holdguard.go index 94ee8bac03..dedf76937a 100644 --- a/src/pkg/holdguard/holdguard.go +++ b/src/pkg/holdguard/holdguard.go @@ -58,11 +58,19 @@ import ( "time" ) -// ReHoldLabel is the label the guard re-applies to a drifted PR. It MUST be a -// member of github.HoldLabels so the re-applied label actually re-engages the -// hold machinery (enumeration moves the PR back into Hold.Items and both -// auto-merge sweeps skip it); cmd/hive pins that agreement with a test. -const ReHoldLabel = "hold" +// ReHoldLabel is the label the guard re-applies to a drifted PR: the hive's +// decision-needed gate label (github.DefaultDecisionNeededLabel). The hive +// never applies `hold` itself (hivecommons/hive#18468); a person's `hold` +// means hands-off. It MUST be recognised by github.HasHoldLabel so the +// re-applied label actually re-engages the hold machinery (enumeration moves +// the PR back into Hold.Items and both auto-merge sweeps skip it); cmd/hive +// pins that agreement with a test. cmd/hive applies the configured spelling +// (github.DecisionNeededLabelName), which defaults to this. +const ReHoldLabel = "decision-needed" + +// CommentHeadingPhrase opens the drift comment CommentBody posts; the +// #18468 label migration reads it as the guard's provenance for a re-hold. +const CommentHeadingPhrase = "Hold-gate integrity: branch changed" // Retention is how long an entry survives without being observed (held, lifted // clean, or drifted). Entries for PRs that merged or closed while held have no @@ -533,7 +541,7 @@ func shortSHA(sha string) string { // smuggled in. func CommentBody(d Drift) string { var b strings.Builder - b.WriteString("## 🔒 Hold-gate integrity: branch changed while hold-gated — fresh review required\n\n") + b.WriteString("## 🔒 " + CommentHeadingPhrase + " while hold-gated — fresh review required\n\n") fmt.Fprintf(&b, "This PR's branch moved while it sat hold-gated: the head recorded when the hold was applied was `%s`, but the branch now sits at `%s`. ", shortSHA(d.RecordedHeadSHA), shortSHA(d.CurrentHeadSHA)) diff --git a/src/pkg/policies/defaults/architect-holdgated.md b/src/pkg/policies/defaults/architect-holdgated.md index 94103b5be8..774437df04 100644 --- a/src/pkg/policies/defaults/architect-holdgated.md +++ b/src/pkg/policies/defaults/architect-holdgated.md @@ -10,7 +10,7 @@ Your job is to analyze system architecture, identify tech debt, anti-patterns, a 1. **Architecture analysis** — review component boundaries, dependency graphs, API contracts, data flows, and coupling 2. **Create GitHub issues for tech debt and structural problems** — every significant finding gets an issue -3. **Create hold-labeled PRs for refactors** — structural improvements, interface cleanup, dependency untangling. NEVER merge. NEVER remove the `hold` label. +3. **Create hold-labeled PRs for refactors** — structural improvements, interface cleanup, dependency untangling. NEVER merge. NEVER remove the `hold` or `ready-for-review` label. 4. **Write findings as beads** — use `bd create` for every finding 5. **Respect hold labels** — never touch issues labeled `hold`, `on-hold`, `hold/review`, `hive-pause/` (any label containing `hold` counts), or `do-not-merge` 6. **Always sign commits** with DCO: `git commit -s` @@ -96,7 +96,7 @@ If the PR body uses `Fixes #N`, `Closes #N`, or `Resolves #N`, use `src/scripts/ 2. Implement the refactor (interface extraction, package reorganization, dependency inversion) 3. Commit: `git commit -s -m "[architect] refactor: "` 4. Run `src/scripts/issue-coauthor.sh --amend ` when this resolves an issue -5. Push the branch, then request the PR with `hive-open-pr` with `hold` label — **NEVER merge**: +5. Push the branch, then request the PR with `hive-open-pr` (the hive labels it `ready-for-review`) — **NEVER merge**: Title the PR the way the TARGET repository titles PRs, and pass `--base` explicitly so the PR lands on the branch that repository requires. Read its AGENTS.md, CONTRIBUTING and recent merged PR titles first: many repositories enforce Conventional Commits and reject a `[]` prefix on the first character — that prefix is hive's own house style, and projecting it outward killed projectbluefin/common#1127 and projectbluefin/review#597 on arrival (hivecommons/hive#7159). The `[]` prefix is still REQUIRED on ISSUE titles, which the hive routes by lane; it is not used for PRs. The form below is the default for a repository that states no convention of its own. @@ -110,7 +110,7 @@ hive-open-pr --repo "$HIVE_REPO" \ ``` Architect can PR: package reorganization, interface extraction, dependency inversion, dead code removal. -Architect must NEVER: merge any PR, remove `hold` label, make feature additions or behavior changes. +Architect must NEVER: merge any PR, remove `hold` or `ready-for-review` label, make feature additions or behavior changes. ## Writing Beads diff --git a/src/pkg/policies/defaults/ci-maintainer-holdgated.md b/src/pkg/policies/defaults/ci-maintainer-holdgated.md index 80e82c2b6a..0b0c3e211f 100644 --- a/src/pkg/policies/defaults/ci-maintainer-holdgated.md +++ b/src/pkg/policies/defaults/ci-maintainer-holdgated.md @@ -8,7 +8,7 @@ You are the **ci-maintainer** agent in a Hive instance operating in **ISSUES_AND 1. **Monitor CI health** — check recent workflow runs for failures, flaky tests, slow builds 2. **Create GitHub issues for CI problems** — every persistent failure or gap gets an issue -3. **Create hold-labeled PRs for CI fixes** — workflow changes, dependency updates, runner config. NEVER merge. NEVER remove the `hold` label. +3. **Create hold-labeled PRs for CI fixes** — workflow changes, dependency updates, runner config. NEVER merge. NEVER remove the `hold` or `ready-for-review` label. 4. **Write findings as beads** — use `bd create` for every finding 5. **Respect hold labels** — never touch issues labeled `hold`, `on-hold`, `hold/review`, `hive-pause/` (any label containing `hold` counts), or `do-not-merge` 6. **Always sign commits** with DCO: `git commit -s` @@ -190,7 +190,7 @@ If the PR body uses `Fixes #N`, `Closes #N`, or `Resolves #N`, use `src/scripts/ 2. Implement the CI workflow fix 3. Commit: `git commit -s -m "[ci-maintainer] fix: "` 4. Run `src/scripts/issue-coauthor.sh --amend ` when this resolves an issue -5. Push the branch, then request the PR with `hive-open-pr` with `hold` label — **NEVER merge**: +5. Push the branch, then request the PR with `hive-open-pr` (the hive labels it `ready-for-review`) — **NEVER merge**: Title the PR the way the TARGET repository titles PRs, and pass `--base` explicitly so the PR lands on the branch that repository requires. Read its AGENTS.md, CONTRIBUTING and recent merged PR titles first: many repositories enforce Conventional Commits and reject a `[]` prefix on the first character — that prefix is hive's own house style, and projecting it outward killed projectbluefin/common#1127 and projectbluefin/review#597 on arrival (hivecommons/hive#7159). The `[]` prefix is still REQUIRED on ISSUE titles, which the hive routes by lane; it is not used for PRs. The form below is the default for a repository that states no convention of its own. @@ -214,7 +214,7 @@ File the issue with the full path, a complete diff, and the verification to run after applying it. Say it needs a maintainer using user credentials, or an ISSUES_PRS_MERGE agent where the App installation has accepted Workflows read/write, to land. The outstanding App permission change is tracked in #6985. -CI Maintainer must NEVER: merge any PR, remove `hold` label, modify production source code. +CI Maintainer must NEVER: merge any PR, remove `hold` or `ready-for-review` label, modify production source code. ## Writing Beads diff --git a/src/pkg/policies/defaults/guide-holdgated.md b/src/pkg/policies/defaults/guide-holdgated.md index d4e831f22a..011f0fbc14 100644 --- a/src/pkg/policies/defaults/guide-holdgated.md +++ b/src/pkg/policies/defaults/guide-holdgated.md @@ -10,7 +10,7 @@ Your job is to audit project documentation and fix gaps — creating issues and 1. **Documentation audit, issues, and hold-gated PRs** — find gaps, file issues, write fixes as PRs 2. **NEVER merge** — not your own PRs, not anyone else's -3. **NEVER remove the `hold` label** from any PR — humans remove it when ready +3. **NEVER remove the `hold` or `ready-for-review` label** from any PR — humans remove it when ready 4. **Write findings as beads** — use `bd create` for every finding 5. **Never write or fix code** — documentation and knowledgebase only 6. **Respect hold labels** — never touch issues labeled `hold`, `on-hold`, `hold/review`, `hive-pause/` (any label containing `hold` counts), or `do-not-merge` @@ -137,7 +137,7 @@ If the PR body uses `Fixes #N`, `Closes #N`, or `Resolves #N`, use `src/scripts/ 2. Write the documentation fix (markdown, inline comments, architecture diagrams) 3. Commit: `git commit -s -m "[guide] docs: "` 4. Run `src/scripts/issue-coauthor.sh --amend ` when this resolves an issue -5. Push the branch, then request the PR with `hive-open-pr` with `hold` label — **NEVER merge**: +5. Push the branch, then request the PR with `hive-open-pr` (the hive labels it `ready-for-review`) — **NEVER merge**: Title the PR the way the TARGET repository titles PRs, and pass `--base` explicitly so the PR lands on the branch that repository requires. Read its AGENTS.md, CONTRIBUTING and recent merged PR titles first: many repositories enforce Conventional Commits and reject a `[]` prefix on the first character — that prefix is hive's own house style, and projecting it outward killed projectbluefin/common#1127 and projectbluefin/review#597 on arrival (hivecommons/hive#7159). The `[]` prefix is still REQUIRED on ISSUE titles, which the hive routes by lane; it is not used for PRs. The form below is the default for a repository that states no convention of its own. @@ -151,7 +151,7 @@ hive-open-pr --repo "$HIVE_REPO" \ ``` Guide can PR: README updates, CONTRIBUTING improvements, architecture docs, getting-started guides, API docs. -Guide must NEVER: merge any PR, remove `hold` label, create PRs that touch source code. +Guide must NEVER: merge any PR, remove `hold` or `ready-for-review` label, create PRs that touch source code. ## Writing Beads diff --git a/src/pkg/policies/defaults/outreach-full.md b/src/pkg/policies/defaults/outreach-full.md index 72b3e921f3..a4d796ec34 100644 --- a/src/pkg/policies/defaults/outreach-full.md +++ b/src/pkg/policies/defaults/outreach-full.md @@ -10,7 +10,7 @@ Your job is to drive community engagement, ecosystem partnerships, and contribut 1. **Community outreach** — identify ecosystem partners, adoption opportunities, contributor onboarding gaps, and community health signals 2. **Create GitHub issues for engagement opportunities** — conference proposals, ecosystem integrations, blog post ideas, outreach targets -3. **Create PRs for outreach content** — blog posts, case studies, partner docs, ADOPTERS.md updates. A PR into the repo the finding is about (`$HIVE_REPO` or another hive-managed repo) is an ordinary hive PR: it follows the hive's ACMM level like any other lane's PR and auto-merges on green CI at L6. Every cross-repo outreach PR — one that targets a repository the hive does not manage (an awesome-list, a partner's docs, another org) — requires the `hold` label, including at ACMM L6; only a human may remove it and merge. The hive applies that hold server-side from the PR's target repo; you do not decide it. +3. **Create PRs for outreach content** — blog posts, case studies, partner docs, ADOPTERS.md updates. A PR into the repo the finding is about (`$HIVE_REPO` or another hive-managed repo) is an ordinary hive PR: it follows the hive's ACMM level like any other lane's PR and auto-merges on green CI at L6. Every cross-repo outreach PR — one that targets a repository the hive does not manage (an awesome-list, a partner's docs, another org) — requires the `ready-for-review` label (it blocks merging exactly like `hold`), including at ACMM L6; only a human may remove it and merge. The hive applies that hold server-side from the PR's target repo; you do not decide it. 4. **Ground every product capability claim before writing it** — verify the behavior against the current repository and released artifacts. In the PR body, cite the exact implementing file, test, release, or human-authored official documentation for each claim. A related filename or plausible platform default is not evidence that the product provides the behavior. If a claim cannot be verified, omit it and flag the question for a human. 5. **NEVER make regulatory or compliance claims** — do not describe a project or product as compliant, certified, conformant, ready for, or satisfying HIPAA, PCI DSS, GDPR, SOC 2, FedRAMP, FIPS, or any other regulatory/certification regime. Software features are not proof of an organization's compliance posture. Refuse the claim and ask a human owner to handle any regulatory language. 6. **NEVER invent roadmap commitments** — only discuss future versions, platforms, dates, or integrations when a human-authored issue, release plan, or official announcement already commits to them. Cite that source and preserve its uncertainty; otherwise omit the commitment and ask a human. diff --git a/src/pkg/policies/defaults/quality-holdgated.md b/src/pkg/policies/defaults/quality-holdgated.md index 4f9321b44d..5c8f83e234 100644 --- a/src/pkg/policies/defaults/quality-holdgated.md +++ b/src/pkg/policies/defaults/quality-holdgated.md @@ -2,13 +2,13 @@ ${GH_AUTH} -You are the **quality** agent. You analyze test coverage, open GitHub issues for testing gaps, and create hold-gated PRs with test improvements. All PRs get a `hold` label — you never merge. +You are the **quality** agent. You analyze test coverage, open GitHub issues for testing gaps, and create hold-gated PRs with test improvements. All PRs get the `ready-for-review` label (applied by the hive) — you never merge. ## Rules 1. **Analyze coverage gaps** — identify untested modules by impact 2. **Open GitHub issues for testing recommendations** — coverage gaps, missing CI workflows, test infrastructure, coverage reporting -3. **Open hold-gated PRs for test improvements** — write the tests, create a PR, label it `hold`. NEVER merge or attempt to merge. NEVER remove the `hold` label. +3. **Open hold-gated PRs for test improvements** — write the tests, create a PR; the hive labels it `ready-for-review`. NEVER merge or attempt to merge. NEVER remove the `hold` or `ready-for-review` label. 4. **Write findings as beads** — use `bd create` for every finding (feeds advisory digest) 5. **Respect hold labels** — never touch issues labeled `hold`, `on-hold`, `hold/review`, `hive-pause/` (any label containing `hold` counts), or `do-not-merge` 6. **Always sign commits** with DCO: `git commit -s` @@ -170,7 +170,7 @@ If the PR body uses `Fixes #N`, `Closes #N`, or `Resolves #N`, use `src/scripts/ 3. Commit with DCO sign-off: `git commit -s -m "[quality] "` 4. Run `src/scripts/issue-coauthor.sh --amend ` when this resolves an issue 5. Push: `git push origin quality/test-` -6. Request the PR with `hive-open-pr` with `hold` label — **NEVER merge**: +6. Request the PR with `hive-open-pr` (the hive labels it `ready-for-review`) — **NEVER merge**: Title the PR the way the TARGET repository titles PRs, and pass `--base` explicitly so the PR lands on the branch that repository requires. Read its AGENTS.md, CONTRIBUTING and recent merged PR titles first: many repositories enforce Conventional Commits and reject a `[]` prefix on the first character — that prefix is hive's own house style, and projecting it outward killed projectbluefin/common#1127 and projectbluefin/review#597 on arrival (hivecommons/hive#7159). The `[]` prefix is still REQUIRED on ISSUE titles, which the hive routes by lane; it is not used for PRs. The form below is the default for a repository that states no convention of its own. diff --git a/src/pkg/policies/defaults/scanner-holdgated.md b/src/pkg/policies/defaults/scanner-holdgated.md index 30e09ba1ef..1f93905e3a 100644 --- a/src/pkg/policies/defaults/scanner-holdgated.md +++ b/src/pkg/policies/defaults/scanner-holdgated.md @@ -9,7 +9,7 @@ You are the **scanner** agent in a Hive instance operating in **ISSUES_AND_PRS h 1. **ONLY work items from the kick message** — never run `gh issue list` or `gh pr list` unprompted 2. **The work list is your implementation queue, not just a diagnosis queue** — a human-filed enhancement or feature request in the work list is already-approved work: implement it and open a hold-gated PR. Do NOT wait for it to become a "finding", and do NOT re-file it as a new issue 3. **NEVER merge** — not your own PRs, not anyone else's -4. **NEVER remove the `hold` label** from any PR — humans remove it when ready +4. **NEVER remove the `hold` or `ready-for-review` label** from any PR — humans remove it when ready 5. **Create GitHub issues for findings** — every confirmed bug gets an issue 6. **Create hold-labeled PRs for concrete fixes** — always label PRs `hold` 6. **Write findings as beads** — use `bd create` for every finding diff --git a/src/pkg/policies/defaults/sec-check-holdgated.md b/src/pkg/policies/defaults/sec-check-holdgated.md index c2d57ddc7b..720f62549d 100644 --- a/src/pkg/policies/defaults/sec-check-holdgated.md +++ b/src/pkg/policies/defaults/sec-check-holdgated.md @@ -8,7 +8,7 @@ You are the **sec-check** agent in a Hive instance operating in **ISSUES_AND_PRS 1. **Security scanning** — audit dependencies, secrets exposure, CVEs, misconfigured permissions, unsafe patterns 2. **Create GitHub issues for vulnerabilities** — every confirmed finding is covered by an issue (batched by root cause, within the filing cap below); use severity labels -3. **Create hold-labeled PRs for security fixes** — dependency bumps, config hardening, unsafe pattern removal. NEVER merge. NEVER remove the `hold` label. +3. **Create hold-labeled PRs for security fixes** — dependency bumps, config hardening, unsafe pattern removal. NEVER merge. NEVER remove the `hold` or `ready-for-review` label. 4. **Write findings as beads** — use `bd create` for every finding 5. **Respect hold labels** — never touch issues labeled `hold`, `on-hold`, `hold/review`, `hive-pause/` (any label containing `hold` counts), or `do-not-merge` 6. **Always sign commits** with DCO: `git commit -s` @@ -144,7 +144,7 @@ If the PR body uses `Fixes #N`, `Closes #N`, or `Resolves #N`, use `src/scripts/ 2. Implement the security fix (dependency bump, config hardening, pattern fix) 3. Commit: `git commit -s -m "[sec-check] fix: "` 4. Run `src/scripts/issue-coauthor.sh --amend ` when this resolves an issue -5. Push the branch, then request the PR with `hive-open-pr` with `hold` label — **NEVER merge**: +5. Push the branch, then request the PR with `hive-open-pr` (the hive labels it `ready-for-review`) — **NEVER merge**: Title the PR the way the TARGET repository titles PRs, and pass `--base` explicitly so the PR lands on the branch that repository requires. Read its AGENTS.md, CONTRIBUTING and recent merged PR titles first: many repositories enforce Conventional Commits and reject a `[]` prefix on the first character — that prefix is hive's own house style, and projecting it outward killed projectbluefin/common#1127 and projectbluefin/review#597 on arrival (hivecommons/hive#7159). The `[]` prefix is still REQUIRED on ISSUE titles, which the hive routes by lane; it is not used for PRs. The form below is the default for a repository that states no convention of its own. @@ -162,7 +162,7 @@ Sec-Check can NOT PR a fix that lives in `.github/workflows/*.yml`: an ISSUES_AN token is minted at the `contributor` tier, which does not carry the Workflows permission, so GitHub rejects the push server-side (#6681). File the issue with the exact replacement text and say it needs a human or an ISSUES_PRS_MERGE agent to land. -Sec-Check must NEVER: merge any PR, remove `hold` label, expose secret values in PR descriptions. +Sec-Check must NEVER: merge any PR, remove `hold` or `ready-for-review` label, expose secret values in PR descriptions. ## Writing Beads diff --git a/src/pkg/policies/defaults/strategist-holdgated.md b/src/pkg/policies/defaults/strategist-holdgated.md index 3408b799cd..88eed6634e 100644 --- a/src/pkg/policies/defaults/strategist-holdgated.md +++ b/src/pkg/policies/defaults/strategist-holdgated.md @@ -10,7 +10,7 @@ Your job is to analyze project trajectory, roadmap alignment, and strategic prio 1. **Strategic planning** — analyze project momentum, adoption signals, roadmap gaps, and competitive landscape 2. **Create GitHub issues for roadmap items and strategic gaps** — prioritized by impact -3. **Create hold-labeled PRs for planning artifacts** — roadmap docs, CONTRIBUTING updates, strategic READMEs. NEVER merge. NEVER remove the `hold` label. +3. **Create hold-labeled PRs for planning artifacts** — roadmap docs, CONTRIBUTING updates, strategic READMEs. NEVER merge. NEVER remove the `hold` or `ready-for-review` label. 4. **Write findings as beads** — use `bd create` for every finding 5. **Respect hold labels** — never touch issues labeled `hold`, `on-hold`, `hold/review`, `hive-pause/` (any label containing `hold` counts), or `do-not-merge` 6. **Always sign commits** with DCO: `git commit -s` @@ -93,7 +93,7 @@ If the PR body uses `Fixes #N`, `Closes #N`, or `Resolves #N`, use `src/scripts/ 2. Write the planning artifact (ROADMAP.md, updated CONTRIBUTING, milestone doc) 3. Commit: `git commit -s -m "[strategist] planning: "` 4. Run `src/scripts/issue-coauthor.sh --amend ` when this resolves an issue -5. Push the branch, then request the PR with `hive-open-pr` with `hold` label — **NEVER merge**: +5. Push the branch, then request the PR with `hive-open-pr` (the hive labels it `ready-for-review`) — **NEVER merge**: Title the PR the way the TARGET repository titles PRs, and pass `--base` explicitly so the PR lands on the branch that repository requires. Read its AGENTS.md, CONTRIBUTING and recent merged PR titles first: many repositories enforce Conventional Commits and reject a `[]` prefix on the first character — that prefix is hive's own house style, and projecting it outward killed projectbluefin/common#1127 and projectbluefin/review#597 on arrival (hivecommons/hive#7159). The `[]` prefix is still REQUIRED on ISSUE titles, which the hive routes by lane; it is not used for PRs. The form below is the default for a repository that states no convention of its own. @@ -106,7 +106,7 @@ hive-open-pr --repo "$HIVE_REPO" \ ``` Strategist can PR: ROADMAP.md, milestone planning docs, contribution strategy docs. -Strategist must NEVER: merge any PR, remove `hold` label, implement features or write source code. +Strategist must NEVER: merge any PR, remove `hold` or `ready-for-review` label, implement features or write source code. ## Writing Beads diff --git a/src/pkg/policies/outreach_claims_test.go b/src/pkg/policies/outreach_claims_test.go index 8ae7f346f3..06651cc4e4 100644 --- a/src/pkg/policies/outreach_claims_test.go +++ b/src/pkg/policies/outreach_claims_test.go @@ -21,7 +21,7 @@ func TestOutreachPolicyRequiresGroundedHumanReviewedClaims(t *testing.T) { required := []string{ "Every cross-repo outreach PR — one that targets a repository the hive does not manage", - "requires the `hold` label, including at ACMM L6", + "requires the `ready-for-review` label (it blocks merging exactly like `hold`), including at ACMM L6", "A PR into the repo the finding is about (`$HIVE_REPO` or another hive-managed repo) is an ordinary hive PR", "Ground every product capability claim before writing it", "cite the exact implementing file, test, release, or human-authored official documentation for each claim", diff --git a/src/pkg/stagelabels/hold.go b/src/pkg/stagelabels/hold.go index 4f024cea38..f147558c0c 100644 --- a/src/pkg/stagelabels/hold.go +++ b/src/pkg/stagelabels/hold.go @@ -31,6 +31,10 @@ type HoldProvenance struct { Issue int `json:"issue,omitempty"` Reporter string `json:"reporter,omitempty"` Association string `json:"association,omitempty"` + // Label is the hold-class label this provenance explains: `hold`, or + // the hive's decision-needed gate label (hivecommons/hive#18468). + // "" reads as `hold`. + Label string `json:"label,omitempty"` } // Hold sources. @@ -77,13 +81,21 @@ func (h *HoldProvenance) Clause() string { if h.SelfImposed() { who = "the hive itself" } - s := "the `hold` label was set by " + who + s := "the `" + h.LabelOrHold() + "` label was set by " + who if reason := strings.TrimSpace(h.Reason); reason != "" { s += ": " + reason } return s } +// LabelOrHold is the label the provenance explains, `hold` when unset. +func (h *HoldProvenance) LabelOrHold() string { + if h == nil || strings.TrimSpace(h.Label) == "" { + return "hold" + } + return strings.ToLower(strings.TrimSpace(h.Label)) +} + // ReporterTrustReason renders the gate's finding the way the pill and the // comment print it: "reporter trust (issue #N by @X, contributor)". func ReporterTrustReason(issue int, reporter, association string) string { diff --git a/src/pkg/stagelabels/human.go b/src/pkg/stagelabels/human.go index e9f3e423e7..0e0bf946fe 100644 --- a/src/pkg/stagelabels/human.go +++ b/src/pkg/stagelabels/human.go @@ -250,7 +250,11 @@ func HumanApprovedReason(reason string) (base, approver string) { // `needs-decision` is retired (hivecommons/hive#12683; nothing writes it) // and stays here only so a PR still carrying it keeps its decision routing // until the label is gone. -var HoldLabels = []string{"hold", "do-not-merge", "needs-decision"} +// `ready-for-review` and `decision-needed` are the hive's own gate labels +// (hivecommons/hive#18468; github.DefaultReadyForReviewLabel and +// github.DefaultDecisionNeededLabel): the hive applies them instead of +// `hold`, and they gate the hand-off the same way. +var HoldLabels = []string{"hold", "do-not-merge", "needs-decision", "ready-for-review", "decision-needed"} // Holds filters labels down to the decision-class modifiers, lower-cased. func Holds(labels []string) []string { @@ -427,7 +431,7 @@ func GateReasons(e Evidence) []string { gates = append(gates, "a sentinel alert is open on this PR") } for _, h := range e.Holds { - if h == "hold" && e.Hold.Clause() != "" { + if e.Hold.Clause() != "" && strings.EqualFold(h, e.Hold.LabelOrHold()) { gates = append(gates, e.Hold.Clause()) continue } diff --git a/src/policies/architect-holdgated.md b/src/policies/architect-holdgated.md index 94103b5be8..774437df04 100644 --- a/src/policies/architect-holdgated.md +++ b/src/policies/architect-holdgated.md @@ -10,7 +10,7 @@ Your job is to analyze system architecture, identify tech debt, anti-patterns, a 1. **Architecture analysis** — review component boundaries, dependency graphs, API contracts, data flows, and coupling 2. **Create GitHub issues for tech debt and structural problems** — every significant finding gets an issue -3. **Create hold-labeled PRs for refactors** — structural improvements, interface cleanup, dependency untangling. NEVER merge. NEVER remove the `hold` label. +3. **Create hold-labeled PRs for refactors** — structural improvements, interface cleanup, dependency untangling. NEVER merge. NEVER remove the `hold` or `ready-for-review` label. 4. **Write findings as beads** — use `bd create` for every finding 5. **Respect hold labels** — never touch issues labeled `hold`, `on-hold`, `hold/review`, `hive-pause/` (any label containing `hold` counts), or `do-not-merge` 6. **Always sign commits** with DCO: `git commit -s` @@ -96,7 +96,7 @@ If the PR body uses `Fixes #N`, `Closes #N`, or `Resolves #N`, use `src/scripts/ 2. Implement the refactor (interface extraction, package reorganization, dependency inversion) 3. Commit: `git commit -s -m "[architect] refactor: "` 4. Run `src/scripts/issue-coauthor.sh --amend ` when this resolves an issue -5. Push the branch, then request the PR with `hive-open-pr` with `hold` label — **NEVER merge**: +5. Push the branch, then request the PR with `hive-open-pr` (the hive labels it `ready-for-review`) — **NEVER merge**: Title the PR the way the TARGET repository titles PRs, and pass `--base` explicitly so the PR lands on the branch that repository requires. Read its AGENTS.md, CONTRIBUTING and recent merged PR titles first: many repositories enforce Conventional Commits and reject a `[]` prefix on the first character — that prefix is hive's own house style, and projecting it outward killed projectbluefin/common#1127 and projectbluefin/review#597 on arrival (hivecommons/hive#7159). The `[]` prefix is still REQUIRED on ISSUE titles, which the hive routes by lane; it is not used for PRs. The form below is the default for a repository that states no convention of its own. @@ -110,7 +110,7 @@ hive-open-pr --repo "$HIVE_REPO" \ ``` Architect can PR: package reorganization, interface extraction, dependency inversion, dead code removal. -Architect must NEVER: merge any PR, remove `hold` label, make feature additions or behavior changes. +Architect must NEVER: merge any PR, remove `hold` or `ready-for-review` label, make feature additions or behavior changes. ## Writing Beads diff --git a/src/policies/ci-maintainer-holdgated.md b/src/policies/ci-maintainer-holdgated.md index 80e82c2b6a..0b0c3e211f 100644 --- a/src/policies/ci-maintainer-holdgated.md +++ b/src/policies/ci-maintainer-holdgated.md @@ -8,7 +8,7 @@ You are the **ci-maintainer** agent in a Hive instance operating in **ISSUES_AND 1. **Monitor CI health** — check recent workflow runs for failures, flaky tests, slow builds 2. **Create GitHub issues for CI problems** — every persistent failure or gap gets an issue -3. **Create hold-labeled PRs for CI fixes** — workflow changes, dependency updates, runner config. NEVER merge. NEVER remove the `hold` label. +3. **Create hold-labeled PRs for CI fixes** — workflow changes, dependency updates, runner config. NEVER merge. NEVER remove the `hold` or `ready-for-review` label. 4. **Write findings as beads** — use `bd create` for every finding 5. **Respect hold labels** — never touch issues labeled `hold`, `on-hold`, `hold/review`, `hive-pause/` (any label containing `hold` counts), or `do-not-merge` 6. **Always sign commits** with DCO: `git commit -s` @@ -190,7 +190,7 @@ If the PR body uses `Fixes #N`, `Closes #N`, or `Resolves #N`, use `src/scripts/ 2. Implement the CI workflow fix 3. Commit: `git commit -s -m "[ci-maintainer] fix: "` 4. Run `src/scripts/issue-coauthor.sh --amend ` when this resolves an issue -5. Push the branch, then request the PR with `hive-open-pr` with `hold` label — **NEVER merge**: +5. Push the branch, then request the PR with `hive-open-pr` (the hive labels it `ready-for-review`) — **NEVER merge**: Title the PR the way the TARGET repository titles PRs, and pass `--base` explicitly so the PR lands on the branch that repository requires. Read its AGENTS.md, CONTRIBUTING and recent merged PR titles first: many repositories enforce Conventional Commits and reject a `[]` prefix on the first character — that prefix is hive's own house style, and projecting it outward killed projectbluefin/common#1127 and projectbluefin/review#597 on arrival (hivecommons/hive#7159). The `[]` prefix is still REQUIRED on ISSUE titles, which the hive routes by lane; it is not used for PRs. The form below is the default for a repository that states no convention of its own. @@ -214,7 +214,7 @@ File the issue with the full path, a complete diff, and the verification to run after applying it. Say it needs a maintainer using user credentials, or an ISSUES_PRS_MERGE agent where the App installation has accepted Workflows read/write, to land. The outstanding App permission change is tracked in #6985. -CI Maintainer must NEVER: merge any PR, remove `hold` label, modify production source code. +CI Maintainer must NEVER: merge any PR, remove `hold` or `ready-for-review` label, modify production source code. ## Writing Beads diff --git a/src/policies/guide-holdgated.md b/src/policies/guide-holdgated.md index d4e831f22a..011f0fbc14 100644 --- a/src/policies/guide-holdgated.md +++ b/src/policies/guide-holdgated.md @@ -10,7 +10,7 @@ Your job is to audit project documentation and fix gaps — creating issues and 1. **Documentation audit, issues, and hold-gated PRs** — find gaps, file issues, write fixes as PRs 2. **NEVER merge** — not your own PRs, not anyone else's -3. **NEVER remove the `hold` label** from any PR — humans remove it when ready +3. **NEVER remove the `hold` or `ready-for-review` label** from any PR — humans remove it when ready 4. **Write findings as beads** — use `bd create` for every finding 5. **Never write or fix code** — documentation and knowledgebase only 6. **Respect hold labels** — never touch issues labeled `hold`, `on-hold`, `hold/review`, `hive-pause/` (any label containing `hold` counts), or `do-not-merge` @@ -137,7 +137,7 @@ If the PR body uses `Fixes #N`, `Closes #N`, or `Resolves #N`, use `src/scripts/ 2. Write the documentation fix (markdown, inline comments, architecture diagrams) 3. Commit: `git commit -s -m "[guide] docs: "` 4. Run `src/scripts/issue-coauthor.sh --amend ` when this resolves an issue -5. Push the branch, then request the PR with `hive-open-pr` with `hold` label — **NEVER merge**: +5. Push the branch, then request the PR with `hive-open-pr` (the hive labels it `ready-for-review`) — **NEVER merge**: Title the PR the way the TARGET repository titles PRs, and pass `--base` explicitly so the PR lands on the branch that repository requires. Read its AGENTS.md, CONTRIBUTING and recent merged PR titles first: many repositories enforce Conventional Commits and reject a `[]` prefix on the first character — that prefix is hive's own house style, and projecting it outward killed projectbluefin/common#1127 and projectbluefin/review#597 on arrival (hivecommons/hive#7159). The `[]` prefix is still REQUIRED on ISSUE titles, which the hive routes by lane; it is not used for PRs. The form below is the default for a repository that states no convention of its own. @@ -151,7 +151,7 @@ hive-open-pr --repo "$HIVE_REPO" \ ``` Guide can PR: README updates, CONTRIBUTING improvements, architecture docs, getting-started guides, API docs. -Guide must NEVER: merge any PR, remove `hold` label, create PRs that touch source code. +Guide must NEVER: merge any PR, remove `hold` or `ready-for-review` label, create PRs that touch source code. ## Writing Beads diff --git a/src/policies/outreach-full.md b/src/policies/outreach-full.md index 72b3e921f3..a4d796ec34 100644 --- a/src/policies/outreach-full.md +++ b/src/policies/outreach-full.md @@ -10,7 +10,7 @@ Your job is to drive community engagement, ecosystem partnerships, and contribut 1. **Community outreach** — identify ecosystem partners, adoption opportunities, contributor onboarding gaps, and community health signals 2. **Create GitHub issues for engagement opportunities** — conference proposals, ecosystem integrations, blog post ideas, outreach targets -3. **Create PRs for outreach content** — blog posts, case studies, partner docs, ADOPTERS.md updates. A PR into the repo the finding is about (`$HIVE_REPO` or another hive-managed repo) is an ordinary hive PR: it follows the hive's ACMM level like any other lane's PR and auto-merges on green CI at L6. Every cross-repo outreach PR — one that targets a repository the hive does not manage (an awesome-list, a partner's docs, another org) — requires the `hold` label, including at ACMM L6; only a human may remove it and merge. The hive applies that hold server-side from the PR's target repo; you do not decide it. +3. **Create PRs for outreach content** — blog posts, case studies, partner docs, ADOPTERS.md updates. A PR into the repo the finding is about (`$HIVE_REPO` or another hive-managed repo) is an ordinary hive PR: it follows the hive's ACMM level like any other lane's PR and auto-merges on green CI at L6. Every cross-repo outreach PR — one that targets a repository the hive does not manage (an awesome-list, a partner's docs, another org) — requires the `ready-for-review` label (it blocks merging exactly like `hold`), including at ACMM L6; only a human may remove it and merge. The hive applies that hold server-side from the PR's target repo; you do not decide it. 4. **Ground every product capability claim before writing it** — verify the behavior against the current repository and released artifacts. In the PR body, cite the exact implementing file, test, release, or human-authored official documentation for each claim. A related filename or plausible platform default is not evidence that the product provides the behavior. If a claim cannot be verified, omit it and flag the question for a human. 5. **NEVER make regulatory or compliance claims** — do not describe a project or product as compliant, certified, conformant, ready for, or satisfying HIPAA, PCI DSS, GDPR, SOC 2, FedRAMP, FIPS, or any other regulatory/certification regime. Software features are not proof of an organization's compliance posture. Refuse the claim and ask a human owner to handle any regulatory language. 6. **NEVER invent roadmap commitments** — only discuss future versions, platforms, dates, or integrations when a human-authored issue, release plan, or official announcement already commits to them. Cite that source and preserve its uncertainty; otherwise omit the commitment and ask a human. diff --git a/src/policies/quality-holdgated.md b/src/policies/quality-holdgated.md index 4f9321b44d..5c8f83e234 100644 --- a/src/policies/quality-holdgated.md +++ b/src/policies/quality-holdgated.md @@ -2,13 +2,13 @@ ${GH_AUTH} -You are the **quality** agent. You analyze test coverage, open GitHub issues for testing gaps, and create hold-gated PRs with test improvements. All PRs get a `hold` label — you never merge. +You are the **quality** agent. You analyze test coverage, open GitHub issues for testing gaps, and create hold-gated PRs with test improvements. All PRs get the `ready-for-review` label (applied by the hive) — you never merge. ## Rules 1. **Analyze coverage gaps** — identify untested modules by impact 2. **Open GitHub issues for testing recommendations** — coverage gaps, missing CI workflows, test infrastructure, coverage reporting -3. **Open hold-gated PRs for test improvements** — write the tests, create a PR, label it `hold`. NEVER merge or attempt to merge. NEVER remove the `hold` label. +3. **Open hold-gated PRs for test improvements** — write the tests, create a PR; the hive labels it `ready-for-review`. NEVER merge or attempt to merge. NEVER remove the `hold` or `ready-for-review` label. 4. **Write findings as beads** — use `bd create` for every finding (feeds advisory digest) 5. **Respect hold labels** — never touch issues labeled `hold`, `on-hold`, `hold/review`, `hive-pause/` (any label containing `hold` counts), or `do-not-merge` 6. **Always sign commits** with DCO: `git commit -s` @@ -170,7 +170,7 @@ If the PR body uses `Fixes #N`, `Closes #N`, or `Resolves #N`, use `src/scripts/ 3. Commit with DCO sign-off: `git commit -s -m "[quality] "` 4. Run `src/scripts/issue-coauthor.sh --amend ` when this resolves an issue 5. Push: `git push origin quality/test-` -6. Request the PR with `hive-open-pr` with `hold` label — **NEVER merge**: +6. Request the PR with `hive-open-pr` (the hive labels it `ready-for-review`) — **NEVER merge**: Title the PR the way the TARGET repository titles PRs, and pass `--base` explicitly so the PR lands on the branch that repository requires. Read its AGENTS.md, CONTRIBUTING and recent merged PR titles first: many repositories enforce Conventional Commits and reject a `[]` prefix on the first character — that prefix is hive's own house style, and projecting it outward killed projectbluefin/common#1127 and projectbluefin/review#597 on arrival (hivecommons/hive#7159). The `[]` prefix is still REQUIRED on ISSUE titles, which the hive routes by lane; it is not used for PRs. The form below is the default for a repository that states no convention of its own. diff --git a/src/policies/scanner-holdgated.md b/src/policies/scanner-holdgated.md index 30e09ba1ef..1f93905e3a 100644 --- a/src/policies/scanner-holdgated.md +++ b/src/policies/scanner-holdgated.md @@ -9,7 +9,7 @@ You are the **scanner** agent in a Hive instance operating in **ISSUES_AND_PRS h 1. **ONLY work items from the kick message** — never run `gh issue list` or `gh pr list` unprompted 2. **The work list is your implementation queue, not just a diagnosis queue** — a human-filed enhancement or feature request in the work list is already-approved work: implement it and open a hold-gated PR. Do NOT wait for it to become a "finding", and do NOT re-file it as a new issue 3. **NEVER merge** — not your own PRs, not anyone else's -4. **NEVER remove the `hold` label** from any PR — humans remove it when ready +4. **NEVER remove the `hold` or `ready-for-review` label** from any PR — humans remove it when ready 5. **Create GitHub issues for findings** — every confirmed bug gets an issue 6. **Create hold-labeled PRs for concrete fixes** — always label PRs `hold` 6. **Write findings as beads** — use `bd create` for every finding diff --git a/src/policies/sec-check-holdgated.md b/src/policies/sec-check-holdgated.md index c2d57ddc7b..720f62549d 100644 --- a/src/policies/sec-check-holdgated.md +++ b/src/policies/sec-check-holdgated.md @@ -8,7 +8,7 @@ You are the **sec-check** agent in a Hive instance operating in **ISSUES_AND_PRS 1. **Security scanning** — audit dependencies, secrets exposure, CVEs, misconfigured permissions, unsafe patterns 2. **Create GitHub issues for vulnerabilities** — every confirmed finding is covered by an issue (batched by root cause, within the filing cap below); use severity labels -3. **Create hold-labeled PRs for security fixes** — dependency bumps, config hardening, unsafe pattern removal. NEVER merge. NEVER remove the `hold` label. +3. **Create hold-labeled PRs for security fixes** — dependency bumps, config hardening, unsafe pattern removal. NEVER merge. NEVER remove the `hold` or `ready-for-review` label. 4. **Write findings as beads** — use `bd create` for every finding 5. **Respect hold labels** — never touch issues labeled `hold`, `on-hold`, `hold/review`, `hive-pause/` (any label containing `hold` counts), or `do-not-merge` 6. **Always sign commits** with DCO: `git commit -s` @@ -144,7 +144,7 @@ If the PR body uses `Fixes #N`, `Closes #N`, or `Resolves #N`, use `src/scripts/ 2. Implement the security fix (dependency bump, config hardening, pattern fix) 3. Commit: `git commit -s -m "[sec-check] fix: "` 4. Run `src/scripts/issue-coauthor.sh --amend ` when this resolves an issue -5. Push the branch, then request the PR with `hive-open-pr` with `hold` label — **NEVER merge**: +5. Push the branch, then request the PR with `hive-open-pr` (the hive labels it `ready-for-review`) — **NEVER merge**: Title the PR the way the TARGET repository titles PRs, and pass `--base` explicitly so the PR lands on the branch that repository requires. Read its AGENTS.md, CONTRIBUTING and recent merged PR titles first: many repositories enforce Conventional Commits and reject a `[]` prefix on the first character — that prefix is hive's own house style, and projecting it outward killed projectbluefin/common#1127 and projectbluefin/review#597 on arrival (hivecommons/hive#7159). The `[]` prefix is still REQUIRED on ISSUE titles, which the hive routes by lane; it is not used for PRs. The form below is the default for a repository that states no convention of its own. @@ -162,7 +162,7 @@ Sec-Check can NOT PR a fix that lives in `.github/workflows/*.yml`: an ISSUES_AN token is minted at the `contributor` tier, which does not carry the Workflows permission, so GitHub rejects the push server-side (#6681). File the issue with the exact replacement text and say it needs a human or an ISSUES_PRS_MERGE agent to land. -Sec-Check must NEVER: merge any PR, remove `hold` label, expose secret values in PR descriptions. +Sec-Check must NEVER: merge any PR, remove `hold` or `ready-for-review` label, expose secret values in PR descriptions. ## Writing Beads diff --git a/src/policies/strategist-holdgated.md b/src/policies/strategist-holdgated.md index 3408b799cd..88eed6634e 100644 --- a/src/policies/strategist-holdgated.md +++ b/src/policies/strategist-holdgated.md @@ -10,7 +10,7 @@ Your job is to analyze project trajectory, roadmap alignment, and strategic prio 1. **Strategic planning** — analyze project momentum, adoption signals, roadmap gaps, and competitive landscape 2. **Create GitHub issues for roadmap items and strategic gaps** — prioritized by impact -3. **Create hold-labeled PRs for planning artifacts** — roadmap docs, CONTRIBUTING updates, strategic READMEs. NEVER merge. NEVER remove the `hold` label. +3. **Create hold-labeled PRs for planning artifacts** — roadmap docs, CONTRIBUTING updates, strategic READMEs. NEVER merge. NEVER remove the `hold` or `ready-for-review` label. 4. **Write findings as beads** — use `bd create` for every finding 5. **Respect hold labels** — never touch issues labeled `hold`, `on-hold`, `hold/review`, `hive-pause/` (any label containing `hold` counts), or `do-not-merge` 6. **Always sign commits** with DCO: `git commit -s` @@ -93,7 +93,7 @@ If the PR body uses `Fixes #N`, `Closes #N`, or `Resolves #N`, use `src/scripts/ 2. Write the planning artifact (ROADMAP.md, updated CONTRIBUTING, milestone doc) 3. Commit: `git commit -s -m "[strategist] planning: "` 4. Run `src/scripts/issue-coauthor.sh --amend ` when this resolves an issue -5. Push the branch, then request the PR with `hive-open-pr` with `hold` label — **NEVER merge**: +5. Push the branch, then request the PR with `hive-open-pr` (the hive labels it `ready-for-review`) — **NEVER merge**: Title the PR the way the TARGET repository titles PRs, and pass `--base` explicitly so the PR lands on the branch that repository requires. Read its AGENTS.md, CONTRIBUTING and recent merged PR titles first: many repositories enforce Conventional Commits and reject a `[]` prefix on the first character — that prefix is hive's own house style, and projecting it outward killed projectbluefin/common#1127 and projectbluefin/review#597 on arrival (hivecommons/hive#7159). The `[]` prefix is still REQUIRED on ISSUE titles, which the hive routes by lane; it is not used for PRs. The form below is the default for a repository that states no convention of its own. @@ -106,7 +106,7 @@ hive-open-pr --repo "$HIVE_REPO" \ ``` Strategist can PR: ROADMAP.md, milestone planning docs, contribution strategy docs. -Strategist must NEVER: merge any PR, remove `hold` label, implement features or write source code. +Strategist must NEVER: merge any PR, remove `hold` or `ready-for-review` label, implement features or write source code. ## Writing Beads From 7f5069c19a3add6d0cfe169f9096c91b5c73558a Mon Sep 17 00:00:00 2001 From: Andy Anderson Date: Mon, 16 Nov 2026 17:39:34 -0500 Subject: [PATCH 2/6] =?UTF-8?q?=F0=9F=90=9B=20fix=20ambiguous=20ListOption?= =?UTF-8?q?s.Page=20and=20drifted=20docs=20citation=20(#18468)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Andy Anderson --- src/docs/scale-envelope.md | 2 +- src/pkg/github/hive_gate_label_migration.go | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/docs/scale-envelope.md b/src/docs/scale-envelope.md index e3e391f987..7fbcb246b7 100644 --- a/src/docs/scale-envelope.md +++ b/src/docs/scale-envelope.md @@ -34,7 +34,7 @@ ones to: 2. **Truncation must preserve the prioritization signal, not cut an arbitrary slice.** This holds today and is easy to assume backwards: - Issues are sorted by actionable rank tier, then **oldest first** within each tier before any cap is applied - (`RankActionableIssues`, `src/pkg/github/client.go:5286-5296`, descending `AgeMinutes` within each tier). + (`RankActionableIssues`, `src/pkg/github/client.go:5250-5260`, descending `AgeMinutes` within each tier). - PRs are sorted by **review class then oldest-first within class** (`SortPullRequestsForReview`, `src/pkg/github/review_priority.go:334`; fixes → refactors/docs → tests). diff --git a/src/pkg/github/hive_gate_label_migration.go b/src/pkg/github/hive_gate_label_migration.go index 01537a8887..fedef67219 100644 --- a/src/pkg/github/hive_gate_label_migration.go +++ b/src/pkg/github/hive_gate_label_migration.go @@ -105,7 +105,7 @@ func (c *Client) migrateRepoHiveHolds(ctx context.Context, repoRef string, res * if resp == nil || resp.NextPage == 0 { return } - opts.Page = resp.NextPage + opts.ListOptions.Page = resp.NextPage } } From 09278ab99d91246805498cc7f5e0bcda30416379 Mon Sep 17 00:00:00 2001 From: Andy Anderson Date: Mon, 16 Nov 2026 17:47:33 -0500 Subject: [PATCH 3/6] =?UTF-8?q?=F0=9F=90=9B=20gate=20the=20hold=20migratio?= =?UTF-8?q?n=20writes,=20update=20golden=20and=20stale=20test=20(#18468)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Andy Anderson --- .../config/testdata/agent_runtime_golden.json | 4 +++- src/pkg/github/hive_gate_label_migration.go | 19 ++++++++++++++----- src/pkg/github/pr_level_hold_guards_test.go | 4 ++-- .../testdata/direct-writes-baseline.txt | 2 +- 4 files changed, 20 insertions(+), 9 deletions(-) diff --git a/src/pkg/config/testdata/agent_runtime_golden.json b/src/pkg/config/testdata/agent_runtime_golden.json index ac2e1ecd62..def64b2536 100644 --- a/src/pkg/config/testdata/agent_runtime_golden.json +++ b/src/pkg/config/testdata/agent_runtime_golden.json @@ -229,7 +229,9 @@ "Human": "", "Clanker": "", "Hive": "" - } + }, + "ReadyForReview": "", + "DecisionNeeded": "" }, "Sensing": { "GHRatePatterns": [ diff --git a/src/pkg/github/hive_gate_label_migration.go b/src/pkg/github/hive_gate_label_migration.go index fedef67219..150cad2b7c 100644 --- a/src/pkg/github/hive_gate_label_migration.go +++ b/src/pkg/github/hive_gate_label_migration.go @@ -11,6 +11,7 @@ import ( "github.com/hivecommons/hive/pkg/delegatedecision" "github.com/hivecommons/hive/pkg/holdguard" + "github.com/hivecommons/hive/pkg/writeback" ) // hiveGateRelabelMarker marks the one comment the migration leaves on an @@ -90,7 +91,7 @@ func (c *Client) migrateRepoHiveHolds(ctx context.Context, repoRef string, res * if done >= maxHiveGateRelabelsPerRepo { return } - migrated, err := c.migrateOneHiveHold(ctx, owner, repo, item.GetNumber()) + migrated, err := c.migrateOneHiveHold(ctx, owner, repo, item) if err != nil { res.Errors = append(res.Errors, fmt.Sprintf("%s#%d: %v", repoRef, item.GetNumber(), err)) continue @@ -109,7 +110,8 @@ func (c *Client) migrateRepoHiveHolds(ctx context.Context, repoRef string, res * } } -func (c *Client) migrateOneHiveHold(ctx context.Context, owner, repo string, number int) (bool, error) { +func (c *Client) migrateOneHiveHold(ctx context.Context, owner, repo string, item *gh.Issue) (bool, error) { + number := item.GetNumber() byApp, _, err := c.latestHoldLabelEventByApp(ctx, owner, repo, number) if err != nil { return false, err @@ -127,14 +129,21 @@ func (c *Client) migrateOneHiveHold(ctx context.Context, owner, repo string, num return false, nil } repoRef := owner + "/" + repo - if _, _, err := c.client.Issues.AddLabelsToIssue(ctx, owner, repo, number, []string{label}); err != nil { + // The relabel goes through the one write-back gate like every other + // unsolicited write (a paused or write-restricted repo keeps its `hold`, + // which still blocks; the next boot retries). + wbItem := writeback.Item{Number: number, IsPR: item.IsPullRequest(), Author: safeGetLogin(item.GetUser()), Labels: extractLabels(item.Labels)} + if d := c.WritebackAllowed(repoRef, wbItem, writeback.KindHoldGateNotice, hiveGateRelabelComment(label)); !d.Allowed { + return false, nil + } + if _, _, err := c.client.Issues.AddLabelsToIssue(ctx, owner, repo, number, []string{label}); err != nil { // writeback:gated return false, fmt.Errorf("adding %s: %w", label, err) } - if _, err := c.client.Issues.RemoveLabelForIssue(ctx, owner, repo, number, url.PathEscape(LegacyHiveHoldLabel)); err != nil && !githubStatusError(err, http.StatusNotFound) { + if _, err := c.client.Issues.RemoveLabelForIssue(ctx, owner, repo, number, url.PathEscape(LegacyHiveHoldLabel)); err != nil && !githubStatusError(err, http.StatusNotFound) { // writeback:gated return false, fmt.Errorf("removing hold: %w", err) } if !relabeledBefore { - if _, _, err := c.client.Issues.CreateComment(ctx, owner, repo, number, &gh.IssueComment{Body: gh.Ptr(hiveGateRelabelComment(label))}); err != nil && c.logger != nil { + if _, _, err := c.client.Issues.CreateComment(ctx, owner, repo, number, &gh.IssueComment{Body: gh.Ptr(hiveGateRelabelComment(label))}); err != nil && c.logger != nil { // writeback:gated // The label swap is the substance; the comment is the courtesy. c.logger.Warn("hive gate label migration: swapped hold but could not comment", "repo", repoRef, "number", number, "label", label, "error", err) } diff --git a/src/pkg/github/pr_level_hold_guards_test.go b/src/pkg/github/pr_level_hold_guards_test.go index e79f413d11..2cd513d5b1 100644 --- a/src/pkg/github/pr_level_hold_guards_test.go +++ b/src/pkg/github/pr_level_hold_guards_test.go @@ -108,11 +108,11 @@ func TestIsTrustedLevelHoldNoticeAuthorGuards(t *testing.T) { } func TestLatestHoldLabelEventBlankLoginFailsClosed(t *testing.T) { - ok, err := (&Client{appBotLogin: " "}).latestHoldLabelEventWasByApp(context.Background(), "o", "r", 7) + ok, _, err := (&Client{appBotLogin: " "}).latestHoldLabelEventByApp(context.Background(), "o", "r", 7) if err != nil || ok { t.Fatalf("blank app bot login: got (%v, %v), want (false, nil)", ok, err) } - ok, err = (*Client)(nil).latestHoldLabelEventWasByApp(context.Background(), "o", "r", 7) + ok, _, err = (*Client)(nil).latestHoldLabelEventByApp(context.Background(), "o", "r", 7) if err != nil || ok { t.Fatalf("nil client: got (%v, %v), want (false, nil)", ok, err) } diff --git a/src/pkg/writeback/testdata/direct-writes-baseline.txt b/src/pkg/writeback/testdata/direct-writes-baseline.txt index 201a0d5521..2312f61ec3 100644 --- a/src/pkg/writeback/testdata/direct-writes-baseline.txt +++ b/src/pkg/writeback/testdata/direct-writes-baseline.txt @@ -22,7 +22,7 @@ raw pkg/github/automerge/automerge_sweep_trusted.go 4 raw pkg/github/automerge/automerge_unauthorized.go 3 raw pkg/github/automerge/reporter_trust_release.go 2 raw pkg/github/automerge/self_authorization_release.go 2 -raw pkg/github/client.go 12 +raw pkg/github/client.go 10 raw pkg/github/close_on_merge.go 3 raw pkg/github/duplicate_sweep.go 2 raw pkg/github/fleet_report.go 2 From eb78b907c059d0d52635a7551cff0d1b12bbd909 Mon Sep 17 00:00:00 2001 From: Andy Anderson Date: Mon, 16 Nov 2026 17:53:13 -0500 Subject: [PATCH 4/6] =?UTF-8?q?=F0=9F=8C=B1=20drop=20unused=20test=20field?= =?UTF-8?q?=20(#18468)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Andy Anderson --- src/pkg/github/hive_gate_labels_test.go | 1 - 1 file changed, 1 deletion(-) diff --git a/src/pkg/github/hive_gate_labels_test.go b/src/pkg/github/hive_gate_labels_test.go index c2c9af5ca7..58472a553d 100644 --- a/src/pkg/github/hive_gate_labels_test.go +++ b/src/pkg/github/hive_gate_labels_test.go @@ -113,7 +113,6 @@ type migrationFake struct { added map[int][]string removed map[int][]string comments map[int][]string - created []string } type migrationItem struct { From 62b8ade086abb3e84418e5448c3b1e79b20aaf75 Mon Sep 17 00:00:00 2001 From: Andy Anderson Date: Mon, 16 Nov 2026 18:08:23 -0500 Subject: [PATCH 5/6] =?UTF-8?q?=F0=9F=90=9B=20update=20watcher=20and=20lev?= =?UTF-8?q?el-notice=20tests=20for=20ready-for-review=20(#18468)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Andy Anderson --- src/pkg/github/pr_level_hold_test.go | 2 +- src/pkg/github/pr_self_authorization_test.go | 10 +++++----- src/pkg/github/request_watcher_start_test.go | 2 +- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/src/pkg/github/pr_level_hold_test.go b/src/pkg/github/pr_level_hold_test.go index 45ff32bc2b..b2af2898d5 100644 --- a/src/pkg/github/pr_level_hold_test.go +++ b/src/pkg/github/pr_level_hold_test.go @@ -228,7 +228,7 @@ func TestEnsureLevelHoldNoticePostsAgentAndDoesNotDuplicate(t *testing.T) { if len(s.comments) != 1 { t.Fatalf("posted %d comments, want one", len(s.comments)) } - for _, want := range []string{levelHoldNoticePrefix, `"agent":"quality"`, "quality", "human removes"} { + for _, want := range []string{levelHoldNoticePrefix, `"agent":"quality"`, "quality", "maintainer reviews the PR and removes it", "`"+DefaultReadyForReviewLabel+"`"} { if !strings.Contains(s.comments[0], want) { t.Fatalf("level hold notice missing %q:\n%s", want, s.comments[0]) } diff --git a/src/pkg/github/pr_self_authorization_test.go b/src/pkg/github/pr_self_authorization_test.go index db06c19e72..c235c68619 100644 --- a/src/pkg/github/pr_self_authorization_test.go +++ b/src/pkg/github/pr_self_authorization_test.go @@ -403,7 +403,7 @@ func TestEvaluateSelfAuthorization_RecognisesTheAIAuthorAccount(t *testing.T) { } // TestPRRequestWatcher_HoldsSelfAuthorizedPR is the end-to-end shape: the PR is -// still opened (the work is not thrown away), it carries "hold", and it carries +// still opened (the work is not thrown away), it carries "decision-needed", and it carries // a comment saying what would clear it. func TestPRRequestWatcher_HoldsSelfAuthorizedPR(t *testing.T) { const botLogin = "kubestellar-hive[bot]" @@ -429,7 +429,7 @@ func TestPRRequestWatcher_HoldsSelfAuthorizedPR(t *testing.T) { c.ProcessPRRequestsOnce(context.Background()) if applied := srv.applied(); len(applied) != 1 || applied[0] != DefaultDecisionNeededLabel { - t.Fatalf("labels applied = %v, want [hold]", applied) + t.Fatalf("labels applied = %v, want [decision-needed]", applied) } comments := srv.postedComments() if len(comments) != 1 { @@ -481,7 +481,7 @@ func TestPRRequestWatcher_DefaultConfigStillHoldsSelfAuthorizedPR(t *testing.T) c.ProcessPRRequestsOnce(context.Background()) if applied := srv.applied(); len(applied) != 1 || applied[0] != DefaultDecisionNeededLabel { - t.Fatalf("labels applied = %v, want [hold] by default", applied) + t.Fatalf("labels applied = %v, want [decision-needed] by default", applied) } if comments := srv.postedComments(); len(comments) != 1 || !strings.Contains(comments[0], SelfAuthorizationNoticeMarker) { t.Fatalf("comments = %v, want one marked #5117 notice", comments) @@ -592,8 +592,8 @@ func TestPRRequestWatcher_HoldGatedLevelSkipsTheLookup(t *testing.T) { } c.ProcessPRRequestsOnce(context.Background()) - if applied := srv.applied(); len(applied) != 1 || applied[0] != DefaultDecisionNeededLabel { - t.Fatalf("labels applied = %v, want [hold] from the level alone", applied) + if applied := srv.applied(); len(applied) != 1 || applied[0] != DefaultReadyForReviewLabel { + t.Fatalf("labels applied = %v, want [ready-for-review] from the level alone", applied) } srv.mu.Lock() listCalls := srv.listCalls diff --git a/src/pkg/github/request_watcher_start_test.go b/src/pkg/github/request_watcher_start_test.go index 2c0417b2d1..a86299c35d 100644 --- a/src/pkg/github/request_watcher_start_test.go +++ b/src/pkg/github/request_watcher_start_test.go @@ -83,7 +83,7 @@ func TestPRRequestWatcher_StartWiresAuthzAndHold(t *testing.T) { if created != 1 { t.Fatalf("expected 1 PR created, got %d", created) } - if !strings.Contains(strings.Join(addedLabels, ","), "hold") { + if !strings.Contains(strings.Join(addedLabels, ","), DefaultReadyForReviewLabel) { t.Errorf("hold-label hook passed to Start was ignored, labels=%v", addedLabels) } } From af4b7e9121c2df5936571f7bb39a8350676a5938 Mon Sep 17 00:00:00 2001 From: Andy Anderson Date: Mon, 16 Nov 2026 18:08:37 -0500 Subject: [PATCH 6/6] =?UTF-8?q?=F0=9F=8C=B1=20gofmt=20(#18468)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Andy Anderson --- src/pkg/github/pr_level_hold_test.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pkg/github/pr_level_hold_test.go b/src/pkg/github/pr_level_hold_test.go index b2af2898d5..f901187533 100644 --- a/src/pkg/github/pr_level_hold_test.go +++ b/src/pkg/github/pr_level_hold_test.go @@ -228,7 +228,7 @@ func TestEnsureLevelHoldNoticePostsAgentAndDoesNotDuplicate(t *testing.T) { if len(s.comments) != 1 { t.Fatalf("posted %d comments, want one", len(s.comments)) } - for _, want := range []string{levelHoldNoticePrefix, `"agent":"quality"`, "quality", "maintainer reviews the PR and removes it", "`"+DefaultReadyForReviewLabel+"`"} { + for _, want := range []string{levelHoldNoticePrefix, `"agent":"quality"`, "quality", "maintainer reviews the PR and removes it", "`" + DefaultReadyForReviewLabel + "`"} { if !strings.Contains(s.comments[0], want) { t.Fatalf("level hold notice missing %q:\n%s", want, s.comments[0]) }