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-adopted-optional-check-auto-merge-off.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- An adopted PR whose only blocker is a red optional check no longer sits at `stage/074-adopted-by-hive` forever on a repo whose auto-merge is off. There the hive only observes and a person merges, so once the head sits unchanged past the 074 dwell with CI idle it moves to `stage/085-needs-decision` (`adoption-stalled:optional-check-failing:<check>`), and the note says the check is optional and a person may re-run it, fix it or merge past it. Where the hive merges, a red optional check alone still never escalates ([#13040](https://github.com/hivecommons/hive/issues/13040)); seen on projectbluefin/actions#752.
5 changes: 3 additions & 2 deletions src/docs/hive-merge.md
Original file line number Diff line number Diff line change
Expand Up @@ -1661,8 +1661,9 @@ red β€” goes to `stage/085-needs-decision` as
per head and reason, retried until GitHub accepts it), so the
dashboard shows a person's item, not a silent 074; "waiting on maintainer
lgtm" is only ever the state at 080+ (hivecommons/hive#12858). The dwell runs
from the head's last hive push, a red optional check alone is not a blocker,
and the escalation releases back to 074 when its reason clears
from the head's last hive push, a red optional check alone is not a blocker
unless the repo's auto-merge is off (a person merges there,
projectbluefin/actions#752), and the escalation releases back to 074 when its reason clears
(hivecommons/hive#13040). The issues a PR covers
follow it: once the sweep stages a PR at 050 or later, the enumeration cycle
writes the same stage on each linked issue (`stage/040-covered-by-pr` until
Expand Down
13 changes: 8 additions & 5 deletions src/docs/labels-and-control-signals/stage-labels.md
Original file line number Diff line number Diff line change
Expand Up @@ -113,7 +113,7 @@ referenced it) a lone `stage/050-review-pending`
| `stage/070-fixing` | PR | hive-owned repair: App/taken-over PR red, changes requested (by the swarm, or by a trusted human's **changes requested** review / `/hive decision <text>` on the current head β€” reason `human-changes-requested`, which also kicks the author agent with the text verbatim, [#13041](https://github.com/hivecommons/hive/issues/13041)) or needs-rebase, **or** a non-App PR whose red head was caused by a hive-pushed commit that must be removed/re-homed; a hive agent is reworking it | 2h |
| `stage/071-needs-author` | PR | human-authored PR (`author/human`): CI red / changes requested / conflicting; the hive posted its diagnosis, the author must act. No nudge, no adoption β€” the person pushes or comments | 24h |
| `stage/072-returned-to-contributor` | PR | clanker PR (`author/clanker`, relay or external hive): CI red / changes requested / conflicting; the hive posted its diagnosis, the ball is in the contributor hive's court. (Briefly spelled `stage/072-needs-author` by [#12713](https://github.com/hivecommons/hive/pull/12713); the engine renames that label back in place) | 24h |
| `stage/074-adopted-by-hive` | PR | the author (a clanker) was unavailable β€” relay offline, never registered, or silent past the grace (see below); the hive took the PR over: in place on the PR's own branch when it may push there (the scanner's red-PR fix kick rebases and fixes it), otherwise via `hive/adopt-<n>` and a superseding App PR that keeps the author's commits (the original closes automatically when the superseder merges, including when every commit pushed to it after the copy was taken is the hive's own; a later commit by anyone else leaves it open with a note). The review fixer never pushes to a superseded original's branch: fixes go to the copy. Adoption is an **ownership** state, not a CI state: the PR reads 074 for as long as the hive owns it β€” through its fixes going pending, green, reviewed or red again (074 outranks 050/060/070/071/072, and a 085 whose only cause is the review swarm's `requires_human` / decision request β€” the hive answers that on the superseding PR, so the original leaves the merge gate for the CI/Review column with an "Adopted β†’ #N" pill in the adopting pass, never "Needs human decision" (hivecommons/hive#14975 β†’ #14980, #14947 β†’ #14977); a hold, sentinel alert, `needs-human` a person applied, fork-guard or manual-merge lane rule keeps 085) β€” and leaves 074 only at the merge gate (080/085/090/100), when the adoption is released, or to 085 `adoption-stalled:<reason>` when the head sat unchanged past the dwell with CI idle and a real blocker the hive cannot push past β€” a red optional check alone never counts, the dwell waits while the fixer queue lists the head and no fixer kick has carried it yet (capped at four dwells; not applied when the fixer is unavailable), and the escalation releases back to 074 as soon as the reason clears (an in-place adoption with a blocking review finding re-homes to `hive/adopt-<n>` first instead; one with a squash-unsafe hive commit elects a merge commit on a `role/trusted` PR β€” `merge-method/merge` label, lane continues β€” and otherwise immediately re-homes to an App-authored superseder (`signoff-rehome`), preserving commits and sign-offs while changing squash attribution; loss of push access re-homes immediately, and idle rebase work re-homes after the dwell). For in-place adoption, a changed head must be linked to the App bot by GitHub commit metadata (the stage store only remembers heads that already passed that check); otherwise the hive treats it as a contributor push and hands the PR back (072 if red, else the normal path). Forgeable git author/committer names and emails never keep 074. A PR whose author holds **admin** or **maintain** on the repository is never adopted or re-homed (one cached permission read per repo and author per 10 minutes; a failed read is not cached and defers: no adoption, and an existing adoption is neither released nor re-homed until the read succeeds), and an adoption of such an author is released on the next pass, closing a still-open hive superseder with a note first. A fork PR is never superseded or re-homed into the base repository (that would run unreviewed fork code with the repository's trusted CI). So a fork PR is adopted only in place, when the hive can push to the fork's branch; one it cannot push to is not adopted at all. It stays at `072` with its author's nudge and queued `fix-pr` task, and parks at `085` as `adoption-stalled:fork-rehome-refused` only after the `072` dwell (24h) since the nudge on that head. An in-place fork adoption that can no longer be finished on the fork's branch parks there at once. | 3h |
| `stage/074-adopted-by-hive` | PR | the author (a clanker) was unavailable β€” relay offline, never registered, or silent past the grace (see below); the hive took the PR over: in place on the PR's own branch when it may push there (the scanner's red-PR fix kick rebases and fixes it), otherwise via `hive/adopt-<n>` and a superseding App PR that keeps the author's commits (the original closes automatically when the superseder merges, including when every commit pushed to it after the copy was taken is the hive's own; a later commit by anyone else leaves it open with a note). The review fixer never pushes to a superseded original's branch: fixes go to the copy. Adoption is an **ownership** state, not a CI state: the PR reads 074 for as long as the hive owns it β€” through its fixes going pending, green, reviewed or red again (074 outranks 050/060/070/071/072, and a 085 whose only cause is the review swarm's `requires_human` / decision request β€” the hive answers that on the superseding PR, so the original leaves the merge gate for the CI/Review column with an "Adopted β†’ #N" pill in the adopting pass, never "Needs human decision" (hivecommons/hive#14975 β†’ #14980, #14947 β†’ #14977); a hold, sentinel alert, `needs-human` a person applied, fork-guard or manual-merge lane rule keeps 085) β€” and leaves 074 only at the merge gate (080/085/090/100), when the adoption is released, or to 085 `adoption-stalled:<reason>` when the head sat unchanged past the dwell with CI idle and a real blocker the hive cannot push past β€” a red optional check alone never counts unless the repo's auto-merge is off (a person merges there), the dwell waits while the fixer queue lists the head and no fixer kick has carried it yet (capped at four dwells; not applied when the fixer is unavailable), and the escalation releases back to 074 as soon as the reason clears (an in-place adoption with a blocking review finding re-homes to `hive/adopt-<n>` first instead; one with a squash-unsafe hive commit elects a merge commit on a `role/trusted` PR β€” `merge-method/merge` label, lane continues β€” and otherwise immediately re-homes to an App-authored superseder (`signoff-rehome`), preserving commits and sign-offs while changing squash attribution; loss of push access re-homes immediately, and idle rebase work re-homes after the dwell). For in-place adoption, a changed head must be linked to the App bot by GitHub commit metadata (the stage store only remembers heads that already passed that check); otherwise the hive treats it as a contributor push and hands the PR back (072 if red, else the normal path). Forgeable git author/committer names and emails never keep 074. A PR whose author holds **admin** or **maintain** on the repository is never adopted or re-homed (one cached permission read per repo and author per 10 minutes; a failed read is not cached and defers: no adoption, and an existing adoption is neither released nor re-homed until the read succeeds), and an adoption of such an author is released on the next pass, closing a still-open hive superseder with a note first. A fork PR is never superseded or re-homed into the base repository (that would run unreviewed fork code with the repository's trusted CI). So a fork PR is adopted only in place, when the hive can push to the fork's branch; one it cannot push to is not adopted at all. It stays at `072` with its author's nudge and queued `fix-pr` task, and parks at `085` as `adoption-stalled:fork-rehome-refused` only after the `072` dwell (24h) since the nudge on that head. An in-place fork adoption that can no longer be finished on the fork's branch parks there at once. | 3h |
| `stage/080-awaiting-merge-admission` | PR | nothing left for the author: CI green (no red check on the head, required or not), verdict approve, no modifiers β€” and the automerge lane has not admitted it yet (prefilter not evaluated for this head, labels not synced, lane tripped). A stall here means a lane problem, so the hive also posts one `<!-- hive:stage-stalled -->` comment with the lane's last skip reason | 30m |
| `stage/085-needs-decision` | PR | **PR-only** since the owner decision of 2026-10-17 (issues park at `stage/045-needs-decision`; before that this stage carried both, [#12683](https://github.com/hivecommons/hive/issues/12683)). A person owes a **decision**, not a merge: a `requires_human` swarm verdict (reason `reviewer-verdict:requires_human`), no reviewer configured, GitHub workflow approval is required for a trusted same-repo bot/App/clanker PR (`workflow-approval-required:<ctx>`); Hive has posted `/ok-to-test` and is waiting for the repo-local `hive-ok-to-test` workflow or a maintainer, or a human-only lane rule unrelated to trust (workflow-path edits, tests removed, human-merge path, reporter-trust hold), or an open issue the PR closes is held or parked (`linked-issue:hold:#N:<label>` / `linked-issue:needs-decision:#N:<label>`), or GitHub refused to update the branch from its base because the base changed `.github/workflows/` and the token the hive used lacks the workflows permission (`workflow-permission`: a person merges or rebases the base in and pushes, or grants the App Workflows: write if the installation lacks it), or the same refusal on a fork head, which the App cannot push workflow files to whatever it is granted (`fork-workflow-update`: the author, or a maintainer when "Allow edits by maintainers" is on, runs `gh pr update-branch` or merges the base in and pushes; projectbluefin/utah#1001). The sweep sends update-branch once per head and base after either refusal and keeps the reason until one of them moves. A trusted human's normal GitHub **Approve** review on the exact current head clears a `requires_human` verdict for any author kind/lane and records `reviewer-verdict:requires_human:human-approved@<login>`; a new head invalidates it. The same approval also clears the merge-lane review gate over any non-approved swarm outcome, a perspective's `changes_requested` included (the `review_evaluated` audit line records `human_approver` and `overrode`); without it, `changes_requested` / `reject` still require fixes or manual merge. Under `review.self_authored_decision_policy: resolve`, a Hive-authored PR's reviewer decision question parks here only when it matches a named risk class (`review.DecisionRiskClasses`: permissions/credentials, security, sensitive paths, data loss/irreversible, merge/trust policy, external side effects, licensing/legal, unverifiable) or carries `<!-- hive-decision-risk: high -->`; any other question is resolved by policy and recorded as an advisory reason on the approving aggregate. Hive-authored non-risk incomplete-fix reviews with concrete remediation are normalized to `changes_requested` at verdict load/aggregation time and by the stage-label detail selector, even when the finding was marked high severity; duplicate summary/changelog intent-alignment cleanup with a concrete trim/reword fix is included. Those PRs go to `stage/070-fixing`, not here. On a hive-authored PR the trusted human can also answer with a **changes requested** review on the head, or `/hive decision <what to change>`, which moves the PR to `stage/070-fixing` and kicks the author agent with the text verbatim ([#13041](https://github.com/hivecommons/hive/issues/13041)); `/hive decision <text>` on a PR the hive did not open gets one reply naming the review-side equivalents. One `<!-- hive:stage-needs-decision -->` comment on entry names what is owed, and for a hive-authored `requires_human` park names the two actions: approve the head to merge as-is, or request changes and the hive pushes the fix. When the PR owes an approval (a `requires_human` verdict, or a workflow-path fence an approval releases) and also carries an open sentinel alert, the comment says one action answers both: **Approve** on the PR's Activity monitor row (or `approve` through the admin MCP's `repository.item_decision`) records the approval for the head and clears the alert's label, while a GitHub **Approve** review or a typed `/hive approve` / `/hive decision approve` reply approves but leaves the label for a maintainer to remove; once the approval is on record, the only step left for the alert is clearing its label (on GitHub, or **Confirm safe** on the row). When the park is a `hold`, the comment says who set it β€” *the `hold` label was set by the hive itself: reporter trust (issue #N by @X, contributor)* or *by @login* β€” and for a hive-set hold offers *release the hold* / *keep it* (hivecommons/hive#15020). **Sentinel alerts and hold-class labels are gates, not stages** (owner decision 2026-11-08, [#17327](https://github.com/hivecommons/hive/issues/17327)): they no longer pin a PR here. The column is the PR's real progress β€” CI running or red β†’ CI / 070, a reviewer question or changes requested β†’ Review / 071, checks green and verdict approve (or no verdict required) β†’ `090-ready-for-human-merge` β€” and the gate rides along as a pill (**Held Β· sentinel Β· confirm intent** / **Held Β· hold**) with the route reason ("a sentinel alert is open on this PR", "held by label `hold`") kept for the decision popover. The gate is still a hard merge stop: every lane and the dashboard's human-merge shortcuts refuse the merge on the label itself, never on the stage number, so a parked PR never merges unattended. `needs-human` keeps parking here (an explicit human ask, not a gate) | none |
| `stage/090-ready-for-human-merge` | PR | the hive would merge this itself but trust/role blocks it: reviewer verdict approve at the **current** head, required checks green (tide excluded), DCO yes, no conflicts, soak elapsed β€” and the only remaining lane reason is the author's tier/role. A maintainer's `/lgtm` `/approve` is the only missing step. A PR this clean that also carries a sentinel alert or a hold-class label stands here too ([#17327](https://github.com/hivecommons/hive/issues/17327)): the gate is a pill on the real stage, the Merge queue cell reads **Held Β· sentinel Β· confirm intent** / **Held Β· hold** instead of queued, and the entry comment adds "Held: a sentinel alert is open on this PR. The hive never merges this head while the gate stands." β€” resolve the alert or lift the hold, then `/lgtm` `/approve`. One `<!-- hive:stage-ready-for-human-merge -->` comment on entry carries the evidence. Always read with the `role/*` and `author/*` labels. (Was `stage/090-needs-human` before [#12528](https://github.com/hivecommons/hive/issues/12528); the engine renames the GitHub label in place) | none |
Expand Down Expand Up @@ -211,7 +211,7 @@ stateDiagram-v2
s074 --> s085: close-first copy closed unmerged or red at two heads β†’ original reopened, adoption-copy-failed
s074 --> s085: the superseding copy still conflicts with the base after the fixer's two rebase-resolve attempts (adoption-stalled:rebase-failed-twice; Adopt into fresh branch / Close as superseded)
s074 --> s072: superseder closed unmerged, or contributor pushed over an in-place adoption (handed back; 050 if that head is green)
s074 --> s085: adopted head unchanged past the dwell with CI idle and a real blocker the hive cannot push past (adoption-stalled:<reason>; a red optional check alone never counts), or the re-home failed
s074 --> s085: adopted head unchanged past the dwell with CI idle and a real blocker the hive cannot push past (adoption-stalled:<reason>; a red optional check alone counts only where auto-merge is off), or the re-home failed
s085 --> s074: the adoption-stalled reason cleared (CI re-ran, check green, verdict landed); escalation released
s085 --> s074: a 085 that is only the review swarm's requires_human yields to a live adoption in the adopting pass (the hive answers on the superseder); a hold, sentinel, needs-human a person applied, fork guard or manual-merge lane rule keeps 085
s050 --> s085: hold / sentinel / human-only lane rule
Expand Down Expand Up @@ -1252,9 +1252,12 @@ When a contributor-agent PR goes red the hive does not just relabel it (a human-
each hive push restarts the clock, and a record written before the head
clock existed starts it at the first sweep that sees it rather than
reading days back to the original adoption (hivecommons/hive#13040). A
red **optional** check alone (`optional-check-failing:<name>`) is never
the reason: the merge gate does not read it, so there is nothing for a
person to decide and the PR stays 074. The escalation holds only while
red **optional** check alone (`optional-check-failing:<name>`) is not
the reason where the hive merges: the lane merges past it, so there is
nothing for a person to decide and the PR stays 074. On a repo whose
auto-merge is off (the lane only observes, `repo-auto-merge-disabled`)
a person merges, so it counts like any other red check and the note
says the check is optional (projectbluefin/actions#752). The escalation holds only while
its reason holds β€” the sweep re-evaluates it every pass and when the
blocker clears (CI re-runs, the check goes green, a verdict lands) the
PR returns to 074 and the lane carries on. A weak opinion is not such
Expand Down
Loading
Loading