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-blocked-repair-writeback-gate.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Blocked sweep: a `blocked` label the hive applied itself, with nothing naming what the issue waits on, is now turned into a `needs-human` ask on every issue, including one created before the hive could write to the repository and one without the review opt-in label. The repair went through the write-back gate as `gate_comment`, so the backfill guard (`writeback.unsolicited.backfill` off) and the opt-in label requirement refused it on every sweep, although the hive had already labelled the issue; the issue stayed `blocked`, out of every agent's reach and in no inbox, for days. The repair is now its own write-back kind, `blocked_repair` (`writeback.kinds.blocked_repair`, default minimum level 1, shown in Settings → Features → Write-back containment and settable with the admin MCP `writeback.kind_policy`): when the sweep has established that the hive's own bot applied the label, neither of those two checks applies. A paused repository, `writeback.per_repo` mode `off`, `issues-only` or `labels-only`, a repository outside `project.repos`, `own_only`, the kind's minimum level and the notification burst hold still refuse it, and a person's `blocked` is left alone as before. A held repair is logged once per issue and reason (`blocked sweep: needs-human ask held by writeback gate`) instead of on every sweep; repeats go to the debug log.
9 changes: 9 additions & 0 deletions src/docs/acmm-policy-matrix.md
Original file line number Diff line number Diff line change
Expand Up @@ -274,6 +274,7 @@ gated. Defaults (override under `writeback.kinds.<kind>`):
| `claim_comment` | — | opt-in label | opt-in label | opt-in label |
| `welcome_comment` | — | — | opt-in label | all items |
| `issue_file` (new hive-authored issues) | L3+ | yes | yes | yes |
| `blocked_repair` (a `blocked` label the hive applied itself, with no blocker named) | L1+ | yes | yes | yes |

`ci_rerun` also covers the one transient re-run of a red PR from
`auto_merge.trusted_bot_authors` (a hive PR is its own item and is not gated):
Expand All @@ -283,6 +284,14 @@ hands the PR to a person with the reason. `bot_rebase_request` only ticks
Renovate's rebase/retry box; a stranded Dependabot PR is handed to a person
instead, because Dependabot refuses commands from apps.

