diff --git a/changelog.d/fixed-regressed-badge-only-on-real-regressions.md b/changelog.d/fixed-regressed-badge-only-on-real-regressions.md new file mode 100644 index 0000000000..5decb84698 --- /dev/null +++ b/changelog.d/fixed-regressed-badge-only-on-real-regressions.md @@ -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)). diff --git a/src/docs/dashboard-sections.md b/src/docs/dashboard-sections.md index 000eb76ba3..aec535f47c 100644 --- a/src/docs/dashboard-sections.md +++ b/src/docs/dashboard-sections.md @@ -631,7 +631,7 @@ More about the line: A progress strip per open issue and pull request showing which step of the pipeline it is on and who must act next. -Fed by `GET /api/stage-tracker`. Every issue and pull request follows the same pipeline, named once in the column header above the list: `Open → Actionable (010) → Claimed (020) → PR in progress (030/040) → CI / Review (050/060) → Merge gate (080/100) → ✓ merged`. Each entry is a title line over a thin chevron strip. Only the current step is coloured: it is filled amber and carries the step name in words; once the PR is merged the final ✓ chevron is the lit one, in green. Motion is reserved for what is running or needs a hand — the lit chevron falls into one of three buckets (`stageTrackerMotion()` in `index.html`): **static** (steady): Open, Open · on hold (any hold label wins over every other signal), Actionable (010), Claimed (020), PR in progress / Covered by PR (030/040) by a human author, Merged, and any unrecognised stage; **active** (gentle pulse): the hive is acting — 030/040 by a hive or clanker author, 050 review pending, 060 reviewed, 070 fixing, 074 adopted by hive, 080 merge gate, 095 pre-merge soak, 100 merge queue; **needs-human** (slower amber→red breathe): a person must move — 015 triage needed, 045/085 needs decision, 071 needs author, 072 returned to contributor, 090 ready for a human merge, or a `stalled` / `blocked` / `needs-human` / `needs-decision` / `needs-triage` modifier on any stage. Under `prefers-reduced-motion` nothing animates; a needs-human step keeps a steady red tint so it still stands out. Every other step is a low-contrast shape with a small grey glyph (circle, bolt, lock, branch, eye, shield, check) — passed steps a subtle neutral fill, steps ahead a faint outline. Side stages are not extra steps: `070 Fixing` (the author's move; the `needs-rebase` chip next to it says what is being fixed — the stage labeller always parks a needs-rebase PR at 070/071/072, never at CI / Review), `071 Needs author` (human-authored), `072 Returned to contributor` (clanker-authored) and `074 Adopted by hive` light *CI / Review* with their own name (an adopted PR stays on 074 through the hive's pushes going pending, green or red again, and moves on only when *Merge gate* takes it); `085 Needs human decision` (PR-only) and `090 Ready for human merge` light *Merge gate* with their own name (the 085 tooltip says what must be decided); an issue parked on a person wears `045 Needs human decision` and lights *Actionable* (the issue side) with that name — a pre-045 issue still wearing 085 is drawn the same way until the reconciler re-stages it; an actionable issue no maintainer has looked at yet wears `015 Triage needed` (carrying `needs-triage`, or held in the reporter-trust gate's `reporter_triage` bucket — never derived from who filed it) and lights *Actionable* as "Triage needed" (a human's move) — so the Actionable column reads "Actionable", "Triage needed" or "Needs human decision", and the Open column is untouched. An issue carrying a hold-class label (`hold`, `do-not-merge*`, `hive-pause/`) is never parked: it sits at *Open* as "Open · on hold" even beside `needs-human`, and the reconciler removes any 045 the hold caught it with ([#13012](https://github.com/hivecommons/hive/issues/13012)). The lit chevron ends with an ink-coloured icon of whose move it is — person (human), robot (clanker) or hexagon (hive): the claim holder on Claimed, the PR author on PR in progress and Returned to contributor, hive on CI / Review, Adopted by hive and Ready for auto merge, a human on Needs human decision and Ready for human merge. `040 Covered by PR` shares the *PR in progress* column with 030; `060 Reviewed`, `080 Awaiting merge admission` and `100 Merge queue` all light *Merge gate* as "Ready for auto merge" (the chevron tooltip says "not yet admitted — " for 060/080 and "admitted, merging" for 100); `095 Pre-merge soak` lights the same column as "Soaking" (hive's move; tooltip "admitted, soaking — Xm left", headline "Pre-merge soak — Xm left" from the payload's `soak_remaining_seconds`, aged from the lane's last sweep), so an admitted PR inside its soak window is no longer drawn as merging; the chevron's own tooltip names the exact stage. Covering pull requests nest under their issue. An issue with no PR yet draws the whole strip like any other row, lit at Open, Actionable or Claimed with the steps ahead faint. Once exactly one PR covers it, issue and PR are a single entry: the issue's `#N title` on the left, `↳ [author icon] #PR title` under the *PR in progress* header on the same title line (the ↳ marks a PR drawn on its issue's row; the PR link's tooltip says so — "linked PR, shown on its issue's row" — and, when two open issues list the same PR, every row but the lowest-numbered issue adds "also under #N"), and one continuous strip — Open, Actionable and Claimed passed, the PR's stage lighting the chevron from PR in progress through CI / Review, Merge gate and ✓; the chip, tooltip and `since` are the PR's. With two or more covering PRs the issue's own strip stops at Claimed — all passed, nothing on the issue line lit. Directly beneath, tighter than the gap between entries, sits one indented sub-row per open covering PR, furthest along first: `[author icon] #N title` at the *PR in progress* column, then that PR's own strip from there on — `PR in progress → CI / Review → Merge gate → ✓` — with its own lit chevron, chip, tooltip and `since`. So an issue with two PRs, one at 030, shows "PR in progress" lit on that sub-row, not on the issue. A PR linked to an open issue in the list has no top-level row of its own; a PR with no linked issue keeps a full-width row and shows the first steps as passed. A PR whose only linked issue is already closed — a superseded PR whose body still says `Fixes #N` after an earlier PR fixed it — keeps its own row with the closed issue in the issue slot: `#N title` as a link, muted and struck through, followed by a small `closed` chip, so the pairing reads at a glance; when the title cannot be resolved the slot says `#N (closed issue)` rather than a bare number (the title comes from the snapshot, or from one cached issue read the cycle makes once per issue — see [Linked issues](dashboard.md#pr-review-and-link-signals)). The *Pull requests* filter flattens the list — every PR as a top-level row; *Issues* and *All* show the nested view. Each row is named once on the left; a covering PR appears under the *PR in progress* header as `[author icon] #N title`. A pull request with no linked issue is named once: `[PR icon] [author icon] #N title` on the left over one continuous strip (first steps passed, its own step lit) and nothing in the *PR in progress* column, which is reserved for covering PRs — so a title never appears twice in a row. Pull requests are never issues here: when a number arrives through both the issues feed and the pulls feed the PR record wins and the issue copy is dropped on the server (pairing is keyed by repository, kind and number), and the *Issues* filter never lists a PR. The author icon is the one coloured legend: hive hexagon in blue, clanker robot in purple, human silhouette in teal (the `author/*` kind, inferred from the snapshot when the label is absent; the login is in the `#N` link's tooltip). The right-hand `since` column, on the title line, is how long the item has been on its step (red when `stalled`). A plain *Open* step — no stage label yet and not on hold — also carries that age in its own words, "Open · since 3d" ("since 14h" under two days), taken from the same `stage_since` instant the column draws (falling back to the time the item was opened, which the chevron tooltip then marks "(opened)"); past `STAGE_TRACKER_OPEN_STALE_DAYS` (2) the chevron takes a subtle red tint. *Open · hold* never shows the age. An Open item carrying the `blocked` label is drawn the same way as a hold — "Open · blocked" with a ⛔ glyph in the hold's yellow — but keeps the age ("Open · blocked · since 7h"; a stale blocked item is exactly what should stand out, [#14194](https://github.com/hivecommons/hive/issues/14194)) and its chevron tooltip says why: "blocked on owner/repo#N" when the payload names the blocker (`blocked_on`), else "carries the blocked label"; when an item is both held and blocked, hold wins — it is a human instruction. At most one muted chip sits to its left on the title line: the most important health modifier (`stalled`, `regressed`, `hold`, `needs-human`, `needs-decision` — shown as "needs human decision" —, `needs-triage` — shown as "triage needed" (amber) on an issue still carrying the `needs-triage` label at a stage other than 015, whose own chevron already says so —, `needs-rebase`, `blocked`, `draft`) with a `+N` for the rest. Everything else — the reason sentence, who must act, nudges sent, the repository, all flags and the last stage hops — is in the hover tooltip on the item's `#N` link (on a nested sub-row, on its `#N` PR link). Hover text in a row lives only on the `#N` link, the covering-PR link, the title and the lit chevron (its stage, and whose move it is); passed and upcoming chevrons, the kind and author icons, chips and the `since` column have none. Title lines never wrap or push the strip out of alignment: the issue title is truncated with an ellipsis before the *PR in progress* column (a clear gap always separates it from the PR entry, which starts at the column edge) and the PR title before the chips and `since`; hovering a truncated title shows the full text. Rows are sorted furthest-along first by default — a covered issue ranks by its furthest-along PR — then longest on the step first; *Sort* also offers longest waiting, newest and number, and the arrow beside it reverses the order. Every open issue and pull request of the watched repositories is listed — actionable, held, claimed, in progress, covered by a PR, filtered by a `needs-*` label, reporter-triage, draft and exempt-labelled alike; an item without a stage label or journal entry sits at *Open*, and one in a scanner bucket with no label yet is placed from the bucket (claimed → 020, in progress → 030, covered → 040). Filters work on the cached payload in the browser and persist across reloads (the page number does not): kind chips, *Repo*, a search box (`#number` / number / title substring, also matching a covering PR), *Since* (any, over 1 hour / 1 day / 1 week on the current step, or past the stage's configured dwell — stalled items always qualify), *Author* kind, *Needs attention* (anything with a health modifier or on 071 / 072 / 085 / 090), and label chips built from every label present, each with its count: a **🙋 Needs human** facet first (attention-coloured; it matches any item carrying a label of the needs-human set — the server's `needs_human_labels`, the same list as the Projects *Needs human* preset: `stage/045-needs-decision`, `stage/085-needs-decision`, `needs-decision`, `needs-direction`, `needs-spec`, `needs-signal`, `needs-human` and `needs-human/*`, the hold labels, `stage/071-needs-author`, `sentinel-alert`, `needs-triage`; its count is the number of distinct items, not the sum of label counts), then every `stage/NNN-*` label in numerical order, then all other labels alphabetically (case-insensitive). When the row would overflow, the **+N more** button opens an in-app *All labels* dialog listing every label in the same order with counts, a type-to-filter box, the same toggles the chips use and a *Clear* button; a label selected there is promoted into the visible row. Chips of one family OR, families AND; *Needs human* ANDs with the label chips. *Clear filters* shows while anything is narrowed. The list is paged — 25 / 50 / 100 rows, default 50 — with Prev / Next and "showing X–Y of N (M filtered out)" above and below; the header count "N rows · M need attention" is for the filtered set, the **sidebar badge is the row count of the default view** (owner: the tracker counts rows, not items — a covering PR drawn on its issue's row is not a row of its own, and an issue with several PRs already has several), and both come from the same `stageTrackerCountsText()` call so they cannot disagree. When rows sit below the payload's open issues + PRs, the "showing" line's tooltip and the badge's footnote say why — "2 PRs shown on their issue's row" — rather than printing a second total.the chevron's own tooltip names the exact stage. Covering pull requests nest under their issue. An issue with no PR yet draws the whole strip like any other row, lit at Open, Actionable or Claimed with the steps ahead faint. Once exactly one PR covers it, issue and PR are a single entry: the issue's `#N title` on the left, `[author icon] #PR title` under the *PR in progress* header on the same title line, and one continuous strip — Open, Actionable and Claimed passed, the PR's stage lighting the chevron from PR in progress through CI / Review, Merge gate and ✓; the chip, tooltip and `since` are the PR's. With two or more covering PRs the issue's own strip stops at Claimed — all passed, nothing on the issue line lit. Directly beneath, tighter than the gap between entries, sits one indented sub-row per open covering PR, furthest along first: `[author icon] #N title` at the *PR in progress* column, then that PR's own strip from there on — `PR in progress → CI / Review → Merge gate → ✓` — with its own lit chevron, chip, tooltip and `since`. So an issue with two PRs, one at 030, shows "PR in progress" lit on that sub-row, not on the issue. A PR linked to an open issue in the list has no top-level row of its own; a PR with no linked issue keeps a full-width row and shows the first steps as passed. The *Pull requests* filter flattens the list — every PR as a top-level row; *Issues* and *All* show the nested view. Each row is named once on the left; a covering PR appears under the *PR in progress* header as `[author icon] #N title`. A pull request with no linked issue is named once: `[PR icon] [author icon] #N title` on the left over one continuous strip (first steps passed, its own step lit) and nothing in the *PR in progress* column, which is reserved for covering PRs — so a title never appears twice in a row. Pull requests are never issues here: when a number arrives through both the issues feed and the pulls feed the PR record wins and the issue copy is dropped on the server (pairing is keyed by repository, kind and number), and the *Issues* filter never lists a PR. The author icon is the one coloured legend: hive hexagon in blue, clanker robot in purple, human silhouette in teal (the `author/*` kind, inferred from the snapshot when the label is absent; the login is in the `#N` link's tooltip). The right-hand `since` column, on the title line, is how long the item has been on its step (red when `stalled`). At most one muted chip sits to its left on the title line: the most important health modifier (`stalled`, `regressed`, `hold`, `needs-human`, `needs-decision` — shown as "needs human decision" —, `needs-rebase`, `blocked`, `draft`) with a `+N` for the rest. Everything else — the reason sentence, who must act, nudges sent, the repository, all flags and the last stage hops — is in the hover tooltip on the item's `#N` link (on a nested sub-row, on its `#N` PR link). Hover text in a row lives only on the `#N` link, the covering-PR link, the title and the lit chevron (its stage, and whose move it is); passed and upcoming chevrons, the kind and author icons, chips and the `since` column have none. Title lines never wrap or push the strip out of alignment: the issue title is truncated with an ellipsis before the *PR in progress* column (a clear gap always separates it from the PR entry, which starts at the column edge) and the PR title before the chips and `since`; hovering a truncated title shows the full text. Rows are sorted furthest-along first by default — a covered issue ranks by its furthest-along PR — then longest on the step first; *Sort* also offers longest waiting, newest and number, and the arrow beside it reverses the order. Every open issue and pull request of the watched repositories is listed — actionable, held, claimed, in progress, covered by a PR, filtered by a `needs-*` label, reporter-triage, draft and exempt-labelled alike; an item without a stage label or journal entry sits at *Open*, and one in a scanner bucket with no label yet is placed from the bucket (claimed → 020, in progress → 030, covered → 040). Filters work on the cached payload in the browser and persist across reloads (the page number does not): kind chips, *Repo*, a search box (`#number` / number / title substring, also matching a covering PR), *Since* (any, over 1 hour / 1 day / 1 week on the current step, or past the stage's configured dwell — stalled items always qualify), *Author* kind, *Needs attention* (anything with a health modifier or on 071 / 072 / 085 / 090), and label chips built from every label present, each with its count: a **🙋 Needs human** facet first (attention-coloured; it matches any item carrying a label of the needs-human set — the server's `needs_human_labels`, the same list as the Projects *Needs human* preset: `stage/045-needs-decision`, `stage/085-needs-decision`, `needs-decision`, `needs-direction`, `needs-spec`, `needs-signal`, `needs-human` and `needs-human/*`, the hold labels, `stage/071-needs-author`, `sentinel-alert`, `needs-triage`; its count is the number of distinct items, not the sum of label counts), then every `stage/NNN-*` label in numerical order, then all other labels alphabetically (case-insensitive). When the row would overflow, the **+N more** button opens an in-app *All labels* dialog listing every label in the same order with counts, a type-to-filter box, the same toggles the chips use and a *Clear* button; a label selected there is promoted into the visible row. Chips of one family OR, families AND; *Needs human* ANDs with the label chips. *Clear filters* shows while anything is narrowed. The list is paged — 25 / 50 / 100 rows, default 50 — with Prev / Next and "showing X–Y of N (M filtered out)" above and below; the header reads "N items (I issues / P PRs) · M need attention" — N, I and P are the whole list, the same `openItems` set the Overview tile and its left-menu counter print, so N always equals the tile's **Total open issues + Total open PRs**; a "· X match filters" note follows while a filter is on. The sidebar counter beside **Hive activity monitor** is that same N — total open items, written in the same render pass as the header, so the two cannot drift apart; how many need attention is the warn-coloured header suffix and the counter's hover tooltip (counted over every item, filters or not). When covering pull requests are nested under their issue the "showing X–Y of R" line counts rows and adds "(P nested under their issues)" so R never reads as a different total. The small monospace strip beside the count — `engine enforce · N anomalies` — is the central stage engine ([ADR-0025](adr/0025-central-stage-engine.md)): `engine` names the current `governor.labels.stage.engine.mode` (green `enforce`, neutral `shadow` = paused, nothing written; hover for what the mode does and the derivation count), `anomalies` counts stage moves the engine's admission table did not expect (red when non-zero). The same numbers are `/api/status.stageEngine`; the mode is changed under **Settings → Labels → Central stage engine mode** and the operator notes are in [operator-reference.md](operator-reference.md#central-stage-engine-rollout). "updated Ns ago · cache" says how old the server-built payload is: the spoke rebuilds it at most every `dashboard.stage_tracker.cache_ttl_s` (default `governor.eval_interval_s`) from its existing snapshot and serves it with an `ETag`, so the browser's 30-second poll is a 304 and no request ever reaches GitHub (`/api/gh-rate-limits` lists the caller `dashboard:stage-tracker` with nothing charged). See [Stage labels](labels-and-control-signals.md#stage-labels-stagennn--the-pipeline-state-machine). +Fed by `GET /api/stage-tracker`. Every issue and pull request follows the same pipeline, named once in the column header above the list: `Open → Actionable (010) → Claimed (020) → PR in progress (030/040) → CI / Review (050/060) → Merge gate (080/100) → ✓ merged`. Each entry is a title line over a thin chevron strip. Only the current step is coloured: it is filled amber and carries the step name in words; once the PR is merged the final ✓ chevron is the lit one, in green. Motion is reserved for what is running or needs a hand — the lit chevron falls into one of three buckets (`stageTrackerMotion()` in `index.html`): **static** (steady): Open, Open · on hold (any hold label wins over every other signal), Actionable (010), Claimed (020), PR in progress / Covered by PR (030/040) by a human author, Merged, and any unrecognised stage; **active** (gentle pulse): the hive is acting — 030/040 by a hive or clanker author, 050 review pending, 060 reviewed, 070 fixing, 074 adopted by hive, 080 merge gate, 095 pre-merge soak, 100 merge queue; **needs-human** (slower amber→red breathe): a person must move — 015 triage needed, 045/085 needs decision, 071 needs author, 072 returned to contributor, 090 ready for a human merge, or a `stalled` / `blocked` / `needs-human` / `needs-decision` / `needs-triage` modifier on any stage. Under `prefers-reduced-motion` nothing animates; a needs-human step keeps a steady red tint so it still stands out. Every other step is a low-contrast shape with a small grey glyph (circle, bolt, lock, branch, eye, shield, check) — passed steps a subtle neutral fill, steps ahead a faint outline. Side stages are not extra steps: `070 Fixing` (the author's move; the `needs-rebase` chip next to it says what is being fixed — the stage labeller always parks a needs-rebase PR at 070/071/072, never at CI / Review), `071 Needs author` (human-authored), `072 Returned to contributor` (clanker-authored) and `074 Adopted by hive` light *CI / Review* with their own name (an adopted PR stays on 074 through the hive's pushes going pending, green or red again, and moves on only when *Merge gate* takes it); `085 Needs human decision` (PR-only) and `090 Ready for human merge` light *Merge gate* with their own name (the 085 tooltip says what must be decided); an issue parked on a person wears `045 Needs human decision` and lights *Actionable* (the issue side) with that name — a pre-045 issue still wearing 085 is drawn the same way until the reconciler re-stages it; an actionable issue no maintainer has looked at yet wears `015 Triage needed` (carrying `needs-triage`, or held in the reporter-trust gate's `reporter_triage` bucket — never derived from who filed it) and lights *Actionable* as "Triage needed" (a human's move) — so the Actionable column reads "Actionable", "Triage needed" or "Needs human decision", and the Open column is untouched. An issue carrying a hold-class label (`hold`, `do-not-merge*`, `hive-pause/`) is never parked: it sits at *Open* as "Open · on hold" even beside `needs-human`, and the reconciler removes any 045 the hold caught it with ([#13012](https://github.com/hivecommons/hive/issues/13012)). The lit chevron ends with an ink-coloured icon of whose move it is — person (human), robot (clanker) or hexagon (hive): the claim holder on Claimed, the PR author on PR in progress and Returned to contributor, hive on CI / Review, Adopted by hive and Ready for auto merge, a human on Needs human decision and Ready for human merge. `040 Covered by PR` shares the *PR in progress* column with 030; `060 Reviewed`, `080 Awaiting merge admission` and `100 Merge queue` all light *Merge gate* as "Ready for auto merge" (the chevron tooltip says "not yet admitted — " for 060/080 and "admitted, merging" for 100); `095 Pre-merge soak` lights the same column as "Soaking" (hive's move; tooltip "admitted, soaking — Xm left", headline "Pre-merge soak — Xm left" from the payload's `soak_remaining_seconds`, aged from the lane's last sweep), so an admitted PR inside its soak window is no longer drawn as merging; the chevron's own tooltip names the exact stage. Covering pull requests nest under their issue. An issue with no PR yet draws the whole strip like any other row, lit at Open, Actionable or Claimed with the steps ahead faint. Once exactly one PR covers it, issue and PR are a single entry: the issue's `#N title` on the left, `↳ [author icon] #PR title` under the *PR in progress* header on the same title line (the ↳ marks a PR drawn on its issue's row; the PR link's tooltip says so — "linked PR, shown on its issue's row" — and, when two open issues list the same PR, every row but the lowest-numbered issue adds "also under #N"), and one continuous strip — Open, Actionable and Claimed passed, the PR's stage lighting the chevron from PR in progress through CI / Review, Merge gate and ✓; the chip, tooltip and `since` are the PR's. With two or more covering PRs the issue's own strip stops at Claimed — all passed, nothing on the issue line lit. Directly beneath, tighter than the gap between entries, sits one indented sub-row per open covering PR, furthest along first: `[author icon] #N title` at the *PR in progress* column, then that PR's own strip from there on — `PR in progress → CI / Review → Merge gate → ✓` — with its own lit chevron, chip, tooltip and `since`. So an issue with two PRs, one at 030, shows "PR in progress" lit on that sub-row, not on the issue. A PR linked to an open issue in the list has no top-level row of its own; a PR with no linked issue keeps a full-width row and shows the first steps as passed. A PR whose only linked issue is already closed — a superseded PR whose body still says `Fixes #N` after an earlier PR fixed it — keeps its own row with the closed issue in the issue slot: `#N title` as a link, muted and struck through, followed by a small `closed` chip, so the pairing reads at a glance; when the title cannot be resolved the slot says `#N (closed issue)` rather than a bare number (the title comes from the snapshot, or from one cached issue read the cycle makes once per issue — see [Linked issues](dashboard.md#pr-review-and-link-signals)). The *Pull requests* filter flattens the list — every PR as a top-level row; *Issues* and *All* show the nested view. Each row is named once on the left; a covering PR appears under the *PR in progress* header as `[author icon] #N title`. A pull request with no linked issue is named once: `[PR icon] [author icon] #N title` on the left over one continuous strip (first steps passed, its own step lit) and nothing in the *PR in progress* column, which is reserved for covering PRs — so a title never appears twice in a row. Pull requests are never issues here: when a number arrives through both the issues feed and the pulls feed the PR record wins and the issue copy is dropped on the server (pairing is keyed by repository, kind and number), and the *Issues* filter never lists a PR. The author icon is the one coloured legend: hive hexagon in blue, clanker robot in purple, human silhouette in teal (the `author/*` kind, inferred from the snapshot when the label is absent; the login is in the `#N` link's tooltip). The right-hand `since` column, on the title line, is how long the item has been on its step (red when `stalled`). A plain *Open* step — no stage label yet and not on hold — also carries that age in its own words, "Open · since 3d" ("since 14h" under two days), taken from the same `stage_since` instant the column draws (falling back to the time the item was opened, which the chevron tooltip then marks "(opened)"); past `STAGE_TRACKER_OPEN_STALE_DAYS` (2) the chevron takes a subtle red tint. *Open · hold* never shows the age. An Open item carrying the `blocked` label is drawn the same way as a hold — "Open · blocked" with a ⛔ glyph in the hold's yellow — but keeps the age ("Open · blocked · since 7h"; a stale blocked item is exactly what should stand out, [#14194](https://github.com/hivecommons/hive/issues/14194)) and its chevron tooltip says why: "blocked on owner/repo#N" when the payload names the blocker (`blocked_on`), else "carries the blocked label"; when an item is both held and blocked, hold wins — it is a human instruction. At most one muted chip sits to its left on the title line: the most important health modifier (`stalled`, `regressed`, `hold`, `needs-human`, `needs-decision` — shown as "needs human decision" —, `needs-triage` — shown as "triage needed" (amber) on an issue still carrying the `needs-triage` label at a stage other than 015, whose own chevron already says so —, `needs-rebase`, `blocked`, `draft`) with a `+N` for the rest. Everything else — the reason sentence, who must act, nudges sent, the repository, all flags and the last stage hops — is in the hover tooltip on the item's `#N` link (on a nested sub-row, on its `#N` PR link). Hover text in a row lives only on the `#N` link, the covering-PR link, the title and the lit chevron (its stage, and whose move it is); passed and upcoming chevrons, the kind and author icons, chips and the `since` column have none. Title lines never wrap or push the strip out of alignment: the issue title is truncated with an ellipsis before the *PR in progress* column (a clear gap always separates it from the PR entry, which starts at the column edge) and the PR title before the chips and `since`; hovering a truncated title shows the full text. Rows are sorted furthest-along first by default — a covered issue ranks by its furthest-along PR — then longest on the step first; *Sort* also offers longest waiting, newest and number, and the arrow beside it reverses the order. Every open issue and pull request of the watched repositories is listed — actionable, held, claimed, in progress, covered by a PR, filtered by a `needs-*` label, reporter-triage, draft and exempt-labelled alike; an item without a stage label or journal entry sits at *Open*, and one in a scanner bucket with no label yet is placed from the bucket (claimed → 020, in progress → 030, covered → 040). Filters work on the cached payload in the browser and persist across reloads (the page number does not): kind chips, *Repo*, a search box (`#number` / number / title substring, also matching a covering PR), *Since* (any, over 1 hour / 1 day / 1 week on the current step, or past the stage's configured dwell — stalled items always qualify), *Author* kind, *Needs attention* (anything with a health modifier or on 071 / 072 / 085 / 090), and label chips built from every label present, each with its count: a **🙋 Needs human** facet first (attention-coloured; it matches any item carrying a label of the needs-human set — the server's `needs_human_labels`, the same list as the Projects *Needs human* preset: `stage/045-needs-decision`, `stage/085-needs-decision`, `needs-decision`, `needs-direction`, `needs-spec`, `needs-signal`, `needs-human` and `needs-human/*`, the hold labels, `stage/071-needs-author`, `sentinel-alert`, `needs-triage`; its count is the number of distinct items, not the sum of label counts), then every `stage/NNN-*` label in numerical order, then all other labels alphabetically (case-insensitive). When the row would overflow, the **+N more** button opens an in-app *All labels* dialog listing every label in the same order with counts, a type-to-filter box, the same toggles the chips use and a *Clear* button; a label selected there is promoted into the visible row. Chips of one family OR, families AND; *Needs human* ANDs with the label chips. *Clear filters* shows while anything is narrowed. The list is paged — 25 / 50 / 100 rows, default 50 — with Prev / Next and "showing X–Y of N (M filtered out)" above and below; the header count "N rows · M need attention" is for the filtered set, the **sidebar badge is the row count of the default view** (owner: the tracker counts rows, not items — a covering PR drawn on its issue's row is not a row of its own, and an issue with several PRs already has several), and both come from the same `stageTrackerCountsText()` call so they cannot disagree. When rows sit below the payload's open issues + PRs, the "showing" line's tooltip and the badge's footnote say why — "2 PRs shown on their issue's row" — rather than printing a second total.the chevron's own tooltip names the exact stage. Covering pull requests nest under their issue. An issue with no PR yet draws the whole strip like any other row, lit at Open, Actionable or Claimed with the steps ahead faint. Once exactly one PR covers it, issue and PR are a single entry: the issue's `#N title` on the left, `[author icon] #PR title` under the *PR in progress* header on the same title line, and one continuous strip — Open, Actionable and Claimed passed, the PR's stage lighting the chevron from PR in progress through CI / Review, Merge gate and ✓; the chip, tooltip and `since` are the PR's. With two or more covering PRs the issue's own strip stops at Claimed — all passed, nothing on the issue line lit. Directly beneath, tighter than the gap between entries, sits one indented sub-row per open covering PR, furthest along first: `[author icon] #N title` at the *PR in progress* column, then that PR's own strip from there on — `PR in progress → CI / Review → Merge gate → ✓` — with its own lit chevron, chip, tooltip and `since`. So an issue with two PRs, one at 030, shows "PR in progress" lit on that sub-row, not on the issue. A PR linked to an open issue in the list has no top-level row of its own; a PR with no linked issue keeps a full-width row and shows the first steps as passed. The *Pull requests* filter flattens the list — every PR as a top-level row; *Issues* and *All* show the nested view. Each row is named once on the left; a covering PR appears under the *PR in progress* header as `[author icon] #N title`. A pull request with no linked issue is named once: `[PR icon] [author icon] #N title` on the left over one continuous strip (first steps passed, its own step lit) and nothing in the *PR in progress* column, which is reserved for covering PRs — so a title never appears twice in a row. Pull requests are never issues here: when a number arrives through both the issues feed and the pulls feed the PR record wins and the issue copy is dropped on the server (pairing is keyed by repository, kind and number), and the *Issues* filter never lists a PR. The author icon is the one coloured legend: hive hexagon in blue, clanker robot in purple, human silhouette in teal (the `author/*` kind, inferred from the snapshot when the label is absent; the login is in the `#N` link's tooltip). The right-hand `since` column, on the title line, is how long the item has been on its step (red when `stalled`). At most one muted chip sits to its left on the title line: the most important health modifier (`stalled`, `regressed`, `hold`, `needs-human`, `needs-decision` — shown as "needs human decision" —, `needs-rebase`, `blocked`, `draft`) with a `+N` for the rest. A `regressed` chip is red only when the row is parked on a person (a human-gate modifier or stage 045 / 071 / 072 / 085 / 090); on a hive-driven stage with nothing waiting on a human it draws as a muted dashed `stage ↓` pill, yields the lead slot to any other modifier, keeps the row out of **Needs attention**, and its tooltip ends "the hive is handling it — no action needed; clears on the next forward step". The marker is set by a genuine backward hop (a lapsed claim 020 → 010, a 030 ↔ 020 flicker and a 040 → 010 after a partially-addressing merge are not regressions) and clears on the first forward hop; see "The regressed marker" in `labels-and-control-signals.md`. Everything else — the reason sentence, who must act, nudges sent, the repository, all flags and the last stage hops — is in the hover tooltip on the item's `#N` link (on a nested sub-row, on its `#N` PR link). Hover text in a row lives only on the `#N` link, the covering-PR link, the title and the lit chevron (its stage, and whose move it is); passed and upcoming chevrons, the kind and author icons, chips and the `since` column have none. Title lines never wrap or push the strip out of alignment: the issue title is truncated with an ellipsis before the *PR in progress* column (a clear gap always separates it from the PR entry, which starts at the column edge) and the PR title before the chips and `since`; hovering a truncated title shows the full text. Rows are sorted furthest-along first by default — a covered issue ranks by its furthest-along PR — then longest on the step first; *Sort* also offers longest waiting, newest and number, and the arrow beside it reverses the order. Every open issue and pull request of the watched repositories is listed — actionable, held, claimed, in progress, covered by a PR, filtered by a `needs-*` label, reporter-triage, draft and exempt-labelled alike; an item without a stage label or journal entry sits at *Open*, and one in a scanner bucket with no label yet is placed from the bucket (claimed → 020, in progress → 030, covered → 040). Filters work on the cached payload in the browser and persist across reloads (the page number does not): kind chips, *Repo*, a search box (`#number` / number / title substring, also matching a covering PR), *Since* (any, over 1 hour / 1 day / 1 week on the current step, or past the stage's configured dwell — stalled items always qualify), *Author* kind, *Needs attention* (anything with a health modifier or on 071 / 072 / 085 / 090), and label chips built from every label present, each with its count: a **🙋 Needs human** facet first (attention-coloured; it matches any item carrying a label of the needs-human set — the server's `needs_human_labels`, the same list as the Projects *Needs human* preset: `stage/045-needs-decision`, `stage/085-needs-decision`, `needs-decision`, `needs-direction`, `needs-spec`, `needs-signal`, `needs-human` and `needs-human/*`, the hold labels, `stage/071-needs-author`, `sentinel-alert`, `needs-triage`; its count is the number of distinct items, not the sum of label counts), then every `stage/NNN-*` label in numerical order, then all other labels alphabetically (case-insensitive). When the row would overflow, the **+N more** button opens an in-app *All labels* dialog listing every label in the same order with counts, a type-to-filter box, the same toggles the chips use and a *Clear* button; a label selected there is promoted into the visible row. Chips of one family OR, families AND; *Needs human* ANDs with the label chips. *Clear filters* shows while anything is narrowed. The list is paged — 25 / 50 / 100 rows, default 50 — with Prev / Next and "showing X–Y of N (M filtered out)" above and below; the header reads "N items (I issues / P PRs) · M need attention" — N, I and P are the whole list, the same `openItems` set the Overview tile and its left-menu counter print, so N always equals the tile's **Total open issues + Total open PRs**; a "· X match filters" note follows while a filter is on. The sidebar counter beside **Hive activity monitor** is that same N — total open items, written in the same render pass as the header, so the two cannot drift apart; how many need attention is the warn-coloured header suffix and the counter's hover tooltip (counted over every item, filters or not). When covering pull requests are nested under their issue the "showing X–Y of R" line counts rows and adds "(P nested under their issues)" so R never reads as a different total. The small monospace strip beside the count — `engine enforce · N anomalies` — is the central stage engine ([ADR-0025](adr/0025-central-stage-engine.md)): `engine` names the current `governor.labels.stage.engine.mode` (green `enforce`, neutral `shadow` = paused, nothing written; hover for what the mode does and the derivation count), `anomalies` counts stage moves the engine's admission table did not expect (red when non-zero). The same numbers are `/api/status.stageEngine`; the mode is changed under **Settings → Labels → Central stage engine mode** and the operator notes are in [operator-reference.md](operator-reference.md#central-stage-engine-rollout). "updated Ns ago · cache" says how old the server-built payload is: the spoke rebuilds it at most every `dashboard.stage_tracker.cache_ttl_s` (default `governor.eval_interval_s`) from its existing snapshot and serves it with an `ETag`, so the browser's 30-second poll is a 304 and no request ever reaches GitHub (`/api/gh-rate-limits` lists the caller `dashboard:stage-tracker` with nothing charged). See [Stage labels](labels-and-control-signals.md#stage-labels-stagennn--the-pipeline-state-machine). **Repo chip.** Each row carries a small monospace chip before the number naming the repository it belongs to (`dibs #456`, `hive #13524`); the chip is tinted per repository from a fixed palette so one repo always looks the same, the configured primary repo is shown muted, and the full `owner/repo` is in the tooltip. Linked PR sub-rows carry the same chip. Clicking a chip sets the **Repo** filter to that repository (click it again, or pick "All repos", to clear). By default the chip appears only when the list spans more than one repository; the ⚙ settings modal's **Repositories** section offers **Show repo chip: always / only when multiple repos / never** (stored under `hive.tracker.repochip`). diff --git a/src/docs/labels-and-control-signals.md b/src/docs/labels-and-control-signals.md index a0b682882e..0642e4bbe8 100644 --- a/src/docs/labels-and-control-signals.md +++ b/src/docs/labels-and-control-signals.md @@ -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 @@ -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 `` +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 diff --git a/src/pkg/dashboard/stage_tracker_motion_test.go b/src/pkg/dashboard/stage_tracker_motion_test.go index 5e5c59e683..8d664bde64 100644 --- a/src/pkg/dashboard/stage_tracker_motion_test.go +++ b/src/pkg/dashboard/stage_tracker_motion_test.go @@ -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"), @@ -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"), diff --git a/src/pkg/dashboard/stage_tracker_regressed_test.go b/src/pkg/dashboard/stage_tracker_regressed_test.go index 91327864a4..5074ce6c3c 100644 --- a/src/pkg/dashboard/stage_tracker_regressed_test.go +++ b/src/pkg/dashboard/stage_tracker_regressed_test.go @@ -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), ''); @@ -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 { diff --git a/src/pkg/dashboard/stage_tracker_repo_grouping_test.go b/src/pkg/dashboard/stage_tracker_repo_grouping_test.go index 9e75fc3110..1ae6b86573 100644 --- a/src/pkg/dashboard/stage_tracker_repo_grouping_test.go +++ b/src/pkg/dashboard/stage_tracker_repo_grouping_test.go @@ -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"), diff --git a/src/pkg/dashboard/stage_tracker_ui_test.go b/src/pkg/dashboard/stage_tracker_ui_test.go index bde460441f..3c8c6cba4f 100644 --- a/src/pkg/dashboard/stage_tracker_ui_test.go +++ b/src/pkg/dashboard/stage_tracker_ui_test.go @@ -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"), @@ -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); @@ -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"), diff --git a/src/pkg/dashboard/static/index.html b/src/pkg/dashboard/static/index.html index 1ac61344d6..1b0621356c 100644 --- a/src/pkg/dashboard/static/index.html +++ b/src/pkg/dashboard/static/index.html @@ -1449,6 +1449,8 @@ .ham-badges { position: absolute; right: calc(4em + var(--sp-3)); top: 0; display: inline-flex; gap: var(--sp-2); } .ham-badge { display: inline-block; font-size: var(--fs-xs); line-height: 1.4; padding: 0 var(--sp-3); border-radius: var(--r-pill); border: var(--line-width) solid var(--line-subtle); color: var(--text-faint); white-space: nowrap; } .ham-badge-mod.ham-mod-stalled, .ham-badge-mod.ham-mod-regressed { color: var(--red); border-color: color-mix(in srgb, var(--red) 45%, transparent); } + /* A regression the hive is already working through: muted, never red. */ + .ham-badge-mod.ham-mod-regressed.ham-mod-handled { color: var(--text-muted); border-color: var(--line-subtle); border-style: dashed; } .ham-badge-mod.ham-mod-needs-triage { color: var(--amber); border-color: color-mix(in srgb, var(--amber) 45%, transparent); } .ham-badge-mod.ham-mod-possible-dupe { color: var(--purple); border-color: color-mix(in srgb, var(--purple) 45%, transparent); } /* Sentinel-flagged PR, #13535 follow-up: the chip beside needs rebase / @@ -7031,7 +7033,7 @@

Hive activity moni - + @@ -13784,7 +13786,7 @@

Where to get help

const mods = Array.isArray(item.modifiers) ? item.modifiers : []; const holdLabels = stageTrackerHoldLabels(item); if (mods.indexOf('stalled') >= 0) return 'Stalled'; - if (mods.indexOf('regressed') >= 0) return 'Sent back'; + if (mods.indexOf('regressed') >= 0 && !stageTrackerRegressionHandled(item)) return 'Sent back'; if (n === 0 && mods.indexOf('hold') >= 0) return 'Open · on hold' + (holdLabels.length ? ' (' + holdLabels.join(', ') + ')' : ''); if (n === 0 && mods.indexOf('blocked') >= 0) return 'Open · blocked'; // An issue parked on a person (045, or a pre-045 085 with no covering @@ -14060,9 +14062,27 @@

Where to get help

return st && (st.short || st.label) ? code + ' ' + (st.short || st.label) : code; } + // Modifiers that park an item on a person. A regression on a row that + // carries none of these and sits on a hive-driven stage is the hive's + // to work through, so the dashboard must not dress it as a human call. + const STAGE_TRACKER_HUMAN_MODS = ['hold', 'needs-human', 'needs-decision', 'needs-rebase', 'blocked', 'stalled']; + const STAGE_TRACKER_HANDLED_TEXT = 'stage ↓'; + const STAGE_TRACKER_HANDLED_NOTE = 'the hive is handling it — no action needed; clears on the next forward step'; + + // True when the item is regressed but nothing about it waits on a + // person: no human-gate modifier and not on a human-gated stage. Such a + // row gets a muted "stage ↓" pill and stays out of "Needs attention". + function stageTrackerRegressionHandled(item) { + const mods = Array.isArray(item.modifiers) ? item.modifiers : []; + if (mods.indexOf('regressed') < 0) return false; + if (mods.some(m => STAGE_TRACKER_HUMAN_MODS.indexOf(m) >= 0)) return false; + return STAGE_TRACKER_ATTENTION_STAGES.indexOf(Number(item.stage) || 0) < 0; + } + // The regressed pill's explanation: which stage the item fell from and // to, when, and the reason recorded with the fall — so "regressed" never // needs a trip to the store to read. '' when the item is not regressed. + // A hive-handled regression adds the note that nobody needs to act. function stageTrackerRegressionText(item, nowMs) { const mods = Array.isArray(item.modifiers) ? item.modifiers : []; const from = Number(item.regressed_from) || 0; @@ -14074,6 +14094,7 @@

Where to get help

if (!isNaN(atMs)) text += ' at ' + agentNowClockTime(atMs, nowMs || Date.now()); if (item.regressed_reason) text += ' because ' + String(item.regressed_reason); if (cur && cur !== to) text += ' · now ' + stageTrackerStageWord(cur); + if (stageTrackerRegressionHandled(item)) text += ' · ' + STAGE_TRACKER_HANDLED_NOTE; return text; } @@ -14115,14 +14136,19 @@

