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/added-decide-issue-judgment.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- "Let hive decide" on a parked issue now judges the way the owner would: a fleet self-report whose remedy is the spoke operator's (expired provider login, credentials, disk, network, App setup) gets one direction comment to the spoke owner — no `approved-direction`, no implementer, the park kept, and never the same direction twice; a hive-filed proposal is approved when it cites an incident or a fixed-one-at-a-time recurrence and declined for now (closed as not planned) when it cites neither; a hive-policy item's recommendation is a real sentence instead of "no special rule applies".
11 changes: 10 additions & 1 deletion src/docs/dashboard-sections.md
Original file line number Diff line number Diff line change
Expand Up @@ -1273,7 +1273,16 @@ The rules live in one place — `src/pkg/delegatedecision/policy.go` (`PolicyTex

**Issues:** dedupe aggressively (`Duplicate of #N`, cross-link overlaps); secrets / PAT / org-permission items are owner-only — `needs-owner` + `hold` with one comment stating the exact owner action, and no more failure issues for that root cause; flaky tests are quarantined with a retry and a deflake task rather than blocking; CI hygiene gate proposals (actionlint, duplication ratchets, link-checker allowlists) are approved as ratchets (baseline; fail only on increases; warning-only briefly, then enforce); design proposals with concrete acceptance criteria are accepted as proposed with explicit defaults; a "review backlog" item is never auto-closed when its PR closes unmerged (drop the relation, comment, re-triage).

Each decision names the rule that fired (`dedupe`, `owner-only`, `flaky-test`, `ci-ratchet`, `design-proposal`, `review-backlog`, `default-approve`, `prefer-contributor`, `contributor-offline`, `sentinel-trusted`, `small-low-risk`, `reporter-trust`, `fix-then-merge`, `default-release`, `hive-policy`, `sentinel-untrusted`, `rail-hold`) in the comment and in the job's `decision.rule`.
**Issues, judged the way the owner would** (the five parked issues he decided by hand; rules evaluated before `default-approve`, which stays the last fallback):

| shape | rule | what the hive does |
| --- | --- | --- |
| a fleet self-report (`<!-- hive:selfreport … -->` marker or `[selfreport]` title) whose class is an operator's to fix — `agent_login_required`, `inference_auth_failed`, `data_disk_pressure`, the GitHub App token / installation / coverage classes, proxy dial / TLS, `crux_runtime_unavailable`, model discovery, label provisioning, shared-CI rerun permission | `selfreport-operator-action` (verdict `operator-action`) | Not code work. One comment telling the owner(s) named in the report's table exactly what to do on *that* spoke ("@owner: re-authenticate the agent provider … on spoke-x"), `needs-owner` added, **no** `approved-direction`, no implementer, the `stage/045-needs-decision` park kept so the actionable set never sees it. It clears when the report stops recurring (or `/fixed`). Clicking *Let hive decide* again never re-posts the direction: the answer is *already decided at that time; waiting on the spoke owner: @owner …* (the #15021 loop). Code-defect classes (panics, repeated unclassified errors, stalls) stay on the implementer path. |
| a hive-filed proposal (`[quality]` / `[scanner]` / `[architect]` / `[strategist]` / `[outreach]` prefix, "Gate proposal", "RFC", or a `kind/design` / `kind/proposal` label) **with evidence** — an `incident #N`, breakage words (broke, regression, outage, uncompilable, blast radius), or a recurrence whose prior instances were each fixed one at a time ("fixed in #415", "Fixing PRs: #415, #417") | `proposal-approve-evidence` (verdict `approve`) | Approved as proposed; the rationale names the evidence ("it cites incident #15322", "the same class was already fixed one at a time in #415, #417"). |
| a hive-filed proposal **without** such evidence | `proposal-not-now` (verdict `not-now`) | Declined for now: a comment saying "no incident or recurrence justifies the cost yet; re-propose with evidence", then closed as not planned (the established declined-proposal path). Never applied to a person's proposal (those keep `default-approve`), never to the hive's own policy (`hive-policy` stays recommend-only). |
| a change to the hive's own policy (for example an RFC to hold unacknowledged hive-filed proposals) | `hive-policy` (recommend-only) | Unchanged in shape, but the recommendation is a real sentence in the owner's terms — "approve `<title>` as proposed — proposals nobody has acknowledged should not be actionable; make it default-on for the lanes it names rather than opt-in; owner to confirm" — never "no special rule applies". |

Each decision names the rule that fired (`dedupe`, `owner-only`, `flaky-test`, `ci-ratchet`, `design-proposal`, `review-backlog`, `selfreport-operator-action`, `proposal-approve-evidence`, `proposal-not-now`, `default-approve`, `prefer-contributor`, `contributor-offline`, `sentinel-trusted`, `small-low-risk`, `reporter-trust`, `fix-then-merge`, `default-release`, `hive-policy`, `sentinel-untrusted`, `rail-hold`) in the comment and in the job's `decision.rule`.

**Safety rails** (`ApplyRails`, applied after the policy and before anything is written): the delegate never merges a PR — it only records the approval the auto-merge engine already acts on per repository settings (a merger/owner requester's approval is written as the queue line the sweep parses; anyone else's as `/lgtm` + `/approve` comments attributed to them); it does not touch an item wearing `hold` (refused, nothing written — release the hold first if you want it decided); it never grants org membership, secrets or permissions (those items get `needs-owner` + `hold` and the one owner-action comment, and keep their park); and a question that is a policy or scope change to the hive itself (settings, governance docs, security posture — the `governance` label or those words in the park reason) is left parked: the delegate posts "hive recommends: …; owner to confirm" and keeps 085.

Expand Down
5 changes: 5 additions & 0 deletions src/docs/labels-and-control-signals.md
Original file line number Diff line number Diff line change
Expand Up @@ -2360,6 +2360,9 @@ The plain-words comment the delegate posts has four lines — **Hive decided** (
| `ci-ratchet` | a CI hygiene gate, landed as a ratchet | A new CI hygiene gate lands as a ratchet: it records today's baseline and fails only on increases, so existing work is never blocked. |
| `contributor-offline` | the author hasn't been reachable since the nudge | The PR's author (or their clanker or hive) has been offline since the hive nudged them, so the hive takes the work over instead of waiting. The decision itself names which: the author's clanker, a connected hive, or the author. |
| `dedupe` | an older issue already tracks this | An older issue already tracks the same work; one thread keeps it moving. |
| `proposal-approve-evidence` | a proposal backed by an incident or a repeated class; approved | The hive-filed proposal names an incident it would have prevented, or prior instances of the same class fixed one at a time, so its cost is justified and it is approved as proposed. |
| `proposal-not-now` | a hive-filed proposal with no incident or recurrence behind it; declined for now | The proposal shows neither an incident it would have prevented nor a repeated class it would end, so its value is speculative. The hive declines it for now and closes it as not planned; re-propose with evidence. |
| `selfreport-operator-action` | a spoke self-report only its operator can fix; not code work | The issue is a fleet self-report (expired login, credentials, disk, network, App setup) whose remedy is on the reporting spoke. The hive tells that spoke's owner what to do and keeps it out of the actionable set; no agent is sent to code. |
| `default-approve` | no special rule applies; the hive took its own recommendation | No owner rule singles this issue out, so the hive went with its own recommendation — the reversible choice that keeps work moving. |
| `default-release` | no special rule applies; a green branch is approved | No owner rule holds this PR back; its branch is green and a merge is reversible, so it is approved. |
| `design-proposal` | a proposal with clear acceptance criteria, accepted as written | The proposal states concrete acceptance criteria, so it is accepted as written; anything not stated keeps today's behaviour. |
Expand Down Expand Up @@ -2395,6 +2398,8 @@ The plain-words comment the delegate posts has four lines — **Hive decided** (
| `labels-add` | added labels | The hive added labels to the item. |
| `labels-remove` | removed labels | The hive removed labels from the item. |
| `link` | cross-linked a related item | The hive left a comment linking a related issue or PR. |
| `not-now`, `close-not-now` | declined for now; closed as not planned | The hive declined the proposal for now and closed it as not planned, with the reason and what evidence would reopen it. |
| `operator-action` | told the spoke owner what to do; nothing for an agent here | The hive named the spoke owner and the one action they take (for example re-authenticate the provider). The item stays parked, gets no approved-direction, and clears when the report stops recurring. |
| `quarantine-flaky` | quarantined the flaky test | The flaky test is quarantined with a retry and a deflake task is filed. |
| `recommend-only`, `recommended` | recommended only; a person confirms | The hive only recommended; the item stays parked until a person confirms. |
| `refused` | did not decide | The hive did not decide this item; its safety rails stopped it (for example, the item is on hold). |
Expand Down
46 changes: 38 additions & 8 deletions src/pkg/dashboard/api_repo_item_decide_delegated.go
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
package dashboard

import (
Expand Down Expand Up @@ -536,7 +536,11 @@
// approve at 20:41Z lifted 045; the scanner re-parked at 01:16Z
// with its own question; the dedup then called the fresh park
// "decided, but it hasn't taken effect" for hours).
if repark, ok := s.delegatedReparkedAfter(ctx, repoFull, number, prior.At); ok {
// A decision that kept the park never lifted the label, so a label
// event after it is not a new ask: re-deciding an operator-action
// self-report must not post the same direction again (the #15021
// loop); it answers "already decided; waiting on <who>".
if repark, ok := s.delegatedReparkedAfter(ctx, repoFull, number, prior.At); ok && !d.KeepsPark {
deciderNotes = append(deciderNotes, "parked again at "+repark.At.UTC().Truncate(time.Second).Format(time.RFC3339)+" ("+repark.Label+") after the decision recorded at "+prior.At.UTC().Truncate(time.Second).Format(time.RFC3339)+": a new ask, deciding anew")
prior = delegatedPriorState{}
}
Expand Down Expand Up @@ -815,23 +819,40 @@
}
}
notes = append(notes, "labels removed: "+strings.Join(a.Labels, ", "))
case delegatedecision.ActionCloseDuplicate:
case delegatedecision.ActionCloseDuplicate, delegatedecision.ActionCloseNotNow:
// Both share one comment-then-close path so the writeback
// ratchet (pkg/writeback/testdata) sees no new write sites.
notNow := a.Kind == delegatedecision.ActionCloseNotNow
body := fmt.Sprintf("%s\n\nRationale: %s.\n\n_Closed by the hive as the owner's delegate (rule `%s`)._\n%s", a.Text, d.Rationale, d.Rule, marker)
reason := "closed as duplicate of #" + strconv.Itoa(a.Target) + " by the hive delegate"
what := "duplicate"
if notNow {
if in.Kind != delegatedecision.KindIssue {
return notes, fmt.Errorf("not-now closes issues only")
}
body = comment
reason = "declined for now by the hive delegate: no incident or recurrence justifies the cost yet"
what = "not-now"
}
if err := client.CreateIssueComment(ctx, repoFull, number, body); err != nil {
return notes, fmt.Errorf("posting duplicate note: %w", err)
return notes, fmt.Errorf("posting %s note: %w", what, err)
}
if in.Kind == delegatedecision.KindPR {
if err := client.CloseSupersededPR(ctx, repoFull, number); err != nil {
return notes, fmt.Errorf("closing superseded PR: %w", err)
}
} else if err := client.CloseIssue(ctx, repoFull, number, ghpkg.IssueCloseOptions{
OverrideReason: "closed as duplicate of #" + strconv.Itoa(a.Target) + " by the hive delegate",
OverrideReason: reason,
SuppressOverrideComment: true,
StateReason: issueStateReasonNotPlanned,
}); err != nil {
return notes, fmt.Errorf("closing duplicate: %w", err)
return notes, fmt.Errorf("closing %s: %w", what, err)
}
if notNow {
notes = append(notes, "closed as not planned (declined for now)")
} else {
notes = append(notes, fmt.Sprintf("closed in favour of #%d", a.Target))
}
notes = append(notes, fmt.Sprintf("closed in favour of #%d", a.Target))
case delegatedecision.ActionLink:
body := fmt.Sprintf("Cross-link: %s (#%d).\n%s", a.Text, a.Target, marker)
if err := client.CreateIssueComment(ctx, repoFull, number, body); err != nil {
Expand Down Expand Up @@ -876,7 +897,15 @@
if err := client.CreateIssueComment(ctx, repoFull, number, comment); err != nil {
return notes, fmt.Errorf("posting recommendation: %w", err)
}
notes = append(notes, "recommendation posted; `"+delegatedecision.LabelNeedsDecision+"` kept for the owner")
park := delegatedecision.LabelNeedsDecision
if in.Kind == delegatedecision.KindIssue {
park = delegatedecision.LabelIssueNeedsDecision
}
if d.Verdict == delegatedecision.VerdictOperatorAction {
notes = append(notes, "operator direction posted; `"+park+"` kept, no approved-direction, no implementer")
} else {
notes = append(notes, "recommendation posted; `"+park+"` kept for the owner")
}
}
}
if lifted := s.liftDelegatedParkLabels(ctx, in, d); len(lifted) > 0 {
Expand All @@ -901,7 +930,8 @@
switch v {
case delegatedecision.VerdictApprove, delegatedecision.VerdictDirection, delegatedecision.VerdictAdoptSupersede,
delegatedecision.VerdictCloseDuplicate, delegatedecision.VerdictCloseSuperseded,
delegatedecision.VerdictQuarantineFlaky, delegatedecision.VerdictAcceptRatchet, delegatedecision.VerdictAcceptProposal:
delegatedecision.VerdictQuarantineFlaky, delegatedecision.VerdictAcceptRatchet, delegatedecision.VerdictAcceptProposal,
delegatedecision.VerdictNotNow:
return true
}
return false
Expand Down
6 changes: 6 additions & 0 deletions src/pkg/dashboard/api_repo_item_decide_delegated_plan.go
Original file line number Diff line number Diff line change
Expand Up @@ -204,6 +204,12 @@ func delegatedPlanWording(in delegatedecision.Input, d delegatedecision.Decision
return "Do nothing: " + delegatedPlanPlain(d.Rationale) + ".", []string{"Nothing changes; " + ref + " stays waiting for you."}
case d.Verdict == delegatedecision.VerdictOwnerOnly:
return "Leave this to the owner.", []string{"Hive labels " + ref + " needs-owner and holds it.", "Only the owner can grant this."}
case d.Verdict == delegatedecision.VerdictOperatorAction:
return "Tell the spoke owner what to do: " + delegatedPlanPlain(strings.TrimPrefix(strings.TrimSpace(d.Text), "operator action — ")) + ".",
[]string{"Hive posts that to the spoke owner and labels " + ref + " needs-owner; no agent is sent.", ref + " stays where it is and clears once the report stops recurring."}
case d.Verdict == delegatedecision.VerdictNotNow:
return "Decline " + ref + " for now and close it as not planned.",
[]string{"Hive posts why: no incident or recurrence justifies the cost yet.", ref + " is closed as not planned; re-propose it with evidence."}
default:
text := delegatedPlanPlain(d.Text)
if text == "" {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -158,7 +158,7 @@ func TestDelegatedPlanWordingDirectionIsOneSentence(t *testing.T) {
t.Fatalf("summary %q", s)
}
// Every verdict's then-list fits the two-item budget.
for _, v := range []delegatedecision.Verdict{delegatedecision.VerdictAdoptSupersede, delegatedecision.VerdictApprove, delegatedecision.VerdictCloseSuperseded, delegatedecision.VerdictRefused, delegatedecision.VerdictOwnerOnly, delegatedecision.VerdictRecommendOnly} {
for _, v := range []delegatedecision.Verdict{delegatedecision.VerdictAdoptSupersede, delegatedecision.VerdictApprove, delegatedecision.VerdictCloseSuperseded, delegatedecision.VerdictRefused, delegatedecision.VerdictOwnerOnly, delegatedecision.VerdictRecommendOnly, delegatedecision.VerdictOperatorAction, delegatedecision.VerdictNotNow} {
s, n := delegatedPlanWording(in, delegatedecision.Decision{Verdict: v, Rationale: "because (hivecommons/hive#1); and more", Text: "do the thing (hivecommons/hive#2)"})
if len(n) > 2 || strings.Contains(s, "Hive would") || strings.Contains(s, "#1)") || strings.Contains(s, "#2)") {
t.Errorf("%s: summary %q then %v", v, s, n)
Expand Down
Loading
Loading