From 35e4f56453e554be18f8ffd4013fc7e7cb06e20c Mon Sep 17 00:00:00 2001 From: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com> Date: Wed, 28 Oct 2026 15:17:14 -0400 Subject: [PATCH 1/2] =?UTF-8?q?=E2=9C=A8=20feat(review):=20run=20combined?= =?UTF-8?q?=20review=20heads=20as=20one=20kick=20per=20head?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Under review.combined_perspectives the planner dropped review_heads, so a hive that wanted several independent models had to run split perspectives and pay heads x perspectives record-only kicks per PR head (10 with two heads and five perspectives) plus the decision kick. Every one re-read the same diff, and review latency and spend scaled with the perspective count instead of the number of independent opinions. With combined perspectives each head now gets one record-only kick carrying every perspective it still owes, using the combined prompt body, and records a JSON array of per-perspective verdicts. Pending entries stay one per (perspective, head), so settling, expiry, head_max_retries, re-asking only the missing perspectives and the decision step are unchanged. Heads are expected by the aggregate in both modes, and the mixed-reviewer-set check now applies in both modes since head dispatch leaves nothing for a plain lane either way. Closes #15058 Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com> Co-authored-by: gregoryhunt <31053269+gregoryhunt@users.noreply.github.com> --- .../added-15058-combined-review-heads.md | 1 + src/docs/review-swarm.md | 6 +- src/pkg/config/review_heads.go | 27 ++-- src/pkg/config/review_heads_test.go | 23 ++-- src/pkg/review/dispatch.go | 2 +- src/pkg/review/prompts.go | 7 +- src/pkg/review/review_heads.go | 86 +++++++++--- src/pkg/review/review_heads_test.go | 123 +++++++++++++++++- 8 files changed, 228 insertions(+), 47 deletions(-) create mode 100644 changelog.d/added-15058-combined-review-heads.md diff --git a/changelog.d/added-15058-combined-review-heads.md b/changelog.d/added-15058-combined-review-heads.md new file mode 100644 index 0000000000..806eecad0a --- /dev/null +++ b/changelog.d/added-15058-combined-review-heads.md @@ -0,0 +1 @@ +- Review heads (`agents..review_heads`) now work with `review.combined_perspectives: true`: each head reviews every perspective in one record-only kick per PR head instead of one kick per perspective, and config load now rejects a reviewer set that mixes lanes with and without heads in combined mode too. diff --git a/src/docs/review-swarm.md b/src/docs/review-swarm.md index 78abeda18f..738caf4b0a 100644 --- a/src/docs/review-swarm.md +++ b/src/docs/review-swarm.md @@ -418,9 +418,11 @@ review: reviewer_agents: [code-reviewer] # naming the base admits its heads ``` -With split perspectives, every perspective is dispatched once per head, to a replica of that head with no review kick in flight (see *One kick in flight per agent* below); the base and its plain `replicas` are not dispatched (they are reserved for the decision step). Because head dispatch asks every perspective of every head, a reviewer lane *without* `review_heads` alongside one with them would have nothing left to review, so config load rejects that mix under `combined_perspectives: false`: every admitted reviewer (the `reviewer_agents` list, or every agent carrying the `review` token when the list is empty) must declare `review_heads`, or be left out. Only heads of admitted bases are expected by the aggregate. Each kick costs one `max_parallel_reviews` slot, and `max_perspectives_per_pr` still bounds how many perspectives a PR head receives. A head reviews **blind** (it is told not to read other reviews of this head) and **records only**: it delivers its verdict with `hive-review --record-verdict` and posts nothing on the PR. The relay stamps each verdict with the head from the dispatch record it bound to (an advisory verdict with no dispatch row carries none) and keeps one report per perspective per head; `review_model` is stamped per head, so each head's report names the model that head ran. +With split perspectives, every perspective is dispatched once per head, to a replica of that head with no review kick in flight (see *One kick in flight per agent* below); the base and its plain `replicas` are not dispatched (they are reserved for the decision step). Because head dispatch asks every perspective of every head, a reviewer lane *without* `review_heads` alongside one with them would have nothing left to review, so config load rejects that mix (split or combined): every admitted reviewer (the `reviewer_agents` list, or every agent carrying the `review` token when the list is empty) must declare `review_heads`, or be left out. Only heads of admitted bases are expected by the aggregate. Each kick costs one `max_parallel_reviews` slot, and `max_perspectives_per_pr` still bounds how many perspectives a PR head receives. A head reviews **blind** (it is told not to read other reviews of this head) and **records only**: it delivers its verdict with `hive-review --record-verdict` and posts nothing on the PR. The relay stamps each verdict with the head from the dispatch record it bound to (an advisory verdict with no dispatch row carries none) and keeps one report per perspective per head; `review_model` is stamped per head, so each head's report names the model that head ran. -Heads have no `review_models` pool of their own (the head is the model) and are not used under `combined_perspectives: true`, where the base reviews as before. +Heads have no `review_models` pool of their own (the head is the model). + +**Combined heads.** Under `combined_perspectives: true` ([#15058](https://github.com/hivecommons/hive/issues/15058)) each head gets **one** record-only kick per PR head carrying every perspective it still owes, instead of one kick per (perspective, head): with 2 heads and 5 perspectives a PR costs 2 head kicks plus the decision rather than 10 plus the decision, and each model reads the diff once. The head records one JSON array with a verdict per perspective through a single `hive-review --record-verdict`; pending entries stay one per (perspective, head), so settling, expiry and `head_max_retries` work per pair, and a head that answers only some perspectives is re-asked for the rest only. As with any combined review, `max_perspectives_per_pr` does not apply and the kick costs one `max_parallel_reviews` slot. The decision step is unchanged. ### The decision step diff --git a/src/pkg/config/review_heads.go b/src/pkg/config/review_heads.go index dd9230c8e1..570f221c6d 100644 --- a/src/pkg/config/review_heads.go +++ b/src/pkg/config/review_heads.go @@ -146,13 +146,13 @@ func (c *Config) dispatchedReviewerBases() []string { // ExpectedReviewHeads lists every head key the swarm dispatches each // perspective to: the review_heads of every enabled base agent the -// dispatcher admits as a reviewer, sorted, when perspectives are split. A -// base review.reviewer_agents does not name is not dispatched, so its heads -// are not expected either, and an all-approve aggregate never waits on -// them. Empty under combined_perspectives (heads are not used there) or -// when no admitted agent declares heads. +// dispatcher admits as a reviewer, sorted, with split and combined +// perspectives alike (hivecommons/hive#15058). A base review.reviewer_agents +// does not name is not dispatched, so its heads are not expected either, and +// an all-approve aggregate never waits on them. Empty when no admitted agent +// declares heads. func (c *Config) ExpectedReviewHeads() []string { - if c == nil || c.Review.CombinedPerspectives { + if c == nil { return nil } var keys []string @@ -173,11 +173,11 @@ func (r ReviewConfig) EffectiveHeadMaxRetries() int { } // validateReviewHeads checks each head's backend is one the governor can -// launch, review.head_max_retries is not negative, and that with split -// perspectives the admitted reviewers either all declare review_heads or -// none do. Head dispatch asks every perspective of every head and leaves -// nothing for a plain reviewer lane alongside them, so a mixed set would -// silently idle the lanes without heads (hivecommons/hive#13542). Structural +// launch, review.head_max_retries is not negative, and that the admitted +// reviewers either all declare review_heads or none do. Head dispatch asks +// every perspective of every head, split or combined (hivecommons/hive#15058), +// and leaves nothing for a plain reviewer lane alongside them, so a mixed set +// would silently idle the lanes without heads (hivecommons/hive#13542). Structural // checks (required fields, aliases, replicas, name collisions) run where the // heads are expanded, so a bad head fails config load the same way a bad // replicas value does. @@ -197,9 +197,6 @@ func (c *Config) validateReviewHeads() error { } } } - if c.Review.CombinedPerspectives { - return nil - } var withHeads, without []string for _, name := range c.dispatchedReviewerBases() { if len(c.Agents[name].ReviewHeads) > 0 { @@ -209,7 +206,7 @@ func (c *Config) validateReviewHeads() error { } } if len(withHeads) > 0 && len(without) > 0 { - return fmt.Errorf("review_heads: with review.combined_perspectives: false every reviewer must declare review_heads: %s do, %s do not; add review_heads to them or leave them out of review.reviewer_agents", + return fmt.Errorf("review_heads: every reviewer must declare review_heads: %s do, %s do not; add review_heads to them or leave them out of review.reviewer_agents", strings.Join(withHeads, ", "), strings.Join(without, ", ")) } return nil diff --git a/src/pkg/config/review_heads_test.go b/src/pkg/config/review_heads_test.go index c81da6c42b..d9d50c566b 100644 --- a/src/pkg/config/review_heads_test.go +++ b/src/pkg/config/review_heads_test.go @@ -170,9 +170,11 @@ func TestExpectedReviewHeadsFollowReviewerAdmission(t *testing.T) { if got := cfg.ExpectedReviewHeads(); len(got) != 3 { t.Fatalf("without reviewer_agents every reviewer base's heads are expected, got %v", got) } + // Combined perspectives dispatch one kick per head (#15058), so the + // heads are expected there too. cfg.Review.CombinedPerspectives = true - if got := cfg.ExpectedReviewHeads(); got != nil { - t.Fatalf("combined perspectives expect heads: %v", got) + if got := cfg.ExpectedReviewHeads(); len(got) != 3 { + t.Fatalf("combined perspectives must expect every head, got %v", got) } } @@ -187,20 +189,23 @@ func TestReviewHeadsRejectMixedReviewerSet(t *testing.T) { if err == nil || !strings.Contains(err.Error(), "security-reviewer do not") { t.Fatalf("mixed reviewers accepted: %v", err) } - // Leaving the plain lane out of reviewer_agents, or running combined - // perspectives (heads unused), is fine. + // Combined perspectives dispatch heads too (#15058), so the mix is + // rejected there as well. + cfg.Review.CombinedPerspectives = true + if err := cfg.validateReviewHeads(); err == nil { + t.Fatal("mixed reviewers accepted under combined perspectives") + } + // Leaving the plain lane out of reviewer_agents is fine in either mode. cfg.Review.ReviewerAgents = []string{"code-reviewer"} if err := cfg.validateReviewHeads(); err != nil { - t.Fatalf("heads-only reviewer set rejected: %v", err) + t.Fatalf("heads-only reviewer set rejected under combined perspectives: %v", err) } - cfg.Review.ReviewerAgents = []string{"code-reviewer", "security-reviewer"} - cfg.Review.CombinedPerspectives = true + cfg.Review.CombinedPerspectives = false if err := cfg.validateReviewHeads(); err != nil { - t.Fatalf("combined perspectives rejected: %v", err) + t.Fatalf("heads-only reviewer set rejected: %v", err) } // Without reviewer_agents the review token decides: a plain lane whose // name carries it is still a mixed set. - cfg.Review.CombinedPerspectives = false cfg.Review.ReviewerAgents = nil if err := cfg.validateReviewHeads(); err == nil { t.Fatal("mixed reviewers by review token accepted") diff --git a/src/pkg/review/dispatch.go b/src/pkg/review/dispatch.go index 116d04010a..a3b6e00f67 100644 --- a/src/pkg/review/dispatch.go +++ b/src/pkg/review/dispatch.go @@ -626,7 +626,7 @@ func PlanDispatch(prs []PullRequest, artifact Artifact, state DispatchState, opt return plan } capable := reviewCapableAgents(opts) - heads, reviewers := dispatchReviewers(capable, opts.CombinedPerspectives) + heads, reviewers := dispatchReviewers(capable) headsMode := len(heads) > 0 maxParallel := opts.MaxParallelReviews if maxParallel <= 0 { diff --git a/src/pkg/review/prompts.go b/src/pkg/review/prompts.go index ef45a6694a..85edffc089 100644 --- a/src/pkg/review/prompts.go +++ b/src/pkg/review/prompts.go @@ -650,7 +650,12 @@ func BuildCombinedPrompt(pr PullRequest, perspectives []Perspective, opts Prompt b.WriteString(permissionsTighteningGuidance) b.WriteString("A Hive-authored incomplete fix with concrete remediation is changes_requested, not requires_human. If there are two engineering remedies (for example, add producer code OR reword a changelog), choose the best route yourself and state it as the requested change; do not escalate the choice to a human unless it falls into one of the risk categories above. Intent-alignment cleanup such as trimming a PR summary or changelog fragment that duplicates already-landed work is also changes_requested when the remediation is concrete.\n") b.WriteString("A perspective you could not meaningfully assess is requires_human, not approve. Approving a perspective you did not actually consider is the one failure mode that makes this whole review worthless, because it is indistinguishable from having considered it.\n") - if opts.PostComments { + if head := strings.TrimSpace(opts.HeadRecordOnly); head != "" { + // A combined review head (hivecommons/hive#15058): every perspective + // in one pass, recorded as one array, posted nowhere. + b.WriteString(buildHeadRecordOnlyInstruction(pr, head)) + fmt.Fprintf(&b, "The verdict file carries all %d verdicts as ONE JSON array, including the clean ones, recorded with a single --record-verdict call. A perspective missing from the array is dispatched to you again.\n", len(perspectives)) + } else if opts.PostComments { b.WriteString(buildCombinedPublishInstruction(pr, perspectives, opts)) } b.WriteString(buildProposeOnlyInstruction(pr, opts)) diff --git a/src/pkg/review/review_heads.go b/src/pkg/review/review_heads.go index 20c57d4ddd..f8bcfebf27 100644 --- a/src/pkg/review/review_heads.go +++ b/src/pkg/review/review_heads.go @@ -7,29 +7,31 @@ import ( "time" ) -// Review heads (hivecommons/hive#13542): with split perspectives, a base -// reviewer's agents..review_heads each review every perspective, so two -// or more models judge the same perspective independently. This file holds -// the planner side: choosing the head reviewers, working out which -// (perspective, head) pairs a PR head still needs, and planning one -// record-only kick per pair. +// Review heads (hivecommons/hive#13542): a base reviewer's +// agents..review_heads each review every perspective, so two or more +// models judge the same perspective independently. This file holds the +// planner side: choosing the head reviewers, working out which +// (perspective, head) pairs a PR head still needs, and planning record-only +// kicks for them: one per pair with split perspectives, one per head carrying +// all of that head's missing pairs under combined perspectives +// (hivecommons/hive#15058). // dispatchReviewers splits the review-capable agents into the heads this // cycle dispatches to and the plain reviewers that follow the ordinary path. -// Agents derived from review_heads only review with split perspectives -// (combined_perspectives off); there the bases that declare them, and those -// bases' plain replicas, are left for the decision step and every other -// reviewer stays on the ordinary path, so a lane without heads is never -// silently dropped (config.validateReviewHeads rejects such a mix, since -// head dispatch leaves it nothing to review). Under combined perspectives -// heads are dropped and every other reviewer works exactly as before. -func dispatchReviewers(reviewers []AgentCapability, combined bool) (heads, others []AgentCapability) { +// Agents derived from review_heads are heads with split and combined +// perspectives alike; the bases that declare them, and those bases' plain +// replicas, are left for the decision step and every other reviewer stays on +// the ordinary path, so a lane without heads is never silently dropped +// (config.validateReviewHeads rejects such a mix, since head dispatch leaves +// it nothing to review). Combined perspectives only change how many kicks a +// head gets per PR head (dispatchHeads), not who reviews. +func dispatchReviewers(reviewers []AgentCapability) (heads, others []AgentCapability) { declaring := map[string]bool{} for _, r := range reviewers { if r.HasReviewHeads { declaring[r.Name] = true } - if r.ReviewHead != "" && !combined { + if r.ReviewHead != "" { heads = append(heads, r) } } @@ -129,6 +131,16 @@ func pendingMissingHeadPerspectives(state DispatchState, pr PullRequest, perspec // bounds how many perspectives a PR head receives; an admitted perspective is // asked of every head so it is judged by all of them. // +// Under combined perspectives (hivecommons/hive#15058) each head instead gets +// ONE kick carrying every perspective it still owes, so a PR costs one kick +// per head rather than heads × perspectives, and each model reads the diff +// once. The head records a JSON array with one verdict per perspective, and +// the pending entries stay one per (perspective, head), so settling, expiry, +// head_max_retries and the decision step work per pair exactly as with split +// perspectives: a head that answers only some perspectives is re-asked for +// the rest. As with any combined review, max_perspectives_per_pr does not +// apply, and the kick costs one slot. +// // Heads run with their own backend and model, so no review_models pool or // perspective_models override applies: the head IS the model. func (p *DispatchPlan) dispatchHeads(pr PullRequest, reviewers []AgentCapability, opts DispatchOptions, delivered map[Perspective]Verdict, deliveredHeads map[Perspective][]string, revisiting bool, delta *DeltaContext, availableSlots int, now time.Time) int { @@ -137,6 +149,9 @@ func (p *DispatchPlan) dispatchHeads(pr PullRequest, reviewers []AgentCapability return availableSlots } missing := pendingMissingHeadPerspectives(p.State, pr, opts.Perspectives.List(), keys, delivered, deliveredHeads) + if opts.CombinedPerspectives { + return p.dispatchCombinedHeads(pr, keys, groups, missing, opts, revisiting, delta, availableSlots, now) + } if perPR := opts.effectiveMaxPerspectivesPerPR(); perPR > 0 { admitted := map[Perspective]bool{} for _, e := range p.State.Pending { @@ -188,6 +203,47 @@ func (p *DispatchPlan) dispatchHeads(pr PullRequest, reviewers []AgentCapability return availableSlots } +// dispatchCombinedHeads is dispatchHeads under combined perspectives: one +// record-only kick per head with a free replica, carrying every missing +// perspective of that head, and one pending entry per (perspective, head). +func (p *DispatchPlan) dispatchCombinedHeads(pr PullRequest, keys []string, groups map[string][]AgentCapability, missing []headPerspective, opts DispatchOptions, revisiting bool, delta *DeltaContext, availableSlots int, now time.Time) int { + byHead := map[string][]Perspective{} + for _, m := range missing { + byHead[m.Head] = append(byHead[m.Head], m.Perspective) + } + for _, head := range keys { + perspectives := byHead[head] + if len(perspectives) == 0 { + continue + } + if availableSlots <= 0 { + break + } + reviewer, free := freeReviewer(groups[head], p.inFlight(opts, now)) + if !free { + continue + } + msg := BuildCombinedPrompt(pr, perspectives, PromptOptions{ + HeadRecordOnly: head, + Revise: revisiting, + Perspectives: opts.Perspectives, + ProposeFixesOnly: !fixPushAllowed(pr, opts), + WritingGuideSection: opts.WritingGuideSection, + ReviewBotLogins: opts.ReviewBotLogins, + ReviewBotMinPriority: opts.ReviewBotMinPriority, + ReviewBackend: reviewer.Backend, + ReviewModel: reviewer.Model, + Delta: delta, + }) + p.ReviewKicks = append(p.ReviewKicks, DispatchKick{Agent: reviewer.Name, Message: msg, PRRef: fmt.Sprintf("%s#%d", pr.Repo, pr.Number), Kind: "review", Repo: pr.Repo, Number: pr.Number, HeadSHA: pr.HeadSHA, BodyDigest: pr.BodyDigest, Perspective: perspectives[0], Perspectives: perspectives, Head: head, AuthorAgent: pr.AuthorAgent, AuthorModel: pr.AuthorModel, ReviewBackend: reviewer.Backend, ReviewModel: reviewer.Model, DeltaPreviousHead: deltaPreviousHead(delta)}) + for _, persp := range perspectives { + p.State.Pending = append(p.State.Pending, PendingReview{Repo: pr.Repo, Number: pr.Number, HeadSHA: pr.HeadSHA, BodyDigest: pr.BodyDigest, Perspective: persp, Agent: reviewer.Name, Head: head, AuthorAgent: pr.AuthorAgent, AuthorModel: pr.AuthorModel, ReviewModel: strings.TrimSpace(reviewer.Model), DeltaPreviousHead: deltaPreviousHead(delta), Dispatched: now}) + } + availableSlots-- + } + return availableSlots +} + // removePendingForPerspectivesAndHeads is removePendingForPerspectives for a // head-aware aggregate: a head's pending entry is dropped only once that head // has reported the perspective, so the other heads' entries keep their TTL. diff --git a/src/pkg/review/review_heads_test.go b/src/pkg/review/review_heads_test.go index 476540c7bf..bd72f6a6bf 100644 --- a/src/pkg/review/review_heads_test.go +++ b/src/pkg/review/review_heads_test.go @@ -251,12 +251,127 @@ func TestNoHeadsKeepsTodaysDispatch(t *testing.T) { } } -func TestCombinedModeIgnoresHeads(t *testing.T) { +// Combined heads (hivecommons/hive#15058): one record-only kick per head +// carrying every perspective it owes, not one per (perspective, head), with +// the pending entries still kept per pair. +func TestCombinedHeadsDispatchOneKickPerHead(t *testing.T) { opts := headsOpts() opts.CombinedPerspectives = true plan := PlanDispatch([]PullRequest{dispatchPR("sha1")}, Artifact{}, DispatchState{}, opts) - if len(plan.ReviewKicks) != 1 || plan.ReviewKicks[0].Agent != "cr" || plan.ReviewKicks[0].Head != "" { - t.Fatalf("combined kicks = %+v, want one combined kick to the base", plan.ReviewKicks) + if len(plan.ReviewKicks) != 2 { + t.Fatalf("kicks = %+v, want one per head", plan.ReviewKicks) + } + heads := map[string]bool{} + for _, k := range plan.ReviewKicks { + if k.Agent == "cr" || k.Head == "" || !strings.HasPrefix(k.Agent, k.Head+"-") { + t.Fatalf("combined head kick went to the wrong agent: %+v", k) + } + heads[k.Head] = true + if len(k.Perspectives) != 2 || k.Perspectives[0] != PerspectiveCorrectness || k.Perspectives[1] != PerspectiveSecurity { + t.Fatalf("kick for %s carries %v, want every perspective", k.Head, k.Perspectives) + } + for _, want := range []string{ + "[review-perspective:correctness,security]", + "INDEPENDENT REVIEW HEAD (" + k.Head + ")", + "--record-verdict --verdict-file ", + "ONE JSON array", + "Do NOT post anything on the PR", + } { + if !strings.Contains(k.Message, want) { + t.Errorf("combined head kick missing %q", want) + } + } + if strings.Contains(k.Message, "--comment --body-file") || strings.Contains(k.Message, "ONE COMMENT, EVERY PERSPECTIVE") { + t.Fatalf("combined head kick tells the head to post a comment:\n%s", k.Message) + } + } + if !heads["cr-sol"] || !heads["cr-sonnet"] { + t.Fatalf("heads kicked = %v, want cr-sol and cr-sonnet", heads) + } + pairs := map[string]bool{} + for _, p := range plan.State.Pending { + pairs[string(p.Perspective)+"/"+p.Head] = true + } + if len(plan.State.Pending) != 4 || len(pairs) != 4 { + t.Fatalf("pending = %+v, want one entry per (perspective, head)", plan.State.Pending) + } + if again := PlanDispatch([]PullRequest{dispatchPR("sha1")}, Artifact{}, plan.State, opts); len(again.ReviewKicks) != 0 { + t.Fatalf("re-dispatched pending combined heads: %+v", again.ReviewKicks) + } +} + +// A combined head that answers some perspectives settles only those pairs; +// the next plan re-asks that head for the rest only, in one kick. +func TestCombinedHeadsReaskOnlyMissingPerspectives(t *testing.T) { + opts := headsOpts() + opts.CombinedPerspectives = true + opts.Perspectives = PerspectiveSet{} // the five built-in perspectives + all := opts.Perspectives.List() + if len(all) != 5 { + t.Fatalf("built-in perspectives = %v, want five", all) + } + plan := PlanDispatch([]PullRequest{dispatchPR("sha1")}, Artifact{}, DispatchState{}, opts) + if len(plan.ReviewKicks) != 2 || len(plan.State.Pending) != 10 { + t.Fatalf("kicks=%d pending=%d, want 2 kicks and 10 pending pairs", len(plan.ReviewKicks), len(plan.State.Pending)) + } + // sol records an array with 3 of 5 verdicts; sonnet answers all 5. + var reports []PerspectiveReport + for i, p := range all { + if i < 3 { + reports = append(reports, PerspectiveReport{Repo: "acme/hive", Number: 7, HeadSHA: "sha1", Perspective: p, Verdict: VerdictApprove, Head: "cr-sol"}) + } + reports = append(reports, PerspectiveReport{Repo: "acme/hive", Number: 7, HeadSHA: "sha1", Perspective: p, Verdict: VerdictApprove, Head: "cr-sonnet"}) + } + agg := AggregateReports(reports, AggregateOptions{Perspectives: opts.Perspectives, ExpectedHeads: []string{"cr-sol", "cr-sonnet"}}) + if agg.Verdict != VerdictIncomplete { + t.Fatalf("aggregate = %s, want incomplete while sol owes two perspectives", agg.Verdict) + } + next := PlanDispatch([]PullRequest{dispatchPR("sha1")}, Artifact{Items: []Aggregate{agg}}, plan.State, opts) + if len(next.ReviewKicks) != 0 { + t.Fatalf("re-asked while sol's missing pairs are still pending: %+v", next.ReviewKicks) + } + for _, p := range next.State.Pending { + if p.Head != "cr-sol" || p.Perspective == all[0] || p.Perspective == all[1] || p.Perspective == all[2] { + t.Fatalf("settled pair still pending: %+v", p) + } + } + if len(next.State.Pending) != 2 { + t.Fatalf("pending = %+v, want only sol's two unanswered pairs", next.State.Pending) + } + // With sol's entries gone (e.g. expired), sol is re-asked the two it + // missed, in one kick, and sonnet is not asked again. + again := PlanDispatch([]PullRequest{dispatchPR("sha1")}, Artifact{Items: []Aggregate{agg}}, DispatchState{}, opts) + if len(again.ReviewKicks) != 1 { + t.Fatalf("kicks = %+v, want one re-ask for cr-sol", again.ReviewKicks) + } + k := again.ReviewKicks[0] + if k.Head != "cr-sol" || len(k.Perspectives) != 2 || k.Perspectives[0] != all[3] || k.Perspectives[1] != all[4] { + t.Fatalf("re-ask = head %s perspectives %v, want cr-sol for %v", k.Head, k.Perspectives, all[3:]) + } +} + +// The decision step is unchanged under combined heads: it fires once every +// head has settled every perspective, with the same prompt. +func TestCombinedHeadsDecisionOnceEveryHeadSettled(t *testing.T) { + split := headsOpts() + opts := headsOpts() + opts.CombinedPerspectives = true + unsettled := AggregateReports([]PerspectiveReport{ + headRep(PerspectiveCorrectness, "cr-sol", VerdictChangesRequested, nilDeref), + headRep(PerspectiveCorrectness, "cr-sonnet", VerdictApprove), + headRep(PerspectiveSecurity, "cr-sonnet", VerdictApprove), + }, headAggOpts()) + early := PlanDispatch([]PullRequest{dispatchPR("sha1")}, Artifact{Items: []Aggregate{unsettled}}, DispatchState{}, opts) + if len(early.ReviewKicks) != 1 || early.ReviewKicks[0].Decision || early.ReviewKicks[0].Head != "cr-sol" || len(early.ReviewKicks[0].Perspectives) != 1 || early.ReviewKicks[0].Perspectives[0] != PerspectiveSecurity { + t.Fatalf("early kicks = %+v, want only security re-asked of cr-sol", early.ReviewKicks) + } + plan := PlanDispatch([]PullRequest{dispatchPR("sha1")}, Artifact{Items: []Aggregate{awaitingAgg()}}, DispatchState{}, opts) + if len(plan.ReviewKicks) != 1 || !plan.ReviewKicks[0].Decision || plan.ReviewKicks[0].Agent != "cr" { + t.Fatalf("kicks = %+v, want exactly the decision kick", plan.ReviewKicks) + } + want := PlanDispatch([]PullRequest{dispatchPR("sha1")}, Artifact{Items: []Aggregate{awaitingAgg()}}, DispatchState{}, split) + if plan.ReviewKicks[0].Message != want.ReviewKicks[0].Message { + t.Fatal("decision prompt differs under combined perspectives") } } @@ -288,7 +403,7 @@ func TestHeadsKeepPlainReviewersOnTheOrdinaryPath(t *testing.T) { opts := headsOpts() opts.Agents = append(headsFleet(), replica("cr-2", "cr"), reviewer("sec")) opts.ReviewerAgents = []string{"cr", "sec"} - heads, others := dispatchReviewers(reviewCapableAgents(opts), false) + heads, others := dispatchReviewers(reviewCapableAgents(opts)) if len(heads) != 3 { t.Fatalf("heads = %+v, want the three head replicas", heads) } From 3f9f5cd3e401faafd613248a5e4c9e86d5fc276a Mon Sep 17 00:00:00 2001 From: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com> Date: Wed, 28 Oct 2026 15:20:17 -0400 Subject: [PATCH 2/2] =?UTF-8?q?=F0=9F=90=9B=20fix(review):=20warn=20instea?= =?UTF-8?q?d=20of=20rejecting=20mixed=20reviewer=20sets=20under=20combined?= =?UTF-8?q?=20heads?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A reviewer set mixing lanes with and without review_heads loaded fine under combined_perspectives before heads were dispatched there, so rejecting it at load would break existing configs. Keep it loadable and log a boot warning that the plain lanes receive no combined perspectives while the heads cover them. Split-perspective validation is unchanged. Refs #15058 Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com> --- .../added-15058-combined-review-heads.md | 2 +- src/cmd/hive/main.go | 3 + src/docs/review-swarm.md | 2 +- src/pkg/config/review_heads.go | 60 +++++++++++++++---- src/pkg/config/review_heads_test.go | 18 ++++-- 5 files changed, 66 insertions(+), 19 deletions(-) diff --git a/changelog.d/added-15058-combined-review-heads.md b/changelog.d/added-15058-combined-review-heads.md index 806eecad0a..8d500e2735 100644 --- a/changelog.d/added-15058-combined-review-heads.md +++ b/changelog.d/added-15058-combined-review-heads.md @@ -1 +1 @@ -- Review heads (`agents..review_heads`) now work with `review.combined_perspectives: true`: each head reviews every perspective in one record-only kick per PR head instead of one kick per perspective, and config load now rejects a reviewer set that mixes lanes with and without heads in combined mode too. +- Review heads (`agents..review_heads`) now work with `review.combined_perspectives: true`: each head reviews every perspective in one record-only kick per PR head instead of one kick per perspective. A combined-mode reviewer set mixing lanes with and without heads still loads, with a boot warning that the plain lanes receive no combined perspectives. diff --git a/src/cmd/hive/main.go b/src/cmd/hive/main.go index 7248b15a9f..d80b44cd0a 100644 --- a/src/cmd/hive/main.go +++ b/src/cmd/hive/main.go @@ -1145,6 +1145,9 @@ func (b *boot) bootConfigWith(deps bootConfigDeps) bool { for _, warning := range config.WriteSurfaceWarnings(b.cfg) { b.logger.Warn("write surface allowlist", "issue", warning) } + for _, warning := range config.ReviewHeadsWarnings(b.cfg) { + b.logger.Warn("review heads config", "issue", warning) + } startupRepoTargetIssue := config.ValidateRepoTargets(b.cfg) if startupRepoTargetIssue != nil { b.logger.Warn("repo target misconfigured — owner action required", diff --git a/src/docs/review-swarm.md b/src/docs/review-swarm.md index 738caf4b0a..c3df94438e 100644 --- a/src/docs/review-swarm.md +++ b/src/docs/review-swarm.md @@ -418,7 +418,7 @@ review: reviewer_agents: [code-reviewer] # naming the base admits its heads ``` -With split perspectives, every perspective is dispatched once per head, to a replica of that head with no review kick in flight (see *One kick in flight per agent* below); the base and its plain `replicas` are not dispatched (they are reserved for the decision step). Because head dispatch asks every perspective of every head, a reviewer lane *without* `review_heads` alongside one with them would have nothing left to review, so config load rejects that mix (split or combined): every admitted reviewer (the `reviewer_agents` list, or every agent carrying the `review` token when the list is empty) must declare `review_heads`, or be left out. Only heads of admitted bases are expected by the aggregate. Each kick costs one `max_parallel_reviews` slot, and `max_perspectives_per_pr` still bounds how many perspectives a PR head receives. A head reviews **blind** (it is told not to read other reviews of this head) and **records only**: it delivers its verdict with `hive-review --record-verdict` and posts nothing on the PR. The relay stamps each verdict with the head from the dispatch record it bound to (an advisory verdict with no dispatch row carries none) and keeps one report per perspective per head; `review_model` is stamped per head, so each head's report names the model that head ran. +With split perspectives, every perspective is dispatched once per head, to a replica of that head with no review kick in flight (see *One kick in flight per agent* below); the base and its plain `replicas` are not dispatched (they are reserved for the decision step). Because head dispatch asks every perspective of every head, a reviewer lane *without* `review_heads` alongside one with them would have nothing left to review, so config load rejects that mix under `combined_perspectives: false` (under `combined_perspectives: true` it still loads, and the hive logs a `review heads config` warning at boot that the plain lanes receive no combined perspectives while the heads cover them): every admitted reviewer (the `reviewer_agents` list, or every agent carrying the `review` token when the list is empty) must declare `review_heads`, or be left out. Only heads of admitted bases are expected by the aggregate. Each kick costs one `max_parallel_reviews` slot, and `max_perspectives_per_pr` still bounds how many perspectives a PR head receives. A head reviews **blind** (it is told not to read other reviews of this head) and **records only**: it delivers its verdict with `hive-review --record-verdict` and posts nothing on the PR. The relay stamps each verdict with the head from the dispatch record it bound to (an advisory verdict with no dispatch row carries none) and keeps one report per perspective per head; `review_model` is stamped per head, so each head's report names the model that head ran. Heads have no `review_models` pool of their own (the head is the model). diff --git a/src/pkg/config/review_heads.go b/src/pkg/config/review_heads.go index 570f221c6d..d5e37fc884 100644 --- a/src/pkg/config/review_heads.go +++ b/src/pkg/config/review_heads.go @@ -173,14 +173,16 @@ func (r ReviewConfig) EffectiveHeadMaxRetries() int { } // validateReviewHeads checks each head's backend is one the governor can -// launch, review.head_max_retries is not negative, and that the admitted -// reviewers either all declare review_heads or none do. Head dispatch asks -// every perspective of every head, split or combined (hivecommons/hive#15058), -// and leaves nothing for a plain reviewer lane alongside them, so a mixed set -// would silently idle the lanes without heads (hivecommons/hive#13542). Structural -// checks (required fields, aliases, replicas, name collisions) run where the -// heads are expanded, so a bad head fails config load the same way a bad -// replicas value does. +// launch, review.head_max_retries is not negative, and that with split +// perspectives the admitted reviewers either all declare review_heads or +// none do. Head dispatch asks every perspective of every head and leaves +// nothing for a plain reviewer lane alongside them, so a mixed set would +// silently idle the lanes without heads (hivecommons/hive#13542). Under +// combined perspectives that mix loaded before heads were dispatched there +// (hivecommons/hive#15058), so it stays loadable and ReviewHeadsWarnings +// reports it instead. Structural checks (required fields, aliases, replicas, +// name collisions) run where the heads are expanded, so a bad head fails +// config load the same way a bad replicas value does. func (c *Config) validateReviewHeads() error { if c.Review.HeadMaxRetries < 0 { return fmt.Errorf("review.head_max_retries must be >= 0") @@ -197,7 +199,40 @@ func (c *Config) validateReviewHeads() error { } } } - var withHeads, without []string + if c.Review.CombinedPerspectives { + return nil + } + if withHeads, without := c.mixedReviewHeadBases(); len(withHeads) > 0 { + return fmt.Errorf("review_heads: with review.combined_perspectives: false every reviewer must declare review_heads: %s do, %s do not; add review_heads to them or leave them out of review.reviewer_agents", + strings.Join(withHeads, ", "), strings.Join(without, ", ")) + } + return nil +} + +// ReviewHeadsWarnings reports, under combined perspectives, an admitted +// reviewer set that mixes bases with and without review_heads. Combined head +// dispatch (hivecommons/hive#15058) asks every perspective of every head, so +// the lanes without heads receive no combined perspectives while the heads +// cover them. Split perspectives reject the same mix at load +// (validateReviewHeads); here it is a warning because the mix loaded fine +// before heads were dispatched under combined perspectives. +func ReviewHeadsWarnings(cfg *Config) []string { + if cfg == nil || !cfg.Review.CombinedPerspectives { + return nil + } + withHeads, without := cfg.mixedReviewHeadBases() + if len(withHeads) == 0 { + return nil + } + return []string{fmt.Sprintf( + "review_heads under review.combined_perspectives: %s declare review_heads, %s do not — while the heads cover every perspective, %s will receive no combined perspectives; add review_heads to them or leave them out of review.reviewer_agents", + strings.Join(withHeads, ", "), strings.Join(without, ", "), strings.Join(without, ", "))} +} + +// mixedReviewHeadBases splits the dispatched reviewer bases into those that +// declare review_heads and those that do not, returning both only when the +// set mixes them. +func (c *Config) mixedReviewHeadBases() (withHeads, without []string) { for _, name := range c.dispatchedReviewerBases() { if len(c.Agents[name].ReviewHeads) > 0 { withHeads = append(withHeads, name) @@ -205,9 +240,8 @@ func (c *Config) validateReviewHeads() error { without = append(without, name) } } - if len(withHeads) > 0 && len(without) > 0 { - return fmt.Errorf("review_heads: every reviewer must declare review_heads: %s do, %s do not; add review_heads to them or leave them out of review.reviewer_agents", - strings.Join(withHeads, ", "), strings.Join(without, ", ")) + if len(withHeads) == 0 || len(without) == 0 { + return nil, nil } - return nil + return withHeads, without } diff --git a/src/pkg/config/review_heads_test.go b/src/pkg/config/review_heads_test.go index d9d50c566b..842d2942bf 100644 --- a/src/pkg/config/review_heads_test.go +++ b/src/pkg/config/review_heads_test.go @@ -189,17 +189,27 @@ func TestReviewHeadsRejectMixedReviewerSet(t *testing.T) { if err == nil || !strings.Contains(err.Error(), "security-reviewer do not") { t.Fatalf("mixed reviewers accepted: %v", err) } - // Combined perspectives dispatch heads too (#15058), so the mix is - // rejected there as well. + if got := ReviewHeadsWarnings(cfg); got != nil { + t.Fatalf("split perspectives warned instead of rejecting: %v", got) + } + // Combined perspectives dispatch heads too (#15058), but that mix loaded + // before, so it still loads and is reported as a warning instead. cfg.Review.CombinedPerspectives = true - if err := cfg.validateReviewHeads(); err == nil { - t.Fatal("mixed reviewers accepted under combined perspectives") + if err := cfg.validateReviewHeads(); err != nil { + t.Fatalf("mixed reviewers rejected under combined perspectives: %v", err) + } + warnings := ReviewHeadsWarnings(cfg) + if len(warnings) != 1 || !strings.Contains(warnings[0], "security-reviewer will receive no combined perspectives") { + t.Fatalf("combined mixed set warnings = %v, want one naming the idle lane", warnings) } // Leaving the plain lane out of reviewer_agents is fine in either mode. cfg.Review.ReviewerAgents = []string{"code-reviewer"} if err := cfg.validateReviewHeads(); err != nil { t.Fatalf("heads-only reviewer set rejected under combined perspectives: %v", err) } + if got := ReviewHeadsWarnings(cfg); got != nil { + t.Fatalf("heads-only reviewer set warned: %v", got) + } cfg.Review.CombinedPerspectives = false if err := cfg.validateReviewHeads(); err != nil { t.Fatalf("heads-only reviewer set rejected: %v", err)