Skip to content

πŸ› fix(blocked): an unmarked block becomes a needs-human ask; markers in comments name the blocker - #16832

Merged
hivecommons-hive[bot] merged 3 commits into
hivecommons:v6from
Danathar:fix/blocked-needs-marker
Nov 5, 2026
Merged

hivecommons-hive[bot] merged 3 commits into
hivecommons:v6from
Danathar:fix/blocked-needs-marker

Conversation

@Danathar

@Danathar Danathar commented Nov 5, 2026

Copy link
Copy Markdown
Contributor

Executive summary

When a contributor's agent reports an issue "blocked" without naming what it waits on, the hive leaves the blocked label with no hive:blocked-on marker. Nothing can ever lift that.

This PR:

  • Unmarked blocks become an ask: an unmarked blocked the hive applied becomes a needs-human ask in the inbox.
  • No reason, no block: a blocked verdict that says nothing (empty, or only the relay footer) is not a block at all.
  • Markers in comments count: they now name the blocker in the row's reason and in the band.

What

Case Before After
Relay blocked verdict names an issue/PR Native link or marker (#15023), lifted on close Unchanged
Relay blocked verdict with text but no issue/PR named blocked stuck, no inbox, "records no reason" Blocked sweep: needs-human added, blocked removed, one note with the two ways out
Relay blocked verdict with an empty or footer-only reason blocked stuck Hub books it idle and releases the label (like a tooling failure)
A person's marker-less blocked Left alone Left alone
Hive-applied, open native "blocked by" link Left alone Left alone
Review-backlog item, hive-applied, no marker Lifted (#13364) Unchanged
Marker in a comment (pr=projectbluefin/actions#697) Row reason blocked; band "records no reason" Row reason blocked on projectbluefin/actions#697; band names it
Marked item closes or merges Lifted by the blocked sweep Unchanged (already existed)

Why

How

  • issue_blocked.go, askHumanBlockedMarkerless: a hive-applied unmarked block that is not a review-backlog item and has no open native link is gated by WritebackAllowed(KindGateComment). The steps are:

    1. add needs-human (before removing blocked, so a failed add leaves the issue parked);
    2. remove blocked;
    3. strip help wanted;
    4. post one <!-- hive:unblocked --> note.

    A person's label is never converted. Converted issues are counted in BlockedIssueResult.AskedHuman.

  • issue_blocked.go, comment markers: the blocked sweep remembers the newest comment marker it reads (blockedOnSeen). blockedFilterReasonFor gives it precedence over the body, the same precedence the sweep lifts by. unblockIssue forgets it.

  • contribute_blocked_tooling.go: isBlockedVerdictReasonless strips HTML comments, --- and 🐝 footer lines, and finds no letter or digit. reclassifyToolingBlockedVerdict then books the verdict idle, and the release comment says "gave no reason" under its own marker.

  • bands.go / overview_ownership.go: blockedReasonSignal turns the row reason into blocked on owner/repo#N β€” lifted when it merges or closes or blocked until <t> β€” re-checked then, replacing the no-reason signal.

Files

File Change
src/pkg/github/issue_blocked.go needs-human ask; comment-marker memory; blockedFilterReasonFor
src/pkg/github/client.go, webhook_item_patch.go Row reason reads the remembered comment marker
src/pkg/github/item_refresh_hook.go unblockIssue forgets it
src/pkg/dashboard/contribute_blocked_tooling.go Reasonless blocked verdict β†’ idle + release
src/pkg/dashboard/contribute_ws.go Log text covers both reclassifications
src/pkg/dashboard/bands.go, overview_ownership.go Band signal names the marker or deadline
src/docs/labels-and-control-signals/reference.md, changelog blocked docs

Tests

Test Covers
TestSweepBlockedIssuesAsksHumanOnRelayMarkerlessBlock Decision table: backlog lifted, relay ask (once over 3 passes), person's / open-link / comment-marker kept
TestReconcileBlockedIssues (updated) The relay case now becomes an ask; needs-human precedes the removal
TestEnumerateActionableRecordsBlockedRecheckAfter (extended) A comment marker names the row's blocker
TestUnblockForgetsCommentMarker, TestBlockedMarkerlessAskNote Memory cleared on unblock; note wording
TestBlockedVerdictReasonlessIsReleased Empty / footer-only / comment-only reasons β†’ idle; #450 and real text stay blocked
TestBlockedRowSignalNamesMarker, TestBlockedReasonSignal Band signal with a marker, a deadline, the bare label
Mutants 15/15 caught
go test github/..., writeback, dashboard, cmd/hive pass
check-docs-citations.py src/docs 2006 verified

Notes

πŸ€– Generated with Claude Code

https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1

…in comments name the blocker

A contributor relay's blocked verdict that named no issue or PR left
`blocked` with no hive:blocked-on marker: lifted, it looped
(projectbluefin/utah#771, 19 cycles); kept, it sat in no inbox
("labelled blocked β€” the label records no reason").

- blocked sweep: a hive-applied marker-less block (not review backlog, no
  open native link) gets needs-human, loses blocked and help wanted, and
  one note naming the two ways out; a person's block is left alone.
- hub: a blocked verdict whose reason is empty or only the relay footer is
  booked idle and its label released (projectbluefin/utah#1002).
- a blocked-on marker the sweep reads in a comment names the row's reason
  and the band signal (projectbluefin/finpilot#624, hivecommons#390); the band reads
  the reason instead of saying "records no reason".

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 danathar 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
#16842 πŸ› fix(labels): a later hive/verified-open or hive/already-done replaces the other same files src/docs/labels-and-control-signals/reference.md
#16811 πŸ› fix(workflows): verify "the App cannot push workflows" before parking on it same files src/docs/labels-and-control-signals/reference.md
src/pkg/github/client.go
#16837 πŸ› fix(contribute): a needs-decision park posts its question same files src/pkg/dashboard/contribute_ws.go
#16843 ✨ feat(ownership): CLOSE an agent finding whose cited lines are gone from main same files src/pkg/github/client.go

@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.

Hive filed review findings that do not block this PR as backlog items:

Cap: 10 backlog item(s) per PR per day.

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

Docs currency (read at head 53b26fc)

The reference.md and changelog updates match the code strings (blockedReasonSignal wording in src/pkg/dashboard/bands.go, the two-ways-out note in blockedMarkerlessAskNote, src/pkg/github/issue_blocked.go). One operator-facing doc that describes the same hub paths was not updated and now contradicts them:

  1. src/docs/contributor-relay.md:1616 β€” "Lifting the label stays human: the relay never removes it, so the admission gate holds the issue past the cooldown until someone who knows the dependency has cleared says so." After this PR a relay-applied blocked with no marker and no open "blocked by" link is converted by the blocked sweep to needs-human (askHumanBlockedMarkerless, src/pkg/github/issue_blocked.go), so the hold no longer waits on a human to lift blocked.

  2. src/docs/contributor-relay.md:1619 β€” the "Not blocked: the contributor's own tooling" bullet documents reclassifyToolingBlockedVerdict and the <!-- hive:blocked-released kind=tooling --> comment only. The function now also demotes a reasonless verdict (isBlockedVerdictReasonless, src/pkg/dashboard/contribute_blocked_tooling.go:80-93, 99-104) and posts a different marker, <!-- hive:blocked-released kind=no-reason --> (:70, :110-114, :125-127). reference.md says "like a tooling failure", but the only place the tooling-failure path is explained is this bullet.

Suggested patch (sentence-level, both lines are single long lines):

- **Lifting the label stays human**: the relay never removes it, so the admission gate holds the issue past the cooldown until someone who knows the dependency has cleared says so.
+ **The relay never lifts the label.** A verdict whose reason names an issue or PR carries a `<!-- hive:blocked-on … -->` marker and is lifted by the blocked sweep when that item merges or closes; a verdict that names nothing is turned by the same sweep into a `needs-human` ask (`needs-human` added, `blocked` removed, one `<!-- hive:unblocked -->` note), so the issue reaches an inbox instead of sitting unlifted.

and, appended to the Not blocked: the contributor's own tooling bullet after …saying why.:

+ A `blocked` verdict whose reason is empty, or only HTML comments and the relay's `---` / 🐝 footer lines (`isBlockedVerdictReasonless`), is demoted the same way: booked idle, label released, one `<!-- hive:blocked-released kind=no-reason -->` comment saying the agent gave no reason (projectbluefin/utah#1002).

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

Style / maintainability review (head 53b26fc). Nothing here blocks; three things would make the new code easier to keep right.

1. askHumanBlockedMarkerless re-implements liftBlockedMarkerless's gate and drops its WARN β€” src/pkg/github/issue_blocked.go:646-657 vs :597-615. The actor lookup, error accounting and hive-identity check are copied verbatim, but the new path returns silently where the lift path logs marker-less blocked label with no hive identity to compare against (:611-613) β€” the lift's own doc comment (:594-596) promises that WARN "so the stuck block is at least visible", and the ask path now hides exactly the case this PR exists to surface. One helper keeps both paths in step:

+// hiveAppliedBlocked reports the actor that last applied `blocked` and
+// whether it was this hive; errors are counted and a missing hive identity
+// is warned once so the stuck block stays visible.
+func hiveAppliedBlocked(ctx context.Context, client *Client, t blockedIssueTarget, res *BlockedIssueResult, logger *slog.Logger) (string, bool) {
+	actor, found, err := client.blockedLabelActor(ctx, t.repo, t.number)
+	if err != nil {
+		res.Errors++
+		logger.Warn("blocked sweep: timeline lookup failed; marker-less block left alone", "repo", t.repo, "issue", t.number, "error", err)
+		return "", false
+	}
+	if !found {
+		return "", false
+	}
+	if !client.isOwnBotLogin(actor) && !client.IsHiveAuthorLogin(actor) {
+		if len(client.hiveBotLogins()) == 0 {
+			logger.Warn("blocked sweep: marker-less blocked label with no hive identity to compare against; left alone", "repo", t.repo, "issue", t.number, "actor", actor)
+		}
+		return actor, false
+	}
+	return actor, true
+}

and both functions become actor, ok := hiveAppliedBlocked(...); if !ok { return false }.

2. blockedOnSeen is a package-level map; every other cache in this package hangs off *Client β€” issue_blocked.go:697-725 vs client.go:62-74 (forgeMu, prBatchMu, prBatchCheckRuns, prBatchReviews). All three call sites already have a *Client (reconcileBlockedTargets, unblockIssue, fetchIssues/classifyWebhookIssue), so this could be c.blockedOnSeenMu/c.blockedOnSeen with no signature change beyond making the three helpers methods. As written, tests must t.Cleanup(forgetBlockedOnSeen) to avoid cross-test leakage (issue_blocked_test.go, the new TestEnumerateActionableRecordsBlockedRecheckAfter block), and an entry is only forgotten via unblockIssue β€” a block a human lifts by hand keeps its entry until restart. The stagelabels.Shared() store you already call from unblockIssue (item_refresh_hook.go:54) is the other existing home for sweep-derived per-issue facts.

3. Misattached doc comment β€” src/pkg/dashboard/contribute_blocked_tooling.go:72-77: the comment describing blockedVerdictFooterLineRE sits on blockedVerdictCommentRE, and the footer regex has none.

// blockedVerdictCommentRE matches HTML comments (markers, footers' hidden
// tags): they say nothing about what the issue waits on.
var blockedVerdictCommentRE = regexp.MustCompile(`(?s)<!--.*?-->`)

// blockedVerdictFooterLineRE matches the lines a relay appends to every
// comment (`---`, the 🐝 Hive Agent footer): they say nothing about what
// the issue waits on.
var blockedVerdictFooterLineRE = regexp.MustCompile(`(?i)^\s*(?:-{3,}|.*🐝.*|.*\*\*hive agent\*\*.*)\s*$`)

Minor, same files: issue_blocked.go:319 references blockedMarkerlessAsk, which does not exist (the function is askHumanBlockedMarkerless); and contribute_blocked_tooling.go:132 (if reason == "" after sanitizeReportedReason) is now unreachable, since any reason that sanitises to empty has no letter or digit and is caught by isBlockedVerdictReasonless at :125 first.

Evidence bundle `#16832bf5b171` sha256:71c17fe0200f1b9ee9fcaf7eaac4a56b4a275e78967f6878bd51297ef392c458 β€” download from the dashboard or `hivectl review evidence #16832`.

@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.

Correctness review (head 53b26fc) β€” no in-scope blocker; one advisory on the writeback gate.

Advisory (low): the conversion's gate refusals are silent and pre-recorded β€” src/pkg/github/issue_blocked.go:666

askHumanBlockedMarkerless asks WritebackAllowed(…, KindGateComment, blockedMarkerlessAskNote) with a constant preview. KindGateComment is in ContentDedupeKinds (src/pkg/writeback/dedupe.go:84), and contentCheckLocked records the write at the moment it allows it (dedupe.go:271-273), before AddLabels/unblockIssue run. Two consequences:

  1. Burst hold (DefaultBurstItems = 2, DefaultBurstWindow = 60s, dedupe.go:30-33): on a repo with several parked relay blocks (the body lists four on projectbluefin/testsuite), only the first converts per sweep; the others return ReasonBurst and askHumanBlockedMarkerless returns false with no log and no counter, falling through to stripBlockedHelpWanted. They do convert on later sweeps, so the body's "become asks on the first sweep after deploy" is one-per-repo-per-sweep in practice.
  2. If AddLabels or unblockIssue fails after the gate allowed, the retry within same_item_ttl (24h) is refused as ReasonDuplicate, again silently.

Neither loses data β€” both self-heal β€” but the silence hides the delay from operators. Suggested: log the refusal like the sibling callers do.

	if d := client.WritebackAllowed(owner+"/"+name, item, writeback.KindGateComment, blockedMarkerlessAskNote); !d.Allowed {
		logger.Info("blocked sweep: needs-human ask held by writeback gate", "repo", t.repo, "issue", t.number, "reason", d.Reason, "detail", d.Detail)
		return false
	}

Verified against the tree: needs-human does reach the inbox as your_turn via parkedOwnership (src/pkg/dashboard/ownership.go:417-419); the open-native-link and person-applied guards hold (issue_blocked.go:647-657); blockedOnSeen is mutex-guarded and cleared in unblockIssue (item_refresh_hook.go:53); test ordering assertion (needs-human before blocked removal) matches the code.

β€” hive: agent=adjudicator-3 backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive

Copy link
Copy Markdown
Contributor

@Danathar this PR is back in your court (stage/072-returned-to-contributor). The hive will not merge it until the head changes.

Review asks:

  • the review swarm requested changes

Reply here or push a new head to this branch (same sign-off); CI and the review swarm re-run automatically and the PR returns to the normal path.

Queued in your relay fix queue (6 waiting): fixes are handed out before new work as soon as you have capacity.

Danathar and others added 2 commits November 5, 2026 18:15
Signed-off-by: Danathar <Danathar@users.noreply.github.com>
Adjudicator advisory on hivecommons#16832: a burst hold (2 items / 60s) or a
duplicate after a failed write within same_item_ttl made
askHumanBlockedMarkerless fall through silently. Log repo, issue, reason
and detail; the conversion retries on a later sweep.

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>
@Danathar

Danathar commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor Author

Thanks, the advisory was right. Fixed in the latest commit (v6 merged in first):

  • When the gate refuses, askHumanBlockedMarkerless now logs "blocked sweep: needs-human ask held by writeback gate" with the repo, issue, reason and detail, then falls through. A burst hold or a retry within same_item_ttl therefore shows in the log, and the conversion retries on a later sweep.
  • TestSweepBlockedAskHeldByGateLogs pauses the repo through the gate. It checks that nothing is written and that the refusal is logged. Deleting the log line fails the test.
  • The PR body now says the conversions are rate-limited by the writeback burst gate, a couple per repo per sweep, rather than all happening on the first sweep after deploy.

@kubestellar-prow kubestellar-prow Bot added size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. and removed size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels Nov 5, 2026

@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 sweep branch and the dashboard reclassifier against the tree at merge-base. The sweep change looks correct to me; one low-severity note on the reason-less detector.

Verified:

  • The new ask sits inside the existing scanned && t.recheckAfter.IsZero() && !t.opsTracking guard and the lookups < blockedSweepCommentLookups budget (src/pkg/github/issue_blocked.go:449-481), and askHumanBlockedMarkerless (:646) takes !t.reviewBacklog while liftBlockedMarkerless (:598) takes t.reviewBacklog, so the two are disjoint and the review-backlog lift is unchanged.
  • Partial-failure ordering converges: needs-human is added before unblockIssue; if the unblock fails the next sweep sees the label already present (issueHasLabel(t.labels, issueNeedsHumanLabel), :671) and retries only the removal. needs-human is already a filter case in client.go:5284, so the converted issue leaves the agent queue as the comment promises.
  • unblockIssue now clears the blockedOnSeen entry (item_refresh_hook.go:53), so a lifted issue does not keep reporting a stale "on owner/repo#N" reason from the process-global map.
  • go build ./pkg/github/ ./pkg/dashboard/ passes on the head.

Low β€” footer regex can swallow a real reason. blockedVerdictFooterLineRE at src/pkg/dashboard/contribute_blocked_tooling.go:77 treats any line containing 🐝 or **Hive Agent** as footer. A one-line verdict such as **Hive Agent** blocked: waits on owner/repo#12 to merge is stripped to nothing, isBlockedVerdictReasonless returns true, and the verdict is demoted to idle with a "gave no reason" release comment even though it named its blocker. Anchoring the pattern to the footer's actual shape (line starts with 🐝 / the --- separator) would avoid it. Not blocking β€” the failure mode is "stays actionable", not a stuck block β€” but it is the inverse of the bug the PR fixes, so worth tightening.

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

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/XL Denotes a PR that changes 500-999 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant