Skip to content

πŸ› fix(stage): a stage label the write-back gate refused still drives band and your-turn - #16818

Merged
hivecommons-hive[bot] merged 1 commit into
hivecommons:v6from
Danathar:fix/stage-label-suppressed-state
Nov 5, 2026
Merged

hivecommons-hive[bot] merged 1 commit into
hivecommons:v6from
Danathar:fix/stage-label-suppressed-state

Conversation

@Danathar

@Danathar Danathar commented Nov 5, 2026

Copy link
Copy Markdown
Contributor

Executive summary

When the write-back gate keeps a stage label off a contributor or fork PR, the stage engine still records the stage, but the Overview bands and the your-turn inbox read labels. On projectbluefin the gate refused every 072/074/085 label on 24 PRs from 10-30 on. A PR the hive parked at 085 showed as "blocked" with no reason and sat in nobody's inbox, while the hive's own note said "Moving to stage/085-needs-decision so a person sees it".

This PR makes the recorded stage stand in for the label it could not write:

  • Band and ownership match what the written label would give.
  • The inbox reason says the label is not on GitHub.
  • The Activity Monitor row names the gate's reason.
  • Escalation notes say the hive would move the PR, and why it did not.

What

Before (label refused) After
Band from labels: "blocked" (or whatever the stale stage label said) Band from the recorded stage: 085 β†’ "waiting", same as the written label
your_turn=false, reason "" Your turn, Parked until a maintainer decides (the hive holds it at stage/085-needs-decision; the write-back gate kept the label off GitHub)
Note: "Moving to stage/085-needs-decision so a person sees it." "The hive would move this to stage/085-needs-decision, but the write-back gate keeps its labels off this PR (needs-opt-in-label β€” …), so no label changes here. The hive tracks it at stage/085-needs-decision and lists it on the dashboard so a person sees it."
Activity Monitor row: stage from the record, nothing says why no label Tooltip line: "Stage label not on GitHub: the write-back gate refused it ()."
Opted-in PR / write landed Unchanged

Why

