diff --git a/changelog.d/fixed-clear-needs-triage-on-claim.md b/changelog.d/fixed-clear-needs-triage-on-claim.md new file mode 100644 index 0000000000..e53fb5d0be --- /dev/null +++ b/changelog.d/fixed-clear-needs-triage-on-claim.md @@ -0,0 +1 @@ +- Stage labels: `needs-triage` is now removed in the same label write that moves an issue to 020-claimed or later (including a direct claim from 015), open issues already claimed and still wearing it are reconciled on the next sweep, and the Hive activity monitor no longer reads a stale `needs-triage` as "Triage needed" on a claimed row — it shows the stage and lists the leftover label as `stale_labels` in a muted tooltip line (#14644). diff --git a/src/docs/dashboard-sections.md b/src/docs/dashboard-sections.md index 9a4dd82a90..51a917fdff 100644 --- a/src/docs/dashboard-sections.md +++ b/src/docs/dashboard-sections.md @@ -640,7 +640,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, in line with the chevron strip, 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 at the right end of the title line, directly over the strip's ✓ cap (on the last line when the title wraps; a hairline above each entry and a hover tint over the whole entry keep chip and `since` unambiguously with their own row — [#14640](https://github.com/hivecommons/hive/issues/14640)): 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 wrap rather than push the strip out of alignment: the issue title stays 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 chip; hovering a 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, in line with the chevron strip, is how long the item has been on its step (red when `stalled`). At most one muted chip sits at the right end of the title line, directly over the strip's ✓ cap (on the last line when the title wraps; a hairline above each entry and a hover tint over the whole entry keep chip and `since` unambiguously with their own row — [#14640](https://github.com/hivecommons/hive/issues/14640)): 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 wrap rather than push the strip out of alignment: the issue title stays 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 chip; hovering a 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, in line with the chevron strip, 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 at the right end of the title line, directly over the strip's ✓ cap (on the last line when the title wraps; a hairline above each entry and a hover tint over the whole entry keep chip and `since` unambiguously with their own row — [#14640](https://github.com/hivecommons/hive/issues/14640)): 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 before the claim (010, 017, 045; at 015 the lit chevron already says so); a `needs-triage` left on a claimed or later issue (020+) is stale, never shown as a chip or stage text, and reported instead as `stale_labels` in the payload with a muted *Stale label* line in the hover tooltip until the stage sweep removes it (hivecommons/hive#14586) —, `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 wrap rather than push the strip out of alignment: the issue title stays 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 chip; hovering a 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, in line with the chevron strip, is how long the item has been on its step (red when `stalled`). At most one muted chip sits at the right end of the title line, directly over the strip's ✓ cap (on the last line when the title wraps; a hairline above each entry and a hover tint over the whole entry keep chip and `since` unambiguously with their own row — [#14640](https://github.com/hivecommons/hive/issues/14640)): 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 wrap rather than push the strip out of alignment: the issue title stays 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 chip; hovering a 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 fbb04efc19..2055426d7e 100644 --- a/src/docs/labels-and-control-signals.md +++ b/src/docs/labels-and-control-signals.md @@ -64,7 +64,7 @@ Some hive-authored labels look like provenance but are read as signals, so they | `hive/` (**retired**, #12539) | Issues, PRs | None | Formerly marked which hive filed or touched an item. Replaced by the `` marker `bin/gh-wrapper.sh` appends after the identity footer (`**Instance:** \`\``) on every body it injects; `github.OriginHive` reads the marker and falls back to a leftover label. Fleet reports name the hive in ``, the seen-marker comment and the `Affected hives` block; claim markers carry `hive=`. Never a hold (#9371). | None | Nobody (was: `gh-wrapper.sh`, self-report joiner, hub relay) | — | `Client.RetireHiveIDLabels` runs at every boot until clean: strips the label from open items, deletes the definition once nothing open carries it, writes `/data/hive-id-label-retire-.json` and a `.done` marker | Hive id (`src/pkg/github/origin_marker.go`, `src/pkg/github/hive_id_label_retire.go`) | | `hold` from ACMM level gate | PRs | PR-request watcher, self-authored auto-merge release | Agent PRs at L3-L5 get literal `hold`; `outreach` PRs whose target repo is not one the hive manages (cross-repo outreach) are held at every level, while same-repo outreach PRs follow the level. The watcher, not the policy prompt, applies it from the PR's target repo (`config.AgentOwnsRepo`). | Hard merge gate | Hive App | PR creation, later self-authored auto-merge release | Auto-release only when current policy no longer requires the level hold, latest hold event was by the App, and the release path runs; otherwise a human removes it | Hive-wide ACMM and agent (`src/pkg/github/pr_request_watcher.go:452-524`, `src/pkg/github/pr_level_hold.go:16-124`) | | `hold` from #5117 self-authorization | PRs | PR-request watcher and self-authorization release | A PR whose only rationale is unacknowledged hive-filed issues gets literal `hold`. Acknowledging the issue later does not remove an existing PR hold by itself. At ACMM L6 (Autonomous), the unset default is off; lower levels default on. | Hard merge gate | Hive App | PR creation; evaluated only when no level hold applies | Acknowledge the issue and remove the PR `hold`; disabled policy release can remove Hive's own hold. At L6, that release path also clears existing Hive-applied #5117 holds when no explicit config keeps the policy on. | `github.self_authorization_hold`, per-repo `project.repo_policies[].self_authorization_hold`, `HIVE_SELF_AUTHORIZATION_HOLD` (`src/pkg/github/pr_self_authorization.go:14-226`, `src/pkg/github/pr_request_watcher.go:452-524`) | -| `triage/accepted` (or `project.issue_filter.reporter_trust.untrusted_require_labels`); `needs-triage` while waiting | Human-filed issues from untrusted reporters | GitHub enumeration | With `reporter_trust.enabled: true`, an issue whose reporter's GitHub `author_association` is outside the trusted set (default `OWNER`, `MEMBER`, `COLLABORATOR`) and whose login is not in `trusted_logins` is not actionable until it carries one of these labels. On the first excluded scan, core `github.Client.fetchIssues` posts one marked explanation comment and applies `needs-triage` (or `awaiting_label`); later scans do not repeat the comment. This is a poller-side write, not an agent prompt, and is capped at 10 new notices per poll. When the triage label appears, the same poll loop removes `needs-triage` only if the marker records that Hive added it, then the issue enters the backlog. Trusted reporters' issues pass untouched. Runs after holds/exempts and before `require_labels`, so the ordinary allow-list still applies afterwards. Hive- and bot-filed issues are not judged here (#5117 owns them). Counted as "needs triage" on the repo card, not as a generic filter refusal. | Hard admission gate (off by default) | Human; Hive App for the visibility comment/label | Enumeration | Add the label, trust the login or association under **Settings → Labels → Reporter trust**, or disable the gate | `project.issue_filter.reporter_trust.{enabled,trusted_associations,trusted_logins,untrusted_require_labels,awaiting_label,comment}` (`src/pkg/config/reporter_trust.go`, `src/pkg/github/client.go` `fetchIssues`) | +| `triage/accepted` (or `project.issue_filter.reporter_trust.untrusted_require_labels`); `needs-triage` while waiting | Human-filed issues from untrusted reporters | GitHub enumeration | With `reporter_trust.enabled: true`, an issue whose reporter's GitHub `author_association` is outside the trusted set (default `OWNER`, `MEMBER`, `COLLABORATOR`) and whose login is not in `trusted_logins` is not actionable until it carries one of these labels. On the first excluded scan, core `github.Client.fetchIssues` posts one marked explanation comment and applies `needs-triage` (or `awaiting_label`); later scans do not repeat the comment. This is a poller-side write, not an agent prompt, and is capped at 10 new notices per poll. When the triage label appears, the same poll loop removes `needs-triage` only if the marker records that Hive added it, then the issue enters the backlog. Independently of the marker, the stage sweep removes `needs-triage` once the issue reaches 020 or later (claiming settles triage; see `stage/015-triage-needed` below) — this is what retires the `needs-triage` that `fleetreport` stamps on hive-filed self-reports at filing. Trusted reporters' issues pass untouched. Runs after holds/exempts and before `require_labels`, so the ordinary allow-list still applies afterwards. Hive- and bot-filed issues are not judged here (#5117 owns them). Counted as "needs triage" on the repo card, not as a generic filter refusal. | Hard admission gate (off by default) | Human; Hive App for the visibility comment/label | Enumeration | Add the label, trust the login or association under **Settings → Labels → Reporter trust**, or disable the gate | `project.issue_filter.reporter_trust.{enabled,trusted_associations,trusted_logins,untrusted_require_labels,awaiting_label,comment}` (`src/pkg/config/reporter_trust.go`, `src/pkg/github/client.go` `fetchIssues`) | | `hold` from #9665 reporter trust | PRs | PR-request watcher, level-hold release | A PR whose rationale (closing or referencing links, or the request's declared issues) traces to an issue filed by an untrusted reporter gets literal `hold` at **every** ACMM level, including L6, plus `needs-human` (so it surfaces as waiting on a person, #10773) and a marked notice naming the untrusted reporter and stating the PR itself was authored by the hive. Any one untrusted citation holds. Evaluated even at hold-gated levels, because the notice is what stops promotion to L6 from releasing the label. | Hard merge gate | Hive App | PR creation; re-checked by the level-hold release path | A human removes `hold`. Hive never auto-releases it: the release sweep sees the notice (or re-evaluates and re-posts it) and leaves the label. Holdguard re-holds on a new head SHA. | `github.reporter_trust_hold` (nil follows `reporter_trust.enabled`), per-repo `project.repo_policies[].reporter_trust_hold`, `HIVE_REPORTER_TRUST_HOLD` (`src/pkg/github/pr_reporter_trust.go`, `src/pkg/github/pr_level_hold.go`) | | `project.repo_policies[].auto_merge: false` | PRs | `hive-merge` relay, App self-authored auto-merge sweep, proxy | Below L6 this resolves off for every repo; at L6, PRs can still be opened, reviewed and held when the per-repo switch is off, but Hive refuses every merge path for that repo. Existing `hold` / `hive-pause/` labels stay put because the disabled repo is skipped before hold release or merge. | Hard merge gate | Operator/dashboard | Merge relay request, self-merge sweep tick, proxy direct merge attempt | Dashboard repo-card switch or config edit sets `auto_merge: true`/removes the override at L6; enabling is rejected below L6 | `project.repo_policies[].auto_merge` (`src/pkg/config/repo_policy.go`, `src/pkg/agent/manager_modes.go`, `src/pkg/github/automerge/automerge_sweep.go`, `src/pkg/proxy/rules.go`) | | `hold` from holdguard | PRs | Holdguard ledger | If the head SHA changes while held, lifting the hold causes Hive to comment and re-apply literal `hold`; the next human removal is the fresh approval. Exception (#13603): when a human (not a Hive account, not a bot) removed the gate label after the current head arrived on the branch, they reviewed the current head, so the lift clears without a comment or re-hold. The head is accepted only on evidence a contributor cannot forge: the server-stamped `head_ref_force_pushed` timeline event that produced it (dated before the lift), or the hive itself having observed that exact head on the PR while the gate was still on (`observed_held_head_sha` in the holdguard ledger). Commit committer dates and SHA-keyed `check_suite` / `status` times are never used; a push after the lift, or a head the hive never saw while held, still re-holds. | Hard merge gate | Hive | Governor holdguard pass | Human removes the re-applied hold | Built-in `holdguard.ReHoldLabel` (`src/pkg/holdguard/holdguard.go:1-43`) | @@ -214,7 +214,7 @@ referenced it) a lone `stage/050-review-pending` | Label | Applies to | Meaning | Expected dwell (then `stage/stalled`) | |---|---|---|---| | `stage/010-actionable` | issue | triaged; eligible for the hive to pick up. A human-filed issue without `needs-triage` counts as triaged by its trusted reporter | 24h | -| `stage/015-triage-needed` | issue | actionable, but no maintainer has looked at it yet. Derived instead of 010 only when the reporter-trust gate is holding the issue: it carries the awaiting label `needs-triage` (`reporter_trust.awaiting_label` default) or sits in the #9665 gate's `reporter_triage` bucket. Who filed it is never consulted — issues from hive agents and from trusted humans are triaged by construction and stay 010. A **display and tracking state, not a gate**: the scanner and relay claim a 015 issue exactly as a 010 one (the reporter-trust gate withholds `needs-triage` issues separately, and that is unchanged), and 015 lights the activity monitor's *Actionable* column as "Triage needed". `015 → 010` (a maintainer triages) is never a regression; `010 → 015` is a reclassification. The Open column is untouched: an issue with no stage stays "Open" | 24h | +| `stage/015-triage-needed` | issue | actionable, but no maintainer has looked at it yet. Derived instead of 010 only when the reporter-trust gate is holding the issue: it carries the awaiting label `needs-triage` (`reporter_trust.awaiting_label` default) or sits in the #9665 gate's `reporter_triage` bucket. Who filed it is never consulted — issues from hive agents and from trusted humans are triaged by construction and stay 010. A **display and tracking state, not a gate**: the scanner and relay claim a 015 issue exactly as a 010 one (the reporter-trust gate withholds `needs-triage` issues separately, and that is unchanged), and 015 lights the activity monitor's *Actionable* column as "Triage needed". `015 → 010` (a maintainer triages) is never a regression; `010 → 015` is a reclassification. Because 015 is not a gate, a claim settles triage: whenever the sweep (or an out-of-cycle claim fact) writes a stage of 020 or later — 020, 030, 040 or a PR-mirrored stage — it removes `needs-triage` in the same label write, and an open issue already at 020+ still wearing it is reconciled on the next sweep; the label survives at 010, 017 and 045, which the table lets fall back to 015 (hivecommons/hive#14586). The Open column is untouched: an issue with no stage stays "Open" | 24h | | `stage/017-possible-existing` | issue | **Possibly exists · needs author.** The prior-art gate found something that looks like the request already (knowledge bead, setting, merged PR, closed issue, doc or code) and parked the issue with the findings; the author confirms the gap (`/hive decision proceed — `) or closes it (`/hive decision exists`, label `already-exists`). The label itself is the park signal and an issue-level hard suppress, so no agent claims it; clanker-filed parks auto-close after `runs.triage.prior_art.bot_close_ttl`; hive-filed issues never wear it ([#13575](https://github.com/hivecommons/hive/issues/13575)) | none | | `stage/020-claimed` | issue | a live claim by anyone — a human, a relay contributor or a hive agent's `hive-open-issue claim` / start mark — with no PR evidence yet (replaces `claimed`, `hive/in-progress`) | 2h | | `stage/030-pr-in-progress` | issue | the claimant has a PR under way: its `hive-open-pr --issues` request named the issue or its start marker named a branch / PR (`pr_started=true` on the `hive:claim` marker). A claim or start mark without that evidence — the scanner's bare `hive-open-issue claim` included — stays at 020 ([#13069](https://github.com/hivecommons/hive/issues/13069)). If the in-progress evidence includes an open Hive-authored PR, the issue-stage lane applies the same PR-link safeguard described for 040: default-branch PRs that fully address the issue get a `Fixes #N` trailer when missing, while partial or non-default-branch PRs get an issue stage-entry comment linking the PR and explaining GitHub's icon limitation. If the claiming PR has already merged, the issue leaves 030: full-fix claims close it with one `` comment (checked before posting, so a close that fails after the comment is retried without a duplicate), while `Refs` / `Part of` claims move back to 010 with a partial-landed note. | 90m | @@ -263,7 +263,7 @@ stateDiagram-v2 s010 --> s045: needs-human / park label (agent escalates) s010 --> s015: needs-triage added (reclassification) s015 --> s010: maintainer triages: triage/accepted, hive/verified-open or approved-direction added, or needs-triage removed (not a regression) - s015 --> s020: scanner / relay claim (015 is not a gate) + s015 --> s020: scanner / relay claim (015 is not a gate; needs-triage removed in the same write) s015 --> s045: needs-human / park label (agent escalates) s020 --> s045: claim lapses on a parked issue s045 --> s010: /hive approve or /hive decision (approved-direction; a person's needs-human keeps it at 045, the hive's own lifts) diff --git a/src/pkg/dashboard/stage_tracker.go b/src/pkg/dashboard/stage_tracker.go index b82ef6cfc0..c15ad57108 100644 --- a/src/pkg/dashboard/stage_tracker.go +++ b/src/pkg/dashboard/stage_tracker.go @@ -307,11 +307,17 @@ type StageTrackerItem struct { // reason; the gate cell reads "Awaiting human: ". Unauthorized // is the pill's tooltip naming the permission and the human action // (hivecommons/hive#14589). - UnauthorizedStep string `json:"unauthorized_step,omitempty"` - Unauthorized string `json:"unauthorized,omitempty"` - NudgeCount int `json:"nudge_count,omitempty"` - LastNudgeAt *time.Time `json:"last_nudge_at,omitempty"` - AdoptedBy int `json:"adopted_by,omitempty"` + UnauthorizedStep string `json:"unauthorized_step,omitempty"` + Unauthorized string `json:"unauthorized,omitempty"` + // StaleLabels are control labels the row still wears that its stage + // has outrun, so they are not read as modifiers: `needs-triage` on an + // issue at 020 or later (015 is not a gate; the reconciler removes the + // label on its next pass, hivecommons/hive#14586). Rendered as a muted + // operator tooltip, never as the stage word. + StaleLabels []string `json:"stale_labels,omitempty"` + NudgeCount int `json:"nudge_count,omitempty"` + LastNudgeAt *time.Time `json:"last_nudge_at,omitempty"` + AdoptedBy int `json:"adopted_by,omitempty"` // ClaimantKind is the author kind of whoever holds the live claim on a // claimed issue (human / clanker / hive), from the worker-claim ledger. ClaimantKind string `json:"claimant_kind,omitempty"` @@ -1167,10 +1173,15 @@ func (s *Server) buildStageTracker(status *StatusPayload, store *stagelabels.Sto if stage == stagelabels.NeedsDecision || stage == stagelabels.IssueNeedsDecision { it.Modifiers = slices.DeleteFunc(it.Modifiers, func(m string) bool { return m == modNeedsDecision }) } - // Likewise 015 says "Triage needed" itself; the needs-triage chip - // only adds information on another stage (a claimed or covered - // issue the gate is still holding). - if stage == stagelabels.TriageNeeded { + // Likewise 015 says "Triage needed" itself, and a needs-triage left + // on a claimed / covered issue is stale, not a signal: 015 is not a + // gate, the stage word is the truth, and the reconciler removes the + // label on its next pass (hivecommons/hive#14586). The chip stays + // only before the claim (010 / 017 / 045). + if stage == stagelabels.TriageNeeded || stage.SettlesTriage() { + if stage != stagelabels.TriageNeeded && slices.Contains(it.Modifiers, modNeedsTriage) { + it.StaleLabels = append(it.StaleLabels, modNeedsTriage) + } it.Modifiers = slices.DeleteFunc(it.Modifiers, func(m string) bool { return m == modNeedsTriage }) } it.Caption, it.Actor = stageTrackerCaption(stage, it.Reason, it.Author, it.Kind, it.Mirrored, rec, hasRec, it.LinkedPR, it.Head) diff --git a/src/pkg/dashboard/stage_tracker_motion_test.go b/src/pkg/dashboard/stage_tracker_motion_test.go index 8fd59ebbb1..9fccbdeff5 100644 --- a/src/pkg/dashboard/stage_tracker_motion_test.go +++ b/src/pkg/dashboard/stage_tracker_motion_test.go @@ -426,6 +426,7 @@ func TestStageTrackerMotionRowStamp(t *testing.T) { jsConstLine(t, html, "STAGE_TRACKER_HANDLED_NOTE"), jsFunc(t, html, "stageTrackerRegressionHandled"), jsFunc(t, html, "stageTrackerRegressionText"), + jsFunc(t, html, "stageTrackerStaleLabelsText"), jsFunc(t, html, "stageTrackerTooltip"), jsFunc(t, html, "stageTrackerChipsHtml"), jsFunc(t, html, "stageTrackerHeadColsHtml"), @@ -535,6 +536,7 @@ func TestStageTrackerMotionPreviewSample(t *testing.T) { jsConstLine(t, html, "STAGE_TRACKER_HANDLED_NOTE"), jsFunc(t, html, "stageTrackerRegressionHandled"), jsFunc(t, html, "stageTrackerRegressionText"), + jsFunc(t, html, "stageTrackerStaleLabelsText"), jsFunc(t, html, "stageTrackerTooltip"), jsFunc(t, html, "stageTrackerChipsHtml"), jsFunc(t, html, "stageTrackerHeadColsHtml"), diff --git a/src/pkg/dashboard/stage_tracker_repo_grouping_test.go b/src/pkg/dashboard/stage_tracker_repo_grouping_test.go index 54faec5b4a..229c872c1b 100644 --- a/src/pkg/dashboard/stage_tracker_repo_grouping_test.go +++ b/src/pkg/dashboard/stage_tracker_repo_grouping_test.go @@ -146,6 +146,7 @@ func stageTrackerRepoGroupingHarness(t *testing.T, html string) string { jsConstLine(t, html, "STAGE_TRACKER_HANDLED_NOTE"), jsFunc(t, html, "stageTrackerRegressionHandled"), jsFunc(t, html, "stageTrackerRegressionText"), + jsFunc(t, html, "stageTrackerStaleLabelsText"), jsFunc(t, html, "stageTrackerTooltip"), jsFunc(t, html, "stageTrackerChipsHtml"), jsFunc(t, html, "stageTrackerHeadColsHtml"), diff --git a/src/pkg/dashboard/stage_tracker_stale_triage.test.js b/src/pkg/dashboard/stage_tracker_stale_triage.test.js new file mode 100644 index 0000000000..86b87b32d6 --- /dev/null +++ b/src/pkg/dashboard/stage_tracker_stale_triage.test.js @@ -0,0 +1,43 @@ +// A needs-triage left on a claimed issue is stale, not a signal +// (hivecommons/hive#14586): the tracker payload carries it as stale_labels, +// the row reads its stage word, the hover shows one muted operator note, and +// no "Accept triage" action is offered. The helpers are lifted straight out +// of index.html so this test runs against the shipped source. +const test = require('node:test'); +const assert = require('node:assert'); +const fs = require('node:fs'); +const path = require('node:path'); + +const html = fs.readFileSync(path.join(__dirname, 'static', 'index.html'), 'utf8'); + +function pick(re, what) { + const m = html.match(re); + assert.ok(m, what + ' not found in index.html'); + return m[0]; +} + +const src = [ + pick(/const STAGE_TRACKER_TRIAGE_STAGE = \d+;/, 'STAGE_TRACKER_TRIAGE_STAGE'), + pick(/const STAGE_TRACKER_ACTIONABLE_STAGE = \d+;/, 'STAGE_TRACKER_ACTIONABLE_STAGE'), + pick(/function stageTrackerStaleLabelsText\(item\) \{[\s\S]*?\n \}\n/, 'stageTrackerStaleLabelsText'), + pick(/function stageTrackerTriageNeeded\(item\) \{[\s\S]*?\n \}\n/, 'stageTrackerTriageNeeded'), +].join('\n'); +const { staleText, triageNeeded } = new Function(src + '; return { staleText: stageTrackerStaleLabelsText, triageNeeded: stageTrackerTriageNeeded };')(); + +// The payload the Go side emits for hivecommons/hive#14586 once claimed. +const claimedStale = { kind: 'issue', number: 14586, stage: 20, stage_slug: 'claimed', modifiers: [], stale_labels: ['needs-triage'] }; + +test('a claimed issue with a stale needs-triage gets one muted operator note', () => { + assert.strictEqual(staleText(claimedStale), 'Stale label: needs-triage (stage has moved on; the hive removes it on its next pass)'); + assert.strictEqual(staleText({ kind: 'issue', stage: 20, modifiers: [] }), ''); + assert.strictEqual(staleText({ kind: 'issue', stage: 20, stale_labels: [] }), ''); + assert.strictEqual(staleText(null), ''); + assert.strictEqual(staleText({ stale_labels: ['needs-triage', 'x'] }), 'Stale labels: needs-triage, x (stage has moved on; the hive removes it on its next pass)'); +}); + +test('a stale needs-triage is not "triage needed" and offers no Accept triage', () => { + assert.strictEqual(triageNeeded(claimedStale), false); + assert.strictEqual(triageNeeded({ kind: 'issue', stage: 15, modifiers: [] }), true, '015 is triage needed by its stage word'); + assert.strictEqual(triageNeeded({ kind: 'issue', stage: 10, modifiers: ['needs-triage'] }), true, 'the pill before the claim still counts'); + assert.strictEqual(triageNeeded({ kind: 'pr', stage: 50, modifiers: ['needs-triage'] }), false); +}); diff --git a/src/pkg/dashboard/stage_tracker_triage_modifier_test.go b/src/pkg/dashboard/stage_tracker_triage_modifier_test.go index c654ecba00..7c9701771c 100644 --- a/src/pkg/dashboard/stage_tracker_triage_modifier_test.go +++ b/src/pkg/dashboard/stage_tracker_triage_modifier_test.go @@ -24,8 +24,11 @@ func TestStageTrackerModifiers_NeedsTriage(t *testing.T) { // An issue at 015-triage-needed lights the Actionable column with its own // word, so the redundant needs-triage chip is dropped there (as the -// needs-decision chip is on 045); on any other stage the chip stays. The -// caption names the maintainer as the next mover (hivecommons/hive#13268). +// needs-decision chip is on 045). On a claimed issue the label is stale — +// 015 is not a gate and the stage word is the truth — so the chip is +// dropped too and the label is reported as stale_labels for the operator +// tooltip (hivecommons/hive#14586). The caption names the maintainer as +// the next mover (hivecommons/hive#13268). func TestStageTracker_TriageNeededStage(t *testing.T) { now := time.Date(2026, 10, 16, 22, 35, 0, 0, time.UTC) s := newTestServer() @@ -57,8 +60,14 @@ func TestStageTracker_TriageNeededStage(t *testing.T) { t.Fatalf("caption %q must carry the derivation reason", issue21.Caption) } issue22 := trackerItem(t, resp, "issue", 22) - if issue22.Stage != trackerNumberClaimed || !hasMod(issue22, modNeedsTriage) { - t.Fatalf("needs-triage chip must survive on other stages: %+v", issue22) + if issue22.Stage != trackerNumberClaimed || hasMod(issue22, modNeedsTriage) { + t.Fatalf("a claimed issue must not read as triage needed: %+v", issue22) + } + if !slices.Equal(issue22.StaleLabels, []string{modNeedsTriage}) { + t.Fatalf("stale needs-triage must be reported for the operator tooltip: %+v", issue22.StaleLabels) + } + if len(issue21.StaleLabels) != 0 { + t.Fatalf("015 wears needs-triage legitimately; stale_labels = %v", issue21.StaleLabels) } var short string for _, st := range resp.Stages { @@ -70,3 +79,48 @@ func TestStageTracker_TriageNeededStage(t *testing.T) { t.Fatalf("stage 015 short = %q", short) } } + +// The needs-triage chip is kept before the claim: at 010 and on the 045 +// park it still tells the operator something, and nothing is reported +// stale. Past the claim (020, 030, 040, and an issue mirroring its covering +// PR's stage) the chip goes and stale_labels names it. +func TestStageTracker_NeedsTriageStaleOnlyPastClaim(t *testing.T) { + now := time.Date(2026, 10, 27, 17, 40, 0, 0, time.UTC) + s := newTestServer() + store := stagelabels.NewStore("", func() time.Time { return now }) + s.stageStore = store + cases := []struct { + number int + stage stagelabels.Stage + stale bool + }{ + {31, stagelabels.Actionable, false}, + {32, stagelabels.IssueNeedsDecision, false}, + {33, stagelabels.Claimed, true}, + {34, stagelabels.PRInProgress, true}, + {35, stagelabels.CoveredByPR, true}, + {36, stagelabels.ReviewPending, true}, + } + var issues []any + for _, c := range cases { + store.Observe(stagelabels.Key("acme/console", c.number), c.stage, "test") + issues = append(issues, github.Issue{Number: c.number, Title: "n", Author: "newcomer", AuthorIsHuman: true, Labels: []string{c.stage.Label(), "needs-triage"}}) + } + status := minimalPayload() + status.HiveID = "hv-test" + status.Repos = []FrontendRepo{{Name: "console", Full: "acme/console", ActionableIssues: issues}} + s.UpdateStatus(status) + resp := s.buildStageTracker(s.status, store, now) + for _, c := range cases { + it := trackerItem(t, resp, "issue", c.number) + if it.Stage != c.stage.Number() { + t.Fatalf("#%d stage = %d, want %d", c.number, it.Stage, c.stage.Number()) + } + if hasMod(it, modNeedsTriage) == c.stale { + t.Fatalf("#%d at %s: needs-triage modifier present=%v, want %v", c.number, c.stage, hasMod(it, modNeedsTriage), !c.stale) + } + if gotStale := slices.Contains(it.StaleLabels, modNeedsTriage); gotStale != c.stale { + t.Fatalf("#%d at %s: stale_labels = %v, want stale=%v", c.number, c.stage, it.StaleLabels, c.stale) + } + } +} diff --git a/src/pkg/dashboard/stage_tracker_ui_test.go b/src/pkg/dashboard/stage_tracker_ui_test.go index fcadea0f04..d901df4d5a 100644 --- a/src/pkg/dashboard/stage_tracker_ui_test.go +++ b/src/pkg/dashboard/stage_tracker_ui_test.go @@ -154,6 +154,7 @@ func TestStageTrackerRows(t *testing.T) { jsConstLine(t, html, "STAGE_TRACKER_HANDLED_NOTE"), jsFunc(t, html, "stageTrackerRegressionHandled"), jsFunc(t, html, "stageTrackerRegressionText"), + jsFunc(t, html, "stageTrackerStaleLabelsText"), jsFunc(t, html, "stageTrackerTooltip"), jsFunc(t, html, "stageTrackerChipsHtml"), jsFunc(t, html, "stageTrackerHeadColsHtml"), diff --git a/src/pkg/dashboard/static/index.html b/src/pkg/dashboard/static/index.html index 214471ab81..2e1d217af6 100644 --- a/src/pkg/dashboard/static/index.html +++ b/src/pkg/dashboard/static/index.html @@ -14217,6 +14217,8 @@

Where to get help

const actorKind = stageTrackerActorKind(item); if (actorKind) lines.push('Next move: ' + actorKind); if (mods.length) lines.push('Flags: ' + mods.map(m => STAGE_TRACKER_MOD_TEXT[m] || m).join(', ')); + const stale = stageTrackerStaleLabelsText(item); + if (stale) lines.push(stale); if (item.sentinel_alert) lines.push(stageTrackerSentinelTip(item)); const regressed = stageTrackerRegressionText(item, nowMs); if (regressed) lines.push(regressed.charAt(0).toUpperCase() + regressed.slice(1)); @@ -15631,8 +15633,10 @@

All labels

open: 'Open on GitHub', copy: 'Copy link', }; // Accept triage shows on an issue the chevron calls "Triage needed": - // stage 015, or the needs-triage pill on another stage (a claimed or - // covered issue the reporter-trust gate still holds). Never on a PR. + // stage 015, or the needs-triage pill on a pre-claim stage (010 / 017 / + // 045). A needs-triage left on a claimed or covered issue is reported + // as stale_labels, not a modifier, so no action is offered for it + // (hivecommons/hive#14586). Never on a PR. const STAGE_TRACKER_TRIAGE_STAGE = 15; const STAGE_TRACKER_ACTIONABLE_STAGE = 10; const STAGE_TRACKER_WHY_WRITE = 'Sign in with write access to this repo'; @@ -15773,6 +15777,14 @@

