diff --git a/changelog.d/changed-15712.md b/changelog.d/changed-15712.md new file mode 100644 index 0000000000..a99710f1c3 --- /dev/null +++ b/changelog.d/changed-15712.md @@ -0,0 +1 @@ +- refactor: split src/docs/labels-and-control-signals.md into per-section pages (#15712) diff --git a/src/docs/adr/0025-central-stage-engine.md b/src/docs/adr/0025-central-stage-engine.md index 6b5bdfa859..4e55ca7623 100644 --- a/src/docs/adr/0025-central-stage-engine.md +++ b/src/docs/adr/0025-central-stage-engine.md @@ -84,7 +84,7 @@ hub read that store and nothing else (`stageStoreOrShared`, parking stages through the label relay (`agentMayAddLabel`, `src/pkg/github/issue_request_label.go:75`), so a clanker can set a stage label and only the next sweep's self-heal corrects it. The docs admit the - arrangement (`src/docs/labels-and-control-signals.md:313-316`). The PR-D + arrangement (`src/docs/labels-and-control-signals/reference.md:313-316`). The PR-D vocabulary cleanup makes claim labels and review adoption checks use `stagelabels` directly; their fact-submission migration remains separate. 3. *No explicit transition model.* `Store.Observe` records that a stage diff --git a/src/docs/contributor-relay.md b/src/docs/contributor-relay.md index b5545f55b8..b5486e9acd 100644 --- a/src/docs/contributor-relay.md +++ b/src/docs/contributor-relay.md @@ -1276,7 +1276,7 @@ The prompt forbids printing `no_work_needed` *and* `complete` for one task, but ### fix-pr tasks -The one place a declaration DOES shape dispatch is the stage-072 contributor nudge ([labels-and-control-signals.md](labels-and-control-signals.md#off-the-happy-path-072--nudge--074--takeover)), and only in the client's favour: the hub never grants more than the relay asked for. When one of a contributor's earlier PRs goes red (failing checks, `changes_requested`, conflicts) and the contributor is online — a heartbeat within `governor.labels.stage.presence_window`, default 15m — the hub pushes the diagnosis to their relay as a `task_assign` the relay may receive **while a task is already running**: +The one place a declaration DOES shape dispatch is the stage-072 contributor nudge ([labels-and-control-signals.md](labels-and-control-signals/stage-labels.md#off-the-happy-path-072--nudge--074--takeover)), and only in the client's favour: the hub never grants more than the relay asked for. When one of a contributor's earlier PRs goes red (failing checks, `changes_requested`, conflicts) and the contributor is online — a heartbeat within `governor.labels.stage.presence_window`, default 15m — the hub pushes the diagnosis to their relay as a `task_assign` the relay may receive **while a task is already running**: ```json { "type": "task_assign", "task_id": "…", "task_gen": 7, diff --git a/src/docs/dashboard.md b/src/docs/dashboard.md index 96bed2450b..9da7131386 100644 --- a/src/docs/dashboard.md +++ b/src/docs/dashboard.md @@ -530,11 +530,11 @@ The badge is derived from Hive's own PR-claim evidence — the same source that ## Review pipeline board -The **Review** section opens with a separately collapsible **Pipeline** tile that shows every open PR as a card in the column for its review stage, from `GET /api/review/pipeline`: unreviewed, reviewing, changes requested, fixing, human hold, approved (merged and abandoned columns stay empty until the API returns those PRs). Each card shows the PR link, an agent or contributor marker, time in stage, reviewer chips, P0–P3 finding counts, the fix-loop counter (red once it is within one of the cap) and the next-action link. Filter by repo, author kind or stage; column headers carry counts. A ⚡ marker on the card means a webhook push or review request triggered the review of the current head (`trigger: event`), ⏳ that one is queued; see [Event-driven dispatch](review-swarm.md#event-driven-dispatch). The board refreshes every 30 seconds and keeps its scroll position. The sibling **Queue** tile is separately collapsible too, ranking the same open PRs in Hive’s suggested review order from `GET /api/review/queue` without hiding the Pipeline tile. A contributor PR the supersession sweep detected as superseded by a merged PR is tagged **superseded** there, with a link to the merged PR, whether or not `supersession_sweep.close_contributor_prs` is on; only when auto-close is on does the tag also show when the grace window ends and the sweep will close it, otherwise it reads "close as superseded or keep open" with no countdown. Owners get **Close now** and **Keep open** (adds `hive/keep-open`, which the sweep never auto-closes). Each queue row reflects the PR's `stage` from the stage-label store ([labels-and-control-signals.md](labels-and-control-signals.md#stagestalled--nobody-is-working-this)): the `stage/stalled` label's tooltip reads "no activity for Xh — nobody is working this PR", a red **waiting on hive Xh** pill marks a PR past its stage dwell while the hive itself holds it (checks running or reviewer verdict pending — the reviewer lane, not the author, needs attention), and an **N hops, M back** pill carries the stage transition history (`stage.history[]`) in its tooltip, replacing the retired `stage/regressed` label. +The **Review** section opens with a separately collapsible **Pipeline** tile that shows every open PR as a card in the column for its review stage, from `GET /api/review/pipeline`: unreviewed, reviewing, changes requested, fixing, human hold, approved (merged and abandoned columns stay empty until the API returns those PRs). Each card shows the PR link, an agent or contributor marker, time in stage, reviewer chips, P0–P3 finding counts, the fix-loop counter (red once it is within one of the cap) and the next-action link. Filter by repo, author kind or stage; column headers carry counts. A ⚡ marker on the card means a webhook push or review request triggered the review of the current head (`trigger: event`), ⏳ that one is queued; see [Event-driven dispatch](review-swarm.md#event-driven-dispatch). The board refreshes every 30 seconds and keeps its scroll position. The sibling **Queue** tile is separately collapsible too, ranking the same open PRs in Hive’s suggested review order from `GET /api/review/queue` without hiding the Pipeline tile. A contributor PR the supersession sweep detected as superseded by a merged PR is tagged **superseded** there, with a link to the merged PR, whether or not `supersession_sweep.close_contributor_prs` is on; only when auto-close is on does the tag also show when the grace window ends and the sweep will close it, otherwise it reads "close as superseded or keep open" with no countdown. Owners get **Close now** and **Keep open** (adds `hive/keep-open`, which the sweep never auto-closes). Each queue row reflects the PR's `stage` from the stage-label store ([labels-and-control-signals.md](labels-and-control-signals/stage-labels.md#stagestalled--nobody-is-working-this)): the `stage/stalled` label's tooltip reads "no activity for Xh — nobody is working this PR", a red **waiting on hive Xh** pill marks a PR past its stage dwell while the hive itself holds it (checks running or reviewer verdict pending — the reviewer lane, not the author, needs attention), and an **N hops, M back** pill carries the stage transition history (`stage.history[]`) in its tooltip, replacing the retired `stage/regressed` label. ## Hive activity monitor -The **Hive activity monitor** section (sidebar, Dashboard group; expanded by default) is the "where is my pizza" view of the hive: one entry per open issue and PR from `GET /api/stage-tracker`, each a title line over a thin tracker strip. Issues and PRs share one set of columns — `Open → Actionable → Claimed → PR in progress → CI / Review → Merge gate → ✓` — with the step names printed once in a column header. Covering PRs nest under their issue: an issue with no PR yet draws the whole strip like any other row (its lit step is Open/Actionable/Claimed with the steps ahead faint); once exactly one PR covers it the issue and PR collapse into a single entry: the issue's `#N title` on the left, `[author icon] #PR title` in the *PR in progress* column of the same title line, and one continuous strip beneath — Open/Actionable/Claimed passed, then the PR's stage drives the lit chevron through `CI / Review → Merge gate → ✓` (chips, tooltip and `since` come from the PR). With two or more covering PRs the issue's own strip stops at Claimed — all passed, nothing lit — and directly beneath, one indented sub-row per open covering PR (furthest along first) carries `[author icon] #N title` at the *PR in progress* column and that PR's own strip from there on with its own lit chevron, modifier chip, tooltip and `since`. A PR linked to an open issue in the list has no top-level row of its own (`nested_under`); PRs with no linked issue keep a full-width row. The *Pull requests* filter flattens the list (every PR a top-level row); *Issues* and *All* show the nested view. Only the current step is coloured (amber, named in words; the ✓ chevron turns green once merged). Whether it moves depends on its *motion bucket* (`stageTrackerMotion()` in `index.html`): **static** — a steady fill — for Open, Open · on hold (any hold label, whatever else is on the item), Actionable (010), Claimed (020), a PR in progress / Covered by PR (030/040) by a human author, Merged, and any stage the dashboard does not recognise; **active** — a gentle pulse — when the hive is acting (030/040 with 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** — a slower amber→red breathe — when 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 any `stalled` / `blocked` / `needs-human` / `needs-decision` / `needs-triage` modifier). Under `prefers-reduced-motion` nothing animates and a needs-human step keeps a steady red tint instead; passed and upcoming steps are low-contrast shapes with a small grey glyph each. Side stages ride the step they branch from — 070/071/072/074 light *CI / Review* as "Fixing" / "Needs author" / "Returned to contributor" / "Adopted by hive", 085/090 light *Merge gate* as "Needs human decision" / "Ready for human merge". The lit chevron ends with a small icon of whose move it is, in the chevron's ink (person = human, robot = clanker, hexagon = hive): the claimant on *Claimed*, the PR author on *PR in progress* and *Returned to contributor*, hive on *CI / Review* / *Adopted by hive* / *Ready for auto merge*, a human on *Triage needed* / *Needs human decision* / *Ready for human merge*; *Open* and *Actionable* carry none; 015 (an actionable issue no maintainer has triaged yet) and 045 light *Actionable* as "Triage needed" / "Needs human decision"; 040 shares *PR in progress* with 030, 060/080/100 light *Merge gate* as "Ready for auto merge" (the chevron tooltip distinguishes "not yet admitted — reason" from "admitted, merging") (the chevron tooltip names the exact stage). Every PR stage has a word: 050/060 "CI / Review", 070 "Fixing" (the author's move — a `needs-rebase` chip beside it says *what* is being fixed; the stage labeller always puts a needs-rebase PR at 070/071/072, never 050/060), 071 "Needs author" (a human-authored PR the author must act on), 072 "Returned to contributor" (a clanker PR handed back to its hive), 074 "Adopted by hive", 080/100 "Ready for auto merge", 085 "Needs human decision", 090 "Ready for human merge". A PR with no linked issue is named exactly once: its title line reads `[kind icon] [author icon] #N title` on the left (no entry in the *PR in progress* column) over one continuous strip with Open/Actionable/Claimed passed and its own stage lit; the `[author icon] #N title` entry under the *PR in progress* header appears only for covering PRs (single-PR entries and nested sub-rows). The author icon is coloured by `author/*` kind (hive blue, clanker purple, human teal). A PR is never an issue in this list: when the same number arrives through both the issues feed and the pulls feed, the PR record wins and the issue-feed copy is dropped server-side (pairing is keyed by repo, kind and number, so a PR can never be its own parent), and the *Issues* filter never shows one. A `since` column on the title line gives time on the current step (red when stalled), with at most one muted health-modifier chip to its left; the reason sentence, actor, nudges, flags and the last stage hops live in the hover tooltip. Titles never wrap: an issue title is cut with an ellipsis before it would reach the *PR in progress* column (leaving a clear gap, so the PR entry always starts at the column's left edge) and a PR title before the chips and `since`; the full title is on the title element's own hover tooltip, separate from the strip's reason tooltip. Rows are sorted furthest-along first by default (a covered issue ranks by its furthest-along PR, not its own 040), then longest-waiting first; the *Sort* select also offers longest waiting, newest and number, with an arrow button that reverses the direction. The list is complete: every open issue and PR of the watched repos is an entry — including claimed, in-progress, needs-human / needs-decision / needs-triage-filtered and reporter-held issues, draft PRs and PRs carrying an exempt label — and an item with no stage yet sits at *Open*. The toolbar filters the cached payload in the browser: *All / Pull requests / Issues*, *Repo*, a search box (`#number`, number or title substring, also matching a covering PR), *Since* (any / over 1 hour / over 1 day / over 1 week on the current step, or *past the stage dwell* = stalled or longer than the step's configured dwell), *Author* (human / clanker / hive) and a *Needs attention* toggle; a row of label chips built from the labels present (`stage/*`, `needs-*`, `author/*`, `role/*`, then any other label shared by two or more items) narrows further — chips of one family OR together, families AND together. *Clear filters* appears whenever something is narrowed. Filter, sort and page size persist in the browser (`localStorage`); the page does not. Pages hold 25 / 50 / 100 rows (default 50) with Prev / Next above and below the list and a "showing X–Y of N (M filtered out)" line; the section header reads "N items (I issues / P PRs) · M need attention" for the whole list (N, I, P come from `open_issues` / `open_prs` in the payload — the same `openItems` set behind the Overview tile, so N equals the tile's total open issues + PRs — with "· X match filters" appended while a filter is on) while the sidebar badge shows the same N (total open items, same render pass — never a separately computed number) with the needs-attention count (modifiers present, or on 071/072/085/090, counted over every item) in its hover tooltip and as the warn-coloured header suffix. The meta line also says "updated Ns ago · cache|fresh": the payload is built server-side at most once per `dashboard.stage_tracker.cache_ttl_s` (default = `governor.eval_interval_s`) from the spoke's existing GitHub snapshot and served with an `ETag`, so the 30-second poll costs a 304 and never a GitHub call (it turns amber once the payload is older than two TTLs). A GitHub webhook naming a listed PR or issue re-reads just that item (one `GET`, debounced by `dashboard.stage_tracker.webhook_refresh_debounce_ms`, default `2000`; off with `dashboard.stage_tracker.webhook_refresh: false`) and patches its row within seconds, ahead of the next eval cycle; see [Webhook-driven PR cache invalidation](operator-reference.md#webhook-driven-pr-cache-invalidation) and, for how that patch relates to the cadence tick and the reconcile that overwrites it (and what `/api/status.webhooks.mode` means when it reads `polling`), [webhooks.md](webhooks.md). Section details: [dashboard-sections.md](dashboard-sections.md#hive-activity-monitor); stage semantics: [labels-and-control-signals.md](labels-and-control-signals.md#stage-labels-stagennn--the-pipeline-state-machine). +The **Hive activity monitor** section (sidebar, Dashboard group; expanded by default) is the "where is my pizza" view of the hive: one entry per open issue and PR from `GET /api/stage-tracker`, each a title line over a thin tracker strip. Issues and PRs share one set of columns — `Open → Actionable → Claimed → PR in progress → CI / Review → Merge gate → ✓` — with the step names printed once in a column header. Covering PRs nest under their issue: an issue with no PR yet draws the whole strip like any other row (its lit step is Open/Actionable/Claimed with the steps ahead faint); once exactly one PR covers it the issue and PR collapse into a single entry: the issue's `#N title` on the left, `[author icon] #PR title` in the *PR in progress* column of the same title line, and one continuous strip beneath — Open/Actionable/Claimed passed, then the PR's stage drives the lit chevron through `CI / Review → Merge gate → ✓` (chips, tooltip and `since` come from the PR). With two or more covering PRs the issue's own strip stops at Claimed — all passed, nothing lit — and directly beneath, one indented sub-row per open covering PR (furthest along first) carries `[author icon] #N title` at the *PR in progress* column and that PR's own strip from there on with its own lit chevron, modifier chip, tooltip and `since`. A PR linked to an open issue in the list has no top-level row of its own (`nested_under`); PRs with no linked issue keep a full-width row. The *Pull requests* filter flattens the list (every PR a top-level row); *Issues* and *All* show the nested view. Only the current step is coloured (amber, named in words; the ✓ chevron turns green once merged). Whether it moves depends on its *motion bucket* (`stageTrackerMotion()` in `index.html`): **static** — a steady fill — for Open, Open · on hold (any hold label, whatever else is on the item), Actionable (010), Claimed (020), a PR in progress / Covered by PR (030/040) by a human author, Merged, and any stage the dashboard does not recognise; **active** — a gentle pulse — when the hive is acting (030/040 with 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** — a slower amber→red breathe — when 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 any `stalled` / `blocked` / `needs-human` / `needs-decision` / `needs-triage` modifier). Under `prefers-reduced-motion` nothing animates and a needs-human step keeps a steady red tint instead; passed and upcoming steps are low-contrast shapes with a small grey glyph each. Side stages ride the step they branch from — 070/071/072/074 light *CI / Review* as "Fixing" / "Needs author" / "Returned to contributor" / "Adopted by hive", 085/090 light *Merge gate* as "Needs human decision" / "Ready for human merge". The lit chevron ends with a small icon of whose move it is, in the chevron's ink (person = human, robot = clanker, hexagon = hive): the claimant on *Claimed*, the PR author on *PR in progress* and *Returned to contributor*, hive on *CI / Review* / *Adopted by hive* / *Ready for auto merge*, a human on *Triage needed* / *Needs human decision* / *Ready for human merge*; *Open* and *Actionable* carry none; 015 (an actionable issue no maintainer has triaged yet) and 045 light *Actionable* as "Triage needed" / "Needs human decision"; 040 shares *PR in progress* with 030, 060/080/100 light *Merge gate* as "Ready for auto merge" (the chevron tooltip distinguishes "not yet admitted — reason" from "admitted, merging") (the chevron tooltip names the exact stage). Every PR stage has a word: 050/060 "CI / Review", 070 "Fixing" (the author's move — a `needs-rebase` chip beside it says *what* is being fixed; the stage labeller always puts a needs-rebase PR at 070/071/072, never 050/060), 071 "Needs author" (a human-authored PR the author must act on), 072 "Returned to contributor" (a clanker PR handed back to its hive), 074 "Adopted by hive", 080/100 "Ready for auto merge", 085 "Needs human decision", 090 "Ready for human merge". A PR with no linked issue is named exactly once: its title line reads `[kind icon] [author icon] #N title` on the left (no entry in the *PR in progress* column) over one continuous strip with Open/Actionable/Claimed passed and its own stage lit; the `[author icon] #N title` entry under the *PR in progress* header appears only for covering PRs (single-PR entries and nested sub-rows). The author icon is coloured by `author/*` kind (hive blue, clanker purple, human teal). A PR is never an issue in this list: when the same number arrives through both the issues feed and the pulls feed, the PR record wins and the issue-feed copy is dropped server-side (pairing is keyed by repo, kind and number, so a PR can never be its own parent), and the *Issues* filter never shows one. A `since` column on the title line gives time on the current step (red when stalled), with at most one muted health-modifier chip to its left; the reason sentence, actor, nudges, flags and the last stage hops live in the hover tooltip. Titles never wrap: an issue title is cut with an ellipsis before it would reach the *PR in progress* column (leaving a clear gap, so the PR entry always starts at the column's left edge) and a PR title before the chips and `since`; the full title is on the title element's own hover tooltip, separate from the strip's reason tooltip. Rows are sorted furthest-along first by default (a covered issue ranks by its furthest-along PR, not its own 040), then longest-waiting first; the *Sort* select also offers longest waiting, newest and number, with an arrow button that reverses the direction. The list is complete: every open issue and PR of the watched repos is an entry — including claimed, in-progress, needs-human / needs-decision / needs-triage-filtered and reporter-held issues, draft PRs and PRs carrying an exempt label — and an item with no stage yet sits at *Open*. The toolbar filters the cached payload in the browser: *All / Pull requests / Issues*, *Repo*, a search box (`#number`, number or title substring, also matching a covering PR), *Since* (any / over 1 hour / over 1 day / over 1 week on the current step, or *past the stage dwell* = stalled or longer than the step's configured dwell), *Author* (human / clanker / hive) and a *Needs attention* toggle; a row of label chips built from the labels present (`stage/*`, `needs-*`, `author/*`, `role/*`, then any other label shared by two or more items) narrows further — chips of one family OR together, families AND together. *Clear filters* appears whenever something is narrowed. Filter, sort and page size persist in the browser (`localStorage`); the page does not. Pages hold 25 / 50 / 100 rows (default 50) with Prev / Next above and below the list and a "showing X–Y of N (M filtered out)" line; the section header reads "N items (I issues / P PRs) · M need attention" for the whole list (N, I, P come from `open_issues` / `open_prs` in the payload — the same `openItems` set behind the Overview tile, so N equals the tile's total open issues + PRs — with "· X match filters" appended while a filter is on) while the sidebar badge shows the same N (total open items, same render pass — never a separately computed number) with the needs-attention count (modifiers present, or on 071/072/085/090, counted over every item) in its hover tooltip and as the warn-coloured header suffix. The meta line also says "updated Ns ago · cache|fresh": the payload is built server-side at most once per `dashboard.stage_tracker.cache_ttl_s` (default = `governor.eval_interval_s`) from the spoke's existing GitHub snapshot and served with an `ETag`, so the 30-second poll costs a 304 and never a GitHub call (it turns amber once the payload is older than two TTLs). A GitHub webhook naming a listed PR or issue re-reads just that item (one `GET`, debounced by `dashboard.stage_tracker.webhook_refresh_debounce_ms`, default `2000`; off with `dashboard.stage_tracker.webhook_refresh: false`) and patches its row within seconds, ahead of the next eval cycle; see [Webhook-driven PR cache invalidation](operator-reference.md#webhook-driven-pr-cache-invalidation) and, for how that patch relates to the cadence tick and the reconcile that overwrites it (and what `/api/status.webhooks.mode` means when it reads `polling`), [webhooks.md](webhooks.md). Section details: [dashboard-sections.md](dashboard-sections.md#hive-activity-monitor); stage semantics: [labels-and-control-signals.md](labels-and-control-signals/stage-labels.md#stage-labels-stagennn--the-pipeline-state-machine). **Sounds (opt-in).** The speaker chip at the right end of the toolbar (🔇 off / 🔊 on; default off, remembered per browser under the `localStorage` key `hive.tracker.sound`) enables two short sounds, both synthesised in the browser with the Web Audio API (no audio file, no network request). The **merge zap** — just under half a second of bug-zapper arc: a ~4 ms high-voltage "snap", then a sputtering electric sizzle (bright noise and a 240 Hz square chopped by a 120 Hz mains pulse train, dropping out and re-striking at random) that holds ~80 ms and dies away, high-passed at 700 Hz — plays when a pull request the tab was already showing merges while the page is open. The trigger compares tracker payloads: a PR counts as merged when its stage reaches the ✓ cap or when its key appears in the payload's `recently_merged` list (the hive's `pr_merged` audit entries of the last 30 minutes — sweep, queue, relay and human merges the PR poller observed alike — which is how a PR that simply dropped out of the open list is told apart from one closed unmerged). Entries that name the repo by its configured short name are qualified to the `owner/name` the rows carry, and a PR that drops off the list a poll before its audit entry lands is still remembered as open until `recently_merged` settles it, so the two never have to arrive in the same payload. It never fires on the first load, for rows that were already merged, for issues, or for a PR it has already zapped; several merges in one refresh play at most two zaps. The **new-item buzz** — a quieter 0.18 s sawtooth near 120 Hz with a ~30 Hz tremolo through a lowpass — plays when an issue or pull request appears on the list that the previous payload did not have; it never fires on the first populated payload, buzzes once per item, and plays at most two buzzes per refresh. Nothing plays while the tab is hidden. Turning the chip on plays one zap then one buzz so you can hear both. The audio context is created on a user gesture and resumed if the browser suspended it; if the autoplay policy still holds it suspended when a sound is due, that sound is skipped and the next click or key press re-arms it. Detection runs over the union of every configured repo's rows, keyed `owner/name/kind#number`, so the sounds fire for each repo the hive governs. Either sound can be replaced from the card's ⚙ settings modal with a user-supplied file (WAV or anything `decodeAudioData` accepts, capped at 4 MB) stored in the browser's IndexedDB (`hive-tracker-sounds`); a stored file that fails to decode falls back to the built-in voice. The modal also carries the **Play sounds** master toggle and a 0–100 **Volume** slider (`localStorage` key `hive.tracker.sound.volume`) that scales the master gain of both built-in and uploaded sounds. Closed issues are not an event the tracker payload carries, so nothing plays for them. diff --git a/src/docs/env-vars.md b/src/docs/env-vars.md index 481ed162f4..9bc216ec03 100644 --- a/src/docs/env-vars.md +++ b/src/docs/env-vars.md @@ -566,7 +566,7 @@ With two or more providers configured, `/login` renders a provider picker; with | Variable | Required | Default | Purpose | |---|---|---|---| -| `HIVE_QUESTION_AUTOCLOSE` | No | unset (config `governor.question_autoclose.enabled`, default `false`) | Turns question auto-close on or off, overriding the config value when set to a boolean (`true`/`false`/`1`/`0`). See [labels-and-control-signals.md](labels-and-control-signals.md#question-auto-close) ([#9584](https://github.com/hivecommons/hive/issues/9584)). | +| `HIVE_QUESTION_AUTOCLOSE` | No | unset (config `governor.question_autoclose.enabled`, default `false`) | Turns question auto-close on or off, overriding the config value when set to a boolean (`true`/`false`/`1`/`0`). See [labels-and-control-signals.md](labels-and-control-signals/glossary-and-operations.md#question-auto-close) ([#9584](https://github.com/hivecommons/hive/issues/9584)). | | `HIVE_QUESTION_AUTOCLOSE_HOURS` | No | `4` (config `governor.question_autoclose.hours`) | Hours an answered question stays open for the author to react 👎 before Hive closes it as completed. Non-positive or non-numeric values are ignored. | ## Credly badge integration (proposed — not implemented) diff --git a/src/docs/github-write-surface.md b/src/docs/github-write-surface.md index 2bb7d3749e..bfdbc38292 100644 --- a/src/docs/github-write-surface.md +++ b/src/docs/github-write-surface.md @@ -176,7 +176,7 @@ requires an `Origin` on its request and normalises labels through upstream-watch, convergence channel) add their non-lane origin label themselves. Provenance is never a gate: if a non-lane origin label cannot be ensured on the repo the issue is still filed without it (logged as a warning), whereas a -retryable failure on a routing label keeps the request queued as before. See [labels-and-control-signals.md](labels-and-control-signals.md#origin-sources). +retryable failure on a routing label keeps the request queued as before. See [labels-and-control-signals.md](labels-and-control-signals/reference.md#origin-sources). ## Lane allowlist diff --git a/src/docs/hive-merge.md b/src/docs/hive-merge.md index 11d81a5682..778d5ed941 100644 --- a/src/docs/hive-merge.md +++ b/src/docs/hive-merge.md @@ -734,7 +734,7 @@ the planned set differs from the labels already on the PR, under the `governor.labels.stage.enabled`. The mapping table, numbering rules, dwell thresholds, the mermaid state machine and the off-happy-path flow (072 → nudge → 074 → takeover) are in -[labels-and-control-signals.md](labels-and-control-signals.md#stage-labels-stagennn--the-pipeline-state-machine); +[labels-and-control-signals.md](labels-and-control-signals/stage-labels.md#stage-labels-stagennn--the-pipeline-state-machine); the code is `src/pkg/stagelabels` and `src/pkg/github/automerge/automerge_stage_labels.go`. Adoption (`stage/074-adopted-by-hive`, `automerge_contributor_adopt.go`) reuses this diff --git a/src/docs/hive-open-issue.md b/src/docs/hive-open-issue.md index 98176a69f9..785af061fb 100644 --- a/src/docs/hive-open-issue.md +++ b/src/docs/hive-open-issue.md @@ -136,7 +136,7 @@ the relation survives a failed link. Once every child of `n` is closed the issue stage sweep closes `n` as completed, and while any child is open `n` is never marked `stage/stalled` ([#12857](https://github.com/hivecommons/hive/issues/12857); see -[labels-and-control-signals.md](labels-and-control-signals.md#decomposed-parents--closed-by-their-children-never-stalled)). +[labels-and-control-signals.md](labels-and-control-signals/stage-labels.md#decomposed-parents--closed-by-their-children-never-stalled)). `--blocked-by ` records that the new issue must wait for issue(s) `n` in the same repo, as GitHub "blocked by" dependencies diff --git a/src/docs/labels-and-control-signals.md b/src/docs/labels-and-control-signals.md index 7cefcc16a6..6620ff9cb9 100644 --- a/src/docs/labels-and-control-signals.md +++ b/src/docs/labels-and-control-signals.md @@ -2,2629 +2,32 @@ This is the operator view of Hive labels: if you add or remove a label, this is what the v5 code does. It also calls out non-label controls that look like labels from the dashboard. -## First use: choose the control +The page is split into one file per area under [`labels-and-control-signals/`](labels-and-control-signals/) so concurrent edits do not collide. Every section keeps its heading and anchor inside its page. -Start from the item's current reason, not a stage number. In the dashboard, open the row's **⋯** menu; on GitHub, inspect its labels and latest explanation comment. Dashboard writes require the role allowed by that action; having a label visible does not grant permission to remove it. +## Pages -| Your task | Control and expected result | If it does not move | -| --- | --- | --- | -| Pause an issue or stop a PR merging | Use the dashboard hold or a matching hold label. Held work leaves normal agent/merge queues; a held red PR can still get CI repair without releasing the hold. | Check every hold label, including the Hive-scoped `hive-pause/`. | -| Resume held work | Release the hold only when its reason is resolved and you have authority to do so. | A new head may trigger holdguard and require fresh human approval. Do not have an agent remove a person's hold. | -| Wait for another PR or outside blocker | Inspect `blocked` and the linked blocker/deadline. A blocked issue is excluded from agent enumeration and automated claims, not merely coloured differently. | Follow the [blocked reference](#blocked); human-applied/re-applied blocks are not automatically lifted. | -| Admit an untrusted reporter's issue | Review it, then apply the configured acceptance label (default `triage/accepted`) or change the reporter-trust policy as an operator. | The ordinary required-label filter still applies after reporter triage. | -| Answer a direction or design question | Use the offered decision action or the exact `/hive decision` form in the reference. | Re-read the park reason; a hold, access restriction or owner-only question is not bypassed by a stage edit. | -| Find who repairs a red PR | Read `author/*`: Hive/self-authored → 070; human → 071; contributor agent → 072. | Use [Stage 07x by author kind](#stage-07x-by-author-kind), not the trust-role label, to find the responsible party. | -| Understand a Projects band | Treat it as a display group, not permission to claim or merge. | Check the actual holds, review, CI, trust and repository policy gates. | - -After an action, check the resulting label/stage, latest comment and dashboard result. A recorded approval is not proof of a merge. See [Dashboard sections explained](dashboard-sections.md#hive-activity-monitor) for row actions and their receipts. - -### The ordinary path - -An admitted issue becomes **010 Actionable**, then **020 Claimed** when someone takes it. Work moves through **030 PR in progress** / **040 Covered by PR** to **050 CI / Review**. A reviewed PR still has to enter the merge gate; **095 Soaking** means admitted but waiting, and **100 Merge queue** means admitted and merging. Human decisions, repair, holds and drafts can interrupt this path. Changing a stage label is not a way around those checks. - -A **stage** is the current step; a **lane** is the worker or processing path; the **head** is the PR's current tip commit. A review **verdict** is a result, **dwell** is time at a step, and **soak** is a pre-merge waiting period. A review **swarm** combines reviewers. **Adoption** means Hive takes responsibility for contributor-agent work; **re-home** means continuing it in a replacement PR, preserving authorship. A **ratchet** permits the old baseline but rejects increases. See the [reader glossary](dashboard-glossary.md#terms). - -### Find the precise rule - -- [Holds and pause controls](#holds-and-pause-controls) -- [Issue admission and triage](#issue-admission-and-triage) -- [PR review and merge controls](#pr-review-and-merge-controls) -- [Contributor routing and other signals](#contributor-routing-and-other-signals) -- [Retired names and compatibility signals](#retired-names-and-compatibility-signals) -- [Stage derivation](#stage-labels-stagennn--the-pipeline-state-machine), [matching rules](#matching-rules) and [implementation trace](#how-labels-reach-agents) - -Policy names matter more than issue numbers. **Self-authorization hold** (#5117) requires acknowledgment of Hive-filed rationale when enabled. **Reporter-trust hold** (#9665) concerns the linked issue's reporter, not the PR author's trust. **Hive-owned suppress reconciliation** (#12002) can lift only eligible Hive-applied holds/blocks; it is not permission to release human-owned controls. - -## Label axes - -Hive-authored labels answer different questions. Read them as independent axes, not as one taxonomy: an issue can carry one label from each axis at the same time, and swapping a label on one axis never changes what the others mean. - -| Axis | Shape | Question it answers | Signal? | Notes | -| --- | --- | --- | --- | --- | -| **Stage** | `stage/` | Where is this item in the pipeline? | Control (read by claims/auto-merge) | See [Stage labels](#stage-labels-stagennn--the-pipeline-state-machine) below. | -| **Agent** | `agent/` | Which agent works it and, for agent-filed issues, which lane filed it? | Routing + ownership + lane provenance | The suffix is always the lane name from `HIVE_AGENT`. The classifier routes on it, PR ownership compares against it, and `authorkind` treats it as this hive's author stamp. Agent-filed issues carry exactly one lane/provenance label: `agent/`. | -| **Origin** | `origin/` | Which non-lane hive component created this item? | Provenance only, never a gate | Reserved for hive filers that have no `agent/` equivalent: `origin/selfreport`, `origin/governor`, `origin/dashboard`, `origin/forge`, and `origin/convergence`. Agent lanes do not use `origin/`; the startup reconciler (`Client.MigrateOriginLabels`, `src/pkg/github/origin_labels.go`) removes redundant lane-origin and bare-lane labels while ensuring `agent/`. `origin/reviewer`, `origin/review`, and `from-review` are retired reviewer-lane spellings and map to `agent/reviewer`. | -| **Role** | `role/` | How far does the hive trust the author's login? | Control (auto-merge) | Was `author/` before #12581; the reconciler rewrites the old spelling. See [`role/*`](#role--would-the-hive-auto-merge-this). | -| **Author** | `author/` | Who wrote it — a person, a contributor's clanker, or this repo's hive? | Informational (gates the 072 nudge/adoption) | `author/human`, `author/clanker`, `author/hive`; names configurable under `governor.labels.author`. See [`author/*`](#author--who-wrote-this-pr). | -| **Modifiers** | `blocked`, `hold`, `needs-*`, `hive-pause/` | What is stopping it right now? | Hold / suppress | See the reference table; these are the hard gates. | - -### Origin sources - -The `` is the component that created the issue, never the person or hive that operates it. Agent lanes are not origin sources: an agent filing an issue gets `agent/` instead, and a bare `` label requested by that same agent is stripped as duplicate provenance. A caller-supplied non-lane `origin/*` label is kept and canonicalised; retired lane-origin spellings are mapped to `agent/`. - -| `origin/` | Created by | Code path | -| --- | --- | --- | -| `origin/selfreport` | Fleet runtime selfreports (`[selfreport] …`), filed directly or relayed by the hub. Sits next to the deprecated `hive/selfreport` for now. | `src/pkg/github/fleet_report.go`, `src/pkg/fleetreport/runtime.go`, `src/pkg/hub/selfreport_relay.go` | -| `origin/governor` | Governor automation: the advisory meta issue, the recommendations issue, upstream-watch filings. Task-list sweeps, stage regress and unpark notices do not file issues today; if they ever do, they use this source. | `src/pkg/github/advisory.go`, `src/pkg/github/recommendations.go`, `src/pkg/upstreamwatch/render.go` | -| `origin/dashboard` | Operator actions in the SPA that file an issue (ACMM eval filing). | `src/pkg/dashboard/api_acmm_eval.go` | -| `origin/forge` | The forge issue seam, when its consumer passes no origin label of its own. | `src/pkg/forge/github_forge.go` | -| `origin/convergence` | The convergence publisher and its GitHub channel. | `src/pkg/convergence/publish/publisher.go`, `src/pkg/convergence/publish/channel.go` | -| *(none)* | A human filing directly. **`origin/human` is deliberately never applied**: the absence of an origin label is what "a person filed this" looks like, and `author/*` already says who wrote a PR. | — | - -Work-source sinks other than GitHub (Jira, Linear) carry no GitHub labels and are outside the axis. - -Some hive-authored labels look like provenance but are read as signals, so they stay outside `origin/*` on purpose: `hive/selfreport` is the dedupe key the self-report joiner searches (`label:hive/selfreport` in `src/pkg/github/fleet_report.go`) and the hub relay re-applies it — it is **deprecated** in favour of `origin/selfreport`, which every new selfreport also carries, and will be removed once the joiner searches the origin label instead; `hive/advisory` makes an issue a standing meta issue that enumeration excludes (`src/pkg/github/standing_issues.go`); `hive/` is **retired** (#12539): nothing writes it any more, the origin marker in the body says which hive wrote an item, and the boot sweep strips leftovers (see the reference row). `hive/sentinel`, `hive/fleet` and `fleet` are only consulted by the good-first-issue exclusion list (`src/pkg/gfi/gfi.go`) and are no longer written by this code base. - -## Categories - -- **Informational / display-only** changes how Hive explains an item, not whether agents can act. -- **Workflow / status** marks a process state such as reviewer outcome or rebase need. -- **Gate / permit** admits, blocks, or releases a specific workflow. -- **Hold / suppress** removes work from agent/contributor/merge lanes until cleared. -- **Contributor eligibility / routing** affects `/contribute` offers or agent lane choice. -- **Human approval / acknowledgement** records that a human accepted a direction or design. - -## Reference table - -This reference replaces the former nine-column table with one headed entry per control. Each entry gives the effect first, then who applies it, when it is checked, how it is released and its exact configuration. Current controls are grouped by task; retired spellings are separated at the end. - -### Holds and pause controls - -#### `hold`, `on-hold`, `hold/review` - -**Applies to:** Issues, PRs. **Kind:** Hard hold. - -Any label containing a configured hold substring is held; held issues/PRs leave agent kicks, PR merge lanes, and the task-list sweep. Held red PRs still route back to their owning agent for CI repair, with instructions not to remove the hold. - -**Who applies it:** Human, Hive level gate, #5117 gate, holdguard, SHA-hold. - -**Checked by:** GitHub enumeration, auto-merge sweeps, task-list sweep. **When:** Enumeration and sweeps. - -**Release or override.** Remove the matching label; Hive releases only literal `hold` it applied itself (level gate, #5117, SHA-hold) - -**Configuration and implementation.** Built-in `HoldLabels`; dashboard exact hold via `Client.SetHoldLabels` (`src/pkg/github/client.go:1317`, `src/pkg/github/client.go:3314-3369`, `src/pkg/scheduler/policy_overlays.go:210-220`) - -#### `hive-pause/` - -**Applies to:** Issues, PRs. **Kind:** Hard hold. - -Exact, hive-scoped dashboard hold. It is not provenance and intentionally avoids the substring `hold`. - -**Who applies it:** Dashboard operator. - -**Checked by:** GitHub enumeration, dashboard hold toggle, auto-merge sweeps, task-list sweep. **When:** Enumeration and sweeps. - -**Release or override.** Dashboard Release removes labels causing the hold, including this one - -**Configuration and implementation.** Canonicalized from hive id (`src/pkg/github/client.go:3371-3380`, `src/pkg/github/client.go:3386-3392`, `src/docs/dashboard.md:80-96`) - -#### `hold` from ACMM level gate - -**Applies to:** PRs. **Kind:** Hard merge gate. - -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`). - -**Who applies it:** Hive App. - -**Checked by:** PR-request watcher, self-authored auto-merge release. **When:** PR creation, later self-authored auto-merge release. - -**Release or override.** 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 - -**Configuration and implementation.** 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 - -**Applies to:** PRs. **Kind:** Hard merge gate. - -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. - -**Who applies it:** Hive App. - -**Checked by:** PR-request watcher and self-authorization release. **When:** PR creation; evaluated only when no level hold applies. - -**Release or override.** 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. - -**Configuration and implementation.** `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`) - -#### `hold` from #9665 reporter trust - -**Applies to:** PRs **not authored by the hive**. **Kind:** Hard merge gate. - -A PR whose rationale 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 that the hold concerns the issue reporter, not the PR author. The rationale is **only the linked issues**: closing-keyword links (`Fixes`/`Closes`/`Resolves`) and the request's declared issues — bare `#N` mentions are not consulted, and a link that resolves to a pull request is skipped rather than judged (hivecommons/hive#15020: `Refs #15009 (closed by #15017)` made the gate judge sibling PR #15017 and attribute a `CONTRIBUTOR` who had merely commented). - -A hive-filed issue (`[selfreport]`, app or AI author) counts as trusted. The gate is **skipped entirely for hive-authored PRs** (App bot, `project.ai_author`, `author/hive`): the hive is the author, so the reporter's trust says nothing about whether its own fix may merge; it still applies to contributor PRs and to PRs opened under a shared PAT account. Any one untrusted citation holds. Evaluated even at hold-gated levels, because the notice is what stops promotion to L6 from releasing the label. - -**Who applies it:** Hive App. - -**Checked by:** PR-request watcher, level-hold release. **When:** PR creation; re-checked by the level-hold release path. - -**Release or override.** A human removes `hold` on a contributor PR; Hive never auto-releases it there. On a **hive-authored** PR still wearing a hive-set reporter-trust hold (newest `hold` event labeled by the App bot with the notice at or after it — a person's hold is left alone), the stage-label pass releases `hold` (and `needs-human` when the notice says the gate added it), posts one `` comment and logs `stage labels: releasing self-imposed reporter-trust hold`. - -The pass also records the hold's provenance (`by`, `source`, `reason`, `since`) on the stage store, so the tracker pill reads *Held by hive · reporter trust (issue #N by @X, contributor)* and the 085 comment names who set the hold and why. Holdguard re-holds on a new head SHA. - -**Configuration and implementation.** `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`, `src/pkg/github/automerge/reporter_trust_release.go`) - -#### `hold` from holdguard - -**Applies to:** PRs. **Kind:** Hard merge gate. - -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. - -**Who applies it:** Hive. - -**Checked by:** Holdguard ledger. **When:** Governor holdguard pass. - -**Release or override.** Human removes the re-applied hold - -**Configuration and implementation.** Built-in `holdguard.ReHoldLabel` (`src/pkg/holdguard/holdguard.go:1-43`) - -#### `hold` from SHA-hold - -**Applies to:** Issues. **Kind:** Hard issue hold. - -Human-filed primary-repo `kind/bug` without a 7-40 hex SHA gets `hold` and a notice carrying ``; once a SHA appears in body/comments, Hive removes `hold` only if the current hold is its own (newest `hold` event labeled by the App bot, paired with an App-authored notice at or after it). A human's hold, a re-hold, or another subsystem's hold stays. Reporters whose author association is trusted (`issue_filter.reporter_trust.trusted_associations`, default OWNER/MEMBER/COLLABORATOR) get the soft `needs-sha` row below instead, and a SHA-hold `hold` already on such an issue is swapped for it (#12002). - -The hard-suppress reconcile also lifts this `hold` once a PR referencing the issue merges after it was applied. - -**Who applies it:** Hive. - -**Checked by:** SHA-hold sweep. **When:** Eval tick SHA sweep; hard-suppress reconcile. - -**Release or override.** Add SHA evidence or merge the fix; sweep removes its own `hold`, a human removes any other - -**Configuration and implementation.** Primary repo and SHA-hold config (`src/pkg/github/client.go` `EnforceSHAHold`, `src/pkg/github/hard_suppress_reconcile.go`) - -#### `needs-sha` from SHA-hold - -**Applies to:** Issues. **Kind:** Soft (informational). - -Trusted-reporter `kind/bug` without a SHA gets this soft label plus the same `` notice instead of `hold`; the issue stays actionable. The sweep removes it once a SHA appears. - -**Who applies it:** Hive. - -**Checked by:** SHA-hold sweep. **When:** Eval tick SHA sweep. - -**Release or override.** Add SHA evidence, or remove the label - -**Configuration and implementation.** `issues.sha_hold_trusted_label` (default `needs-sha`; `hold` restores the hard hold for everyone) - -### Issue admission and triage - -#### GitHub "blocked by" dependency - -**Applies to:** Issues. **Kind:** Soft hold. - -An open issue whose GitHub dependency list names an open blocker is enumerated with `DependsOn` edges and kept out of the ACTIONABLE ISSUES an agent picks from; the kick names it once in a `Blocked by open dependencies` footer with its blockers. A blocker that is closed resolves the edge; a mutual pair (A↔B) is dropped with a warning so neither hides the other. The blocker list failing to load fails open (issue offered). - -**Who applies it:** Human (GitHub UI) or agent via `hive-open-issue --blocked-by` when splitting ordered children. - -**Checked by:** GitHub enumeration, kick-list assembly. **When:** Enumeration. - -**Release or override.** Close the blocker, or remove the dependency on GitHub - -**Configuration and implementation.** None (`src/pkg/github/issue_dependencies.go`, `src/pkg/scheduler/kickmessage.go` `partitionBlockedIssues`/`formatBlockedIssuesNote`) - -#### `blocked` - -**Applies to:** Issues. **Kind:** Hard suppress. - -The issue waits on an unmerged PR (or another outside blocker): the review backlog files a finding `blocked` when its evidence file exists only on the reviewed PR (absent on the base branch), and `hive-open-issue comment --blocked-on-pr ` parks an existing one; both write ``. A `blocked` issue is filtered (reason `blocked on owner/repo#N`), derives no stage label, is refused by every automated claim producer (`blocked: owner/repo#N`) including the contributor relay, and never carries `help wanted` ([#13093](https://github.com/hivecommons/hive/issues/13093)). - -When a blocked filing folds into an already-open twin, the twin's own state governs: `blocked` is not applied to it, because the folded body (and its marker) is discarded and the twin's earlier evidence stands on its own; the blocked sweep also lifts a hive-applied `blocked` that has no marker, no deadline and no ops-tracking marker, leaving a human-applied one alone ([#13364](https://github.com/hivecommons/hive/issues/13364)). With no blocked-on marker, a body deadline `` files it `blocked until ` and the activity monitor's blocked chip reads `re-check at ` ([#13310](https://github.com/hivecommons/hive/issues/13310)). - -With the marker, the activity monitor's pill reads `blocked on #N`, links the PR and carries its cached state (`blocked_on_pr` in `/api/stage-tracker`), and the hive's own removal of the label re-reads the issue live rather than waiting for the next enumeration ([#14952](https://github.com/hivecommons/hive/issues/14952)). It is also always skipped by contributor admission and shown in the default waiting band. - -**Who applies it:** Hive (reserved for agents; relay only). - -**Checked by:** Enumeration, stage derivation, claim gate, review backlog, blocked sweep. **When:** Review backlog filing; blocked-on comment relay. - -**Release or override.** The blocked sweep after each stage-label sync removes it, with one `` note, once the tracked PR is merged or closed, or once a recheck-after deadline passes (`deadline passed; re-triaging`) unless the body also carries ``. An ops-tracking issue on the hive's own project keeps `blocked` once its deadline passes and instead gets soak triage: the hub's `/api/hub/hives` (or, with no hub, the spoke's own `/api/version`) is probed for every `stable`-channel hive (fresh heartbeat, no restart loop, running the candidate `sha256:` digest or `v5 ` named in the body), ONE `` comment is posted, only the checklist lines that evidence proves are ticked, and `` is appended to the body so the sweep does not repeat ([#13311](https://github.com/hivecommons/hive/issues/13311)); a human may remove it at any time. - -The hard-suppress reconcile (#12002) can also lift a Hive-applied `blocked` after a referencing PR merges, but only when the newest label event was by the App bot; human-applied or re-applied labels are not lifted. It posts ``. - -**Configuration and implementation.** Fixed label (`src/pkg/github/issue_blocked.go`, `src/pkg/github/issue_recheck_soak.go`, `src/pkg/github/issue_stage_labels.go`, `src/pkg/github/issue_claim_gate.go`); contributor/dashboard controls: `hub.contribute_skip_labels`, dashboard bands (`src/pkg/config/config.go:4585-4685`, `src/docs/dashboard.md:105-140`) - -#### `needs-human` - -**Applies to:** Issues. **Kind:** Hard suppress. - -Issue is filtered, not held: no agent kick or contributor offer; task-list sweep adds it only when a merged PR carries the explicit `Refs #N (needs-human: )` marker (never on a held issue; remainder prose yields `hive/handoff` instead, [#12002](https://github.com/hivecommons/hive/issues/12002)), and the claim escalation gate adds it instead of a third no-progress claim by the same agent (`governor.claims.escalate_after_claims`, [#10527](https://github.com/hivecommons/hive/issues/10527)). The un-park sweep keeps a "What to reply" comment on every parked issue listing the commands. - -See [Maintainer commands](maintainer-commands.md). - -**Who applies it:** Hive or human. - -**Checked by:** Enumeration, task-list sweep, claim escalation gate and un-park sweep. **When:** Enumeration/task-list sweep/kick building. - -**Release or override.** A person can remove the label directly. On the ordinary issue un-park path, an eligible maintainer's `/hive approve` / `/hive decision ` clears `needs-human` **regardless of who applied it**, including a person or an unknown actor (`stageengine.DecisionLiftsNeedsHuman`). The command is the human answer the label requested. It also removes `stage/045-needs-decision` and retired park spellings (including an issue's pre-045 `stage/085-needs-decision`), adds `approved-direction`, and lets the engine derive 010 when no other gate remains. - -The maintainer must have write, maintain or admin repository permission. The label timeline attributes the reply; it does not veto an otherwise eligible command. Leaving `needs-human` behind would re-derive 045 and undo the un-park ([#13075](https://github.com/hivecommons/hive/issues/13075), seen on [#12984](https://github.com/hivecommons/hive/issues/12984)). Earlier provenance-sensitive descriptions ([#12680](https://github.com/hivecommons/hive/issues/12680), [#12681](https://github.com/hivecommons/hive/issues/12681)) do not describe this current command rule. - -**Keep or add `hold` if work must stay stopped after the decision.** These commands never remove it. Label-driven repositories use their separate configured approval/lifecycle policy: `unparkLabelDrivenCommand` removes only Hive-applied park labels, including `needs-human`; ordinary un-park commands do not bypass that route's ownership rules. - -Agents may ADD it through the relay `label` command when an owner's direction reserves the work for people (then `/unclaim`); they may never remove it (`src/pkg/github/issue_unpark_command.go`, `src/pkg/github/issue_request_label.go`) - -**Configuration and implementation.** Fixed label (`src/pkg/github/client.go:1798-1803`, `src/pkg/github/task_list_sweep.go:611-641`, `src/pkg/github/task_list_sweep.go:874-880`, `src/cmd/hive/claimescalation.go`) - -#### `needs-spec` from the clarity gate - -**Applies to:** Issues. **Kind:** Hard suppress. - -With the gate on (default off), a human-filed, unclaimed issue whose clarity score (goal, acceptance criteria, scope, detail, open choices) is under `runs.triage.clarity_gate.threshold` gets one `` comment with concise questions for its author and the `needs-spec` hard-suppress label instead of a claim; it derives `stage/045-needs-decision` and leaves the agent queue ([#13577](https://github.com/hivecommons/hive/issues/13577)). - -**Who applies it:** Hive. - -**Checked by:** Scheduler kick assembly (`runs.triage.clarity_gate`). **When:** Before kicks are built. - -**Release or override.** The issue author, or a non-hive commenter with write/maintain/admin, replies after the marker and the resume sweep removes the hive's own `needs-spec` and records the un-park so the issue re-derives `stage/010-actionable` ([#13588](https://github.com/hivecommons/hive/issues/13588)); a `needs-spec` a person added is never lifted by the sweep. Or remove `needs-spec` by hand. The marker keeps the gate from asking again - -**Configuration and implementation.** `runs.triage.clarity_gate` (`src/pkg/scheduler/clarity_gate.go`, `src/pkg/classify/clarity.go`, `src/pkg/github/clarity_gate_resume.go`) - -#### `stage/017-possible-existing` from the prior-art gate - -**Applies to:** Issues. **Kind:** Hard suppress. - -With the gate on (default on), an unclaimed feature / RFC / epic issue whose key terms match an existing knowledge bead, setting, merged PR, closed issue, doc or code identifier at `runs.triage.prior_art.threshold` (default 70) gets one `` comment quoting the findings and the `stage/017-possible-existing` label instead of a claim; hive-filed issues get a `` note and are never parked ([#13575](https://github.com/hivecommons/hive/issues/13575)). - -**Who applies it:** Hive. - -**Checked by:** Scheduler kick assembly (`runs.triage.prior_art`). **When:** Before kicks are built. - -**Release or override.** The author or a write+ commenter replies `/hive decision proceed — ` (label lifted, a *Scope vs existing* section appended to the body, re-derives 010) or `/hive decision exists` (closed `not_planned` with `already-exists`); a plain reply lifts the label too. A clanker-filed park with no reply is closed `already-exists` after `runs.triage.prior_art.bot_close_ttl` (default 72h); reopen to continue. A 017 a person added is never lifted by the sweep - -**Configuration and implementation.** `runs.triage.prior_art` (`src/pkg/priorart`, `src/pkg/scheduler/prior_art_gate.go`, `src/pkg/github/prior_art_gate_resume.go`) - -#### `hive/handoff` - -**Applies to:** Issues. **Kind:** Informational. - -Soft hand-off marker. When a merged PR's `Refs #N` remainder section says in prose that the rest needs a person or another lane ("needs a human", "fix lane", "quality lane", "production change", …) without the explicit `needs-human:` marker, the sweep adds this label and notes "handed off to the next lane" in its remainder comment instead of parking the issue. It is not a hold, suppress, or enumeration filter: the issue stays actionable, so the next lane can still claim it ([#12002](https://github.com/hivecommons/hive/issues/12002)). - -Not added when the same sweep is applying `needs-human`. - -**Who applies it:** Hive (task-list sweep). - -**Checked by:** Task-list sweep. **When:** Task-list sweep. - -**Release or override.** Human or the claiming lane removes it; Hive never removes it - -**Configuration and implementation.** Fixed label (`src/pkg/github/task_list_sweep.go:85`, `src/pkg/github/task_list_sweep.go:576-596`, `src/pkg/github/task_list_sweep.go:635-665`) - -#### `hive/advisory` - -**Applies to:** Issues. **Kind:** Hard exclusion. - -Hive advisory report is never actionable and never appears on the Hold list. - -**Who applies it:** Hive. - -**Checked by:** Standing meta classifier. **When:** Before holds/exempts. - -**Release or override.** Remove label, but exact advisory title still excludes - -**Configuration and implementation.** Fixed label/name (`src/pkg/github/standing_issues.go:1-57`, `src/pkg/github/client.go:1726-1744`) - -#### `triage/advisory` - -**Applies to:** Issues. **Kind:** Hard exclusion. - -Advisory-only dedupe checklist (`Decision required: no`, #11864) is never actionable and never appears on the Hold list; action-required checklists are parked with `needs-decision` instead. The close-on-merge backfill closes it once every `#N` it references is closed or merged, or after 7 days, and swaps it for `needs-decision` plus the "What to reply" notice if line two turns to `Decision required: yes` (#11871). - -**Who applies it:** Dedupe agent. - -**Checked by:** Standing meta classifier. **When:** Before holds/exempts. - -**Release or override.** Remove label - -**Configuration and implementation.** Fixed label/name (`src/pkg/github/standing_issues.go`) - -#### Human assignee - -**Applies to:** Issues. **Kind:** Non-label approval. - -Human assignee acknowledges hive-filed direction and moves issue into rank tier 2. - -**Who applies it:** Human. - -**Checked by:** #5117 gate and ranking. **When:** PR creation/ranking. - -**Release or override.** Unassign - -**Configuration and implementation.** N/A (`src/pkg/github/pr_self_authorization.go:180-226`, `src/pkg/github/client.go:4748-4777`) - -#### Human comment - -**Applies to:** Issues. **Kind:** Non-label approval. - -Any human comment in the first 100 issue comments acknowledges for #5117, but does not change ranking tier by itself. - -**Who applies it:** Human. - -**Checked by:** #5117 gate. **When:** PR creation. - -**Release or override.** N/A - -**Configuration and implementation.** `selfAuthCommentPageSize` (`src/pkg/github/pr_self_authorization.go:14-18`, `src/pkg/github/pr_self_authorization.go:180-226`) - -#### `needs-reporter-confirmation` - -**Applies to:** Issues. **Kind:** Hard suppress / human signal. - -Marks an issue whose opted-in fix appears to have landed but still needs the reporter or a maintainer to reply `/fixed`. The `CloseIssue` reporter-confirmation gate applies it only when `hive: needs-confirmation` or `issues.reporter_confirmation` requested the gate; if the reporter has write/maintain/admin access Hive also adds `needs-human` so the dashboard's human queue catches it. - -**Who applies it:** Hive App. - -**Checked by:** Issue-close gate, dashboard. **When:** Enumeration/dashboard. - -**Release or override.** `/fixed`, deliberate close, or `/reopen` removes this label. Hive does not remove `needs-human` here because it may have been set by another workflow. - -**Configuration and implementation.** Fixed label (`src/pkg/github/issue_close.go`, `src/scripts/issue-confirm-fixed.sh`) - -#### `hive: needs-confirmation` label/body text - -**Applies to:** Issues. **Kind:** Gate input. - -Opts one human-filed bug-family issue into reporter verification before closing. PR bodies keep `Closes`/`Fixes`; the close path leaves the issue open pending confirmation until `/fixed`, `hive: reporter-confirmed`, an override, or marker removal. - -**Who applies it:** Human/filer/operator. - -**Checked by:** Issue-close gate. **When:** `CloseIssue`. - -**Release or override.** Remove label/text or confirm fixed - -**Configuration and implementation.** Fixed phrase (`src/pkg/github/pr_request_claims.go`, `src/pkg/github/issue_close.go`) - -#### `hive: reporter-confirmed` label/body text - -**Applies to:** Issues. **Kind:** Permit. - -Legacy marker showing the reporter/maintainer verified the fix. Close-on-merge is now the default, so this is usually redundant; it still bypasses an active `hive: needs-confirmation` or `issues.reporter_confirmation` gate. - -**Who applies it:** Human/reporter. - -**Checked by:** Issue-close gate. **When:** `CloseIssue`, `/fixed` workflow. - -**Release or override.** Remove label/text - -**Configuration and implementation.** Fixed phrase (`src/pkg/github/pr_request_claims.go`, `src/pkg/github/issue_close.go`) - -#### `hive: close-on-merge` label/body text - -**Applies to:** Issues. **Kind:** Permit. - -Legacy filing-time marker for bugs whose merged fix is the verification. Close-on-merge is now the default, so this is usually redundant; it still bypasses an active reporter-confirmation config gate. `hive-open-issue --close-on-merge` still adds it for compatibility. - -**Who applies it:** Human/filer. - -**Checked by:** Issue-close gate. **When:** `CloseIssue`. - -**Release or override.** Remove label/text - -**Configuration and implementation.** Fixed phrase (`src/pkg/github/pr_request_claims.go`, `src/pkg/github/issue_close.go`) - -#### `design-approved` - -**Applies to:** Issues. **Kind:** Planning gate. - -Approves a requested architect design; counts after a design exists. - -**Who applies it:** Human. - -**Checked by:** Planning design gate. **When:** Planning label sweep. - -**Release or override.** Remove/re-apply design labels as needed - -**Configuration and implementation.** `planning.design_approved_label` (`src/pkg/planning/design.go:68-125`, `src/pkg/planning/design.go:320-345`) - -#### Lane-name label or `agent/` segment - -**Applies to:** Issues. **Kind:** Soft routing. - -Routes issue to a lane after title prefix and before keyword routing. Scanner sees every issue; other agents see their lane. - -**Who applies it:** Hive/human. - -**Checked by:** Classifier/scheduler. **When:** Classification before kicks. - -**Release or override.** Change/remove label - -**Configuration and implementation.** `agents.*.lane_keywords` (`src/pkg/classify/classifier.go:249-276`, `src/pkg/scheduler/templates.go:298-303`) - -#### `auto-qa`, `auto-qa-finding`, `kind/security`, `kind/regression` - -**Applies to:** Issues. **Kind:** Soft classification. - -`auto-qa`/`auto-qa-finding` make Simple; `kind/security`/`kind/regression` make Complex. - -**Who applies it:** Hive/human. - -**Checked by:** Classifier. **When:** Classification. - -**Release or override.** Remove label - -**Configuration and implementation.** Classifier tables (`src/pkg/classify/classifier.go:279-303`) - -#### `run/spec`, `run/fix` - -**Applies to:** Issues. **Kind:** Gate when enabled. - -Forces spec or direct-fix triage when runs triage is enabled. - -**Who applies it:** Human/Hive. - -**Checked by:** Runs triage. **When:** Triage. - -**Release or override.** Remove label - -**Configuration and implementation.** `runs.triage.enabled` (`src/pkg/classify/triage.go:1-55`) - -#### `runs.triage.spec_labels` / `fix_labels` (v6/edge Spek) - -**Applies to:** Issues. **Kind:** Gate when enabled. - -Configured exact labels route to spec or fix; mark this v6/edge when documenting Spek behavior. - -**Who applies it:** Operator/human. - -**Checked by:** Spek/runs triage. **When:** Triage. - -**Release or override.** Remove label/config - -**Configuration and implementation.** `runs.triage.spec_labels`, `runs.triage.fix_labels` (`src/pkg/classify/triage.go:35-55`) - -#### `tracker`, `meta-tracker`, `tracking`, `epic` (last segment) - -**Applies to:** Issues. **Kind:** Soft for agents; hard for contributors. - -Marks coordination-only/tracker issues; agents see tracker tags, contributors do not get them. - -**Who applies it:** Human/Hive. - -**Checked by:** Tracker detector, PR claim rewrite, contributor queue. **When:** Enumeration/contributor admission. - -**Release or override.** Remove label or close tracker - -**Configuration and implementation.** Tracker detector (`src/pkg/github/client.go:3634-3683`) - -#### `epic` (any case; `governor.claims.never_claim_labels`) - -**Applies to:** Issues. **Kind:** Hard for agent claims. - -Umbrella issue is never a unit of agent work: every automated claim producer (relay `claim`, start signal, contributor lane) is refused with `never-claim label: