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-needs-decision-real-stage.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Activity Monitor: a PR parked at `stage/085-needs-decision` whose head is short of merge-ready (checks running, red or unreported; review verdict pending or asking for a person) now lights its real stage — the CI or Review track, with an amber human-gated marker — and carries the ask as the **needs human decision** pill (question in the hover, decision popover on click) instead of forcing a *Needs human · decision* chevron into the PR in progress column while CI and Review spun dim (#17442, #17416). PR in progress is passed, Merge queue stays empty; one lit stage per row.
9 changes: 5 additions & 4 deletions src/docs/dashboard-sections/activity-monitor.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ Side stages share a column rather than adding columns:
| 045 Needs human decision | Actionable on an issue. A pre-045 issue still wearing 085 is drawn here until reconciliation. |
| 070 Fixing / 071 Needs author / 072 Returned to contributor | CI / Review: Hive repairs its own PR at 070; a human author acts at 071; a contributor agent gets its PR back at 072. `needs-rebase` explains a repair here, not at 050. |
| 074 Adopted by hive | CI / Review while the Hive repairs adopted work; pending, green or red pushes remain 074 until the merge gate takes it. |
| 085 Needs human decision / 090 Ready for human merge | Merge queue on a PR. Read the decision or merge reason rather than assuming Hive will merge it. A 090 cell reading **Held · sentinel · confirm intent** or **Held · hold** is a gate on an otherwise ready PR: Hive never merges it while the gate stands. |
| 085 Needs human decision / 090 Ready for human merge | A human gate is a pill on the PR's real stage, not a stage of its own ([#17327](https://github.com/hivecommons/hive/issues/17327), [#17453](https://github.com/hivecommons/hive/issues/17453)). A 085 PR whose head is short of merge-ready — checks running, red or unreported; the review verdict pending or asking for a person — lights **CI / Review** (the CI track while checks run or are not green, the Review track while its verdict is what waits), with an amber marker on the lit track and the **needs human decision** pill carrying the question (its popover holds the actions); PR in progress is passed, Merge queue empty. Only a 085 PR that is merge-ready (review approved, CI green on this head), queued or merging, and every 090, sits in the **Merge queue** column — read the decision or merge reason rather than assuming Hive will merge it. A 090 cell reading **Held · sentinel · confirm intent** or **Held · hold** is a gate on an otherwise ready PR: Hive never merges it while the gate stands. |
| 060 / 080 / 095 / 100 | Separate gate states; use the [merge-gate reference](#merge-queue-pills--legend) below for exact words and countdowns. |

The author legend is a blue Hive hexagon, purple contributor-agent robot or teal human silhouette. The kind is `author/*`, inferred from the snapshot if its label is absent; the link tooltip names the login. On Claimed, the actor is the claim holder; on PR in progress and Returned to contributor it is the author. Hive owns review, adoption and auto-merge work; a human owns a human decision or manual merge. The payload's `stage_actor` is the authoritative actor (see [Who is on it](#who-is-on-it-actor-icons)).
Expand Down Expand Up @@ -244,13 +244,13 @@ The payload also carries `sentinel_details`: one entry per finding with its `rul

A person's *Approve* through that dialog **is** the human review the alert asked for: it removes the `sentinel-alert` label when present and records a `sentinel_acknowledged` human action keyed to the head in the review evidence bundle, so a bundle-only alert (findings but no label — hivecommons/crux#30) clears too; the payload then reads `sentinel_alert: false` with `sentinel_reason` suffixed `— acknowledged by @login`, the findings stay on record, and a new head starts over.

The delegated *Let hive decide* path never clears it. Hovering the lit chevron of a parked row names the parking stage itself (`Needs human decision`), not the 080 column it rides on; `Next move` follows the real stage (human at 085 and at a held 090, hive at 080). A held row's stage never advances the merge: the lanes and the dashboard's one-click shortcuts check the gate itself, so a parked PR never merges unattended. Lane text and chip update in place on refresh (keyed reconcile, no flash).
The delegated *Let hive decide* path never clears it. Hovering the lit chevron of a parked row names the parking stage itself (`Needs human decision`) when it sits in the Merge queue column, and *· needs a person: <question>* on the lit CI / Review track when the head is not merge-ready ([#17453](https://github.com/hivecommons/hive/issues/17453)); `Next move` follows the real stage (human at 085 and at a held 090, hive at 080). A held row's stage never advances the merge: the lanes and the dashboard's one-click shortcuts check the gate itself, so a parked PR never merges unattended. Lane text and chip update in place on refresh (keyed reconcile, no flash).

#### Unauthorized pill

A pull request the hive cannot move because its GitHub App lacks a permission for the next step — it wears `hive:unauthorized` ([#14589](https://github.com/hivecommons/hive/issues/14589)); first case: approving held `action_required` workflow runs needs `actions: write` — carries the `unauthorized` modifier in the tracker payload, drawn in the far-right pill column exactly like `stalled` / `hold` / `draft` but muted (dashed, `--text-muted`), never red: it is nothing wrong, just a step only a person may take.

It counts under **Needs attention**. Before the merge gate only the held-workflow-runs step shows (see *Pills before the merge gate*). Its tooltip (payload `unauthorized`) names the missing permission and the human step; on the **Needs human decision** lane the lit chevron and the caption read **Awaiting human: approve workflow runs** (payload `unauthorized_step`, from the `unauthorized:<step>` stage reason). The pill, label and payload fields clear themselves in the tick the step is no longer needed.
It counts under **Needs attention**. Before the merge gate only the held-workflow-runs step shows (see *Pills before the merge gate*). Its tooltip (payload `unauthorized`) names the missing permission and the human step; on the **Needs human decision** lane the caption reads **Awaiting human: approve workflow runs** (payload `unauthorized_step`, from the `unauthorized:<step>` stage reason) and the row lights its real stage — the CI / Review track, amber-marked — with the `unauthorized` pill carrying the step ([#16524](https://github.com/hivecommons/hive/issues/16524), [#17453](https://github.com/hivecommons/hive/issues/17453)). The pill, label and payload fields clear themselves in the tick the step is no longer needed.

#### Merge train

Expand Down Expand Up @@ -456,7 +456,8 @@ An *active* chevron is filled amber and carries words; an inactive one is its ic
2. **CI and Review resolve first.** A track is active only while it genuinely runs on the current head (a check-run in progress or queued, a ring not yet full; a reviewer running or queued). If either runs, the PR is waiting on it: the stage chevron (PR in progress, Merge queue …) renders settled-current — filled but still, icon only, its words in the tooltip — and nothing else is active.
3. **CI leads Review.** When both tracks would light at once — CI running while the review is queued, in progress or being re-adjudicated — CI is the lit chevron and Review is dim with a small note (*re-review queued* after a push, *review in progress*, *review queued*); its words stay in the tooltip, ending *… behind CI*. The stage chevron is the fallback: active only when no track is in motion.
4. **The PR in progress chevron speaks the PR's lifecycle** — draft, pushed, rebasing, *Unassigned · next: scanner*, *Deferred · waiting on #N*, *Waiting for @author · fix owed* — never a CI or review verdict. *CI failing*, *CI 4/11 · 1 failing* and *changes requested* are the CI and Review chevrons' words; the PR in progress tooltip keeps the red reason as detail.
5. **The CI and Review tooltips state what the track waits on — never "activity unknown".** With no verdict and no reviewer in flight the spoke derives the Review statement from what it already knows, in this order: the PR is merged or closed (*Review · n/a (closed)*), it is a draft (*Review · draft, not requested*), CI on the head has not finished (*Review · waiting for CI*), CI is done and nobody started (*Review · not started · hive reviewer next*, or *· needs reviewer* when the repo has no hive reviewer lane). A settled verdict explains itself — *Changes requested by the hive reviewer: 1 perspective posted findings … · 12m ago · quality ✓ · security ✗: token logged* — and stays known as its observation ages. The one no-data wording, *Review · no data for head f269349 yet · refreshing* (CI: *CI · no checks observed for head … yet · refreshing*), appears only when the spoke has fetched nothing for the head, and names the next step.
5. **A human gate is a pill, not a stage.** A PR parked at 085 for a person — a reviewer's question, a permission only a maintainer holds, a rerun to approve — with checks running, red or unreported, or its review verdict pending, is drawn at its real stage: CI (with motion while checks run) or Review is the one lit chevron, wearing an amber marker (`ham-human-gated`), and the ask is the **needs human decision** pill in the row's pill strip (human icon, the question in its hover, the decision popover on click); the lit track's tooltip ends *· needs a person: <question>*. It never lights a *Needs human · decision* chevron in the PR in progress column while CI and Review spin dim ([#17453](https://github.com/hivecommons/hive/issues/17453): #17442 did, with CI 3/9 running; #17416 read *Needs human · review* the same way). Only a merge-ready, queued or merging 085 is a Merge queue matter.
6. **The CI and Review tooltips state what the track waits on — never "activity unknown".** With no verdict and no reviewer in flight the spoke derives the Review statement from what it already knows, in this order: the PR is merged or closed (*Review · n/a (closed)*), it is a draft (*Review · draft, not requested*), CI on the head has not finished (*Review · waiting for CI*), CI is done and nobody started (*Review · not started · hive reviewer next*, or *· needs reviewer* when the repo has no hive reviewer lane). A settled verdict explains itself — *Changes requested by the hive reviewer: 1 perspective posted findings … · 12m ago · quality ✓ · security ✗: token logged* — and stays known as its observation ages. The one no-data wording, *Review · no data for head f269349 yet · refreshing* (CI: *CI · no checks observed for head … yet · refreshing*), appears only when the spoke has fetched nothing for the head, and names the next step.

On a red PR (CI failing or changes requested on the current head, or a 07x fix stage) the PR in progress word comes from pickup evidence:

Expand Down
6 changes: 5 additions & 1 deletion src/pkg/dashboard/stage_tracker_build.go
Original file line number Diff line number Diff line change
Expand Up @@ -166,7 +166,10 @@ func (s *Server) buildStageTracker(status *StatusPayload, store *stagelabels.Sto
it.Modifiers, it.DeferredModifiers = stageTrackerModifiers(labels, status.HiveID, rec, hasRec, overrides, now, draft, it.Reason, it.Kind, stage, it.Mirrored)
// 045/085 have their own chevron word ("Needs human decision"); the
// chip only adds information when needs-decision modifies another
// stage.
// stage — or when the 085 row's chevron is its real stage (CI /
// Review) and the pill is what carries the ask; that case is
// re-added once the head's tracks are known
// (stageTrackerApplyPersonActsOnPRPill).
if stage == stagelabels.NeedsDecision || stage == stagelabels.IssueNeedsDecision {
it.Modifiers = slices.DeleteFunc(it.Modifiers, func(m string) bool { return m == modNeedsDecision })
}
Expand Down Expand Up @@ -565,6 +568,7 @@ func (s *Server) buildStageTracker(status *StatusPayload, store *stagelabels.Sto
it.CodeActivity, it.Remediation, it.Deferral, it.ReviewActivity, it.DisplayColumn, it.Caption = activityItem.CodeActivity, activityItem.Remediation, activityItem.Deferral, activityItem.ReviewActivity, activityItem.DisplayColumn, activityItem.Caption
stageTrackerApplyReworkOwedBy(it)
stageTrackerApplyTrainQueuedCaption(it)
stageTrackerApplyPersonActsOnPRPill(it)
}
stageTrackerApplyReauthor(resp.Items, store, status.GitHubBaseURL, now)
resp.NeedsHuman, resp.OnHold = stageTrackerHumanCounts(resp.Items)
Expand Down
2 changes: 1 addition & 1 deletion src/pkg/dashboard/stage_tracker_decision_popover_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -155,7 +155,7 @@ func TestStageTrackerDecisionPopoverTriggersInRow(t *testing.T) {
`typeof stageTrackerDecisionOf === 'function' ? stageTrackerDecisionOf(item) : null`,
`stageTrackerDecisionTriggerHtml(decision, caption, fullTip)`,
`if (typeof hideConfigTooltip === 'function') hideConfigTooltip();`,
`stageTrackerDecisionTriggerHtml(decision, inner, tip, 'ham-badge ham-badge-mod ' + cls)`,
`stageTrackerDecisionTriggerHtml(decision, askIco ? askIco + ` + "`<span class=\"ham-mod-word\">${inner}</span>`" + ` : inner, tip, 'ham-badge ham-badge-mod ' + cls + (askIco ? ' ham-mod-ask' : ''))`,
`${decision ? '' : ` + "` title=\"${esc(tip)}\"`" + `}`,
`if (typeof stageTrackerWireDecisionPop === 'function') stageTrackerWireDecisionPop(el);`,
`decision_needed: lp.decision_needed || null`,
Expand Down
27 changes: 27 additions & 0 deletions src/pkg/dashboard/stage_tracker_hold_provenance_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -146,6 +146,7 @@ func TestStageTrackerHoldProvenanceJS(t *testing.T) {
"function stageTrackerItemKey(it) { return it.repo + '/' + it.kind + '#' + it.number; }",
"function stageTrackerDecisionTriggerHtml(decision, inner, tip, cls) { return '<button class=\"' + cls + ' ham-decision-trigger\" data-ham-decision=\"' + esc(decision.key) + '\">' + inner + '</button>'; }",
jsConstLine(t, html, "STAGE_TRACKER_MOD_PRIORITY"),
jsConstLine(t, html, "STAGE_TRACKER_HUMAN_MODS"),
jsConstLine(t, html, "STAGE_TRACKER_MOD_TEXT"),
jsConstLine(t, html, "STAGE_TRACKER_HANDLED_TEXT"),
jsConstLine(t, html, "STAGE_TRACKER_DRAFT_TIP"),
Expand All @@ -155,7 +156,10 @@ func TestStageTrackerHoldProvenanceJS(t *testing.T) {
jsFunc(t, html, "stageTrackerDecisionOf"),
jsFunc(t, html, "stageTrackerHoldPill"),
jsFunc(t, html, "stageTrackerHoldTip"),
jsConstBlock(t, html, "STAGE_TRACKER_ICONS"),
jsFunc(t, html, "stageTrackerIcon"),
jsFunc(t, html, "stageTrackerChipsHtml"),
stageTrackerManualMergeJS(t, html),
}, "\n")+`
const hold = { by: 'hive', source: 'reporter-trust', reason: 'reporter trust (issue #15017 by @Karibhou, contributor)', since: '2026-10-20T17:14:14Z', issue: 15017, reporter: 'Karibhou', association: 'contributor', pill: 'Held by hive · reporter trust (issue #15017 by @Karibhou, contributor)' };
const decision = { question: 'The hive held this PR itself for reporter trust (issue #15017 by @Karibhou, contributor). Release the hold, or keep it?', asked_by: 'the hive', options: [ { action: 'release', label: 'Release hold', enabled: true } ] };
Expand All @@ -182,5 +186,28 @@ assert.strictEqual(stageTrackerHoldPill({ hold: null }), '');
assert.strictEqual(stageTrackerHoldTip({ hold: {} }, 0), '');
// Without the pill field the text is built from the parts.
assert.strictEqual(stageTrackerHoldPill({ hold: { by: 'hive', reason: 'r' } }), 'Held by hive · r');
// hivecommons/hive#17442 (#17453): a 085 PR with CI running and the review
// verdict pending lights its real stage, so the ask rides as the
// needs-decision pill — even on a payload that predates the server adding
// the modifier — and that pill opens the decision popover.
const ask = { question: 'Dependabot alerts need the security_events read permission. Grant it, or merge without the check?', asked_by: 'sec-check', options: [ { action: 'decide:approve', label: 'Approve', enabled: true }, { action: 'decide:delegate', label: 'Let hive decide', enabled: true } ] };
const running = { repo: 'hivecommons/hive', kind: 'pr', number: 17442, stage: 85, head: 'c0ffee1', modifiers: [], decision_needed: ask,
ci_activity: { head: 'c0ffee1', state: 'running', active: true, checks_passed: 3, checks_total: 9 },
review_activity: { head: 'c0ffee1', state: 'human_decision', perspectives_done: 5, perspectives_total: 5 } };
const rpill = stageTrackerChipsHtml(running);
assert.ok(rpill.includes('ham-mod-needs-decision') && rpill.includes('>needs human decision<'), rpill);
assert.ok(rpill.includes('ham-mod-ask') && rpill.includes('ham-mod-ico') && rpill.includes('<span class="ham-mod-word">needs human decision</span>'), 'the ask pill wears the person icon with its words foldable: ' + rpill);
assert.ok(rpill.includes('ham-decision-trigger') && rpill.includes('data-ham-decision="hivecommons/hive/pr#17442"'), rpill);
assert.ok(!rpill.includes('+1'), 'one pill, not duplicated: ' + rpill);
// The server already carrying the modifier adds nothing twice.
const served = stageTrackerChipsHtml(Object.assign({}, running, { modifiers: ['needs-decision'] }));
assert.strictEqual((served.match(/ham-mod-needs-decision/g) || []).length, 1, served);
assert.ok(!served.includes('+1'), served);
// A pill that already names the person owed (unauthorized, hold) stands in: no needs-decision stacked behind it.
const gated = stageTrackerChipsHtml(Object.assign({}, running, { modifiers: ['unauthorized'] }));
assert.ok(!gated.includes('ham-mod-needs-decision') && !gated.includes('+1'), gated);
// A merge-ready 085 twin (approved + CI green) is the gate's: no invented pill.
const ready = stageTrackerChipsHtml(Object.assign({}, running, { ci_activity: { head: 'c0ffee1', state: 'passing' }, review_activity: { head: 'c0ffee1', state: 'approved' } }));
assert.ok(!ready.includes('ham-mod-needs-decision'), ready);
`)
}
Loading
Loading