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-blocked-needs-marker.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- A `blocked` label that names nothing is no longer a dead end. A contributor relay's blocked verdict that named no issue or PR used to leave `blocked` with no marker: before 10-28 the sweep lifted it and the next relay re-blocked it (projectbluefin/utah#771 cycled 19 times); since then it stuck and the issue showed in no inbox ("labelled blocked β€” the label records no reason"). The blocked sweep now turns such a hive-applied block into a `needs-human` ask with one note, a verdict whose reason is empty or only the relay footer is booked idle with its label released (projectbluefin/utah#1002), and a blocked-on marker in a comment (projectbluefin/finpilot#624, #390) now names the blocker in the row reason and the band signal.
6 changes: 3 additions & 3 deletions src/docs/labels-and-control-signals/reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,7 @@ Some hive-authored labels look like provenance but are read as signals, so they
| `needs-sha` from SHA-hold | Issues | SHA-hold sweep | Trusted-reporter `kind/bug` without a SHA gets this soft label plus the same `<!-- hive:sha-hold -->` notice instead of `hold`; the issue stays actionable. The sweep removes it once a SHA appears. | Soft (informational) | Hive | Eval tick SHA sweep | Add SHA evidence, or remove the label | `issues.sha_hold_trusted_label` (default `needs-sha`; `hold` restores the hard hold for everyone) |
| `do-not-merge` and `do-not-merge*` | Issues, PRs | Exempt filter, merge sweeps, task-list sweep | Permanently exempt; exact match is case-insensitive but prefix matching follows Go `strings.HasPrefix` on the original label. | Hard suppress | Human | Enumeration/sweeps | Human removes | Built-in `PermanentExemptLabels` (`src/pkg/github/client.go:750-755`, `src/pkg/github/client.go:2035-2053`) |
| `governor.labels.exempt` entries | Issues, PRs | Exempt filter | Same exempt behavior as `do-not-merge`; wins over required-label admission. Defaults include `nightly-tests`, `LFX`, `meta-tracker`, `auto-qa-tuning-report`, `adopters`, `changes-requested`, `waiting-on-author`. | Hard suppress | Operator/dashboard | Enumeration/sweeps | Remove label or config entry | `governor.labels.exempt` (`src/pkg/config/governor_config.go:175-184`, `src/pkg/config/defaults.go:260-270`) |
| `blocked` | Issues | Enumeration, stage derivation, claim gate, review backlog, blocked sweep | The issue waits on an unmerged PR (or another outside blocker): the review backlog files a finding `blocked` when its evidence file exists only on the reviewed PR (absent on the base branch), and `hive-open-issue comment --blocked-on-pr <n>` parks an existing one; both write `<!-- hive:blocked-on pr=owner/repo#N -->`. A `blocked` issue is filtered (reason `blocked on owner/repo#N`), derives no stage label, is refused by every automated claim producer (`blocked: owner/repo#N`) including the contributor relay, and never carries `help wanted` ([#13093](https://github.com/hivecommons/hive/issues/13093)). When a blocked filing folds into an already-open twin, the twin's own state governs: `blocked` is not applied to it, because the folded body (and its marker) is discarded and the twin's earlier evidence stands on its own; the blocked sweep also lifts a hive-applied `blocked` that has no marker, no deadline and no ops-tracking marker, but only on a review-backlog item (its body carries `filed by Hive review backlog`) that GitHub reports no open "blocked by" link on ([#13364](https://github.com/hivecommons/hive/issues/13364)). Every other marker-less `blocked` stays: a human's, and a contributor relay's `blocked` verdict, which GitHub records as the App bot too because the relay labels with its hub-minted task token and which a person lifts (`/hive approve`, [#7924](https://github.com/hivecommons/hive/issues/7924)); lifting it only sent the issue back to the next agent, which re-applied it. With no blocked-on marker, a body deadline `<!-- hive:recheck-after <RFC3339> -->` files it `blocked until <RFC3339>` and the activity monitor's blocked chip reads `re-check at <t>` ([#13310](https://github.com/hivecommons/hive/issues/13310)). | Hard suppress | Hive (reserved for agents; relay only) | Review backlog filing; blocked-on comment relay | The blocked sweep after each stage-label sync removes it, with one `<!-- hive:unblocked -->` note, once the tracked PR is merged or closed, or once a recheck-after deadline passes (`deadline <t> passed; re-triaging`) unless the body also carries `<!-- hive:ops-tracking -->`. An ops-tracking issue on the hive's own project keeps `blocked` once its deadline passes and instead gets soak triage: the hub's `/api/hub/hives` (or, with no hub, the spoke's own `/api/version`) is probed for every `stable`-channel hive (fresh heartbeat, no restart loop, running the candidate `sha256:` digest or `v5 <short-sha>` named in the body), ONE `<!-- hive:recheck-evidence at=<RFC3339> -->` comment is posted, only the checklist lines that evidence proves are ticked, and `<!-- hive:recheck-done -->` is appended to the body so the sweep does not repeat ([#13311](https://github.com/hivecommons/hive/issues/13311)); a human may remove it at any time | Fixed label (`src/pkg/github/issue_blocked.go`, `src/pkg/github/issue_recheck_soak.go`, `src/pkg/github/issue_stage_labels.go`, `src/pkg/github/issue_claim_gate.go`) |
| `blocked` | Issues | Enumeration, stage derivation, claim gate, review backlog, blocked sweep | The issue waits on an unmerged PR (or another outside blocker): the review backlog files a finding `blocked` when its evidence file exists only on the reviewed PR (absent on the base branch), and `hive-open-issue comment --blocked-on-pr <n>` parks an existing one; both write `<!-- hive:blocked-on pr=owner/repo#N -->`. A `blocked` issue is filtered (reason `blocked on owner/repo#N`), derives no stage label, is refused by every automated claim producer (`blocked: owner/repo#N`) including the contributor relay, and never carries `help wanted` ([#13093](https://github.com/hivecommons/hive/issues/13093)). When a blocked filing folds into an already-open twin, the twin's own state governs: `blocked` is not applied to it, because the folded body (and its marker) is discarded and the twin's earlier evidence stands on its own; the blocked sweep also lifts a hive-applied `blocked` that has no marker, no deadline and no ops-tracking marker, but only on a review-backlog item (its body carries `filed by Hive review backlog`) that GitHub reports no open "blocked by" link on ([#13364](https://github.com/hivecommons/hive/issues/13364)). A human's marker-less `blocked` stays. A contributor relay's `blocked` verdict that named nothing (GitHub records it as the App bot too, because the relay labels with its hub-minted task token) is turned into a `needs-human` ask instead: `needs-human` is added, `blocked` removed and one note says what is missing. Lifting it only sent the issue back to the next agent, which re-applied it, and keeping it hid the issue from every inbox. A blocked verdict whose reason is empty or only the relay footer is booked idle and its label released, like a tooling failure. A marker in a comment counts like one in the body: the row's reason (`blocked on owner/repo#N`) and the band signal name it. With no blocked-on marker, a body deadline `<!-- hive:recheck-after <RFC3339> -->` files it `blocked until <RFC3339>` and the activity monitor's blocked chip reads `re-check at <t>` ([#13310](https://github.com/hivecommons/hive/issues/13310)). | Hard suppress | Hive (reserved for agents; relay only) | Review backlog filing; blocked-on comment relay | The blocked sweep after each stage-label sync removes it, with one `<!-- hive:unblocked -->` note, once the tracked PR is merged or closed, or once a recheck-after deadline passes (`deadline <t> passed; re-triaging`) unless the body also carries `<!-- hive:ops-tracking -->`. An ops-tracking issue on the hive's own project keeps `blocked` once its deadline passes and instead gets soak triage: the hub's `/api/hub/hives` (or, with no hub, the spoke's own `/api/version`) is probed for every `stable`-channel hive (fresh heartbeat, no restart loop, running the candidate `sha256:` digest or `v5 <short-sha>` named in the body), ONE `<!-- hive:recheck-evidence at=<RFC3339> -->` comment is posted, only the checklist lines that evidence proves are ticked, and `<!-- hive:recheck-done -->` is appended to the body so the sweep does not repeat ([#13311](https://github.com/hivecommons/hive/issues/13311)); a human may remove it at any time | Fixed label (`src/pkg/github/issue_blocked.go`, `src/pkg/github/issue_recheck_soak.go`, `src/pkg/github/issue_stage_labels.go`, `src/pkg/github/issue_claim_gate.go`) |
| `needs-human` | Issues | Enumeration, task-list sweep, claim escalation gate and un-park sweep | Filters issues from agent kicks and contributor offers; records a human decision requirement. See the [issue reference](#needs-human) and [Maintainer commands](../maintainer-commands.md). | Hard suppress | Hive or human | Enumeration/task-list sweep/kick building | An eligible maintainer's ordinary `/hive approve` or `/hive decision <text>` lifts it regardless of who applied it; label-driven un-parking remains provenance-sensitive. Keep `hold` if work must stay stopped. Agents may add, never remove it. | Fixed label (`src/pkg/github/client.go:1008-1024`, `src/pkg/github/task_list_sweep.go:611-641`, `src/pkg/github/task_list_sweep.go:874-880`, `src/cmd/hive/claimescalation.go`) |
| `needs-spec` from the clarity gate | Issues | Scheduler kick assembly (`runs.triage.clarity_gate`) | With the gate on (default off), a human-filed, unclaimed issue whose clarity score (goal, acceptance criteria, scope, detail, open choices) is under `runs.triage.clarity_gate.threshold` gets one `<!-- hive:clarity-gate -->` comment with concise questions for its author and the `needs-spec` hard-suppress label instead of a claim; it derives `stage/045-needs-decision` and leaves the agent queue ([#13577](https://github.com/hivecommons/hive/issues/13577)). | Hard suppress | Hive | Before kicks are built | The issue author, or a non-hive commenter with write/maintain/admin, replies after the marker and the resume sweep removes the hive's own `needs-spec` and records the un-park so the issue re-derives `stage/010-actionable` ([#13588](https://github.com/hivecommons/hive/issues/13588)); a `needs-spec` a person added is never lifted by the sweep. Or remove `needs-spec` by hand. The marker keeps the gate from asking again | `runs.triage.clarity_gate` (`src/pkg/scheduler/clarity_gate.go`, `src/pkg/classify/clarity.go`, `src/pkg/github/clarity_gate_resume.go`) |
| `stage/017-possible-existing` from the prior-art gate | Issues | Scheduler kick assembly (`runs.triage.prior_art`) | With the gate on (default on), an unclaimed feature / RFC / epic issue whose key terms match an existing knowledge bead, setting, merged PR, closed issue, doc or code identifier at `runs.triage.prior_art.threshold` (default 70) gets one `<!-- hive:prior-art-gate -->` comment quoting the findings and the `stage/017-possible-existing` label instead of a claim; hive-filed issues get a `<!-- hive:prior-art-findings -->` note and are never parked ([#13575](https://github.com/hivecommons/hive/issues/13575)). | Hard suppress | Hive | Before kicks are built | The author or a write+ commenter replies `/hive decision proceed β€” <gap>` (label lifted, a *Scope vs existing* section appended to the body, re-derives 010) or `/hive decision exists` (closed `not_planned` with `already-exists`); a plain reply lifts the label too. A clanker-filed park with no reply is closed `already-exists` after `runs.triage.prior_art.bot_close_ttl` (default 72h); reopen to continue. A 017 a person added is never lifted by the sweep | `runs.triage.prior_art` (`src/pkg/priorart`, `src/pkg/scheduler/prior_art_gate.go`, `src/pkg/github/prior_art_gate_resume.go`) |
Expand Down Expand Up @@ -298,9 +298,9 @@ An open issue whose GitHub dependency list names an open blocker is enumerated w

The issue waits on an unmerged PR (or another outside blocker): the review backlog files a finding `blocked` when its evidence file exists only on the reviewed PR (absent on the base branch), and `hive-open-issue comment --blocked-on-pr <n>` parks an existing one; both write `<!-- hive:blocked-on pr=owner/repo#N -->`. A `blocked` issue is filtered (reason `blocked on owner/repo#N`), derives no stage label, is refused by every automated claim producer (`blocked: owner/repo#N`) including the contributor relay, and never carries `help wanted` ([#13093](https://github.com/hivecommons/hive/issues/13093)).

When a blocked filing folds into an already-open twin, the twin's own state governs: `blocked` is not applied to it, because the folded body (and its marker) is discarded and the twin's earlier evidence stands on its own; the blocked sweep also lifts a hive-applied `blocked` that has no marker, no deadline and no ops-tracking marker, leaving a human-applied one alone ([#13364](https://github.com/hivecommons/hive/issues/13364)). With no blocked-on marker, a body deadline `<!-- hive:recheck-after <RFC3339> -->` files it `blocked until <RFC3339>` and the activity monitor's blocked chip reads `re-check at <t>` ([#13310](https://github.com/hivecommons/hive/issues/13310)).
When a blocked filing folds into an already-open twin, the twin's own state governs: `blocked` is not applied to it, because the folded body (and its marker) is discarded and the twin's earlier evidence stands on its own; the blocked sweep also lifts a hive-applied `blocked` that has no marker, no deadline and no ops-tracking marker on a review-backlog item, leaving a human-applied one alone ([#13364](https://github.com/hivecommons/hive/issues/13364)). Any other hive-applied marker-less `blocked` (a contributor relay's verdict that named no issue or PR) becomes a `needs-human` ask, with one note naming the two ways out: name the dependency, or remove `needs-human` to re-queue it. A verdict with no reason at all is not blocked: the hub books it idle and releases the label. With no blocked-on marker, a body deadline `<!-- hive:recheck-after <RFC3339> -->` files it `blocked until <RFC3339>` and the activity monitor's blocked chip reads `re-check at <t>` ([#13310](https://github.com/hivecommons/hive/issues/13310)).

With the marker, the activity monitor's pill reads `blocked on #N`, links the PR and carries its cached state (`blocked_on_pr` in `/api/stage-tracker`), and the hive's own removal of the label re-reads the issue live rather than waiting for the next enumeration ([#14952](https://github.com/hivecommons/hive/issues/14952)). It is also always skipped by contributor admission and shown in the default waiting band.
With the marker (in the body, or in a comment the blocked sweep has read), the band signal reads `blocked on owner/repo#N β€” lifted when it merges or closes` instead of `the label records no reason`, the activity monitor's pill reads `blocked on #N`, links the PR and carries its cached state (`blocked_on_pr` in `/api/stage-tracker`), and the hive's own removal of the label re-reads the issue live rather than waiting for the next enumeration ([#14952](https://github.com/hivecommons/hive/issues/14952)). It is also always skipped by contributor admission and shown in the default waiting band.

**Who applies it:** Hive (reserved for agents; relay only).

Expand Down
21 changes: 20 additions & 1 deletion src/pkg/dashboard/bands.go
Original file line number Diff line number Diff line change
Expand Up @@ -143,6 +143,25 @@ func uniqueLabels(labels, fallback []string) []string {
return out
}

// blockedNoReasonSignal is the band signal for `blocked` with nothing that
// names the blocker; blockedReasonSignal replaces it when the row's reason
// does (a blocked-on marker, or a recheck deadline).
const blockedNoReasonSignal = "labelled blocked β€” the label records no reason; see the issue"

// blockedReasonSignal names what a blocked row waits on from its enumeration
// reason ("blocked on owner/repo#N", "blocked until <t>"); "" when the reason
// is the bare label. projectbluefin/finpilot#624 and #390 carried markers and
// still read "records no reason".
func blockedReasonSignal(reason string) string {
if repo, pr, ok := github.ParseBlockedOnReason(reason); ok {
return fmt.Sprintf("blocked on %s#%d β€” lifted when it merges or closes", repo, pr)
}
if rest, ok := strings.CutPrefix(strings.TrimSpace(reason), "blocked until "); ok && rest != "" {
return "blocked until " + rest + " β€” re-checked then"
}
return ""
}

func IssueBand(issue github.Issue, held bool, cfg config.DashboardIssueBandsConfig, now time.Time, selfAuthorizationHoldActive ...func(string) bool) IssueBandInfo {
norm := normalizeIssueBandsConfig(cfg)
labels := labelSet(issue.Labels)
Expand Down Expand Up @@ -177,7 +196,7 @@ func IssueBand(issue github.Issue, held bool, cfg config.DashboardIssueBandsConf
if open := slices.Compact(issue.OpenBlockers()); len(open) > 0 {
signals = append(signals, Signal{Glyph: "β›”", Label: "blocked by " + strings.Join(open, ", ")})
} else if labels["blocked"] {
signals = append(signals, Signal{Glyph: "β›”", Label: "labelled blocked β€” the label records no reason; see the issue"})
signals = append(signals, Signal{Glyph: "β›”", Label: blockedNoReasonSignal})
}
if labelsNeedDecision(labels) {
signals = append(signals, Signal{Glyph: "❓", Label: "needs decision"})
Expand Down
50 changes: 50 additions & 0 deletions src/pkg/dashboard/blocked_marker_signal_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
package dashboard

import (
"testing"
"time"

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

// projectbluefin/finpilot#624 (the hive's own `pr=projectbluefin/actions#697`
// comment marker) and #390 (a maintainer's) still read "labelled blocked β€”
// the label records no reason". The row's enumeration reason names the
// blocker; the band signal now says it.
func TestBlockedRowSignalNamesMarker(t *testing.T) {
now := time.Date(2026, 11, 5, 22, 0, 0, 0, time.UTC)
cfg := config.DashboardIssueBandsConfig{}
for _, tc := range []struct {
reason string
want string
}{
{reason: "blocked on projectbluefin/actions#697", want: "blocked on projectbluefin/actions#697 β€” lifted when it merges or closes"},
{reason: "blocked until 2026-11-07T00:00:00Z", want: "blocked until 2026-11-07T00:00:00Z β€” re-checked then"},
{reason: "blocked", want: blockedNoReasonSignal},
{reason: "", want: blockedNoReasonSignal},
} {
row := github.RepoWorkIssue{Repo: "projectbluefin/finpilot", Number: 624, Labels: []string{"blocked", "triage/accepted"}, Bucket: "filtered", Reason: tc.reason}
info := nonActionableIssueInfo(row, "finpilot", cfg, now, nil)
got := blockedSignals11716(info)
if len(got) != 1 || got[0] != tc.want {
t.Errorf("reason %q: blocked signals = %q, want [%q]", tc.reason, got, tc.want)
}
}
}

func TestBlockedReasonSignal(t *testing.T) {
for reason, want := range map[string]string{
"blocked on o/r#5": "blocked on o/r#5 β€” lifted when it merges or closes",
"blocked": "",
"hold label": "",
"blocked until ": "",
"blocked on o/r#notanum": "",
" blocked on o/r#12 ": "blocked on o/r#12 β€” lifted when it merges or closes",
"blocked until tomorrow": "blocked until tomorrow β€” re-checked then",
} {
if got := blockedReasonSignal(reason); got != want {
t.Errorf("blockedReasonSignal(%q) = %q, want %q", reason, got, want)
}
}
}
Loading
Loading