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-fork-pr-not-adopted-without-push.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- **Contributor PRs from forks the hive cannot push to are no longer adopted and parked within minutes.** The hive never moves a fork's commits into the base repository, so adopting a fork PR whose branch it cannot push to only parked it at `stage/085-needs-decision` on the next pass, 15 minutes after the author's relay went offline. Such a PR now stays at `stage/072-returned-to-contributor` with its nudge and the relay's queued `fix-pr` task, and is parked at 085 with the same maintainer ask only after the 072 dwell (24h) since the nudge on that head. In-place adoption on forks that allow maintainer edits, same-repository adoption, and explicit owner-delegated adoption are unchanged.
12 changes: 8 additions & 4 deletions src/docs/hive-merge.md
Original file line number Diff line number Diff line change
Expand Up @@ -724,10 +724,14 @@ it on that branch (never a replacement PR), after which it follows the normal
is never superseded or re-homed into `hive/adopt-<n>`: a branch in the base
repository makes a same-repository PR, which runs with the repository's
secrets and write tokens and skips its fork-only guards, so unreviewed fork
code would run as trusted. The hive records the refusal and the next pass
parks the PR at `085` as `adoption-stalled:fork-rehome-refused` with a
maintainer ask; in-place adoption on the fork's own branch (when the
contributor allows maintainer edits) is unchanged. When adoption is in-place on the contributor PR's own
code would run as trusted. So a fork PR the hive cannot push to is not
adopted at all: it stays at `072` with its author's nudge and queued `fix-pr`
task, and only after the `072` dwell (24h) since the nudge on that head does
it park at `085` as `adoption-stalled:fork-rehome-refused` with a maintainer
ask. In-place adoption on the fork's own branch (when the contributor allows
maintainer edits) is unchanged; if such an adoption later needs a re-home,
the hive records the refusal and the next pass parks it at `085` with the
same ask. When adoption is in-place on the contributor PR's own
branch, the hive owns the head it pushed: once that head is green, approved
by the reviewer, DCO-clean and soaked, the contributor lane admits it under
the hive's own authority (`contributor-lane:adopted-by-hive`, see the
Expand Down
12 changes: 11 additions & 1 deletion src/docs/labels-and-control-signals.md
Original file line number Diff line number Diff line change
Expand Up @@ -228,7 +228,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). 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 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, 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); it parks at `085` as `adoption-stalled:fork-rehome-refused` instead. | 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). 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 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, 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`), `sentinel-alert`, `hold` / `do-not-merge*` / `needs-decision` modifier, 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 App lacks the workflows permission (`workflow-permission`: a person merges or rebases the base in and pushes, or grants the App Workflows: write). 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` 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, per lane, what clears it ([#13087](https://github.com/hivecommons/hive/issues/13087)): for a hive-authored `requires_human` park the two actions — approve the head (review or `/hive approve` reply after the verdict) to merge as-is, or request changes and the hive pushes the fix; for any other `requires_human` park a trusted merger's approval by review or `/hive approve` reply; for a hold / sentinel park the label a person must remove; for a linked-issue park the issue and the label to remove from it; and for a manual-merge-only lane rule that a maintainer must merge by hand, which no approval overrides | 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 sentinel alert, no conflicts, soak elapsed, no hold — and the only remaining lane reason is the author's tier/role. A maintainer's `/lgtm` `/approve` is the only missing step. 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 @@ -919,6 +919,16 @@ When a clanker-authored contributor PR goes red the hive does not just relabel i
2h); and, on a hub that reports no presence at all, the nudge-time
graces (`contributor_grace_online` 2h / `contributor_grace_offline` 15m
after a comment-only nudge);
A **fork** PR is adopted by any of these rules only when the hive can
finish it on the fork's own branch (`mode=in-place`: the contributor
allows maintainer edits and the base-sync touches no workflow file). A
fork PR the hive cannot push to is never moved into the base repository,
so it is not adopted: it stays at `072` with the nudge and its relay's
queued `fix-pr` task, and after the `072` dwell (24h) since the nudge on
that head it parks at `085` as `adoption-stalled:fork-rehome-refused`
with one note asking a maintainer to review it and bring it in or close
it. A new head from the author re-arms the normal path. An explicit
owner-delegated adoption request is still recorded and parks at once.
- `reason=dco-rehome` (always `mode=supersede`) — not a fresh adoption
but a second takeover: an in-place-adopted head stayed
DCO-red with unsigned commits the hive cannot rewrite on the contributor
Expand Down
2 changes: 1 addition & 1 deletion src/docs/running-at-level-6.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ The third route is the human-approved queue (normally `lgtm`): an authorized mer
| Draft | Excluded; author marks ready for review when finished. See [eligibility](../cmd/hive/merge_eligibility.go) and [sweep](../pkg/github/automerge/automerge_sweep.go). |
| GitHub-blocked PR | Missing required checks/reviews, signatures, conflicts or branch rules still bind the merge. Satisfy the actual rule, not just the Hive pill. See [merge block reasons](../pkg/github/merge_block_reason.go) and [sweep](../pkg/github/automerge/automerge_sweep.go). |
| PR escalated after failed fixes | The fix ledger parks exhausted repair work; `needs-human` is a triage signal, **not by itself a universal merge hold**. The scanner separates escalated rows; outside the self-authored review gate below, a green App PR may still merge. Add `hold` if the decision must prevent merging; repair/review, clear the escalation, then release the hold. See [escalation](../pkg/escalation/escalation.go), `writeMergeEligible` in [eligibility](../cmd/hive/merge_eligibility.go), and [sweep](../pkg/github/automerge/automerge_sweep.go). |
| Behind/conflicting fork PR | A GitHub `behind` state triggers an update attempt in the sweep, not a guaranteed repair. The hive cannot assume write access to a contributor's fork. Author rebases/updates the fork, resolves conflicts and reruns CI; a fork merely older than base is not blocked unless GitHub requires freshness or reports a conflict. See [sweep](../pkg/github/automerge/automerge_sweep.go) and `UpdateBranch` in [pull requests](../pkg/github/pullrequest.go). |
| Behind/conflicting fork PR | A GitHub `behind` state triggers an update attempt in the sweep, not a guaranteed repair. The hive cannot assume write access to a contributor's fork. Author rebases/updates the fork, resolves conflicts and reruns CI; a fork merely older than base is not blocked unless GitHub requires freshness or reports a conflict. A relay's fork PR is adopted only when the hive can push to the fork's branch; otherwise it waits at 072 for its relay's `fix-pr` task and reaches you at 085 (`adoption-stalled:fork-rehome-refused`) only after the 24h 072 dwell. See [sweep](../pkg/github/automerge/automerge_sweep.go) and `UpdateBranch` in [pull requests](../pkg/github/pullrequest.go). |
| Adopted PR with unsigned commits | `no-dco` cannot be fixed by adding a later empty signed commit. If all unsigned commits are hive-authored (GitHub-linked to the App bot; git author emails never count) and the adopted branch can be pushed, the hive rewrites just its own unsigned commits with sign-off in place. If any unsigned commit is contributor-authored/unknown, or the branch cannot be pushed, adoption re-homes the work onto a hive-owned branch from the base, cherry-picks or squashes with `-s` while preserving original authorship/credit, opens a superseding PR, and closes the original. See [stage 074 adoption](labels-and-control-signals.md#off-the-happy-path-072--nudge--074--takeover). |
| Adopted PR with review changes requested | `stage/074-adopted-by-hive` means Hive owns the branch. A swarm `changes_requested` verdict must feed the fix dispatcher, not a human `/lgtm` request; for in-place adoptions the fixer may push signed commits to the contributor branch, and the PR stays in the fixer's work list every cycle until a new head lands. If the bounded attempts are exhausted, Hive parks it visibly at 085 with `fix-attempts-exhausted`. |
| Issue parked for a maintainer decision | A human with repository write/maintain/admin permission comments `/hive approve`, `/hive decision <direction>`, or `/hive done` (the owner finished a step only they could do); the un-park sweep removes decision labels, never `hold`. Plain "approved" is insufficient. See [maintainer commands](maintainer-commands.md) and [un-park implementation](../pkg/github/issue_unpark_command.go). |
Expand Down
Loading
Loading