Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/fixed-stuck-decision-plain-words.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- "Let hive decide" now tells the owner when a recorded decision never took effect and what to do about it: past `decisions.delegate.effect_timeout` (default 30m) a repeat click answers "Hive decided <plain action> at <time>, but it hasn't taken effect: <plain why>" with Merge as maintainer / Re-run decision / Close as superseded / Send back for a new commit as buttons, and the hive posts one plain-words follow-up on the item; every rule, verdict and reason is rendered from one glossary (Go + dashboard mirror) so slugs like `contributor-offline` or "supersede" are never shown bare; the delegate's `/hive decision` comment carries "Hive decided / Why / What happens next / If it doesn't happen"; and a decision comment the hive itself posted is never parsed as a reviewer's change request — the self-blocking seen on [#14822](https://github.com/hivecommons/hive/pull/14822).
6 changes: 5 additions & 1 deletion src/docs/dashboard-sections.md
Original file line number Diff line number Diff line change
Expand Up @@ -722,7 +722,11 @@ Fed by `GET /api/stage-tracker`. Every issue and pull request follows the same p

**Audit marker.** Every comment the delegate writes ends with `<!-- hive:delegated-decision by=<hive-id> policy=owner-delegate -->` (and a visible "Decided by … as the owner's delegate under the owner-delegate policy (rule `…`)" line), so a delegated decision can always be told from a human one on GitHub, in the Decisions log, and in any later count.

