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
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- The stage tracker's `regressed` chip now fires only on a genuine fall: a lapsed claim (020 β†’ 010/015), the claim's PR-evidence flicker (030 β†’ 020), the agent returning to its covering PR (040 β†’ 030) and a 040 β†’ 010 after the covering PR merged partially are no longer booked as regressions; the marker clears on the first forward hop instead of waiting for the item to climb back to the stage it fell from; and on a hive-driven row with nothing waiting on a person it draws as a muted `stage ↓` pill (tooltip: the hive is handling it) outside **Needs attention**, keeping red for human-gated rows ([#14570](https://github.com/hivecommons/hive/issues/14570)).
2 changes: 1 addition & 1 deletion src/docs/dashboard-sections.md

Large diffs are not rendered by default.

47 changes: 43 additions & 4 deletions src/docs/labels-and-control-signals.md
Original file line number Diff line number Diff line change
Expand Up @@ -269,15 +269,15 @@ stateDiagram-v2
s045 --> s015: park label removed by hand on an untriaged issue (approved-direction itself counts as triage, so /hive approve lands on 010)
s020 --> s030: PR under way (hive-open-pr request or start marker naming a branch)
s020 --> s040: PR opened straight from the claim
s020 --> s010: claim released or lapsed with no PR
s020 --> s015: claim released or lapsed with no PR on an untriaged issue
s020 --> s010: claim released or lapsed with no PR (not a regression: 020 is a reservation, nothing was built)
s020 --> s015: claim released or lapsed with no PR on an untriaged issue (not a regression)
s030 --> s040: PR opened
s030 --> s010: PR request failed / start mark lapsed with no PR
s030 --> s015: PR request failed / start mark lapsed with no PR on an untriaged issue
s030 --> s020: PR evidence lapsed while the claim is still held (backward hop, commented)
s040 --> s010: covering PR closed unmerged with no live claim or start marker (backward hop, narrated on the PR)
s040 --> s010: covering PR closed unmerged with no live claim or start marker (backward hop, narrated on the PR; not a regression when the PR merged and left hive/partially-addressed)
s040 --> s015: covering PR closed unmerged on an untriaged issue (backward hop, narrated on the PR)
s040 --> s030: covering PR closed while a PR request / start marker is still live (backward hop, narrated on the PR)
s040 --> s030: the agent is back on the covering PR (live claim with the PR under way; not a regression)
s040 --> s020: covering PR closed while the claim is still held (backward hop, narrated on the PR)
s040 --> s050: the PR takes over (issue stays 040)
s050 --> s060: swarm approve
Expand Down Expand Up @@ -318,6 +318,45 @@ stateDiagram-v2
s100 --> [*]: merged (labels removed)
```

#### The regressed marker: when it is set, when it clears

The dashboard's `regressed` chip and the `<!-- hive:stage-regressed -->`
stage comment both come from one per-item flag in the stage store
(`Record.RegressedFrom`, `src/pkg/stagelabels/store.go`), never from a GitHub
label (`stage/regressed` is retired and stripped on sight). Its lifecycle:

- **Set** by `Store.Observe` when a hop is a regression under
`IsRegression(from, to)`: a numerically backward hop *except* the drawn
exceptions above. Leaving a reservation is never a regression (020 β†’ 010 /
015 on a lapsed or released claim β€” nothing was built); 030 β†’ 020 is the
claim's PR evidence flickering (the issue is still claimed), not a fall;
040 β†’ 030 is the agent back on its PR; leaving 015, 045, 085, 090 and
100 β†’ 095 are reclassifications. A fall that is **progress** β€” 040 β†’ 010
because the covering PR merged and left `hive/partially-addressed` β€” is
never booked either (`Decision.Progress`, `Store.ObserveProgress`).
- **Kept** across a same-stage re-observation and across a backward hop that
is itself not a regression (a 040 β†’ 020 fall followed by 020 β†’ 010 stays
regressed: the item has not moved ahead yet).
- **Cleared** by the first forward hop of any size (not only by climbing back
to the stage it fell from), by a progress fall, or when the rule changes so
the recorded fall no longer counts (old records heal on their next
observation). The clear happens in the same tick that applies the new
stage label, and the dashboard stops drawing the chip on its next
`GET /api/stage-tracker` (`regressed_from` is absent, the modifier gone).

How the chip renders depends on whether a person is in the loop. On a
hive-driven stage with no human-gate modifier (`hold`, `needs-human`,
`needs-decision`, `needs-rebase`, `blocked`, `stalled`) and off the
human-gated stages (045 / 071 / 072 / 085 / 090), it draws as a muted,
dashed `stage ↓` pill whose hover text names the fall and ends "the hive is
handling it β€” no action needed; clears on the next forward step", and the
row stays out of **Needs attention** and keeps its ordinary headline. Only a
regression on a human-gated row keeps the red `regressed` pill and the
"Sent back" headline β€” red means someone has to act
([#14570](https://github.com/hivecommons/hive/issues/14570): freshly
filed issues whose claim lapsed wore a red `regressed` that read as a call to
action).

### How an issue's stage is decided

The enumeration cycle already sorts every open issue into a work bucket
Expand Down
9 changes: 9 additions & 0 deletions src/pkg/dashboard/stage_tracker_motion_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -418,6 +418,11 @@ func TestStageTrackerMotionRowStamp(t *testing.T) {
jsFunc(t, html, "stageTrackerStripItems"),
jsFunc(t, html, "stageTrackerCurrentStageHtml"),
jsFunc(t, html, "stageTrackerStageWord"),
jsConstLine(t, html, "STAGE_TRACKER_ATTENTION_STAGES"),
jsConstLine(t, html, "STAGE_TRACKER_HUMAN_MODS"),
jsConstLine(t, html, "STAGE_TRACKER_HANDLED_TEXT"),
jsConstLine(t, html, "STAGE_TRACKER_HANDLED_NOTE"),
jsFunc(t, html, "stageTrackerRegressionHandled"),
jsFunc(t, html, "stageTrackerRegressionText"),
jsFunc(t, html, "stageTrackerTooltip"),
jsFunc(t, html, "stageTrackerChipsHtml"),
Expand Down Expand Up @@ -522,6 +527,10 @@ func TestStageTrackerMotionPreviewSample(t *testing.T) {
jsFunc(t, html, "stageTrackerStripItems"),
jsFunc(t, html, "stageTrackerCurrentStageHtml"),
jsFunc(t, html, "stageTrackerStageWord"),
jsConstLine(t, html, "STAGE_TRACKER_HUMAN_MODS"),
jsConstLine(t, html, "STAGE_TRACKER_HANDLED_TEXT"),
jsConstLine(t, html, "STAGE_TRACKER_HANDLED_NOTE"),
jsFunc(t, html, "stageTrackerRegressionHandled"),
jsFunc(t, html, "stageTrackerRegressionText"),
jsFunc(t, html, "stageTrackerTooltip"),
jsFunc(t, html, "stageTrackerChipsHtml"),
Expand Down
42 changes: 39 additions & 3 deletions src/pkg/dashboard/stage_tracker_regressed_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -75,15 +75,21 @@ func TestStageTrackerRegressedPillExplainsItself(t *testing.T) {
jsFunc(t, html, "stageTrackerStageWord"),
jsConstLine(t, html, "STAGE_TRACKER_NEEDS_DECISION"),
stageTrackerSentinelJS(t, html),
jsConstLine(t, html, "STAGE_TRACKER_ATTENTION_STAGES"),
jsConstLine(t, html, "STAGE_TRACKER_HUMAN_MODS"),
jsConstLine(t, html, "STAGE_TRACKER_HANDLED_TEXT"),
jsConstLine(t, html, "STAGE_TRACKER_HANDLED_NOTE"),
jsFunc(t, html, "stageTrackerRegressionHandled"),
jsFunc(t, html, "stageTrackerRegressionText"),
jsFunc(t, html, "stageTrackerChipsHtml"),
}, "\n") + `
const item = { stage: 10, modifiers: ['regressed'], regressed_from: 40, regressed_to: 20, regressed_at: '2026-10-22T12:44:59Z', regressed_reason: 'live issue claim' };
const text = stageTrackerRegressionText(item, 0);
assert.strictEqual(text, 'regressed: 040 Covered by PR β†’ 020 Claimed at T' + Date.parse(item.regressed_at) + ' because live issue claim Β· now 010 Actionable');
// On a hive-driven stage with no human gate the explanation ends with the "no action needed" note.
assert.strictEqual(text, 'regressed: 040 Covered by PR β†’ 020 Claimed at T' + Date.parse(item.regressed_at) + ' because live issue claim Β· now 010 Actionable Β· ' + STAGE_TRACKER_HANDLED_NOTE);
// No hop detail: falls back to the current stage, no time, no reason.
assert.strictEqual(stageTrackerRegressionText({ stage: 20, modifiers: ['regressed'], regressed_from: 40 }, 0), 'regressed: 040 Covered by PR β†’ 020 Claimed');
// Unknown stage numbers still read as codes.
assert.strictEqual(stageTrackerRegressionText({ stage: 20, modifiers: ['regressed'], regressed_from: 40 }, 0), 'regressed: 040 Covered by PR β†’ 020 Claimed Β· ' + STAGE_TRACKER_HANDLED_NOTE);
// Unknown stage numbers still read as codes; 072 is parked on a person, so no note.
assert.strictEqual(stageTrackerRegressionText({ stage: 72, modifiers: ['regressed'], regressed_from: 100 }, 0), 'regressed: 100 β†’ 072');
// Not regressed β†’ nothing.
assert.strictEqual(stageTrackerRegressionText({ stage: 10, modifiers: ['stalled'], regressed_from: 40 }, 0), '');
Expand All @@ -93,6 +99,36 @@ const pill = stageTrackerChipsHtml(item);
assert.ok(pill.includes('title="regressed: 040 Covered by PR β†’ 020 Claimed at T'), pill);
assert.ok(pill.includes('because live issue claim'), pill);
assert.ok(!stageTrackerChipsHtml({ stage: 10, modifiers: ['stalled'] }).includes('title='));
// Hive-handled: muted "stage ↓" pill, never the red regressed look, and it says so on hover.
const handledCases = [
{ name: 'actionable', item: item },
{ name: 'claimed', item: { stage: 20, modifiers: ['regressed'], regressed_from: 30 } },
{ name: 'pr in progress', item: { stage: 30, modifiers: ['regressed'], regressed_from: 40 } },
{ name: 'draft folds in', item: { kind: 'pr', stage: 50, modifiers: ['regressed', 'draft'], regressed_from: 100 } },
];
for (const c of handledCases) {
assert.ok(stageTrackerRegressionHandled(c.item), c.name);
const h = stageTrackerChipsHtml(c.item);
assert.ok(h.includes(STAGE_TRACKER_HANDLED_NOTE), c.name + ': ' + h);
if (c.item.modifiers.length === 1) {
assert.ok(h.includes('ham-mod-regressed ham-mod-handled') && h.includes('>' + STAGE_TRACKER_HANDLED_TEXT + '<'), c.name + ': ' + h);
} else {
assert.ok(!h.includes('ham-mod-regressed') && h.includes('ham-mod-draft') && h.includes(' +1<'), c.name + ' yields the lead pill: ' + h);
}
}
// A human gate keeps the red "regressed" pill: a human-gated stage or a human-call modifier.
const redCases = [
{ name: 'needs decision stage', item: { stage: 85, modifiers: ['regressed'], regressed_from: 100 } },
{ name: 'returned to contributor', item: { stage: 72, modifiers: ['regressed'], regressed_from: 100 } },
{ name: 'needs-rebase alongside', item: { kind: 'pr', stage: 70, modifiers: ['regressed', 'needs-rebase'], regressed_from: 100 } },
{ name: 'hold alongside', item: { stage: 10, modifiers: ['regressed', 'hold'], regressed_from: 40 } },
];
for (const c of redCases) {
assert.ok(!stageTrackerRegressionHandled(c.item), c.name);
const h = stageTrackerChipsHtml(c.item);
assert.ok(h.includes('ham-mod-regressed') && !h.includes('ham-mod-handled') && h.includes('>regressed'), c.name + ': ' + h);
assert.ok(!h.includes(STAGE_TRACKER_HANDLED_NOTE), c.name + ': ' + h);
}
`
out, err := exec.Command(node, "-e", script).CombinedOutput()
if err != nil {
Expand Down
4 changes: 4 additions & 0 deletions src/pkg/dashboard/stage_tracker_repo_grouping_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -140,6 +140,10 @@ func stageTrackerRepoGroupingHarness(t *testing.T, html string) string {
jsFunc(t, html, "stageTrackerStripItems"),
jsFunc(t, html, "stageTrackerCurrentStageHtml"),
jsFunc(t, html, "stageTrackerStageWord"),
jsConstLine(t, html, "STAGE_TRACKER_HUMAN_MODS"),
jsConstLine(t, html, "STAGE_TRACKER_HANDLED_TEXT"),
jsConstLine(t, html, "STAGE_TRACKER_HANDLED_NOTE"),
jsFunc(t, html, "stageTrackerRegressionHandled"),
jsFunc(t, html, "stageTrackerRegressionText"),
jsFunc(t, html, "stageTrackerTooltip"),
jsFunc(t, html, "stageTrackerChipsHtml"),
Expand Down
15 changes: 15 additions & 0 deletions src/pkg/dashboard/stage_tracker_ui_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -148,6 +148,10 @@ func TestStageTrackerRows(t *testing.T) {
jsFunc(t, html, "stageTrackerStripItems"),
jsFunc(t, html, "stageTrackerCurrentStageHtml"),
jsFunc(t, html, "stageTrackerStageWord"),
jsConstLine(t, html, "STAGE_TRACKER_HUMAN_MODS"),
jsConstLine(t, html, "STAGE_TRACKER_HANDLED_TEXT"),
jsConstLine(t, html, "STAGE_TRACKER_HANDLED_NOTE"),
jsFunc(t, html, "stageTrackerRegressionHandled"),
jsFunc(t, html, "stageTrackerRegressionText"),
jsFunc(t, html, "stageTrackerTooltip"),
jsFunc(t, html, "stageTrackerChipsHtml"),
Expand Down Expand Up @@ -438,6 +442,13 @@ for (const parked of [45, 85]) {
}
// 045 needs attention like the other parking stages.
assert.ok(stageTrackerNeedsAttention({ kind: 'issue', stage: 45 }) && stageTrackerNeedsAttention({ kind: 'pr', stage: 85 }) && !stageTrackerNeedsAttention({ kind: 'issue', stage: 10 }));
// A regression the hive is working through is not a call on a person: out of "Needs attention", no "Sent back" headline.
assert.ok(!stageTrackerNeedsAttention({ kind: 'issue', stage: 10, modifiers: ['regressed'], regressed_from: 40 }), 'regressed at Actionable is hive-handled');
assert.ok(!stageTrackerNeedsAttention({ kind: 'issue', stage: 30, modifiers: ['regressed', 'draft'], regressed_from: 40 }), 'draft is not a human gate');
assert.ok(stageTrackerNeedsAttention({ kind: 'issue', stage: 85, modifiers: ['regressed'], regressed_from: 100 }), 'regressed while parked on a person');
assert.ok(stageTrackerNeedsAttention({ kind: 'pr', stage: 70, modifiers: ['regressed', 'needs-rebase'], regressed_from: 100 }), 'regressed with a human-call modifier');
assert.notStrictEqual(stageTrackerHeadline({ kind: 'issue', stage: 10, modifiers: ['regressed'], regressed_from: 40 }), 'Sent back');
assert.strictEqual(stageTrackerHeadline({ kind: 'pr', stage: 70, modifiers: ['regressed', 'needs-rebase'], regressed_from: 100 }), 'Sent back');
// ...but an issue whose single covering PR sits on 085 still rides the PR's
// merge gate, with the "(its PR)" suffix.
row = stageTrackerRowHtml({ repo: 'acme/console', number: 356, kind: 'issue', stage: 40, linked_prs: [{ number: 109, author_kind: 'hive', stage: 85 }] }, stages, ctx);
Expand Down Expand Up @@ -717,6 +728,10 @@ func TestStageTrackerFilterSortPage(t *testing.T) {
jsFunc(t, html, "stageTrackerAnchor"),
jsFunc(t, html, "stageTrackerLinkedSorted"),
jsFunc(t, html, "stageTrackerSortKey"),
jsConstLine(t, html, "STAGE_TRACKER_HUMAN_MODS"),
jsConstLine(t, html, "STAGE_TRACKER_HANDLED_TEXT"),
jsConstLine(t, html, "STAGE_TRACKER_HANDLED_NOTE"),
jsFunc(t, html, "stageTrackerRegressionHandled"),
jsFunc(t, html, "stageTrackerNeedsAttention"),
jsFunc(t, html, "stageTrackerWaitSince"),
jsFunc(t, html, "stageTrackerLabelFamily"),
Expand Down
Loading
Loading