From 201438682348bab09ffcf2c0c87f78f9519a3936 Mon Sep 17 00:00:00 2001 From: scanner Date: Tue, 6 Oct 2026 19:18:07 -0400 Subject: [PATCH 1/2] feat: publish Hive dashboard section help page Signed-off-by: scanner --- changelog.d/added-253-hive-dashboard-help-page.md | 3 +++ scripts/sync-hive-docs.ts | 4 ++++ src/app/docs/page-map.ts | 8 ++++++++ 3 files changed, 15 insertions(+) create mode 100644 changelog.d/added-253-hive-dashboard-help-page.md diff --git a/changelog.d/added-253-hive-dashboard-help-page.md b/changelog.d/added-253-hive-dashboard-help-page.md new file mode 100644 index 0000000..0393795 --- /dev/null +++ b/changelog.d/added-253-hive-dashboard-help-page.md @@ -0,0 +1,3 @@ +- Published the Hive dashboard section help page, the dashboard glossary and + the labels and control signals reference under a new "Dashboard" sidebar + group (hivecommons/docs#253). diff --git a/scripts/sync-hive-docs.ts b/scripts/sync-hive-docs.ts index 196a52e..5bfc82e 100644 --- a/scripts/sync-hive-docs.ts +++ b/scripts/sync-hive-docs.ts @@ -38,6 +38,10 @@ const files: Array<{ source: string; target?: string }> = [ { source: "security-model.md" }, { source: "securing-your-hive.md" }, { source: "troubleshooting.md" }, + // Dashboard section help pages (hivecommons/docs#253, hivecommons/hive#10915). + { source: "dashboard-sections.md" }, + { source: "dashboard-glossary.md" }, + { source: "labels-and-control-signals.md" }, { source: "backup-restore.md", target: "backup-dr.md" }, { source: "env-vars.md" }, // Third-party integration guide (hivecommons/hive#10171). diff --git a/src/app/docs/page-map.ts b/src/app/docs/page-map.ts index 468a552..652d645 100644 --- a/src/app/docs/page-map.ts +++ b/src/app/docs/page-map.ts @@ -128,6 +128,14 @@ const NAV_STRUCTURE_HIVE: Array<{ title: string; items: NavItem[] }> = [ { 'Running at ACMM Level 6': 'running-at-level-6.md' }, ] }, + { + title: 'Dashboard', + items: [ + { 'Dashboard sections explained': 'dashboard-sections.md' }, + { 'Dashboard glossary': 'dashboard-glossary.md' }, + { 'Labels and control signals': 'labels-and-control-signals.md' }, + ] + }, { title: 'Integrating with Hive', items: [ From be61fd37a5b5df452c01f771b2ca48f1afaeff5b Mon Sep 17 00:00:00 2001 From: scanner Date: Tue, 6 Oct 2026 19:29:21 -0400 Subject: [PATCH 2/2] fix: commit synced Dashboard section content so the nav _meta resolves The nav added a Dashboard group but the three synced pages were never committed under docs/content/hive, so the page map dropped the folder while still listing it in the top-level _meta (Validation of "_meta" file has failed in CI). Add the synced content produced by scripts/sync-hive-docs.ts. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: scanner --- docs/content/hive/dashboard-glossary.md | 43 ++ docs/content/hive/dashboard-sections.md | 591 ++++++++++++++++++ .../hive/labels-and-control-signals.md | 179 ++++++ 3 files changed, 813 insertions(+) create mode 100644 docs/content/hive/dashboard-glossary.md create mode 100644 docs/content/hive/dashboard-sections.md create mode 100644 docs/content/hive/labels-and-control-signals.md diff --git a/docs/content/hive/dashboard-glossary.md b/docs/content/hive/dashboard-glossary.md new file mode 100644 index 0000000..82f5667 --- /dev/null +++ b/docs/content/hive/dashboard-glossary.md @@ -0,0 +1,43 @@ +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/dashboard-glossary.md) during the docs build. Edit the canonical source in the Hive repository. + +# Dashboard glossary and sidebar IA + +This glossary records the operator-facing names used by the dashboard. The ADR-0018 IA/naming pass is implemented. + +For a plain-language explanation of every dashboard section β€” what it shows, how its numbers are worked out, and what to do about them β€” see [Dashboard sections explained](/docs/hive/dashboard-sections). Each section title's **?** mark opens its entry there. + +## Terms + +| Term | Meaning | Use in operator UI | +| --- | --- | --- | +| Agent | Runnable automation process or configured role that can plan, scan, review, or otherwise work on hive tasks. | Use for dashboard automation and agent detail pages. | +| Contributor | Human or GitHub account participating through the contributor portal. | Use for people/accounts, leaderboards, trust controls, and profile/admin copy. | +| Contributor agent (ClankeR) | A contributor's relay-backed worker. Use the full form on first or prominent mention, then Contributor agent for repeated inline mentions. | Use when the operator UI refers to the worker connected through the contributor relay. | +| Governor | Policy engine that decides cadence, autonomy, budgets, and merge/apply gates. | Use for the overview/governance surface and settings that control automation policy. | +| Fleet | The set of agents or contributor agents under observation in an operational context. | Use for aggregate operational controls and live monitoring. | +| Issue band | A display-only group in a repository card's issue column, named for the operator's action: Unclaimed, Claimed, Needs triage (agent-filed and not yet acknowledged by a human), Needs human, or Confirm & close. | Use for Projects card grouping; do not imply scheduler eligibility changed. Hover a band header, Overview slice, or legend row for its rule. | +| Pill legend | The collapsible Projects-section key explaining pill colours, borders, glyphs, and badges as a colour key plus captioned issue, pull-request, review, link, and action pills. The aligned repository-card rows keep the left chip for the issue band or PR review class and align actions in fixed slots. | Use for the compact legend above project cards. | +| PR band | A display-only group in a repository card's pull-request column: Needs human, Merge-eligible, Blocked, In review, Open, or Draft. | Use for Projects card grouping; do not imply merge queue, hold, or review eligibility changed. | +| Stale issue | An actionable repository-card issue whose `updated_at` activity is older than the configured `dashboard.issue_bands.stale_days` threshold. | Use for the `N no activity > Nd` counter and `πŸ•’` badge. | +| Stale PR | A repository-card PR whose `updated_at` activity is older than the configured `dashboard.issue_bands.stale_days` threshold. | Use for the PR `πŸ•’` badge. | + +Keep **ClankeR** only when naming the contributor relay product/brand, for example the contributor portal line β€œPowered by ClankeR.” Avoid casual lowercase `clanker` as an operator-facing noun. + +## Sidebar map + +The operator sidebar keeps the existing destinations, IDs, `data-action` handlers, and route hashes, but groups them by operator task: + +| Group | Items | +| --- | --- | +| Dashboard | Overview, Governor, Throughput | +| Agents | Dynamic agent tree, `+ Add agent`, `+ Group` | +| Resources | Projects, Contributors | +| Intelligence | Advisory, ACMM Eval, Inception, Knowledge, Strategy Lab | +| Admin | Tokens, Cost, Review Queue, Agents, Audit Log, Diagnostics | +| Help | FAQ, Getting Started, API Spec (Redoc), Getting Started Guide, Join our Discord, Report an Issue | + +On the v6 line the sidebar also lists Runs and Platform. Sections hidden by the ACMM level or a feature setting are hidden from the sidebar too. + +Count badges use the shared `.badge-count` recipe. Zero counts render as dimmed `0` badges with `data-zero`. + +Internal `clanker-*` CSS classes, DOM ids, data keys, and JavaScript names are stable compatibility identifiers. They are not user-facing names and should remain as-is. diff --git a/docs/content/hive/dashboard-sections.md b/docs/content/hive/dashboard-sections.md new file mode 100644 index 0000000..c098585 --- /dev/null +++ b/docs/content/hive/dashboard-sections.md @@ -0,0 +1,591 @@ +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/dashboard-sections.md) during the docs build. Edit the canonical source in the Hive repository. + +# Dashboard sections explained + +This page explains every section of the Hive dashboard in plain words. It is written for someone running Hive for the first time. + +Every section title on the dashboard has a small **?** mark next to it. Rest the pointer on it, or move to it with the Tab key, to see one sentence about the section. Click it, tap it, or press Enter on it to open this page at that section's entry. + +Each entry answers the same questions in the same order: + +1. What the section is. This is the same sentence the **?** mark shows. +2. What it tells you. +3. How its numbers and labels are worked out. +4. What it is good for: when to look at it, and what to do about it. +5. A short example. +6. When the section appears. +7. Which settings change it. + +Hive has two release lines. **v5** is the stable line. **v6** is the newer line. Where something exists on only one line, the entry says so. + +For short definitions of the names the dashboard uses, see the [dashboard glossary](/docs/hive/dashboard-glossary). For how the dashboard is built, see the [spoke dashboard guide](https://github.com/hivecommons/hive/blob/v5/src/docs/dashboard.md). + +## Words used on this page + +These words have a special meaning in Hive. Each entry explains them again the first time it uses them. + +- **Autonomy level:** how much Hive may do on its own, from L1 (watch only) to L6 (works and merges on its own). Hive calls this the ACMM level. +- **Tracked:** an issue or pull request that Hive has put on its work list after its filters ran. +- **Actionable:** a tracked item that Hive could work on now, because nothing is waiting on a person. +- **Held:** an item someone parked on purpose by adding a hold label, such as `hold` or `on-hold`. Hive leaves it alone. +- **Outside:** an open item that Hive's filters kept off its work list, for example because of a label. +- **Band:** a group the dashboard puts an issue or pull request in, named after what it needs next. Bands are for display only. +- **Needs-human:** waiting on a person, for example for a decision or a review. It is also the name of a label. +- **Merge-eligible:** a pull request that passed every check Hive uses before it may merge it. + +## Overview + +How many issues and pull requests Hive is tracking right now, and how many of them it can work on. + +**What it tells you.** The top row of tiles splits all your open work into a few piles. The two charts show the same work grouped by what it needs next. The small lines inside each tile show how the number moved over the last day or week. + +**How the numbers are worked out.** + +- **Total open issues** and **Total open PRs** count every open issue and every open pull request in the repositories you selected. Draft pull requests count too. +- Each total is written as a sum, for example `10 = 2 actionable + 0 held + 1 blocked + 7 outside`. +- **Actionable now** counts tracked items that Hive could work on now. Tracked means Hive put the item on its work list. Actionable means nothing is waiting on a person. +- Issues in the "Needs human" and "Confirm & close" bands are left out of Actionable now. A band is a display group named after what the item needs next. +- Pull requests in the "Needs human" and "Blocked" bands are left out, and so are drafts. +- **Held** counts issues and pull requests with a hold label. A hold label, such as `hold` or `on-hold`, parks an item on purpose. +- **Blocked / needs-human** counts work that waits on a person or on something else. For issues, that is the "Needs human" and "Confirm & close" bands. It also counts issues with a `needs-human` label and issues waiting for their reporter. For pull requests, it is the "Needs human" and "Blocked" bands. +- **Outside** counts open items that Hive's filters kept off its work list. Hover its β“˜ mark to see why each item was kept out. The reasons are labels such as `needs-direction`, `needs-decision` or `needs-spec`, and exempt labels. Others are reporter triage, your project issue filter, standing advisory issues and bot dependency dashboards. Draft pull requests count here too. +- The last part of Outside is **hold-adjacent/other**. It is whatever is left after every named reason is counted. Hive cannot say more about these items. +- The Outside tile exists on the v5 line only. On v6 the same items are part of the totals but have no tile of their own. +- **Issues by band** groups tracked and held issues. The bands are Unclaimed, Claimed, Needs triage, Needs human and Confirm & close. +- Unclaimed means nobody is assigned. Claimed means a person or a Hive worker took it. Needs triage means a Hive worker filed it and no person has approved it yet. +- Needs human means a label such as `blocked` or `needs-decision` asks a person to act. Confirm & close means a worker thinks the issue is already done. +- **PRs by band** groups open and held pull requests. The bands are Needs human, Merge-eligible, Blocked, In review, Open and Draft. +- Merge-eligible means the pull request passed every check Hive uses before merging. Blocked means a failed check, a merge conflict, or a blocking review verdict. +- Hover any band in a chart to see its exact rule. +- The trend lines come from samples the hive takes on each status refresh, roughly every few minutes. Samples are kept for about 30 days and thinned to 96 points. +- Your browser also keeps its own samples. When you filter by repository, only the browser's samples are used. + +**Numbers that look like they should match but do not.** + +- The band charts count more than Actionable now. The charts include items in "Needs human" and "Confirm & close". Actionable now leaves those out. So an issue chart can total 3 while Actionable now shows 2 issues. +- The "PRs by band" chart puts held pull requests in "Needs human". The tiles count the same pull requests as Held. So the chart can show 4 needing a human while the Blocked / needs-human tile shows 0 pull requests. + +**What it is good for.** Look here first each day. A growing Actionable now means Hive has work to do. A growing Blocked / needs-human means people are the bottleneck. Click a tile to filter the Projects section to the items it counts. Then add the missing decision, remove a stale label, or close finished issues. + +**Example.** The tile reads `10 = 2 actionable + 0 held + 1 blocked + 7 outside`. Hive can work on 2 issues. One waits on a person. Seven were kept out by your filters. Hover the β“˜ mark on Outside to see that 2 are bot dependency dashboards. Those are expected and need no action. + +**When it appears.** Always. The Overview section cannot be hidden. + +**Settings that change it.** + +- `dashboard.issue_bands.waiting_labels` and `dashboard.issue_bands.done_labels` decide which labels put issues in "Needs human" and "Confirm & close". +- `dashboard.issue_bands.stale_days` decides when an item counts as having had no activity for too long. +- `project.issue_filter.require_labels`, `project.issue_filter.hard_suppress_labels`, `project.issue_filter.reporter_trust` and `governor.labels.exempt` decide what counts as Outside. Change them in **Settings β†’ Labels**. +- The chart type and trend window are saved in your browser only. + +## Governor + +How busy Hive thinks your projects are right now, and how often it wakes its workers as a result. + +**What it tells you.** The Governor is the part of Hive that decides how often each worker runs. A worker is one of Hive's AI agents. This section shows the Governor's current mode, the work it is counting, its budget, and its schedule for each worker. + +**How the numbers are worked out.** + +- The **mode** is one of idle, quiet, busy or surge. Each mode runs workers more often than the one before it. +- The Governor picks a mode by comparing the amount of actionable work with three thresholds. Actionable work is work Hive could do now, with nothing waiting on a person. +- The **actionable issues** and **actionable PRs** tiles use the same count as the Overview's Actionable now tile. The two always agree. +- The **hold** list names every held item. Held means someone parked it with a hold label. +- The **cadence table** shows, for each worker, how often it runs in each mode. Continuous means it runs again as soon as it finishes. +- The **budget** shows how much of the AI spending allowance for the current period has been used. + +**What it is good for.** Check it when Hive seems too slow or too busy. If the mode stays idle while work piles up, check the thresholds. If one worker never runs, check its row in the cadence table. + +**Example.** The mode reads `busy` and the gauge shows 12 actionable items. The busy threshold is 10 and the surge threshold is 20. Hive will run its workers at the busy pace until the count drops below 10. + +**When it appears.** At autonomy level L2 and above. The autonomy level is how much Hive may do on its own, from L1 to L6. + +**Settings that change it.** + +- The βš™οΈ button opens the Governor settings: workers, thresholds, budget, notifications and health checks. +- The mode thresholds live in `governor.modes`. Choosing an autonomy level writes default thresholds there. +- The budget lives in `governor.budget`. + +## PRs by model + +Which AI models wrote the pull requests Hive opened, and how often each model's work was merged without extra fixes. + +**What it tells you.** This part of the Governor section compares the AI models your workers use. It shows how many pull requests each model wrote and how they ended. + +**How the numbers are worked out.** + +- Each row is one model. The bar splits its pull requests into merged, still open, and closed without merging. +- **First-pass rate** is the share of merged pull requests that needed no follow-up fixes. +- **Failure rate** and **nothing to ship** count runs that failed or finished without a pull request. +- A model gets a **rank** only after it has at least 5 merged pull requests in the window. With fewer, the sample is too small to compare. +- You can show the last 7 days, the last 30 days, or all time. You can sort by rank or by count. + +**What it is good for.** Use it when choosing which model a worker should use. A model with a low first-pass rate costs more review time. + +**Example.** Model A has 40 pull requests and a 70% first-pass rate. Model B has 6 pull requests and a 30% rate. Model A is the safer default. + +**When it appears.** Inside the Governor section, so at autonomy level L2 and above. + +**Settings that change it.** No settings change this section. The minimum sample of 5 merged pull requests comes from `HIVE_CONTRIBUTE_EFFECTIVE_MODELS_MIN_PRS`. + +## Advisory + +Reports, advice and suggestions Hive has written about your projects and about how it is running. + +**What it tells you.** This section groups five smaller sections: Advisory Digest, Hive Advice, Fleet Report Preview, Ready to level up? and Lifecycle Timeline. Each has its own entry below. + +**How the numbers are worked out.** This section has no numbers of its own. Its collapsed summary repeats a count from one of the sections inside it. + +**What it is good for.** Open it about once a week to read what Hive suggests. Collapse it when you do not need it. + +**Example.** The collapsed title reads `2 weekly advice items`. Open it and read Hive Advice first. + +**When it appears.** At autonomy level L2 and above. The autonomy level is how much Hive may do on its own, from L1 to L6. Some sections inside it hide themselves when they are empty. + +**Settings that change it.** Settings under `governor.advisory` change how often the findings are refreshed. + +## Advisory Digest + +The open findings Hive's workers have written down, such as bugs, ideas and advice, grouped by who wrote them. + +**What it tells you.** Hive's workers record what they notice as findings. A worker is one of Hive's AI agents. The digest lists every open finding of type advisory, bug or feature. + +**How the numbers are worked out.** + +- The total is the number of open findings. +- Each worker's count is the number of open findings it wrote. +- Internal notes, such as tasks and decisions, are left out on purpose. + +**What it is good for.** Read it to see problems your workers noticed but did not fix. Turn useful findings into issues, and close findings that no longer apply. + +**Example.** The digest shows 3 findings from the scanner. One says a test is flaky. You open an issue for it. + +**When it appears.** Inside Advisory, so at autonomy level L2 and above. When there are no findings it says so. + +**Settings that change it.** Settings under `governor.advisory` change how often findings are refreshed and when old ones are marked stale. See the [Advisory digest guide](https://github.com/hivecommons/hive/blob/v5/src/docs/advisory.md). + +## Hive Advice + +A short weekly list of things Hive recommends you do to keep work moving on your projects. + +**What it tells you.** Hive checks its own counters and your open work, then lists a few concrete steps. The list is frozen for a week so it does not change under you. The numbers inside it still refresh. + +**How the numbers are worked out.** + +- Some rules depend on the Governor's mode, such as "give idle workers a schedule". +- Other rules read the Overview's bands. A band is a display group named after what an item needs next. +- For example, Hive advises clearing blocked pull requests when they pass a set share of all open pull requests. +- Two count tiles show the Governor's count and the Overview chart's count. They can differ, because the chart includes items that wait on a person. + +**What it is good for.** Work through it once a week. Each recommendation lists the first few items it is about and links to the full list. + +**Example.** The advice says "41 of 70 blocked pull requests fail one check β€” fix the check first". Fixing that check unblocks most of them. + +**When it appears.** Inside Advisory, so at autonomy level L2 and above. It is hidden when there is nothing to recommend. + +**Settings that change it.** The thresholds under `governor.advisory` change when each rule fires. See [Owner advice](https://github.com/hivecommons/hive/blob/v5/src/docs/advisory.md#owner-advice). + +## Fleet Report Preview + +Problems Hive has noticed in itself that it would report to the Hive maintainers, and problems that have since gone away. + +**What it tells you.** Hive can report its own faults to the people who build Hive. This section shows what it would report, and which earlier problems have cleared. + +**How the numbers are worked out.** + +- Each report row names the problem, how serious it is, and how often it happened. +- A recovered row means the problem stopped. It carries no details. +- The badge says "dry-run preview" when Hive is only showing reports, not sending them. + +**What it is good for.** Read it before you allow Hive to send reports, so you know exactly what would leave your hive. + +**Example.** One row says a check failed 5 times in an hour. A day later it shows as recovered. + +**When it appears.** Inside Advisory, so at autonomy level L2 and above. It is hidden when there are no reports and no recoveries. + +**Settings that change it.** `governor.fleet_report.file_upstream` decides whether reports are sent. The default, `false`, only previews them. See [Fleet self-reporting](https://github.com/hivecommons/hive/blob/v5/src/docs/fleet-report.md). + +## Ready to level up? + +Whether Hive thinks you could safely let it do more on its own, and what still has to be true first. + +**What it tells you.** Hive's autonomy level is how much it may do on its own, from L1 (watch only) to L6 (works and merges on its own). Hive calls it the ACMM level. This section says whether to move up a level or stay. + +**How the numbers are worked out.** + +- Hive compares live signals, such as how often its pull requests merge cleanly, with the conditions for the next level. +- Met conditions get a tick. Unmet conditions say what is missing. +- Each repository can show its own suggested level. You can pin a repository so it keeps its level. + +**What it is good for.** Check it when you are thinking about giving Hive more freedom. Fix the unmet conditions first. + +**Example.** It says "stay at L4" because only 60% of pull requests merged without rework. The next level needs 80%. + +**When it appears.** Inside Advisory, so at autonomy level L2 and above. It is hidden when there is no recommendation yet. + +**Settings that change it.** The current autonomy level and the per-repository pins change it. See the [level-up advisor guide](https://github.com/hivecommons/hive/blob/v5/src/docs/acmm-advisor.md). + +## Lifecycle Timeline + +A timeline of recent pull requests, from when they were opened to when they were merged or got stuck. + +**What it tells you.** Each row follows one piece of work through its steps. The tiles above count how many are in flight, merged or blocked. + +**How the numbers are worked out.** + +- **In flight** counts pull requests still moving. **Merged** counts those that landed. **Blocked** counts those that stopped. +- The section shows up to 50 rows at first. Use "Expand more" to see older rows. +- Rows with no events are left out. + +**What it is good for.** Use it to see where work gets stuck. A long gap before review means reviews are slow. + +**Example.** A row shows a pull request opened 3 hours ago, reviewed after 2 hours, and still waiting for checks. + +**When it appears.** Inside Advisory, so at autonomy level L2 and above. With no recent events it says so instead of hiding. + +**Settings that change it.** No settings change this section. + +## Throughput + +How many pull requests were opened, merged and closed over a chosen time window, and who did the work. + +**What it tells you.** It shows the flow of pull requests and issues through your projects. It splits the work between Hive, people and other bots. + +**How the numbers are worked out.** + +- **Opened** counts pull requests Hive's workers created. **Merged** counts pull requests seen merging. **Closed** counts pull requests closed without merging. +- **Time to merge** shows the middle value and the slowest 10% of merges. +- **Hive vs human** is Hive's share of the work, leaving out work with no known author. +- The default window is 24 hours. You can choose from 1 hour up to all time, and filter by repository. + +**What it is good for.** Watch it over a week. If merged stays well below opened, work is piling up in review. + +**Example.** In 24 hours, 12 pull requests opened and 9 merged. The median time to merge is 2 hours. Review is keeping up. + +**When it appears.** Always. On v5 and v6 it is a top-level section of its own. + +**Settings that change it.** The window, repository and role controls are in the section. How far back data goes depends on how long the audit log keeps events. See [Throughput](https://github.com/hivecommons/hive/blob/v5/src/docs/dashboard.md#throughput). + +## Tokens + +How much text the AI models read and wrote for Hive recently, broken down by model and by worker. + +**What it tells you.** AI models are billed by tokens, which are small pieces of text. This section shows how many tokens Hive used and who used them. + +**How the numbers are worked out.** + +- The section adds up tokens from every recorded session in the window, which is 24 hours by default. +- It splits them into input, output and cached tokens, and by model and worker. +- The burn rate is tokens per hour. + +**What it is good for.** Look here when costs jump. A worker with a much higher burn than the others may be stuck in a loop. + +**Example.** The section shows 2 million tokens in 24 hours, and one worker used half of them. You check that worker's recent runs. + +**When it appears.** At autonomy level L3 and above. The autonomy level is how much Hive may do on its own, from L1 to L6. + +**Settings that change it.** No settings change this section. Which models and providers you configure changes what it can record. See [Token tracking](https://github.com/hivecommons/hive/blob/v5/src/docs/token-tracking.md). + +## Cost + +An estimate of what Hive's use of AI models has cost so far, based on public list prices. + +**What it tells you.** It turns token counts into money, so you can see what Hive costs. + +**How the numbers are worked out.** + +- Cost is tokens multiplied by each model's public list price. The badge "est." is a reminder that it is an estimate. +- If you pay a flat subscription, your real bill may differ. +- **Cost per merged PR** and **cost per closed issue** divide the estimate by how many were merged or closed. With none, they show a dash. +- When your AI gateway reports its own spending, that figure appears too. + +**What it is good for.** Use it to judge whether Hive is worth its cost. Compare cost per merged pull request over time. + +**Example.** The estimate is $40 this month for 80 merged pull requests, so about $0.50 each. + +**When it appears.** Always. + +**Settings that change it.** The models you configure and their prices change it. Gateway credentials add the gateway's own spending. See [Token tracking](https://github.com/hivecommons/hive/blob/v5/src/docs/token-tracking.md). + +## Projects + +One card per repository Hive looks after, listing its open issues and pull requests grouped by what each one needs next. + +**What it tells you.** Each card is one repository. Its issues and pull requests are sorted into bands. A band is a display group named after what the item needs next. + +**How the numbers are worked out.** + +- The cards use the same bands as the Overview charts. See the Overview entry for each band's meaning. +- Small pills on each item show signals, such as a hold, a failing check or no recent activity. +- The **needs-human** count in the header counts open pull requests that need a person to review or decide. Needs-human means waiting on a person. + +**What it is good for.** Use it to act on single items. Open the legend above the cards to learn what each pill means. + +**Example.** A card shows 3 issues under "Confirm & close". You check each one, and close those whose fix has landed. + +**When it appears.** At autonomy level L2 and above. The autonomy level is how much Hive may do on its own, from L1 to L6. + +**Settings that change it.** + +- The repositories Hive watches are set in **Settings β†’ Projects**. +- The `dashboard.issue_bands` settings change the band rules. +- See [Repository card legend, issue bands, and PR bands](https://github.com/hivecommons/hive/blob/v5/src/docs/dashboard.md#repository-card-legend-issue-bands-and-pr-bands). + +## ACMM Eval + +How ready your repositories are for Hive to work on them alone, scored against a published checklist. + +**What it tells you.** ACMM is the checklist Hive uses to decide how much it may do on its own. This is called the autonomy level, from L1 to L6. This section scores your repositories against that checklist. + +**How the numbers are worked out.** + +- **Codebase Readiness** scores the repositories themselves, such as tests and documentation. +- **Operational Autonomy** scores how Hive is running. +- **Overall ACMM** is the level both scores support. **Criteria Passed** counts the checks that pass. +- With several repositories, a criterion passes if any repository passes it. +- A waived criterion is marked as waived, not as failed. + +**What it is good for.** Use it to find what stops you reaching a higher level. Click **Open Issue** on a failed criterion to file the work. + +**Example.** Overall shows L3 because "has a contributing guide" fails. You add the guide and click **Re-evaluate**. + +**When it appears.** Always. + +**Settings that change it.** + +- The level you choose with **Change level** changes the target. +- Waivers in a repository's `.acmm.yml` file mark criteria as waived. +- `governor.acmm.issue_tracker` decides where **Open Issue** files. +- See the [ACMM policy matrix](/docs/hive/acmm-policy-matrix). + +## Approvals + +Actions Hive wants to take that are waiting for you to approve or reject them. + +**What it tells you.** Some actions need a person's yes before Hive does them. This section lists them. + +**How the numbers are worked out.** The badge counts pending approvals. Each row is one request. Select rows, then choose **Approve selected** or **Reject selected**. + +**What it is good for.** Check it whenever the badge shows a number. Hive waits until you decide. + +**Example.** Hive asks to merge a pull request in a protected repository. You read it and approve it. + +**When it appears.** Only when the approval desk is turned on. Only owners can read and decide approvals. + +**Settings that change it.** `tool_approval.enabled` turns the section on. The rules under `tool_approval` decide which actions need approval. + +## Audit Log + +A searchable record of everything Hive has done, newest first. + +**What it tells you.** Every action Hive takes is written to the audit log. This section lets you read and search it. + +**How the numbers are worked out.** + +- The collapsed summary counts today's events. +- The search box matches any of the words you type. Wrap text in slashes, like `/merge.*failed/`, to search with a pattern. +- The match count shows how many events match. + +**What it is good for.** Use it to answer "what did Hive do, and when?". Save searches you use often with **Save**. + +**Example.** You search `merged` and see that Hive merged 4 pull requests this morning. + +**When it appears.** Always. People without enough access see an error instead of events. + +**Settings that change it.** How long events are kept depends on the audit log settings. See the [Audit log guide](https://github.com/hivecommons/hive/blob/v5/src/docs/audit-log.md). + +## Review Queue + +Every open pull request in your projects, in the order Hive suggests reviewing them, with the reasons for each position. + +**What it tells you.** It ranks open pull requests from all your repositories in one list, whoever wrote them. + +**How the numbers are worked out.** Hive scores each pull request by its review priority and history, then sorts them. The header shows how many are in the queue. The order is the same every time for the same data. + +**What it is good for.** Review from the top when you have time. The reasons tell you why an item is high. + +**Example.** The first pull request is small, its checks pass and it has waited 3 days. It is quick to review. + +**When it appears.** Always. It is empty when there are no open pull requests. + +**Settings that change it.** The review settings in **Settings** change the ranking rules. See [Review queue triage](https://github.com/hivecommons/hive/blob/v5/src/docs/review-queue-triage.md). + +## Strategy Lab + +An experimental planner that tries out changes to how Hive works and records what it learned. + +**What it tells you.** The Strategy Lab runs small experiments on Hive's own settings. It shows its goals, its plan and a ledger of results. + +**How the numbers are worked out.** The ledger lists each experiment and its result. The section has no other numbers. + +**What it is good for.** Try it only if you want Hive to tune itself. You approve or stop each experiment. + +**Example.** The lab proposes a faster schedule for one worker for a day. You approve it, and the ledger records the result. + +**When it appears.** Only when the Strategy Lab setting is on and the autonomy level is L4 or above. The autonomy level is how much Hive may do on its own, from L1 to L6. + +**Settings that change it.** `dashboard.strategy_lab: true` turns it on. See [Strategy Lab](https://github.com/hivecommons/hive/blob/v5/src/docs/strategy-lab.md). + +## Inception + +A step-by-step guide that turns a new project idea into a first set of files and planned work. + +**What it tells you.** It walks you through describing a project. Hive asks questions, proposes a structure and creates the first files. + +**How the numbers are worked out.** This section has no numbers. + +**What it is good for.** Use it when starting a new project with Hive. Answer its questions, review the plan, then approve it. + +**Example.** You describe a small web service. Inception asks two questions and then proposes a folder layout and five starter issues. + +**When it appears.** Always. + +**Settings that change it.** No settings change this section. See [Inception](https://github.com/hivecommons/hive/blob/v5/src/docs/inception.md). + +## Knowledge + +The facts Hive has learned about your projects, where they came from, and how much Hive trusts each one. + +**What it tells you.** Hive's workers keep notes about your projects as facts. This section lets you search, add, edit and remove them. + +**How the numbers are worked out.** + +- The summary counts all stored facts. +- Each fact has a confidence score. It rises when the fact is confirmed again and falls with time. +- Layers show where facts come from, such as one project or a shared source. + +**What it is good for.** Check it when a worker keeps making the same mistake. Correct the wrong fact here. + +**Example.** A fact says tests run with `make test`, but your project uses `go test`. You edit the fact. + +**When it appears.** Always. + +**Settings that change it.** Knowledge sources, shared sources and imports are managed inside the section. See the [knowledge curator guide](https://github.com/hivecommons/hive/blob/v5/src/docs/knowledge-curator.md). + +## Contributors + +The people who lend their computers or AI helpers to your projects, and how far Hive trusts each of them. + +**What it tells you.** A contributor is a person who signed up to help. Some connect their own AI worker. This section lists them and their trust level. + +**How the numbers are worked out.** The summary shows active contributors and all registered contributors. Active means seen recently. + +**What it is good for.** Use it to give trusted people more access, or remove access. Share the `/contribute` link to invite people. + +**Example.** A contributor has fixed 10 issues cleanly. You raise their trust so they can take bigger tasks. + +**When it appears.** At autonomy level L2 and above. The autonomy level is how much Hive may do on its own, from L1 to L6. + +**Settings that change it.** Trust and roles are changed on each contributor card. See [Contributor trust and roles](https://github.com/hivecommons/hive/blob/v5/src/docs/contributor-trust-and-roles.md). + +## Diagnostics + +Health checks for Hive itself, such as its connections, credentials and safety switches, to help you find out why something is not working. + +**What it tells you.** Each tile checks one part of Hive. Examples are the code hosting connection, AI provider logins and safety switches that stop work after repeated failures. + +**How the numbers are worked out.** + +- Each tile reads the latest health data from the hive. +- A red or amber tile explains what failed and what to try. +- On v5, a **Platform** tile shows which code hosting service is connected and which optional services are on. On v6 this is its own section. +- **Quality stats** come from the checks your quality worker is set up to run. + +**What it is good for.** Open it when something stops working. Fix the first red tile first. + +**Example.** A tile says the AI provider login expired. You log in again from the worker's card. + +**When it appears.** At autonomy level L3 and above. The autonomy level is how much Hive may do on its own, from L1 to L6. + +**Settings that change it.** Provider credentials, code hosting settings and the quality worker's stats change the tiles. See [Dashboard route and health checks](https://github.com/hivecommons/hive/blob/v5/src/docs/health-checks.md). + +## Agent Logs + +The raw text output of each worker, for following what it is doing line by line. + +**What it tells you.** It would show a worker's output as it runs. A worker is one of Hive's AI agents. + +**How the numbers are worked out.** This section has no numbers. + +**What it is good for.** Today you cannot open it. Use the terminal or log links on each card in the Agents section instead. + +**Example.** To read the scanner's output, open its card in Agents and choose its log link. + +**When it appears.** Never, on both v5 and v6. The dashboard always hides it. + +**Settings that change it.** No settings change this section. See [Agent logging](https://github.com/hivecommons/hive/blob/v5/src/docs/agent-logging.md). + +## Agents + +Each worker Hive runs, what it is doing now, and buttons to pause, restart or configure it. + +**What it tells you.** A worker is one of Hive's AI agents. Each card shows a worker's state, model, schedule and repositories. + +**How the numbers are worked out.** + +- The header counts running workers and all workers. +- A worker's state comes from the hive, for example running, idle, paused or needs login. +- A worker outside your autonomy level's usual set still shows when it is running or turned on. + +**What it is good for.** Use it to pause a worker, restart a stuck one, or change its settings. Fix any card that says it needs a login. + +**Example.** A card says "needs login". You click **Login** and sign in again. + +**When it appears.** Always. + +**Settings that change it.** Each card's βš™οΈ button opens its settings: schedule, model, tools and permissions. See [Agent configuration](/docs/hive/agent-configuration). + +## FAQ + +Short answers to the questions people most often ask when they start using Hive. + +**What it tells you.** It answers common questions about levels, advice, contributors, cost and where to get help. + +**How the numbers are worked out.** This section has no numbers. + +**What it is good for.** Read it in your first week. Each answer links to a fuller guide. + +**Example.** You wonder why Hive does not merge anything. The FAQ explains that merging starts at a higher level. + +**When it appears.** Always, at every level. + +**Settings that change it.** No settings change this section. + +## Runs + +Longer pieces of work Hive is carrying out in stages, and which ones are waiting for you. + +This section exists on the v6 line only. + +**What it tells you.** A run is one larger task that moves through stages, such as spec, plan and implement. Each card shows a run's stage and who it is waiting on. + +**How the numbers are worked out.** + +- The header counts active runs, runs blocked on a person, and recently finished runs. +- A run is finished when it has an outcome or waits on nobody. +- Owners can approve a run's next step from its card. + +**What it is good for.** Check it for runs blocked on a person. Answer their questions or approve the next stage. + +**Example.** The header reads `2 active Β· 1 blocked on human`. One run waits for you to approve its plan. + +**When it appears.** On v6 only, always. + +**Settings that change it.** Which workers can take staged work changes what appears. See [Runs](https://github.com/hivecommons/hive/blob/v5/src/docs/runs.md). + +## Platform + +Which code hosting service Hive is connected to and which optional platform services are switched on. + +This section exists on the v6 line only. On v5 the same facts are in the Diagnostics section. + +**What it tells you.** It shows the code hosting service, such as GitHub, GitLab or Gitea, and how many repositories Hive watches. It also shows whether optional services, such as the token minting service, are on. + +**How the numbers are worked out.** The repository count is the number of repositories Hive watches. The other tiles show on or off. + +**What it is good for.** Check it after setup to confirm Hive is connected where you expect. + +**Example.** It shows `GitHub Β· 3 repos` and "Mint on". Hive watches three GitHub repositories and the token service runs. + +**When it appears.** On v6 only, when the hive reports platform data. + +**Settings that change it.** Your code hosting settings and optional service settings change it. diff --git a/docs/content/hive/labels-and-control-signals.md b/docs/content/hive/labels-and-control-signals.md new file mode 100644 index 0000000..fa24d50 --- /dev/null +++ b/docs/content/hive/labels-and-control-signals.md @@ -0,0 +1,179 @@ +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/labels-and-control-signals.md) during the docs build. Edit the canonical source in the Hive repository. + +# Hive Labels and Control Signals + +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. + +## How labels reach agents + +Most hard gates run before an agent sees work. GitHub issue enumeration reads labels in this order: standing meta issues are excluded first, then hold labels move the item to the Hold list, then exempt labels and the issue-level hard-suppress labels (`needs-human`, `needs-direction`, `needs-decision`, `needs-spec`; `hardSuppressIssueLabels` in `src/pkg/github/labels.go`) filter it out, so no agent kick names, and no kick claims, a parked issue, then `project.issue_filter.require_labels` admits or rejects the issue, and only then is it actionable (`src/pkg/github/client.go:955-1045`). Pull requests use the same hold-first enumeration for the PR Hold list (`src/pkg/github/client.go:1110-1165`). That means kick prompts, dashboard actionable counts, planning-from-label, and contributor offers normally inherit the same gate. + +Some sweeps bypass that enumeration and list items themselves, but every one of them gates on the same hold predicate as enumeration (`Client.IsHeldLabels` / `Client.isHeld`, `src/pkg/github/client.go:1964-1972`, `src/pkg/github/client.go:2674-2676`), so the generic hold substrings and the exact dashboard `hive-pause/` label hold everywhere: + +- Auto-merge sweeps reach it through the `Transport.IsHeldLabels` seam; both the queued (`lgtm`) and the self-authored sweep skip a held PR before fetching it (`src/pkg/github/automerge/automerge_sweep.go:23-38`, `src/pkg/github/automerge/automerge_sweep.go:959-964`, `src/pkg/github/automerge/automerge_sweep.go:966-1004`, `src/pkg/github/automerge/automerge_sweep.go:1029-1046`). +- The task-list sweep skips a held issue before its exempt / issue `needs-human` gate, so a held issue is never commented on, relabelled, or closed by it (`src/pkg/github/task_list_sweep.go:797-815`). +- The SHA-hold sweep lists primary-repo `kind/bug` issues itself, adds literal `hold` plus a marker notice when no SHA is present, and removes `hold` only when the current hold is its own: the newest `hold` label event is a `labeled` by the App bot and an App-authored SHA-hold notice was posted at or after it (`src/pkg/github/client.go:2467-2532`, `src/pkg/github/client.go:2582-2604`). +- PR-request watching applies server-side PR holds after a PR is opened; the agent's `--label hold` flag is deliberately discarded by the wrapper (`src/pkg/github/pr_request_watcher.go:452-524`, `bin/hive-open-pr.sh:142-150`). + +The "respect hold labels" text in policy templates names the enforced set (`hold`, `on-hold`, `hold/review`, `hive-pause/`, any label containing `hold`, plus `do-not-merge` as exempt) but is a prompt-level backstop. The hard gate is the enumerator or sweep named in the table. + +## 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 + +| Label or signal | Applies to | Consumer | Effect | Gate or signal | Who applies | When checked | Cleared / overridden | Config knobs | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| `hold`, `on-hold`, `hold/review` | Issues, PRs | GitHub enumeration, auto-merge sweeps, task-list sweep | 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. | Hard hold | Human, Hive level gate, #5117 gate, holdguard, SHA-hold | Enumeration and sweeps | Remove the matching label; Hive releases only literal `hold` it applied itself (level gate, #5117, SHA-hold) | Built-in `HoldLabels`; dashboard exact hold via `Client.SetHoldLabels` (`src/pkg/github/client.go:750-755`, `src/pkg/github/client.go:1894-1972`, `src/pkg/scheduler/policy_overlays.go:210-220`) | +| `hive-pause/` | Issues, PRs | GitHub enumeration, dashboard hold toggle, auto-merge sweeps, task-list sweep | Exact, hive-scoped dashboard hold. It is not provenance and intentionally avoids the substring `hold`. | Hard hold | Dashboard operator | Enumeration and sweeps | Dashboard Release removes labels causing the hold, including this one | Canonicalized from hive id (`src/pkg/github/client.go:1898-1932`, `src/pkg/github/client.go:1936-1945`, `src/docs/dashboard.md:80-96`) | +| GitHub "blocked by" dependency | Issues | GitHub enumeration, kick-list assembly | 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). | Soft hold | Human (GitHub UI) or agent via `hive-open-issue --blocked-by` when splitting ordered children | Enumeration | Close the blocker, or remove the dependency on GitHub | None (`src/pkg/github/issue_dependencies.go`, `src/pkg/scheduler/kickmessage.go` `partitionBlockedIssues`/`formatBlockedIssuesNote`) | +| `hive/` | Issues | Provenance/migration fallback only | Marks hive provenance. It is no longer a hold label except a temporary failed-migration fallback during upgrade. | Informational | Hive | Display/migration | Remove if unwanted; do not use as a hold | Hive id (`src/pkg/github/client.go:1947-1953`) | +| `hold` from ACMM level gate | PRs | PR-request watcher, self-authored auto-merge release | Non-outreach agent PRs at L3-L5 get literal `hold`; `outreach` PRs are held at every level. The watcher, not the policy prompt, applies it. | 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 Fully 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`) | +| `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. | Hard merge gate | Hive | Governor holdguard pass | Human removes the re-applied hold | Built-in `holdguard.ReHoldLabel` (`src/pkg/holdguard/holdguard.go:1-43`) | +| `hold` from SHA-hold | Issues | SHA-hold sweep | 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. | Hard issue hold | Hive | Eval tick SHA sweep | Add SHA evidence; sweep removes its own `hold`, a human removes any other | Primary repo and SHA-hold config (`src/pkg/github/client.go:2467-2532`, `src/pkg/github/client.go:2582-2604`) | +| `do-not-merge` and `do-not-merge*` | Issues, PRs | Exempt filter, merge sweeps, task-list sweep | Permanently exempt; exact match is case-insensitive but prefix matching follows Go `strings.HasPrefix` on the original label. | Hard suppress | Human | Enumeration/sweeps | Human removes | Built-in `PermanentExemptLabels` (`src/pkg/github/client.go:750-755`, `src/pkg/github/client.go:2030-2048`) | +| `governor.labels.exempt` entries | Issues, PRs | Exempt filter | Same exempt behavior as `do-not-merge`; wins over required-label admission. Defaults include `nightly-tests`, `LFX`, `meta-tracker`, `auto-qa-tuning-report`, `adopters`, `changes-requested`, `waiting-on-author`. | Hard suppress | Operator/dashboard | Enumeration/sweeps | Remove label or config entry | `governor.labels.exempt` (`src/pkg/config/config.go:3388-3396`, `src/pkg/config/config.go:5800-5808`) | +| `needs-human` | Issues | Enumeration, task-list sweep, claim escalation gate and un-park sweep | Issue is filtered, not held: no agent kick or contributor offer; task-list sweep can add it when a merged PR leaves human remainder work (never on a held issue), 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](https://github.com/hivecommons/hive/blob/v5/src/docs/maintainer-commands.md). | Hard suppress | Hive or human | Enumeration/task-list sweep/kick building | Human removes, or a maintainer with write/maintain/admin access replies `/hive approve` or `/hive decision ` on the issue, which also adds `approved-direction` and never touches `hold` (`src/pkg/github/issue_unpark_command.go`) | Fixed label (`src/pkg/github/client.go:1008-1024`, `src/pkg/github/task_list_sweep.go:611-641`, `src/pkg/github/task_list_sweep.go:797-815`, `src/cmd/hive/claimescalation.go`) | +| `needs-human` | PRs | Escalation ledger and reviewer lane | Applied when red-CI fix budget is exhausted; stops automated fix dispatch and sends the PR to the human/reviewer lane. It is not a PR enumeration filter. | Hard fix-dispatch gate | Hive | Escalation pass/kick building | Human removes after root cause or reviewer un-escalates; budget resets after grace | Fixed label (`src/pkg/escalation/escalation.go:400-470`, `src/pkg/escalation/escalation.go:1185-1205`) | +| `hive/advisory` | Issues | Standing meta classifier | Hive advisory report is never actionable and never appears on the Hold list. | Hard exclusion | Hive | Before holds/exempts | Remove label, but exact advisory title still excludes | Fixed label/name (`src/pkg/github/standing_issues.go:1-57`, `src/pkg/github/client.go:983-1001`) | +| `approved-direction` | Agent-filed issues | #5117 gate, ranking, kick tag | A PR opened after the label is present avoids #5117 hold; the issue ranks ahead of unacknowledged hive-filed backlog. | Gate input + soft ranking | Human | PR creation and issue ranking | Remove label; human assignee/comment can still acknowledge for #5117 | Fixed `HumanAckLabel` (`src/pkg/github/pr_self_authorization.go:14-226`, `src/pkg/github/client.go:2740-2832`) | +| Human assignee | Issues | #5117 gate and ranking | Human assignee acknowledges hive-filed direction and moves issue into rank tier 2. | Non-label approval | Human | PR creation/ranking | Unassign | N/A (`src/pkg/github/pr_self_authorization.go:180-226`, `src/pkg/github/client.go:2784-2832`) | +| Relay-linked parent | Hive-filed issues the relay split out of a parent | #5117 gate, ranking, kick tag | A child the issue-request relay itself linked as a GitHub sub-issue inherits acknowledgement from an **open, unheld** parent that is human-filed or carries `approved-direction`/a human assignee; one level only, and only for links the relay made (recorded in `/data/split-parents.json`), never for sub-issue links added later in the UI. The kick line shows `[hive-filed+parent-ack #N]`. | Non-label approval | Hive (from the parent's human signal) | Enumeration and PR creation | `hold` the child, or close/hold the parent | Fixed ledger (`src/pkg/github/split_parents.go`) | +| Human comment | Issues | #5117 gate | Any human comment in the first 100 issue comments acknowledges for #5117, but does not change ranking tier by itself. | Non-label approval | Human | PR creation | N/A | `selfAuthCommentPageSize` (`src/pkg/github/pr_self_authorization.go:14-18`, `src/pkg/github/pr_self_authorization.go:180-226`) | +| `needs-reporter-confirmation` | Issues | Issue-close gate, post-merge refs sweep, dashboard | Marks an issue whose fix appears to have landed but still needs the reporter or a maintainer to reply `/fixed`. The `CloseIssue` reporter-confirmation gate and the `hive-post-merge-refs-sweep` prompt apply it; if the reporter has write/maintain/admin access Hive also adds `needs-human` so the dashboard's human queue catches it. | Hard suppress / human signal | Hive App | Enumeration/dashboard | `/fixed`, deliberate close, or `/reopen` removes this label. Hive does not remove `needs-human` here because it may have been set by another workflow. | Fixed label (`src/pkg/github/issue_close.go`, `src/scripts/comment-merged-refs.sh`, `src/scripts/issue-confirm-fixed.sh`) | +| `hive: reporter-confirmed` label/body text | Issues | Issue-close gate | Allows the reporter-confirmation close gate to close a human-filed bug after the fix is verified. PR bodies keep `Closes`/`Fixes`; the close path decides whether to leave the issue open pending confirmation. | Permit | Human/reporter | `CloseIssue` | Remove label/text | Fixed phrase (`src/pkg/github/pr_request_claims.go:266-410`, `src/pkg/github/issue_close.go:26-28`) | +| `hive: close-on-merge` label/body text | Issues | Issue-close gate | Filing-time opt-in for a human-filed bug whose merged fix is the verification (code-sweep findings, timing/failure-path/fleet-only bugs the reporter cannot reproduce): the close path accepts the merge immediately. Without it (or `hive: reporter-confirmed`) a human-filed bug can still carry `Closes #N`/`Fixes #N`, but Hive leaves it open pending reporter confirmation. `hive-open-issue --close-on-merge` adds it to the body. | Permit | Human/filer | `CloseIssue` | Remove label/text | Fixed phrase (`src/pkg/github/pr_request_claims.go:268-410`, `src/pkg/github/issue_close.go:26-28`) | +| `design-approved` | Issues | Planning design gate | Approves a requested architect design; counts after a design exists. | Planning gate | Human | Planning label sweep | Remove/re-apply design labels as needed | `planning.design_approved_label` (`src/pkg/planning/design.go:68-125`, `src/pkg/planning/design.go:320-345`) | +| Lane-name label or `agent/` segment | Issues | Classifier/scheduler | Routes issue to a lane after title prefix and before keyword routing. Scanner sees every issue; other agents see their lane. | Soft routing | Hive/human | Classification before kicks | Change/remove label | `agents.*.lane_keywords` (`src/pkg/classify/classifier.go:249-276`, `src/pkg/scheduler/templates.go:298-303`) | +| `agent/` | Issues, PRs | Provenance, ownership, dashboard bands | Marks the filing/owning agent. The wrapper always derives the suffix from the lane name (`HIVE_AGENT`), never the display name, so PR ownership and label routing see the same token the scheduler compares against. | Informational + routing | Hive | Issue/PR creation and display | Remove if wrong | Agent identity settings (`bin/gh-wrapper.sh:1068-1113`, `src/pkg/scheduler/pr_annotations.go:146-158`) | +| Priority labels (`triage/accepted`, `ai-fix-requested`, `approved-direction`, `kind/bug`, `bug`, `priority/critical-urgent`, `priority/important-soon`, `help wanted`, `good first issue`) | Human-filed issues | Ranking | Human-filed issues with these labels go to tier 0 in kick lists. | Soft ordering | Human/Hive | Ranking | Remove label | `HIVE_ACTIONABLE_PRIORITY_LABELS` (`src/pkg/github/client.go:2740-2832`) | +| `auto-qa`, `auto-qa-finding`, `kind/security`, `kind/regression` | Issues | Classifier | `auto-qa`/`auto-qa-finding` make Simple; `kind/security`/`kind/regression` make Complex. | Soft classification | Hive/human | Classification | Remove label | Classifier tables (`src/pkg/classify/classifier.go:279-303`) | +| `run/spec`, `run/fix` | Issues | Runs triage | Forces spec or direct-fix triage when runs triage is enabled. | Gate when enabled | Human/Hive | Triage | Remove label | `runs.triage.enabled` (`src/pkg/classify/triage.go:1-55`) | +| `runs.triage.spec_labels` / `fix_labels` (v6/edge Spek) | Issues | Spek/runs triage | Configured exact labels route to spec or fix; mark this v6/edge when documenting Spek behavior. | Gate when enabled | Operator/human | Triage | Remove label/config | `runs.triage.spec_labels`, `runs.triage.fix_labels` (`src/pkg/classify/triage.go:35-55`) | +| `tracker`, `meta-tracker`, `tracking`, `epic` (last segment) | Issues | Tracker detector, PR claim rewrite, contributor queue | Marks coordination-only/tracker issues; agents see tracker tags, contributors do not get them. | Soft for agents; hard for contributors | Human/Hive | Enumeration/contributor admission | Remove label or close tracker | Tracker detector (`src/pkg/github/client.go:2090-2156`) | +| `hive-plan`, `hive-design` | Issues | Planning label sweep | `hive-plan` mints/decomposes an epic; `hive-design` asks architect for design first. Only works when planning-from-label is enabled and ACMM >= 5. | Gate when enabled | Human | Planning sweep | Remove label or process plan/design | `planning.plan_from_label`, `planning.plan_labels`, `planning.design_labels` (`src/pkg/config/config.go:400-460`, `src/pkg/planning/issue.go:483-510`) | +| `lgtm` | PRs | Queued auto-merge sweep | Queue label for human/owner merge action; the sweep also requires its normal authorization and skips held/exempt PRs. Adding by hand is not enough if the App approval/authorization is absent. | Permit | Dashboard/merger | Auto-merge sweep | Remove label; head changes can de-queue | `governor.labels.automerge`, default `lgtm` (`src/pkg/config/config.go:3388-3396`, `src/pkg/config/config.go:4952-4957`, `src/pkg/github/automerge/automerge_sweep.go:966-1036`) | +| `reviewer-passed` | PRs | Reviewer lane/escalation reconciliation | Marks one reviewer pass/de-escalation; with no `needs-human`, un-escalates. | Workflow | Reviewer lane/Hive | Reviewer/escalation pass | Remove only if intentionally re-reviewing | Fixed label (`src/pkg/escalation/escalation.go:1185-1205`) | +| `reviewer-recommend-close` | PRs | Reviewer lane | Reviewer recommends closing rather than continuing automated repair. | Workflow | Reviewer lane | Reviewer pass | Human decides/clears | Fixed label (`src/pkg/scheduler/reviewer_lane.go:296-305`) | +| `review.human_decision_label` | PRs | Human-decision mirror | Mirrors review `requires_human` verdict to an existing repo label. It gates nothing and Hive does not create/remove it. | Informational | Hive if label exists | Review verdict | Human removes | `review.human_decision_label` (`src/pkg/github/human_decision_label.go:1-36`, `src/pkg/config/config.go:7186-7203`) | +| `needs-rebase` | PRs | Scanner/kick annotation | Fills mergeability annotation in kick data. | Informational | Scanner/Hive | PR status processing | Remove after rebase | Fixed label (`src/pkg/scheduler/pr_annotations.go:117-144`) | +| `hive/covered-by-pr` | Issues | PR-claim label sync and dashboard | Open PR is verified as related; issue remains actionable. Labels are synced only for actionable issues, so stale labels can remain on held/exempt/filtered issues. | Display-only | Hive | Claim sync after enumeration | Hive removes when actionable issue no longer has open PR evidence | Fixed label (`src/pkg/github/prclaims.go:1380-1435`) | +| `hive/likely-done` | Issues | PR-claim label sync and dashboard | Merged PR is verified as related while issue remains open; issue remains actionable until GitHub/operator closes or confirms. | Display-only | Hive | Claim sync after enumeration | Hive removes when actionable evidence no longer says likely done | Fixed label (`src/pkg/github/prclaims.go:1380-1435`) | +| `hive/already-done` | Issues | Contributor queue, already-done verdict close path, and dashboard | Contributor already-done verdict/confirmation; default contributor skip label and done band. When the verdict cites a PR that the API verifies as merged on the default branch, Hive labels the issue and runs the normal completed close path; human-filed bugs still wait for reporter confirmation unless they opted into close-on-merge. | Contributor hard skip; dashboard display; conditional close | Hive/contributor flow | Contributor admission, verified verdict settlement, issue close gate | Human removes/reopens or confirms reporter-gated bugs | `hub.contribute_already_done_label`, fixed label (`src/pkg/config/config.go:4701-4924`, `src/pkg/dashboard/contribute_verdict_settle.go`, `src/pkg/github/issue_close.go`) | +| `blocked` | Issues | Contributor queue and dashboard issue bands | Always included in contributor skip patterns and default waiting band. Does not by itself stop spoke-agent enumeration unless also exempt/held/filtered. | Contributor hard skip; display | Human | Contributor admission/dashboard render | Remove label | `hub.contribute_skip_labels`, dashboard bands (`src/pkg/config/config.go:4585-4685`, `src/docs/dashboard.md:105-140`) | +| `needs-direction` | Issues | Enumeration, escalation labels, dashboard issue bands and un-park sweep | ADR-0019 escalation marker for work that needs a maintainer direction decision before continuing. Filtered from enumeration like `needs-human`: no agent kick, kick claim or contributor offer. The un-park sweep keeps the same "What to reply" notice as `needs-human`/`needs-decision` and accepts the same `/hive approve` or `/hive decision ` commands. See [Maintainer commands](https://github.com/hivecommons/hive/blob/v5/src/docs/maintainer-commands.md). | Hard suppress until directed | Hive/human | Dashboard render and un-park sweep | Human removes, or a maintainer replies `/hive approve` / `/hive decision `, which also adds `approved-direction` and never touches `hold` (`src/pkg/github/issue_unpark_command.go`) | Fixed escalation label (`src/pkg/github/labels.go`, `src/docs/adr/0019-escalation-over-stalling.md`) | +| `needs-decision` | Issues | Enumeration, contributor relay, dashboard issue bands and un-park sweep | Relay can apply it when a maintainer decision is needed; filtered from enumeration like `needs-human`, so no agent kick, kick claim or contributor offer. The un-park sweep keeps the "What to reply" notice and command handling documented in [Maintainer commands](https://github.com/hivecommons/hive/blob/v5/src/docs/maintainer-commands.md). | Contributor hard skip; display | Relay/Hive/human | Contributor admission/dashboard render | Human removes, or a maintainer replies `/hive approve` / `/hive decision `, which also adds `approved-direction` and never touches `hold` (`src/pkg/github/issue_unpark_command.go`); empty config disables relay application | `hub.contribute_needs_decision_label` (`src/pkg/config/config.go:4397-4408`, `src/pkg/config/config.go:4645-4685`) | +| `needs-triage`, `discussion`, `question`, `tracking`, `epic` | Issues | Contributor queue | Default contributor skip labels/patterns. | Contributor hard skip | Human/Hive | Contributor admission | Remove label or config | `hub.contribute_skip_labels`, `HIVE_CONTRIBUTE_SKIP_LABELS` (`src/pkg/config/config.go:4585-4685`) | +| Contributor allow/deny label filters | Issues | Contributor queue | Hive-wide label filters can run in deny mode (skip if any label matches) or allow mode (offer only if at least one label matches); per-repo filters layer on top and can only narrow offers. Patterns use Hive wildcard/substring matching, not GitHub hold matching. | Contributor hard gate | Operator | Contributor admission | Edit filter mode/list or per-repo filter | `hub.contribute_labels_mode`, `contribute_deny_labels`, `contribute_allow_labels`, `contribute_repo_filters` (`src/pkg/config/config.go:4388-4420`, `src/pkg/config/config.go:6940-6994`, `src/pkg/config/config.go:7008-7055`) | +| `1-triage`, `2-discussing`, stage labels | Issues | Dashboard repo-card bands/legend | Stage vocabulary is display-only unless another consumer names the same label. `2-discussing` ships in the default waiting band; `1-triage` is just a visible repo taxonomy label unless configured elsewhere. | Display-only | Human/repo automation | Dashboard render | Remove label or change band config | `dashboard.issue_bands` (`src/docs/dashboard.md:105-140`) | +| `claimed`, `preempted:`, `hive/claimed-by-` | Issues | Claims/dashboard | A claim is a comment; the `claimed` label is a mirror Hive keeps in sync. Go claim gates use comments/assignees/ledger, not these labels. | Display-only | Hive/claim flows | Dashboard render | Cleared by claim flow or human | `governor.claims.*` (`src/docs/dashboard.md:105-140`) | +| `from-review` | Issues | Review backlog filing | Marks issues filed from review findings. No code path uses it as a gate. | Informational | Hive | Issue creation/display | Remove label | Fixed label (`src/pkg/github/review_backlog.go:1-40`) | +| `hive: churn-triaged` | Issues | Contributor churn guard | Marks churn triage acknowledgement for contributor flow. | Workflow signal | Human/Hive | Contributor/churn checks | Remove label to re-triage | Fixed phrase in contributor flow docs/config (`src/pkg/dashboard/contribute_admission.go:302-338`) | +| `good first issue`, `help wanted`, `bug`, `enhancement` | Issues | Contributor opportunistic ordering | Small ordering boost/visibility in contributor panels; `good first issue`, `help wanted`, and `bug` also appear in default actionable priority labels for human-filed issues. | Soft ordering | Human/Hive | Contributor queue/ranking | Remove label | Contributor/ranking config (`src/pkg/github/client.go:2740-2832`) | + +## Matching rules + +- **GitHub generic holds** are case-insensitive substring matches against `hold`, `on-hold`, `hold/review`, plus configured non-`hive-pause/` extra holds. A label such as `threshold` contains `hold` and therefore holds (`src/pkg/github/client.go:1894-1932`). +- **`hive-pause/`** is case-insensitive exact match, not substring, so it does not collide with `hive/` provenance (`src/pkg/github/client.go:1898-1932`). +- **Exempt labels** use case-insensitive equality or prefix for permanent/configured labels, but the prefix check uses the original label string (`src/pkg/github/client.go:2030-2048`). +- **Contributor skip labels** are lowercased and matched with `path.Match` glob syntax; invalid globs fall back to exact case-insensitive matching (`src/pkg/config/config.go:4658-4708`). +- **Lane routing** lowercases labels and matches lane/routing tokens by segment, so `agent/scanner` can route to scanner; PR `agent/` ownership paths are stricter and should be treated as case-sensitive operationally. The wrapper writes `agent/` from `HIVE_AGENT`, so the label always carries a routable token (`src/pkg/classify/classifier.go:249-276`, `bin/gh-wrapper.sh:1068-1113`). +- **Planning and triage labels** are exact label names after normalization; defaults are prefixed (`hive-plan`, `hive-design`) so ordinary `plan` or capitalized `Epic` taxonomy does not trigger planning (`src/pkg/config/config.go:400-460`, `src/pkg/classify/triage.go:66-84`). +- **Linear holds** use GitHub-like case-insensitive substring matching with defaults plus `work_source.linear.hold_labels` (`src/pkg/worksource/linear.go:344-355`). +- **Jira holds** use exact, case-sensitive equality against configured `work_source.jira.hold_labels`; there is no built-in Jira default (`src/pkg/worksource/jira.go:50-68`, `src/pkg/worksource/jira.go:302-330`). +- **GitHub Projects** work source carries labels through but does not implement a hold-label gate (`src/pkg/worksource/github_projects.go:250-285`). + +## Config that changes label behavior + +- `github.self_authorization_hold`, `project.repo_policies[].self_authorization_hold`, and `HIVE_SELF_AUTHORIZATION_HOLD` change #5117 holds. When all are unset, the default follows the live ACMM level: on through L5, off at L6 Fully Autonomous. +- Hive-wide ACMM level controls level holds; per-repo ACMM overrides do not make PRs skip the level hold. +- `governor.labels.exempt`, `governor.labels.automerge`, and `project.issue_filter.require_labels` decide exempt/admit/queue behavior. +- `project.issue_filter.reporter_trust.*` (admission by reporter), `github.reporter_trust_hold`, `project.repo_policies[].reporter_trust_hold`, and `HIVE_REPORTER_TRUST_HOLD` (the matching merge hold) are the #9665 reporter-trust gate. Off unless `reporter_trust.enabled: true`; the hold follows that switch unless set on its own. Both are edited under **Settings β†’ Labels** (who is trusted, which triage label) and **Settings β†’ Repos** (the hold). +- `planning.plan_from_label`, `planning.plan_labels`, `planning.design_labels`, and `planning.design_approved_label` control planning labels, with the L5+ planning floor. +- `runs.triage.enabled`, `runs.triage.spec_labels`, and `runs.triage.fix_labels` control run triage labels. +- `governor.question_autoclose.*` (`HIVE_QUESTION_AUTOCLOSE`, `HIVE_QUESTION_AUTOCLOSE_HOURS`) closes answered `question` issues; see [Question auto-close](#question-auto-close). +- `governor.claims.*`, `review.human_decision_label`, `hub.contribute_*`, `dashboard.issue_bands.*`, and `HIVE_ACTIONABLE_PRIORITY_LABELS` control the display/contributor/ranking labels above, including contributor label allow/deny filters and per-repo narrowing. +- `work_source.linear.hold_labels` and `work_source.jira.hold_labels` are non-GitHub label-equivalent gates with the different matching rules described above. +- Not labels: `project.paused_repos` pauses an entire repo; contributor queue holds can park `owner/repo#N` without changing GitHub labels. + +## Question auto-close + +Off by default ([#9584](https://github.com/hivecommons/hive/issues/9584)). When on, a question issue the hive has answered is closed after a short window unless the person who asked objects, so answered questions stop inflating the open-issue count and being rescanned every sweep. + +```yaml +governor: + question_autoclose: + enabled: true # or HIVE_QUESTION_AUTOCLOSE=true + hours: 4 # or HIVE_QUESTION_AUTOCLOSE_HOURS; default 4 + labels: [question, kind/question] # default; what marks a question + human_label: needs-human # default; added when the author objects +``` + +How it works: + +1. The scanner kick gains a short answer contract: an issue that only asks a question gets the `question` label and ONE answer comment, which ends with a hidden `` marker and the line "If this doesn't answer your question, react πŸ‘Ž to this comment and the issue will stay open." The footer text is built by Hive and passed through the mention sanitizer. +2. Hive watches question-labelled issues from the normal issue pass. When the last comment on one is a marked answer posted by the hive's own identity (the GitHub App bot login `[bot]` or `project.ai_author`), it schedules a close at answer time + `hours`. The schedule lives in `/data/question-autoclose.json`, so a restart keeps the original deadline. The marker is plain text, so a marked comment from any other account (a person or another bot pasting it) is ignored and never starts the clock; with no hive identity known, nothing is auto-closed. +3. At the deadline Hive re-reads the issue. A πŸ‘Ž from the issue author on the answer keeps it open and adds `human_label`. Otherwise the issue is closed with `state_reason: completed` and no extra comment, so the answer stays the last thing Hive said. + +A schedule is cancelled (never acted on) when anyone comments after the answer, the issue is closed by someone else, the question label is removed, or a bug, enhancement, hold or `human_label` label appears. Bugs (`bug`, `kind/bug`, human-filed bug reports), enhancements/features and held issues are never auto-closed. A cancelled or finished answer is remembered for 30 days so the same answer is never scheduled twice; a new answer after a follow-up starts a new window. + +### Dashboard + +The Governor dialog's Features tab has a "Question Auto-Close" section: a switch for `enabled` and a field for `hours` (`GET`/`PUT /api/config/governor/question-autoclose`, owner-only, same pointer/only-what-you-send contract as the other governor-config sections). Turning it on there shows a read-only live-schedule table underneath β€” one row per answered issue currently waiting out its objection window (repo/issue, answered-at, closes-at), backed by `GET /api/config/governor/question-autoclose/schedule`. The table is read-only: `labels`/`human_label` still need `hive.yaml`. + +## Lifecycle examples + +### Strategist-filed direction to a PR + +1. Strategist files an issue with `[strategist]`/`agent/strategist`. It is actionable but lower-ranked as hive-filed. +2. A maintainer adds `approved-direction`, assigns a human, or comments. Label or assignee also improves ranking; a comment only satisfies #5117. +3. An agent opens a PR citing the issue. If the acknowledgement existed before PR creation, no #5117 hold is applied. At L3-L5, the separate level hold can still apply. +4. If acknowledgement is added after a PR already has `hold`, remove the PR hold too. + +### Holding an issue + +1. Add `hold`/`on-hold`/`hold/review`, or use dashboard `⏸ Hold` to add `hive-pause/`. +2. Enumeration moves it to the Hold list. It leaves agent kicks and the contributor queue. +3. Caveat: the task-list and SHA sweeps do their own listing but honour the same hold predicate; SHA-hold lifts only the literal `hold` it applied itself. +4. Remove the hold label or click `β–Ά Release`; it is reconsidered on the next enumeration. + +### Holding a PR + +1. The PR receives `hold` from a human, the level gate, #5117, holdguard, or SHA-related policy. +2. It is not merge-eligible or auto-merged. If CI is red and it is not outreach/escalated, its owning agent may still be asked to fix CI without removing the hold. +3. If the branch moves while held and then the hold is lifted, holdguard re-adds `hold`; removing it again is the fresh approval. + +### Escalation + +1. Red CI across the distinct-SHA budget applies PR `needs-human`; automated fix dispatch stops. +2. Reviewer lane may add `reviewer-passed` and remove/un-escalate `needs-human`, or add `reviewer-recommend-close`. +3. A human can remove `needs-human` after addressing the root cause; the ledger resets after the grace period. + +## Non-label equivalents + +- **Human comments and assignees** can acknowledge hive-filed directions for #5117; assignees also affect ranking. +- **Hidden comment markers** carry state that no label does. `` records an issue claim, `` dedupes a published finding, `` marks an overlap notice, `` starts the question auto-close clock, and `` is stamped on the single comment a fix lane leaves on a PR it defers to shared incident `#` (`DEFER_TO_INCIDENT` from `bin/hive-baseline-check.sh`), so "every PR incident `#` broke" stays greppable after the fix lands ([#10441](https://github.com/hivecommons/hive/issues/10441)). One marker per PR per incident; it is never edited or removed while the incident is open. While incident `#` is open, the governor records it as `deferred_incident` on the PR's `ci-failing.json` row and the kick builders keep that PR out of every CI-FAILING / FIX-BEFORE-NEW repair list, naming it only as deferred; once the incident closes the PR is listed for repair again ([#10528](https://github.com/hivecommons/hive/issues/10528)). +- **Paused repos** (`project.paused_repos`) stop whole-repo write/merge/enumeration paths without labels. +- **Contributor queue holds** such as active leases, cooldowns, dependencies, and quota guard holds suppress contributor offers without touching GitHub labels. +- **Jira/Linear labels** map only where the work-source adapter supports them: Linear skips held work using substring hold labels; Jira skips exact configured hold labels; GitHub Projects currently imports labels but does not use a hold gate. + +## Repo-card legend vocabulary + +The repository-card legend is a UI vocabulary, not a second scheduler. Unclaimed, claimed, needs-triage, needs-human, and confirm-and-close issue bands are computed client-side from labels/assignees, the snapshot's `human_acknowledged` flag (the cheap half of the #5117 acknowledgment: `approved-direction` or a human assignee, no comment scan), and `dashboard.issue_bands`; PR bands are computed client-side from held/needs-human labels, merge verdicts, CI, review links, draft state, and the same waiting/stale display config. Non-winning states stay as badges. State glyphs such as `β›”`, `❓`, `πŸ‘€`, `βœ“`, role badges, stale `πŸ•’`, PR `βœ“`/`◐`/`⚠`, held `⏸`, failing CI `βœ— CI`, conflicts `β‘‚`, reviewed `πŸ’¬`, auto-merge `πŸ”€`, and review-class badges explain the same data the table above names. Changing a band label changes the repo card description only; it does not make an item held, exempt, mergeable, or actionable. + +## Documented inconsistencies and follow-ups + +Issue #8924 recorded the sharp edges of this page's first version; #8927 aligned the code: auto-merge sweeps, the task-list sweep, and the SHA-hold sweep now gate on the enumeration hold predicate (so `hive-pause/` holds everywhere), SHA-hold lifts only its own `hold`, policy templates name the enforced hold set, and `agent/` is always the lane name. Two behaviours remain deliberate rather than fixed: + +- Level-hold and #5117 disabled-policy auto-release are different. The self-authored auto-merge sweep may still release its own #5117 self-authorization holds, but ACMM level-applied holds are never auto-released by a sweep or level change. They are released by a human removing `hold`, or by a deliberate one-off `PUT /api/packs/level` with `release_level_holds: true`, which touches only Hive App level-hold notices whose latest `hold` event was by the App. +- `hive-open-pr` discards every `--label` value, including `hold`, because the PR-request watcher applies holds server-side (`bin/hive-open-pr.sh:142-150`, `src/docs/hive-open-pr.md`).