**Setting.** `decisions.delegate.enabled` (default **true** — the same default as the other "let the hive do it" switches); `decisions.delegate.repos.<owner/repo>.enabled` (or the bare repository name) overrides per repository. `decisions.delegate.llm.enabled` (default **false**) adds the LLM step described below. When it is off the menu entry stays visible but the endpoint answers 403 naming the setting. See [operator-reference.md](operator-reference.md).
**Plain words, everywhere.** Every rule, verdict and reason the delegate can show is rendered from one glossary (`src/pkg/delegatedecision/decision_glossary.go`, mirrored into the page as `STAGE_TRACKER_DECISION_GLOSSARY`; see [Labels → Decision glossary](labels-and-control-signals.md#decision-glossary)): the toast says "adopted (the author's hive hasn't been connected since the nudge)", never "(contributor-offline)"; the `/hive decision` comment carries a four-line block — **Hive decided** / **Why** / **What happens next** (with "expected within 30 min") / **If it doesn't happen** — above the attribution and the marker; the needs-decision popover's blocker line uses the same words.

**When the decision doesn't take effect.** A recorded decision is expected to cause something — the park lifted, a merge, a close, a fresh hive-authored PR, a new commit — within `decisions.delegate.effect_timeout` (default **30m**). Clicking *Let hive decide* again inside that window answers *No change — hive already recorded this decision at <time>: <plain action> (<plain rule>)* and *Expected by <deadline>: <effect>*. Past the deadline the answer is `result.action: "no-effect"`: *Hive decided <plain action> at <time>, but it hasn't taken effect: <plain why>* — the why read from the lane reason and the PR's state (a reviewer asked for changes; the hive's own decision comment was read as a change request, the [#14822](https://github.com/hivecommons/hive/pull/14822) case; security-sensitive files need a maintainer; conflicts; red CI; sign-off missing; a hold; the author is still online so adoption cannot start; adoption is switched off) — and the toast carries the concrete next actions as buttons (`result.options`, the popover's option shape): **Merge as maintainer (on GitHub)** (a link; the dashboard never merges), **Re-run decision** (posts the same request with `"force": true`, skipping the dedup), **Close as superseded**, **Send back for a new commit**. At the same time the hive posts one follow-up comment on the item — *Hive decided … but it hasn't taken effect / What should have happened / Why it hasn't / What you can do* — stamped `<!-- hive:decision-stalled … -->` so it is posted once and never read as a decision. The dashboard's own `/hive decision` comments (the delegated marker) are never parsed as a reviewer's change request, whichever login they were posted under.

**Setting.** `decisions.delegate.enabled` (default **true** — the same default as the other "let the hive do it" switches); `decisions.delegate.repos.<owner/repo>.enabled` (or the bare repository name) overrides per repository. `decisions.delegate.llm.enabled` (default **false**) adds the LLM step described below. `decisions.delegate.effect_timeout` (default **30m**, a Go duration) is how long a recorded decision may go without its expected effect before a repeat click reports it as stuck. When the delegate is off the menu entry stays visible but the endpoint answers 403 naming the setting. See [operator-reference.md](operator-reference.md).

**What this release decides mechanically.** The decider is rules-first: the cases above that are mechanically decidable (dedupe, owner-only, flaky, CI ratchet, design proposal, review backlog, contributor-offline, sentinel-trusted, small-low-risk, reporter-trust, hive-policy) are decided from the item itself; anything else falls to the reversible default (approve direction on an issue; release a green hive PR; ask for the fix first when the head is red or conflicting). Competing-PR detection and a real adopt-supersede trigger are tracked in a follow-up issue linked from the PR that added this action.

Expand Down
73 changes: 73 additions & 0 deletions src/docs/labels-and-control-signals.md
Original file line number Diff line number Diff line change
Expand Up @@ -1324,6 +1324,79 @@ sync, so the stage pass leaves them alone and only writes its own `dco` /
`no-dco`. Readers accept the Prow pair as a fallback verdict. Retiring them
is a Prow `plugins.yaml` (kubestellar/infra) change, not a hive write.

## Decision glossary

Every rule, verdict and reason the owner-delegate decider ("Let hive decide") and the lane engine can show an operator has one plain-words entry here, kept in one place — `src/pkg/delegatedecision/decision_glossary.go`, mirrored into the dashboard as `STAGE_TRACKER_DECISION_GLOSSARY` (a test fails when the two drift) — and used everywhere the hive talks to a person about a decision: the Activity Monitor result toast, the needs-decision popover, the `/hive decision` comment the delegate posts, and tooltips. A rule slug is never shown bare: where the slug appears for the record (the comment's attribution line, the audit log) the plain words sit next to it. The owner's case that forced this was [#14822](https://github.com/hivecommons/hive/pull/14822): a toast reading "hive already recorded this decision (rule `contributor-offline`)" and a PR comment saying "supersede" told him neither why the hive could not decide nor what supersede meant.

The plain-words comment the delegate posts has four lines — **Hive decided** (the action in plain words), **Why** (the rule in plain words), **What happens next** (the expected effect and by when, `decisions.delegate.effect_timeout`), **If it doesn't happen** (what the owner can do) — above the attribution line and the machine marker (`<!-- hive:delegated-decision … -->`, unchanged). When the effect has not shown by the deadline the delegate posts one follow-up (marker `<!-- hive:decision-stalled by=<hive-id> rule=<rule> -->`, never a second decision and never parsed as one) with **What should have happened / Why it hasn't / What you can do**, and the toast for a repeat click says the same (see [Dashboard sections → Let hive decide](dashboard-sections.md#let-hive-decide)).

**Rules (why the hive decided the way it did)**

| Token | Plain words | Detail |
|---|---|---|
| `ci-ratchet` | a CI hygiene gate, landed as a ratchet | A new CI hygiene gate lands as a ratchet: it records today's baseline and fails only on increases, so existing work is never blocked. |
| `contributor-offline` | the author's hive hasn't been connected since the nudge | The PR's author has been offline since the hive nudged them, so the hive takes the work over instead of waiting. |
| `dedupe` | an older issue already tracks this | An older issue already tracks the same work; one thread keeps it moving. |
| `default-approve` | no special rule applies; the hive took its own recommendation | No owner rule singles this issue out, so the hive went with its own recommendation — the reversible choice that keeps work moving. |
| `default-release` | no special rule applies; a green branch is approved | No owner rule holds this PR back; its branch is green and a merge is reversible, so it is approved. |
| `design-proposal` | a proposal with clear acceptance criteria, accepted as written | The proposal states concrete acceptance criteria, so it is accepted as written; anything not stated keeps today's behaviour. |
| `fix-then-merge` | the branch isn't mergeable yet | The branch cannot merge as it is (conflicts, red CI or a missing sign-off); the hive told the author agent exactly what to fix. |
| `flaky-test` | a flaky test, quarantined with a retry | The failure is a flaky test: it is quarantined with a retry and a separate deflake task is filed, so it blocks nothing. |
| `hive-policy` | this changes the hive's own rules | This changes the hive's own settings, governance or security posture; the hive only recommends and the owner confirms. |
| `llm-delegate` | decided by the hive's model under the owner's rules | No mechanical rule applied, so the hive's model decided under the owner's standing rules; the same safety rails applied. |
| `owner-only`, `owner_only` | only the hive owner can do this | This needs a secret, token or organization permission that only the hive owner holds; the hive cannot do it for you. |
| `prefer-contributor` | a contributor's PR and a hive PR do the same work | A contributor's PR and a hive-authored PR cover the same work; the hive prefers the contributor's when it is mergeable and current. |
| `rail-hold` | the item is on hold | The item carries the hold label; the hive never acts on a held item until a person releases the hold. |
| `reporter-trust` | the hold on an unknown reporter is cleared because the fix is sound | The PR was held until the reporter's trust was known; its fix is green and mergeable, so the hold is cleared. |
| `review-backlog` | the PR closed without merging, so the issue stays open | The fixing PR closed unmerged; the issue stays open and is re-triaged rather than auto-closed. |
| `sentinel-trusted` | security-sensitive files changed, but the author is trusted | Security-sensitive files changed; because the author is trusted the hive approved, but a person must still remove the sentinel label before it merges. |
| `sentinel-untrusted` | security-sensitive files changed; a maintainer must approve | Security-sensitive files changed in a PR from an author without write access; a maintainer must review and approve it. |
| `small-low-risk` | a small, low-risk change on a green branch | The change is small and low-risk (docs, CI pins, text, workflow hygiene) and CI is green, so it is approved. |

**Actions and verdicts (what the hive decided)**

| Token | Plain words | Detail |
|---|---|---|
| `accept-proposal` | accepted the proposal as written | The proposal is accepted as written with its stated defaults. |
| `accept-ratchet` | accepted as a ratchet | Accepted as a ratchet: baseline recorded now, failures only on increases. |
| `adopt` | hive takes over finishing this PR | Adopt means the hive takes over finishing this PR: it rebases, fixes CI and merges it, keeping the author's commits and sign-off. |
| `adopt-supersede`, `adopted`, `adoption/supersede`, `supersede`, `supersede-now` | close this PR and open a fresh hive-authored PR with the same commits | Supersede means the hive closes this PR and opens a fresh hive-authored PR carrying the same commits and sign-off, then finishes it itself. |
| `approve`, `approve-review`, `approved` | approved for merge | The hive approved it; the merge gate merges it once every check passes. |
| `close-as-duplicate`, `close-duplicate` | closed as a duplicate | Closed because an older item already tracks the same work. |
| `close-superseded`, `closed`, `superseded` | closed because another PR carries the work | Closed because another PR carries the same work; the author is credited there. |
| `comment-decision` | recorded the decision on GitHub | The hive posted the decision as a `/hive decision` comment, the way a maintainer would. |
| `directed`, `direction` | told the author agent what to change | The hive recorded direction for the author agent, which pushes a new commit with that change. |
| `labels-add` | added labels | The hive added labels to the item. |
| `labels-remove` | removed labels | The hive removed labels from the item. |
| `link` | cross-linked a related item | The hive left a comment linking a related issue or PR. |
| `quarantine-flaky` | quarantined the flaky test | The flaky test is quarantined with a retry and a deflake task is filed. |
| `recommend-only`, `recommended` | recommended only; a person confirms | The hive only recommended; the item stays parked until a person confirms. |
| `refused` | did not decide | The hive did not decide this item; its safety rails stopped it (for example, the item is on hold). |

**Reasons (why a decision has not taken effect)**

| Token | Plain words | Detail |
|---|---|---|
| `adoption-disabled` | adoption is switched off on this hive | Stage adoption is disabled on this hive (governor.labels.stage.adoption), so a request to take a PR over is never carried out. |
| `author-online` | the author's hive is connected, so hive won't take the PR over | Adoption is for authors whose hive has gone offline; this author's hive is connected, so the hive leaves the PR with them. |
| `behind` | the branch is behind the base branch | The branch is behind the base branch and must be updated before it can merge. |
| `changes-requested`, `changes_requested`, `contributor-lane:changes-requested`, `human-changes-requested`, `request_changes`, `reviewer-verdict:request_changes` | a reviewer asked for changes; a new commit is needed | A reviewer asked for changes on this branch. Approving cannot override that: only a new commit, or a maintainer merging by hand, moves it. |
| `checks-failing`, `ci-failing`, `ci-red`, `red` | CI is failing on this branch | Required checks are failing on this branch; nothing merges until they are green. |
| `conflict`, `conflicting`, `dirty` | the branch conflicts with the base branch | The branch has merge conflicts with the base branch; it needs a rebase before anything can merge. |
| `contributor-lane:sentinel-blocked`, `sentinel`, `sentinel-alert`, `sentinel-blocked` | security-sensitive files changed; a maintainer must approve | Security-sensitive files changed. The hive never merges until a maintainer reviews and removes the sentinel label. |
| `dco`, `dco-missing` | a commit is missing its sign-off | A commit on the branch is missing its Developer Certificate of Origin sign-off; the author must sign it off. |
| `effect-unknown` | the hive did not say why | The hive could not tell from the lane reason why the decision has not taken effect. |
| `hold` | on hold; the hive does nothing until it is released | The item is on hold. The hive does nothing with it until a person releases the hold. |
| `label:needs-human`, `needs-human`, `requires_human` | marked needs-human; a person must remove the label | The item is marked needs-human: automated fixes ran out or a person flagged it. The hive waits until the label is removed. |
| `no-effect` | the decision hasn't taken effect | The hive recorded this decision, but what it was supposed to cause has not happened within the expected time. |
| `no-new-commit` | no new commit has been pushed | The hive gave direction, but no new commit has been pushed yet. |
| `not-closed-yet` | the close didn't land | The hive decided to close it, but it is still open; the close call did not land. |
| `not-merged-yet` | the merge gate hasn't merged it | The hive approved it but the merge gate has not merged it; its lane reason says what still blocks it. |
| `self-decision-read-as-changes` | hive's own decision comment was read as a reviewer asking for changes | The merge gate read the hive's own `/hive decision` comment as a reviewer asking for changes, so the decision blocked the PR it meant to advance (hivecommons/hive#14822). A new commit or a maintainer merge clears it. |
| `still-parked` | the item is still waiting on a person | The item is still parked for a person's decision; the recorded decision did not move it. |

A `/hive decision …` comment the hive itself wrote as the owner's delegate (it carries the delegated-decision marker) is never read as a maintainer's command: not as a change request on the PR, not as an approval. [#14822](https://github.com/hivecommons/hive/pull/14822) fixes the parse of `/hive decision approve <rationale>`; the marker guard covers every other decision text the delegate can post, whichever login it was posted under.

## 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:3318-3361`).
Expand Down
Loading
Loading