diff --git a/changelog.d/fixed-contributor-lane-review-off.md b/changelog.d/fixed-contributor-lane-review-off.md new file mode 100644 index 0000000000..71d4f58c0a --- /dev/null +++ b/changelog.d/fixed-contributor-lane-review-off.md @@ -0,0 +1 @@ +- A contributor-lane PR on a hive whose review swarm is off no longer waits at `050-review-pending` forever. `auto_merge.contributor_lane.require_reviewer_verdict` (default on) wanted a reviewer verdict whenever a reviewer agent existed, but the review planner only asks reviewers when `review.require_approval` and `review.fan_out` are both on. On a self-hosted spoke with the swarm off, twelve green docs PRs sat at "Review swarm requested; waiting for a verdict" with the Review track reading "0/5 · in progress" and nothing dispatched. Such a head now skips as `contributor-lane:review-off` and parks at `085-needs-decision` with that cause, and the Activity Monitor's Review track says a person must review instead of "in progress". diff --git a/src/cmd/hive/contributor_lane_wiring_test.go b/src/cmd/hive/contributor_lane_wiring_test.go index 0b77924a60..ad03be8ffe 100644 --- a/src/cmd/hive/contributor_lane_wiring_test.go +++ b/src/cmd/hive/contributor_lane_wiring_test.go @@ -101,6 +101,47 @@ func TestContributorLaneVerdictFunc(t *testing.T) { } } +// A reviewer agent with the review swarm off (review.require_approval or +// review.fan_out unset) never produces a verdict: the planner only plans +// maintainer-answered heads. The gate must say so (ReviewOff) instead of +// reading as a verdict on its way (hive-wild-mole, Danathar/sensi#681). +func TestContributorLaneVerdictFuncReviewSwarmOff(t *testing.T) { + orig := review.ReviewVerdictsPath + review.ReviewVerdictsPath = filepath.Join(t.TempDir(), "verdicts", review.ReviewVerdictsFile) + defer func() { review.ReviewVerdictsPath = orig }() + + cfg := &config.Config{AgentRuntimeConfig: config.AgentRuntimeConfig{Agents: map[string]config.AgentConfig{"reviewer": {Enabled: true, Role: "reviewer"}}}} + if v := contributorLaneVerdictFunc(cfg, nil)("acme/widget", 7, "sha7"); !v.Configured || v.Approved || !v.ReviewOff { + t.Fatalf("swarm off, no artifact: %+v, want Configured and ReviewOff", v) + } + artifact := review.Artifact{Items: []review.Aggregate{ + {Repo: "acme/widget", Number: 8, HeadSHA: "sha8", Verdict: review.VerdictChangesRequested}, + }} + if err := review.WriteArtifact(review.ReviewVerdictsPath, artifact); err != nil { + t.Fatal(err) + } + if v := contributorLaneVerdictFunc(cfg, nil)("acme/widget", 7, "sha7"); !v.ReviewOff { + t.Fatalf("swarm off, unreviewed head: %+v, want ReviewOff", v) + } + if v := contributorLaneVerdictFunc(cfg, nil)("acme/widget", 8, "sha8"); v.ReviewOff || v.Verdict != string(review.VerdictChangesRequested) { + t.Fatalf("swarm off, recorded verdict: %+v, want the verdict and no ReviewOff", v) + } + for _, tc := range []struct { + name string + requireApproval, fanOut bool + wantOff bool + }{ + {"fan_out alone", false, true, true}, + {"require_approval alone", true, false, true}, + {"both on", true, true, false}, + } { + cfg.Review.RequireApproval, cfg.Review.FanOut = tc.requireApproval, tc.fanOut + if v := contributorLaneVerdictFunc(cfg, nil)("acme/widget", 7, "sha7"); v.ReviewOff != tc.wantOff { + t.Fatalf("%s: ReviewOff = %v, want %v", tc.name, v.ReviewOff, tc.wantOff) + } + } +} + func TestContributorLaneVerdictFromArtifactNormalizesLegacyRequiresHuman(t *testing.T) { artifact := review.Artifact{Items: []review.Aggregate{{ Repo: "acme/widget", diff --git a/src/cmd/hive/merge_eligibility.go b/src/cmd/hive/merge_eligibility.go index 3ccd75ac69..b183b58a12 100644 --- a/src/cmd/hive/merge_eligibility.go +++ b/src/cmd/hive/merge_eligibility.go @@ -213,24 +213,42 @@ func contributorLaneReviewerConfigured(cfg *config.Config) bool { return false } +// contributorLaneReviewDispatched reports whether the review planner asks +// reviewers for new heads at all. It mirrors planReviewDispatchWith's +// answeredOnly rule: with review.require_approval or review.fan_out off the +// planner hands out only maintainer-answered fix work, never a review. +func contributorLaneReviewDispatched(cfg *config.Config) bool { + return cfg != nil && cfg.Review.RequireApproval && cfg.Review.FanOut +} + // contributorLaneVerdictFunc answers the contributor-lane reviewer gate from // the same durable review-verdicts.json the merge-eligibility gate reads // (review.Artifact.HasAggregateApproval). An unreadable artifact with a -// reviewer configured fails closed: Configured=true, Approved=false. +// reviewer configured fails closed: Configured=true, Approved=false. A head +// with no aggregate on a hive that never dispatches the review swarm is +// marked ReviewOff: no verdict is on its way, and the lane says so +// (contributor-lane:review-off) instead of waiting at no-verdict forever. func contributorLaneVerdictFunc(cfg *config.Config, logger *slog.Logger) automerge.ContributorLaneVerdictFunc { return func(repo string, number int, headSHA string) automerge.ContributorLaneVerdict { if !contributorLaneReviewerConfigured(cfg) { return automerge.ContributorLaneVerdict{} } + reviewOff := !contributorLaneReviewDispatched(cfg) artifact, err := review.LoadArtifact("") if err != nil { - if logger != nil && !errors.Is(err, os.ErrNotExist) { + if errors.Is(err, os.ErrNotExist) { + // Nothing was ever reviewed: no verdict for this head either. + return automerge.ContributorLaneVerdict{Configured: true, ReviewOff: reviewOff} + } + if logger != nil { logger.Warn("contributor-lane verdict gate: review-verdicts.json unavailable; failing closed", "error", err) } return automerge.ContributorLaneVerdict{Configured: true} } approved := artifact.HasAggregateApproval(repo, number, headSHA) - return contributorLaneVerdictFromArtifact(artifact, repo, number, headSHA, approved) + v := contributorLaneVerdictFromArtifact(artifact, repo, number, headSHA, approved) + v.ReviewOff = reviewOff && !approved && strings.TrimSpace(v.Verdict) == "" + return v } } diff --git a/src/docs/adr/0025-central-stage-engine.md b/src/docs/adr/0025-central-stage-engine.md index b2fc7466b2..7abf97347b 100644 --- a/src/docs/adr/0025-central-stage-engine.md +++ b/src/docs/adr/0025-central-stage-engine.md @@ -55,11 +55,11 @@ hub read that store and nothing else (`stageStoreOrShared`, (`src/pkg/github/automerge/automerge_stage_labels.go:365`), observations are sorted by `stageLanePrecedence` (self 3 > trusted 2 > contributor 1, `src/pkg/github/automerge/automerge_stage_labels.go:177`), each is classified - by `ClassifyStage` (`src/pkg/stageengine/derive_pr_classify.go:342`) + by `ClassifyStage` (`src/pkg/stageengine/derive_pr_classify.go:344`) into a ranked opinion (`prstage.RankNone..prstage.RankOwned`, `src/pkg/stageengine/prstage/types.go:145-148`), and `ResolveStage` picks the winner - (`src/pkg/stageengine/derive_pr_classify.go:718`). These PR helpers now + (`src/pkg/stageengine/derive_pr_classify.go:720`). These PR helpers now live in the engine (#13779); automerge keeps only gathering-side previews. Shared concepts — parking (045/085, `needs-human`, hold labels), author kind (070/071/072), adoption (074), terminal states, `origin/*` — are modelled twice with diff --git a/src/docs/dashboard-sections/activity-monitor.md b/src/docs/dashboard-sections/activity-monitor.md index 62e306316f..a9d0a0693e 100644 --- a/src/docs/dashboard-sections/activity-monitor.md +++ b/src/docs/dashboard-sections/activity-monitor.md @@ -446,7 +446,7 @@ An *active* chevron is filled amber and carries words; an inactive one is its ic 2. **CI and Review resolve first.** A track is active only while it genuinely runs on the current head (a check-run in progress or queued, a ring not yet full; a reviewer running or queued). If either runs, the PR is waiting on it: the stage chevron (PR in progress, Merge queue …) renders settled-current — filled but still, icon only, its words in the tooltip — and nothing else is active. 3. **CI + Review is the only pair.** Two chevrons are active together only when both tracks run at once; every other combination is exactly one active chevron. The stage chevron is the ≥ 1 fallback: active only when no track is in motion. 4. **The PR in progress chevron speaks the PR's lifecycle** — draft, pushed, rebasing, *Unassigned · next: scanner*, *Waiting for @author · fix owed* — never a CI or review verdict. *CI failing*, *CI 4/11 · 1 failing* and *changes requested* are the CI and Review chevrons' words; the PR in progress tooltip keeps the red reason as detail. -5. **The CI and Review tooltips state what the track waits on — never "activity unknown".** With no verdict and no reviewer in flight the spoke derives the Review statement from what it already knows, in this order: the PR is merged or closed (*Review · n/a (closed)*), it is a draft (*Review · draft, not requested*), CI on the head has not finished (*Review · waiting for CI*), CI is done and nobody started (*Review · not started · hive reviewer next*, or *· needs reviewer* when the repo has no hive reviewer lane). A settled verdict explains itself — *Changes requested by the hive reviewer: 1 perspective posted findings … · 12m ago · quality ✓ · security ✗: token logged* — and stays known as its observation ages. The one no-data wording, *Review · no data for head f269349 yet · refreshing* (CI: *CI · no checks observed for head … yet · refreshing*), appears only when the spoke has fetched nothing for the head, and names the next step. +5. **The CI and Review tooltips state what the track waits on — never "activity unknown".** With no verdict and no reviewer in flight the spoke derives the Review statement from what it already knows, in this order: the PR is merged or closed (*Review · n/a (closed)*), it is a draft (*Review · draft, not requested*), CI on the head has not finished (*Review · waiting for CI*), CI is done and nobody started (*Review · not started · hive reviewer next*, or *· needs reviewer* when the repo has no hive reviewer lane or the review swarm is off). A 050 row reads *Review 0/5 · in progress* only on a hive that dispatches reviewers; with the swarm off it falls through to these statements. A settled verdict explains itself — *Changes requested by the hive reviewer: 1 perspective posted findings … · 12m ago · quality ✓ · security ✗: token logged* — and stays known as its observation ages. The one no-data wording, *Review · no data for head f269349 yet · refreshing* (CI: *CI · no checks observed for head … yet · refreshing*), appears only when the spoke has fetched nothing for the head, and names the next step. #### The row's lead action, inline diff --git a/src/docs/hive-merge.md b/src/docs/hive-merge.md index caac5ad845..b787096825 100644 --- a/src/docs/hive-merge.md +++ b/src/docs/hive-merge.md @@ -1058,7 +1058,12 @@ A PR merges through this tier only when all of the following hold: the tier never merges unreviewed), and `review-verdicts.json` records an approving aggregate verdict for the current head (`require_reviewer_verdict`, default `true`). Missing or failing verdicts - skip with `contributor-lane:no-verdict`. A `requires_human` verdict a + skip with `contributor-lane:no-verdict`. On a hive whose review swarm is + off (`review.require_approval` or `review.fan_out` unset), no reviewer is + ever asked, so a head with no verdict skips with + `contributor-lane:review-off` instead and parks at + `085-needs-decision`: a person merges it, or the owner turns the swarm on + or `require_reviewer_verdict` off. A `requires_human` verdict a trusted merger answered on the head clears this gate; on a PR no diff fence trips, the lane itself records a trusted merger's typed `/hive decision approve` posted after the head as that answer (the same diff --git a/src/docs/labels-and-control-signals/stage-labels.md b/src/docs/labels-and-control-signals/stage-labels.md index abdcca3788..4f149992ac 100644 --- a/src/docs/labels-and-control-signals/stage-labels.md +++ b/src/docs/labels-and-control-signals/stage-labels.md @@ -395,7 +395,7 @@ used to admit the PR: | CI red (required or optional) while **every** failing check on the head is also red on the base branch's tip — the governor's `base_red_checks` / `base_red`, set during CI enrichment when a same-named latest check run on the base ref (meta checks excluded) concluded failure / timed_out / cancelled / action_required / startup_failure / stale **and** the PR's changed files include none of `.github/workflows/*`, `Dockerfile` / `Dockerfile.*` / `*.Dockerfile`, `go.mod` / `go.sum` (a PR touching those plausibly owns the check and stays author-facing; a lookup error or a diff beyond the file-list page budget also stays author-facing) | `050-review-pending` / `060-reviewed`, reason `base-branch-red:,` ("waiting for the base branch's CI to recover (…) — not this PR's fault"): never 070/071/072, never nudged (a 072 nudge already posted for the head is edited in place to say it was withdrawn), never stalled, still not merged (the lane's skip reason is the same token). The fix loop counts no attempt, kicks no fixer, and posts one `` hold comment per head; an escalation the hive itself raised (ledger `label_applied`) over such a head has its `needs-human` removed with the hold wording. The next evaluation after the base goes green re-evaluates the head: a still-red PR is handed back as usual. Conflicts and requested changes stay author-facing (seen on [#13270](https://github.com/hivecommons/hive/pull/13270) and [#13258](https://github.com/hivecommons/hive/pull/13258), 2026-10-20) | | CI red (required or optional) on a **fork** PR while **every** failing check's annotation says the check refuses forks (case-insensitive `fork pull request(s) cannot`, `maintainer must push this branch`, or `cannot publish` together with `fork` — a fork-publication / fork-secrets guard) | `085-needs-decision`, reason `fork-guard:,`: never 070/071/072, never nudged, never adopted (074) — neither the author nor the hive can turn the check green by pushing to the fork. The entry comment names the check and says a maintainer must push the branch to the repository (or run or approve it for head `` as the repository requires). A new head on the same fork PR (a merge of the base, or the author's push) keeps the guard while the lane's red check is one of the recorded `fork-guard:` checks, so the PR does not drop to 072 and nobody is nudged before the annotation for that head is read. The hive also does not update the branch of a fork head that waits on a fork-guarded check: the run a maintainer dispatches proves one exact head, and a merge of the base would discard it. Once the check is green the guard drops and updates resume before merge. A same-repo PR with the same message, or a fork PR with any other red check, is handed back as usual ([#14273](https://github.com/hivecommons/hive/issues/14273), projectbluefin/utah-packages#862 and #869) | | any **non-required** check on the current head is red, whatever the lane's reason (the lane gates on required checks only, so it still soaks and merges; a reader of the rollup sees ✗). Parking modifiers (`hold`, `needs-human`, admission reasons) still win | `070-fixing` / `071-needs-author` / `072-returned-to-contributor` (by author kind), reason `optional-check-failing:` (the nudge lists every red check); never 080 or 100. A red *required* check is the lane's own `required-check-failing:*` → 070/071/072 ([#12538](https://github.com/hivecommons/hive/issues/12538), seen on [#12457](https://github.com/hivecommons/hive/pull/12457)) | -| `label:hold`, `held`, `label:needs-human`, `exempt-label`, `excluded-label:*`, `sentinel`, `human-merge-path*`, `intent-*`, `contributor-lane:workflow-path` / `tests-removed` / `no-reviewer` / `reporter-trust-hold`, `workflow-permission` (GitHub refused update-branch or the merge-forward with a 403 because the base changed `.github/workflows/` and the token the hive used lacks the workflows permission; no token the hive holds can push that update, so it is not sent to 070), `fork-workflow-update` (the same update-branch refusal on a fork head: the App is not installed on the fork, so no grant lets it push there), `linked-issue:hold:#N: