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-stage-label-suppressed-state.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- A PR stage the write-back gate kept off GitHub now drives the Overview bands and the your-turn inbox, and the hive no longer announces a label it did not write. On projectbluefin the gate refused every 072/074/085 label on 24 contributor and fork PRs (opt-in label missing, or the backfill guard) from 10-30 on; the stage engine recorded the stage, but bands and ownership read labels, so a PR parked at 085 showed "blocked" with no reason and was in nobody's inbox, while its note said "Moving to `stage/085-needs-decision` so a person sees it" (projectbluefin/fsdk-containers#491, projectbluefin/utah-packages#812). The snapshot now carries the recorded stage beside GitHub's labels (`suppressed_stage`), band and ownership read it, the inbox reason says the label is not on GitHub, the Activity Monitor row's tooltip names the gate's reason (`labels_suppressed`), and escalation notes say the hive would move the PR and why it did not.
11 changes: 11 additions & 0 deletions src/docs/acmm-policy-matrix.md
Original file line number Diff line number Diff line change
Expand Up @@ -255,6 +255,17 @@ listed only so an agent can file regression issues should carry
`backfill: false` (default) additionally keeps every kind off items that
predate hive's first sight of, or write access to, the repo.

"Internal tracking" means the stage engine still records the PR's stage
when the gate keeps its `stage_label` write off GitHub: the record carries
`labels_suppressed` and the gate's reason, the Overview bands and the
your-turn inbox read that stage in place of the missing label (a refused 085
park is still *Parked until a maintainer decides*), the Activity Monitor row
says "Stage label not on GitHub" with the reason, and an escalation note
says the hive *would* move the PR to `stage/085-needs-decision` and why it
did not instead of "Moving to". The backfill guard applies to
`stage_label` like every other kind; with the stage tracked internally an
older PR is still in the inbox, only unlabelled on GitHub.

## Example config alignment

`src/hive.yaml.example` uses the built-in `quality` lane for automated test suites, coverage gates, and regression checks. There is no built-in `tester` lane in the ACMM packs, known-agent defaults, or shipped policy templates; operators who want a separate tester must define it as a custom agent with explicit metadata and a policy template.
Expand Down
11 changes: 7 additions & 4 deletions src/pkg/dashboard/overview_export.go
Original file line number Diff line number Diff line change
Expand Up @@ -479,8 +479,11 @@ func holdItemIssue(item github.HoldItem) github.Issue {
}

type frontendPR struct {
// pr is the PR as the hive tracks it (withSuppressedStage); wire is the
// snapshot entry as published, with GitHub's labels.
pr github.PullRequest
verdict *github.MergeVerdict
wire FrontendPR
}

func frontendRepoPRs(repo FrontendRepo, held bool) []frontendPR {
Expand All @@ -500,19 +503,19 @@ func frontendRepoPRs(repo FrontendRepo, held bool) []frontendPR {
func frontendPullRequest(raw any) (frontendPR, bool) {
switch v := raw.(type) {
case FrontendPR:
return frontendPR{pr: v.PullRequest, verdict: v.MergeVerdict}, true
return frontendPR{pr: withSuppressedStage(v.PullRequest, v.SuppressedStage), verdict: v.MergeVerdict, wire: v}, true
case *FrontendPR:
if v == nil {
return frontendPR{}, false
}
return frontendPR{pr: v.PullRequest, verdict: v.MergeVerdict}, true
return frontendPR{pr: withSuppressedStage(v.PullRequest, v.SuppressedStage), verdict: v.MergeVerdict, wire: *v}, true
case github.PullRequest:
return frontendPR{pr: v}, true
return frontendPR{pr: v, wire: FrontendPR{PullRequest: v}}, true
case *github.PullRequest:
if v == nil {
return frontendPR{}, false
}
return frontendPR{pr: *v}, true
return frontendPR{pr: *v, wire: FrontendPR{PullRequest: *v}}, true
default:
return frontendPR{}, false
}
Expand Down
2 changes: 1 addition & 1 deletion src/pkg/dashboard/overview_status.go
Original file line number Diff line number Diff line change
Expand Up @@ -217,7 +217,7 @@ func (s *Server) statusWithOverviewBands(status *StatusPayload, now time.Time) *
slice := overviewPRChartSlice(entry.pr, entry.verdict, ownership, autoMergeLabel)
term := overviewPRTerm(ownership, held || len(holdLabels(entry.pr.Labels, status.HiveID)) > 0, entry.pr, entry.verdict, autoMergeLabel)
countSlice(slices.PRs, slice)
result = append(result, overviewStatusPR{FrontendPR{entry.pr, entry.verdict}, info, ownership, slice, term, criticalPathFor(paths, ownershipKindPR, entry.pr.Number)})
result = append(result, overviewStatusPR{entry.wire, info, ownership, slice, term, criticalPathFor(paths, ownershipKindPR, entry.pr.Number)})
}
return result
}
Expand Down
2 changes: 1 addition & 1 deletion src/pkg/dashboard/ownership.go
Original file line number Diff line number Diff line change
Expand Up @@ -923,7 +923,7 @@ func decideRepoOwnership(repos []FrontendRepo, cfg config.DashboardIssueBandsCon
}
pr := entry.pr
pr.Repo = nonEmpty(pr.Repo, repoName)
record(ownershipKindPR, pr.Number, pr.URL, decidePROwnershipGated(pr, entry.verdict, held, cfg, env), pr.CreatedAt, pr.UpdatedAt)
record(ownershipKindPR, pr.Number, pr.URL, withSuppressedStageNote(decidePROwnershipGated(pr, entry.verdict, held, cfg, env), entry.wire.SuppressedStage), pr.CreatedAt, pr.UpdatedAt)
}
}
prRows(repo.OpenPrs, false)
Expand Down
78 changes: 78 additions & 0 deletions src/pkg/dashboard/pr_suppressed_stage.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
package dashboard

import (
"strings"

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

// Stage labels the write-back gate kept off a PR (hivecommons/hive#15122
// containment). The stage engine still records the stage, but the bands and
// the your-turn decision read labels, so a contributor PR the hive parked at
// 085 showed as "blocked" with no reason and was in nobody's inbox
// (projectbluefin, 2026-10-30 → 11-05: 24 PRs, among them
// projectbluefin/fsdk-containers#491 and projectbluefin/utah-packages#812).
// The snapshot carries the recorded stage beside the real labels, and every
// reader that decodes a PR (frontendPullRequest) sees it in place of the
// stage labels GitHub has.

// attachSuppressedStages stamps each snapshot PR whose last stage write the
// gate refused with the stage its record holds.
func attachSuppressedStages(repos []FrontendRepo, store *stagelabels.Store) {
if store == nil {
return
}
for ri := range repos {
repoName := overviewRepoName(repos[ri])
stamp := func(items []any) {
for i, raw := range items {
fp, ok := raw.(FrontendPR)
if !ok {
continue
}
fp.SuppressedStage, fp.SuppressedStageReason = suppressedStageFor(store, nonEmpty(fp.Repo, repoName), fp.Number)
items[i] = fp
}
}
stamp(repos[ri].OpenPrs)
stamp(repos[ri].HeldPrs)
}
}

// suppressedStageFor is the PR stage label the record holds while the gate
// keeps labels off the item, with the gate's reason; "" otherwise.
func suppressedStageFor(store *stagelabels.Store, repo string, number int) (string, string) {
rec, ok := store.Get(stagelabels.Key(repo, number))
if !ok || !rec.LabelsSuppressed || !rec.Stage.Applies(stagelabels.PRItem) {
return "", ""
}
return rec.Stage.Label(), rec.LabelsSuppressedReason
}

// withSuppressedStage is pr as the hive tracks it: its stage/* labels
// replaced by stage, the one it could not write. Labels are copied; the
// snapshot keeps what GitHub shows.
func withSuppressedStage(pr github.PullRequest, stage string) github.PullRequest {
if stage == "" {
return pr
}
labels := make([]string, 0, len(pr.Labels)+1)
for _, l := range pr.Labels {
if !strings.HasPrefix(strings.ToLower(strings.TrimSpace(l)), "stage/") {
labels = append(labels, l)
}
}
pr.Labels = append(labels, stage)
return pr
}

// withSuppressedStageNote tells the person a your-turn PR was put in front
// of that GitHub does not show the stage: they will not find the label.
func withSuppressedStageNote(o Ownership, stage string) Ownership {
if stage == "" || !o.YourTurn {
return o
}
o.Reason += " (the hive holds it at " + stage + "; the write-back gate kept the label off GitHub)"
return o
}
100 changes: 100 additions & 0 deletions src/pkg/dashboard/pr_suppressed_stage_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
package dashboard

import (
"strings"
"testing"
"time"

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

// projectbluefin, 10-30 → 11-05: the write-back gate kept every 072/074/085
// label off 24 contributor and fork PRs while the stage engine recorded the
// stage. Bands and your-turn read labels, so a PR parked at 085 showed
// "blocked" with no reason and your_turn=false
// (projectbluefin/fsdk-containers#491, projectbluefin/utah-packages#812,
// which still wore a stale stage/074). The record now stands in for the
// label it could not write: band and ownership match the written label.
func TestSuppressedStageDrivesBandAndOwnership(t *testing.T) {
now := ownershipNow11565
mk := func(labels ...string) FrontendPR {
return FrontendPR{PullRequest: github.PullRequest{
Repo: "projectbluefin/utah-packages", Number: 812, Title: "fix: pin", Author: "arteeh",
Labels: labels, Mergeable: github.MergeableNo, CreatedAt: now.Add(-6 * 24 * time.Hour), UpdatedAt: now.Add(-time.Hour),
}}
}
decide := func(fp FrontendPR) (Ownership, string) {
repos := []FrontendRepo{{Name: "utah-packages", Full: "projectbluefin/utah-packages", OpenPrs: []any{fp}}}
decideRepoOwnership(repos, config.DashboardIssueBandsConfig{}, ownershipEnv11565(5))
o := repos[0].Ownership[ownershipKey(ownershipKindPR, 812)]
entry, _ := frontendPullRequest(repos[0].OpenPrs[0])
return o, prBand(entry.pr, entry.verdict, false, config.DashboardIssueBandsConfig{}, now, github.AutoMergeQueuedLabel, "").Band
}

written, writtenBand := decide(mk("role/trusted", stagelabels.NeedsDecision.Label()))
if !written.YourTurn || written.ReasonCode != OwnershipReasonParkedNeedsDecision {
t.Fatalf("fixture: written 085 = %+v, want your turn, parked_needs_decision", written)
}

store := stagelabels.NewStore("", func() time.Time { return now })
key := stagelabels.Key("projectbluefin/utah-packages", 812)
store.Observe(key, stagelabels.NeedsDecision, "adoption-stalled:reviewer-verdict:changes_requested")
store.NoteLabelsSuppressed(key, true, "needs-opt-in-label — #812 carries none of hive-review")
repos := []FrontendRepo{{Name: "utah-packages", Full: "projectbluefin/utah-packages", OpenPrs: []any{mk("role/trusted", stagelabels.AdoptedByHive.Label())}}}
attachSuppressedStages(repos, store)
fp := repos[0].OpenPrs[0].(FrontendPR)
if fp.SuppressedStage != stagelabels.NeedsDecision.Label() || !strings.Contains(fp.SuppressedStageReason, "needs-opt-in-label") {
t.Fatalf("attached = %q / %q, want the recorded 085 and the gate's reason", fp.SuppressedStage, fp.SuppressedStageReason)
}
if len(fp.Labels) != 2 || fp.Labels[1] != stagelabels.AdoptedByHive.Label() {
t.Fatalf("the snapshot keeps GitHub's labels: %v", fp.Labels)
}

got, gotBand := decide(fp)
if !got.YourTurn || got.ReasonCode != written.ReasonCode || got.Verb != written.Verb {
t.Fatalf("suppressed 085 = %+v, want the written label's decision %+v", got, written)
}
if !strings.HasPrefix(got.Reason, written.Reason) || !strings.Contains(got.Reason, "kept the label off GitHub") {
t.Fatalf("reason = %q, want %q plus why GitHub shows no label", got.Reason, written.Reason)
}
if gotBand != writtenBand || gotBand != "waiting" {
t.Fatalf("band = %q, written label gives %q; want both waiting", gotBand, writtenBand)
}

// The same record with its write landed (labels carry the stage) or no
// record at all: nothing is attached, the labels decide as before.
store.NoteLabelsSuppressed(key, false, "")
repos[0].OpenPrs[0] = mk("role/trusted", stagelabels.AdoptedByHive.Label())
attachSuppressedStages(repos, store)
if fp := repos[0].OpenPrs[0].(FrontendPR); fp.SuppressedStage != "" {
t.Fatalf("landed write still attached %q", fp.SuppressedStage)
}
if o, _ := decide(repos[0].OpenPrs[0].(FrontendPR)); o.ReasonCode == OwnershipReasonParkedNeedsDecision {
t.Fatalf("no suppression: the stale record must not park the PR: %+v", o)
}
}

func TestStageTrackerRowNamesSuppressedLabels(t *testing.T) {
now := time.Date(2026, 10, 29, 20, 30, 0, 0, time.UTC)
s, store, status := offlineClankerFixture(t, now, now.Add(-3*time.Hour))
key := stagelabels.Key("hivecommons/hive", 15312)
store.Observe(key, stagelabels.NeedsDecision, "contributor-lane:decision-requested")
store.NoteLabelsSuppressed(key, true, "needs-opt-in-label — #15312 carries none of hive-review")
if it := trackerItem(t, s.buildStageTracker(status, store, now), "pr", 15312); !strings.HasPrefix(it.LabelsSuppressed, "needs-opt-in-label") {
t.Fatalf("row labels_suppressed = %q, want the gate's reason", it.LabelsSuppressed)
}
store.NoteLabelsSuppressed(key, false, "")
if it := trackerItem(t, s.buildStageTracker(status, store, now), "pr", 15312); it.LabelsSuppressed != "" {
t.Fatalf("landed write: row labels_suppressed = %q, want empty", it.LabelsSuppressed)
}

html := indexHTML(t)
runStageTrackerRowActionsScript(t, "const assert = require('assert');\n"+jsFunc(t, html, "stageTrackerLabelsSuppressedText")+`
assert.strictEqual(stageTrackerLabelsSuppressedText({}), '');
const tip = stageTrackerLabelsSuppressedText({ labels_suppressed: 'needs-opt-in-label — #812 carries none of hive-review' });
assert.ok(tip.startsWith('Stage label not on GitHub'), tip);
assert.ok(tip.includes('needs-opt-in-label'), tip);
`)
}
1 change: 1 addition & 0 deletions src/pkg/dashboard/server.go
Original file line number Diff line number Diff line change
Expand Up @@ -2917,6 +2917,7 @@ func (s *Server) UpdateStatusIfFresh(status *StatusPayload, buildEpoch uint64) b
status.RepoTargetIssue = ""
}
}
attachSuppressedStages(status.Repos, s.stageStoreOrShared())
status.ContributorPool = s.BuildContributorPoolStatus()
status.Inception = s.buildFrontendInception()
if s.contributeHub != nil {
Expand Down
4 changes: 4 additions & 0 deletions src/pkg/dashboard/stage_tracker.go
Original file line number Diff line number Diff line change
Expand Up @@ -574,6 +574,10 @@ type StageTrackerItem struct {
// label on its next pass, hivecommons/hive#14586). Rendered as a muted
// operator tooltip, never as the stage word.
StaleLabels []string `json:"stale_labels,omitempty"`
// LabelsSuppressed is the write-back gate's reason when it kept this
// row's stage label off GitHub: the stage shown is the hive's record,
// not a label on the item. "" when the labels carry the stage.
LabelsSuppressed string `json:"labels_suppressed,omitempty"`
// MergeTrain is set on a PR riding a conflict-aware merge train
// (hivecommons/hive#15117): its position, the front, the PRs ahead and
// the overlapping files. See stage_tracker_merge_train.go.
Expand Down
3 changes: 3 additions & 0 deletions src/pkg/dashboard/stage_tracker_build.go
Original file line number Diff line number Diff line change
Expand Up @@ -140,6 +140,9 @@ func (s *Server) buildStageTracker(status *StatusPayload, store *stagelabels.Sto
it.DCOTotal, it.DCOUnsigned = total, unsigned
}
}
if hasRec && rec.LabelsSuppressed && rec.Stage != stagelabels.None {
it.LabelsSuppressed = nonEmpty(rec.LabelsSuppressedReason, "write-back gate")
}
it.Hold = stageTrackerHoldFrom(rec, hasRec, labels)
var attempt github.MergeAttempt
var hasAttempt bool
Expand Down
4 changes: 2 additions & 2 deletions src/pkg/dashboard/stage_tracker_offline_clanker_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ func TestStageTrackerSuppressedDecisionRecordKeepsStage(t *testing.T) {
s, store, status := offlineClankerFixture(t, now, now.Add(-3*time.Hour))
key := stagelabels.Key("hivecommons/hive", 15312)
store.Observe(key, stagelabels.NeedsDecision, "contributor-lane:decision-requested")
store.NoteLabelsSuppressed(key, true)
store.NoteLabelsSuppressed(key, true, "needs-opt-in-label")
it := trackerItem(t, s.buildStageTracker(status, store, now), "pr", 15312)
if it.Stage != stagelabels.NeedsDecision.Number() || it.StageSince == nil {
t.Fatalf("suppressed 085 record: stage %d since %v caption %q, want 085 from the record", it.Stage, it.StageSince, it.Caption)
Expand All @@ -61,7 +61,7 @@ func TestStageTrackerSuppressedDecisionRecordKeepsStage(t *testing.T) {
}
// The same record with the label write landed and then removed is a
// lifted park, as before.
store.NoteLabelsSuppressed(key, false)
store.NoteLabelsSuppressed(key, false, "")
if it := trackerItem(t, s.buildStageTracker(status, store, now), "pr", 15312); it.Stage == stagelabels.NeedsDecision.Number() {
t.Fatalf("label-less 085 record with labels not suppressed still parks the row: %+v", it)
}
Expand Down
8 changes: 8 additions & 0 deletions src/pkg/dashboard/static-src/js/tracker-actions.js
Original file line number Diff line number Diff line change
Expand Up @@ -292,6 +292,14 @@
if (!stale.length) return '';
return 'Stale label' + (stale.length > 1 ? 's' : '') + ': ' + stale.join(', ') + ' (stage has moved on; the hive removes it on its next pass)';
}
// Pure: the operator note for a stage the write-back gate kept off
// GitHub (labels_suppressed: the gate's reason). The row's stage is the
// hive's record; the item carries no such label. '' when none.
function stageTrackerLabelsSuppressedText(item) {
const why = item && typeof item.labels_suppressed === 'string' ? item.labels_suppressed.trim() : '';
if (!why) return '';
return 'Stage label not on GitHub: the write-back gate refused it (' + why + '). The hive tracks this stage itself.';
}
// Pure: whether a row is an issue waiting on a maintainer's triage.
function stageTrackerTriageNeeded(item) {
if (!item || item.kind === 'pr') return false;
Expand Down
2 changes: 2 additions & 0 deletions src/pkg/dashboard/static-src/js/tracker-row-strip.js
Original file line number Diff line number Diff line change
Expand Up @@ -723,6 +723,8 @@
if (mods.length) lines.push('Flags: ' + mods.map(m => STAGE_TRACKER_MOD_TEXT[m] || m).join(', '));
const stale = stageTrackerStaleLabelsText(item);
if (stale) lines.push(stale);
const suppressed = typeof stageTrackerLabelsSuppressedText === 'function' ? stageTrackerLabelsSuppressedText(item) : '';
if (suppressed) lines.push(suppressed);
const deferred = stageTrackerDeferredMods(item);
if (deferred.length) lines.push(STAGE_TRACKER_DEFERRED_NOTE + deferred.map(m => STAGE_TRACKER_MOD_TEXT[m] || m).join(', '));
if (item.sentinel_alert && deferred.indexOf(STAGE_TRACKER_SENTINEL_CHIP) < 0) lines.push(stageTrackerSentinelTip(item));
Expand Down
10 changes: 10 additions & 0 deletions src/pkg/dashboard/static/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -19110,6 +19110,8 @@ <h3 class="faq-group-title">Where to get help</h3>
if (mods.length) lines.push('Flags: ' + mods.map(m => STAGE_TRACKER_MOD_TEXT[m] || m).join(', '));
const stale = stageTrackerStaleLabelsText(item);
if (stale) lines.push(stale);
const suppressed = typeof stageTrackerLabelsSuppressedText === 'function' ? stageTrackerLabelsSuppressedText(item) : '';
if (suppressed) lines.push(suppressed);
const deferred = stageTrackerDeferredMods(item);
if (deferred.length) lines.push(STAGE_TRACKER_DEFERRED_NOTE + deferred.map(m => STAGE_TRACKER_MOD_TEXT[m] || m).join(', '));
if (item.sentinel_alert && deferred.indexOf(STAGE_TRACKER_SENTINEL_CHIP) < 0) lines.push(stageTrackerSentinelTip(item));
Expand Down Expand Up @@ -23110,6 +23112,14 @@ <h2 class="config-title" id="activity-monitor-labels-title">All labels</h2>
if (!stale.length) return '';
return 'Stale label' + (stale.length > 1 ? 's' : '') + ': ' + stale.join(', ') + ' (stage has moved on; the hive removes it on its next pass)';
}
// Pure: the operator note for a stage the write-back gate kept off
// GitHub (labels_suppressed: the gate's reason). The row's stage is the
// hive's record; the item carries no such label. '' when none.
function stageTrackerLabelsSuppressedText(item) {
const why = item && typeof item.labels_suppressed === 'string' ? item.labels_suppressed.trim() : '';
if (!why) return '';
return 'Stage label not on GitHub: the write-back gate refused it (' + why + '). The hive tracks this stage itself.';
}
// Pure: whether a row is an issue waiting on a maintainer's triage.
function stageTrackerTriageNeeded(item) {
if (!item || item.kind === 'pr') return false;
Expand Down
5 changes: 5 additions & 0 deletions src/pkg/dashboard/status_builder.go
Original file line number Diff line number Diff line change
Expand Up @@ -1823,6 +1823,11 @@ func openPRIsMergeable(pr any) bool {
type FrontendPR struct {
github.PullRequest
MergeVerdict *github.MergeVerdict `json:"merge_verdict,omitempty"`
// SuppressedStage is the stage label the hive holds this PR at but the
// write-back gate kept off GitHub, with the gate's reason
// (attachSuppressedStages); "" when the labels carry the stage.
SuppressedStage string `json:"suppressed_stage,omitempty"`
SuppressedStageReason string `json:"suppressed_stage_reason,omitempty"`
}

// AttachMergeVerdicts stamps the governor's per-PR merge verdicts onto the
Expand Down
Loading
Loading