diff --git a/changelog.d/added-review-require-labels.md b/changelog.d/added-review-require-labels.md new file mode 100644 index 0000000000..5c0fcdb82a --- /dev/null +++ b/changelog.d/added-review-require-labels.md @@ -0,0 +1 @@ +- `review.require_labels` — a PR-side approval allow-list for reviews, the counterpart of `project.issue_filter.require_labels`: when set, the hive reviews only PRs carrying at least one of the labels. Enforced server-side in the cadence reviewer's PR list, the fan-out dispatch planner and the `hive-review` relay (which re-reads the PR's labels and refuses any review, thread reply or verdict on an unlabelled PR, audited as `review_label_gate_refused`), so a prompt cannot bypass it. New **Settings → Features → Review Gate → "Only review labelled PRs"** toggle with a label list, saved through `PUT /api/config/review`. Empty (the default) changes nothing. Reported-by: @joerunde (a1-vllm-spyre spoke: "the team wants reviews gated — run only when a label is added to a PR"). diff --git a/src/cmd/hive/main.go b/src/cmd/hive/main.go index 7f36745a29..45ae35bd30 100644 --- a/src/cmd/hive/main.go +++ b/src/cmd/hive/main.go @@ -10453,6 +10453,9 @@ func installReviewRelaySettings(client *github.Client, cfg *config.Config, logge func() bool { return cfg.Review.CombinedPerspectives }, func() int { return cfg.Review.MaxReviewsPerHead }, ) + // review.require_labels (PR approval allow-list): the relay's half of the + // gate, read live so a Features-tab edit applies to the next request. + client.SetReviewRequireLabels(func() []string { return cfg.Review.RequireLabels }) } // reviewBacklogRouting resolves review.severity / review.backlog and the @@ -10801,6 +10804,7 @@ func planReviewDispatchWith(ctx context.Context, cfg *config.Config, actionable prAgents := auditPRAgents(cfg.Project.Org, time.Now().Add(-auditPRAttributionWindow), "") candidates := make([]github.PullRequest, 0, len(actionable.PRs.Items)+len(actionable.PRs.Held)) seenPRs := map[string]bool{} + labelGated := 0 addCandidates := func(items []github.PullRequest) { for _, pr := range items { fullRepo := fullRepoName(pr.Repo, cfg.Project.Org) @@ -10809,11 +10813,22 @@ func planReviewDispatchWith(ctx context.Context, cfg *config.Config, actionable continue } seenPRs[key] = true + // review.require_labels: an unlabelled PR is never dispatched + // to the swarm. The relay refuses it independently. + if !cfg.Review.AdmitsPRLabels(pr.Labels) { + labelGated++ + continue + } candidates = append(candidates, pr) } } addCandidates(actionable.PRs.Items) addCandidates(actionable.PRs.Held) + if labelGated > 0 && logger != nil { + logger.Info("review label gate withheld PRs from review dispatch", + "withheld", labelGated, "candidates", len(candidates), + "require_labels", strings.Join(cfg.Review.NormalizedRequireLabels(), ",")) + } sort.SliceStable(candidates, func(i, j int) bool { ri, rj := candidates[i].ReviewRank, candidates[j].ReviewRank if ri > 0 && rj > 0 && ri != rj { diff --git a/src/docs/agent-configuration.md b/src/docs/agent-configuration.md index 268888bca1..636bce3b99 100644 --- a/src/docs/agent-configuration.md +++ b/src/docs/agent-configuration.md @@ -1031,6 +1031,7 @@ Semantics: - An issue must carry **at least one** required label to be eligible. Matching is case-insensitive and **exact** (a prefix like `approved-for-agents-maybe` does not satisfy `approved-for-agents` — prefix matching would over-admit through an approval gate). - **Exempt wins on conflict**: an issue carrying both an exempt label and a required label stays excluded. There is deliberately no separate `exclude_labels` field — the exempt list *is* the exclusion mechanism, applied first. - PRs and the Hold list are unaffected: open PRs are in-flight work, and held issues still appear under On Hold. +- PRs have their own, separate allow-list for **reviews**: `review.require_labels` (Settings → Features → Review Gate → "Only review labelled PRs") keeps the hive from reviewing a PR until it carries an approval label; see [review-swarm.md](review-swarm.md#only-review-labelled-prs-reviewrequire_labels). Use a distinct label from the issue gate if the two approvals mean different things to your maintainers. Both polarities are enforced at **enumeration** — the point where GitHub issues become the hive's actionable set — not in the prompt. A filtered issue never enters the queue, never appears in a kick, never triggers plan-from-label, and cannot be re-selected by a confused (or prompt-injected) agent re-listing the repo. Kick prompts additionally state the active require policy so agents know the list is intentionally short. Both lists are edited on the Labels tab; an active require gate is also noted read-only under **Projects**, and hub-managed hives can receive `issue_filter` with their project config over the heartbeat. diff --git a/src/docs/dashboard-sections.md b/src/docs/dashboard-sections.md index 0cdea35f66..ff7e6f2baf 100644 --- a/src/docs/dashboard-sections.md +++ b/src/docs/dashboard-sections.md @@ -431,6 +431,8 @@ Review Pipeline shows pull requests by stage first; Review Queue lists the same Each open PR in the stage the review pipeline derived for it (GET /api/review/pipeline), with reviewers, P0–P3 findings, the fix-loop counter and the next action. +When **Settings → Features → Review Gate → Only review labelled PRs** (`review.require_labels`) is on, PRs without one of the approval labels stay in the *unreviewed* stage until a maintainer labels them: the planner never dispatches them and the relay refuses reviews on them. + **What it tells you.** Each column is one stage of the review loop: unreviewed, reviewing, changes requested, fixing, waiting for a human, approved, merged and abandoned. Each card shows the pull request, who has reviewed it, how many findings were raised at each severity and what should happen next. **How the numbers are worked out.** Hive reads the last review results it recorded for each pull request and places the card in a stage from those results alone. The collapsible Pipeline tile header shows how many pull requests are on the board. Nothing is fetched from GitHub when you open it. diff --git a/src/docs/dashboard.md b/src/docs/dashboard.md index a1304230be..efd1c1c46d 100644 --- a/src/docs/dashboard.md +++ b/src/docs/dashboard.md @@ -99,6 +99,14 @@ through `/api/config/auto-merge`, with a watched-repo multi-select (no selection means all watched repositories), role selector, GitHub permission switch, and excluded-label list. +Governor settings **Features → Review Gate** includes the owner-only +**Only review labelled PRs** toggle with a comma-separated label list. It +edits `review.require_labels` through `/api/config/review`; on, the hive +reviews only PRs carrying one of the labels (enforced in the reviewer kick +list, the review dispatch planner and the hive-review relay — see +[review-swarm.md](review-swarm.md#only-review-labelled-prs-reviewrequire_labels)). +Off (the default) sends an empty list and every open PR stays reviewable. + The cadence table starts each agent row with the same `1`/`0` Agent power rocker used in the agent settings panel, so owners can enable or disable an agent from the table; disabled rows are dimmed, and read-only viewers see the diff --git a/src/docs/review-swarm.md b/src/docs/review-swarm.md index dfa0221475..fec72d5ddb 100644 --- a/src/docs/review-swarm.md +++ b/src/docs/review-swarm.md @@ -181,6 +181,7 @@ review: contributor_prs: base_sync: false # optional; let GitHub update-branch unstick hive-authored fork PRs (default off) priority_labels: false # optional; mirror the PR review queue rank onto review-priority/* labels (default off) + require_labels: [] # optional; review ONLY PRs carrying one of these labels (default empty = every open PR); see "Only review labelled PRs" pending_ttl: 45m # optional; re-dispatch a review that has posted no verdict after this long (default 45m) pending_fix_ttl: 2h # optional; dispatch the next bounded fix attempt when a fixer has pushed no new head after this long (default 2h; negative disables expiry) max_redispatch: 3 # optional; expiries per head before the PR is held for a human (default 3) @@ -202,6 +203,46 @@ review: ### Blocking line (`review.severity`, `review.backlog`) +### Only review labelled PRs (`review.require_labels`) + +`review.require_labels` is the PR-side counterpart of the issue approval gate +`project.issue_filter.require_labels` ([agent-configuration.md](agent-configuration.md#label-policy-which-issues-agents-may-work)): +a team that wants hive reviews **only on PRs a maintainer has opted in** names +the label(s) here, and the hive reviews nothing else. + +```yaml +review: + require_labels: [hive-review] # a PR is reviewed only if it carries at least one of these +``` + +Dashboard: **Settings → Features → Review Gate → "Only review labelled PRs"** +(toggle + comma-separated label list; saved through `PUT /api/config/review` +into the dashboard overlay, so it survives restarts and ACMM pack re-applies — +it is a `review.*` key, not an agent block). + +Semantics: + +- **Absent/empty = no gate.** Every open PR stays reviewable; no existing hive + goes quiet on upgrade. +- A PR must carry **at least one** listed label. Matching is case-insensitive + and **exact** (`approved-for-review` does not satisfy `approved`). +- **Enforced server-side in three places**, so a prompt cannot route around it: + the cadence reviewer's `${PR_LIST}` and the fan-out dispatch planner never + offer an unlabelled PR (log line `review label gate withheld PRs from …`), + and the `hive-review` relay refuses any request — review, thread reply, + resolution or bare `record_verdict` — on a PR that lacks the label after + re-reading its labels with the App token (`.denied`, audit + `review_label_gate_refused`). A failed label fetch is retried, never waved + through. +- The reviewer's kick carries a `REVIEW LABEL GATE` notice naming the labels, + mirroring the issue-filter notice. +- Labels are **never created** by the hive; name one the repo already + maintains. Exempt/hold labels still exclude a PR that also carries an + approval label. +- It is independent of `review.require_approval`: a hive that gates merge on + review AND gates review on a label simply does not merge unlabelled PRs + until a person labels (or merges) them. + `review.severity.block_at` is the lowest finding priority that still blocks merge, on the P0–P3 scale (critical → P0, high → P1, medium → P2, low/info → P3). **Settings → Features → Review Gate → Severity & backlog** offers three presets: *Strict (P0–P2 block)* sets `P2`, *Ship fast (P0–P1 block)* sets `P1`, and *Everything blocks* sets `P3`. Unset keeps today's behaviour. Findings below the line are posted as non-blocking comments when `comment_below` is true (default) and filed as follow-up work when `backlog_below` is true (default). `review.backlog` says where that follow-up work goes: diff --git a/src/pkg/config/config.go b/src/pkg/config/config.go index 660e44c5c4..d123b7eabb 100644 --- a/src/pkg/config/config.go +++ b/src/pkg/config/config.go @@ -7565,6 +7565,18 @@ type ReviewConfig struct { // a repo that does not already have them is skipped. Off by default: a // label on every PR is churn a repo must ask for. PriorityLabels bool `yaml:"priority_labels,omitempty" json:"priority_labels,omitempty"` + // RequireLabels is the PR-side approval allow-list, the review + // counterpart of project.issue_filter.require_labels. Non-empty: a PR is + // reviewed by the hive only if it carries AT LEAST ONE of these labels + // (case-insensitive exact match). It is enforced in two places so a + // prompt cannot route around it: the reviewer kick lists and the review + // dispatch planner never offer an unlabelled PR, and the hive-review + // relay refuses to post on one. Absent/empty keeps today's behaviour — + // every open PR is reviewable — so no existing hive goes quiet on + // upgrade. The label is never created: name one the governed repos + // already maintain. Operator-added hold/exempt labels still exclude a PR + // that also carries an approval label. + RequireLabels []string `yaml:"require_labels,omitempty" json:"require_labels,omitempty"` // VerdictLabels mirrors the review swarm's state for each PR's current // head onto exactly one label (hivecommons/hive#13833): reviewing while // the head's review is pending, then the settled verdict. Independent of diff --git a/src/pkg/config/review_require_labels.go b/src/pkg/config/review_require_labels.go new file mode 100644 index 0000000000..dbac8cb463 --- /dev/null +++ b/src/pkg/config/review_require_labels.go @@ -0,0 +1,52 @@ +package config + +import "strings" + +// ReviewRequireLabelsSkipReason is the one phrase every surface uses when +// review.require_labels keeps a PR out of review, so a kick list, the relay's +// refusal and the governor log all read the same. +const ReviewRequireLabelsSkipReason = "review.require_labels: PR carries none of the approval labels" + +// NormalizedRequireLabels returns review.require_labels trimmed and without +// blanks or duplicates, in the operator's order. An all-blank list is nil, +// which every caller reads as "gate off". +func (r ReviewConfig) NormalizedRequireLabels() []string { + if len(r.RequireLabels) == 0 { + return nil + } + out := make([]string, 0, len(r.RequireLabels)) + seen := map[string]bool{} + for _, l := range r.RequireLabels { + l = strings.TrimSpace(l) + if l == "" { + continue + } + key := strings.ToLower(l) + if seen[key] { + continue + } + seen[key] = true + out = append(out, l) + } + if len(out) == 0 { + return nil + } + return out +} + +// RequireLabelsEnabled reports whether the PR review label gate is on. +func (r ReviewConfig) RequireLabelsEnabled() bool { + return len(r.NormalizedRequireLabels()) > 0 +} + +// AdmitsPRLabels is the review-side counterpart of IssueFilterConfig.Admits: +// with review.require_labels empty every PR is admitted; otherwise the PR must +// carry at least one of the configured labels (case-insensitive exact match, +// never prefix — "approved-for-review" must not admit under "approved"). +func (r ReviewConfig) AdmitsPRLabels(labels []string) bool { + required := r.NormalizedRequireLabels() + if len(required) == 0 { + return true + } + return anyLabelMatches(required, labels) +} diff --git a/src/pkg/config/review_require_labels_test.go b/src/pkg/config/review_require_labels_test.go new file mode 100644 index 0000000000..fabd7a027e --- /dev/null +++ b/src/pkg/config/review_require_labels_test.go @@ -0,0 +1,46 @@ +package config + +import "testing" + +func TestReviewConfigAdmitsPRLabels(t *testing.T) { + t.Run("empty gate admits every PR", func(t *testing.T) { + var r ReviewConfig + if !r.AdmitsPRLabels(nil) || !r.AdmitsPRLabels([]string{"anything"}) { + t.Fatal("empty review.require_labels must admit every PR") + } + if r.RequireLabelsEnabled() { + t.Fatal("empty gate must report disabled") + } + }) + t.Run("blank-only list is the empty gate", func(t *testing.T) { + r := ReviewConfig{RequireLabels: []string{" ", ""}} + if r.RequireLabelsEnabled() || !r.AdmitsPRLabels(nil) { + t.Fatal("blank entries must not turn the gate on") + } + }) + t.Run("requires at least one label, case-insensitive exact", func(t *testing.T) { + r := ReviewConfig{RequireLabels: []string{"hive-review", " approved-for-agents "}} + if !r.RequireLabelsEnabled() { + t.Fatal("expected gate on") + } + if r.AdmitsPRLabels(nil) { + t.Fatal("unlabelled PR must be refused") + } + if r.AdmitsPRLabels([]string{"bug", "approved"}) { + t.Fatal("prefix of an approval label must not admit") + } + if !r.AdmitsPRLabels([]string{"bug", "Hive-Review"}) { + t.Fatal("case-insensitive match must admit") + } + if !r.AdmitsPRLabels([]string{"approved-for-agents"}) { + t.Fatal("trimmed configured label must admit") + } + }) + t.Run("normalized drops blanks and duplicates", func(t *testing.T) { + r := ReviewConfig{RequireLabels: []string{"a", " a ", "", "B", "b"}} + got := r.NormalizedRequireLabels() + if len(got) != 2 || got[0] != "a" || got[1] != "B" { + t.Fatalf("unexpected normalized labels: %v", got) + } + }) +} diff --git a/src/pkg/dashboard/api_config_review.go b/src/pkg/dashboard/api_config_review.go index 6964ee228d..84f4c32de8 100644 --- a/src/pkg/dashboard/api_config_review.go +++ b/src/pkg/dashboard/api_config_review.go @@ -117,6 +117,9 @@ func (s *Server) handleReviewConfigPut(w http.ResponseWriter, r *http.Request) { SelfDecisionPolicy *string `json:"self_authored_decision_policy"` ConfidenceScore *bool `json:"confidence_score"` PriorityLabels *bool `json:"priority_labels"` + // RequireLabels replaces review.require_labels whole; an empty list + // turns the PR review label gate off. + RequireLabels *[]string `json:"require_labels"` // VerdictLabels replaces review.verdict_labels whole: its four keys // only mean something together (one label per state), and an empty // object turns the feature off (hivecommons/hive#13833). @@ -519,6 +522,9 @@ func (s *Server) handleReviewConfigPut(w http.ResponseWriter, r *http.Request) { if body.PriorityLabels != nil { cfg.Review.PriorityLabels = *body.PriorityLabels } + if body.RequireLabels != nil { + cfg.Review.RequireLabels = config.ReviewConfig{RequireLabels: *body.RequireLabels}.NormalizedRequireLabels() + } if body.MaxReviewsPerHead != nil { cfg.Review.MaxReviewsPerHead = *body.MaxReviewsPerHead } diff --git a/src/pkg/dashboard/api_config_review_require_labels_test.go b/src/pkg/dashboard/api_config_review_require_labels_test.go new file mode 100644 index 0000000000..396bab830c --- /dev/null +++ b/src/pkg/dashboard/api_config_review_require_labels_test.go @@ -0,0 +1,40 @@ +package dashboard + +import ( + "net/http" + "testing" +) + +// PUT /api/config/review replaces review.require_labels whole, normalizes it, +// and an empty list turns the gate off; an absent key leaves it alone. +func TestReviewConfigPut_RequireLabels(t *testing.T) { + s := covApiServer(t) + + rec := doPut(s, "/api/config/review", map[string]any{"require_labels": []string{" hive-review ", "", "hive-review", "approved-for-agents"}}) + if rec.Code != http.StatusOK { + t.Fatalf("expected 200, got %d: %s", rec.Code, rec.Body.String()) + } + got := s.deps.Config.Review.RequireLabels + if len(got) != 2 || got[0] != "hive-review" || got[1] != "approved-for-agents" { + t.Fatalf("require_labels not normalized: %v", got) + } + + if rec := doPut(s, "/api/config/review", map[string]any{"priority_labels": true}); rec.Code != http.StatusOK { + t.Fatalf("expected 200, got %d", rec.Code) + } + if len(s.deps.Config.Review.RequireLabels) != 2 { + t.Fatalf("absent key must leave require_labels untouched: %v", s.deps.Config.Review.RequireLabels) + } + + if rec := doPut(s, "/api/config/review", map[string]any{"require_labels": []string{}}); rec.Code != http.StatusOK { + t.Fatalf("expected 200, got %d", rec.Code) + } + if s.deps.Config.Review.RequireLabelsEnabled() { + t.Fatalf("empty list must turn the gate off: %v", s.deps.Config.Review.RequireLabels) + } + + get := doGetNoRole(s, "/api/config/review") + if get.Code != http.StatusOK { + t.Fatalf("GET expected 200, got %d", get.Code) + } +} diff --git a/src/pkg/dashboard/static/index.html b/src/pkg/dashboard/static/index.html index a99590e4c7..2794d85c5e 100644 --- a/src/pkg/dashboard/static/index.html +++ b/src/pkg/dashboard/static/index.html @@ -3705,6 +3705,7 @@ .rv-reviewer-row .rv-reviewer-state, .rv-reviewer-list .rv-reviewer-empty { font-size: var(--fs-xs); color: var(--muted); } .rv-reviewer-help { margin: var(--sp-1) var(--sp-0) var(--sp-0); } .rv-reviewer-help-above { margin: var(--sp-0) var(--sp-0) var(--sp-2); } + #rv-require-labels-field[hidden] { display: none; } .am-trusted-authors-repos { min-height: 72px; } .am-bot-empty { color: var(--muted); margin: var(--sp-1) 0; } .am-bot-add { display: flex; gap: var(--sp-3); margin-top: var(--sp-4); align-items: center; } @@ -36927,6 +36928,7 @@