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-tracker-000-new.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- The Hive activity monitor now lists every open issue and pull request from its `opened` webhook (with replay and poll fallback) instead of waiting for the governor's next publish, and renders a not-yet-staged item as a `000-new` row in the Open column that says who moves it next β€” a maintainer's triage label or the hive's stage-label pass β€” and when the next pass is due (#15094).
2 changes: 2 additions & 0 deletions src/docs/dashboard-sections.md
Original file line number Diff line number Diff line change
Expand Up @@ -684,6 +684,8 @@ Fed by `GET /api/stage-tracker`. Every issue and pull request follows the same p

**Blocked pill.** An issue wearing `blocked` because the hive parked it on a pull request β€” its body carries `<!-- hive:blocked-on pr=owner/repo#N -->` (the review backlog's spin-off issues, `hive-open-issue comment --blocked-on-pr`) β€” names that PR: the payload carries `blocked_on_pr: {repo, number, url, state}`, the pill reads `blocked on #N` and links to the PR, its tooltip says `Blocked on PR owner/repo#N (open) β€” lifts when it merges; re-triage if closed unmerged`, the caption reads `Blocked on PR #N β€” lifts when it merges` instead of `No stage recorded yet`, and the row's title and chevron tooltip carry the blocker too ([#14952](https://github.com/hivecommons/hive/issues/14952): #14863 showed a bare grey pill and "blocked Β· since 7h" with nothing to say what it waited on). The state (`open`, `merged`, `closed`, or absent when nothing knows) comes only from what the hive already holds β€” the status snapshot's open PRs, the ForgeState cache, the recent-merge ring β€” never a GitHub call from the tracker build; a merged or closed-unmerged blocker says so (`merged; the blocked sweep lifts the label next` / `closed unmerged; the blocked sweep re-triages it next`). The server reads the marker from the issue body when it has one, else from the enumeration's `blocked on owner/repo#N` reason, so sidelined rows (which carry only the reason) name it too. A `blocked` issue with neither (a human-applied label) keeps the bare pill. This is distinct from `blocked_on`, the open GitHub "blocked by" dependencies of a sequenced sub-issue ([#14765](https://github.com/hivecommons/hive/issues/14765)); when a row has both, the chevron tooltip lists them together.

**New row (`000-new`, the pre-stage state).** Every open issue and pull request in `project.repos` is on the list from the moment GitHub reports it β€” there is no gap between "opened" and "the hive has an opinion about it" ([#15094](https://github.com/hivecommons/hive/issues/15094)). The `issues.opened` / `pull_request.opened` webhook re-read inserts the item into the status payload straight away (`insertFrontendRepoItem`; the governor side keeps the same row in its cached snapshot so a republish does not drop it), the per-item replay re-applies that insert after a governor republish, and the enumeration poll is the fallback for a missed delivery. Until something places the item β€” a stage record, a `stage/*` label, a hold, a blocked marker, a bucket other than *reporter triage* / *unclassified* β€” the row is anchored in the **Open** column with the lit chevron reading **New** (`ham-open-new`, blue ✦ rather than amber) and a caption that names who moves it next and when: `New Β· waiting for the stage-label pass (β†’ 010 actionable), then the scanner (next pass in 7m)` for an issue the reporter gate has already admitted, `New Β· waiting for a maintainer's triage (add `triage/accepted`); the hive's next pass in 7m` for a human contributor's issue the reporter-trust gate is still holding (the label names come from `issues.filter.reporter_trust.untrusted_require_labels`), and `New Β· waiting for the stage-label pass (β†’ 050 review pending)` for a pull request. The *since* time is the item's `created_at`; "next pass" is the governor's next kick (`governor.nextKickAt`, so it counts down with the Governor tile and reads *due now* once it has passed). The payload carries it all as `new{since, next_mover (maintainer|hive), next_mover_text, next_pass_at, next_pass_in_seconds, gates[], text}`; the chevron tooltip lists the gates ahead β€” **triage** (the reporter gate: done when admitted, next when a triage label is still needed), **actionable** (the stage-label pass marks it 010), **claimed** (the scanner claims it, 020) β€” each marked βœ“ done, β†’ next or Β· later, and the row's actor icon reads *human* while the next mover is a maintainer and *hive* otherwise. A row that already wears a hold, `blocked`, a draft marker or any stage record is never *New*; neither is an issue at `015` once the stage-label pass has written it.

**Hive's own unblock is live.** When the blocked sweep or the review-backlog block reconciler lifts `blocked` itself (the tracked PR merged or closed; the `<!-- hive:unblocked -->` note), it takes the same path as an inbound label webhook: the tracker cache is dropped and the issue is queued for the targeted re-read (`ItemPatches` delivery `self:edit`), which patches the status row and the governor's cached snapshot at once. A reconcile enumeration that was already listing when the unblock happened used to overwrite that patch with its pre-unblock copy, and the rows reverted to `blocked` until the next pass (~an hour on the hive's hive); the governor now replays re-reads newer than the listing's start onto the pass's result before publishing it, so a row never moves backwards behind a read it has already made.

**Closed issue, open PR.** A pull request whose `Fixes #N` issue has already closed (auto-closed by a bot, or closed by hand) while the PR is still open is live work, not a stale line: the row is anchored on the PR ([#14655](https://github.com/hivecommons/hive/issues/14655)). The PR's own icon, number and title lead the row at full width, its stage drives the strip and its timestamps sort it β€” closing the issue is not a regression of the PR β€” and the closed issue shrinks to a muted `closes #N Β· closed` chip linking to it. An issue closed as *not planned* adds an `issue closed (not planned)` chip so the reader can tell the PR may be moot. At 090 such a row still counts under *Needs attention*: the human has a merge to click. When the PR closes or merges too, the row leaves the list as before (a merged PR shows in *Recently merged* for its retention window).
Expand Down
22 changes: 22 additions & 0 deletions src/docs/labels-and-control-signals.md
Original file line number Diff line number Diff line change
Expand Up @@ -442,6 +442,28 @@ not read as the issue regressing.
> [operator-reference.md](operator-reference.md#central-stage-engine-rollout)
> and the plan in [stage-engine-plan.md](stage-engine-plan.md).

### Before any stage: `000-new` in the activity monitor

A freshly opened issue or pull request carries no `stage/*` label and no
stage record until the stage-label pass of the next enumeration cycle
looks at it (and, for a human contributor's issue, until a maintainer
adds a reporter-trust label β€” `triage/accepted` by default,
`issues.filter.reporter_trust.untrusted_require_labels`). That gap is not a
label: nothing is written on GitHub for it. It *is* a state the dashboard
shows ([#15094](https://github.com/hivecommons/hive/issues/15094)): the
`opened` webhook re-read inserts the item into the activity monitor at once,
and until something places it the row reads `000-new` in the **Open** column
with a caption naming the next mover β€” a maintainer (the triage gate is the
next hop; the caption says which label to add) or the hive (the stage-label
pass marks it `010-actionable`, then the scanner claims it, `020`) β€” and the
governor's next-pass countdown. The gates ahead are always the same three,
in order: **triage** (reporter gate, skipped for admitted reporters and the
hive's own filings) β†’ **actionable** (`010`, written by the stage-label pass)
β†’ **claimed** (`020`, the scanner). `triage/accepted` plus `help wanted` on
a human-filed issue is actionable work at every level: once the label lands
the next pass writes `010` and the scanner may claim it. The dashboard
legend is in [dashboard-sections.md](dashboard-sections.md#hive-activity-monitor).

### How a PR's stage is decided

The automerge sweep already computes one reason per PR per lane each cycle
Expand Down
27 changes: 17 additions & 10 deletions src/pkg/dashboard/open_items.go
Original file line number Diff line number Diff line change
Expand Up @@ -192,19 +192,26 @@ func reconcileRepoOpenItems(r *FrontendRepo) openItemCounts {
r.UnlistedPRs = max(0, r.PRs-counts.PRs)
r.Issues = counts.Issues
r.PRs = counts.PRs
if r.WorkBreakdown != nil {
wb := *r.WorkBreakdown
if wb.Issues.Total() != counts.Issues {
wb.Issues = rebuildIssueBreakdown(wb.Issues, items)
}
if wb.PRs.Total() != counts.PRs {
wb.PRs = rebuildPRBreakdown(items)
}
r.WorkBreakdown = &wb
}
refitRepoWorkBreakdown(r, items, counts)
return counts
}

// refitRepoWorkBreakdown rebuilds the coarse work buckets from the items
// when the breakdown's totals no longer match the item lists.
func refitRepoWorkBreakdown(r *FrontendRepo, items []openItemRef, counts openItemCounts) {
if r.WorkBreakdown == nil {
return
}
wb := *r.WorkBreakdown
if wb.Issues.Total() != counts.Issues {
wb.Issues = rebuildIssueBreakdown(wb.Issues, items)
}
if wb.PRs.Total() != counts.PRs {
wb.PRs = rebuildPRBreakdown(items)
}
r.WorkBreakdown = &wb
}

// rebuildIssueBreakdown recounts the coarse issue buckets from the items.
// The named sub-buckets inside Filtered (needs-human, needs-decision,
// needs-spec, reporter-confirmation, exempt, blocked) come from labels the
Expand Down
9 changes: 8 additions & 1 deletion src/pkg/dashboard/stage_tracker.go
Original file line number Diff line number Diff line change
Expand Up @@ -442,7 +442,11 @@ type StageTrackerItem struct {
// row's βœ“ badge and its hover read these (operator_actions.go).
LastOperatorAction *StageTrackerOperatorAction `json:"last_operator_action,omitempty"`
OperatorActionCount int `json:"operator_action_count,omitempty"`
History []StageTrackerHop `json:"history"`
// New is set on a 000-new item β€” open, unplaced, nothing holding it β€”
// with who moves it next and the gates ahead; the Open column renders
// it as "New Β· waiting for …" (hivecommons/hive#15094).
New *StageTrackerNew `json:"new,omitempty"`
History []StageTrackerHop `json:"history"`
}

// StageTrackerLinkedIssue is one issue a PR closes, as its row's issue
Expand Down Expand Up @@ -1682,6 +1686,7 @@ func (s *Server) buildStageTracker(status *StatusPayload, store *stagelabels.Sto
resp.Items = append(resp.Items, it)
}
prState := s.stageTrackerPRStateResolver(status, resp.RecentlyMerged)
issueFilter := s.issueFilterConfig()
addIssue := func(repoName string, issue github.Issue, bucket, bucketReason string, progress *github.IssueChildren) {
// A closed issue has no stage; a stage label it closed wearing is
// the closed-issue sweep's to remove, not a row to render
Expand Down Expand Up @@ -1732,6 +1737,7 @@ func (s *Server) buildStageTracker(status *StatusPayload, store *stagelabels.Sto
finish(&it, issue.Labels, stage, rec, ok, false)
stageTrackerBlockedBy(&it, issue.OpenBlockers())
stageTrackerBlockedOnPR(&it, issue.Body, bucketReason, status.GitHubBaseURL, prState)
applyStageTrackerNew(&it, stageTrackerNewState(it, ok, issueFilter, status.Governor, now))
if it.Stage == trackerNumberClaimed {
it.ClaimantKind = s.stageTrackerClaimantKind(repoName, issue.Number)
}
Expand Down Expand Up @@ -1770,6 +1776,7 @@ func (s *Server) buildStageTracker(status *StatusPayload, store *stagelabels.Sto
it.Lane = laneHive
}
finish(&it, pr.Labels, labelStage(pr.Labels), rec, ok, pr.Draft)
applyStageTrackerNew(&it, stageTrackerNewState(it, ok, issueFilter, status.Governor, now))
it.SentinelAlert, it.SentinelFindings, it.SentinelReason = s.stageTrackerSentinel(evidenceVerifier, repoName, pr.Number, pr.HeadSHA, pr.Labels)
// The sentinel chip is a merge-gate pill too (the trusted-author
// notice and the real alert alike): sentinel_alert stays truthful
Expand Down
183 changes: 183 additions & 0 deletions src/pkg/dashboard/stage_tracker_new.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,183 @@
package dashboard

import (
"fmt"
"slices"
"strings"
"time"

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

// StageTrackerNewSlug is the pre-stage slug a brand-new open item wears in
// the Open column before any stage pass has placed it: it has no stage/*
// label and no store record, nothing holds or blocks it, and the only
// thing between it and 010/050 is the next pass of whoever moves it
// (hivecommons/hive#15094). Stage stays 0 so the column keys are unchanged.
const StageTrackerNewSlug = "000-new"

// Next movers of a 000-new item.
const (
// StageTrackerMoverMaintainer: a human must accept triage first (the
// reporter-trust gate holds an un-admitted reporter's issue).
StageTrackerMoverMaintainer = "maintainer"
// StageTrackerMoverHive: the hive's own stage-label pass places it on
// its next governor cycle.
StageTrackerMoverHive = "hive"
)

// Gate states on a 000-new item.
const (
StageTrackerGateDone = "done"
StageTrackerGateNext = "next"
StageTrackerGateLater = "later"
)

// StageTrackerGate is one gate ahead of a 000-new item.
type StageTrackerGate struct {
Name string `json:"name"`
State string `json:"state"`
Text string `json:"text"`
}

// StageTrackerNew narrates a 000-new item: who moves it next, when that
// pass is due, and the gates between it and a claim.
type StageTrackerNew struct {
// Since is when the item was opened (the row's since-time).
Since *time.Time `json:"since,omitempty"`
// NextMover is maintainer or hive; NextMoverText the plain words.
NextMover string `json:"next_mover"`
NextMoverText string `json:"next_mover_text"`
// NextPassAt / NextPassInSeconds: the governor's next cycle, when the
// hive is the mover and the governor has published one.
NextPassAt *time.Time `json:"next_pass_at,omitempty"`
NextPassInSeconds int64 `json:"next_pass_in_s,omitempty"`
Gates []StageTrackerGate `json:"gates"`
// Text is the row caption: "New Β· waiting for <mover> (next pass in Nm)".
Text string `json:"text"`
}

// stageTrackerIsNew reports whether a finished row is a 000-new item: no
// stage, no record, nothing holding or blocking it, not a draft, and in a
// bucket that means "not placed yet" rather than "placed outside the
// actionable set" (filtered, hive_advisory, claimed, …).
func stageTrackerIsNew(it StageTrackerItem, hasRec bool) bool {
if it.Stage != 0 || hasRec || it.Hold != nil || len(it.BlockedOn) > 0 || it.BlockedOnPR != nil {
return false
}
for _, m := range it.Modifiers {
if m != modNeedsTriage {
return false
}
}
switch it.Bucket {
case "", stageengineReporterTriageBucket:
return true
case "other":
return it.BucketReason == forgeUnclassifiedReason || it.BucketReason == webhookUnclassifiedReason
}
return false
}

// stageengineReporterTriageBucket mirrors github's workBucketReporterTriage.
const stageengineReporterTriageBucket = "reporter_triage"

// stageTrackerNewState builds the 000-new narration for it, or nil when
// the row is not new. filter is the project's issue filter (nil-safe);
// governor carries the next cycle when published.
func stageTrackerNewState(it StageTrackerItem, hasRec bool, filter *config.IssueFilterConfig, governor FrontendGovernor, now time.Time) *StageTrackerNew {
if !stageTrackerIsNew(it, hasRec) {
return nil
}
n := &StageTrackerNew{Since: it.CreatedAt}
if n.Since == nil {
n.Since = it.UpdatedAt
}
triagePending := it.Kind == "issue" && (it.Bucket == stageengineReporterTriageBucket || slices.Contains(it.Modifiers, modNeedsTriage))
if t, ok := parseGovernorNextKick(governor.NextKickAt); ok {
n.NextPassAt = &t
if left := t.Sub(now); left > 0 {
n.NextPassInSeconds = int64(left / time.Second)
}
}
var pass string
switch {
case n.NextPassAt != nil && n.NextPassInSeconds > 0:
pass = "next pass in " + formatETA(time.Duration(n.NextPassInSeconds)*time.Second)
case n.NextPassAt != nil:
pass = "next pass due now"
}
switch {
case triagePending:
n.NextMover = StageTrackerMoverMaintainer
labels := []string{"triage/accepted"}
if filter != nil {
if l := filter.ReporterTrustRequiredLabelsForNotice(); len(l) > 0 {
labels = l
}
}
n.NextMoverText = "a maintainer's triage (add `" + strings.Join(labels, "` or `") + "`)"
n.Gates = []StageTrackerGate{
{Name: "triage", State: StageTrackerGateNext, Text: "a maintainer accepts triage (" + strings.Join(labels, " / ") + ")"},
{Name: "actionable", State: StageTrackerGateLater, Text: "the stage-label pass marks it 010 actionable"},
{Name: "claimed", State: StageTrackerGateLater, Text: "the scanner claims it (020)"},
}
case it.Kind == "pr":
n.NextMover = StageTrackerMoverHive
n.NextMoverText = "the stage-label pass (β†’ 050 review pending)"
n.Gates = []StageTrackerGate{
{Name: "review", State: StageTrackerGateNext, Text: "the stage-label pass places it at 050 review pending"},
{Name: "merge-gate", State: StageTrackerGateLater, Text: "reviews and checks admit it to the merge gate"},
}
default:
n.NextMover = StageTrackerMoverHive
n.NextMoverText = "the stage-label pass (β†’ 010 actionable), then the scanner"
n.Gates = []StageTrackerGate{
{Name: "triage", State: StageTrackerGateDone, Text: "reporter admitted; no triage label needed"},
{Name: "actionable", State: StageTrackerGateNext, Text: "the stage-label pass marks it 010 actionable"},
{Name: "claimed", State: StageTrackerGateLater, Text: "the scanner claims it (020)"},
}
}
n.Text = "New Β· waiting for " + n.NextMoverText
if pass != "" && n.NextMover == StageTrackerMoverHive {
n.Text += " (" + pass + ")"
} else if pass != "" {
n.Text += fmt.Sprintf("; the hive's %s", pass)
}
return n
}

// parseGovernorNextKick reads FrontendGovernor.NextKickAt (RFC3339).
func parseGovernorNextKick(s string) (time.Time, bool) {
if s == "" {
return time.Time{}, false
}
t, err := time.Parse(time.RFC3339, s)
if err != nil {
return time.Time{}, false
}
return t, true
}

// applyStageTrackerNew stamps the 000-new state on a finished row: slug,
// caption, actor and since-time all read from it.
func applyStageTrackerNew(it *StageTrackerItem, n *StageTrackerNew) {
if n == nil {
return
}
it.New = n
it.StageSlug = StageTrackerNewSlug
it.Caption = n.Text
it.Actor = n.NextMover
if n.Since != nil && it.StageSince == nil {
it.StageSince = n.Since
}
}

// issueFilterConfig is the project's issue filter, or nil without deps.
func (s *Server) issueFilterConfig() *config.IssueFilterConfig {
if s == nil || s.deps == nil || s.deps.Config == nil {
return nil
}
return &s.deps.Config.Project.IssueFilter
}
Loading
Loading