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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/added-15058-combined-review-heads.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Review heads (`agents.<name>.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.
3 changes: 3 additions & 0 deletions src/cmd/hive/main.go
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
package main

import (
Expand Down Expand Up @@ -1145,6 +1145,9 @@
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",
Expand Down
6 changes: 4 additions & 2 deletions src/docs/review-swarm.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 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) 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

Expand Down
61 changes: 46 additions & 15 deletions src/pkg/config/review_heads.go
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -177,10 +177,12 @@ func (r ReviewConfig) EffectiveHeadMaxRetries() int {
// 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
// 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.
// 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")
Expand All @@ -200,17 +202,46 @@ func (c *Config) validateReviewHeads() error {
if c.Review.CombinedPerspectives {
return nil
}
var withHeads, without []string
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)
} else {
without = append(without, name)
}
}
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",
strings.Join(withHeads, ", "), strings.Join(without, ", "))
if len(withHeads) == 0 || len(without) == 0 {
return nil, nil
}
return nil
return withHeads, without
}
33 changes: 24 additions & 9 deletions src/pkg/config/review_heads_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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)
}
}

Expand All @@ -187,20 +189,33 @@ 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.
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.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: %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
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("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")
Expand Down
2 changes: 1 addition & 1 deletion src/pkg/review/dispatch.go
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down
7 changes: 6 additions & 1 deletion src/pkg/review/prompts.go
Original file line number Diff line number Diff line change
Expand Up @@ -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))
Expand Down
Loading
Loading