diff --git a/changelog.d/fixed-needs-sha-gate.md b/changelog.d/fixed-needs-sha-gate.md new file mode 100644 index 0000000000..83461ef9f2 --- /dev/null +++ b/changelog.d/fixed-needs-sha-gate.md @@ -0,0 +1 @@ +- `needs-sha` now keeps the hive off an issue until the reporter adds a commit SHA, whatever the reporter-trust setting: an issue wearing it (the configured `issues.sha_hold_trusted_label`, default `needs-sha`) leaves every agent work lane, so nothing implements, decomposes or claims it. The SHA-hold sweep removes the label once a SHA appears, which releases the issue. This restores the safety the old `hold` gave after #18542 stopped the hive applying `hold`. The label is created with the description "Waiting on the reporter for the commit SHA; hive won't work this until it's added." diff --git a/src/docs/labels-and-control-signals/glossary-and-operations.md b/src/docs/labels-and-control-signals/glossary-and-operations.md index fefc5877bd..7a0ff58037 100644 --- a/src/docs/labels-and-control-signals/glossary-and-operations.md +++ b/src/docs/labels-and-control-signals/glossary-and-operations.md @@ -135,7 +135,7 @@ Some sweeps list items themselves. They still use the same hold predicate (`Clie - Auto-merge sweeps use `Transport.IsHeldLabels`. The queued (`lgtm`) sweep skips a held PR before fetching it; the self-authored sweep skips held PRs and `needs-human` before merge (`src/pkg/github/automerge/automerge_sweep.go:23-38`, `src/pkg/github/automerge/automerge_sweep.go:954-959`, `src/pkg/github/automerge/automerge_sweep_loop.go:13-48`, `src/pkg/github/automerge/automerge_sweep_loop.go:73-92`). - The task-list sweep skips held issues before its exempt / issue `needs-human` gate. It does not comment on, relabel or close them (`src/pkg/github/task_list_sweep.go:848-854`). -- The SHA-hold sweep lists primary-repo `kind/bug` issues itself. Without a SHA it adds `issues.sha_hold_trusted_label` (default `needs-sha`) and a marker notice for every reporter; it never applies `hold` (#18468; before that, untrusted reporters got literal `hold`, #12002). It removes only its own current hold: the newest label event must be a `labeled` by the App bot with an App-authored SHA-hold notice at or after it (`EnforceSHAHold` / `shaHoldIsOwn` in `src/pkg/github/client.go`). +- The SHA-hold sweep lists primary-repo `kind/bug` issues itself. Without a SHA it adds `issues.sha_hold_trusted_label` (default `needs-sha`) and a marker notice for every reporter; it never applies `hold`, and `needs-sha` keeps agents off the issue until it is removed (#18468; before that, untrusted reporters got literal `hold`, #12002). It removes only its own current hold: the newest label event must be a `labeled` by the App bot with an App-authored SHA-hold notice at or after it (`EnforceSHAHold` / `shaHoldIsOwn` in `src/pkg/github/client.go`). - PR-request watching applies server-side holds after creation; the wrapper discards an agent's `--label hold` (`src/pkg/github/pr_request_watcher.go:452-524`, `bin/hive-open-pr.sh:142-150`). Policy templates also say to respect `hold`, `on-hold`, `hold/review`, `hive-pause/`, any label containing `hold`, and exempt `do-not-merge`. That instruction is a prompt-level backstop; enumeration and sweep checks are the hard enforcement. diff --git a/src/docs/labels-and-control-signals/reference.md b/src/docs/labels-and-control-signals/reference.md index 316ff3e8dc..c4b71de76f 100644 --- a/src/docs/labels-and-control-signals/reference.md +++ b/src/docs/labels-and-control-signals/reference.md @@ -191,7 +191,7 @@ Commit committer dates and SHA-keyed `check_suite` / `status` times are never us **Applies to:** Issues. **Kind:** Hard issue hold. -Since [#18468](https://github.com/hivecommons/hive/issues/18468) the sweep gives every reporter the `needs-sha` label below and never applies `hold`; an untrusted reporter's issue stays out of automatic work through the reporter-trust gate. Before that, human-filed primary-repo `kind/bug` without a 7-40 hex SHA got `hold` and a notice carrying ``; once a SHA appears in body/comments, Hive removes `hold` only if the current hold is its own (newest `hold` event labeled by the App bot, paired with an App-authored notice at or after it). A human's hold, a re-hold, or another subsystem's hold stays. Reporters whose author association is trusted (`issue_filter.reporter_trust.trusted_associations`, default OWNER/MEMBER/COLLABORATOR) get the soft `needs-sha` row below instead, and a SHA-hold `hold` already on such an issue is swapped for it (#12002). +Since [#18468](https://github.com/hivecommons/hive/issues/18468) the sweep gives every reporter the `needs-sha` label below and never applies `hold`; `needs-sha` itself keeps the issue out of agent work with reporter trust on or off. Before that, human-filed primary-repo `kind/bug` without a 7-40 hex SHA got `hold` and a notice carrying ``; once a SHA appears in body/comments, Hive removes `hold` only if the current hold is its own (newest `hold` event labeled by the App bot, paired with an App-authored notice at or after it). A human's hold, a re-hold, or another subsystem's hold stays. Reporters whose author association is trusted (`issue_filter.reporter_trust.trusted_associations`, default OWNER/MEMBER/COLLABORATOR) get the soft `needs-sha` row below instead, and a SHA-hold `hold` already on such an issue is swapped for it (#12002). The hard-suppress reconcile also lifts this `hold` once a PR referencing the issue merges after it was applied. @@ -205,9 +205,9 @@ The hard-suppress reconcile also lifts this `hold` once a PR referencing the iss #### `needs-sha` from SHA-hold -**Applies to:** Issues. **Kind:** Soft (informational). +**Applies to:** Issues. **Kind:** Hard (issue gate; not a PR merge gate). -Trusted-reporter `kind/bug` without a SHA gets this soft label plus the same `` notice instead of `hold`; the issue stays actionable. The sweep removes it once a SHA appears. +A `kind/bug` without a SHA gets this label plus the `` notice. While it is on the issue no agent implements, decomposes or claims it, whatever the reporter-trust setting; the issue shows as filtered in the work list. The sweep removes it once a SHA appears, which releases the issue. Description: "Waiting on the reporter for the commit SHA; hive won't work this until it's added." **Who applies it:** Hive. diff --git a/src/docs/operator-reference/README.md b/src/docs/operator-reference/README.md index ca55cd255b..6a22d3d121 100644 --- a/src/docs/operator-reference/README.md +++ b/src/docs/operator-reference/README.md @@ -207,7 +207,7 @@ Top-level YAML keys accepted by `config.Config`: | `dedupe.advisory_autoclose` | `true`. | The close-on-merge backfill works the dedupe agent's advisory checklists itself ([#15754](https://github.com/hivecommons/hive/issues/15754)): for every open hive-authored issue whose body opens with `` it ticks each `- [ ] #N …` task line whose #N is closed or merged (one body edit per sweep, idempotent) and, once every line is ticked, comments `All N items resolved (#a closed, #b merged …) — closing this advisory.` and closes the issue as `completed`. A checklist with open items expires after seven days. The Activity Monitor never parks an advisory at 045 regardless. `false` leaves checklists untouched (they still expire). Env/dashboard: yaml-only. | | `issues.close_on_merge_recheck` | `24h`. | How long a merged-PR claim keeps its settled close-on-merge verdict before the ledger sweep re-verifies it against the API. Once a sweep reaches a final verdict for a claim — issue closed, already closed, Hive marker present, awaiting confirmation, untrusted author, reopened by a person, or PR not merged — it stamps `close_on_merge_settled_at` on the claim and later sweeps skip the claim with no API call until this window elapses. Transient failures (issue, timeline or comment reads/writes that errored) never settle and retry on the next sweep as before. The marker follows the claim while the same PR claims the issue and resets when a different PR takes it over. Env override: `HIVE_CLOSE_ON_MERGE_RECHECK` (Go duration). | | `issues.reporter_confirmation` | `false`. | Legacy opt-in switch for hives that want every human-filed bug-family issue to wait for reporter verification before close. Leave false for the default close-on-merge policy; add `hive: needs-confirmation` to an individual issue when only that issue needs the gate. `hive: reporter-confirmed` and `hive: close-on-merge` remain accepted legacy bypasses. | -| `issues.sha_hold_trusted_label` | `needs-sha`. | Soft label the SHA-hold sweep applies to a `kind/bug` without a commit SHA when the reporter's author association is in `project.issue_filter.reporter_trust.trusted_associations` (default OWNER/MEMBER/COLLABORATOR), instead of the hard `hold` (#12002). The notice is the same; the issue stays actionable. A SHA-hold `hold` already on such an issue is swapped for this label. Set to `hold` to restore the hard hold for every reporter. | +| `issues.sha_hold_trusted_label` | `needs-sha`. | Soft label the SHA-hold sweep applies to a `kind/bug` without a commit SHA when the reporter's author association is in `project.issue_filter.reporter_trust.trusted_associations` (default OWNER/MEMBER/COLLABORATOR), instead of the hard `hold` (#12002). The label keeps the issue out of agent work until it is removed. A SHA-hold `hold` already on such an issue is swapped for this label. Set to `hold` to restore the hard hold for every reporter. | | `issues.lift_hive_hard_suppress` | `true`. | Runs the hard-suppress reconcile (#12002): a `hold` or `blocked` label on an open issue is lifted when Hive provably applied it (newest label event is a `labeled` by the App bot; for `hold`, paired with the `` notice) and a PR cross-referencing the issue merged after it. Hive posts one note carrying ``. Human-applied labels are never lifted. Skipped with the other unstick steps when the API budget is critical. | | `issues.hard_suppress_reconcile_interval` | `30m`. | Minimum time between hard-suppress reconcile passes. | | `issues.rfc_existing_check.enabled` | `false`. | Triage existing-coverage check (#13575): new open issues labelled `rfc`, `enhancement` or `kind/feature` get one comment that lists the existing settings that may already cover the request. Each setting links to Settings with the search set to its key. The comment carries `` and is never posted twice. The check never labels or closes issues. Tuning keys are `post_when_nothing_found`, `labels`, `max_matches` and `max_age`; see [Triage: does this RFC already exist?](../settings.md#triage-does-this-rfc-already-exist). | diff --git a/src/docs/scale-envelope.md b/src/docs/scale-envelope.md index e3e391f987..4a3216023a 100644 --- a/src/docs/scale-envelope.md +++ b/src/docs/scale-envelope.md @@ -34,7 +34,7 @@ ones to: 2. **Truncation must preserve the prioritization signal, not cut an arbitrary slice.** This holds today and is easy to assume backwards: - Issues are sorted by actionable rank tier, then **oldest first** within each tier before any cap is applied - (`RankActionableIssues`, `src/pkg/github/client.go:5286-5296`, descending `AgeMinutes` within each tier). + (`RankActionableIssues`, `src/pkg/github/client.go:5336-5346`, descending `AgeMinutes` within each tier). - PRs are sorted by **review class then oldest-first within class** (`SortPullRequestsForReview`, `src/pkg/github/review_priority.go:334`; fixes → refactors/docs → tests). diff --git a/src/pkg/github/client.go b/src/pkg/github/client.go index 5a956bfbca..e12904495c 100644 --- a/src/pkg/github/client.go +++ b/src/pkg/github/client.go @@ -132,6 +132,9 @@ type Client struct { issueFilter IssueAdmitter agentIssueDecisionPolicyMu sync.RWMutex agentIssueDecisionPolicy string + // needsSHALabelName is the configured SHA-hold label, recorded by each + // EnforceSHAHold sweep (guarded by issueFilterMu). Empty means the default. + needsSHALabelName string // reporterConfirmationEnabled restores the legacy close gate for all // human-filed bug-family issues when configured. Nil/false means only // per-issue opt-in markers activate the gate. @@ -1975,6 +1978,13 @@ func (c *Client) fetchIssues(ctx context.Context, repo string, now time.Time, re details = append(details, c.workIssue(repo, issue, labels, "filtered", issueNeedsReporterConfirmationLabel)) continue } + // needs-sha: waiting on the reporter for a commit SHA. Out of every + // agent lane whatever the reporter-trust setting (hivecommons/hive#18542). + if label := c.needsSHALabelOn(labels); label != "" { + breakdown.Filtered++ + details = append(details, c.workIssue(repo, issue, labels, "filtered", label)) + continue + } if suppress := hardSuppressIssueBucket(issueFilter, labels); suppress != "" { breakdown.Filtered++ breakdown.addHardSuppress(suppress) @@ -4692,6 +4702,43 @@ type SHAHoldResult struct { // configured (config.DefaultSHAHoldTrustedLabel). const defaultSHAHoldLabel = "needs-sha" +// NeedsSHALabelDescription is the repo label description for the SHA-hold label. +const NeedsSHALabelDescription = "Waiting on the reporter for the commit SHA; hive won't work this until it's added." + +// needsSHALabelOn returns the SHA-hold label the labels carry (the configured +// name, or the default name), or "" when none. An issue wearing it is parked +// on the reporter and kept out of agent work lanes. +func (c *Client) needsSHALabelOn(labels []string) string { + c.issueFilterMu.RLock() + configured := c.needsSHALabelName + c.issueFilterMu.RUnlock() + for _, name := range []string{configured, defaultSHAHoldLabel} { + if name = strings.TrimSpace(name); name == "" { + continue + } + for _, l := range labels { + if strings.EqualFold(strings.TrimSpace(l), name) { + return name + } + } + } + return "" +} + +func (c *Client) setNeedsSHALabel(name string) { + c.issueFilterMu.Lock() + c.needsSHALabelName = strings.TrimSpace(name) + c.issueFilterMu.Unlock() +} + +// ensureNeedsSHALabel creates the SHA-hold label with its description when +// the repo lacks it. Best effort: the label add that follows still works. +func (c *Client) ensureNeedsSHALabel(ctx context.Context, owner, repo, name string) { + if err := c.EnsureIssueLabel(ctx, owner+"/"+repo, name, "fbca04", NeedsSHALabelDescription); err != nil { + c.logger.Warn("could not ensure SHA-hold label", "repo", repo, "label", name, "error", err) + } +} + // shaHoldLabel returns the label the sweep applies to an issue missing a SHA. // It is never `hold`: a `hold` means a person said hands-off, and the hive // no longer applies one itself (hivecommons/hive#18468). Before #18468 an @@ -4714,6 +4761,7 @@ func (c *Client) EnforceSHAHold(ctx context.Context, cfg SHAHoldConfig) (*SHAHol } result := &SHAHoldResult{} owner, repo := c.splitRepo(cfg.PrimaryRepo) + c.setNeedsSHALabel(cfg.shaHoldLabel()) opts := &gh.IssueListByRepoOptions{ State: "open", @@ -4771,6 +4819,7 @@ func (c *Client) enforceSoftSHAHold(ctx context.Context, owner, repo string, num return } if !hasSHA && !softHeld { + c.ensureNeedsSHALabel(ctx, owner, repo, soft) if _, _, err := c.client.Issues.AddLabelsToIssue(ctx, owner, repo, number, []string{soft}); err != nil { c.logger.Warn("failed to add soft SHA label", "repo", repo, "issue", number, "label", soft, "error", err) result.Skipped++ @@ -4797,6 +4846,7 @@ func (c *Client) enforceSoftSHAHold(ctx context.Context, owner, repo string, num result.Unheld++ c.logger.Info("SHA-UNHOLD", "repo", repo, "issue", number, "author", author, "label", soft) case !hasSHA && !softHeld: + c.ensureNeedsSHALabel(ctx, owner, repo, soft) if _, _, err := c.client.Issues.AddLabelsToIssue(ctx, owner, repo, number, []string{soft}); err != nil { c.logger.Warn("failed to add soft SHA label", "repo", repo, "issue", number, "label", soft, "error", err) result.Skipped++ diff --git a/src/pkg/github/labels.go b/src/pkg/github/labels.go index 3bf91b6773..d488205145 100644 --- a/src/pkg/github/labels.go +++ b/src/pkg/github/labels.go @@ -136,6 +136,10 @@ var escalationIssueLabelDefinitions = map[string]issueLabelDefinition{ color: "fbca04", description: "Hive is waiting for the issue reporter or a maintainer to confirm the fix", }, + defaultSHAHoldLabel: { + color: "fbca04", + description: NeedsSHALabelDescription, + }, issueNeedsSpecLabel: { color: "bfd4f2", description: "Hive needs a specification or acceptance criteria before continuing", diff --git a/src/pkg/github/needs_sha_gate_test.go b/src/pkg/github/needs_sha_gate_test.go new file mode 100644 index 0000000000..7f4f137e28 --- /dev/null +++ b/src/pkg/github/needs_sha_gate_test.go @@ -0,0 +1,92 @@ +package github + +import ( + "context" + "net/http" + "net/http/httptest" + "testing" + "time" + + gh "github.com/google/go-github/v72/github" + "github.com/hivecommons/hive/pkg/config" +) + +func needsSHAIssues() []wireIssue { + return []wireIssue{ + {Number: 1, Title: "bug without sha", User: wireUser{"maintainer"}, AuthorAssociation: "MEMBER", + Labels: []wireLabel{{Name: "kind/bug"}, {Name: "needs-sha"}}, CreatedAt: hoursAgo(3)}, + {Number: 2, Title: "bug with sha supplied", User: wireUser{"maintainer"}, AuthorAssociation: "MEMBER", + Labels: []wireLabel{{Name: "kind/bug"}}, CreatedAt: hoursAgo(2)}, + } +} + +func enumerateNeedsSHA(t *testing.T, f config.IssueFilterConfig, label string) *ActionableResult { + t.Helper() + org, repo := "testorg", "testrepo" + server := httptest.NewServer(buildMux(t, org, repo, needsSHAIssues(), nil)) + t.Cleanup(server.Close) + c := newTestClient(t, server, org, []string{repo}) + c.SetIssueFilter(f) + if label != "" { + c.setNeedsSHALabel(label) + } + result, err := c.EnumerateActionable(context.Background()) + if err != nil { + t.Fatalf("EnumerateActionable: %v", err) + } + return result +} + +// A needs-sha issue is never dispatched, with reporter trust on or off; the +// issue whose label was removed (a SHA arrived) is workable. +func TestEnumerateActionable_NeedsSHAKeepsIssueOutOfWork(t *testing.T) { + cases := map[string]config.IssueFilterConfig{ + "reporter trust off": {}, + "reporter trust on": enabledReporterTrust(), + } + for name, f := range cases { + t.Run(name, func(t *testing.T) { + nums := actionableNumbers(enumerateNeedsSHA(t, f, "")) + if nums[1] { + t.Error("needs-sha issue entered the actionable set") + } + if !nums[2] { + t.Error("positive control failed: the issue without needs-sha must be actionable") + } + }) + } +} + +func TestEnumerateActionable_NeedsSHAConfiguredName(t *testing.T) { + org, repo := "testorg", "testrepo" + issues := needsSHAIssues() + issues[0].Labels = []wireLabel{{Name: "kind/bug"}, {Name: "awaiting-sha"}} + server := httptest.NewServer(buildMux(t, org, repo, issues, nil)) + t.Cleanup(server.Close) + c := newTestClient(t, server, org, []string{repo}) + c.setNeedsSHALabel("awaiting-sha") + result, err := c.EnumerateActionable(context.Background()) + if err != nil { + t.Fatalf("EnumerateActionable: %v", err) + } + if actionableNumbers(result)[1] { + t.Error("issue wearing the configured SHA label entered the actionable set") + } +} + +func TestClassifyWebhookIssue_NeedsSHASidelined(t *testing.T) { + c := newTestClient(t, httptest.NewServer(http.NotFoundHandler()), "o", []string{"r"}) + for name, f := range map[string]config.IssueFilterConfig{"off": {}, "on": enabledReporterTrust()} { + t.Run(name, func(t *testing.T) { + c.SetIssueFilter(f) + issue := &gh.Issue{Number: gh.Ptr(7), State: gh.Ptr("open"), Title: gh.Ptr("bug"), + User: &gh.User{Login: gh.Ptr("maintainer")}, AuthorAssociation: gh.Ptr("MEMBER"), + Labels: []*gh.Label{{Name: gh.Ptr("kind/bug")}, {Name: gh.Ptr("needs-sha")}}, + CreatedAt: &gh.Timestamp{Time: time.Now().Add(-time.Hour)}} + p := c.classifyWebhookIssue("o/r", issue, issueLabelNames(issue.Labels), time.Now()) + if p.Bucket != WebhookBucketSidelined || p.WorkIssue == nil || p.WorkIssue.Reason != "needs-sha" { + t.Fatalf("patch = %+v, want sidelined with reason needs-sha", p) + } + }) + } +} diff --git a/src/pkg/github/webhook_item_patch.go b/src/pkg/github/webhook_item_patch.go index 46691c73c6..8b94746828 100644 --- a/src/pkg/github/webhook_item_patch.go +++ b/src/pkg/github/webhook_item_patch.go @@ -93,6 +93,9 @@ func (c *Client) classifyWebhookIssue(repo string, issue *gh.Issue, labels []str if labelPresent(labels, issueNeedsReporterConfirmationLabel) { return sidelined("filtered", issueNeedsReporterConfirmationLabel) } + if label := c.needsSHALabelOn(labels); label != "" { + return sidelined("filtered", label) + } if suppress := hardSuppressIssueBucket(issueFilter, labels); suppress != "" { return sidelined("filtered", suppress) }