Skip to content
Closed
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/added-15023-relay-blocked-blocker.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- A contributor blocked verdict that names its blocker (`owner/repo#N`, `#N`, or an issue/PR URL) now records it on the task issue — a native GitHub "blocked by" link for an open issue, a `hive:blocked-on` marker for an open PR — so the hive lifts `blocked` itself once the blocker closes.
2 changes: 1 addition & 1 deletion src/docs/labels-and-control-signals.md
Original file line number Diff line number Diff line change
Expand Up @@ -112,7 +112,7 @@ Some hive-authored labels look like provenance but are read as signals, so they
| `hive/partially-addressed` | Issues | Close-on-merge sweep, PR-claim label sync and task-list sweep | A merged PR covered only part of the issue ([#11931](https://github.com/hivecommons/hive/issues/11931)): applied instead of `hive/likely-done` when the PR has no closing keyword (`Fixes`/`Closes`/`Resolves #N`) for the issue, its body carries a remainder/out-of-scope paragraph, or none of the backtick-quoted paths cited in the issue body is among its changed files. No `/fixed` prompt is posted, `hive/likely-done` is suppressed, and the issue stays in the actionable pool; the `<!-- hive:task-list-sweep -->` comment lists the cited paths no merged PR changed as `Not yet touched: ...`. | Display; suppresses likely-done | Hive | Close-on-merge sweep for issues behind a confirmation gate | Hive removes it when a later merged PR fully covers the issue and `hive/likely-done` is applied; humans may remove it | Fixed label (`src/pkg/github/close_on_merge.go`, `src/pkg/github/task_list_sweep.go`) |
| `hive/verified-open` | Issues | Verify-once kick path, PR-claim label sync and close-on-merge | A `hive/likely-done` / already-done claim from a merged PR was checked and the issue is NOT finished ([#11931](https://github.com/hivecommons/hive/issues/11931)): the agent that verified it labels the issue (`src/pkg/scheduler/kickmessage.go` "verify once" instruction) so later kicks say "already verified — implement the rest" and the claim sync never re-applies `hive/likely-done` from the same stale claim (`src/pkg/github/prclaims.go`). Merged-PR evidence, orthogonal to the stage: the issue keeps moving `010 → 020 → 030 → 040` as new work starts. | Suppresses likely-done; kick wording | Agent (verify-once kick) / Hive | Verify-once kick, claim sync | Human removes when the issue is really done, or close-on-merge closes the issue | Fixed label (`src/pkg/github/prclaims.go` `VerifiedOpenLabel`, `src/cmd/hive/verifyonce.go`) |
| `hive/already-done` | Issues | Contributor queue, already-done verdict close path, and dashboard | Contributor already-done verdict/confirmation; default contributor skip label and done band. When the verdict cites a PR that the API verifies as merged on the default branch, Hive labels the issue and runs the normal completed close path; human-filed bugs close too unless `hive: needs-confirmation` or `issues.reporter_confirmation` opted into the reporter gate. A verdict that cites no PR/commit, or whose citation fails verification, is never labelled: Hive comments that the contributor reports it may be resolved and holds it from offers for `hub.contribute_already_done_hold_days`. | Contributor hard skip; dashboard display; conditional close | Hive/contributor flow | Contributor admission, verified verdict settlement, issue close gate | Human removes/reopens or confirms reporter-gated bugs | `hub.contribute_already_done_label`, fixed label (`src/pkg/config/hub_config.go:196-208`, `src/pkg/config/defaults.go:275-289`, `src/pkg/dashboard/contribute_verdict_settle.go`, `src/pkg/github/issue_close.go`) |
| `blocked` | Issues | Contributor queue, dashboard issue bands, un-park sweep | Always included in contributor skip patterns and default waiting band. Does not by itself stop spoke-agent enumeration unless also exempt/held/filtered. It parks the issue on a person for the un-park sweep (#12376): Hive keeps the "What to reply" notice on it, and `/hive approve` (lift and re-offer) or `/hive decision <text>` (lift with instructions) remove it; label approval removes it only when the App bot applied it. A contributor blocked verdict whose reason says a person must act (an admin, maintainer, owner or operator; no other item, upstream or release named) is labelled `needs-human` instead. The label records no reason: the dashboard row signal and BLOCKED pill hover name the open GitHub "blocked by" links when the issue has them (`Issue.DependsOn`), and otherwise say the label records no reason. Blocked-by links are read for actionable issues only, so held and parked rows always show the label-only text. | Contributor hard skip; display | Human, or Hive App on a contributor blocked verdict | Contributor admission/dashboard render | Remove label. Hive's hard-suppress reconcile (#12002) lifts a `blocked` whose newest label event is a `labeled` by the App bot once a PR referencing the issue merges after it (a PR in one of the hive's repos authored by the App bot or `project.ai_author`; a person's PR that only mentions the issue never counts), posting one note carrying `<!-- hive:hard-suppress-lifted -->`; a human-applied (or re-applied) `blocked` is never lifted. The blocked sweep never lifts a contributor verdict's `blocked`: its marker-less lift is for review-backlog items only (see the review-backlog `blocked` row). | `hub.contribute_skip_labels`, dashboard bands (`src/pkg/config/hub_config.go:136-155`, `src/pkg/config/hub_config.go:469-492`, `src/docs/dashboard.md:105-140`) |
| `blocked` | Issues | Contributor queue, dashboard issue bands, un-park sweep | Always included in contributor skip patterns and default waiting band. Does not by itself stop spoke-agent enumeration unless also exempt/held/filtered. It parks the issue on a person for the un-park sweep (#12376): Hive keeps the "What to reply" notice on it, and `/hive approve` (lift and re-offer) or `/hive decision <text>` (lift with instructions) remove it; label approval removes it only when the App bot applied it. A contributor blocked verdict whose reason says a person must act (an admin, maintainer, owner or operator; no other item, upstream or release named) is labelled `needs-human` instead. When a contributor blocked verdict's reason names its blocker (`owner/repo#N`, `#N`, or an issue or PR URL; the first one that is not the issue itself), the hub records it once: an open issue becomes a native GitHub "blocked by" link on the task issue, an open PR a `<!-- hive:blocked-on pr=owner/repo#N -->` comment, so the hard-suppress reconcile or the blocked sweep lifts `blocked` when it closes; a closed or unreadable blocker records nothing ([#15023](https://github.com/hivecommons/hive/issues/15023)). Otherwise the label records no reason: the dashboard row signal and BLOCKED pill hover name the open GitHub "blocked by" links when the issue has them (`Issue.DependsOn`), and otherwise say the label records no reason. Blocked-by links are read for actionable issues only, so held and parked rows always show the label-only text. | Contributor hard skip; display | Human, or Hive App on a contributor blocked verdict | Contributor admission/dashboard render | Remove label. Hive's hard-suppress reconcile (#12002) lifts a `blocked` whose newest label event is a `labeled` by the App bot once a PR referencing the issue merges after it (a PR in one of the hive's repos authored by the App bot or `project.ai_author`; a person's PR that only mentions the issue never counts), posting one note carrying `<!-- hive:hard-suppress-lifted -->`; a human-applied (or re-applied) `blocked` is never lifted. The blocked sweep never lifts a contributor verdict's `blocked`: its marker-less lift is for review-backlog items only (see the review-backlog `blocked` row). | `hub.contribute_skip_labels`, dashboard bands (`src/pkg/config/hub_config.go:136-155`, `src/pkg/config/hub_config.go:469-492`, `src/docs/dashboard.md:105-140`) |
| `needs-direction` (retired) | Issues | Issue stage reconciler (migration only) | Retired ([#12683](https://github.com/hivecommons/hive/issues/12683)): nothing writes it. `stage/045-needs-decision` is the single "issue parked for a maintainer ruling" signal (owner decision: `stage/085-needs-decision` is PR-only). An open issue still carrying it is read as parked (same hard suppress, same un-park), the issue stage reconciler adds `stage/045-needs-decision` and then removes the retired label, and the label definition is deleted from the repo once no open item carries it. The scanner's "needs-direction (scanner): …" comment may remain as the explanation text accompanying the 045 transition — no label. | Hard suppress until migrated | — (legacy) | Issue stage reconciler | Migrated to `stage/045-needs-decision` (`src/pkg/github/legacy_decision_labels.go`) | Fixed legacy spelling (`src/pkg/config/issue_filter.go`) |
| `needs-decision` (retired) | Issues, PRs | Issue stage reconciler (migration only); PR lanes read it as a hold modifier until gone | Retired ([#12683](https://github.com/hivecommons/hive/issues/12683)): nothing writes it. The relay's `hive-open-issue --needs-decision` and the configured `project.issue_filter.hard_suppress_labels.needs_decision` / `hub.contribute_needs_decision_label` now default to `stage/045-needs-decision`; a configured legacy spelling (or `stage/085-needs-decision`) is upgraded. Migration as for `needs-direction`. | Hard suppress until migrated | — (legacy) | Issue stage reconciler | Migrated to `stage/045-needs-decision` (`src/pkg/github/legacy_decision_labels.go`) | `hub.contribute_needs_decision_label` (`src/pkg/config/hub_config.go`, `src/pkg/config/issue_filter.go`) |
| `needs-triage`, `discussion`, `question`, `tracking`, `epic` | Issues | Contributor queue | Default contributor skip labels/patterns. | Contributor hard skip | Human/Hive | Contributor admission | Remove label or config | `hub.contribute_skip_labels`, `HIVE_CONTRIBUTE_SKIP_LABELS` (`src/pkg/config/hub_config.go:136-155`, `src/pkg/config/hub_config.go:469-492`) |
Expand Down
60 changes: 60 additions & 0 deletions src/pkg/dashboard/contribute_verdict_blocker.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
package dashboard

import (
"context"
"time"

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

// A blocked verdict's `blocked` label is a gate only a human lifts unless the
// hive can read what it waits on (hivecommons/hive#15023). When the reason
// names its blocker, the hub records it — a native "blocked by" link for an
// open issue, a blocked-on marker for an open PR — so the existing reconciles
// lift `blocked` once the blocker closes. A reason with no resolvable
// reference, a closed blocker or a failed read records nothing: the block
// stays human-lifted, as before.

// verdictBlockerRecordTimeout bounds the detached GitHub work: one blocker
// read, one blocker-list or comment read, at most one write.
const verdictBlockerRecordTimeout = 30 * time.Second

// recordVerdictBlocker records the blocker a blocked verdict's reason names
// on the task issue. Runs detached from the read loop; callers `go` it. A
// re-delivered verdict naming the same blocker is written at most once per
// hub; GitHub-side checks cover restarts.
func (h *ContributeWSHub) recordVerdictBlocker(task *WSTaskAssign, reason string) {
if h == nil || task == nil || task.Kind != "issue" || task.Repo == "" || task.Number <= 0 || task.ExternalID != "" {
return
}
blocker, ok := ghpkg.ParseVerdictBlocker(reason, task.Repo, task.Number)
if !ok {
return
}
key := task.identityKey() + "->" + blocker.String()
if _, seen := h.verdictBlockersRecorded.LoadOrStore(key, struct{}{}); seen {
return
}
ctx, cancel := context.WithTimeout(context.Background(), verdictBlockerRecordTimeout)
defer cancel()
outcome, err := h.recordVerdictBlockerOnForge(ctx, task.Repo, task.Number, blocker)
if err != nil {
// Forget the key so a later re-delivery may try again.
h.verdictBlockersRecorded.Delete(key)
h.logger.Warn("[contribute-ws] blocked verdict: could not record the named blocker",
"repo", task.Repo, "number", task.Number, "blocker", blocker.String(), "error", err)
return
}
h.logger.Info("[contribute-ws] blocked verdict: recorded the named blocker",
"repo", task.Repo, "number", task.Number, "blocker", blocker.String(), "outcome", string(outcome))
}

func (h *ContributeWSHub) recordVerdictBlockerOnForge(ctx context.Context, repo string, number int, blocker ghpkg.VerdictBlocker) (ghpkg.VerdictBlockerOutcome, error) {
if h.verdictBlockerRecorder != nil {
return h.verdictBlockerRecorder(ctx, repo, number, blocker)
}
if h.server == nil || h.server.deps == nil || h.server.deps.GHClient == nil {
return "", ghpkg.ErrNoGitHubClient
}
return h.server.deps.GHClient.RecordVerdictBlocker(ctx, repo, number, blocker)
}
94 changes: 94 additions & 0 deletions src/pkg/dashboard/contribute_verdict_blocker_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
package dashboard

import (
"context"
"errors"
"sync"
"testing"

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

// verdictBlockerFixture records what the hub asked the forge to record.
type verdictBlockerFixture struct {
mu sync.Mutex
calls []string
err error
}

func (f *verdictBlockerFixture) record(_ context.Context, repo string, number int, b ghpkg.VerdictBlocker) (ghpkg.VerdictBlockerOutcome, error) {
f.mu.Lock()
defer f.mu.Unlock()
f.calls = append(f.calls, repo+"->"+b.String())
if f.err != nil {
return "", f.err
}
return ghpkg.VerdictBlockerLinked, nil
}

func (f *verdictBlockerFixture) count() int {
f.mu.Lock()
defer f.mu.Unlock()
return len(f.calls)
}

// hivecommons/hive#15023: a blocked verdict that names its blocker records it
// once per task; a reason with no reference, a non-issue task and a
// re-delivered verdict write nothing.
func TestRecordVerdictBlocker_SeamAndDedupe(t *testing.T) {
hub, _ := covK2Hub(t)
fx := &verdictBlockerFixture{}
hub.verdictBlockerRecorder = fx.record
task := &WSTaskAssign{Kind: "issue", Repo: "projectbluefin/testsuite", Number: 975}

hub.recordVerdictBlocker(nil, "blocked on ublue-os/server#450")
hub.recordVerdictBlocker(&WSTaskAssign{Kind: "pr", Repo: "o/r", Number: 5}, "blocked on #6")
hub.recordVerdictBlocker(&WSTaskAssign{Kind: "issue", Repo: "o/r", Number: 5, ExternalID: "LIN-1"}, "blocked on #6")
hub.recordVerdictBlocker(task, blockedReason)
if n := fx.count(); n != 0 {
t.Fatalf("no reference or a non-GitHub-issue task must record nothing, got %v", fx.calls)
}

hub.recordVerdictBlocker(task, "#975 is blocked on the open issue ublue-os/server#450")
if len(fx.calls) != 1 || fx.calls[0] != "projectbluefin/testsuite->ublue-os/server#450" {
t.Fatalf("the named blocker must be recorded on the task issue, got %v", fx.calls)
}
hub.recordVerdictBlocker(task, "still blocked on ublue-os/server#450")
if n := fx.count(); n != 1 {
t.Fatalf("a re-delivered verdict must not record twice, got %v", fx.calls)
}
}

func TestRecordVerdictBlocker_ErrorAllowsRetry(t *testing.T) {
hub, _ := covK2Hub(t)
fx := &verdictBlockerFixture{err: errors.New("boom")}
hub.verdictBlockerRecorder = fx.record
task := &WSTaskAssign{Kind: "issue", Repo: "o/r", Number: 5}

hub.recordVerdictBlocker(task, "blocked on o/x#9")
fx.err = nil
hub.recordVerdictBlocker(task, "blocked on o/x#9")
if n := fx.count(); n != 2 {
t.Fatalf("a failed record must not dedupe the retry, got %v", fx.calls)
}
}

// A tooling-failure verdict is reclassified idle before the blocker hook, so
// a reason that happens to cite a reference writes nothing.
func TestRecordVerdictBlocker_ToolingReclassifiedWritesNothing(t *testing.T) {
reason := "the push to my fork is rejected; see hivecommons/hive#11775"
verdict, ok := reclassifyToolingBlockedVerdict(completionVerdictBlocked, reason)
if !ok || verdict == completionVerdictBlocked {
t.Fatalf("tooling reason must be reclassified away from blocked, got (%q, %v)", verdict, ok)
}
}

func TestRecordVerdictBlocker_NoClientIsLogged(t *testing.T) {
hub, _ := covK2Hub(t)
if hub.server != nil && hub.server.deps != nil {
hub.server.deps.GHClient = nil
}
if _, err := hub.recordVerdictBlockerOnForge(context.Background(), "o/r", 5, ghpkg.VerdictBlocker{Repo: "o/r", Number: 6}); !errors.Is(err, ghpkg.ErrNoGitHubClient) {
t.Fatalf("no GitHub client must report ErrNoGitHubClient, got %v", err)
}
}
13 changes: 13 additions & 0 deletions src/pkg/dashboard/contribute_ws.go
Original file line number Diff line number Diff line change
Expand Up @@ -1213,6 +1213,11 @@ type ContributeWSHub struct {
// GHClient. gateParkRekicks records the one re-kick each issue gets.
gateParkReleaser func(ctx context.Context, repo string, number int, reporter, reason string) error
gateParkRekicks gateParkRekicks
// verdictBlockerRecorder is the seam for recording the blocker a blocked
// verdict names (contribute_verdict_blocker.go); nil means use GHClient.
// verdictBlockersRecorded dedupes re-delivered verdicts per task.
verdictBlockerRecorder func(ctx context.Context, repo string, number int, blocker ghpkg.VerdictBlocker) (ghpkg.VerdictBlockerOutcome, error)
verdictBlockersRecorded sync.Map
// wrongBaseBranchChecker validates a wrong_base target against the target
// repository; nil means use GHClient.BranchExists. wrongBaseParker is the
// mutation seam for the invalid/unverifiable fallback.
Expand Down Expand Up @@ -4486,6 +4491,14 @@ func (s *wsSession) handleTaskComplete(msg WSMessage) {
go h.releaseToolingBlockedIssue(completedTask, s.contributor.profile.GitHubUsername, verdictReason)
}
}
// A blocked verdict that names its blocker (owner/repo#N, #N, an
// issue or PR URL) is recorded as a native "blocked by" link or a
// blocked-on PR marker, so the hive lifts `blocked` itself when
// the blocker closes (hivecommons/hive#15023).
if verdict == completionVerdictBlocked && completedTask != nil {
taskCopy := *completedTask
go h.recordVerdictBlocker(&taskCopy, verdictReason)
}
// A needs-decision verdict whose reason is the target repository's
// OWN confirmation gate — "AGENTS.md says offer a spec and wait",
// "registered sibling checkout missing" — is not a decision a
Expand Down
19 changes: 19 additions & 0 deletions src/pkg/dashboard/contribute_ws_blocked_verdict_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -202,6 +202,16 @@ func TestBlockedVerdict_WireShape(t *testing.T) {
return ghpkg.SettleVerification{Settled: true, Claim: ghpkg.IssueClaim{PRNumber: ref.Number, MergedPR: true}}, nil
}

// #15023: the blocker the reason names is recorded on the task issue.
recorded := make(chan string, 4)
hub.verdictBlockerRecorder = func(_ context.Context, repo string, number int, b ghpkg.VerdictBlocker) (ghpkg.VerdictBlockerOutcome, error) {
if number != 105 {
t.Errorf("blocker recorded on #%d, want #105", number)
}
recorded <- repo + "->" + b.String()
return ghpkg.VerdictBlockerLinked, nil
}

conn.WriteJSON(WSMessage{Type: "ready", Seq: 2})
assign := readMsg(t, conn)
if assign.Type != "task_assign" {
Expand Down Expand Up @@ -254,6 +264,15 @@ func TestBlockedVerdict_WireShape(t *testing.T) {
if !ok || !rec.Blocked || rec.Reporter != "blocked-user" {
t.Fatalf("ledger row must be the blocked marker for the reporting contributor, got ok=%v rec=%+v", ok, rec)
}

select {
case got := <-recorded:
if got != "myorg/repo1->projectbluefin/utah-packages#41" {
t.Fatalf("the named blocker must be recorded on the task issue, got %q", got)
}
case <-time.After(5 * time.Second):
t.Fatal("a blocked verdict naming its blocker must record it through the seam")
}
}

func TestNeedsDecisionVerdict_BooksFullCooldownAndLedgerMarker(t *testing.T) {
Expand Down
Loading
Loading