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/changed-writeback-gate-close-first.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Adoption close-first now asks the write-back gate before it closes, labels or reopens a contributor's original PR ([#15272](https://github.com/hivecommons/hive/issues/15272)). These writes land on a PR the hive did not author, but they were only counted in the direct-write ratchet baseline, so they ignored a repo pause, the per-repo mode and the `contributor_adopt` kind policy (default L6 + opt-in label). When the gate refuses, the original stays open and closes when the hive's copy merges, and the refusal shows up in the write-back drill-down. A reopen that is due waits for the next poll, for example until an operator lifts a pause; a refusal for any other reason (the kind policy changed after the hive closed the PR) is logged at warn, because it leaves a hive-closed PR shut until a person reopens it. The ratchet baseline drops `automerge_adoption_close_first.go` (7 → 0).
15 changes: 13 additions & 2 deletions src/docs/labels-and-control-signals.md
Original file line number Diff line number Diff line change
Expand Up @@ -1147,7 +1147,13 @@ When a clanker-authored contributor PR goes red the hive does not just relabel i
copy exists: the stage record is superseded (no row, no chevron, no
needs-human) and the copy is the one PR for the issue. A close GitHub
refuses (403/404) leaves the original open with the note, superseded
all the same. `close_first: false` restores the keep-open behaviour
all the same. The note, label and close are unsolicited writes on a
contributor's PR, so the pass first asks the write-back gate as kind
`contributor_adopt` (default L6 + opt-in label; see the write-back
table in
[operator-reference.md](operator-reference.md#what-hive-writes-to-github-and-when)):
refused, nothing is written and the original stays open on the
keep-open path below until the copy merges. `close_first: false` restores the keep-open behaviour
below: the note has no `close_first` field, the original moves to
`stage/074-adopted-by-hive` (its linked issue mirrors the stage) and
closes only when the copy merges. The hub drops the PR from the
Expand All @@ -1166,7 +1172,12 @@ When a clanker-authored contributor PR goes red the hive does not just relabel i
`adoption/supersede` request re-runs the takeover from the same head).
**Ping-pong guard:** one reopen per original per 24h — a second failed
copy inside the window leaves the original closed with a `held=true`
note saying so. The orphan recovery below never runs for a close-first
note saying so. The reopen, its note and the label removal also go
through the `contributor_adopt` write-back gate: refused, nothing is
written and the record stays due its next poll, so a lifted repo pause
lands the reopen; a policy change after the close is warned in the log
and leaves the hive-closed original shut until a person reopens it.
The orphan recovery below never runs for a close-first
original (its copy being closed is a failure, not an orphan); the
`hive:adoption-copy-failed` note is a settled marker, so the marker scan
never re-adopts a reopened original on its own.
Expand Down
10 changes: 9 additions & 1 deletion src/docs/operator-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -775,7 +775,14 @@ labelled `hive/superseded`, so one issue never shows two active PRs
hivecommons/hive#15135). If the copy is closed unmerged or its required
checks are red at two heads, the hive reopens the original, removes
`hive/superseded`, and parks it at `stage/085` with `adoption-copy-failed`
("needs a person"); at most one reopen per original per 24h. `close_first:
("needs a person"); at most one reopen per original per 24h. The note,
label, close and reopen are unsolicited writes on a contributor's PR, so each
first asks the write-back gate as kind `contributor_adopt` (L6 + opt-in label
by default; see [the write-back table](#what-hive-writes-to-github-and-when)):
refused, the original is not closed and stays open on the keep-open path
until the copy merges, and a due reopen waits for the next poll (a pause
lifting lands it; a policy change after the close is warned in the log and
leaves the PR closed until a person reopens it). `close_first:
false` keeps the earlier behaviour: the original moves to 074 and closes
only once the superseder merges. Whether that rework reaches each agent is visible per row
on Operations → Connected contributor agents: the relay's parallel capacity
Expand Down Expand Up @@ -960,6 +967,7 @@ that level, the power the write-back exists to govern?
| PR↔issue linker (`pr_issue_link.go`, `pr_contributor_link.go`, `linked_prs.go`) | PR watcher | "covered by PR" label on the issue, link comments | issues referenced by any PR | `covered_by_pr_label` → L5 + label |
| Verdict / decision labels (`pr_decision_operator.go`, `human_decision_label.go`, `legacy_decision_labels.go`, `contribute_verdict_settle.go`) | review verdicts, dashboard decisions | `hive:verdict-*`, decision labels | reviewed PRs | `verdict_label` → L3 + label; dashboard-triggered decisions are solicited |
| Contributor adopt / nudge / bot takeover (`automerge/automerge_contributor_*.go`, `automerge_bot_takeover.go`) | auto-merge sweep | adopt comment, update-branch push, workflow approval, nudge comments | contributor PRs in the contributor lane | `contributor_adopt` → L6 + label |
| Adoption close-first (`automerge/automerge_adoption_close_first.go`) | auto-merge sweep, when a supersede adoption opens the hive's copy; close-first poll | close-first note, `hive/superseded` label and close on the original; reopen, copy-failed note and label removal when the copy fails | the contributor's original PR | `contributor_adopt` → L6 + label; refused: the original stays open until the copy merges, and a due reopen waits for the next poll |
| Claims (`prclaims.go`, `claimed_by_label.go`, `cmd/hive/claimswire.go`, `claimescalation.go`) | claim ledger changes | `claimed-by:*` labels, claim/escalation comments | claimed issues | `claim_comment` → L4 + label (hive-claimed issues are own items) |
| Issue close / task-list / decomposed parents (`issue_close.go`, `task_list_sweep.go`, `decomposed_parents.go`, `close_on_merge.go`, `tracking_issue.go`) | merges, sweeps | close, body edits (checkbox ticks), `Refs` rewrites | issues linked from hive PRs | `issue_close`, `parent_issue_edit` → L5 + label; hive-filed issues are own items |
| Gate comments (`pkg/scheduler/clarity_gate.go`, `prior_art_gate.go`, `triage.go`, `issue_blocked.go`, `issue_recheck_soak.go`) | scheduler intake | clarity/prior-art/triage questions, `blocked` labels | issues admitted by the issue filter | `gate_comment` → L5 + label; items carrying the intake label are opted in |
Expand Down
76 changes: 65 additions & 11 deletions src/pkg/github/automerge/automerge_adoption_close_first.go
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
package automerge

import (
Expand All @@ -12,6 +12,7 @@
gh "github.com/google/go-github/v72/github"
hgithub "github.com/hivecommons/hive/pkg/github"
"github.com/hivecommons/hive/pkg/stagelabels"
"github.com/hivecommons/hive/pkg/writeback"
)

// Close-first supersession (hivecommons/hive#15135).
Expand All @@ -33,6 +34,13 @@
// stagelabels.LaneReasonAdoptionCopyFailed. One reopen per original per
// stagelabels.AdoptionReopenWindow: a copy that keeps failing after that
// leaves the original closed with a note rather than flipping it.
//
// Closing, labelling and reopening a contributor's original are unsolicited
// writes on a PR the hive did not author, so every one asks the write-back
// gate (writeback.KindContributorAdopt) first. A refused close-first leaves
// the original open on the keep-open path; a refused reopen leaves the
// record due its next poll, so the reopen lands once the gate allows it
// (e.g. when an operator lifts a repo pause).

// AdoptionCopyFailedMarker opens the note posted when the hive reopens (or,
// past the reopen guard, declines to reopen) a close-first original.
Expand Down Expand Up @@ -110,18 +118,23 @@
// A close GitHub refuses leaves the original open with the note (as the
// merge-time close does); any other close failure leaves the record on
// the keep-open path, where settleSuperseder closes it when the copy merges.
// A write-back gate refusal writes nothing and leaves it on that path too.
func (c *Engine) closeSupersededOriginalFirst(ctx context.Context, store *stagelabels.Store, key string, obs stageObservation, policy StageLabelPolicy, superseding int, reason, fence string, now time.Time) (int, error) {
owner, repo, number := obs.Owner, obs.Repo, obs.Number
logArgs := []any{"repo", obs.Display, "pr", number, "head", obs.HeadSHA, "superseded_by", superseding, "reason", reason}
body := AdoptionCloseFirstComment(obs, policy.HiveID, superseding, reason) + adoptionFenceNote(fence)
if _, _, err := c.gh.Issues.CreateComment(ctx, owner, repo, number, &gh.IssueComment{Body: gh.Ptr(body)}); err != nil {
if d := c.writebackAllowed(obs.Display, writebackItemForObservation(obs), writeback.KindContributorAdopt, body); !d.Allowed {
c.info("stage labels: close-first adoption suppressed by the write-back gate; original left open on the keep-open path", append(logArgs, "writeback_reason", d.Reason, "writeback_detail", d.Detail)...)
return 0, nil
}
if _, _, err := c.gh.Issues.CreateComment(ctx, owner, repo, number, &gh.IssueComment{Body: gh.Ptr(body)}); err != nil { // writeback:gated
c.warn("stage labels: close-first adoption note failed; original left open on the keep-open path", append(logArgs, "error", err)...)
return 0, err
}
if _, _, err := c.gh.Issues.AddLabelsToIssue(ctx, owner, repo, number, []string{hgithub.SupersededLabel}); err != nil {
if _, _, err := c.gh.Issues.AddLabelsToIssue(ctx, owner, repo, number, []string{hgithub.SupersededLabel}); err != nil { // writeback:gated
c.warn("stage labels: close-first adoption label failed", append(logArgs, "label", hgithub.SupersededLabel, "error", err)...)
}
if _, _, err := c.gh.PullRequests.Edit(ctx, owner, repo, number, &gh.PullRequest{State: gh.Ptr("closed")}); err != nil {
if _, _, err := c.gh.PullRequests.Edit(ctx, owner, repo, number, &gh.PullRequest{State: gh.Ptr("closed")}); err != nil { // writeback:gated
if isGitHubStatus(err, http.StatusForbidden) || isGitHubStatus(err, http.StatusNotFound) {
store.MarkSupersededClosedFirst(key, superseding, true, now)
c.warn("stage labels: cannot close superseded original (permission); left open with the note", append(logArgs, "error", err)...)
Expand Down Expand Up @@ -242,22 +255,42 @@
// reopenSupersededOriginal gives a close-first original back to a person:
// reopen, one note, `hive/superseded` off, parked at 085 with
// LaneReasonAdoptionCopyFailed. Within stagelabels.AdoptionReopenWindow of
// the last reopen the original stays closed and the note says so.
// the last reopen the original stays closed and the note says so. A
// write-back gate refusal writes nothing and settles nothing: the record
// stays due its next poll. A pause is logged at info (it lifts); any other
// refusal means the policy moved under a PR the hive closed, and is warned.
func (c *Engine) reopenSupersededOriginal(ctx context.Context, store *stagelabels.Store, cand closeFirstRecord, why string, redHeads int, now time.Time) (int, error) {
rec, copy := cand.rec, cand.rec.AdoptedBy
owner, repo, number := cand.owner, cand.repo, cand.number
logArgs := []any{"repo", owner + "/" + repo, "pr", number, "head", rec.AdoptedHead, "superseded_by", copy, "why", why, "red_heads", redHeads}
if rec.AdoptionReopenedWithin(now, stagelabels.AdoptionReopenWindow) {
held := rec.AdoptionReopenedWithin(now, stagelabels.AdoptionReopenWindow)
preview := AdoptionCopyFailedComment(number, copy, rec.AdoptedHead, why, redHeads)
if held {
preview = AdoptionCopyFailedHeldComment(copy, rec.AdoptedHead, why, redHeads, rec.AdoptReopenedAt, now)
}
if d := c.writebackAllowed(owner+"/"+repo, c.closeFirstOriginalItem(ctx, cand), writeback.KindContributorAdopt, preview); !d.Allowed {
gateArgs := append(logArgs, "writeback_reason", d.Reason, "writeback_detail", d.Detail)
if d.Reason == writeback.ReasonRepoPaused {
c.info("stage labels: close-first original reopen suppressed by the write-back gate; retried at the next poll", gateArgs...)
return 0, nil
}
// Not a pause: the contributor_adopt policy changed after the hive
// closed this PR, so the reopen that would undo that close no
// longer clears the gate. The PR stays closed until the policy
// allows it again or a person reopens it; say so loudly.
c.warn("stage labels: close-first original reopen refused by the write-back gate; hive-closed PR stays closed until the contributor_adopt policy allows the reopen or a person reopens it", gateArgs...)
return 0, nil
}
if held {
store.MarkCloseFirstSettled(cand.key)
c.warn("stage labels: close-first copy failed again within the reopen window; original stays closed", append(logArgs, "reopened_at", rec.AdoptReopenedAt)...)
body := AdoptionCopyFailedHeldComment(copy, rec.AdoptedHead, why, redHeads, rec.AdoptReopenedAt, now)
if _, _, err := c.gh.Issues.CreateComment(ctx, owner, repo, number, &gh.IssueComment{Body: gh.Ptr(body)}); err != nil {
if _, _, err := c.gh.Issues.CreateComment(ctx, owner, repo, number, &gh.IssueComment{Body: gh.Ptr(preview)}); err != nil { // writeback:gated
c.warn("stage labels: close-first held note failed", append(logArgs, "error", err)...)
return 0, err
}
return 1, nil
}
if _, _, err := c.gh.PullRequests.Edit(ctx, owner, repo, number, &gh.PullRequest{State: gh.Ptr("open")}); err != nil {
if _, _, err := c.gh.PullRequests.Edit(ctx, owner, repo, number, &gh.PullRequest{State: gh.Ptr("open")}); err != nil { // writeback:gated
c.warn("stage labels: reopening superseded original failed", append(logArgs, "error", err)...)
return 0, err
}
Expand All @@ -268,18 +301,39 @@
c.warn("stage labels: hive's copy failed; original reopened for a person", logArgs...)
comments := 0
var firstErr error
body := AdoptionCopyFailedComment(number, copy, rec.AdoptedHead, why, redHeads)
if _, _, err := c.gh.Issues.CreateComment(ctx, owner, repo, number, &gh.IssueComment{Body: gh.Ptr(body)}); err != nil {
if _, _, err := c.gh.Issues.CreateComment(ctx, owner, repo, number, &gh.IssueComment{Body: gh.Ptr(preview)}); err != nil { // writeback:gated
c.warn("stage labels: reopen note failed", append(logArgs, "error", err)...)
firstErr = err
} else {
comments++
}
if _, err := c.gh.Issues.RemoveLabelForIssue(ctx, owner, repo, number, url.PathEscape(hgithub.SupersededLabel)); err != nil && !isGitHubStatus(err, http.StatusNotFound) {
if _, err := c.gh.Issues.RemoveLabelForIssue(ctx, owner, repo, number, url.PathEscape(hgithub.SupersededLabel)); err != nil && !isGitHubStatus(err, http.StatusNotFound) { // writeback:gated
c.warn("stage labels: removing superseded label failed", append(logArgs, "label", hgithub.SupersededLabel, "error", err)...)
if firstErr == nil {
firstErr = err
}
}
return comments, firstErr
}

// closeFirstOriginalItem is the gate's view of a closed original. No lane
// lists a closed PR, so with a gate installed it is read once here (the
// labels decide the opt-in); without one, or when the read fails, the bare
// number stands in, which the gate treats as carrying no opt-in label.
func (c *Engine) closeFirstOriginalItem(ctx context.Context, cand closeFirstRecord) writeback.Item {
item := writeback.Item{Number: cand.number, IsPR: true}
if c.writebackGate() == nil {
return item
}
pr, _, err := c.gh.PullRequests.Get(ctx, cand.owner, cand.repo, cand.number)
if err != nil || pr == nil {
c.warn("stage labels: close-first original lookup for the write-back gate failed", "repo", cand.owner+"/"+cand.repo, "pr", cand.number, "error", err)
return item
}
item.Author = pr.GetUser().GetLogin()
for _, l := range pr.Labels {
item.Labels = append(item.Labels, l.GetName())
}
item.CreatedAt = pr.GetCreatedAt().Time
return item
}
Loading
Loading