All labels

out.push({ id: 'decide:close-wontfix', label: "Close as won't-fix…", enabled, why, danger: true }); return out; } + // Pure: the operator note for labels the row's stage has outrun + // (stale_labels: a needs-triage still on a claimed issue, which the + // reconciler removes on its next pass — hivecommons/hive#14586). '' when none. + function stageTrackerStaleLabelsText(item) { + const stale = item && Array.isArray(item.stale_labels) ? item.stale_labels.filter(Boolean) : []; + if (!stale.length) return ''; + return 'Stale label' + (stale.length > 1 ? 's' : '') + ': ' + stale.join(', ') + ' (stage has moved on; the hive removes it on its next pass)'; + } // Pure: whether a row is an issue waiting on a maintainer's triage. function stageTrackerTriageNeeded(item) { if (!item || item.kind === 'pr') return false; diff --git a/src/pkg/github/issue_stage_facts.go b/src/pkg/github/issue_stage_facts.go index 4e1d1c8aa4..564a87d0a2 100644 --- a/src/pkg/github/issue_stage_facts.go +++ b/src/pkg/github/issue_stage_facts.go @@ -99,6 +99,10 @@ func resolveIssueLabelFacts(in IssueStageInput, f *stageengine.Facts) { if untriaged, why := issueUntriaged(in); untriaged { is.TriageAwaiting = why } + is.TriageAwaitingLabel = "" + if issueHasLabel(in.Labels, triageAwaitingLabel) { + is.TriageAwaitingLabel = triageAwaitingLabel + } } // issueInputFrom rebuilds the label/bucket view of an out-of-cycle Facts diff --git a/src/pkg/github/issue_stage_labels.go b/src/pkg/github/issue_stage_labels.go index 7f5c883eef..32832f5dd6 100644 --- a/src/pkg/github/issue_stage_labels.go +++ b/src/pkg/github/issue_stage_labels.go @@ -476,6 +476,15 @@ func SyncIssueStageLabelsWith(ctx context.Context, client *Client, result *Actio if !covered && !awaitingChildren { want.Stalled = stagelabels.Stalled(rec, policy.Dwell, now) } + // A claimed / covered issue still wearing the reporter-trust + // awaiting label is stale (015 is not a gate): the engine's + // Decision.Clear takes it off in the stage write, and the + // pre-plan here must see the same write as due so an issue + // whose stage label is already right is still reconciled + // (hivecommons/hive#14586). + if stage.SettlesTriage() && issueHasLabel(in.Labels, triageAwaitingLabel) { + want.Clear = []string{triageAwaitingLabel} + } } if stage == stagelabels.PRInProgress || stage == stagelabels.CoveredByPR { edited, commented := ensureIssueStagePRLink(ctx, client, in, store, key, logger) diff --git a/src/pkg/github/issue_stage_labels_triage_clear_test.go b/src/pkg/github/issue_stage_labels_triage_clear_test.go new file mode 100644 index 0000000000..54c25acc62 --- /dev/null +++ b/src/pkg/github/issue_stage_labels_triage_clear_test.go @@ -0,0 +1,57 @@ +package github + +import ( + "slices" + "strings" + "testing" + + "github.com/hivecommons/hive/pkg/claims" + "github.com/hivecommons/hive/pkg/stagelabels" +) + +// hivecommons/hive#14586: a hive-filed self-report wears `needs-triage` from +// filing; the scanner claims it from 015 (not a gate) and the label survived +// the 015 → 020 write, so a claimed — then closed — issue still read "Triage +// needed". The sweep now takes `needs-triage` off in the same write as the +// stage, and reconciles an issue already at 020 that still wears it. +func TestSyncIssueStageLabels_ClaimClearsNeedsTriage(t *testing.T) { + fake := newIssueStageServer(t) + c := issueStageTestClient(t, fake.srv, true) + result := &ActionableResult{} + // 14586: direct claim from 015. + appendRepoWorkIssueDetail(result, Issue{ + Repo: "acme/widgets", Number: 14586, Author: "hive-app[bot]", + Labels: []string{"kind/bug", triageAwaitingLabel, stagelabels.TriageNeeded.Label(), "hive/claimed-by-scanner"}, + ClaimKind: string(claims.KindAgent), + }, workBucketClaimed, "live claim") + // 14587: already 020 and correct, but still wearing the stale label. + appendRepoWorkIssueDetail(result, Issue{ + Repo: "acme/widgets", Number: 14587, Author: "hive-app[bot]", + Labels: []string{triageAwaitingLabel, stagelabels.Claimed.Label()}, + ClaimKind: string(claims.KindAgent), + }, workBucketClaimed, "live claim") + // 14588: untriaged and unclaimed stays 015 and keeps its label. + result.Issues = IssueResultFromItems([]Issue{{Repo: "acme/widgets", Number: 14588, Author: "alice", AuthorIsHuman: true, Labels: []string{triageAwaitingLabel}}}) + + res := syncSeeded(t, fake, c, result, stagelabels.NewStore("", stageNow), stageNow()) + if res.Items != 3 { + t.Fatalf("items = %d, want 3", res.Items) + } + fake.mu.Lock() + defer fake.mu.Unlock() + if got := strings.Join(fake.added[14586], ","); got != stagelabels.Claimed.Label() { + t.Fatalf("direct claim must land 020: added=%v", fake.added[14586]) + } + if !slices.Contains(fake.removed[14586], triageAwaitingLabel) || !slices.Contains(fake.removed[14586], stagelabels.TriageNeeded.Label()) { + t.Fatalf("015 and needs-triage must come off in the claim write: removed=%v", fake.removed[14586]) + } + if slices.Contains(fake.removed[14586], "kind/bug") || slices.Contains(fake.removed[14586], "hive/claimed-by-scanner") { + t.Fatalf("unrelated labels must not be touched: removed=%v", fake.removed[14586]) + } + if len(fake.added[14587]) != 0 || !slices.Equal(fake.removed[14587], []string{triageAwaitingLabel}) { + t.Fatalf("already-claimed issue must shed only the stale label: added=%v removed=%v", fake.added[14587], fake.removed[14587]) + } + if got := strings.Join(fake.added[14588], ","); got != stagelabels.TriageNeeded.Label() || len(fake.removed[14588]) != 0 { + t.Fatalf("untriaged issue keeps needs-triage: added=%v removed=%v", fake.added[14588], fake.removed[14588]) + } +} diff --git a/src/pkg/stageengine/decision.go b/src/pkg/stageengine/decision.go index d88d8c1e06..268c9b1e84 100644 --- a/src/pkg/stageengine/decision.go +++ b/src/pkg/stageengine/decision.go @@ -36,12 +36,17 @@ type Decision struct { // positive "no stage" that clears the hive-owned labels. Additive to the // ADR-0025 shape, which has no way to say "skip" otherwise. Abstain bool + // Clear names hive-stamped labels outside the stage families that the + // derived stage has made stale, removed in the same label write + // (stagelabels.Desired.Clear): the reporter-trust awaiting label on an + // issue whose stage settles triage (hivecommons/hive#14586). + Clear []string } // Desired renders the Decision as the full hive-owned label set the writer // should make the item carry. func (d Decision) Desired() stagelabels.Desired { - return stagelabels.Desired{Stage: d.Stage, Role: d.Role, Kind: d.Kind, KindLabels: d.KindLabels, Stalled: d.Stalled, DCO: d.DCO, MergeCommit: d.MergeCommit} + return stagelabels.Desired{Stage: d.Stage, Role: d.Role, Kind: d.Kind, KindLabels: d.KindLabels, Stalled: d.Stalled, DCO: d.DCO, MergeCommit: d.MergeCommit, Clear: d.Clear} } // abstain is the Decision for "no opinion" with a reason for the log. diff --git a/src/pkg/stageengine/derive_issue.go b/src/pkg/stageengine/derive_issue.go index 1d4369f6c8..5f9b9075fb 100644 --- a/src/pkg/stageengine/derive_issue.go +++ b/src/pkg/stageengine/derive_issue.go @@ -58,9 +58,27 @@ func deriveIssue(f Facts) Decision { // label as found and the next sweep re-judges it from the restarted // clock. Stalled: f.Issue.Stalled && stage != stagelabels.None, + Clear: issueTriageClear(f, stage), } } +// issueTriageClear names the reporter-trust awaiting label the issue still +// wears once its stage has settled triage (020 claimed and later), so the +// writer removes it in the same label write as the stage. 015 is a tracking +// state, not a gate: the scanner claims an untriaged issue exactly as a +// triaged one, which left hive-filed self-reports (fleetreport stamps +// `needs-triage` at filing) claimed, closed and still "needing triage" +// (hivecommons/hive#14586). Nil at 010/015/017/045 and when the label is +// absent, so an issue before the claim keeps the label and nothing else +// churns. +func issueTriageClear(f Facts, stage stagelabels.Stage) []string { + label := strings.TrimSpace(f.Issue.TriageAwaitingLabel) + if label == "" || !stage.SettlesTriage() { + return nil + } + return []string{label} +} + // issueStage is the bucket → stage mapping. covered reports whether an open // PR the lanes have staged at 040 or later covers the issue (health then // belongs to the PR, whose stage the reason names). diff --git a/src/pkg/stageengine/derive_issue_triage_clear_test.go b/src/pkg/stageengine/derive_issue_triage_clear_test.go new file mode 100644 index 0000000000..ad3a495de5 --- /dev/null +++ b/src/pkg/stageengine/derive_issue_triage_clear_test.go @@ -0,0 +1,74 @@ +package stageengine + +import ( + "slices" + "testing" + + "github.com/hivecommons/hive/pkg/claims" + "github.com/hivecommons/hive/pkg/stagelabels" +) + +// A claimed (020), PR-in-progress (030) or covered (040) issue still wearing +// the reporter-trust awaiting label asks the writer to clear it in the same +// label write (hivecommons/hive#14586): 015 is not a gate, so the label is +// stale once the hive has moved on. Before the claim — 010, 015, the 045 +// park — and when the label is absent, nothing is cleared. +func TestDeriveIssueClearsStaleTriageLabelPastClaim(t *testing.T) { + const label = "needs-triage" + wearing := func(mut func(f *Facts)) func(f *Facts) { + return func(f *Facts) { + f.Labels = append(f.Labels, label) + f.Issue.TriageAwaiting = "carries " + label + f.Issue.TriageAwaitingLabel = label + if mut != nil { + mut(f) + } + } + } + cases := []struct { + name string + mut func(f *Facts) + stage stagelabels.Stage + clear []string + }{ + {"015 keeps the label", wearing(nil), stagelabels.TriageNeeded, nil}, + {"direct claim 015→020 clears it", wearing(func(f *Facts) { + f.Issue.Bucket = BucketClaimed + f.Issue.Claim = &ClaimFact{Holder: "scanner", Kind: claims.KindAgent} + }), stagelabels.Claimed, []string{label}}, + {"in-progress mark clears it", wearing(func(f *Facts) { f.Issue.Bucket = BucketInProgress }), stagelabels.Claimed, []string{label}}, + {"PR under way clears it", wearing(func(f *Facts) { + f.Issue.Bucket = BucketClaimed + f.Issue.Claim = &ClaimFact{Kind: claims.KindAgent, PRStarted: true} + }), stagelabels.PRInProgress, []string{label}}, + {"covered by PR clears it", wearing(func(f *Facts) { + f.Issue.Bucket = BucketCoveredByPR + f.Issue.CoveringPR = &Ref{Owner: "acme", Repo: "widgets", Number: 99, Kind: stagelabels.PRItem} + }), stagelabels.CoveredByPR, []string{label}}, + {"045 park keeps the label", wearing(func(f *Facts) { f.Park.DecisionLabel = "needs-spec" }), stagelabels.IssueNeedsDecision, nil}, + {"umbrella claim stays untriaged", wearing(func(f *Facts) { + f.Issue.Bucket = BucketClaimed + f.Issue.Claim = &ClaimFact{Kind: claims.KindAgent} + f.Issue.UmbrellaLabel = "epic" + }), stagelabels.TriageNeeded, nil}, + {"claimed without the label is a no-op", func(f *Facts) { + f.Issue.Bucket = BucketClaimed + f.Issue.Claim = &ClaimFact{Kind: claims.KindAgent} + }, stagelabels.Claimed, nil}, + {"closed clears nothing extra", wearing(func(f *Facts) { f.Open = false }), stagelabels.None, nil}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + d := DeriveIssue(derivedIssueFacts(tc.mut)) + if d.Stage != tc.stage { + t.Fatalf("stage = %s, want %s (%+v)", d.Stage, tc.stage, d) + } + if !slices.Equal(d.Clear, tc.clear) { + t.Fatalf("Clear = %v, want %v", d.Clear, tc.clear) + } + if got := d.Desired().Clear; !slices.Equal(got, tc.clear) { + t.Fatalf("Desired().Clear = %v, want %v", got, tc.clear) + } + }) + } +} diff --git a/src/pkg/stageengine/deriver_test.go b/src/pkg/stageengine/deriver_test.go index 6b26da7cc7..64a1165f09 100644 --- a/src/pkg/stageengine/deriver_test.go +++ b/src/pkg/stageengine/deriver_test.go @@ -1,6 +1,7 @@ package stageengine import ( + "reflect" "testing" "github.com/hivecommons/hive/pkg/stagelabels" @@ -30,7 +31,7 @@ func TestBuiltInDerivers(t *testing.T) { func TestDecisionDesiredAndRef(t *testing.T) { d := Decision{Stage: stagelabels.Fixing, Role: stagelabels.RoleTrusted, Kind: "hive", Stalled: true, DCO: stagelabels.DCOYes} want := stagelabels.Desired{Stage: stagelabels.Fixing, Role: stagelabels.RoleTrusted, Kind: "hive", Stalled: true, DCO: stagelabels.DCOYes} - if d.Desired() != want { + if !reflect.DeepEqual(d.Desired(), want) { t.Fatalf("Desired() = %+v", d.Desired()) } r := Ref{Owner: "Acme", Repo: "Widgets", Number: 12, Kind: stagelabels.PRItem} diff --git a/src/pkg/stageengine/facts.go b/src/pkg/stageengine/facts.go index faf47c0745..886670223a 100644 --- a/src/pkg/stageengine/facts.go +++ b/src/pkg/stageengine/facts.go @@ -155,6 +155,13 @@ type IssueFacts struct { // the reporter-trust awaiting label it carries or the gate's // reporter_triage bucket. TriageAwaiting string + // TriageAwaitingLabel is the reporter-trust awaiting label the issue + // actually wears (`needs-triage` / `reporter_trust.awaiting_label`), + // "" when it carries none. Separate from TriageAwaiting because a + // claimed issue still wearing it derives 020, not 015, and the deriver + // then asks the writer to clear the stale label in the same write + // (hivecommons/hive#14586). + TriageAwaitingLabel string } // ClaimFact is the live claim on an issue. diff --git a/src/pkg/stagelabels/plan_clear_test.go b/src/pkg/stagelabels/plan_clear_test.go new file mode 100644 index 0000000000..1054977f0d --- /dev/null +++ b/src/pkg/stagelabels/plan_clear_test.go @@ -0,0 +1,67 @@ +package stagelabels + +import ( + "slices" + "testing" +) + +// Desired.Clear names third-party labels the write must take off alongside +// the stage (hivecommons/hive#14586: the reporter-trust `needs-triage` left +// on a claimed issue). It removes only what is present, matches +// case-insensitively, never adds, and leaves every other foreign label alone. +func TestPlanClearRemovesNamedLabelsOnly(t *testing.T) { + want := Desired{Stage: Claimed, Clear: []string{"needs-triage"}} + + add, remove := Plan([]string{"stage/015-triage-needed", "needs-triage", "kind/bug", "hive/claimed-by-scanner"}, want) + if !slices.Equal(add, []string{"stage/020-claimed"}) { + t.Fatalf("add = %v", add) + } + if !slices.Contains(remove, "needs-triage") || !slices.Contains(remove, "stage/015-triage-needed") { + t.Fatalf("remove = %v; want the stale stage and needs-triage in one write", remove) + } + for _, l := range remove { + if l == "kind/bug" || l == "hive/claimed-by-scanner" { + t.Fatalf("plan touched an unrelated label: remove = %v", remove) + } + } + + // Stage already right: the stale label alone is due. + add, remove = Plan([]string{"stage/020-claimed", "Needs-Triage", "kind/bug"}, want) + if len(add) != 0 || !slices.Equal(remove, []string{"Needs-Triage"}) { + t.Fatalf("stage correct: add = %v remove = %v; want only the (case-insensitive) stale label removed", add, remove) + } + + // Label absent: nothing to do. + add, remove = Plan([]string{"stage/020-claimed", "kind/bug"}, want) + if len(add) != 0 || len(remove) != 0 { + t.Fatalf("absent: add = %v remove = %v; want a no-op", add, remove) + } + + // Clear never adds, and an empty Clear leaves the label where it is. + add, remove = Plan([]string{"stage/020-claimed", "needs-triage"}, Desired{Stage: Claimed}) + if len(add) != 0 || len(remove) != 0 { + t.Fatalf("no Clear: add = %v remove = %v; want needs-triage untouched", add, remove) + } +} + +// SettlesTriage is true from the claim on (and for the PR-mirrored stages) +// and false before it, on the 045 park, and for None — those are the stages +// the transition table lets fall back to 015, so the label must survive. +func TestSettlesTriage(t *testing.T) { + cases := map[Stage]bool{ + None: false, + Actionable: false, + TriageNeeded: false, + IssueNeedsDecision: false, + Claimed: true, + PRInProgress: true, + CoveredByPR: true, + ReviewPending: true, + MergeQueue: true, + } + for s, want := range cases { + if got := s.SettlesTriage(); got != want { + t.Errorf("%s.SettlesTriage() = %v, want %v", s, got, want) + } + } +} diff --git a/src/pkg/stagelabels/stagelabels.go b/src/pkg/stagelabels/stagelabels.go index 446214c93b..fc7b03ac04 100644 --- a/src/pkg/stagelabels/stagelabels.go +++ b/src/pkg/stagelabels/stagelabels.go @@ -411,6 +411,18 @@ func (s Stage) Before(other Stage) bool { return s.Number() < other.Number() } +// SettlesTriage reports whether an issue at s has moved past the triage +// question: it is claimed (020), has a PR under way (030), is covered by an +// open PR (040) or mirrors a PR stage. 015 is a tracking state, not a gate +// (the scanner claims from it exactly as from 010), so a `needs-triage` the +// issue still wears at one of these stages is stale: the reconciler removes +// it (Desired.Clear) and the activity monitor does not read "Triage needed" +// from it (hivecommons/hive#14586). 010, 015, 017 and the 045 park are +// before the claim and keep the label. +func (s Stage) SettlesTriage() bool { + return s != None && !s.Before(Claimed) && s != IssueNeedsDecision +} + // YieldsToAdoption reports whether a live adoption (Record.AdoptionLive) // replaces s with AdoptedByHive. Adoption is who owns the PR, not what CI // says, so it outranks every review-side stage — 050 review-pending, 060 @@ -759,6 +771,13 @@ type Desired struct { // MergeCommit is the merge-method verdict for the head; // MergeCommitUnknown leaves `merge-method/merge` as found. MergeCommit MergeCommitState + // Clear names labels outside the stage/role/author/health families + // that the item must not carry at this stage: a hive-stamped signal + // the stage has made stale (the reporter-trust awaiting label + // `needs-triage` once an issue is claimed, hivecommons/hive#14586). + // Each is removed when present and never added; matching is + // case-insensitive. Empty leaves every third-party label alone. + Clear []string } // Plan returns the labels to add and remove so current carries exactly the @@ -792,6 +811,12 @@ func Plan(current []string, want Desired) (add, remove []string) { if want.MergeCommit == MergeCommitWanted { wantLabel(MergeCommitLabel) } + clearSet := map[string]bool{} + for _, l := range want.Clear { + if l = strings.ToLower(strings.TrimSpace(l)); l != "" { + clearSet[l] = true + } + } // Matching is case-insensitive: wanted keys and each current label are // compared through their lowercased forms, so a mis-cased existing label // counts as present rather than being removed and re-added. Removals @@ -807,6 +832,10 @@ func Plan(current []string, want Desired) (add, remove []string) { if _, ok := wanted[lower]; ok { continue } + if clearSet[lower] { + remove = append(remove, l) + continue + } // The hive's own DCO pair is reconciled only once the commit check // has spoken; an unread head keeps its pill. if dcoOwned(lower) {