diff --git a/changelog.d/fixed-delegate-competing-options.md b/changelog.d/fixed-delegate-competing-options.md
new file mode 100644
index 0000000000..4c824ea403
--- /dev/null
+++ b/changelog.d/fixed-delegate-competing-options.md
@@ -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`).
diff --git a/src/docs/dashboard-sections/activity-monitor.md b/src/docs/dashboard-sections/activity-monitor.md
index ab810d0ca4..8b3e4bd7ca 100644
--- a/src/docs/dashboard-sections/activity-monitor.md
+++ b/src/docs/dashboard-sections/activity-monitor.md
@@ -717,9 +717,10 @@ The rules live in one place — `src/pkg/delegatedecision/policy.go` (`PolicyTex
| a fleet self-report (`` 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 `
` 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.
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 a74c287a82..9c6c87dbe5 100644
--- a/src/docs/labels-and-control-signals/glossary-and-operations.md
+++ b/src/docs/labels-and-control-signals/glossary-and-operations.md
@@ -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 ` 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. |
diff --git a/src/pkg/dashboard/api_repo_item_decide_delegated.go b/src/pkg/dashboard/api_repo_item_decide_delegated.go
index 06e974d93d..40d1c9c75c 100644
--- a/src/pkg/dashboard/api_repo_item_decide_delegated.go
+++ b/src/pkg/dashboard/api_repo_item_decide_delegated.go
@@ -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 {
@@ -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).
diff --git a/src/pkg/dashboard/api_repo_item_decide_delegated_options_test.go b/src/pkg/dashboard/api_repo_item_decide_delegated_options_test.go
new file mode 100644
index 0000000000..465c8b19f5
--- /dev/null
+++ b/src/pkg/dashboard/api_repo_item_decide_delegated_options_test.go
@@ -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)
+ }
+}
diff --git a/src/pkg/dashboard/api_repo_item_decide_delegated_plan.go b/src/pkg/dashboard/api_repo_item_decide_delegated_plan.go
index f5d57ffe52..4b289494cc 100644
--- a/src/pkg/dashboard/api_repo_item_decide_delegated_plan.go
+++ b/src/pkg/dashboard/api_repo_item_decide_delegated_plan.go
@@ -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
@@ -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:
diff --git a/src/pkg/dashboard/static-src/js/tracker-filter-fetch.js b/src/pkg/dashboard/static-src/js/tracker-filter-fetch.js
index 97468151f8..95be137f82 100644
--- a/src/pkg/dashboard/static-src/js/tracker-filter-fetch.js
+++ b/src/pkg/dashboard/static-src/js/tracker-filter-fetch.js
@@ -102,6 +102,8 @@
"dco": {"kind": "reason", "plain": "a commit is missing its sign-off", "detail": "A commit on the branch is missing its Developer Certificate of Origin sign-off; the author must sign it off."},
"dco-missing": {"kind": "reason", "plain": "a commit is missing its sign-off", "detail": "A commit on the branch is missing its Developer Certificate of Origin sign-off; the author must sign it off."},
"dedupe": {"kind": "rule", "plain": "an older issue already tracks this", "detail": "An older issue already tracks the same work; one thread keeps it moving."},
+ "competing-options": {"kind": "rule", "plain": "the issue asks a person to choose between options; the hive does not pick", "detail": "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 ` on the issue."},
+ "recommended-option": {"kind": "rule", "plain": "the issue offers options and recommends one; the hive went with that one", "detail": "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."},
"default-approve": {"kind": "rule", "plain": "no special rule applies; the hive took its own recommendation", "detail": "No owner rule singles this issue out, so the hive went with its own recommendation — the reversible choice that keeps work moving."},
"default-release": {"kind": "rule", "plain": "no special rule applies; a green branch is approved", "detail": "No owner rule holds this PR back; its branch is green and a merge is reversible, so it is approved."},
"design-proposal": {"kind": "rule", "plain": "a proposal with clear acceptance criteria, accepted as written", "detail": "The proposal states concrete acceptance criteria, so it is accepted as written; anything not stated keeps today's behaviour."},
diff --git a/src/pkg/dashboard/static/index.html b/src/pkg/dashboard/static/index.html
index 0ffb032b27..0caa15a8e4 100644
--- a/src/pkg/dashboard/static/index.html
+++ b/src/pkg/dashboard/static/index.html
@@ -22766,6 +22766,8 @@ All labels
"dco": {"kind": "reason", "plain": "a commit is missing its sign-off", "detail": "A commit on the branch is missing its Developer Certificate of Origin sign-off; the author must sign it off."},
"dco-missing": {"kind": "reason", "plain": "a commit is missing its sign-off", "detail": "A commit on the branch is missing its Developer Certificate of Origin sign-off; the author must sign it off."},
"dedupe": {"kind": "rule", "plain": "an older issue already tracks this", "detail": "An older issue already tracks the same work; one thread keeps it moving."},
+ "competing-options": {"kind": "rule", "plain": "the issue asks a person to choose between options; the hive does not pick", "detail": "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 ` on the issue."},
+ "recommended-option": {"kind": "rule", "plain": "the issue offers options and recommends one; the hive went with that one", "detail": "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."},
"default-approve": {"kind": "rule", "plain": "no special rule applies; the hive took its own recommendation", "detail": "No owner rule singles this issue out, so the hive went with its own recommendation — the reversible choice that keeps work moving."},
"default-release": {"kind": "rule", "plain": "no special rule applies; a green branch is approved", "detail": "No owner rule holds this PR back; its branch is green and a merge is reversible, so it is approved."},
"design-proposal": {"kind": "rule", "plain": "a proposal with clear acceptance criteria, accepted as written", "detail": "The proposal states concrete acceptance criteria, so it is accepted as written; anything not stated keeps today's behaviour."},
diff --git a/src/pkg/delegatedecision/competing_options.go b/src/pkg/delegatedecision/competing_options.go
new file mode 100644
index 0000000000..ef9cf2b557
--- /dev/null
+++ b/src/pkg/delegatedecision/competing_options.go
@@ -0,0 +1,69 @@
+package delegatedecision
+
+import (
+ "fmt"
+ "strconv"
+ "strings"
+)
+
+// Competing options on a parked issue. An issue that asks its owner to pick
+// one of several alternatives (projectbluefin/utah#920: carry the tools in
+// the image, a `ujust` recipe, or a -dx flavor) used to fall to
+// default-approve, whose "approve the direction" recorded no choice, so the
+// claiming agent picked one itself. The delegate now goes with an option only
+// when the issue recommends one, and names it in the recorded decision;
+// otherwise it leaves the choice to a person.
+
+const (
+ // RuleRecommendedOption approves the option the issue itself recommends.
+ RuleRecommendedOption = "recommended-option"
+ // RuleCompetingOptions refuses: the issue offers options and recommends
+ // none, so choosing is the owner's.
+ RuleCompetingOptions = "competing-options"
+)
+
+// Option is one alternative a parked issue offers its owner: its label as
+// the issue writes it ("A", "2") and a one-line summary.
+type Option struct {
+ Label string `json:"label"`
+ Summary string `json:"summary,omitempty"`
+}
+
+// Name is the option as a decision names it: "option 2: A ujust recipe".
+func (o Option) Name() string {
+ name := "option " + o.Label
+ if s := strings.TrimSpace(o.Summary); s != "" {
+ name += ": " + s
+ }
+ return name
+}
+
+// competingOptionsDecision decides an issue that offers two or more
+// options: it goes with the one the issue recommends, or refuses when the
+// issue recommends none. ok is false for an issue offering fewer than two.
+func competingOptionsDecision(in Input) (Decision, bool) {
+ if len(in.Options) < 2 {
+ return Decision{}, false
+ }
+ ref := "#" + strconv.Itoa(in.Number)
+ labels := make([]string, 0, len(in.Options))
+ for _, o := range in.Options {
+ labels = append(labels, o.Label)
+ }
+ for _, o := range in.Options {
+ if in.RecommendedOption == "" || o.Label != in.RecommendedOption {
+ continue
+ }
+ chosen := o
+ d := approveIssue(RuleRecommendedOption, "go with "+chosen.Name(),
+ fmt.Sprintf("the issue offers %d options and recommends option %s", len(in.Options), chosen.Label))
+ d.Option = &chosen
+ return d, true
+ }
+ return Decision{
+ Verdict: VerdictRefused, Rule: RuleCompetingOptions, KeepsPark: true,
+ Text: "choose one of " + ref + "'s options with Give direction",
+ Rationale: fmt.Sprintf("the issue asks a person to choose between %d options (%s) and recommends none; the hive does not pick one for you",
+ len(in.Options), strings.Join(labels, ", ")),
+ }, true
+}
diff --git a/src/pkg/delegatedecision/competing_options_test.go b/src/pkg/delegatedecision/competing_options_test.go
new file mode 100644
index 0000000000..f07dcd3037
--- /dev/null
+++ b/src/pkg/delegatedecision/competing_options_test.go
@@ -0,0 +1,89 @@
+package delegatedecision
+
+import (
+ "strings"
+ "testing"
+)
+
+// projectbluefin/utah#920's three delivery options, as the dashboard reads
+// them from the body.
+var utah920Options = []Option{
+ {Label: "1", Summary: "Carry a small set in the image: `gdb-headless`, `elfutils`, `sysprof-cli`."},
+ {Label: "2", Summary: "A `ujust` recipe that installs the set on demand."},
+ {Label: "3", Summary: "A `-dx`/debug flavor only, leaving the default image alone."},
+}
+
+func utah920Input() Input {
+ return Input{Kind: KindIssue, Number: 920, Repo: "projectbluefin/utah",
+ Title: "Ship (or make one command away) gdb, sysprof-cli and elfutils for diagnosing shell hangs",
+ Labels: []string{"kind/feature", LabelIssueNeedsDecision}, Options: utah920Options}
+}
+
+func TestCompetingOptionsWithoutARecommendationAreNotDecided(t *testing.T) {
+ d := ApplyRails(Decide(utah920Input()), Rails{})
+ if d.Verdict != VerdictRefused || d.Rule != RuleCompetingOptions || !d.KeepsPark {
+ t.Fatalf("decision = %+v, want a refusal under %s", d, RuleCompetingOptions)
+ }
+ if len(d.Actions) != 0 {
+ t.Fatalf("a refusal writes nothing, got actions %+v", d.Actions)
+ }
+ if want := "the issue asks a person to choose between 3 options (1, 2, 3) and recommends none"; !strings.HasPrefix(d.Rationale, want) {
+ t.Errorf("rationale %q, want it to start %q", d.Rationale, want)
+ }
+ if d.Option != nil {
+ t.Errorf("no option is chosen, got %+v", d.Option)
+ }
+}
+
+func TestCompetingOptionsGoWithTheRecommendedOne(t *testing.T) {
+ in := utah920Input()
+ in.RecommendedOption = "2"
+ d := ApplyRails(Decide(in), Rails{})
+ if d.Verdict != VerdictApprove || d.Rule != RuleRecommendedOption {
+ t.Fatalf("decision = %+v, want approve under %s", d, RuleRecommendedOption)
+ }
+ if d.Option == nil || d.Option.Label != "2" {
+ t.Fatalf("option = %+v, want 2", d.Option)
+ }
+ want := "go with option 2: A `ujust` recipe that installs the set on demand."
+ if d.Text != want {
+ t.Errorf("text %q, want %q", d.Text, want)
+ }
+ // The recorded `/hive decision` carries the option, so the claiming
+ // agent builds that one and not one it picks itself.
+ var recorded string
+ for _, a := range d.Actions {
+ if a.Kind == ActionCommentDecision {
+ recorded = a.Text
+ }
+ }
+ if recorded != want {
+ t.Errorf("recorded decision %q, want %q", recorded, want)
+ }
+ if body := CommentBody(d, "h1", "writer"); !strings.Contains(body, "option 2: A `ujust` recipe") {
+ t.Errorf("decision comment does not name the option:\n%s", body)
+ }
+}
+
+func TestCompetingOptionsOnlyApplyToARealChoice(t *testing.T) {
+ in := utah920Input()
+ in.Options = in.Options[:1]
+ if d := Decide(in); d.Rule != "default-approve" {
+ t.Errorf("one option is not a choice: rule %q, want default-approve", d.Rule)
+ }
+ in.Options = nil
+ if d := Decide(in); d.Rule != "default-approve" {
+ t.Errorf("no options: rule %q, want default-approve", d.Rule)
+ }
+ // A recommendation that names none of the options is no recommendation.
+ in = utah920Input()
+ in.RecommendedOption = "7"
+ if d := Decide(in); d.Rule != RuleCompetingOptions {
+ t.Errorf("unoffered recommendation: rule %q, want %s", d.Rule, RuleCompetingOptions)
+ }
+ // The LLM decider only ever replaces the reversible default; a choice
+ // between options never reaches it.
+ if IsReversibleDefault(Decide(utah920Input())) {
+ t.Error("a competing-options refusal must not be handed to the LLM decider")
+ }
+}
diff --git a/src/pkg/delegatedecision/decision_glossary.go b/src/pkg/delegatedecision/decision_glossary.go
index 75f3e2b627..b8a43d1281 100644
--- a/src/pkg/delegatedecision/decision_glossary.go
+++ b/src/pkg/delegatedecision/decision_glossary.go
@@ -149,6 +149,10 @@ var glossary = []GlossaryEntry{
Detail: "The issue is a hive advisory (a dedupe checklist or triage note) and every item it lists is closed or merged, so nothing is left to read; the hive closes it as completed."},
{Slug: RuleAdvisoryInProgress, Kind: GlossaryRule, Plain: "a hive advisory the hive is still working; nothing to decide",
Detail: "The issue is a hive advisory whose items are still being worked: the sweep ticks each as it closes or merges and closes the advisory when all are resolved. Nothing is written and nobody is parked on it."},
+ {Slug: RuleRecommendedOption, Kind: GlossaryRule, Plain: "the issue offers options and recommends one; the hive went with that one",
+ Detail: "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."},
+ {Slug: RuleCompetingOptions, Kind: GlossaryRule, Plain: "the issue asks a person to choose between options; the hive does not pick",
+ Detail: "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 ` on the issue."},
{Slug: "default-approve", Kind: GlossaryRule, Plain: "no special rule applies; the hive took its own recommendation",
Detail: "No owner rule singles this issue out, so the hive went with its own recommendation — the reversible choice that keeps work moving."},
{Slug: "default-release", Kind: GlossaryRule, Plain: "no special rule applies; a green branch is approved",
diff --git a/src/pkg/delegatedecision/policy.go b/src/pkg/delegatedecision/policy.go
index 0e64370f8d..fb2f6b6e8e 100644
--- a/src/pkg/delegatedecision/policy.go
+++ b/src/pkg/delegatedecision/policy.go
@@ -200,6 +200,11 @@ type Input struct {
// question, when one was recorded.
Reasons []string
Question string
+ // Options are the alternatives an issue offers its owner, read from its
+ // body or the hive's park comment; RecommendedOption is the Label of the
+ // one that text recommends, "" when it names none.
+ Options []Option
+ RecommendedOption string
// Author is the PR's / issue's GitHub login, for plain-words answers.
Author string
// HiveAuthored: the hive opened the PR / filed the issue.
@@ -382,6 +387,9 @@ type Decision struct {
// Ladder is the contributor-PR rung the decision landed on and why
// the rungs above it did not apply (hivecommons/hive#15289).
Ladder *Ladder `json:"ladder,omitempty"`
+ // Option is the issue's option the decision goes with, when it offered
+ // several (RuleRecommendedOption).
+ Option *Option `json:"option,omitempty"`
}
// Marker is the audit stamp every delegated comment carries.
@@ -572,6 +580,11 @@ func decideIssue(in Input) Decision {
return approveIssue("review-backlog", "keep "+ref+" open: drop the relation to the closed PR, note it here and re-triage; a review-backlog item is never auto-closed when its PR closes unmerged",
"the PR closing unmerged leaves the work undone")
}
+ // Every rule below approves a direction. An issue that offers a choice
+ // is approved only as the option it recommends, never as a bare one.
+ if d, ok := competingOptionsDecision(in); ok {
+ return d
+ }
if hasLabel(in.Labels, labelFlaky) || flakyRE.MatchString(in.Title) || flakyRE.MatchString(firstLines(in.Body, 6)) {
d := approveIssue("flaky-test", "quarantine the flaky test with a retry and file a deflake task; do not block on it",
"a flaky test blocks nothing by policy — quarantine with retry, deflake separately")
diff --git a/src/pkg/github/issue_decision_options.go b/src/pkg/github/issue_decision_options.go
new file mode 100644
index 0000000000..f629cb1db5
--- /dev/null
+++ b/src/pkg/github/issue_decision_options.go
@@ -0,0 +1,141 @@
+package github
+
+import (
+ "regexp"
+ "strings"
+
+ gh "github.com/google/go-github/v72/github"
+
+ "github.com/hivecommons/hive/pkg/delegatedecision"
+)
+
+// IssueDecisionOptions reads the options a parked issue asks its owner to
+// choose between, for "Let hive decide" (projectbluefin/utah#920): the
+// lettered options the "What to reply" notice offers (the issue body, or the
+// newest hive comment that lists them), else a numbered list a cue line
+// introduces as alternatives ("Pick one:", "three competing delivery
+// mechanisms:"). recommended is the label the same text recommends, "" when
+// it names none. Fewer than two options reads as none.
+func (c *Client) IssueDecisionOptions(issueBody string, issueAuthor *gh.User, comments []*gh.IssueComment) (options []delegatedecision.Option, recommended string) {
+ m := c.unparkMenuFor(issueBody, issueAuthor, comments)
+ if len(m.options) >= 2 {
+ for _, l := range m.options {
+ options = append(options, delegatedecision.Option{Label: l, Summary: m.optionText[l]})
+ }
+ return options, m.recommended
+ }
+ // No lettered options: the newest park text with a numbered option list
+ // wins, as for letters. The hive's own notices, replies and the
+ // delegate's verdicts are not park text; a withdrawn ask takes its
+ // options with it.
+ source := ""
+ if numberedDecisionOptions(issueBody) != nil {
+ source = issueBody
+ }
+ for _, cm := range comments {
+ if cm == nil || !c.isHiveAccount(cm.GetUser()) {
+ continue
+ }
+ body := cm.GetBody()
+ switch {
+ case strings.Contains(body, parkWithdrawnMarkerPrefix):
+ source = ""
+ case strings.Contains(body, unparkNoticeMarker), strings.Contains(body, unparkReplyMarkerPrefix),
+ strings.Contains(body, unparkAcceptedMarker), strings.Contains(body, parkRecheckMarker),
+ delegatedecision.IsDelegatedComment(body):
+ case numberedDecisionOptions(body) != nil:
+ source = body
+ }
+ }
+ if source == "" {
+ return nil, ""
+ }
+ options = numberedDecisionOptions(source)
+ return options, numberedRecommendedOption(source, options)
+}
+
+// numberedOptionItemRE is a numbered list item, "1. text" or "2) text",
+// indented at most three spaces as Markdown allows.
+var numberedOptionItemRE = regexp.MustCompile(`^ {0,3}([1-9])[.)][ \t]+(\S.*)$`)
+
+// numberedOptionCueRE is a lead-in that makes the numbered list after it a
+// set of alternatives rather than steps.
+var numberedOptionCueRE = regexp.MustCompile(`(?i)\b(?:pick|choose|select)\s+(?:one|between|from|among)\b|\bone of\b|\b(?:options?|alternatives?|choices?)\b|\bcompeting\b|\bmutually exclusive\b|\beither\b`)
+
+// numberedDecisionOptions reads the first numbered list in text that a cue
+// line introduces as alternatives: the nearest non-blank line before item 1
+// must read as one (numberedOptionCueRE). Items must run 1, 2, 3 … with only
+// blank or indented continuation lines between them; a numbered list of
+// steps ("What it cost: 1. eu-stack … 2. gdb …") has no such lead-in and is
+// not read. Fenced code is skipped. Fewer than two items reads as none.
+func numberedDecisionOptions(text string) []delegatedecision.Option {
+ lines := strings.Split(strings.ReplaceAll(text, "\r\n", "\n"), "\n")
+ lead, fenced := "", false
+ for i := 0; i < len(lines); i++ {
+ line := lines[i]
+ if strings.HasPrefix(strings.TrimSpace(line), "```") {
+ fenced = !fenced
+ continue
+ }
+ if fenced {
+ continue
+ }
+ m := numberedOptionItemRE.FindStringSubmatch(line)
+ if m == nil || m[1] != "1" || !numberedOptionCueRE.MatchString(lead) {
+ if strings.TrimSpace(line) != "" {
+ lead = line
+ }
+ continue
+ }
+ var opts []delegatedecision.Option
+ j := i
+ for ; j < len(lines); j++ {
+ l := lines[j]
+ if im := numberedOptionItemRE.FindStringSubmatch(l); im != nil {
+ if im[1] != string(rune('1'+len(opts))) {
+ break
+ }
+ opts = append(opts, delegatedecision.Option{Label: im[1], Summary: unparkCleanOptionSummary(strings.ReplaceAll(im[2], "**", ""))})
+ continue
+ }
+ if strings.TrimSpace(l) == "" || strings.HasPrefix(l, " ") || strings.HasPrefix(l, "\t") {
+ continue
+ }
+ break
+ }
+ if len(opts) >= 2 {
+ return opts
+ }
+ lead, i = line, j-1
+ }
+ return nil
+}
+
+// numberedOptionRefRE names a numbered option on a recommendation line:
+// "option 2", "choice #3", or a bare number right after the word
+// ("Recommendation: 2.", "I recommend **1**").
+var numberedOptionRefRE = regexp.MustCompile(`(?i)\b(?:option|choice|alternative)\s*#?\s*([1-9])\b|\brecommend\w*(?:\s+is)?\s*[:—–-]?\s*\**\s*([1-9])\**(?:[.):,;]|\s|$)`)
+
+// numberedRecommendedOption is the numbered option text recommends, read
+// only from lines that mention a recommendation and only as an explicit
+// option reference, so a stray number ("saves 3 hours") is never taken for
+// a choice. "" when none of options is named.
+func numberedRecommendedOption(text string, options []delegatedecision.Option) string {
+ offered := map[string]bool{}
+ for _, o := range options {
+ offered[o.Label] = true
+ }
+ for _, line := range strings.Split(text, "\n") {
+ if !unparkMentionsRecommendation(line) {
+ continue
+ }
+ for _, m := range numberedOptionRefRE.FindAllStringSubmatch(line, -1) {
+ for _, n := range m[1:] {
+ if offered[n] {
+ return n
+ }
+ }
+ }
+ }
+ return ""
+}
diff --git a/src/pkg/github/issue_decision_options_test.go b/src/pkg/github/issue_decision_options_test.go
new file mode 100644
index 0000000000..e1b1d7d4f5
--- /dev/null
+++ b/src/pkg/github/issue_decision_options_test.go
@@ -0,0 +1,135 @@
+package github
+
+import (
+ "strings"
+ "testing"
+
+ gh "github.com/google/go-github/v72/github"
+
+ "github.com/hivecommons/hive/pkg/delegatedecision"
+)
+
+// projectbluefin/utah#920 as filed: a numbered list of steps under "What it
+// cost", then three numbered alternatives under "Pick one:".
+const utah920Body = "## What it cost, concretely\n\n" +
+ "The shell's main thread was pinned at 95-99% CPU. What got us to a JS-level stack:\n\n" +
+ "1. `eu-stack` samples of the main thread: shows SpiderMonkey GC marking, but only native frames.\n" +
+ "2. `gdb` attached, calling `gjs_dumpstack()` (exported by `libgjs`): prints the live JS stack to the journal.\n\n" +
+ "## Proposal\n\n" +
+ "Pick one:\n\n" +
+ "1. **Carry a small set in the image:** `gdb-headless`, `elfutils`, `sysprof-cli`. Smallest useful set.\n" +
+ "2. **A `ujust` recipe** (e.g. `ujust troubleshoot-tools`) that installs the set on demand.\n" +
+ "3. **A `-dx`/debug flavor** only, leaving the default image alone.\n\n" +
+ "Whichever is chosen, I would add a short troubleshooting note under `docs/skills/`.\n"
+
+// The contributor's 045 comment on utah#920: the cue is "competing".
+const utah920Park = "### Maintainer Decision Required\n\n" +
+ "Issue #920 proposes three competing delivery mechanisms for troubleshooting tools:\n" +
+ "1. **Carry directly in the base image**: Adds ~23 MB installed size to all Utah image variants.\n" +
+ "2. **On-demand `ujust` troubleshooting recipe**: Installs tools on demand.\n" +
+ "3. **Dedicated `-dx` / debug flavor**: Preserves default image size.\n"
+
+func optionLabels(opts []delegatedecision.Option) string {
+ var l []string
+ for _, o := range opts {
+ l = append(l, o.Label)
+ }
+ return strings.Join(l, ",")
+}
+
+func TestNumberedDecisionOptionsReadsOnlyACuedList(t *testing.T) {
+ opts := numberedDecisionOptions(utah920Body)
+ if optionLabels(opts) != "1,2,3" {
+ t.Fatalf("utah#920 options = %+v, want 1,2,3 from the Pick one list", opts)
+ }
+ if got, want := opts[0].Summary, "Carry a small set in the image: `gdb-headless`, `elfutils`, `sysprof-cli`. Smallest useful set."; got != want {
+ t.Errorf("summary 1 = %q, want %q", got, want)
+ }
+ if strings.Contains(opts[1].Summary, "**") || !strings.HasPrefix(opts[1].Summary, "A `ujust` recipe") {
+ t.Errorf("summary 2 = %q", opts[1].Summary)
+ }
+ if got := optionLabels(numberedDecisionOptions(utah920Park)); got != "1,2,3" {
+ t.Errorf("045 comment options = %q, want 1,2,3", got)
+ }
+
+ for name, text := range map[string]string{
+ "steps with no cue": strings.SplitN(utah920Body, "## Proposal", 2)[0],
+ "single option": "Pick one:\n\n1. Only this.\n",
+ "not starting at one": "Options:\n\n2. b\n3. c\n",
+ "out of order": "Options:\n\n1. a\n3. c\n",
+ "inside a code fence": "```\nPick one:\n1. a\n2. b\n```\n",
+ "cue far from the list": "Pick one of these later.\n\nSome other paragraph.\n\n1. a\n2. b\n",
+ } {
+ if got := numberedDecisionOptions(text); got != nil {
+ t.Errorf("%s: read %+v as options", name, got)
+ }
+ }
+
+ // A prose line between items ends the list; indented continuation
+ // lines do not.
+ if got := optionLabels(numberedDecisionOptions("Options:\n\n1. a\n more about a\n\n2. b\n")); got != "1,2" {
+ t.Errorf("continuation lines: %q, want 1,2", got)
+ }
+ if got := numberedDecisionOptions("Options:\n\n1. a\nProse ends the list.\n2. b\n"); got != nil {
+ t.Errorf("prose between items: %+v", got)
+ }
+}
+
+func TestNumberedDecisionOptionSummaryIsSanitised(t *testing.T) {
+ opts := numberedDecisionOptions("Choose between:\n\n1. Ping @someone now\n2. b\n")
+ if len(opts) != 2 {
+ t.Fatalf("options = %+v", opts)
+ }
+ if s := opts[0].Summary; strings.Contains(s, "@someone") || strings.Contains(s, "\nWithdrawn."
+ if opts, _ = c.IssueDecisionOptions(utah920Body, person, []*gh.IssueComment{ghComment("hive[bot]", withdrawn)}); opts != nil {
+ t.Errorf("a withdrawn ask kept its options: %+v", opts)
+ }
+}
diff --git a/src/pkg/github/issue_unpark_command.go b/src/pkg/github/issue_unpark_command.go
index 8bef618763..9766ea877d 100644
--- a/src/pkg/github/issue_unpark_command.go
+++ b/src/pkg/github/issue_unpark_command.go
@@ -1564,7 +1564,15 @@ func unparkOptionSummary(line string) string {
default:
rest = unparkPlainOptionAt(line)
}
- rest = rest[1:]
+ return unparkCleanOptionSummary(rest[1:])
+}
+
+// unparkCleanOptionSummary turns the text after an option's marker into its
+// one-line summary: separators and a closing bold marker trimmed, HTML
+// comments removed and @mentions defanged (the text is untrusted and is
+// quoted in hive-authored comments), whitespace collapsed, cut to
+// unparkOptionSummaryMax runes.
+func unparkCleanOptionSummary(rest string) string {
rest = strings.TrimLeftFunc(rest, func(r rune) bool { return strings.ContainsRune(" \t*.:)—–-", r) })
rest = strings.TrimSpace(rest)
rest = strings.TrimSpace(strings.TrimSuffix(rest, "**"))