From 50375dd869285a2ad78025de73b58aaa18b4c7b5 Mon Sep 17 00:00:00 2001 From: Danathar <6772335+Danathar@users.noreply.github.com> Date: Tue, 17 Nov 2026 05:52:25 -0500 Subject: [PATCH] stage: the 085 needs-decision comment always names a cause A PR the stage pass held at 085 on the same head was re-parked with a bare route when the lane's own human route came back without a decision: on projectbluefin/fsdk-containers#553 the contributor lane's verdict cache read no verdict while the stage pass held requires_human with the finding "the reviewer marked this change high-risk", and DecisionComment rendered "Needs a decision, not a merge:" over an empty list. - preserveNeedsDecisionOnSameHead's re-park now builds its route from the stage pass's verdict (sameHeadDecisionRoute): the requires_human verdict, the finding, and the question or summaries, in the wording RouteHuman uses (stagelabels.RequiresHumanReasons). - The shared-CI permission park carries its decision cause as the reason. - DecisionComment never renders an empty list: a route with no reasons names DecisionReasonUnnamed ("the reviewer asked for a human decision"), and postHumanEntry logs a warning naming the PR and head. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1 Signed-off-by: Danathar <6772335+Danathar@users.noreply.github.com> --- .../fixed-needs-decision-empty-reasons.md | 1 + .../stage-labels.md | 8 +++ ...automerge_same_head_decision_route_test.go | 45 ++++++++++++++ .../github/automerge/automerge_stage_human.go | 26 +++++++++ .../automerge/automerge_stage_labels.go | 5 +- src/pkg/stagelabels/human.go | 58 ++++++++++++------- src/pkg/stagelabels/human_test.go | 49 ++++++++++++++++ 7 files changed, 171 insertions(+), 21 deletions(-) create mode 100644 changelog.d/fixed-needs-decision-empty-reasons.md create mode 100644 src/pkg/github/automerge/automerge_same_head_decision_route_test.go diff --git a/changelog.d/fixed-needs-decision-empty-reasons.md b/changelog.d/fixed-needs-decision-empty-reasons.md new file mode 100644 index 0000000000..4cbe82448f --- /dev/null +++ b/changelog.d/fixed-needs-decision-empty-reasons.md @@ -0,0 +1 @@ +- The `stage/085-needs-decision` comment always says why a decision is needed. When a PR was held at 085 on the same head after the contributor lane's own read of the reviewer verdict came back empty, the hive re-parked it with a bare route and posted "Needs a decision, not a merge:" followed by nothing, although the stage pass held the reviewer's `requires_human` verdict and finding ([projectbluefin/fsdk-containers#553](https://github.com/projectbluefin/fsdk-containers/pull/553)). The re-park now carries the reviewer's verdict, finding and question; the shared-CI permission park carries its cause; and any 085 route that still has no reason renders "the reviewer asked for a human decision" with a warning in the hive log naming the PR and head. diff --git a/src/docs/labels-and-control-signals/stage-labels.md b/src/docs/labels-and-control-signals/stage-labels.md index 8a3c3aa063..687212b5d2 100644 --- a/src/docs/labels-and-control-signals/stage-labels.md +++ b/src/docs/labels-and-control-signals/stage-labels.md @@ -483,6 +483,14 @@ maintainer's behalf, so prow/tide see nothing until a person acts. The check digest costs two REST calls per head and is cached 10 minutes; it is read only for human-routed PRs. +The 085 comment always names a cause. A PR the stage pass holds at 085 on +the same head, after the lane's own route came back without a decision, is +re-parked with the reviewer's `requires_human` verdict, finding and question +from the stage pass's verdict read. A route that still reaches 085 with no +reason renders "Needs a decision, not a merge: the reviewer asked for a human +decision." and the hive logs a warning naming the PR, head and lane reason +([projectbluefin/fsdk-containers#553](https://github.com/projectbluefin/fsdk-containers/pull/553)). + ### `role/*` — would the hive auto-merge this? One per PR, derived from what the lane used for admission (registry tier, diff --git a/src/pkg/github/automerge/automerge_same_head_decision_route_test.go b/src/pkg/github/automerge/automerge_same_head_decision_route_test.go new file mode 100644 index 0000000000..a0e5641f69 --- /dev/null +++ b/src/pkg/github/automerge/automerge_same_head_decision_route_test.go @@ -0,0 +1,45 @@ +package automerge + +import ( + "strings" + "testing" + + "github.com/hivecommons/hive/pkg/stagelabels" +) + +// TestSameHeadDecisionRouteNamesReviewerFinding pins +// projectbluefin/fsdk-containers#553: the same-head 085 re-park carried an +// empty route, and the entry comment read "Needs a decision, not a merge:" +// with no reason, while the stage pass held the reviewer's requires_human +// verdict and its finding. The re-park's route now names them. +func TestSameHeadDecisionRouteNamesReviewerFinding(t *testing.T) { + head := "0afe7c60b570d5b04dd2967459ab41797f4af639" + obs := stageObservation{HeadSHA: head, Lane: stageLaneContributor} + obs.Detail.VerdictKnown = true + obs.Detail.Verdict = ContributorLaneVerdict{ + Configured: true, + Verdict: "requires_human", + DecisionRequested: true, + DecisionFinding: "the reviewer marked this change high-risk", + } + route := sameHeadDecisionRoute(obs) + if route.Stage != stagelabels.NeedsDecision || route.Head != head || route.Verdict != stagelabels.VerdictRequiresHuman || route.SelfAuthored { + t.Fatalf("route = %+v", route) + } + body := stagelabels.DecisionComment(route) + for _, want := range []string{ + "- the reviewer swarm returned `requires_human` @0afe7c6\n", + "- the review found: the reviewer marked this change high-risk\n", + } { + if !strings.Contains(body, want) { + t.Fatalf("DecisionComment missing %q:\n%s", want, body) + } + } + + self := stageObservation{HeadSHA: head, Lane: stageLaneSelf} + if r := sameHeadDecisionRoute(self); !r.SelfAuthored || len(r.Reasons) != 0 { + t.Fatalf("self-authored route with no verdict = %+v", r) + } else if body := stagelabels.DecisionComment(r); !strings.Contains(body, "Needs a decision, not a merge: "+stagelabels.DecisionReasonUnnamed+".") { + t.Fatalf("no verdict known: DecisionComment =\n%s", body) + } +} diff --git a/src/pkg/github/automerge/automerge_stage_human.go b/src/pkg/github/automerge/automerge_stage_human.go index 82cd678d3e..97186e0b49 100644 --- a/src/pkg/github/automerge/automerge_stage_human.go +++ b/src/pkg/github/automerge/automerge_stage_human.go @@ -819,6 +819,27 @@ func joinNames(names []string) string { // reasons of its own (trust is the only objection). var readyEntryCause = stagelabels.EntryCause([]string{"ready for a human merge"}) +// sameHeadDecisionRoute is the 085 route preserveNeedsDecisionOnSameHead +// re-parks a head on. The human route built this pass can disagree with +// the stage pass's own verdict read: on projectbluefin/fsdk-containers#553 +// the contributor lane's verdict cache read no verdict while the stage pass +// held `requires_human` with its finding, the route came back without a +// decision, and the re-park posted "Needs a decision, not a merge:" with no +// reason at all. The reasons come from the stage pass's verdict instead; +// with no verdict known for the head the comment names +// stagelabels.DecisionReasonUnnamed. +func sameHeadDecisionRoute(obs stageObservation) stagelabels.Route { + route := stagelabels.Route{Stage: stagelabels.NeedsDecision, Head: obs.HeadSHA, SelfAuthored: obs.Lane == stageLaneSelf, + Holds: stagelabels.Holds(obs.Labels), Hold: obs.Hold} + if !obs.Detail.VerdictKnown { + return route + } + v := normalizeContributorLaneVerdict(obs.Detail.Verdict) + route.Verdict = stagelabels.VerdictRequiresHuman + route.Reasons = stagelabels.RequiresHumanReasons(obs.HeadSHA, v.DecisionFinding, v.DecisionQuestion, v.HumanSummaries) + return route +} + func (c *Engine) postHumanEntry(ctx context.Context, store *stagelabels.Store, key string, obs stageObservation, role stagelabels.Role, route stagelabels.Route) (int, error) { rec, ok := store.Get(key) if !ok || rec.Stage != route.Stage { @@ -871,6 +892,11 @@ func (c *Engine) postHumanEntry(ctx context.Context, store *stagelabels.Store, k case stagelabels.ReadyForHumanMerge: body = stagelabels.ReadyComment(route, trustCause(obs.Reason, role)) case stagelabels.NeedsDecision: + if len(route.Reasons) == 0 { + // The comment falls back to DecisionReasonUnnamed; name the + // route that carried no reason so it can be found. + c.warn("stage labels: 085 route carries no reason; the entry comment names a generic one", "repo", obs.Display, "pr", obs.Number, "head", obs.HeadSHA, "reason", obs.Reason, "lane", obs.Lane) + } body = stagelabels.DecisionComment(route) + c.workflowApprovalSnippet(obs.Reason) default: return 0, nil diff --git a/src/pkg/github/automerge/automerge_stage_labels.go b/src/pkg/github/automerge/automerge_stage_labels.go index f0575c58f0..3c5f327d2b 100644 --- a/src/pkg/github/automerge/automerge_stage_labels.go +++ b/src/pkg/github/automerge/automerge_stage_labels.go @@ -1450,6 +1450,9 @@ func (c *Engine) ApplyStageLabels(ctx context.Context) (StageLabelResult, error) verdict.Rank = stageRankOwned obs.Reason = unauthorizedReason(step) route := stagelabels.Route{Stage: stagelabels.NeedsDecision} + if cause := decisionCause(obs.Reason); cause != "" { + route.Reasons = []string{cause} + } obs.Route = &route } // Only re-park when the post-steps would leave 085: an adoption @@ -1458,7 +1461,7 @@ func (c *Engine) ApplyStageLabels(ctx context.Context) (StageLabelResult, error) if replacement, ok := preserveNeedsDecisionOnSameHead(prevRec, hadPrev, obs, verdict); ok { verdict = replacement obs.Reason = replacement.Reason - route := stagelabels.Route{Stage: stagelabels.NeedsDecision} + route := sameHeadDecisionRoute(obs) obs.Route = &route } } diff --git a/src/pkg/stagelabels/human.go b/src/pkg/stagelabels/human.go index 239fd8d4c7..f004b5b58f 100644 --- a/src/pkg/stagelabels/human.go +++ b/src/pkg/stagelabels/human.go @@ -482,6 +482,34 @@ func ParseFixerExhausted(reason string) (attempts int, ok bool) { // specific cause; EntryCause leaves it out of the dedup digest. const decisionConsequenceReason = "the automerge lane will not merge this unattended" +// RequiresHumanReasons are the 085 reasons for a reviewer `requires_human` +// verdict on head: the verdict itself, the finding behind it, and the +// reviewer's question (else its human-facing summaries). +func RequiresHumanReasons(head, finding, question string, summaries []string) []string { + reasons := []string{"the reviewer swarm returned `requires_human` @" + ShortSHA(head)} + if f := strings.TrimSpace(finding); f != "" { + reasons = append(reasons, "the review found: "+f) + } + if q := strings.TrimSpace(question); q != "" { + if decisionQuestionPlaceholderMention(q) { + q += " _(the reviewer named no specific person; repository approvers/owners, this is yours)_" + } + reasons = append(reasons, "reviewer question: "+q) + } else { + for _, summary := range summaries { + if s := strings.TrimSpace(summary); s != "" { + reasons = append(reasons, "reviewer summary: "+s) + } + } + } + return reasons +} + +// DecisionReasonUnnamed is the 085 entry comment's reason when the route +// reached it with none: the note always names a cause, never an empty list +// (projectbluefin/fsdk-containers#553). +const DecisionReasonUnnamed = "the reviewer asked for a human decision" + // RouteHuman decides which stage a lane's "a human must act" resolves to. func RouteHuman(e Evidence) Route { return withGates(e, routeProgress(e)) @@ -665,22 +693,7 @@ func routeProgress(e Evidence) Route { // head: the decision is made, not owed. break } - decide = append(decide, "the reviewer swarm returned `requires_human` @"+ShortSHA(e.Head)) - if f := strings.TrimSpace(e.DecisionFinding); f != "" { - decide = append(decide, "the review found: "+f) - } - if q := strings.TrimSpace(e.DecisionQuestion); q != "" { - if decisionQuestionPlaceholderMention(q) { - q += " _(the reviewer named no specific person; repository approvers/owners, this is yours)_" - } - decide = append(decide, "reviewer question: "+q) - } else { - for _, summary := range e.HumanSummaries { - if s := strings.TrimSpace(summary); s != "" { - decide = append(decide, "reviewer summary: "+s) - } - } - } + decide = append(decide, RequiresHumanReasons(e.Head, e.DecisionFinding, e.DecisionQuestion, e.HumanSummaries)...) } // A sentinel alert or a hold-class label is a gate, not a stage // (hivecommons/hive#17327): withGates rides it on whatever stage the @@ -955,7 +968,8 @@ func readyCommentBehindTail(r Route) string { "\n\nThe hive never approves on your behalf: `/lgtm` `/approve` if you accept it; the branch still has to be brought up to date before it can merge." } -// DecisionComment renders the 085 entry comment naming what is owed. +// DecisionComment renders the 085 entry comment naming what is owed. A +// route with no reasons names DecisionReasonUnnamed instead of an empty list. func DecisionComment(r Route) string { var b strings.Builder b.WriteString(DecisionCommentMarker) @@ -964,13 +978,17 @@ func DecisionComment(r Route) string { } else { b.WriteString("\nNeeds a decision, not a merge") } - if len(r.Reasons) == 1 { + reasons := r.Reasons + if len(reasons) == 0 { + reasons = []string{DecisionReasonUnnamed} + } + if len(reasons) == 1 { b.WriteString(": ") - b.WriteString(r.Reasons[0]) + b.WriteString(reasons[0]) b.WriteString(".") } else { b.WriteString(":\n") - for _, reason := range r.Reasons { + for _, reason := range reasons { b.WriteString("- ") b.WriteString(reason) b.WriteString("\n") diff --git a/src/pkg/stagelabels/human_test.go b/src/pkg/stagelabels/human_test.go index 65eb1e6820..d495dd7388 100644 --- a/src/pkg/stagelabels/human_test.go +++ b/src/pkg/stagelabels/human_test.go @@ -995,3 +995,52 @@ func TestDecisionActionsDoNotReaskARecordedApproval(t *testing.T) { t.Fatalf("requires_human actions = %q", got) } } + +// TestDecisionCommentReasonList pins projectbluefin/fsdk-containers#553: a +// route that reaches 085 with no reasons names DecisionReasonUnnamed, never +// "Needs a decision, not a merge:" over an empty list; one reason and +// several reasons render as before. +func TestDecisionCommentReasonList(t *testing.T) { + for _, tc := range []struct { + name string + reasons []string + want string + }{ + {name: "zero reasons name the generic cause", want: "\nNeeds a decision, not a merge: the reviewer asked for a human decision.\n\n"}, + {name: "one reason is inline", reasons: []string{"the review found: the reviewer marked this change high-risk"}, want: "\nNeeds a decision, not a merge: the review found: the reviewer marked this change high-risk.\n\n"}, + {name: "several reasons are a list", reasons: []string{"first", "second"}, want: "\nNeeds a decision, not a merge:\n- first\n- second\n\n\n"}, + } { + t.Run(tc.name, func(t *testing.T) { + got := DecisionComment(Route{Stage: NeedsDecision, Reasons: tc.reasons}) + if !strings.HasPrefix(got, DecisionCommentMarker+tc.want) { + t.Fatalf("DecisionComment =\n%q\nwant prefix\n%q", got, DecisionCommentMarker+tc.want) + } + if strings.Contains(got, "not a merge:\n\n") { + t.Fatalf("DecisionComment has an empty reason list:\n%s", got) + } + }) + } +} + +// RequiresHumanReasons is the one wording of a requires_human verdict, shared +// by RouteHuman and the same-head 085 re-park. +func TestRequiresHumanReasons(t *testing.T) { + got := RequiresHumanReasons("0afe7c60b570d5b0", "the reviewer marked this change high-risk", "", []string{" ", "privacy impact unclear"}) + want := []string{ + "the reviewer swarm returned `requires_human` @0afe7c6", + "the review found: the reviewer marked this change high-risk", + "reviewer summary: privacy impact unclear", + } + if strings.Join(got, "\n") != strings.Join(want, "\n") { + t.Fatalf("RequiresHumanReasons = %q, want %q", got, want) + } + e := readyEvidence() + e.AuthorKind = authorkind.Clanker + e.Verdict = VerdictRequiresHuman + e.DecisionFinding = "the reviewer marked this change high-risk" + e.DecisionQuestion = "ship it?" + r := RouteHuman(e) + if want := RequiresHumanReasons(e.Head, e.DecisionFinding, e.DecisionQuestion, nil); r.Stage != NeedsDecision || strings.Join(r.Reasons, "\n") != strings.Join(want, "\n") { + t.Fatalf("RouteHuman reasons = %q, want %q", r.Reasons, want) + } +}