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/fixed-hold-step-by-source.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- A `hold` the hive set for a human-merge path is no longer described as a reporter-trust hold. projectbluefin/utah#1097 and projectbluefin/finpilot#627 were told to "Release it … and the lane merges on its next pass, or keep it until a maintainer has reviewed the issue's reporter", while the hive's own notice said it will not merge them. The hold's provenance now records `human-merge-path` when the App's human-merge-path notice is on the PR, and the 085 comment and the decision popover say a maintainer merges it by hand; a hold the hive can only attribute to its label event points at the hive's notice instead of naming the reporter gate.
2 changes: 1 addition & 1 deletion src/docs/dashboard-sections/activity-monitor.md
Original file line number Diff line number Diff line change
Expand Up @@ -560,7 +560,7 @@ The buttons run the row context menu's code path, so the same result toast and i

#### Hold pill with provenance

When the hive can say who set a row's `hold` label and why, the pill does not read a bare *hold*: it reads **Held by hive · reporter trust (issue #15017 by @Karibhou, contributor)** when the hive's own reporter-trust gate ([#9665](https://github.com/hivecommons/hive/issues/9665)) set it, **Held by hive** when the hive set it for another reason, or **Held by @login** when a person added the label; a hold the hive cannot attribute keeps the plain *hold* word.
When the hive can say who set a row's `hold` label and why, the pill does not read a bare *hold*: it reads **Held by hive · reporter trust (issue #15017 by @Karibhou, contributor)** when the hive's own reporter-trust gate ([#9665](https://github.com/hivecommons/hive/issues/9665)) set it, **Held by hive · it changes a human-merge path (`auto_merge.human_merge_paths`)** when the human-merge-path refusal ([#11027](https://github.com/hivecommons/hive/issues/11027)) set it, **Held by hive** when the hive set it for another reason, or **Held by @login** when a person added the label; a hold the hive cannot attribute keeps the plain *hold* word. The 085 comment and the decision popover word the release step for the gate that set the hold: only a reporter-trust hold is released into the lane's merge; a human-merge-path hold says the hive never merges the PR and a maintainer merges it by hand; any other hive hold points at the hive's notice on the PR instead of naming a gate.

The hover text repeats the pill, says since when, and for a hive-set reporter-trust hold explains that the hive set it itself and that *Release hold* lifts it. That same pill opens the needs-human decision popover: its question reads *The hive held this PR itself for reporter trust (issue #N by @X, contributor). Release the hold, or keep it?*, **Release hold** leads the buttons (enabled), *Let hive decide* waits until the hold is released, and `blocker_reason` is `hold:hive`.

Expand Down
2 changes: 1 addition & 1 deletion src/docs/labels-and-control-signals/reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -226,7 +226,7 @@ A hive-filed issue (`[selfreport]`, app or AI author) counts as trusted. The gat

**Release or override.** A human removes `hold` on a contributor PR; Hive never auto-releases it there. On a **hive-authored** PR still wearing a hive-set reporter-trust hold (newest `hold` event labeled by the App bot with the notice at or after it — a person's hold is left alone), the stage-label pass releases `hold` (and `needs-human` when the notice says the gate added it), posts one `<!-- hive:reporter-trust-release -->` comment and logs `stage labels: releasing self-imposed reporter-trust hold`.

The pass also records the hold's provenance (`by`, `source`, `reason`, `since`) on the stage store, so the tracker pill reads *Held by hive · reporter trust (issue #N by @X, contributor)* and the 085 comment names who set the hold and why. Holdguard re-holds on a new head SHA.
The pass also records the hold's provenance (`by`, `source`, `reason`, `since`) on the stage store, so the tracker pill reads *Held by hive · reporter trust (issue #N by @X, contributor)* and the 085 comment names who set the hold and why. `source` is `reporter-trust`, `human-merge-path` (the App's `<!-- hive-human-merge-path -->` notice is on the PR) or `label`. Holdguard re-holds on a new head SHA.

**Configuration and implementation.** `github.reporter_trust_hold` (nil follows `reporter_trust.enabled`), per-repo `project.repo_policies[].reporter_trust_hold`, `HIVE_REPORTER_TRUST_HOLD` (`src/pkg/github/pr_reporter_trust.go`, `src/pkg/github/pr_level_hold.go`, `src/pkg/github/automerge/reporter_trust_release.go`)

Expand Down
5 changes: 5 additions & 0 deletions src/pkg/dashboard/stage_tracker_decision_pr.go
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,11 @@ func decisionForPR(it StageTrackerItem, verdict *review.Aggregate, sentinelLabel
// name the gate and the issue, and offer release / keep.
d.AskedBy = decisionAskedByLane
d.Question = "The hive held this PR itself for " + decisionHoldReason(selfHold) + ". Release the hold (the lane then merges it on its next pass once the other gates are clear), or keep it?"
if strings.EqualFold(selfHold.Source, stagelabels.HoldSourceHumanMergePath) {
// No lane merges a human-merge-path PR, held or not: the
// person's step is the merge (projectbluefin/utah#1097).
d.Question = "The hive held this PR because " + decisionHoldReason(selfHold) + ": the hive never merges it. Review it and merge it by hand, or close it?"
}
if selfHold.Since != nil {
t := *selfHold.Since
d.Since = &t
Expand Down
29 changes: 29 additions & 0 deletions src/pkg/dashboard/stage_tracker_hold_human_merge_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
package dashboard

import (
"strings"
"testing"
"time"

"github.com/hivecommons/hive/pkg/stagelabels"
)

// projectbluefin/utah#1097: a hive hold from the human-merge-path refusal
// must not offer "release it and the lane merges it"; no lane merges it.
func TestStageTrackerDecisionHumanMergePathHold(t *testing.T) {
since := time.Date(2026, 11, 3, 15, 42, 20, 0, time.UTC)
it := StageTrackerItem{Repo: "projectbluefin/utah", Number: 1097, Kind: "pr", Stage: stagelabels.NeedsDecision.Number(), StageSince: &since, Reason: "label:hold", Modifiers: []string{modHold},
Hold: &StageTrackerHold{By: "hive", Source: stagelabels.HoldSourceHumanMergePath, Reason: "it changes " + stagelabels.HumanMergePathReason, Since: &since}}
d := stageTrackerDecisionNeeded(it, nil, "")
if d == nil {
t.Fatal("a hive-held 085 row must carry a decision")
}
for _, want := range []string{"because it changes a human-merge path", "the hive never merges it", "merge it by hand"} {
if !strings.Contains(d.Question, want) {
t.Errorf("question lacks %q: %q", want, d.Question)
}
}
if strings.Contains(d.Question, "the lane then merges it") {
t.Fatalf("question promises a lane merge: %q", d.Question)
}
}
19 changes: 19 additions & 0 deletions src/pkg/github/automerge/reporter_trust_release.go
Original file line number Diff line number Diff line change
Expand Up @@ -64,9 +64,28 @@ func (c *Engine) holdProvenance(ctx context.Context, owner, repo string, number
if notice != nil && !notice.PostedAt.Before(since.Add(-reporterTrustNoticeSlack)) {
return notice.Finding.HoldProvenance(since), notice, nil
}
// The human-merge-path refusal posts its notice once per PR and re-adds
// the label on later heads, so its notice explains the hold whenever the
// App wrote it (projectbluefin/utah#1097: told "the lane merges on its
// next pass" while the notice said a person must merge it).
if humanMergePathNoticed(comments, appBot) {
return &stagelabels.HoldProvenance{By: stagelabels.HoldByHive, Source: stagelabels.HoldSourceHumanMergePath,
Reason: "it changes " + stagelabels.HumanMergePathReason, Since: since}, notice, nil
}
return &stagelabels.HoldProvenance{By: stagelabels.HoldByHive, Source: stagelabels.HoldSourceLabel, Since: since}, notice, nil
}

// humanMergePathNoticed reports whether the App posted the human-merge-path
// hold notice on the thread.
func humanMergePathNoticed(comments []*gh.IssueComment, appBot string) bool {
for _, cm := range comments {
if cm != nil && strings.EqualFold(hgithub.SafeGetLogin(cm.GetUser()), appBot) && strings.Contains(cm.GetBody(), hgithub.HumanMergePathMarker) {
return true
}
}
return false
}

// reporterTrustNoticeSlack is how far before the `hold` label event the
// gate's notice may have been posted and still explain it: the watcher
// labels first and comments seconds later, but a stale notice from an
Expand Down
29 changes: 29 additions & 0 deletions src/pkg/github/automerge/reporter_trust_release_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,14 @@ func reporterTrustNoticeComment(at string) map[string]any {
}
}

func humanMergePathNoticeComment(login, at string) map[string]any {
return map[string]any{
"body": hgithub.HumanMergePathComment([]string{".github/workflows/build.yml"}),
"user": map[string]string{"login": login},
"created_at": at,
}
}

func holdEvent(event, actor, at string) map[string]any {
return map[string]any{
"event": event,
Expand Down Expand Up @@ -87,6 +95,27 @@ func TestHoldProvenance(t *testing.T) {
want: &stagelabels.HoldProvenance{By: "hive", Source: "reporter-trust", Reason: "reporter trust (issue #15017 by @Karibhou, contributor)", Issue: 15017, Reporter: "Karibhou", Association: "CONTRIBUTOR", Since: time.Date(2026, 10, 20, 17, 14, 18, 0, time.UTC)},
notice: true,
},
{
// projectbluefin/utah#1097: the human-merge-path refusal's
// notice explains the hive's hold on any later head.
name: "hive label plus the human-merge-path notice",
comments: []map[string]any{humanMergePathNoticeComment(testHiveAppBotLogin, "2026-10-19T09:00:00Z")},
events: []map[string]any{holdEvent("labeled", testHiveAppBotLogin, labelAt)},
want: &stagelabels.HoldProvenance{By: "hive", Source: "human-merge-path", Reason: "it changes " + stagelabels.HumanMergePathReason, Since: time.Date(2026, 10, 20, 17, 14, 14, 0, time.UTC)},
},
{
name: "a human-merge-path notice someone else posted explains nothing",
comments: []map[string]any{humanMergePathNoticeComment("someone", "2026-10-19T09:00:00Z")},
events: []map[string]any{holdEvent("labeled", testHiveAppBotLogin, labelAt)},
want: &stagelabels.HoldProvenance{By: "hive", Source: "label", Since: time.Date(2026, 10, 20, 17, 14, 14, 0, time.UTC)},
},
{
name: "a fresh reporter-trust notice outranks the human-merge-path notice",
comments: []map[string]any{humanMergePathNoticeComment(testHiveAppBotLogin, "2026-10-19T09:00:00Z"), reporterTrustNoticeComment("2026-10-20T17:14:18Z")},
events: []map[string]any{holdEvent("labeled", testHiveAppBotLogin, labelAt)},
want: &stagelabels.HoldProvenance{By: "hive", Source: "reporter-trust", Reason: "reporter trust (issue #15017 by @Karibhou, contributor)", Issue: 15017, Reporter: "Karibhou", Association: "CONTRIBUTOR", Since: time.Date(2026, 10, 20, 17, 14, 14, 0, time.UTC)},
notice: true,
},
{name: "nothing at all"},
} {
t.Run(tc.name, func(t *testing.T) {
Expand Down
21 changes: 16 additions & 5 deletions src/pkg/stagelabels/hold.go
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,9 @@ type HoldProvenance struct {
// lower-cased login of the person (or other app) who did; "" unknown.
By string `json:"by,omitempty"`
// Source names the hive gate behind a hive-set hold: HoldSourceReporterTrust
// for the reporter-trust gate (#9665), HoldSourceLabel for a hold the
// hive can only attribute to the label event.
// for the reporter-trust gate (#9665), HoldSourceHumanMergePath for the
// human-merge-path refusal (#11027), HoldSourceLabel for a hold the hive
// can only attribute to the label event.
Source string `json:"source,omitempty"`
// Reason is the plain-words cause ("reporter trust (issue #N by @X,
// contributor)"), "" when only the label is known.
Expand All @@ -35,11 +36,15 @@ type HoldProvenance struct {

// Hold sources.
const (
HoldByHive = "hive"
HoldSourceReporterTrust = "reporter-trust"
HoldSourceLabel = "label"
HoldByHive = "hive"
HoldSourceReporterTrust = "reporter-trust"
HoldSourceHumanMergePath = "human-merge-path"
HoldSourceLabel = "label"
)

// HumanMergePathReason is the plain-words cause of a human-merge-path hold.
const HumanMergePathReason = "a human-merge path (`auto_merge.human_merge_paths`)"

// SelfImposed reports whether the hive itself set this hold.
func (h *HoldProvenance) SelfImposed() bool {
return h != nil && strings.EqualFold(strings.TrimSpace(h.By), HoldByHive)
Expand All @@ -50,6 +55,12 @@ func (h *HoldProvenance) ReporterTrust() bool {
return h != nil && strings.EqualFold(strings.TrimSpace(h.Source), HoldSourceReporterTrust)
}

// HumanMergePath reports whether the hold came from the human-merge-path
// refusal: no lane merges the PR, whatever the label says.
func (h *HoldProvenance) HumanMergePath() bool {
return h != nil && strings.EqualFold(strings.TrimSpace(h.Source), HoldSourceHumanMergePath)
}

// Pill is the tracker pill text: "Held by hive · reporter trust (issue #N
// by @X, contributor)", "Held by @octocat", or "" when nothing is known.
func (h *HoldProvenance) Pill() string {
Expand Down
56 changes: 56 additions & 0 deletions src/pkg/stagelabels/hold_step_source_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
package stagelabels

import (
"strings"
"testing"
)

// projectbluefin/utah#1097 and projectbluefin/finpilot#627: a hold the
// human-merge-path refusal set was described with the reporter-trust step
// ("the lane merges on its next pass … until a maintainer has reviewed the
// issue's reporter"), contradicting the refusal's own "a person must merge
// it". The step is now worded for the gate that set the hold.
func TestSelfImposedHoldStepMatchesItsGate(t *testing.T) {
route := func(h *HoldProvenance) Route {
return Route{Stage: NeedsDecision, Head: "bb9de1e6b0000000000000000000000000000000", Holds: []string{"hold"}, Hold: h}
}
for _, tc := range []struct {
name string
hold *HoldProvenance
want []string
never []string
}{
{
name: "reporter trust keeps its release step",
hold: &HoldProvenance{By: HoldByHive, Source: HoldSourceReporterTrust, Reason: "reporter trust (issue #15017 by @Karibhou, contributor)"},
want: []string{"reporter trust (issue #15017", "the lane merges on its next pass", "reviewed the issue's reporter"},
never: []string{"merges it by hand"},
},
{
name: "human-merge path is a person's merge",
hold: &HoldProvenance{By: HoldByHive, Source: HoldSourceHumanMergePath, Reason: "it changes " + HumanMergePathReason},
want: []string{"`auto_merge.human_merge_paths`", "the hive never merges it", "merges it by hand", "does not hand it back to the lane"},
never: []string{"the lane merges on its next pass", "reporter"},
},
{
name: "a gate known only from the label event",
hold: &HoldProvenance{By: HoldByHive, Source: HoldSourceLabel},
want: []string{"its notice on this PR names the gate", "remove the `hold` label"},
never: []string{"the lane merges on its next pass", "reporter", "its own gate"},
},
} {
t.Run(tc.name, func(t *testing.T) {
got := DecisionActions(route(tc.hold))
for _, w := range tc.want {
if !strings.Contains(got, w) {
t.Errorf("missing %q:\n%s", w, got)
}
}
for _, n := range tc.never {
if strings.Contains(got, n) {
t.Errorf("must not say %q:\n%s", n, got)
}
}
})
}
}
29 changes: 24 additions & 5 deletions src/pkg/stagelabels/human.go
Original file line number Diff line number Diff line change
Expand Up @@ -894,11 +894,7 @@ func DecisionActions(r Route) string {
}
for _, h := range r.Holds {
if h == "hold" && r.Hold.SelfImposed() {
reason := strings.TrimSpace(r.Hold.Reason)
if reason == "" {
reason = "its own gate"
}
steps = append(steps, "The hive set `hold` itself for "+reason+". **Release** it (dashboard row menu → Release hold, or remove the `hold` label) and the lane merges on its next pass once the other gates are clear, or **keep** it until a maintainer has reviewed the issue's reporter; `/hive approve` does not remove it")
steps = append(steps, selfImposedHoldStep(r.Hold))
continue
}
steps = append(steps, "resolve the reason for `"+h+"` and have a maintainer remove that label (`/hive approve` does not remove it)")
Expand All @@ -917,6 +913,29 @@ func DecisionActions(r Route) string {
return b.String()
}

// selfImposedHoldStep is the release step for a `hold` the hive set itself,
// worded for the gate that set it. Only the reporter-trust gate's hold is
// released into an unattended merge; a human-merge-path hold stays a
// person's merge whatever the label says (projectbluefin/utah#1097,
// projectbluefin/finpilot#627 were told the lane would merge them); a hold
// the hive can attribute only to its label event names no gate it cannot see.
func selfImposedHoldStep(h *HoldProvenance) string {
reason := strings.TrimSpace(h.Reason)
switch {
case h.ReporterTrust():
if reason == "" {
reason = "its own gate"
}
return "The hive set `hold` itself for " + reason + ". **Release** it (dashboard row menu → Release hold, or remove the `hold` label) and the lane merges on its next pass once the other gates are clear, or **keep** it until a maintainer has reviewed the issue's reporter; `/hive approve` does not remove it"
case h.HumanMergePath():
return "The hive set `hold` because this PR changes " + HumanMergePathReason + ": the hive never merges it, so a maintainer reviews it and merges it by hand; removing `hold` does not hand it back to the lane"
}
if reason == "" {
return "The hive set `hold` itself; its notice on this PR names the gate. Resolve that, then remove the `hold` label; `/hive approve` does not remove it"
}
return "The hive set `hold` itself for " + reason + ". Resolve that, then remove the `hold` label; `/hive approve` does not remove it"
}

// HumanAuthorOwesAnswer reports whether a requires_human verdict on a PR a
// person pushed themselves routes to the author (071) rather than to a
// decision (085): the author is human and not this hive, no trusted merger
Expand Down
Loading