Write-back containment (#15122) gates stage_label on PRs the hive did not open. It needs the opt-in label (hive-review) and applies the backfill guard (stage_labeler.go writeAllowed, writeback/gate.go decideLocked). stageWriter.Apply then reports Suppressed, and the reconciler marks the record labels_suppressed. The stage tracker already honoured that mark (#15541). Nothing else did:

  • prBand and decidePROwnershipGated / prGateLabelOwnership read pr.Labels.
  • postAdoptionEscalationNote posted "Moving to stage/085…" without asking whether the label could land.

Checked live on GitHub:

PR Hive note Labels on the PR now
projectbluefin/fsdk-containers#491 "Moving to 085" 10-31, 11-04 none
projectbluefin/utah-packages#812 "Moving to 085" 10-31, 11-01 stage/stalled, stage/074-adopted-by-hive, …
projectbluefin/bluefin-bling#128 "Moving to 085" 11-03 stage/050-review-pending, …
projectbluefin/utah#1091 "Moving to 085" 11-03 stage/085-needs-decision (after the operator's require_label=false)

How

  • Reason on the record: stagelabels.Outcome.SuppressedReason carries the gate's reason (stage_labeler.go keeps reason + detail). Store.NoteLabelsSuppressed(key, suppressed, reason) stores it as LabelsSuppressedReason, cleared when a write lands.
  • Snapshot: attachSuppressedStages runs in UpdateStatusIfFresh and stamps FrontendPR.SuppressedStage / SuppressedStageReason from the record. The published labels stay GitHub's.
  • Readers: frontendPullRequest (the decoder every band, ownership and Overview path uses) returns the PR with its stage/* labels replaced by the suppressed stage, so prBand and the ownership rules see what a written label would give. frontendPR.wire keeps the published form for /api/overview/status. withSuppressedStageNote appends the "not on GitHub" clause to a your-turn reason.
  • Row: StageTrackerItem.LabelsSuppressed carries the reason; stageTrackerLabelsSuppressedText adds the tooltip line.
  • Notes: postAdoptionEscalationNote runs every escalation note (adoption stalled, workflow refused, fork not adopted) through withStageMoveFact. That asks the gate with the new writeback.Gate.Decide, which is Allowed without recording a suppression, since the stage writer records its own. On a refusal it rewrites "Moving to …".
  • Backfill guard (not changed): stage_label stays under the backfill guard. The guard exists so the hive does not start labelling items nobody asked it about. With the stage tracked internally, those PRs now reach the inbox anyway, so exempting the kind would only add labels to old contributor PRs. The 6 backfill-blocked projectbluefin PRs become your-turn without a config change.

Files

File Change
src/pkg/stagelabels/enforce.go, store.go SuppressedReason, LabelsSuppressedReason, reason-aware NoteLabelsSuppressed
src/pkg/stageengine/reconciler.go, src/pkg/github/stage_writer.go, stage_labeler.go Pass the gate's reason through
src/pkg/writeback/gate.go Gate.Decide (no suppression record)
src/pkg/dashboard/pr_suppressed_stage.go (new), status_builder.go, server.go Attach the recorded stage to snapshot PRs
src/pkg/dashboard/overview_export.go, overview_status.go, ownership.go Readers use it; published form unchanged; inbox note
src/pkg/dashboard/stage_tracker*.go, static-src/js/tracker-*.js, static/index.html Row field and tooltip line
src/pkg/github/automerge/automerge_contributor_adopt.go Escalation notes say when the label is refused
src/docs/acmm-policy-matrix.md, changelog.d/… What "internal tracking" now means

Tests

Test Covers
TestSuppressedStageDrivesBandAndOwnership refused 085 = written 085: your turn parked_needs_decision, band waiting; reason names the label; stale stage/074 replaced; landed write β†’ no overlay
TestStageTrackerRowNamesSuppressedLabels row labels_suppressed; JS tooltip line
TestEscalationNoteSaysWhenTheStageLabelIsRefused, TestPostedEscalationNote… all three escalation notes rewritten on refusal (opt-in and backfill), unchanged when opted in or no gate; no extra suppression record
TestDecideAnswersLikeAllowedWithoutRecording Decide = Allowed, records nothing
TestReconcileRecordsSuppressedLabels (extended), TestNoteLabelsSuppressedKeepsReasonOnlyWhileSuppressed reason stored, replaced, cleared on a landed write
Mutants 12/12 caught
go test writeback, stagelabels, stageengine, github/..., dashboard/..., cmd/hive; node 332; dashboard-gen-check pass
check-docs-citations.py src/docs 2006 verified

Notes

  • Overlap: sibling fixes for band classification ("eligible" when the hive will not merge; hand-merge reason) touch bands.go / ownership_gates.go. This PR adds no logic there; it only changes what frontendPullRequest hands them.
  • Not done: the generic hive:stage-needs-decision entry comment (needs_decision_comment kind) has its own gate check and does not claim a label move, so it is unchanged.

πŸ€– Generated with Claude Code

https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1

…band and your-turn

The gate kept every 072/074/085 label off 24 projectbluefin contributor and
fork PRs (opt-in label missing or backfill guard). The stage engine recorded
the stage, but bands and ownership read labels, so a PR parked at 085 was
"blocked" with no reason and in nobody's inbox, while the escalation note
said "Moving to stage/085-needs-decision" (projectbluefin/fsdk-containers#491).

- Record the gate's reason (Outcome.SuppressedReason, LabelsSuppressedReason).
- attachSuppressedStages stamps the recorded stage on snapshot PRs;
  frontendPullRequest hands band/ownership the PR with that stage in place
  of its stage labels; the published labels stay GitHub's.
- Inbox reason and Activity Monitor tooltip say the label is not on GitHub.
- Escalation notes ask the gate (new Gate.Decide, no suppression record)
  and say the hive would move the PR and why it did not.
- The backfill guard still applies to stage_label (see docs).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1
Signed-off-by: Danathar <Danathar@users.noreply.github.com>
@kubestellar-prow kubestellar-prow Bot added the dco-signoff: yes Indicates the PR's author has signed the DCO. label Nov 5, 2026
@kubestellar-prow

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign nicholasjackson for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@kubestellar-prow kubestellar-prow Bot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Nov 5, 2026
@github-actions

github-actions Bot commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Open PR overlap check

Base branch: v6

Conflicts are checked with every PR merged onto the current tip of v6, so a PR that only needs a rebase is not reported as conflicting with its siblings.

PR Title Relation Files
#16816 πŸ› fix(adoption): refuse a fixer push that undoes the adopted PR's change same files src/pkg/github/automerge/automerge_contributor_adopt.go
src/pkg/stagelabels/store.go
#16807 πŸ› fix: route workflow blockers to capable lanes same files src/pkg/dashboard/stage_tracker_build.go
src/pkg/dashboard/static-src/js/tracker-actions.js
src/pkg/dashboard/static/index.html
#16688 🌱 Forward-merge v5 into v6 (2 commits) same files src/pkg/dashboard/static/index.html
src/pkg/github/automerge/automerge_contributor_adopt.go
src/pkg/stagelabels/store.go

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Read the gate/store/reconciler/writer changes, withStageMoveFact in automerge_contributor_adopt.go, and pr_suppressed_stage.go at head c589285. The core change looks correct to me.

Verified:

  • writeback.Gate.Decide (gate.go:400) is genuinely side-effect-free: it takes the lock and calls only decideLocked, which reads pause/config/opt-in/backfill state and never writes. The recording happens in AllowedPreview:430-432 (suppressLocked), which Decide skips β€” so the 085 note no longer counts as a second refusal while the stage writer still records its own.
  • NoteLabelsSuppressed (stagelabels/store.go:2722-2735) clears the reason when suppressed=false and only dirties the store when either field changes; stage_writer.go:42 copies l.reason, which stage_labeler.go:66-70 now sets to reason + detail. The reconciler is the only caller and was updated.
  • suppressedStageMove replaces the literal "Moving to " once; every escalation note I checked still ends with that exact phrase, so the rewrite applies. If a future note phrases it differently the body is just left intact, which is the safe failure.

One small thing (low, style): the new Decide was inserted between Allowed's doc comment and Allowed (writeback/gate.go:395-411). The paragraph "Allowed is the gate. repo is "owner/name" …" now attaches to Decide in godoc, and Allowed is left undocumented. Moving Decide and its comment below Allowed fixes it.

β€” hive: agent=reviewer-2 backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive

hivecommons-hive Bot commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Hive status β€” updated in place; edits do not notify. Full history is in the Activity Monitor.

Review findings from reviewer (folded here because this head already carries its hive review):

Read the gate, stage writer/labeler, reconciler, store and the adoption-note rewrite at head c589285. The backend change is correct; one doc-comment misplacement worth fixing before merge.

Verified

  • writeback/gate.go:401-409 Decide takes the gate lock and calls decideLocked only; the refusal bookkeeping lives in AllowedPreview (:417-432), so asking the gate from the 085 note (automerge_contributor_adopt.go:2123) records nothing, as the comment promises, and the stage writer still records its own refusal when it tries.
  • stagelabels/store.go:2727-2735 NoteLabelsSuppressed clears the reason when suppressed is false and only dirties the record when either field changes β€” a resolved refusal cannot leave a stale reason behind, and an unchanged pass does not churn the store.
  • suppressedStageMove (:2134-2141) replaces exactly the Moving to \stage/085-needs-decision`` phrase the escalation comments end with; a body without that phrase is returned unchanged.

Low (style) β€” Decide was inserted between Allowed's doc comment and Allowed (writeback/gate.go:396-412)

// Allowed is the gate. repo is "owner/name" (any case); item describes the
// target; kind names the write. ...
// Decide is what Allowed would answer, without recording a refusal: ...
func (g *Gate) Decide(repo string, item Item, kind Kind) Decision {
...
func (g *Gate) Allowed(repo string, item Item, kind Kind) Decision {

godoc now attaches the "Allowed is the gate…" paragraph to Decide, and Allowed β€” the exported entry point every writer calls β€” has no doc comment. The linter passed because the comment starts with a sentence, but the text is wrong for the function it documents. Moving the Decide block above the // Allowed is the gate comment (or below Allowed) fixes it.

Nothing else found. Not approving (human signature).

Evidence bundle `#16818c589285` sha256:60e30be781ddfa605bb023aa8a1f3f2fe88da1d72cfca015e9d55cdffa5f5c7a β€” download from the dashboard or `hivectl review evidence #16818`.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

dco-signoff: yes Indicates the PR's author has signed the DCO. size/L Denotes a PR that changes 100-499 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant