diff --git a/changelog.d/changed-let-hive-merge-lead.md b/changelog.d/changed-let-hive-merge-lead.md new file mode 100644 index 0000000000..9e90c04647 --- /dev/null +++ b/changelog.d/changed-let-hive-merge-lead.md @@ -0,0 +1 @@ +- Tracker 090 *Ready for human merge*: the lead action is now **Approve and let hive merge** (`queue-merge`) — hive merges on its next tick once CI is green, soak and self-merge ban apply; **Merge now as maintainer** (`merge-now`, and its *Rebase, then merge as maintainer* variant) is secondary. The automerge sweep now honours an operator's recorded queue-merge approval on an untrusted-author PR and attributes the merge to that operator. On the hive's own PR the App no longer tries to review itself (GitHub 422 "Can not approve your own pull request"): the queue note is a comment, the operator's approval is recorded in the hive's store as the plain Approve records it, and the self-authored lane merges on it; the review-request watcher downgrades such a refused review to a COMMENT instead of retrying. diff --git a/src/docs/api-reference/packs-and-acmm.md b/src/docs/api-reference/packs-and-acmm.md index 88d86e4b62..6401a35f2b 100644 --- a/src/docs/api-reference/packs-and-acmm.md +++ b/src/docs/api-reference/packs-and-acmm.md @@ -17,9 +17,9 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | `GET` | `/api/repos/{owner}/{repo}/hold-permission` | Dashboard auth/session | Reports whether the signed-in user can toggle hold chips for a repository card. Owners are allowed; otherwise the server checks GitHub `repos/{owner}/{repo}/collaborators/{user}/permission` and briefly caches the effective permission | `pkg/dashboard/api.go:333`, `pkg/dashboard/api_repo_hold.go` | | `GET` | `/api/repos/{owner}/{repo}/items/{number}` | Dashboard session | Per-item detail for the activity monitor's decision badge: `{repo, number, stage, stage_slug, operator_actions[], operator_action_count, last_operator_action}`. `operator_actions[]` is the server-side ledger of every row action submitted from the dashboard (hold/release, decision, decide-delegated, send-to-human, accept-triage — recorded by `recordOperatorAction` around those routes) as `{action, actor, at, note, target, outcome: pending|applied|no-op|failed, detail, head_sha, stage}`; `last_operator_action` adds the derived `state` (`waiting|addressed|stuck|pending|failed`), `stuck_after_seconds` and `followed[]` (the stage hops after the action). The same `last_operator_action` / `operator_action_count` ride every stage-tracker row and linked PR. Persisted in `/data/operator-actions.json`; `HIVE_OPERATOR_ACTION_STUCK_AFTER` (default `30m`) sets the stuck window. Rows also carry `rebase_merge: {state: approved|rebasing|ci-pending|merged|failed, actor, base, text, fail_reason, conflict_files[], armed_at}` while a *Rebase, then merge as maintainer* follow-through is live or just settled (persisted in `/data/rebase-merge-followups.json`; `fail_reason: foreign-head` when the head moved after the approval by someone other than the hive, so nothing merged), and `rebase: {attempt, max, exhausted, head, text}` on a conflicting PR the fixer is rebasing under the two-attempt loop guard (`/data/rebase-attempts.json`). | `pkg/dashboard/api.go`, `pkg/dashboard/operator_actions.go` | | `POST` | `/api/repos/{owner}/{repo}/items/{number}/hold` | Owner or repo write/maintain/admin | Add or remove a dashboard hold chip for an issue or PR. Body `{"held": true}` adds the hive's exact-match canonical `hive-pause/` label; `{"held": false}` removes exactly the labels causing the hold (`hive-pause/` and/or generic hold labels) and never removes `hive/` provenance. Every toggle writes an audit-log entry; the #8851 upgrade migration writes `/data/hive-hold-migration-.json` with audit-backed, provenance-only, and ambiguous legacy `hive/` classifications. | `pkg/dashboard/api.go:337`, `pkg/dashboard/api_repo_hold.go` | -| `POST` | `/api/repos/{owner}/{repo}/items/{number}/decision` | Owner or repo write/maintain/admin, signed-in GitHub user | Record an operator decision from the activity monitor's row menu / selection bar. Body `{"decision": "approve"|"direction"|"close-superseded"|"close-wontfix"|"adopt"|"reroute"|"re-author"|"merge-now"|"queue-merge", "comment": "…", "type": "issue"|"pr", "superseded_by": "#458", "force": true, "to": ""|"any"}` (`force` only with `adopt`, `to` only with `reroute`; an unknown `decision` is a 400). On an issue parked at 045, `approve`/`direction` act exactly as a maintainer's `/hive approve` / `/hive decision ` comment would (labels, `approved-direction`, stage-engine Unparked fact, reply comment naming the operator). On a PR parked at 085 (`type: "pr"`), `approve` posts the `/lgtm` and `/approve` commands as two comments attributed to the operator, records the approval against the head as the human answer to a `requires_human` / decision-requested verdict (the lanes and the stage engine honour it like a trusted merger's Approve review), lifts `needs-human`, clears the sentinel label and acknowledges the bundle's sentinel findings for that head, re-derives the stage and drops the tracker cache — the response adds `released` (`approval-recorded`, `needs-human`, `sentinel-label`, `sentinel-acknowledged`) and `stage`; the merge gate decides from there (no review as the operator, no merge) — and `direction` records the text as a human change request against the head — the `/hive decision` fix lane — on a hive-authored PR, and on a contributor's clanker PR (`author/clanker` / hive attribution markers) where the text is posted to the contributor's hive and the PR moves to `stage/072-returned-to-contributor` (`status: "direction-returned-to-contributor"`); a person's PR, which no hive can carry direction to, answers 409. The close variants post a comment naming the operator (and the superseding PR when `superseded_by` is given) and close the item as not planned. `adopt` and `re-author` require `type: "pr"` and queue adoption via the `adoption/supersede` label (409 unless `governor.labels.stage.adoption` is enabled). `adopt` with `"force": true` is *Adopt now* ([#15038](https://github.com/hivecommons/hive/issues/15038)): it bypasses the author's presence, the grace window and `maintainer_policy`, marks the stage record and nudges the automerge sweep so the adoption engine supersedes the head at once (responds `status: "already-adopted"` when nothing is left to do; 400 on the hive's own PR). `reroute` (`type: "pr"`, `"to": ""|"any"`) hands the PR's follow-up work to another online clanker through the contributor fix queue, posts a `` note and arms a pickup timer that falls back to Adopt now after `governor.reroute.pickup_timeout`; answers `status: "rerouted"`, 409 when no clanker is online or adoption is disabled. On a PR at 090, `merge-now` (*Approve & merge as maintainer*) posts an attributed comment and merges immediately through the hive's GitHub App, returning `status: "merged"`; `queue-merge` (*Approve — let hive merge*) records an approval attributed to the operator and applies the automerge label, returning `status: "queued-for-merge"` for the hive's merge sweep once CI is green and the head has soaked. Both require `type: "pr"` and a verified owner or `merger` role in addition to the route's repo permission check; both refuse closed/merged PRs and the operator's own PR. `merge-now` on a PR whose `mergeable_state` is `dirty`/`behind` instead answers `202` with `status: "rebase-queued"` (approval recorded, rebase kicked, merge follows via the follow-through once the hive's own rebase is green; a head pushed by anyone else fails the follow-through closed; `head-not-pushable` refusal on a fork without maintainer edits). `approve` on such a PR adds `rebase: {attempt, max, exhausted, head, text}` for the rebase episode it opened. Every decision writes an audit-log entry (`repo_item_decision_*`, e.g. `repo_item_decision_adopt_now`, `repo_item_decision_reroute`). | `pkg/dashboard/api.go:338`, `pkg/dashboard/api_repo_item_decision.go` | +| `POST` | `/api/repos/{owner}/{repo}/items/{number}/decision` | Owner or repo write/maintain/admin, signed-in GitHub user | Record an operator decision from the activity monitor's row menu / selection bar. Body `{"decision": "approve"|"direction"|"close-superseded"|"close-wontfix"|"adopt"|"reroute"|"re-author"|"merge-now"|"queue-merge", "comment": "…", "type": "issue"|"pr", "superseded_by": "#458", "force": true, "to": ""|"any"}` (`force` only with `adopt`, `to` only with `reroute`; an unknown `decision` is a 400). On an issue parked at 045, `approve`/`direction` act exactly as a maintainer's `/hive approve` / `/hive decision ` comment would (labels, `approved-direction`, stage-engine Unparked fact, reply comment naming the operator). On a PR parked at 085 (`type: "pr"`), `approve` posts the `/lgtm` and `/approve` commands as two comments attributed to the operator, records the approval against the head as the human answer to a `requires_human` / decision-requested verdict (the lanes and the stage engine honour it like a trusted merger's Approve review), lifts `needs-human`, clears the sentinel label and acknowledges the bundle's sentinel findings for that head, re-derives the stage and drops the tracker cache — the response adds `released` (`approval-recorded`, `needs-human`, `sentinel-label`, `sentinel-acknowledged`) and `stage`; the merge gate decides from there (no review as the operator, no merge) — and `direction` records the text as a human change request against the head — the `/hive decision` fix lane — on a hive-authored PR, and on a contributor's clanker PR (`author/clanker` / hive attribution markers) where the text is posted to the contributor's hive and the PR moves to `stage/072-returned-to-contributor` (`status: "direction-returned-to-contributor"`); a person's PR, which no hive can carry direction to, answers 409. The close variants post a comment naming the operator (and the superseding PR when `superseded_by` is given) and close the item as not planned. `adopt` and `re-author` require `type: "pr"` and queue adoption via the `adoption/supersede` label (409 unless `governor.labels.stage.adoption` is enabled). `adopt` with `"force": true` is *Adopt now* ([#15038](https://github.com/hivecommons/hive/issues/15038)): it bypasses the author's presence, the grace window and `maintainer_policy`, marks the stage record and nudges the automerge sweep so the adoption engine supersedes the head at once (responds `status: "already-adopted"` when nothing is left to do; 400 on the hive's own PR). `reroute` (`type: "pr"`, `"to": ""|"any"`) hands the PR's follow-up work to another online clanker through the contributor fix queue, posts a `` note and arms a pickup timer that falls back to Adopt now after `governor.reroute.pickup_timeout`; answers `status: "rerouted"`, 409 when no clanker is online or adoption is disabled. On a PR at 090, `queue-merge` (*Approve and let hive merge*, the lead action) records an approval attributed to the operator and applies the automerge label, returning `status: "queued-for-merge"` (on the hive's own PR, which the App cannot review, the queue note is a comment and the operator's approval is recorded as `approve` records it — `released` lists `approval-recorded`, `admitted`); hive's merge sweep merges on its next tick once CI is green and the head has soaked, and that recorded operator approval is the one thing that lets the sweep merge an untrusted-author PR (the merge comment names the operator). `merge-now` (*Merge now as maintainer*, secondary) posts an attributed comment and merges immediately through the hive's GitHub App, returning `status: "merged"`. Both require `type: "pr"` and a verified owner or `merger` role in addition to the route's repo permission check; both refuse closed/merged PRs and the operator's own PR. `merge-now` on a PR whose `mergeable_state` is `dirty`/`behind` instead answers `202` with `status: "rebase-queued"` (approval recorded, rebase kicked, merge follows via the follow-through once the hive's own rebase is green; a head pushed by anyone else fails the follow-through closed; `head-not-pushable` refusal on a fork without maintainer edits). `approve` on such a PR adds `rebase: {attempt, max, exhausted, head, text}` for the rebase episode it opened. Every decision writes an audit-log entry (`repo_item_decision_*`, e.g. `repo_item_decision_adopt_now`, `repo_item_decision_reroute`). | `pkg/dashboard/api.go:338`, `pkg/dashboard/api_repo_item_decision.go` | | `POST` / `GET` | `/api/repos/{owner}/{repo}/items/{number}/decide-delegated` | Same as `…/hold` (owner or repo write), signed-in GitHub user; `decisions.delegate.enabled` (403 when off) | *Let hive decide*: enqueue a delegated-decision job in which the hive decides the parked item itself as the owner's delegate under `pkg/delegatedecision.PolicyText` and records it as a human decision (`/hive decision` comment with the `` marker, park labels off, `triage/accepted`, queue approval on a PR head). Body `{"type": "issue"|"pr", "reason", "caption", "sentinel_reason"}`. `POST` answers 202 with the job (`{id, status: "running"|"done"|"failed", decision: {verdict, rule, text, rationale, actions, keeps_park, ladder?: {decision, reason, ruled_out[]}}, notes, error}`; `ladder` is set on contributor-PR decisions and names the rung that decided — `already-fixed` → `mergeable-as-is` → `rebase-then-merge` → `return-to-contributor` → `contributor-offline` — and why each rung above it did not apply); 409 with the running job while one is in flight; `GET` reads it. Rails: never merges, refuses items wearing `hold`, never grants secrets/permissions (`needs-owner` + `hold` instead), recommends only on hive policy/governance questions (keeps 085). Audited as `repo_item_decision_delegated[_failed]`. See [dashboard-sections.md](../dashboard-sections.md#let-hive-decide). | `pkg/dashboard/api.go:329`, `pkg/dashboard/api_repo_item_decide_delegated.go` | -| `POST` | `/api/repos/{owner}/{repo}/items/{number}/decide-delegated/plan` | Same as `…/decide-delegated` | Preview for *Let hive decide*: runs the same owner-delegate policy with **no side effects** (nothing written, no job) and answers `{would, rule, acting, title, summary, why, consequences[], ladder, mergeable_as_is, alternatives[], writes: false, prior, notes}` — `summary` is one verb-first sentence with no "Hive would:" prefix (*Send #15332 back to its author with one instruction: make CI green, nothing else.*), `why` one short line (*CI is red.*), `consequences` at most two items, `ladder` the rung that decided with its `ruled_out` list, and `mergeable_as_is` whether an as-is merge is honest (the merge-now alternative is dropped when it is not). The dialog shows **Cancel** / **Let hive do that**, plus **Approve & merge as-is** only when `mergeable_as_is`; only then does the SPA post `…/decide-delegated` with `chosen` naming the button. See [dashboard-sections.md](../dashboard-sections.md#let-hive-decide). | `pkg/dashboard/api.go:341`, `pkg/dashboard/api_repo_item_decide_delegated_plan.go` | +| `POST` | `/api/repos/{owner}/{repo}/items/{number}/decide-delegated/plan` | Same as `…/decide-delegated` | Preview for *Let hive decide*: runs the same owner-delegate policy with **no side effects** (nothing written, no job) and answers `{would, rule, acting, title, summary, why, consequences[], ladder, mergeable_as_is, alternatives[], writes: false, prior, notes}` — `summary` is one verb-first sentence with no "Hive would:" prefix (*Send #15332 back to its author with one instruction: make CI green, nothing else.*), `why` one short line (*CI is red.*), `consequences` at most two items, `ladder` the rung that decided with its `ruled_out` list, and `mergeable_as_is` whether an as-is merge is honest (the queue-merge and merge-now alternatives are dropped when it is not). The dialog shows **Cancel** / **Let hive do that**, plus **Approve and let hive merge** (or **Merge now as maintainer** when the hive would approve anyway) only when `mergeable_as_is`; only then does the SPA post `…/decide-delegated` with `chosen` naming the button. See [dashboard-sections.md](../dashboard-sections.md#let-hive-decide). | `pkg/dashboard/api.go:341`, `pkg/dashboard/api_repo_item_decide_delegated_plan.go` | | `POST` | `/api/repos/{owner}/{repo}/items/{number}/blocker/recheck` | Same as `…/hold` (owner or repo write), signed-in GitHub user | *Re-check permissions* on an issue parked on a capability blocker (#15099): probes the GitHub App installation's permissions; when the missing permission is granted, clears every ledger entry blocked on it and un-parks the item (`{result: {outcome: "released", …}}`), otherwise `{result: {outcome: "no-effect", reason: "blocker", options: [...]}}`; 404 when the item has no blocker, 409 when the blocker is not a capability gap | `pkg/dashboard/api.go:342` | | `POST` | `/api/repos/{owner}/{repo}/items/{number}/blocker/close-partial` | Same as `…/hold` (owner or repo write), signed-in GitHub user | Option (c) on a capability blocker (#15099): labels the issue `hive/partially-addressed`, posts the operator's `{"comment"}` naming what remains and closes it; the ledger entry is cleared | `pkg/dashboard/api.go:343` | | `POST` | `/api/repos/{owner}/{repo}/items/{number}/accept-triage` | Owner or repo write/maintain/admin | Accept triage on an issue from the activity monitor's row menu — what a maintainer accepting triage on GitHub does by hand: adds the reporter-trust triage label (`triage/accepted`, or the first of `issue_filter.reporter_trust.untrusted_require_labels`; the label is created in the repo if missing) and removes the awaiting label (`needs-triage` / `reporter_trust.awaiting_label`) and a Hive-written `stage/015-triage-needed`. Empty body. Returns `{ok, repo, number, acceptLabel, added, removed, alreadyAccepted, minStatusSeq}`; an issue already carrying the accept label with nothing left to remove is a no-op (`alreadyAccepted: true`, no write, no audit). 404 for a pull request or an unknown item. The status snapshot's labels are patched so the next reconcile reads 010 Actionable before the engine's own 015 → 010 derivation. Every write is audited as `repo_item_accept_triage` under the dashboard user. | `pkg/dashboard/api.go:538`, `pkg/dashboard/api_repo_item_accept_triage.go` | diff --git a/src/docs/dashboard-copy-inventory.md b/src/docs/dashboard-copy-inventory.md index c06fa10382..3d87256746 100644 --- a/src/docs/dashboard-copy-inventory.md +++ b/src/docs/dashboard-copy-inventory.md @@ -28,7 +28,7 @@ twice.** The tests that hold the line are named in the last column. The new hover, verbatim (title line omitted): > **Ready to merge. Hive won't merge it alone — @odttlnt isn't a trusted author yet.** -> [ Merge it ] [ More ⋯ ] +> [ Let hive merge ] [ More ⋯ ] > Asked by the hive · 7 hours ago > Details ▸ *Hive never merges this on its own; a maintainer merges here or on GitHub. To trust @odttlnt: add them as a merger under ⚙ Security → Authorized users. · Ready for human merge · untrusted author · Next move: human — a maintainer merges it* @@ -60,8 +60,8 @@ The new hover, verbatim (title line omitted): | `stageTrackerStripItems` 090 chevron tip (`tracker-row.js`) | chevron `title` / popover Details | word + reason + stage description + actor (≈ 70) | word + reason + actor (≈ 20) | `TestStageTrackerSentinelLane…` whyTip case | | `stageTrackerTooltip` author line | row tooltip | `@x (author/clanker, inferred)` | `@x (agent, inferred)`; duplicate lines dropped | `TestStageTrackerRows` | | `stageTrackerDCOCaveat` | confirm dialogs | 55 | 46 | `TestStageTrackerReauthor…` in `stage_tracker_row_actions_test.go` | -| Confirm: Approve & merge as maintainer | dialog | 76 | 53 | same | -| Confirm: Approve — let hive merge | dialog | 62 | 49 | same | +| Confirm: Approve and let hive merge (lead) | dialog | 62 | 49 | same | +| Confirm: Merge now as maintainer | dialog | 76 | 53 | same | | ⋯ menu hints (`stageTrackerLeadActions` → `ham-menu-hint`) | ⋯ menu | server consequences (11–31 each) | server consequences (≤ 12 each) | Go budget test | | `stageTrackerOpenTriageNeeded` → `stageTrackerSegments` / `stageTrackerHeadline` Open word (`tracker-row.js`, `tracker-words.js`) | Open chevron, chevron hover first word, row tooltip headline | *New · since 28m* on a reporter-trust hold; the ask lived only in the caption ([#15437](https://github.com/hivecommons/hive/issues/15437)) | *Triage needed · since 28m* (same word as the `needs-triage` chip / 015) | `TestStageTrackerNewRowRendering`, `TestStageTracker_ReporterTrustHoldReadsTriageNeeded` | | `stageTrackerTriageNeededCaption` (`stageTrackerCaption` 015, `stageTrackerNewState` hold text) | row caption, feed | 110 ("Actionable, but no maintainer has looked at it yet; waiting for triage — triage needed: carries needs triage": *triage* ×3 after the chevron word) / 84 ("New · waiting for a maintainer's triage (add `triage/accepted`); the hive's next pass in 7m") | 31 ("Triage needed — accept or close"; the next-mover and next-pass narration stay on the chevron hover) | `TestStageTracker_TriageNeededStage`, `TestStageTracker_ReporterTrustHoldReadsTriageNeeded`, `TestStageTrackerNewState` | diff --git a/src/docs/dashboard-sections.md b/src/docs/dashboard-sections.md index 92e642109a..32914d8de5 100644 --- a/src/docs/dashboard-sections.md +++ b/src/docs/dashboard-sections.md @@ -37,7 +37,7 @@ These words have a special meaning in Hive. Each entry explains them again the f - **Contributor:** a person outside the maintainer team whose issue or pull request Hive is tracking. - **Author:** whoever opened the pull request — a person, an agent or Hive. A **trusted author** is one Hive may merge for without asking. - **Reviewer:** a person or agent that reviews a pull request; Hive's own review swarm is *the reviewer*. -- **Merge:** the one word for landing a pull request. *Merge it* is you merging now; *Let hive merge it* is you approving so Hive merges on its next pass. +- **Merge:** the one word for landing a pull request. *Let hive merge* (the lead) is you approving so Hive merges through its own App on the next tick once CI is green; *Merge now* is you merging at once as maintainer. Hover text follows one budget: one sentence of state in plain words, at most 40 visible words, one recommended action, and everything technical (config keys, stage numbers, how to change a setting) behind a single collapsed **Details**. The same sentence is never shown twice on one surface. The per-builder word counts live in [dashboard-copy-inventory.md](dashboard-copy-inventory.md). @@ -780,7 +780,7 @@ Side stages share a column rather than adding columns: The author legend is a blue Hive hexagon, purple contributor-agent robot or teal human silhouette. The kind is `author/*`, inferred from the snapshot if its label is absent; the link tooltip names the login. On Claimed, the actor is the claim holder; on PR in progress and Returned to contributor it is the author. Hive owns review, adoption and auto-merge work; a human owns a human decision or manual merge. The payload's `stage_actor` is the authoritative actor (see [Who is on it](#who-is-on-it-actor-icons)). -At 090 the row explains why: `· workflow files`, `· tests removed`, `· manual-merge policy`, `· branch protection`, `· merge method`, `· auto-merge off`, `· untrusted author`, `· unauthorized`, `· reviewer deferred`, `· policy` or `· human merge` (a ⚠️-titled or `needs-owner-merge` PR — the caption reads *Ready for human merge (breaking change — owner merges)*, `human_merge_reason` is `breaking-change`, and hive never merges it, so **Approve — let hive merge** is greyed) ([#14658](https://github.com/hivecommons/hive/issues/14658)). `human_merge_reason` is a `prstage.HumanMergeReason*` code from the stage record's lane reason; `human_merge_reason_text` supplies the sentence and next step. For example, workflow-file changes require Merge on GitHub. Manual-merge text can read *Awaiting human merge · workflow files · approved by @login*; search and needs-attention text carry the same reason. A nested PR mirrors `human_approver`, `manual_merge` and both reason fields on `linked_prs`. +At 090 the row explains why: `· workflow files`, `· tests removed`, `· manual-merge policy`, `· branch protection`, `· merge method`, `· auto-merge off`, `· untrusted author`, `· unauthorized`, `· reviewer deferred`, `· policy` or `· human merge` (a ⚠️-titled or `needs-owner-merge` PR — the caption reads *Ready for human merge (breaking change — owner merges)*, `human_merge_reason` is `breaking-change`, and hive never merges it, so **Approve and let hive merge** is greyed and **Merge now as maintainer** leads) ([#14658](https://github.com/hivecommons/hive/issues/14658)). `human_merge_reason` is a `prstage.HumanMergeReason*` code from the stage record's lane reason; `human_merge_reason_text` supplies the sentence and next step. For example, workflow-file changes require Merge on GitHub. Manual-merge text can read *Awaiting human merge · workflow files · approved by @login*; search and needs-attention text carry the same reason. A nested PR mirrors `human_approver`, `manual_merge` and both reason fields on `linked_prs`. ### Pairing, rows and counts @@ -1099,7 +1099,7 @@ The menu is positioned at the pointer, clamped to the viewport, uses `menu` / `m A PR waiting for a person to merge it (*Ready for human merge*, a `human_merge_reason` such as an untrusted author) counts as parked for this purpose. When an issue has two or more open nested PRs the issue row's menu no longer offers a single *Decide…* that would silently pick one: it offers **Let hive decide — all N PRs** (hint *per PR*), which asks the server to decide each PR on its own (see [Let hive decide](#let-hive-decide)); the issue's own *Decide…* stays only when the issue itself is parked at 045. -*Close as superseded by…* on a nested PR with exactly one open sibling under the same issue pre-fills that sibling's number. Within the general *Decide…* group, the first entry is *Let hive decide* (see [Let hive decide](#let-hive-decide) below): the hive decides as the owner's delegate and records it the way a person's decision is recorded. For a PR: *Approve (/lgtm + /approve)* posts those two commands as comments attributed to you and records your approval against the PR's current head as the human answer the row was parked for — a `requires_human` / decision-requested reviewer verdict, the hive's own `needs-human` park (a supersession question, say), the `sentinel-alert` label and the evidence bundle's sentinel findings are all released by it (the response's `released` lists what was: `approval-recorded`, `needs-human`, `sentinel-label`, `sentinel-acknowledged`), the stage engine re-derives the stage on the spot and the tracker cache is dropped — and the sentinel sweep honours the release for that head, re-arming only on a new push — so the row leaves *Needs human decision* for 080 *Awaiting merge admission* on the next read; the merge gate (and the auto-merge lanes, which honour the recorded approval on that head exactly as a trusted merger's GitHub Approve review) takes it from there; this approval path neither submits a GitHub review as you nor merges immediately. For a direct merge, use the separate 090 **Approve & merge as maintainer** action. +*Close as superseded by…* on a nested PR with exactly one open sibling under the same issue pre-fills that sibling's number. Within the general *Decide…* group, the first entry is *Let hive decide* (see [Let hive decide](#let-hive-decide) below): the hive decides as the owner's delegate and records it the way a person's decision is recorded. For a PR: *Approve (/lgtm + /approve)* posts those two commands as comments attributed to you and records your approval against the PR's current head as the human answer the row was parked for — a `requires_human` / decision-requested reviewer verdict, the hive's own `needs-human` park (a supersession question, say), the `sentinel-alert` label and the evidence bundle's sentinel findings are all released by it (the response's `released` lists what was: `approval-recorded`, `needs-human`, `sentinel-label`, `sentinel-acknowledged`), the stage engine re-derives the stage on the spot and the tracker cache is dropped — and the sentinel sweep honours the release for that head, re-arming only on a new push — so the row leaves *Needs human decision* for 080 *Awaiting merge admission* on the next read; the merge gate (and the auto-merge lanes, which honour the recorded approval on that head exactly as a trusted merger's GitHub Approve review) takes it from there; this approval path neither submits a GitHub review as you nor merges immediately. To merge, use the 090 **Approve and let hive merge** action (or the secondary **Merge now as maintainer** for a direct merge). On a Prow repo where the hive bot is not an approver, Prow has already answered the hive's earlier commands with "restricted to collaborators" / "NOT APPROVED"; a later Approve then records the decision without posting the two comments again and says so (`commands_skipped: prow-rejects-bot-commands`, and the toast reads *Approval recorded; `/lgtm` + `/approve` not posted*). A new head carries no answer: pushing to the PR re-asks. @@ -1227,7 +1227,7 @@ A refusal is scoped to the head it failed on. Once the PR head moves (merge-from #### Merging is held for the toast's lifetime -Every merge path (sweep, dashboard *Approve & merge*, relay, forge) registers its attempt in `pkg/github` before the GitHub call and its outcome after. The tracker reads this registry on each build: it shows 100 **Merging** with `merge_gate.merging_since` during the call, or **Merge failed** and the refusal reason. This makes even a merge completed between 30-second polls visible ([#15245](https://github.com/hivecommons/hive/issues/15245)). +Every merge path (sweep, dashboard *Approve and let hive merge* / *Merge now as maintainer*, relay, forge) registers its attempt in `pkg/github` before the GitHub call and its outcome after. The tracker reads this registry on each build: it shows 100 **Merging** with `merge_gate.merging_since` during the call, or **Merge failed** and the refusal reason. This makes even a merge completed between 30-second polls visible ([#15245](https://github.com/hivecommons/hive/issues/15245)). The SPA keeps a hold per PR from the first moment it saw *Merging* — or, for a merge it never saw coming, from the poll that reported it merged — and for `STAGE_TRACKER_MERGING_HOLD_MS` (= `STAGE_TRACKER_MERGE_BANNER_MS`, 30 s) the row stays on the board at 100 *Merging · merge landed* before it advances to ✓ and the banner, glyph flight and chip bump fire. A refused merge drops the hold at once. @@ -1241,15 +1241,15 @@ The *working* spin (an agent on the item right now) stays a separate cue and now The menu exposes the action the row is asking a person to take ([#15078](https://github.com/hivecommons/hive/issues/15078)). Whenever a row — an issue row whose one nested PR is parked, or a PR sub-row — is in a state that asks a person for something, the ⋯ menu **leads** with the matching action(s), taken straight from the payload's `decision_needed.options`, each with its consequence as the hint; the generic entries (*Decide…*, *Hold*, *Re-evaluate now*, *Mark needs-human…*, *Open on GitHub*, *Copy link*) follow under a separator, and the needs-human popover shows the same options with the consequence under each button (`ham-decision-consequences`). -A Go table test (`TestStageTrackerNeedsHumanStatesCarryAnAction`) keeps every state `stageTrackerNeedsHuman` flags on a non-empty options list with at least one enabled action (or a disabled one whose `reason_if_disabled` is plain words), and renderer tests (`TestStageTrackerRowActionsLeadWithDecisionOptions`, `TestStageTrackerIssueRowWithNested090PRCarriesAllThree` — the issue row over its one nested 090 PR carries Approve & merge, Approve — let hive merge and Let hive decide) keep the menu leading with them. *Let hive decide* is on every needs-human state: where the hive cannot act it says so in plain words through the no-effect toast instead of silently recording a decision. +A Go table test (`TestStageTrackerNeedsHumanStatesCarryAnAction`) keeps every state `stageTrackerNeedsHuman` flags on a non-empty options list with at least one enabled action (or a disabled one whose `reason_if_disabled` is plain words), and renderer tests (`TestStageTrackerRowActionsLeadWithDecisionOptions`, `TestStageTrackerIssueRowWithNested090PRCarriesAllThree` — the issue row over its one nested 090 PR carries Approve and let hive merge, Merge now as maintainer and Let hive decide) keep the menu leading with them. *Let hive decide* is on every needs-human state: where the hive cannot act it says so in plain words through the no-effect toast instead of silently recording a decision. State by state: | State the pill shows | Lead actions in ⋯ and in the popover (consequence) | |---|---| -| PR at 090 *Ready for human merge* | **Approve & merge as maintainer**, **Approve — let hive merge**, then **Let hive decide**, followed by other applicable actions. Merger/owner role and confirmation required for merge actions. Read [the 090 action reference](#choose-an-action-at-090) before using a trust override or re-authoring. When the row also wears **needs rebase**, **Rebase, then merge as maintainer** sits right after Approve (below). | +| PR at 090 *Ready for human merge* | **Approve and let hive merge**, **Merge now as maintainer**, then **Let hive decide**, followed by other applicable actions. Merger/owner role and confirmation required for merge actions. Read [the 090 action reference](#choose-an-action-at-090) before using a trust override or re-authoring. When the row also wears **needs rebase**, **Rebase, then merge as maintainer** takes the direct-merge slot (below). | | PR at 085 *Needs human decision* | Let hive decide · Approve · Give direction · Close as superseded · Close as won't fix · Hold (unchanged). | -| PR at 085 or 090 that also wears **needs rebase** (behind or conflicting with its base) | **Rebase, then merge as maintainer** replaces *Approve & merge as maintainer* — a plain merge would be a GitHub 405 — with the consequence *hive rebases #N onto base, waits for CI, then merges it with your approval on record; you'll get a toast when it lands or if the rebase conflicts*. The click records your approval first (/lgtm + /approve in your name), arms a follow-through, and kicks the rebase (GitHub update-branch for the hive's own PR when it is merely behind; otherwise the fixer lane, which now owns a parked PR with an armed follow-through); the endpoint answers `202 rebase-queued` and the toast reads *rebase queued, merge to follow*. The row then reads **Rebasing → merge queued (approved by @you)** with the working cue, *Rebased → waiting for CI, then merge* once the head moves, and the normal merge-gate pills after that. On green the hive merges the rebased head with your approval attributed — only a head the hive itself produced counts as the rebase; a head someone else pushes after your click settles the action as *failed* (*the head moved after your approval*) with **Approve the new head & merge** · **Close as superseded** as the ways out, nothing merged. On a conflict (or CI red, or no rebase within 2 h) the action settles as *failed* with the conflicting files and two ways out — **Adopt into fresh branch** · **Close as superseded** — on the row's badge and in a note on the PR. The ledger's `last_operator_action.followed[]` carries each step (`approval-recorded` → `rebase-kicked` → `rebased` → `ci-green` → `merged`, or `failed`). ([#14822](https://github.com/hivecommons/hive/issues/14822)) | +| PR at 085 or 090 that also wears **needs rebase** (behind or conflicting with its base) | **Rebase, then merge as maintainer** replaces *Merge now as maintainer* — a plain merge would be a GitHub 405 — with the consequence *hive rebases #N onto base, waits for CI, then merges it with your approval on record; you'll get a toast when it lands or if the rebase conflicts*. The click records your approval first (/lgtm + /approve in your name), arms a follow-through, and kicks the rebase (GitHub update-branch for the hive's own PR when it is merely behind; otherwise the fixer lane, which now owns a parked PR with an armed follow-through); the endpoint answers `202 rebase-queued` and the toast reads *rebase queued, merge to follow*. The row then reads **Rebasing → merge queued (approved by @you)** with the working cue, *Rebased → waiting for CI, then merge* once the head moves, and the normal merge-gate pills after that. On green the hive merges the rebased head with your approval attributed — only a head the hive itself produced counts as the rebase; a head someone else pushes after your click settles the action as *failed* (*the head moved after your approval*) with **Approve the new head & merge** · **Close as superseded** as the ways out, nothing merged. On a conflict (or CI red, or no rebase within 2 h) the action settles as *failed* with the conflicting files and two ways out — **Adopt into fresh branch** · **Close as superseded** — on the row's badge and in a note on the PR. The ledger's `last_operator_action.followed[]` carries each step (`approval-recorded` → `rebase-kicked` → `rebased` → `ci-green` → `merged`, or `failed`). ([#14822](https://github.com/hivecommons/hive/issues/14822)) | | PR (hive-authored or a trusted author's) that is **conflicting** with its base | No click needed: the fixer lane rebases it on the hive's behalf, and the gate pill reads **Rebasing · attempt n/2** (spinning) — each fixer push that GitHub still reports dirty is the next attempt. After two the hive stops: the pill reads **Rebase failed · 2/2 — needs a person** and the row's menu still offers *Adopt into fresh branch* / *Close as superseded*. A merely `behind` PR gets GitHub's update-branch from its merge lane even while it wears prow's stale needs-rebase label. **Approve** on such a PR records the approval and opens the rebase episode in your name — the toast reads *Approved — #N conflicts with base; hive will rebase it next pass (attempt 1/2)* with a **Rebase, then merge as maintainer** button, never "the merge gate takes it from here"; the *Approving…* cue clears the moment the decision records. ([#15103](https://github.com/hivecommons/hive/issues/15103)) | | Issue at 045 *Needs decision* (direction) | Let hive decide · Give direction · Approve direction · Send back to the hive · Hold (unchanged). | | Human-authored PR at 071 *Needs author* (or a legacy 072 pending reconciliation) | Let hive decide · Close as superseded · Close as won't fix · Hold — Hive never rewrites a person's PR, so the choice is wait or close. | @@ -1266,8 +1266,8 @@ These are different operations, not interchangeable approvals: | Action | Effect and result | | --- | --- | -| **Approve & merge as maintainer** | Merges #N into its base now through Hive's identity, attributed to you in a PR comment. Audit: `repo_item_decision_merge`, `source: dashboard`. Toast: *merged*; badge: `merge-now`. | -| **Approve — let hive merge** | Records your owner decision as an APPROVE review and the automerge label. The sweep merges on its next eligible pass once CI is green and the head has soaked. Toast: *queued for merge*; badge: `queue-merge`. | +| **Approve and let hive merge** (lead) | The default way a maintainer exercises their last word on an untrusted-author PR. Records your owner decision as an APPROVE review, admits the head (`admitted_by: operator-approval:`) and adds the automerge label; the hive's auto-merge sweep merges it through its own App on the next tick once CI is green — soak and the self-merge ban still apply, and the merge comment names you. Inline lead button: *Let hive merge*. Toast: *approved — hive will merge on the next tick once CI is green*; badge: `queue-merge`. | +| **Merge now as maintainer** (secondary) | Merges #N into its base now through Hive's identity, attributed to you in a PR comment. On a row that needs a rebase it reads *Rebase, then merge as maintainer*. Leads only when queueing is greyed (a breaking change hive never merges, or a head somebody already admitted). Audit: `repo_item_decision_merge`, `source: dashboard`. Toast: *merged*; badge: `merge-now`. | | **Let hive decide** | At 090, does **not** run the delegation policy. It returns a no-effect explanation, such as *I can't merge this: author @Karibhou is untrusted on hotshot — …*, with the two approval actions and the 👥 Contributors remedy. | | **Re-author as hive PR** | A separate, explicit choice when the commit check finds missing `Signed-off-by`: re-home commits on a signed-off Hive branch and open a superseding PR, not merge the original as-is. Disabled with a reason on a person's PR. | @@ -1281,7 +1281,7 @@ Missing sign-offs are disclosed **before** acting, in the blocker line and both The 090 pill's tooltip says *why* the author is untrusted and *what would make them trusted*, per reason code. For `contributor-lane:author-association` (hotshot#317), it explains that @login has neither a GitHub owner/member/collaborator association nor a trusted/merger tier in this Hive's contributor registry. Hive will not merge their PR unattended. -To trust that author for unattended work, give them a trusted or merger tier under **👥 Contributors** (`auto_merge.contributor_lane.require_tiers`), or add them as a repository collaborator on GitHub. Until then, a maintainer chooses **Approve & merge as maintainer** or **Approve — let hive merge** from ⋯. +To trust that author for unattended work, give them a trusted or merger tier under **👥 Contributors** (`auto_merge.contributor_lane.require_tiers`), or add them as a repository collaborator on GitHub. Until then, a maintainer chooses **Approve and let hive merge** (hive merges on its next tick once CI is green, attributed to the maintainer) or **Merge now as maintainer** from ⋯. Other reason codes name their own remedy: @@ -1365,7 +1365,7 @@ Every rule, verdict and reason the delegate can show is rendered from one glossa #### 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