`blocked_repair` replaces a marker-less `blocked` the hive applied with a
`needs-human` ask (see
[`blocked`](labels-and-control-signals/reference.md#blocked)). It needs no
opt-in label and ignores the backfill guard, because the hive has already
written to that issue: a contributor relay applies the label with a task
token at any level, so the repair has the lowest floor. On an issue whose
`blocked` the hive did not apply, the kind is never used.

In practice: **L4 means hive files issues and talks only on its own PRs**;
**L5 adds comments and labels on PRs a maintainer labelled `hive-review`**;
**L6 lets sentinel and welcome comments reach unlabelled PRs**. A repo
Expand Down
9 changes: 8 additions & 1 deletion src/docs/labels-and-control-signals/reference.md

Large diffs are not rendered by default.

10 changes: 6 additions & 4 deletions src/docs/operator-reference/sweeps-and-operations.md
Original file line number Diff line number Diff line change
Expand Up @@ -550,7 +550,8 @@ that level, the power the write-back exists to govern?
| 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 (an agent-authored original closes without the label, `adoption.close_superseded: on_adopt`); 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 |
| Gate comments (`pkg/scheduler/clarity_gate.go`, `prior_art_gate.go`, `triage.go`, `verdict_blocker.go`, `pr_blocked_depends_on.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 |
| Blocked repair (`pkg/github/issue_blocked.go`) | blocked sweep (every 5 min) and the blocked reconcile after each stage-label sync | `needs-human` added, `blocked` removed, one `<!-- hive:unblocked -->` note asking a maintainer to name the dependency or re-queue the issue | open issues whose `blocked` the hive's own bot applied and that name nothing they wait on (no blocked-on marker, deadline, ops-tracking marker or native "blocked by" link; not a review-backlog item) | `blocked_repair` → L1, no opt-in label and no backfill guard, because the hive already wrote the label being repaired; a pause, `per_repo.mode` `off` / `issues-only` / `labels-only` and a raised `min_level` still refuse it. Refused: the issue keeps `blocked` and the hold is logged once per issue and reason |
| Welcome / outreach (`pkg/gfi`, `gfi_forge.go`, `pr_clanker_requested.go`) | good-first-issue selection | welcome comment, `good first issue` label | issues hive advertises | `welcome_comment` → L5 with label, L6 without |
| Issue filing (`pkg/upstreamwatch/github_filer.go`, `advisory.go`, scanner/deps/regression agents, `dedupe_advisory_close.go`) | agents, advisory digest, upstream watch | **new** issues hive authors, pinned advisory issue + comments | `project.repos` | `issue_file` → L3, no label (this is what listing a repo opts in to; `per_repo.mode: issues-only` keeps only this) |
| Code scanning sweep (`pkg/github/code_scanning.go`, `pkg/codescanning`) | hourly sweep (`code_scanning`, opt-in per repo) | **new** grouped issues from code scanning alerts, alert-table body edits, one closing comment + close when every alert is fixed or dismissed | the hive's own `hive/code-scanning` issues in repos with `code_scanning` on | `issue_file` → L3, no label (own items); see [code-scanning.md](../code-scanning.md) |
Expand Down Expand Up @@ -610,9 +611,10 @@ Policy decides whether a kind may write to an item; the content layer under
only to comment kinds whose body the caller handed the gate as the preview
(`sentinel`, `needs_decision_comment`, `supersession_notice`,
`duplicate_fix_notice`, `reporter_trust_hold`, `contributor_adopt`,
`claim_comment`, `gate_comment`, `welcome_comment`); `Allowed()` without a
preview — labels, closes, hold-gate upkeep, task-list edits — stays
policy-only. Three checks run after the policy gate allows a write:
`claim_comment`, `gate_comment`, `welcome_comment`, `blocked_repair`);
`Allowed()` without a preview — labels, closes, hold-gate upkeep, task-list
edits — stays policy-only. Three checks run after the policy gate allows a
write:

| Check | Key | Suppression reason | Default |
|---|---|---|---|
Expand Down
30 changes: 26 additions & 4 deletions src/pkg/github/issue_blocked.go
Original file line number Diff line number Diff line change
Expand Up @@ -471,6 +471,7 @@ func (c *Client) SweepBlockedIssues(ctx context.Context, opts BlockedSweepOption
})
}
}
c.retainBlockedRepairHeld(repos, targets)
return c.reconcileBlockedTargets(ctx, targets, c.logger), nil
}

Expand Down Expand Up @@ -532,6 +533,8 @@ func (c *Client) reconcileBlockedTargets(ctx context.Context, targets []blockedI
stripBlockedHelpWanted(ctx, c, t, &res, logger)
continue
}
// A block that names what it waits on is not one the repair converts.
forgetBlockedRepairHeld(c, t)
if onIssue {
reconcileBlockedOnIssue(ctx, c, t, prRepo, prNumber, &res, logger)
continue
Expand Down Expand Up @@ -706,8 +709,17 @@ const blockedMarkerlessNote = blockedUnblockedMarker + "\nUnblocked: the `blocke
// and puts it in the maintainer inbox with the question. Only a hive-applied
// label with no open native "blocked by" link is converted; a person's
// marker-less block is theirs. Reports whether the issue was converted.
//
// The write-back gate is asked as blocked_repair with the fact established
// here, that the label is the hive's (Item.HiveAppliedBlock). The hive has
// already written to such an issue, so the gate does not hold the repair back
// for the issue predating the hive's write access or lacking the opt-in
// label; while it was asked as gate_comment both did, every sweep, and the
// issue stayed in the invisible state above for days. A pause, the repo mode
// and the kind's minimum level still refuse it.
func askHumanBlockedMarkerless(ctx context.Context, client *Client, t blockedIssueTarget, res *BlockedIssueResult, logger *slog.Logger) bool {
if t.reviewBacklog || t.openBlockedBy > 0 {
forgetBlockedRepairHeld(client, t)
return false
}
actor, found, err := client.blockedLabelActor(ctx, t.repo, t.number)
Expand All @@ -717,6 +729,7 @@ func askHumanBlockedMarkerless(ctx context.Context, client *Client, t blockedIss
return false
}
if !found || (!client.isOwnBotLogin(actor) && !client.IsHiveAuthorLogin(actor)) {
forgetBlockedRepairHeld(client, t)
return false
}
item, err := client.WritebackItemForNumber(ctx, t.repo, t.number)
Expand All @@ -725,14 +738,23 @@ func askHumanBlockedMarkerless(ctx context.Context, client *Client, t blockedIss
logger.Warn("blocked sweep: item lookup failed; marker-less block left alone", "repo", t.repo, "issue", t.number, "error", err)
return false
}
owner, name := client.splitRepo(t.repo)
if d := client.WritebackAllowed(owner+"/"+name, item, writeback.KindGateComment, blockedMarkerlessAskNote); !d.Allowed {
item.HiveAppliedBlock = true
gateRepo := client.blockedRepairRepo(t.repo)
if d := client.WritebackAllowed(gateRepo, item, writeback.KindBlockedRepair, blockedMarkerlessAskNote); !d.Allowed {
// The burst hold lets a couple of asks per repo through per sweep,
// and a failed write's retry is a duplicate for same_item_ttl; both
// clear on a later sweep. Say so rather than fall through silently.
logger.Info("blocked sweep: needs-human ask held by writeback gate", "repo", t.repo, "issue", t.number, "reason", d.Reason, "detail", d.Detail)
// clear on a later sweep. Say so rather than fall through silently,
// but once per issue and reason: the sweep asks again every few
// minutes, and a hold that lasts (a pause, the repo mode, the level)
// would repeat the line each time. Repeats go to the debug log.
level := slog.LevelDebug
if client.WritebackGate().NoteHeld(gateRepo, t.number, writeback.KindBlockedRepair, d.Reason) {
level = slog.LevelInfo
}
logger.Log(ctx, level, "blocked sweep: needs-human ask held by writeback gate", "repo", t.repo, "issue", t.number, "reason", d.Reason, "detail", d.Detail)
return false
}
forgetBlockedRepairHeld(client, t)
if !issueHasLabel(t.labels, issueNeedsHumanLabel) {
if err := client.AddLabels(ctx, t.repo, t.number, []string{issueNeedsHumanLabel}); err != nil { // writeback:gated
res.Errors++
Expand Down
51 changes: 51 additions & 0 deletions src/pkg/github/issue_blocked_repair_held.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
package github

import (
"strings"

"github.com/hivecommons/hive/pkg/writeback"
)

// The blocked sweep asks the write-back gate about every marker-less
// hive-applied block on every pass, and a refusal that lasts would be logged
// each time. The gate remembers the reason it last refused each issue for
// (writeback.Gate.NoteHeld); these helpers keep that memory in step with the
// sweep, so a hold is reported once per issue and reason and again after the
// issue stopped being one the repair converts.

// blockedRepairRepo is repo as owner/name, the form the gate is asked with.
func (c *Client) blockedRepairRepo(repo string) string {
owner, name := c.splitRepo(repo)
return owner + "/" + name
}

// forgetBlockedRepairHeld drops the hold remembered for t: the repair went
// through, or t is no longer a block the repair converts (it names what it
// waits on, a person applied it, it is a review-backlog item). A later hold
// is then logged again.
func forgetBlockedRepairHeld(client *Client, t blockedIssueTarget) {
client.WritebackGate().ForgetHeld(client.blockedRepairRepo(t.repo), t.number, writeback.KindBlockedRepair)
}

// retainBlockedRepairHeld forgets the holds of issues in repos that targets,
// the complete listing of open `blocked` issues in those repos, no longer
// contains: an issue that was closed, or whose label was removed, never
// reaches the repair again. A repo outside this listing keeps its holds, so
// a sweep of some repos does not forget the others.
func (c *Client) retainBlockedRepairHeld(repos []string, targets []blockedIssueTarget) {
gate := c.WritebackGate()
if gate == nil {
return
}
listed := make(map[string]bool, len(repos))
for _, repo := range repos {
listed[strings.ToLower(c.blockedRepairRepo(repo))] = true
}
open := make(map[string]bool, len(targets))
for _, t := range targets {
open[blockedOnSeenKey(c.blockedRepairRepo(t.repo), t.number)] = true
}
gate.RetainHeld(writeback.KindBlockedRepair, func(repo string, number int) bool {
return !listed[repo] || open[blockedOnSeenKey(repo, number)]
})
}
Loading
Loading