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-delegate-competing-options.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- "Let hive decide" no longer approves a bare "direction" on an issue that asks its owner to choose between options. Before, projectbluefin/utah#920 (carry debugging tools in the image, a `ujust` recipe, or a `-dx` flavor) planned *Approve the direction of #920 and let the hive pick it up* under `default-approve`, recording no choice, so the claiming agent would pick one itself. The delegate now reads the issue's options (the lettered options the "What to reply" notice reads, or a numbered list a `Pick one:` / "competing" / "options" lead-in introduces, from the body or the newest hive park comment). When the same text recommends one, it goes with that option and names it in the plan and in the recorded `/hive decision` (rule `recommended-option`). When it recommends none, it writes nothing and leaves the choice to a person, offering Give direction (rule `competing-options`).
3 changes: 2 additions & 1 deletion src/docs/dashboard-sections/activity-monitor.md
Original file line number Diff line number Diff line change
Expand Up @@ -717,9 +717,10 @@ The rules live in one place β€” `src/pkg/delegatedecision/policy.go` (`PolicyTex
| 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). |
| an issue that asks its owner to choose between two or more options: lettered options as the *What to reply* notice reads them (`Option A:`, `**B.**`, `- C:`), or a numbered list whose lead-in line reads as a choice (`Pick one:`, "three competing mechanisms:", "options", "either") β€” in the body or the newest hive park comment ([projectbluefin/utah#920](https://github.com/projectbluefin/utah/issues/920)) | `recommended-option` (verdict `approve`) when the same text recommends one of them ("Recommendation: option 2", "My recommendation is **B**"); `competing-options` (verdict `refused`) when it recommends none | With a recommendation, the plan reads *Go with option 2: … β€” the option #N recommends β€” and let the hive build it*, and the recorded `/hive decision go with option 2: …` names the option, so the claiming agent builds that one. Without one, nothing is written: the plan reads *Leave the choice to you: #N asks a person to choose between 3 options (1, 2, 3) and recommends none* and offers **Give direction**. Checked before every other approving issue rule, so an issue with a choice is never approved as a bare "direction"; a numbered list of steps with no such lead-in is not read as options. |
| 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`, `one-pr-per-issue`) in the comment and in the job's `decision.rule`.
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`, `recommended-option`, `competing-options`, `default-approve`, `prefer-contributor`, `contributor-offline`, `sentinel-trusted`, `small-low-risk`, `reporter-trust`, `fix-then-merge`, `default-release`, `hive-policy`, `sentinel-untrusted`, `rail-hold`, `one-pr-per-issue`) 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
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,8 @@ The plain-words comment the delegate posts has four lines β€” **Hive decided** (
| `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. |
| `recommended-option` | the issue offers options and recommends one; the hive went with that one | The issue asks its owner to choose between options and recommends one. The hive went with the recommended option and named it in the recorded decision, so the agent that claims the issue builds that option, not one it picks itself. |
| `competing-options` | the issue asks a person to choose between options; the hive does not pick | The issue offers competing options and recommends none. Choosing between them is the owner's call, so the hive did not decide: use Give direction to name the option, or reply `/hive decision <option>` on the issue. |
| `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
26 changes: 26 additions & 0 deletions src/pkg/dashboard/api_repo_item_decide_delegated.go
Original file line number Diff line number Diff line change
Expand Up @@ -721,6 +721,8 @@ func (s *Server) gatherDelegatedInput(ctx context.Context, repoFull string, numb
}
}
}
} else {
in.Options, in.RecommendedOption = client.IssueDecisionOptions(in.Body, issue.GetUser(), delegatedIssueComments(ctx, api, owner, repoName, number))
}
sentinel := s.sentinelLabel()
for _, l := range in.Labels {
Expand Down Expand Up @@ -814,6 +816,30 @@ func (s *Server) delegatedSentinelReason(repoFull string, number int, head, rowR
}
}

// delegatedIssueCommentPages caps how much of a long thread is read for the
// park's options: the newest hive comment that lists them wins.
const delegatedIssueCommentPages = 5

// delegatedIssueComments reads an issue's comments, oldest first, for the
// options its park offers. A read error is not fatal: the options are then
// read from the body alone.
func delegatedIssueComments(ctx context.Context, api *gh.Client, owner, repoName string, number int) []*gh.IssueComment {
var out []*gh.IssueComment
opts := &gh.IssueListCommentsOptions{ListOptions: gh.ListOptions{PerPage: delegatedDecisionGatherLimit}}
for page := 0; page < delegatedIssueCommentPages; page++ {
comments, resp, err := api.Issues.ListComments(ctx, owner, repoName, number, opts)
if err != nil {
return out
}
out = append(out, comments...)
if resp == nil || resp.NextPage == 0 {
break
}
opts.Page = resp.NextPage
}
return out
}

// delegatedHeadCIState is what the head's checks say: green (every
// gating check passed), pending (some still running, none failed), or
// neither (a check failed, or none ever reported).
Expand Down
114 changes: 114 additions & 0 deletions src/pkg/dashboard/api_repo_item_decide_delegated_options_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,114 @@
package dashboard

import (
"encoding/json"
"net/http"
"strings"
"testing"

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

// projectbluefin/utah#920: three mutually exclusive delivery options, parked
// at 045. "Let hive decide" offered "Approve the direction of #920 and let
// the hive pick it up", which recorded no choice. It must name the option it
// goes with, or leave the choice to a person.
const delegatedOptionsBody = "## Problem\n\nNo debugger ships.\n\n## Proposal\n\nPick one:\n\n" +
"1. **Carry a small set in the image:** `gdb-headless`, `elfutils`, `sysprof-cli`.\n" +
"2. **A `ujust` recipe** that installs the set on demand.\n" +
"3. **A `-dx`/debug flavor** only, leaving the default image alone.\n"

func TestDelegatedPlanWordingNamesTheOptionOrLeavesTheChoice(t *testing.T) {
options := []delegatedecision.Option{{Label: "1", Summary: "image"}, {Label: "2", Summary: "A ujust recipe"}, {Label: "3", Summary: "-dx flavor"}}
in := delegatedecision.Input{Kind: delegatedecision.KindIssue, Number: 920, Options: options}

summary, next := delegatedPlanWording(in, delegatedecision.Decision{Verdict: delegatedecision.VerdictRefused, Rule: delegatedecision.RuleCompetingOptions, KeepsPark: true})
if want := "Leave the choice to you: #920 asks a person to choose between 3 options (1, 2, 3) and recommends none."; summary != want {
t.Errorf("refusal summary %q, want %q", summary, want)
}
if strings.Join(next, "|") != "Nothing changes; #920 stays waiting for you.|Use Give direction to name the option the hive should build." {
t.Errorf("refusal consequences %q", next)
}

chosen := options[1]
summary, next = delegatedPlanWording(in, delegatedecision.Decision{Verdict: delegatedecision.VerdictApprove, Rule: delegatedecision.RuleRecommendedOption, Option: &chosen})
if want := "Go with option 2: A ujust recipe β€” the option #920 recommends β€” and let the hive build it."; summary != want {
t.Errorf("approve summary %q, want %q", summary, want)
}
if strings.Join(next, "|") != "Hive records option 2 as the decision and removes the needs-decision hold.|An agent claims #920 on the next cycle and builds option 2." {
t.Errorf("approve consequences %q", next)
}
for _, s := range append([]string{summary}, next...) {
if strings.Contains(s, "the direction") {
t.Errorf("an issue with options must never read as a bare direction: %q", s)
}
}
}

func TestDelegatedDecisionPlanForAnIssueWithOptions(t *testing.T) {
for _, tc := range []struct {
name string
body string
wantWould delegatedecision.Verdict
wantRule string
wantSum string
wantWhy string
}{
{"no recommendation", delegatedOptionsBody, delegatedecision.VerdictRefused, delegatedecision.RuleCompetingOptions,
"Leave the choice to you: #7 asks a person to choose between 3 options (1, 2, 3) and recommends none.",
"The issue asks a person to choose between 3 options (1, 2, 3) and recommends none."},
{"recommends option 2", delegatedOptionsBody + "\nRecommendation: option 2, it keeps the image small.\n", delegatedecision.VerdictApprove, delegatedecision.RuleRecommendedOption,
"Go with option 2: A `ujust` recipe that installs the set on demand β€” the option #7 recommends β€” and let the hive build it.",
"The issue offers 3 options and recommends option 2."},
} {
t.Run(tc.name, func(t *testing.T) {
mock := &repoItemDecisionMock{issueTitle: "Ship debugging tools", issueBody: tc.body, issueLabels: []string{"kind/feature", "stage/045-needs-decision"}}
srv := newDelegatedServer(t, mock)
w := postDelegatedPlan(t, srv, 7, "writer", `{"type":"issue"}`, map[string]string{"X-Hive-Role": "merger"})
if w.Code != http.StatusOK {
t.Fatalf("code=%d body=%s", w.Code, w.Body.String())
}
var plan delegatedDecisionPlan
if err := json.Unmarshal(w.Body.Bytes(), &plan); err != nil {
t.Fatal(err)
}
if plan.Would != string(tc.wantWould) || plan.Rule != tc.wantRule || plan.Summary != tc.wantSum || plan.Why != tc.wantWhy || plan.Writes {
t.Fatalf("plan would=%q rule=%q summary=%q why=%q writes=%v", plan.Would, plan.Rule, plan.Summary, plan.Why, plan.Writes)
}
hasDirection := false
for _, alt := range plan.Alternatives {
hasDirection = hasDirection || (alt.Action == decisionActionDirection && alt.Enabled)
}
if !hasDirection {
t.Errorf("Give direction must stay offered: %+v", plan.Alternatives)
}
if len(mock.comments) != 0 || len(mock.edits) != 0 {
t.Fatalf("a plan may not write: %v %v", mock.comments, mock.edits)
}
})
}
}

// Running the decision: with no recommendation nothing is written; with one,
// the recorded `/hive decision` names the option the claiming agent builds.
func TestDelegatedDecisionIssueWithOptionsRecordsTheChoice(t *testing.T) {
mock := &repoItemDecisionMock{issueBody: delegatedOptionsBody, issueLabels: []string{"stage/045-needs-decision"}}
srv := newDelegatedServer(t, mock)
job := decodeDelegatedJob(t, postDelegated(t, srv, 7, "writer", `{"type":"issue"}`, nil))
if job.Decision == nil || job.Decision.Rule != delegatedecision.RuleCompetingOptions {
t.Fatalf("job = %+v", job)
}
if len(mock.comments) != 0 || len(mock.added) != 0 || len(mock.removed) != 0 {
t.Fatalf("a refusal must write nothing: comments=%v added=%v removed=%v", mock.comments, mock.added, mock.removed)
}

mock = &repoItemDecisionMock{issueBody: delegatedOptionsBody + "\nI recommend option 2.\n", issueLabels: []string{"stage/045-needs-decision"}}
srv = newDelegatedServer(t, mock)
job = decodeDelegatedJob(t, postDelegated(t, srv, 7, "writer", `{"type":"issue"}`, nil))
if job.Decision == nil || job.Decision.Rule != delegatedecision.RuleRecommendedOption {
t.Fatalf("job = %+v", job)
}
if len(mock.comments) == 0 || !strings.HasPrefix(mock.comments[0], "/hive decision go with option 2: A `ujust` recipe that installs the set on demand.") {
t.Fatalf("recorded decision does not name option 2: %v", mock.comments)
}
}
13 changes: 13 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 @@ -336,6 +336,12 @@ func delegatedPlanWording(in delegatedecision.Input, d delegatedecision.Decision
"Hive opens its copy of " + ref + ", lets it soak, and merges it.",
ref + " is closed as superseded; the author keeps the credit.",
}
case d.Verdict == delegatedecision.VerdictApprove && in.Kind == delegatedecision.KindIssue && d.Option != nil:
// The issue offered a choice: the plan names the option, so
// approving never leaves the pick to the claiming agent
// (projectbluefin/utah#920).
return "Go with " + strings.TrimSuffix(d.Option.Name(), ".") + " β€” the option " + ref + " recommends β€” and let the hive build it.",
[]string{"Hive records option " + d.Option.Label + " as the decision and removes the needs-decision hold.", "An agent claims " + ref + " on the next cycle and builds option " + d.Option.Label + "."}
case d.Verdict == delegatedecision.VerdictApprove && in.Kind == delegatedecision.KindIssue:
// An issue has no commit to approve and nothing to merge
// (hivecommons/hive#15754): approval is the direction, and an
Expand Down Expand Up @@ -366,6 +372,13 @@ func delegatedPlanWording(in delegatedecision.Input, d delegatedecision.Decision
case d.Verdict == delegatedecision.VerdictDirection:
return "Send " + ref + " back to its author with one instruction: " + delegatedPlanInstruction(in, d) + ".",
[]string{"Hive posts that instruction on " + ref + ".", "The author pushes a fix; the row updates when it lands."}
case d.Verdict == delegatedecision.VerdictRefused && d.Rule == delegatedecision.RuleCompetingOptions:
labels := make([]string, 0, len(in.Options))
for _, o := range in.Options {
labels = append(labels, o.Label)
}
return fmt.Sprintf("Leave the choice to you: %s asks a person to choose between %d options (%s) and recommends none.", ref, len(in.Options), strings.Join(labels, ", ")),
[]string{"Nothing changes; " + ref + " stays waiting for you.", "Use Give direction to name the option the hive should build."}
case d.Verdict == delegatedecision.VerdictRefused:
return "Do nothing: " + delegatedPlanPlain(d.Rationale) + ".", []string{"Nothing changes; " + ref + " stays waiting for you."}
case d.Verdict == delegatedecision.VerdictOwnerOnly:
Expand Down
Loading
Loading