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-overview-hold-reason-drafts.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- The Overview's PR rows say what actually holds a PR, and drafts are counted. `hold_reason` told PRs held only by their sentinel alert (projectbluefin/homebrew-tap#60, testsuite#1108) to wait "until the hold label is removed" and called their absent `hold` "usually the ACMM level gate", and gave a holdguard hold (utah-packages#878) the same ACMM sentence. It now names a hold label only when the PR wears one, and keeps the ACMM sentence for a generic hold whose recorded sources are unknown or name the level gate; the repository card's tooltip uses the same rule. The Draft band read 0 hive-wide while projectbluefin/common#1532, #1626 and server#585 were open drafts, because the enumeration sidelines drafts; the bands and `/api/overview` now count them.
2 changes: 1 addition & 1 deletion src/docs/dashboard-glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ The ADR-0018 information-architecture/naming pass is implemented. The table belo
| Fleet | The set of agents or contributor agents under observation in an operational context. | Use for aggregate operational controls and live monitoring. |
| Issue band | A display-only group in a repository card's issue column, named for the operator's action: Unclaimed, Claimed, Needs triage (agent-filed and not yet acknowledged by a human), Parked, or Confirm & close. | Use for Projects card grouping; do not imply scheduler eligibility changed. Hover a band header, Overview slice, or legend row for its rule. |
| Pill legend | The collapsible Projects-section key explaining pill colours, borders, glyphs, and badges as a colour key plus captioned issue, pull-request, review, link, and action pills, including the red sentinel pill for PRs that carry the configured sentinel alert label. The aligned repository-card rows keep the left chip for the issue band or PR review class and align actions in fixed slots. | Use for the compact legend above project cards. |
| PR band | A display-only group in a repository card's pull-request column: Gated, Merge-eligible, Blocked, In review, Open, or Draft. | Use for Projects card grouping; do not imply merge queue, hold, or review eligibility changed. |
| PR band | A display-only group in a repository card's pull-request column: Gated, Merge-eligible, Blocked, In review, Open, or Draft. Drafts are counted from the sidelined draft list, since the enumeration keeps them out of the open-PR list. | Use for Projects card grouping; do not imply merge queue, hold, or review eligibility changed. |
| Stale issue | An actionable repository-card issue whose `updated_at` activity is older than the configured `dashboard.issue_bands.stale_days` threshold. | Use for the `N no activity > Nd` counter and `🕒` badge. |
| Stale PR | A repository-card PR whose `updated_at` activity is older than the configured `dashboard.issue_bands.stale_days` threshold. | Use for the PR `🕒` badge. |

Expand Down
21 changes: 14 additions & 7 deletions src/pkg/dashboard/bands.go
Original file line number Diff line number Diff line change
Expand Up @@ -222,7 +222,7 @@ func IssueBand(issue github.Issue, held bool, cfg config.DashboardIssueBandsConf
if band == "waiting" {
chip = issueLabelChip(labels)
}
return IssueBandInfo{Band: band, Role: role, Acknowledged: acknowledged, Held: held, HoldReason: heldReason(issue.Labels, false, ""), Stale: stale, Signals: signals, Chip: chip}
return IssueBandInfo{Band: band, Role: role, Acknowledged: acknowledged, Held: held, HoldReason: heldReason(issue.Labels, false, "", nil), Stale: stale, Signals: signals, Chip: chip}
}

// issueLabelChip returns the chip word for the highest-precedence waiting
Expand Down Expand Up @@ -339,7 +339,7 @@ func prBand(pr github.PullRequest, verdict *github.MergeVerdict, held bool, cfg
if stale {
signals = append(signals, Signal{Glyph: "🕒", Label: fmt.Sprintf("stale: no activity > %dd", norm.StaleDays)})
}
return PRBandInfo{Band: band, Role: role, Held: held, HoldReason: heldReason(pr.Labels, pr.HiveAttributed, hiveID, pr.ReporterTrustReason), Stale: stale, Signals: signals}
return PRBandInfo{Band: band, Role: role, Held: held, HoldReason: heldReason(pr.Labels, pr.HiveAttributed, hiveID, pr.HoldSources, pr.ReporterTrustReason), Stale: stale, Signals: signals}
}