Where to get help

const mods = (Array.isArray(item.modifiers) ? item.modifiers.slice() : []) .sort((x, y) => STAGE_TRACKER_MOD_PRIORITY.indexOf(x) - STAGE_TRACKER_MOD_PRIORITY.indexOf(y)); if (!mods.length) return sentinel; - let text = STAGE_TRACKER_MOD_TEXT[mods[0]] || mods[0].replace(/-/g, ' '); + // A regression the hive is working through yields the lead pill to any + // other modifier and, alone, draws muted as "stage ↓" rather than red. + const handled = stageTrackerRegressionHandled(item); + if (handled && mods.length > 1) mods.push(mods.shift()); + let text = handled && mods[0] === 'regressed' ? STAGE_TRACKER_HANDLED_TEXT : (STAGE_TRACKER_MOD_TEXT[mods[0]] || mods[0].replace(/-/g, ' ')); // A blocked row with a hive:recheck-after deadline ("blocked until ") names when the sweep re-checks it. const recheck = mods[0] === 'blocked' ? /^blocked until (\S+)/i.exec(String(item.bucket_reason || '')) : null; const recheckMs = recheck ? Date.parse(recheck[1]) : NaN; if (!isNaN(recheckMs)) text += ' · re-check at ' + agentNowClockTime(recheckMs, Date.now()); // The regressed pill (lead or folded into "+1") explains itself on hover. const regressed = stageTrackerRegressionText(item, Date.now()); - return sentinel + `${esc(text)}${mods.length > 1 ? ' +' + (mods.length - 1) : ''}`; + const cls = 'ham-mod-' + mods[0] + (handled && mods[0] === 'regressed' ? ' ham-mod-handled' : ''); + return sentinel + `${esc(text)}${mods.length > 1 ? ' +' + (mods.length - 1) : ''}`; } // Ghost strip for a title line: the lead cell (Open..Claimed) carries @@ -14830,6 +14856,7 @@

Where to get help

function stageTrackerNeedsAttention(item) { const mods = Array.isArray(item.modifiers) ? item.modifiers : []; const n = Number(item.stage) || 0; + if (stageTrackerRegressionHandled(item)) return false; return mods.length > 0 || STAGE_TRACKER_ATTENTION_STAGES.indexOf(n) >= 0; } diff --git a/src/pkg/github/issue_stage_labels.go b/src/pkg/github/issue_stage_labels.go index 17e3568065..7f5c883eef 100644 --- a/src/pkg/github/issue_stage_labels.go +++ b/src/pkg/github/issue_stage_labels.go @@ -203,10 +203,18 @@ func issueUntriaged(in IssueStageInput) (untriaged bool, why string) { // current stage from the shared store. A decomposed parent's reason // carries the "waiting on N open child issue(s)" suffix. func IssueStageFor(in IssueStageInput, prStage func(repo string, number int) stagelabels.Stage) (stage stagelabels.Stage, covered bool, reason string) { - d := stageengine.DeriveIssue(issueFactsFrom(in, prStage)) + d := issueStageDecision(in, prStage) return d.Stage, d.Covered, d.Reason } +// issueStageDecision is IssueStageFor with the whole Decision: the sweep +// also needs Progress, which tells the store that a 040 → 010 fall came +// from the covering PR merging (hive/partially-addressed) rather than +// closing unmerged. +func issueStageDecision(in IssueStageInput, prStage func(repo string, number int) stagelabels.Stage) stageengine.Decision { + return stageengine.DeriveIssue(issueFactsFrom(in, prStage)) +} + // issueHoldLabel returns the hold-class label that pauses the issue, or "". // The enumeration's verdict (in.Held, Client.isHeld with the configured // hive-pause/ label) is authoritative; the label scan covers the @@ -454,13 +462,14 @@ func SyncIssueStageLabelsWith(ctx context.Context, client *Client, result *Actio in.ClaimedBy = "" in.PRStarted = false } - stage, covered, reason := IssueStageFor(in, prStage) + d := issueStageDecision(in, prStage) + stage, covered, reason := d.Stage, d.Covered, d.Reason var want stagelabels.Desired var tr stagelabels.Transition if stage == stagelabels.None { store.Forget(key) } else { - tr = store.Observe(key, stage, reason) + tr = store.ObserveProgress(key, stage, reason, d.Progress) noteIssueCoveringPR(client, store, key, in, stage) rec, _ := store.Get(key) want = stagelabels.Desired{Stage: stage} diff --git a/src/pkg/github/prclaims.go b/src/pkg/github/prclaims.go index 87f7e6a5ec..f4d5ba940a 100644 --- a/src/pkg/github/prclaims.go +++ b/src/pkg/github/prclaims.go @@ -124,8 +124,9 @@ const ( // PartiallyAddressedLabel marks an open issue whose merged PR covered only // part of it (no closing keyword, a remainder paragraph, or none of the // cited paths changed). It suppresses likely-done and keeps the issue - // actionable (#11931). - PartiallyAddressedLabel = "hive/partially-addressed" + // actionable (#11931). Spelled in stagelabels so the stage engine can + // read it without importing this package. + PartiallyAddressedLabel = stagelabels.PartiallyAddressedLabel // PartiallyAddressedLabelColor is the amber label colour used for partially-addressed. PartiallyAddressedLabelColor = "fbca04" // PartiallyAddressedLabelDescription is the description hive creates PartiallyAddressedLabel with. diff --git a/src/pkg/stageengine/decision.go b/src/pkg/stageengine/decision.go index 912bcc1e9a..d88d8c1e06 100644 --- a/src/pkg/stageengine/decision.go +++ b/src/pkg/stageengine/decision.go @@ -23,8 +23,13 @@ type Decision struct { // lanes have staged at 040 or later covers it: the dwell clock then // belongs to the PR and the sweep does not judge the issue stalled. Covered bool - Reason string // stored on the Record, rendered in comments/tracker - Human *stagelabels.Route // set when the stage is a hand-off (085/090) + // Progress is set when the stage fell in number but the move is + // forward motion the Store must not book as a regression: an issue + // leaving 040 for 010 because the PR covering it merged and addressed + // part of it (stagelabels.PartiallyAddressedLabel). + Progress bool + Reason string // stored on the Record, rendered in comments/tracker + Human *stagelabels.Route // set when the stage is a hand-off (085/090) // Abstain means the deriver has no opinion: nothing it saw classifies // the item (today's stageRankNone), so the reconciler leaves the labels // and the Store untouched. It is distinct from Stage == None, which is a diff --git a/src/pkg/stageengine/derive_issue.go b/src/pkg/stageengine/derive_issue.go index f6051eae6e..1d4369f6c8 100644 --- a/src/pkg/stageengine/derive_issue.go +++ b/src/pkg/stageengine/derive_issue.go @@ -52,6 +52,7 @@ func deriveIssue(f Facts) Decision { Stage: stage, Reason: reason, Covered: covered, + Progress: issueProgress(f, stage), Terminal: stage == stagelabels.None && f.Issue.LikelyDone, // The dwell verdict is the sweep's: an out-of-cycle fact carries the // label as found and the next sweep re-judges it from the restarted @@ -132,6 +133,19 @@ func issueStage(f Facts) (stage stagelabels.Stage, covered bool, reason string) return stagelabels.None, false, "outside the pipeline: " + string(is.Bucket) } +// issueProgress reports whether an issue back at an actionable stage got +// there by a PR landing: close-on-merge labels the issue partially-addressed +// when the merged PR covered only part of it and leaves the remainder at +// 010. Seen from the stage number alone that is 040 → 010, a fall; seen +// from the label it is work that merged, so the Store must not book a +// regression for it. +func issueProgress(f Facts, stage stagelabels.Stage) bool { + if stage != stagelabels.Actionable && stage != stagelabels.TriageNeeded { + return false + } + return HasLabelFold(f.Labels, stagelabels.PartiallyAddressedLabel) +} + // actionableIssueStage is 010-actionable or, for an untriaged issue, 015. // Who filed the issue is deliberately not consulted — hive-, agent- and // trusted-human-filed issues are 010 (owner decision, hivecommons/hive#13287 diff --git a/src/pkg/stageengine/reconciler.go b/src/pkg/stageengine/reconciler.go index e4bccc3640..c97f7807df 100644 --- a/src/pkg/stageengine/reconciler.go +++ b/src/pkg/stageengine/reconciler.go @@ -153,7 +153,7 @@ func (r *reconciler) Reconcile(ctx context.Context, f Facts) (Transition, error) tr.Anomaly = a r.recordAnomaly(f.Ref, tr.From, tr.To, d.Reason, a) } - r.opts.Store.Observe(key, d.Stage, d.Reason) + r.opts.Store.ObserveProgress(key, d.Stage, d.Reason, d.Progress) noteCoveringPR(r.opts.Store, key, f, d.Stage) out, err := r.opts.Writer.Apply(ctx, f.Ref, f.Labels, d.Desired()) diff --git a/src/pkg/stageengine/regression_progress_test.go b/src/pkg/stageengine/regression_progress_test.go new file mode 100644 index 0000000000..e843bdacbe --- /dev/null +++ b/src/pkg/stageengine/regression_progress_test.go @@ -0,0 +1,122 @@ +package stageengine + +import ( + "context" + "log/slog" + "strings" + "testing" + "time" + + "github.com/hivecommons/hive/pkg/stagelabels" +) + +// TestDeriveIssueProgress pins Decision.Progress: set only when an issue +// lands on an actionable stage wearing hive/partially-addressed (the PR +// that covered it merged and left a remainder), never from the label at +// another stage nor from the stage alone. +func TestDeriveIssueProgress(t *testing.T) { + partial := stagelabels.PartiallyAddressedLabel + cases := []struct { + name string + mut func(f *Facts) + stage stagelabels.Stage + want bool + }{ + {"actionable, no label", nil, stagelabels.Actionable, false}, + {"actionable, partially addressed", func(f *Facts) { f.Labels = []string{"help wanted", partial} }, stagelabels.Actionable, true}, + {"label case-insensitive", func(f *Facts) { f.Labels = []string{strings.ToUpper(partial)} }, stagelabels.Actionable, true}, + {"triage needed, partially addressed", func(f *Facts) { + f.Labels = []string{partial} + f.Issue.TriageAwaiting = "carries needs-triage" + }, stagelabels.TriageNeeded, true}, + {"covered again, label still on", func(f *Facts) { + f.Labels = []string{partial} + f.Issue.Bucket = BucketCoveredByPR + }, stagelabels.CoveredByPR, false}, + {"claimed, label still on", func(f *Facts) { + f.Labels = []string{partial} + f.Issue.Bucket = BucketClaimed + }, stagelabels.Claimed, false}, + {"closed, label on", func(f *Facts) { + f.Labels = []string{partial} + f.Open = false + }, stagelabels.None, false}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + d := DeriveIssue(derivedIssueFacts(tc.mut)) + if d.Stage != tc.stage || d.Progress != tc.want { + t.Fatalf("stage=%v progress=%v, want stage=%v progress=%v (%+v)", d.Stage, d.Progress, tc.stage, tc.want, d) + } + }) + } +} + +// TestReconcileProgressFallBooksNoRegression replays hivecommons/hive#14557 +// through the real issue deriver: filed → claimed → covered by a PR → the +// PR merges partially and the issue returns to 010 wearing +// hive/partially-addressed. The record must not read as regressed. The +// control case — the covering PR closes unmerged, no label — still does. +func TestReconcileProgressFallBooksNoRegression(t *testing.T) { + cases := []struct { + name string + labels []string + wantRegressed bool + }{ + {"covering PR merged partially", []string{stagelabels.CoveredByPR.Label(), stagelabels.PartiallyAddressedLabel}, false}, + {"covering PR closed unmerged", []string{stagelabels.CoveredByPR.Label()}, true}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + ctx := context.Background() + now := time.Date(2026, 10, 27, 12, 0, 0, 0, time.UTC) + store := stagelabels.NewStore("", func() time.Time { return now }) + r := New(Options{ + Mode: ModeEnforce, + Store: store, + Writer: newFakeWriter(), + Now: func() time.Time { return now }, + Logger: slog.New(slog.NewTextHandler(&strings.Builder{}, nil)), + Metrics: NewCounters(), + }) + pr := &Ref{Owner: "hivecommons", Repo: "hive", Number: 14562, Kind: stagelabels.PRItem} + steps := []func(f *Facts){ + func(f *Facts) { f.Issue.Bucket = BucketActionable }, + func(f *Facts) { + f.Issue.Bucket = BucketClaimed + f.Issue.Claim = &ClaimFact{Holder: "scanner", Kind: "agent"} + }, + func(f *Facts) { f.Issue.Bucket = BucketCoveredByPR; f.Issue.CoveringPR = pr }, + func(f *Facts) { f.Issue.Bucket = BucketActionable; f.Labels = tc.labels }, + } + var last Transition + for i, mut := range steps { + now = now.Add(time.Duration(i) * 10 * time.Minute) + f := Facts{ + Ref: Ref{Owner: "hivecommons", Repo: "hive", Number: 14557, Kind: stagelabels.IssueItem}, + Open: true, + Issue: &IssueFacts{}, + } + mut(&f) + tr, err := r.Reconcile(ctx, f) + if err != nil { + t.Fatalf("step %d: %v", i, err) + } + last = tr + } + if last.From != stagelabels.CoveredByPR || last.To != stagelabels.Actionable { + t.Fatalf("final hop %v → %v, want 040 → 010", last.From, last.To) + } + rec, ok := store.Get(stagelabels.Key("hivecommons/hive", 14557)) + if !ok { + t.Fatal("record missing") + } + if rec.Regressed() != tc.wantRegressed { + t.Fatalf("Regressed()=%v, want %v: %+v", rec.Regressed(), tc.wantRegressed, rec) + } + if hop := rec.History[len(rec.History)-1]; hop.Regressed != tc.wantRegressed || hop.From != stagelabels.CoveredByPR { + t.Fatalf("last hop %+v, want regressed=%v from 040", hop, tc.wantRegressed) + } + }) + } +} diff --git a/src/pkg/stageengine/transition_table.go b/src/pkg/stageengine/transition_table.go index cefcff6e26..57d92a6249 100644 --- a/src/pkg/stageengine/transition_table.go +++ b/src/pkg/stageengine/transition_table.go @@ -28,7 +28,7 @@ var diagramEdges = map[Edge]bool{ {stagelabels.PRInProgress, stagelabels.Claimed}: true, // PR evidence lapsed while the claim is still held (backward hop, commented) {stagelabels.CoveredByPR, stagelabels.Actionable}: true, // covering PR closed unmerged with no live claim or start marker (backward hop, narrated on the PR) {stagelabels.CoveredByPR, stagelabels.TriageNeeded}: true, // covering PR closed unmerged on an untriaged issue (backward hop, narrated on the PR) - {stagelabels.CoveredByPR, stagelabels.PRInProgress}: true, // covering PR closed while a PR request / start marker is still live (backward hop, narrated on the PR) + {stagelabels.CoveredByPR, stagelabels.PRInProgress}: true, // the agent is back on the covering PR (live claim with the PR under way; not a regression) {stagelabels.CoveredByPR, stagelabels.Claimed}: true, // covering PR closed while the claim is still held (backward hop, narrated on the PR) {stagelabels.CoveredByPR, stagelabels.ReviewPending}: true, // the PR takes over (issue stays 040; cross-kind) {stagelabels.ReviewPending, stagelabels.Reviewed}: true, // swarm approve diff --git a/src/pkg/stageengine/transition_table_test.go b/src/pkg/stageengine/transition_table_test.go index d5977e19df..880736d8bf 100644 --- a/src/pkg/stageengine/transition_table_test.go +++ b/src/pkg/stageengine/transition_table_test.go @@ -125,10 +125,10 @@ func TestExpectedRules(t *testing.T) { {"non-regression backward hop", stagelabels.PRItem, stagelabels.ReadyForHumanMerge, stagelabels.ReturnedToContributor, true}, {"non-regression backward hop not drawn", stagelabels.PRItem, stagelabels.ReadyForHumanMerge, stagelabels.Reviewed, true}, {"drawn regression", stagelabels.PRItem, stagelabels.MergeQueue, stagelabels.Fixing, true}, - {"drawn regression (issue): claim lapsed", stagelabels.IssueItem, stagelabels.Claimed, stagelabels.Actionable, true}, + {"drawn hop (issue): claim lapsed, not a regression", stagelabels.IssueItem, stagelabels.Claimed, stagelabels.Actionable, true}, {"drawn regression (issue): start mark lapsed", stagelabels.IssueItem, stagelabels.PRInProgress, stagelabels.Actionable, true}, {"covering PR closed, nothing live", stagelabels.IssueItem, stagelabels.CoveredByPR, stagelabels.Actionable, true}, - {"covering PR closed, start marker live", stagelabels.IssueItem, stagelabels.CoveredByPR, stagelabels.PRInProgress, true}, + {"covering PR worked again, not a regression", stagelabels.IssueItem, stagelabels.CoveredByPR, stagelabels.PRInProgress, true}, {"covering PR closed, claim held", stagelabels.IssueItem, stagelabels.CoveredByPR, stagelabels.Claimed, true}, {"PR evidence lapsed, claim held", stagelabels.IssueItem, stagelabels.PRInProgress, stagelabels.Claimed, true}, // 045 never regresses (IsRegression) and every backward hop among diff --git a/src/pkg/stagelabels/consumer_contract_test.go b/src/pkg/stagelabels/consumer_contract_test.go index 1bff9b6df8..d3ce9377da 100644 --- a/src/pkg/stagelabels/consumer_contract_test.go +++ b/src/pkg/stagelabels/consumer_contract_test.go @@ -77,7 +77,10 @@ func TestPossiblyExistingStage(t *testing.T) { t.Errorf("017 → %v flagged as regression", to) } } - if !stagelabels.IsRegression(stagelabels.Claimed, s) { - t.Fatal("020 → 017 must be a regression, like → 010") + if stagelabels.IsRegression(stagelabels.Claimed, s) { + t.Fatal("020 → 017 is a lapsed reservation, not a regression (like → 010)") + } + if !stagelabels.IsRegression(stagelabels.PRInProgress, s) { + t.Fatal("030 → 017 must be a regression, like → 010") } } diff --git a/src/pkg/stagelabels/covering_pr_test.go b/src/pkg/stagelabels/covering_pr_test.go index 5a4abcb567..386940d34e 100644 --- a/src/pkg/stagelabels/covering_pr_test.go +++ b/src/pkg/stagelabels/covering_pr_test.go @@ -55,8 +55,10 @@ func TestRecordRegressionHop(t *testing.T) { if !ok || hop.From != CoveredByPR || hop.Stage != Claimed || !hop.At.Equal(fallAt) || hop.Reason != "live issue claim" || !hop.Regressed { t.Fatalf("RegressionHop = %+v ok=%v, want the 040→020 fall at %v", hop, ok, fallAt) } - if rec.RegressedFrom != CoveredByPR || !rec.RegressedAt.Equal(now) { - t.Fatalf("record = from %v at %v, want 040 high-water mark and the latest fall time", rec.RegressedFrom, rec.RegressedAt) + // 020 → 010 is a lapsed reservation, not a second fall: the record keeps + // the 040 → 020 fall as its only regression. + if rec.RegressedFrom != CoveredByPR || !rec.RegressedAt.Equal(fallAt) { + t.Fatalf("record = from %v at %v, want 040 high-water mark and the 040→020 fall time %v", rec.RegressedFrom, rec.RegressedAt, fallAt) } now = now.Add(time.Minute) s.Observe(key, CoveredByPR, "open PR #270 covers it") diff --git a/src/pkg/stagelabels/regression_reservation_test.go b/src/pkg/stagelabels/regression_reservation_test.go new file mode 100644 index 0000000000..3e4658aef6 --- /dev/null +++ b/src/pkg/stagelabels/regression_reservation_test.go @@ -0,0 +1,173 @@ +package stagelabels + +import ( + "path/filepath" + "testing" + "time" +) + +// TestIsRegressionReservationStages pins that leaving 020 (a claim or start +// mark, nothing built), 030 → 020 (the claim still held, its PR evidence +// gone quiet for a tick) and 040 → 030 (the agent back on the covering PR) +// are not regressions, while genuine falls still are. The scanner's freshly +// filed split-outs wore a red "regressed" badge minutes after being filed +// because a lapsed claim counted as a fall; hive#14525 wore it for a +// 030 ↔ 020 flap every claim renewal. +func TestIsRegressionReservationStages(t *testing.T) { + cases := []struct { + name string + from, to Stage + want bool + }{ + {"claim released to the pool", Claimed, Actionable, false}, + {"claim released to triage", Claimed, TriageNeeded, false}, + {"claim parked by prior-art gate", Claimed, PossiblyExisting, false}, + {"covered PR being worked again", CoveredByPR, PRInProgress, false}, + {"covered PR closed unmerged", CoveredByPR, Actionable, true}, + {"covered PR to bare claim", CoveredByPR, Claimed, true}, + {"PR under way abandoned", PRInProgress, Actionable, true}, + {"PR under way abandoned on an untriaged issue", PRInProgress, TriageNeeded, true}, + {"PR evidence flickers, claim still held", PRInProgress, Claimed, false}, + {"review knocked back to claim", ReviewPending, Claimed, true}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + if got := IsRegression(tc.from, tc.to); got != tc.want { + t.Fatalf("IsRegression(%v, %v) = %v, want %v", tc.from, tc.to, got, tc.want) + } + }) + } +} + +// TestStoreObserveProgressFall pins ObserveProgress: a fall flagged as +// progress (the covering PR merged and addressed part of the issue) books +// no regression and resolves one already open; the same fall without the +// flag is a regression as before. +func TestStoreObserveProgressFall(t *testing.T) { + now := time.Date(2026, 10, 27, 12, 0, 0, 0, time.UTC) + newStore := func(t *testing.T) *Store { + t.Helper() + return NewStore(filepath.Join(t.TempDir(), "s.json"), func() time.Time { return now }) + } + cases := []struct { + name string + before []Stage + progress bool + wantRegressed bool + wantRecovered bool + wantFrom Stage + wantHopFlag bool + }{ + {"covered PR merged partially", []Stage{Actionable, Claimed, CoveredByPR}, true, false, false, None, false}, + {"covered PR closed unmerged", []Stage{Actionable, Claimed, CoveredByPR}, false, true, false, CoveredByPR, true}, + {"progress heals an open regression", []Stage{Actionable, CoveredByPR, Claimed}, true, false, true, None, false}, + {"first observation is never a fall", nil, false, false, false, None, false}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + st := newStore(t) + key := Key("o/r", 14557) + for _, s := range tc.before { + st.Observe(key, s, "setup") + } + if tc.wantRecovered { + // Setup walks 040 → 020 (a real fall) so the record is + // regressed before the progress observation arrives. + if rec, _ := st.Get(key); !rec.Regressed() { + t.Fatalf("setup should leave the record regressed: %+v", rec) + } + } + tr := st.ObserveProgress(key, Actionable, "actionable", tc.progress) + rec, _ := st.Get(key) + if tr.Regressed != tc.wantRegressed || tr.Recovered != tc.wantRecovered || rec.RegressedFrom != tc.wantFrom { + t.Fatalf("tr=%+v rec.RegressedFrom=%v; want regressed=%v recovered=%v from=%v", tr, rec.RegressedFrom, tc.wantRegressed, tc.wantRecovered, tc.wantFrom) + } + if len(rec.History) == 0 { + t.Fatal("no hop recorded") + } + if last := rec.History[len(rec.History)-1]; last.Regressed != tc.wantHopFlag { + t.Fatalf("last hop %+v; want regressed=%v", last, tc.wantHopFlag) + } + }) + } +} + +// TestStoreObserveClaimLapseNoRegression replays the scanner split-out +// shape — filed, claimed by the scanner, claim lapsed three minutes later — +// and asserts the record never regresses, and that a record persisted +// before the rule changed (regressed from 020) heals on its next sweep. +func TestStoreObserveClaimLapseNoRegression(t *testing.T) { + now := time.Date(2026, 10, 27, 11, 38, 0, 0, time.UTC) + st := NewStore(filepath.Join(t.TempDir(), "s.json"), func() time.Time { return now }) + key := Key("hivecommons/hive", 14558) + st.Observe(key, Claimed, "live issue claim") + now = now.Add(3 * time.Minute) + tr := st.Observe(key, Actionable, "actionable") + rec, _ := st.Get(key) + if tr.Regressed || rec.Regressed() || rec.History[len(rec.History)-1].Regressed { + t.Fatalf("lapsed claim booked as a regression: tr=%+v rec=%+v", tr, rec) + } + + // A record written by the old rule heals on the next observation. + stale := Key("hivecommons/hive", 14554) + st.mu.Lock() + st.items[stale] = Record{Stage: Actionable, RegressedFrom: Claimed, RegressedAt: now, History: []Hop{{Stage: Claimed, At: now}, {From: Claimed, Stage: Actionable, At: now, Regressed: true}}} + st.mu.Unlock() + tr = st.Observe(stale, Actionable, "actionable") + rec, _ = st.Get(stale) + if !tr.Recovered || rec.Regressed() { + t.Fatalf("stale 020 regression did not heal: tr=%+v rec=%+v", tr, rec) + } + + // hive#14525: 030 ↔ 020 every claim renewal, the holder unchanged. + flap := Key("hivecommons/hive", 14525) + st.Observe(flap, Claimed, "live agent claim (no PR yet)") + for i := 0; i < 3; i++ { + now = now.Add(15 * time.Minute) + if tr = st.Observe(flap, PRInProgress, "live claim with a PR under way"); tr.Regressed { + t.Fatalf("flap %d up: %+v", i, tr) + } + now = now.Add(15 * time.Minute) + if tr = st.Observe(flap, Claimed, "live agent claim (no PR yet)"); tr.Regressed { + t.Fatalf("flap %d down booked as a regression: %+v", i, tr) + } + } + if rec, _ = st.Get(flap); rec.Regressed() { + t.Fatalf("flapping claim reads as regressed: %+v", rec) + } +} + +// TestStoreRegressionClearsOnForwardHop pins the lifecycle the dashboard +// badge follows: set by a genuine fall, kept across a non-regression +// backward hop, cleared by the first forward hop (not only by climbing all +// the way back to the stage it fell from). +func TestStoreRegressionClearsOnForwardHop(t *testing.T) { + cases := []struct { + name string + walk []Stage + after []bool // Regressed() after each hop of walk + }{ + {"issue: fall, slide, first step up clears", []Stage{Actionable, CoveredByPR, Claimed, Actionable, Claimed}, []bool{false, false, true, true, false}}, + {"pr: fall, partial climb clears", []Stage{ReviewPending, MergeQueue, ReviewPending, Reviewed, MergeQueue}, []bool{false, false, true, false, false}}, + {"pr: fall, repair route clears", []Stage{Reviewed, AwaitingMergeAdmission, ReviewPending, Fixing}, []bool{false, false, true, false}}, + {"pr: fall then lateral re-attribution keeps it", []Stage{AwaitingMergeAdmission, ReturnedToContributor, Fixing}, []bool{false, true, true}}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + now := time.Date(2026, 10, 27, 12, 0, 0, 0, time.UTC) + st := NewStore(filepath.Join(t.TempDir(), "s.json"), func() time.Time { return now }) + key := Key("o/r", 1) + for i, s := range tc.walk { + now = now.Add(time.Minute) + tr := st.Observe(key, s, "walk") + rec, _ := st.Get(key) + if rec.Regressed() != tc.after[i] { + t.Fatalf("hop %d → %v: Regressed()=%v, want %v (tr=%+v)", i, s, rec.Regressed(), tc.after[i], tr) + } + if i > 0 && tc.after[i-1] && !tc.after[i] && !tr.Recovered { + t.Fatalf("hop %d → %v cleared the regression without reporting Recovered: %+v", i, s, tr) + } + } + }) + } +} diff --git a/src/pkg/stagelabels/stagelabels.go b/src/pkg/stagelabels/stagelabels.go index e2500b5d21..c7b20e3315 100644 --- a/src/pkg/stagelabels/stagelabels.go +++ b/src/pkg/stagelabels/stagelabels.go @@ -127,6 +127,13 @@ const RolePrefix = "role/" // spellings are LegacyRoleLabels now and the reconciler replaces them. const AuthorPrefix = authorkind.Prefix +// PartiallyAddressedLabel marks an open issue whose merged PR covered only +// part of it; close-on-merge adds it instead of likely-done and the issue +// returns to 010 with the remainder still actionable (hivecommons/hive#11931). +// The stage engine reads it to tell that fall from a regression: the PR +// landed, so leaving 040 for 010 is progress. +const PartiallyAddressedLabel = "hive/partially-addressed" + // StalledLabel is the health label; it coexists with the stage label. const StalledLabel = Prefix + "stalled" diff --git a/src/pkg/stagelabels/stagelabels_test.go b/src/pkg/stagelabels/stagelabels_test.go index 04d3321f59..54bbbff618 100644 --- a/src/pkg/stagelabels/stagelabels_test.go +++ b/src/pkg/stagelabels/stagelabels_test.go @@ -386,9 +386,14 @@ func TestStoreObserveRegressRecoverAndStalled(t *testing.T) { t.Fatalf("second fall: tr=%+v rec=%+v", tr, rec) } // Red CI then a fixed head back to review is the repair route: the - // move to fixing regresses, leaving fixing for review does not. - if tr = st.Observe(key, Fixing, "check-failing:unit"); tr.Regressed || tr.Recovered { - t.Fatalf("50→70 is forward: %+v", tr) + // move to fixing is forward (and, being a forward step, resolves the + // open regression — the badge comes off as soon as the item moves on), + // leaving fixing for review does not regress. + if tr = st.Observe(key, Fixing, "check-failing:unit"); tr.Regressed || !tr.Recovered { + t.Fatalf("50→70 is forward and resolves the regression: %+v", tr) + } + if rec, _ = st.Get(key); rec.Regressed() { + t.Fatalf("forward step must clear the regression: %+v", rec) } if tr = st.Observe(key, ReviewPending, "check-pending"); tr.Regressed || tr.Recovered { t.Fatalf("fixing→review-pending must not regress: %+v", tr) @@ -408,13 +413,20 @@ func TestStoreObserveRegressRecoverAndStalled(t *testing.T) { } } } - if tr = st.Observe(key, Reviewed, "y"); tr.Recovered { - t.Fatal("not yet back to the regressed-from stage") + // Fall again from 100 so a plain forward step can be watched clearing + // it: 050 → 060 is not back at the high-water mark but it is moving + // ahead, and that is enough. + st.Observe(key, MergeQueue, "soaking") + if tr = st.Observe(key, ReviewPending, "head-changed"); !tr.Regressed { + t.Fatalf("fall again: %+v", tr) } - tr = st.Observe(key, MergeQueue, "z") + tr = st.Observe(key, Reviewed, "y") rec, _ = st.Get(key) if !tr.Recovered || rec.Regressed() { - t.Fatalf("recovery: tr=%+v rec=%+v", tr, rec) + t.Fatalf("first forward step must resolve the regression: tr=%+v rec=%+v", tr, rec) + } + if tr = st.Observe(key, MergeQueue, "z"); tr.Recovered || tr.Regressed { + t.Fatalf("nothing left to recover: %+v", tr) } tr = st.Observe(key, None, "") if _, ok := st.Get(key); ok || tr.Prev != MergeQueue { @@ -1406,11 +1418,14 @@ func TestTriageNeededStage(t *testing.T) { if IsRegression(Actionable, TriageNeeded) { t.Fatal("010 → 015 is forward") } - for _, from := range []Stage{Claimed, PRInProgress, CoveredByPR} { + for _, from := range []Stage{PRInProgress, CoveredByPR} { if !IsRegression(from, TriageNeeded) { t.Errorf("%v → 015 must be a regression, like → 010", from) } } + if IsRegression(Claimed, TriageNeeded) { + t.Fatal("020 → 015 is a lapsed reservation, not a regression (like → 010)") + } if IsRegression(IssueNeedsDecision, TriageNeeded) { t.Fatal("un-parking 045 → 015 is not a step back") } diff --git a/src/pkg/stagelabels/store.go b/src/pkg/stagelabels/store.go index b0af939481..1954ed4df1 100644 --- a/src/pkg/stagelabels/store.go +++ b/src/pkg/stagelabels/store.go @@ -475,6 +475,16 @@ func (s *Store) Get(key string) (Record, bool) { // transition. A None stage is terminal: the record is dropped and the // transition carries Prev so the caller can clear labels. func (s *Store) Observe(key string, stage Stage, reason string) Transition { + return s.ObserveProgress(key, stage, reason, false) +} + +// ObserveProgress is Observe with the caller's knowledge of WHY the stage +// moved. progress reports that whatever took the item to stage was forward +// motion even if the stage number fell — an issue leaving 040 for 010 +// because the PR covering it merged and addressed part of it. A fall that +// is progress books no regression and resolves one already open: the work +// landed, so nothing was lost. +func (s *Store) ObserveProgress(key string, stage Stage, reason string, progress bool) Transition { s.mu.Lock() defer s.mu.Unlock() now := s.now() @@ -499,19 +509,27 @@ func (s *Store) Observe(key string, stage Stage, reason string) Transition { tr.Changed = true } switch { - case had && prev.Stage != None && IsRegression(prev.Stage, stage): - // Backwards. A fall while already regressed keeps the ORIGINAL - // high-water mark so recovery means getting all the way back. + case had && prev.Stage != None && !progress && IsRegression(prev.Stage, stage): + // Backwards. A second fall while still regressed keeps the ORIGINAL + // high-water mark so the narration names where the item first fell + // from. if !prev.Regressed() || prev.RegressedFrom.Before(prev.Stage) { next.RegressedFrom = prev.Stage } next.RegressedAt = now next.RegressionCommented = false tr.Regressed = true - case prev.Regressed() && (!stage.Before(prev.RegressedFrom) || !IsRegression(prev.RegressedFrom, stage)): - // Back at (or past) the high-water mark, or the mark was a stage a - // fall from is no longer counted (records written before the rule - // changed heal here). + case prev.Regressed() && (progress || prev.Stage.Before(stage) || !IsRegression(prev.RegressedFrom, stage)): + // The regression is resolved the moment the item moves ahead: any + // forward hop, a fall that is progress (the covering PR merged), or + // a mark that a fall from is no longer counted (records written + // before the rule changed heal here). A non-regression backward hop + // (020 → 010 after a 040 → 020 fall, 072 → 070) neither books nor + // clears. The owner's reading (hivecommons/hive#14570): + // "regressed" on something that is moving ahead asks a person to + // act on nothing, so the badge comes off with the first forward + // step rather than waiting for the climb back to the high-water + // mark. next.RegressedFrom = None next.RegressedAt = time.Time{} next.RegressionCommented = false @@ -608,7 +626,8 @@ func (s *Store) CountOwnComments(key string, n int) { } // IsRegression reports whether moving from → to is a backward transition -// worth flagging. A lower number is backward, except leaving a repair stage +// worth flagging. A lower number is backward, except leaving a claim (020 is +// a reservation with nothing built behind it), leaving a repair stage // (fixing, needs-author, returned-to-contributor, adopted-by-hive) for review of the new // head, which is the repair route itself, not a second regression, and // leaving the human stages: 045, 085 and 090 are parking stages ("the hive @@ -622,6 +641,29 @@ func IsRegression(from, to Stage) bool { return false } switch from { + case Claimed: + // 020 is a reservation, not progress: a claim or start mark with + // no PR behind it. Releasing it, letting it lapse or the prior-art + // gate parking the issue (→ 010 / 015 / 017) puts the issue back in + // the pool exactly as it was before the claim; nothing anyone built + // was lost, so there is nothing to have regressed from. The + // scanner's split-out issues wore a red "regressed" badge minutes + // after being filed because of this edge alone. + return false + case PRInProgress: + // 030 → 020 is the same claim, still held, with the PR-under-way + // evidence behind it gone quiet for a tick: hivecommons/hive#14525 + // and rationguard#396 flapped 030 ↔ 020 every renewal and wore a + // red "regressed" badge for it. Nothing enumerated existed at 030 + // (an open PR would be 040), so the holder lost no ground. Losing + // the claim itself (→ 010 / 015) stays a fall: an agent announced a + // PR and vanished. + return to != Claimed + case CoveredByPR: + // 040 → 030 is the agent going back to work on the PR that covers + // the issue (a live claim with the PR under way): the PR is still + // open, so the issue has not lost ground. + return to != PRInProgress case AdoptedByHive: // 074 → 072 is an adoption that was declined (superseder closed // unmerged): the PR is handed back, not knocked back.