// prBandFlags reports the merge-state facts every PR band is chosen from.
Expand Down Expand Up @@ -685,23 +685,30 @@ func containsAnyHoldLabel(s string, needles []string) bool {
return false
}

func heldReason(labels []string, hiveAttributed bool, hiveID string, evidence ...string) string {
// heldReason is the hold tooltip / hold_reason. It names a hold label only
// when the item wears one: a PR held by its sentinel alert or a policy hold
// alone was told to wait "until the hold label is removed" and that its
// (absent) generic hold was "usually the ACMM level gate"
// (projectbluefin/homebrew-tap#60, testsuite#1108). The ACMM sentence is kept
// for a generic hold whose recorded sources are unknown or name the level
// gate, not for one the holdguard or another gate set (utah-packages#878).
func heldReason(labels []string, hiveAttributed bool, hiveID string, sources []string, evidence ...string) string {
held := holdLabels(labels, hiveID)
parts := make([]string, 0, 3)
labelText := ""
if len(held) > 0 {
quoted := make([]string, 0, len(held))
for _, label := range held {
quoted = append(quoted, "`"+label+"`")
}
labelText = " — label " + strings.Join(quoted, ", ")
parts = append(parts, "On hold — label "+strings.Join(quoted, ", ")+": agents will not act on this until the hold label is removed")
} else {
parts = append(parts, "On hold: agents will not act on this until what holds it is cleared")
}
parts = append(parts, "On hold"+labelText+": agents will not act on this until the hold label is removed")
if len(evidence) > 0 && evidence[0] != "" {
parts = append(parts, evidence[0]+", a maintainer must review this")
return strings.Join(parts, "; ")
}
if hiveAttributed {
if hiveAttributed && len(held) > 0 && (len(sources) == 0 || slices.Contains(sources, github.HoldSourceLevelGate)) {
parts = append(parts, "opened by a hive agent — a generic `hold` here is usually the ACMM level gate; the dashboard hive-pause hold is only removed by an operator")
}
for _, label := range labels {
Expand Down
44 changes: 44 additions & 0 deletions src/pkg/dashboard/bands_hold_reason_source_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
package dashboard

import (
"strings"
"testing"

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

// hold_reason named a hold label PRs held only by their sentinel alert did
// not carry (projectbluefin/homebrew-tap#60, testsuite#1108), and called a
// holdguard hold the ACMM level gate (utah-packages#878).
func TestHeldReasonNamesOnlyWhatHoldsIt(t *testing.T) {
for _, tc := range []struct {
name string
labels []string
sources []string
want []string
never []string
}{
{name: "sentinel alert only", labels: []string{"sentinel-alert", "stage/072-returned-to-contributor"},
want: []string{"until what holds it is cleared"}, never: []string{"hold label", "ACMM level gate"}},
{name: "holdguard hold", labels: []string{"hold"}, sources: []string{github.HoldSourceHoldguard},
want: []string{"label `hold`", "until the hold label is removed"}, never: []string{"ACMM level gate"}},
{name: "level gate hold", labels: []string{"hold"}, sources: []string{github.HoldSourceLevelGate},
want: []string{"label `hold`", "ACMM level gate"}},
{name: "generic hold, sources unknown", labels: []string{"hold"},
want: []string{"label `hold`", "ACMM level gate"}},
} {
t.Run(tc.name, func(t *testing.T) {
got := heldReason(tc.labels, true, "", tc.sources)
for _, w := range tc.want {
if !strings.Contains(got, w) {
t.Errorf("missing %q: %s", w, got)
}
}
for _, n := range tc.never {
if strings.Contains(got, n) {
t.Errorf("must not say %q: %s", n, got)
}
}
})
}
}
55 changes: 55 additions & 0 deletions src/pkg/dashboard/overview_draft_band_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
package dashboard

import (
"testing"

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

// The Draft band read 0 hive-wide while projectbluefin/common#1532, #1626 and
// server#585 were open drafts: the enumeration sidelines drafts instead of
// listing them with the open PRs, and the bands only walked the open and
// held lists.
func TestOverviewDraftsLandInDraftBand(t *testing.T) {
s := newTestServer()
s.deps = &Dependencies{Config: &config.Config{}}
now := mustTime9102(t, "2026-11-05T21:00:00Z")
open := github.PullRequest{Number: 7, BaseRef: "main", Title: "fix", Author: "someone", Labels: []string{}, Mergeable: github.MergeableYes, MergeableState: "clean", UpdatedAt: now, CreatedAt: now}
status := &StatusPayload{HiveID: "h1", Repos: []FrontendRepo{{
Full: "projectbluefin/common",
OpenPrs: []any{FrontendPR{PullRequest: open}},
NonActionablePrs: []any{
github.RepoWorkPR{Repo: "projectbluefin/common", Number: 1532, Title: "wip", Draft: true, Bucket: "draft", Reason: "Draft", CreatedAt: now, UpdatedAt: now},
github.RepoWorkPR{Repo: "projectbluefin/common", Number: 1626, Title: "wip", Labels: []string{"approved"}, Draft: true, Bucket: "draft", Reason: "Draft", CreatedAt: now, UpdatedAt: now},
github.RepoWorkPR{Repo: "projectbluefin/common", Number: 9, Title: "excluded", Bucket: "exempt", Reason: "Exempt label"},
},
}}}

rows, specs := s.overviewPRRows(status, s.issueBandsConfig(), overviewFilters{}, now)
counts := map[string]int{}
for _, spec := range specs {
counts[spec.Key] = spec.Count
}
if counts["draft"] != 2 {
t.Fatalf("Draft count = %d, want 2; counts = %v", counts["draft"], counts)
}
if len(rows) != 3 {
t.Fatalf("rows = %d, want the open PR and the two drafts", len(rows))
}
for _, item := range s.overviewPRItems(status, s.issueBandsConfig(), overviewFilters{}, now) {
if item.pr.Number == 9 {
t.Fatal("a sidelined non-draft PR is not a draft row")
}
}

out := s.statusWithOverviewBands(status, now)
if out.OverviewBands == nil {
t.Fatal("status payload carries no overview bands")
}
for _, spec := range out.OverviewBands.PRs {
if spec.Key == "draft" && spec.Count != 2 {
t.Fatalf("status payload Draft band = %d, want 2 (%+v)", spec.Count, out.OverviewBands.PRs)
}
}
}
32 changes: 31 additions & 1 deletion src/pkg/dashboard/overview_export.go
Original file line number Diff line number Diff line change
Expand Up @@ -263,7 +263,7 @@ func overviewIssueItems(status *StatusPayload, cfg config.DashboardIssueBandsCon
for _, issue := range frontendRepoIssues(repo, true) {
issue.Repo = nonEmpty(issue.Repo, repoName)
info := IssueBand(issue, true, cfg, now, selfAuthorizationHoldActive)
info.HoldReason = heldReason(issue.Labels, false, status.HiveID)
info.HoldReason = heldReason(issue.Labels, false, status.HiveID, nil)
ownership := ownershipFor(repo.Ownership, ownershipKindIssue, issue.Number)
slice := overviewIssueChartSlice(issue, ownership)
if !filters.matchBand(info.Band) || !filters.matchSlice(slice) || !filters.matchFlags(info.Stale, true) {
Expand Down Expand Up @@ -369,6 +369,16 @@ func (s *Server) overviewPRItems(status *StatusPayload, cfg config.DashboardIssu
}
out = append(out, overviewPRItem{pr: entry.pr, verdict: entry.verdict, held: true, info: info, ownership: ownership, slice: slice})
}
for _, entry := range frontendRepoDraftPRs(repo) {
entry.pr.Repo = nonEmpty(entry.pr.Repo, repoName)
info := prBand(entry.pr, nil, false, cfg, now, autoMergeLabel, status.HiveID)
ownership := ownershipFor(repo.Ownership, ownershipKindPR, entry.pr.Number)
slice := overviewPRChartSlice(entry.pr, nil, ownership, autoMergeLabel)
if !filters.matchBand(info.Band) || !filters.matchSlice(slice) || !filters.matchFlags(info.Stale, false) {
continue
}
out = append(out, overviewPRItem{pr: entry.pr, info: info, ownership: ownership, slice: slice})
}
}
return out
}
Expand Down Expand Up @@ -497,6 +507,26 @@ func frontendRepoPRs(repo FrontendRepo, held bool) []frontendPR {
return out
}

// frontendRepoDraftPRs are the repo's open drafts as band entries. The
// enumeration sidelines drafts (github.RepoWorkPR, bucket "draft") instead of
// listing them with OpenPrs / HeldPrs, so the PR bands never saw one: the
// Draft band read 0 hive-wide while projectbluefin/common#1532, #1626 and
// server#585 were open drafts.
func frontendRepoDraftPRs(repo FrontendRepo) []frontendPR {
var out []frontendPR
for _, raw := range repo.NonActionablePrs {
w, ok := repoWorkPR(raw)
if !ok || !w.Draft {
continue
}
out = append(out, frontendPR{pr: github.PullRequest{
Repo: w.Repo, Number: w.Number, Title: w.Title, Author: w.Author, Labels: append([]string(nil), w.Labels...),
Draft: true, URL: w.URL, CreatedAt: w.CreatedAt, UpdatedAt: w.UpdatedAt, AppAuthored: w.AppAuthored, HiveAttributed: w.HiveAttributed,
}})
}
return out
}

func frontendPullRequest(raw any) (frontendPR, bool) {
switch v := raw.(type) {
case FrontendPR:
Expand Down
7 changes: 6 additions & 1 deletion src/pkg/dashboard/overview_status.go
Original file line number Diff line number Diff line change
Expand Up @@ -155,7 +155,7 @@ func (s *Server) statusWithOverviewBands(status *StatusPayload, now time.Time) *
issue.Repo = nonEmpty(issue.Repo, repoName)
info := IssueBand(issue, held, cfg, now, selfAuthorizationHoldActive)
if held {
info.HoldReason = heldReason(issue.Labels, false, status.HiveID)
info.HoldReason = heldReason(issue.Labels, false, status.HiveID, nil)
}
countSlice(out.OverviewBands.Issues, info.Band)
ownership := ownershipFor(decisions, ownershipKindIssue, issue.Number)
Expand Down Expand Up @@ -229,6 +229,11 @@ func (s *Server) statusWithOverviewBands(status *StatusPayload, now time.Time) *
repo.NonActionableIssues = nonActionable(repo.NonActionableIssues, *repo, repoName)
repo.OpenPrs = prs(repo.OpenPrs, false, repo.Ownership, repo.CriticalPath)
repo.HeldPrs = prs(repo.HeldPrs, true, repo.Ownership, repo.CriticalPath)
// Drafts are sidelined, not listed with the PRs above; count them in
// their band so the Draft band is not always 0.
for _, entry := range frontendRepoDraftPRs(*repo) {
countSlice(out.OverviewBands.PRs, prBand(entry.pr, nil, false, cfg, now, autoMergeLabel, status.HiveID).Band)
}
}
out.OverviewTotals = overviewTotals(status)
var fullCfg *config.Config
Expand Down
11 changes: 11 additions & 0 deletions src/pkg/dashboard/repo_card_held_pills_7896_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -375,6 +375,17 @@ check('renovate says on hold', heldReason(renovate).startsWith('On hold'));
check('renovate names needs-human', heldReason(renovate).includes('needs-human: automated fix attempts exhausted'));
check('renovate does not claim the level gate', !heldReason(renovate).includes('ACMM level gate'));

// projectbluefin/homebrew-tap#60: held by its sentinel alert alone. No hold
// label to remove, and no generic hold to call the ACMM gate.
const sentinelOnly = { labels: ['sentinel-alert'], hive_attributed: true };
check('sentinel-only names no hold label', !heldReason(sentinelOnly).includes('hold label'));
check('sentinel-only says what holds it', heldReason(sentinelOnly).includes('until what holds it is cleared'));
check('sentinel-only does not claim the level gate', !heldReason(sentinelOnly).includes('ACMM level gate'));
// projectbluefin/utah-packages#878: a holdguard hold is not the level gate.
const holdguard = { labels: ['hold'], hive_attributed: true, hold_sources: ['holdguard'] };
check('holdguard does not claim the level gate', !heldReason(holdguard).includes('ACMM level gate'));
check('a recorded level gate keeps the sentence', heldReason({ labels: ['hold'], hive_attributed: true, hold_sources: ['level_gate'] }).includes('ACMM level gate'));

const reporterHeld = { labels: ['hold', 'needs-human'], hive_attributed: true, reporter_trust_reason: 'reporter-trust hold — issue #42 filed by @outsider' };
check('reporter hold names the request reporter', heldReason(reporterHeld).includes(reporterHeld.reporter_trust_reason));
check('reporter hold does not claim exhausted fixes', !heldReason(reporterHeld).includes('automated fix attempts exhausted'));
Expand Down
10 changes: 8 additions & 2 deletions src/pkg/dashboard/static-src/js/repos.js
Original file line number Diff line number Diff line change
Expand Up @@ -696,12 +696,18 @@
const held = holdLabels(labels);
const needsHuman = labels.includes('needs-human');
const parts = [];
parts.push('On hold' + (held.length ? ' — label ' + held.map(l => '`' + l + '`').join(', ') : '') + ': agents will not act on this until the hold label is removed');
// Same wording as the Go heldReason (bands.go): a hold label is named
// only when the item wears one, and the ACMM sentence only for a
// generic hold whose sources are unknown or name the level gate.
parts.push(held.length
? 'On hold — label ' + held.map(l => '`' + l + '`').join(', ') + ': agents will not act on this until the hold label is removed'
: 'On hold: agents will not act on this until what holds it is cleared');
if (item && item.reporter_trust_reason) {
parts.push(item.reporter_trust_reason);
return parts.join('; ');
}
if (item && item.hive_attributed) parts.push('opened by a hive agent — a generic `hold` here is usually the ACMM level gate; the dashboard hive-pause hold is only removed by an operator');
const sources = (item && Array.isArray(item.hold_sources)) ? item.hold_sources : [];
if (item && item.hive_attributed && held.length && (!sources.length || sources.includes('level_gate'))) parts.push('opened by a hive agent — a generic `hold` here is usually the ACMM level gate; the dashboard hive-pause hold is only removed by an operator');
if (needsHuman) parts.push('labelled needs-human: automated fix attempts exhausted');
return parts.join('; ');
}
Expand Down
10 changes: 8 additions & 2 deletions src/pkg/dashboard/static/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -32495,12 +32495,18 @@ <h4 style="margin:14px 0 6px">Approval and audit records</h4>${approval}`;
const held = holdLabels(labels);
const needsHuman = labels.includes('needs-human');
const parts = [];
parts.push('On hold' + (held.length ? ' — label ' + held.map(l => '`' + l + '`').join(', ') : '') + ': agents will not act on this until the hold label is removed');
// Same wording as the Go heldReason (bands.go): a hold label is named
// only when the item wears one, and the ACMM sentence only for a
// generic hold whose sources are unknown or name the level gate.
parts.push(held.length
? 'On hold — label ' + held.map(l => '`' + l + '`').join(', ') + ': agents will not act on this until the hold label is removed'
: 'On hold: agents will not act on this until what holds it is cleared');
if (item && item.reporter_trust_reason) {
parts.push(item.reporter_trust_reason);
return parts.join('; ');
}
if (item && item.hive_attributed) parts.push('opened by a hive agent — a generic `hold` here is usually the ACMM level gate; the dashboard hive-pause hold is only removed by an operator');
const sources = (item && Array.isArray(item.hold_sources)) ? item.hold_sources : [];
if (item && item.hive_attributed && held.length && (!sources.length || sources.includes('level_gate'))) parts.push('opened by a hive agent — a generic `hold` here is usually the ACMM level gate; the dashboard hive-pause hold is only removed by an operator');
if (needsHuman) parts.push('labelled needs-human: automated fix attempts exhausted');
return parts.join('; ');
}
Expand Down
Loading