diff --git a/changelog.d/fixed-decision-toast-issue-wording.md b/changelog.d/fixed-decision-toast-issue-wording.md new file mode 100644 index 0000000000..f8535a97d7 --- /dev/null +++ b/changelog.d/fixed-decision-toast-issue-wording.md @@ -0,0 +1 @@ +- **Let-hive-decide toast: an issue decision no longer reads as "approved for merge".** On hive's own spoke, issue #15021 (`approved-direction` applied, `stage/045-needs-decision` never removed) produced the toast "Hive decided on hivecommons/hive#15021: decided, but it hasn't taken effect … Hive decided **approved for merge** at 2026-10-28T20:41:22Z". Nothing merges on an issue. The decision glossary (`pkg/delegatedecision`) now carries issue words beside the PR words for every decision kind that differs — `approve` → PR "approved for merge" / issue "approved to proceed — an agent may claim it"; `direction`, `close-superseded` and the `hold` reason likewise — and `ActionPlainOn` / `PlainOn` / `DetailOn` select by item kind in the toast, the `/hive decision` comment and the stalled follow-up (the SPA mirror `stageTrackerPlainWords(slug, detail, itemKind)` does the same). The headline no longer says "decided … decided" ("no effect yet"), and the SPA rewrites the server's RFC3339 stamps into the operator's clock ("2h ago (4:41 PM)") through the shared timezone helper. When the hive can see the real cause — the 045 park label still on an issue that already carries `approved-direction` — the toast says so ("stage/045-needs-decision is still on the issue; the scanner skips it until that label clears") and offers the fix first: **Lift the park (remove stage/045-needs-decision)** runs the audited issue-decision path that removes the label and tells the stage engine the park lifted, followed by Re-evaluate now, Re-run decision and Give direction. diff --git a/src/pkg/dashboard/api_repo_item_decide_delegated.go b/src/pkg/dashboard/api_repo_item_decide_delegated.go index f24b7e2f2f..abdd22ca0e 100644 --- a/src/pkg/dashboard/api_repo_item_decide_delegated.go +++ b/src/pkg/dashboard/api_repo_item_decide_delegated.go @@ -549,7 +549,7 @@ func (s *Server) decideDelegatedOne(ctx context.Context, repoFull string, number now := delegatedDecisionNow() timeout := s.delegatedEffectTimeout() why := s.delegatedStuckWhy(in, d, req, prior) - options := delegatedStuckOptions(in, d, mergerRole) + options := delegatedStuckOptions(in, d, mergerRole, why) res := delegatedDecisionEffectResult(rowActionTarget(repoFull, kind, number), in, d, prior.At, now, timeout, why, options) notes := append(deciderNotes, "already applied; nothing written") noop := "already-applied" diff --git a/src/pkg/dashboard/api_repo_item_decide_delegated_test.go b/src/pkg/dashboard/api_repo_item_decide_delegated_test.go index e18fd9bbf5..38f3972b33 100644 --- a/src/pkg/dashboard/api_repo_item_decide_delegated_test.go +++ b/src/pkg/dashboard/api_repo_item_decide_delegated_test.go @@ -494,7 +494,7 @@ func TestDelegatedDecisionStuckReportsNoEffect(t *testing.T) { } res := job.Result t.Logf("outcome: %s\nnext: %s\nwhy: %s", res.Outcome, res.Next, res.Why) - for _, want := range []string{"Hive decided close this PR and open a fresh hive-authored PR with the same commits at 2026-10-28T12:01:00Z", "but it hasn't taken effect:"} { + for _, want := range []string{"Close this PR and open a fresh hive-authored PR with the same commits at 2026-10-28T12:01:00Z", "but it hasn't taken effect:"} { if !strings.Contains(res.Outcome, want) { t.Fatalf("outcome %q missing %q", res.Outcome, want) } @@ -619,6 +619,55 @@ func TestReparkFromEvents(t *testing.T) { } } +// TestDelegatedDecisionStuckIssueWording reproduces hivecommons/hive#15021: +// the hive approved an ISSUE (`default-approve`), approved-direction landed +// but stage/045-needs-decision never came off. Past the effect timeout the +// toast must not say "approved for merge" (nothing merges on an issue), +// must name the stuck label, and must offer the lift first. +func TestDelegatedDecisionStuckIssueWording(t *testing.T) { + pinDelegatedClock(t, "2026-10-28T22:00:00Z") + prior := delegatedecision.Decision{Verdict: delegatedecision.VerdictApprove, Rule: "default-approve", Text: "approve", Rationale: "default"} + mock := &repoItemDecisionMock{issueLabels: []string{"help wanted", "triage/accepted", "approved-direction", "stage/045-needs-decision"}} + mock.priorComments = []string{delegatedecision.CommentBodyWith(prior, "h1", "writer", delegatedecision.CommentOptions{Kind: delegatedecision.KindIssue})} + srv := newDelegatedServer(t, mock) + w := postDelegated(t, srv, 7, "writer", `{"type":"issue","reason":"needs-decision","caption":"Needs decision"}`, nil) + if w.Code != http.StatusOK { + t.Fatalf("code=%d body=%s", w.Code, w.Body.String()) + } + job := decodeDelegatedJob(t, w) + if job.Result == nil || job.Result.Action != rowActionNoEffect { + t.Fatalf("result = %+v notes=%v", job.Result, job.Notes) + } + res := job.Result + t.Logf("outcome: %s\nnext: %s\nwhy: %s", res.Outcome, res.Next, res.Why) + if res.Why != delegatedecision.GlossaryParkLabelStuck { + t.Fatalf("why = %q", res.Why) + } + for _, bad := range []string{"approved for merge", "merge gate", "Hive decided"} { + if strings.Contains(res.Outcome, bad) { + t.Fatalf("PR wording / repeated headline in issue outcome %q: %q", res.Outcome, bad) + } + } + for _, want := range []string{"Approved to proceed — an agent may claim it at 2026-10-28T", "stage/045-needs-decision is still on the issue"} { + if !strings.Contains(res.Outcome, want) { + t.Fatalf("outcome %q missing %q", res.Outcome, want) + } + } + if !strings.Contains(res.Next, "approved-direction") || !strings.Contains(res.Next, "Lift the park") { + t.Fatalf("next = %q", res.Next) + } + if len(res.Options) < 4 || res.Options[0].Action != decisionActionApprove || !res.Options[0].Enabled || res.Options[1].Action != decisionActionRetry { + t.Fatalf("options = %+v", res.Options) + } + if labels := strings.Join(optionLabels(res.Options), "|"); !strings.Contains(labels, "Re-run decision") || !strings.Contains(labels, "Give direction") || strings.Contains(labels, "Merge as maintainer") { + t.Fatalf("options = %q", labels) + } + // The follow-up comment carries the issue words too. + if len(mock.comments) != 1 || strings.Contains(mock.comments[0], "approved for merge") || !strings.Contains(mock.comments[0], "approved to proceed") { + t.Fatalf("comments = %v", mock.comments) + } +} + // TestDelegatedStuckWhyReadsTheLane covers the why derivation per lane // reason and verdict so every stuck decision gets a specific plain reason. func TestDelegatedStuckWhyReadsTheLane(t *testing.T) { @@ -647,6 +696,13 @@ func TestDelegatedStuckWhyReadsTheLane(t *testing.T) { {"hold", pr, approve, delegatedDecisionRequest{Reason: "hold"}, selfApprove, delegatedecision.GlossaryHold}, {"pr fallback", pr, approve, delegatedDecisionRequest{}, selfApprove, delegatedecision.GlossaryNotMergedYet}, {"issue fallback", issue, approve, delegatedDecisionRequest{}, selfApprove, delegatedecision.GlossaryStillParked}, + {"issue park label outlived the approval", delegatedecision.Input{Kind: delegatedecision.KindIssue, Labels: []string{"help wanted", "approved-direction", "stage/045-needs-decision"}}, approve, delegatedDecisionRequest{}, selfApprove, delegatedecision.GlossaryParkLabelStuck}, + {"issue park label without the ack is just parked", delegatedecision.Input{Kind: delegatedecision.KindIssue, Labels: []string{"stage/045-needs-decision"}}, approve, delegatedDecisionRequest{}, selfApprove, delegatedecision.GlossaryStillParked}, + {"pr with both labels is not the issue case", func() delegatedecision.Input { + i := pr + i.Labels = []string{"approved-direction", "stage/045-needs-decision"} + return i + }(), approve, delegatedDecisionRequest{}, selfApprove, delegatedecision.GlossaryNotMergedYet}, {"close fallback", pr, delegatedecision.Decision{Verdict: delegatedecision.VerdictCloseSuperseded}, delegatedDecisionRequest{}, selfApprove, delegatedecision.GlossaryNotClosedYet}, {"direction fallback", pr, delegatedecision.Decision{Verdict: delegatedecision.VerdictDirection}, delegatedDecisionRequest{}, selfApprove, delegatedecision.GlossaryNoNewCommit}, } diff --git a/src/pkg/dashboard/delegated_decision_effect.go b/src/pkg/dashboard/delegated_decision_effect.go index 3e8b611511..c4a8ebe19e 100644 --- a/src/pkg/dashboard/delegated_decision_effect.go +++ b/src/pkg/dashboard/delegated_decision_effect.go @@ -11,6 +11,7 @@ import ( "github.com/hivecommons/hive/pkg/config" "github.com/hivecommons/hive/pkg/delegatedecision" ghpkg "github.com/hivecommons/hive/pkg/github" + "github.com/hivecommons/hive/pkg/stagelabels" ) // Stuck-decision detection for "Let hive decide" (hivecommons/hive#14822). @@ -199,6 +200,8 @@ func (s *Server) delegatedStuckWhy(in delegatedecision.Input, d delegatedecision return delegatedecision.GlossaryNotClosedYet case d.Verdict == delegatedecision.VerdictDirection: return delegatedecision.GlossaryNoNewCommit + case issueParkLabelStuck(in, d): + return delegatedecision.GlossaryParkLabelStuck case in.Kind == delegatedecision.KindIssue: return delegatedecision.GlossaryStillParked default: @@ -206,6 +209,26 @@ func (s *Server) delegatedStuckWhy(in delegatedecision.Input, d delegatedecision } } +// issueParkLabelStuck reports the case seen on hivecommons/hive#15021: the +// hive approved an issue and `approved-direction` landed, but the +// stage/045-needs-decision park label never came off, so the scanner keeps +// skipping the issue. The toast names the label and offers the lift. +func issueParkLabelStuck(in delegatedecision.Input, d delegatedecision.Decision) bool { + if in.Kind != delegatedecision.KindIssue || d.Verdict != delegatedecision.VerdictApprove { + return false + } + park, ack := false, false + for _, l := range in.Labels { + switch { + case strings.EqualFold(strings.TrimSpace(l), stagelabels.IssueNeedsDecision.Label()): + park = true + case strings.EqualFold(strings.TrimSpace(l), ghpkg.HumanAckLabel): + ack = true + } + } + return park && ack +} + // isApproveDecisionText reports a bare `/hive decision approve[d]`. func isApproveDecisionText(line string) bool { rest := strings.TrimSpace(strings.TrimPrefix(strings.TrimSpace(line), "/hive decision")) @@ -220,9 +243,17 @@ func isApproveDecisionText(line string) bool { // delegatedStuckOptions are the concrete next actions for a decision that // has not taken effect, in the popover's option shape so the SPA renders // them as buttons. Merging is the in-tracker merge-now action -// (hivecommons/hive#15087) for a merger, not a link out. -func delegatedStuckOptions(in delegatedecision.Input, d delegatedecision.Decision, mergerRole bool) []StageTrackerDecisionOption { +// (hivecommons/hive#15087) for a merger, not a link out. When why is the stuck 045 park +// label, the first option lifts it: `decide:approve` on an issue runs +// RecordOperatorIssueDecision, the audited path that removes the park +// label and tells the stage engine the park lifted. +func delegatedStuckOptions(in delegatedecision.Input, d delegatedecision.Decision, mergerRole bool, why string) []StageTrackerDecisionOption { var opts []StageTrackerDecisionOption + if why == delegatedecision.GlossaryParkLabelStuck { + opts = append(opts, + StageTrackerDecisionOption{Action: decisionActionApprove, Label: "Lift the park (remove " + stagelabels.IssueNeedsDecision.Label() + ")", Enabled: true}, + StageTrackerDecisionOption{Action: decisionActionRetry, Label: "Re-evaluate now", Enabled: true}) + } if in.Kind == delegatedecision.KindPR && d.Verdict != delegatedecision.VerdictCloseDuplicate && d.Verdict != delegatedecision.VerdictCloseSuperseded { o := decisionOption(decisionActionMergeNow, "Merge as maintainer", mergerRole, decisionWhyMergerRole) o.Consequence = "merges #" + strconv.Itoa(in.Number) + " now via hive's identity, attributed to you" @@ -255,7 +286,7 @@ func delegatedDecisionEffectResult(target RowActionTarget, in delegatedecision.I eff := delegatedecision.ExpectedEffect(d, in.Kind) at := prior.UTC().Truncate(time.Second) stamp := at.Format(time.RFC3339) - plainAction := delegatedecision.ActionPlain(d) + plainAction := delegatedecision.ActionPlainOn(d, in.Kind) out := RowActionResult{Target: target, Rule: d.Rule, AppliedAt: &at, Why: why} if !eff.Waits { out.Action = rowActionNoop @@ -272,8 +303,11 @@ func delegatedDecisionEffectResult(target RowActionTarget, in delegatedecision.I } out.Action = rowActionNoEffect out.Options = options - out.Outcome = "Hive decided " + plainAction + " at " + stamp + ", but it hasn't taken effect: " + delegatedecision.Plain(why) + "." - next := "Expected: " + eff.What + ". " + delegatedecision.Detail(why) + // The toast headline already says "Hive decided on "; the body + // does not say "decided" again. The SPA rewrites the RFC3339 stamp into + // the operator's clock (stageTrackerStampWords). + out.Outcome = delegatedecision.CapitalizeFirst(plainAction) + " at " + stamp + ", but it hasn't taken effect: " + delegatedecision.PlainOn(why, in.Kind) + "." + next := "Expected: " + eff.What + ". " + delegatedecision.DetailOn(why, in.Kind) if labels := optionLabels(options); len(labels) > 0 { next += " Options: " + strings.Join(labels, " · ") + "." } diff --git a/src/pkg/dashboard/stage_tracker_row_actions_test.go b/src/pkg/dashboard/stage_tracker_row_actions_test.go index a8b94639da..7f57026f56 100644 --- a/src/pkg/dashboard/stage_tracker_row_actions_test.go +++ b/src/pkg/dashboard/stage_tracker_row_actions_test.go @@ -23,6 +23,7 @@ func stageTrackerRowActionsPreamble(t *testing.T, html string) string { jsConstLine(t, html, "STAGE_TRACKER_MENU_FAIL_LINES"), jsConstBlock(t, html, "STAGE_TRACKER_DECISION_GLOSSARY"), jsFunc(t, html, "stageTrackerPlainWords"), + jsFunc(t, html, "stageTrackerShortAgo"), jsConstBlock(t, html, "STAGE_TRACKER_ACTION_LABELS"), jsConstLine(t, html, "STAGE_TRACKER_WHY_WRITE"), jsConstLine(t, html, "STAGE_TRACKER_WHY_ROLE"), @@ -1033,16 +1034,34 @@ assert.ok(text.outcome.startsWith('No change — hive already recorded this deci // hivecommons/hive#14822: a recorded decision that never took effect is a // warning that says why in plain words and carries the next actions. const stuck = { action: 'no-effect', rule: 'contributor-offline', why: 'self-decision-read-as-changes', target, applied_at: '2026-10-28T13:01:29Z', - outcome: "Hive decided close this PR and open a fresh hive-authored PR with the same commits at 2026-10-28T13:01:29Z, but it hasn't taken effect: hive's own decision comment was read as a reviewer asking for changes.", + outcome: "Close this PR and open a fresh hive-authored PR with the same commits at 2026-10-28T13:01:29Z, but it hasn't taken effect: hive's own decision comment was read as a reviewer asking for changes.", next: 'Options: Merge as maintainer · Re-run decision · Close as superseded · Send back for a new commit.', options: [{ action: 'decide:merge-now', label: 'Merge as maintainer', enabled: true }, { action: 'decide:delegate:rerun', label: 'Re-run decision', enabled: true }, { action: 'decide:close-superseded', label: 'Close as superseded', enabled: false, reason_if_disabled: 'write required' }, { action: 'decide:direction', label: 'Send back for a new commit', enabled: true }, { label: 'no action' }] }; -text = stageTrackerResultText(stuck, issue, { id: 'decide:delegate' }); -assert.strictEqual(text.head, "Hive decided on o/r#14938 → PR #14947: decided, but it hasn't taken effect (the author's clanker hasn't been connected since the nudge)"); +const stuckNow = Date.parse('2026-10-28T15:01:29Z'); +text = stageTrackerResultText(stuck, issue, { id: 'decide:delegate', nowMs: stuckNow }); +assert.strictEqual(text.head, "Hive decided on o/r#14938 → PR #14947: no effect yet (the author's clanker hasn't been connected since the nudge)", 'the headline does not say "decided" twice'); assert.strictEqual(text.type, 'warning'); assert.strictEqual(text.options.length, 4, 'options without an action are dropped'); // The raw RFC3339 stamp never reaches the operator (#15126). assert.ok(!/2026-10-28T13:01:29Z/.test(text.outcome) && / at 13:01( today)?, but/.test(text.outcome), text.outcome); assert.ok(text.why.startsWith('The merge gate read the hive'), text.why); assert.ok(!/contributor-offline|self-decision/.test(text.head + text.outcome + text.why), 'no bare slug reaches the operator'); +// hivecommons/hive#15021: an ISSUE's approve is never "approved for merge", +// and a stuck 045 park label is named with the lift as the first option. +const issueTarget = { repo: 'o/r', kind: 'issue', number: 15021, url: 'u15021' }; +const stuckIssue = { action: 'no-effect', rule: 'default-approve', why: 'park-label-stuck', target: issueTarget, applied_at: '2026-10-28T13:01:29Z', + outcome: "Approved to proceed — an agent may claim it at 2026-10-28T13:01:29Z, but it hasn't taken effect: stage/045-needs-decision is still on the issue; the scanner skips it until that label clears.", + next: 'Expected: the issue leaves Needs decision and an agent picks it up. Options: Lift the park (remove stage/045-needs-decision) · Re-evaluate now · Re-run decision · Give direction.', + options: [{ action: 'decide:approve', label: 'Lift the park (remove stage/045-needs-decision)', enabled: true }, { action: 'retry', label: 'Re-evaluate now', enabled: true }, { action: 'decide:delegate:rerun', label: 'Re-run decision', enabled: true }, { action: 'decide:direction', label: 'Give direction', enabled: true }] }; +text = stageTrackerResultText(stuckIssue, Object.assign({}, issue, { kind: 'issue', number: 15021 }), { id: 'decide:delegate', rowRef: 'o/r#15021', nowMs: stuckNow }); +assert.strictEqual(text.head, 'Hive decided on o/r#15021: no effect yet (no special rule applies; the hive took its own recommendation)'); +assert.ok(text.outcome.indexOf('approved for merge') < 0, text.outcome); +assert.ok(text.why.startsWith('The hive approved the issue and applied approved-direction'), text.why); +assert.strictEqual(text.options[0].action, 'decide:approve', 'the lift is the first option'); +assert.strictEqual(stageTrackerPlainWords('approve', false, 'issue'), 'approved to proceed — an agent may claim it'); +assert.strictEqual(stageTrackerPlainWords('approve', false, 'pr'), 'approved for merge'); +assert.strictEqual(stageTrackerPlainWords('approve'), 'approved for merge', 'no kind reads as a PR'); +assert.strictEqual(stageTrackerPlainWords('close-superseded', true, 'issue'), 'Closed because another issue already tracks the same work; the discussion continues there.'); +assert.strictEqual(stageTrackerPlainWords('close-duplicate', false, 'issue'), 'closed as a duplicate', 'an entry without issue words keeps its plain words'); assert.strictEqual(stageTrackerPlainWords('supersede'), 'close this PR and open a fresh hive-authored PR with the same commits'); assert.strictEqual(stageTrackerPlainWords('adoption-stalled:contributor-offline'), "the author's clanker hasn't been connected since the nudge"); assert.strictEqual(stageTrackerPlainWords('contributor-lane:changes-requested'), stageTrackerPlainWords('changes_requested')); diff --git a/src/pkg/dashboard/static/index.html b/src/pkg/dashboard/static/index.html index 86a2e3f257..d57e2c9d3c 100644 --- a/src/pkg/dashboard/static/index.html +++ b/src/pkg/dashboard/static/index.html @@ -17709,10 +17709,10 @@

All labels

"adoption-stalled:contributor-lane:workflow-path": {"kind": "reason", "plain": "the PR edits .github/workflows; the hive's App lacks the `workflows` permission, so it cannot adopt it", "detail": "The PR changes files under .github/workflows. The hive's GitHub App has no `workflows` permission, so the adoption fence refuses to publish those edits from the hive. Grant the App the `workflows` permission and re-run the decision, or have a person rebase and merge it on GitHub, or close it as superseded."}, "adoption-undone": {"kind": "reason", "plain": "the hive's copy was closed without merging and the adoption was undone", "detail": "The hive opened its copy, but the copy was closed without merging and a fresh one could not be opened, so the adoption was undone and the PR is back in its normal flow. Re-run the decision to adopt it again, or act on GitHub."}, "adoption/supersede": {"kind": "action", "plain": "close this PR and open a fresh hive-authored PR with the same commits", "detail": "Supersede means the hive closes this PR and opens a fresh hive-authored PR carrying the same commits and sign-off, then finishes it itself."}, - "approve": {"kind": "action", "plain": "approved for merge", "detail": "The hive approved it; the merge gate merges it once every check passes."}, - "approve-review": {"kind": "action", "plain": "approved for merge", "detail": "The hive approved it; the merge gate merges it once every check passes."}, - "approved": {"kind": "action", "plain": "approved for merge", "detail": "The hive approved it; the merge gate merges it once every check passes."}, - "author-association": {"kind": "reason", "plain": "no merge lane vouches for this PR's author; a maintainer merges", "detail": "The PR is ready, but its author is not a collaborator and holds no trusted or merger tier, so no merge lane vouches for them and the hive never merges it unattended. A maintainer merges it (Approve & merge as maintainer, or Approve — let hive merge), or trusts the author under 👥 Contributors."}, + "approve": {"kind": "action", "plain": "approved for merge", "detail": "The hive approved it; the merge gate merges it once every check passes.", "issue_plain": "approved to proceed — an agent may claim it", "issue_detail": "The hive approved the direction; the issue leaves Needs decision and an agent may claim it. Nothing is merged."}, + "approve-review": {"kind": "action", "plain": "approved for merge", "detail": "The hive approved it; the merge gate merges it once every check passes.", "issue_plain": "approved to proceed — an agent may claim it", "issue_detail": "The hive approved the direction; the issue leaves Needs decision and an agent may claim it. Nothing is merged."}, + "approved": {"kind": "action", "plain": "approved for merge", "detail": "The hive approved it; the merge gate merges it once every check passes.", "issue_plain": "approved to proceed — an agent may claim it", "issue_detail": "The hive approved the direction; the issue leaves Needs decision and an agent may claim it. Nothing is merged."}, + "author-association": {"kind": "reason", "plain": "no merge lane vouches for this PR's author; a maintainer merges", "detail": "The PR is ready, but its author is not a collaborator and holds no trusted or merger tier, so no merge lane vouches for them and the hive never merges it unattended. A maintainer merges it (Approve \u0026 merge as maintainer, or Approve — let hive merge), or trusts the author under 👥 Contributors."}, "author-online": {"kind": "reason", "plain": "the author's clanker is connected, so hive won't take the PR over", "detail": "Adoption is for authors whose clanker has gone offline; this author's clanker is connected, so the hive leaves the PR with them."}, "behind": {"kind": "reason", "plain": "the branch is behind the base branch", "detail": "The branch is behind the base branch and must be updated before it can merge."}, "blocker": {"kind": "reason", "plain": "the hive can't do this itself", "detail": "The item is blocked on something the hive cannot do: a permission the GitHub App lacks, or a step only a person may take. No decision clears it; grant the permission (and re-check) or do the step by hand (hivecommons/hive#15099)."}, @@ -17727,12 +17727,12 @@

All labels

"ci-red": {"kind": "reason", "plain": "CI is failing on this branch", "detail": "Required checks are failing on this branch; nothing merges until they are green."}, "close-as-duplicate": {"kind": "action", "plain": "closed as a duplicate", "detail": "Closed because an older item already tracks the same work."}, "close-duplicate": {"kind": "action", "plain": "closed as a duplicate", "detail": "Closed because an older item already tracks the same work."}, - "close-superseded": {"kind": "action", "plain": "closed because another PR carries the work", "detail": "Closed because another PR carries the same work; the author is credited there."}, - "closed": {"kind": "action", "plain": "closed because another PR carries the work", "detail": "Closed because another PR carries the same work; the author is credited there."}, + "close-superseded": {"kind": "action", "plain": "closed because another PR carries the work", "detail": "Closed because another PR carries the same work; the author is credited there.", "issue_plain": "closed because another issue carries the work", "issue_detail": "Closed because another issue already tracks the same work; the discussion continues there."}, + "closed": {"kind": "action", "plain": "closed because another PR carries the work", "detail": "Closed because another PR carries the same work; the author is credited there.", "issue_plain": "closed because another issue carries the work", "issue_detail": "Closed because another issue already tracks the same work; the discussion continues there."}, "comment-decision": {"kind": "action", "plain": "recorded the decision on GitHub", "detail": "The hive posted the decision as a `/hive decision` comment, the way a maintainer would."}, "conflict": {"kind": "reason", "plain": "the branch conflicts with the base branch", "detail": "The branch has merge conflicts with the base branch; it needs a rebase before anything can merge."}, "conflicting": {"kind": "reason", "plain": "the branch conflicts with the base branch", "detail": "The branch has merge conflicts with the base branch; it needs a rebase before anything can merge."}, - "contributor-lane:author-association": {"kind": "reason", "plain": "no merge lane vouches for this PR's author; a maintainer merges", "detail": "The PR is ready, but its author is not a collaborator and holds no trusted or merger tier, so no merge lane vouches for them and the hive never merges it unattended. A maintainer merges it (Approve & merge as maintainer, or Approve — let hive merge), or trusts the author under 👥 Contributors."}, + "contributor-lane:author-association": {"kind": "reason", "plain": "no merge lane vouches for this PR's author; a maintainer merges", "detail": "The PR is ready, but its author is not a collaborator and holds no trusted or merger tier, so no merge lane vouches for them and the hive never merges it unattended. A maintainer merges it (Approve \u0026 merge as maintainer, or Approve — let hive merge), or trusts the author under 👥 Contributors."}, "contributor-lane:changes-requested": {"kind": "reason", "plain": "a reviewer asked for changes; a new commit is needed", "detail": "A reviewer asked for changes on this branch. Approving cannot override that: only a new commit, or a maintainer merging by hand, moves it."}, "contributor-lane:sentinel-blocked": {"kind": "reason", "plain": "security-sensitive files changed; a maintainer must approve", "detail": "Security-sensitive files changed. The hive never merges until a maintainer reviews and removes the sentinel label."}, "contributor-lane:workflow-path": {"kind": "reason", "plain": "the PR edits .github/workflows; the hive's App lacks the `workflows` permission, so it cannot adopt it", "detail": "The PR changes files under .github/workflows. The hive's GitHub App has no `workflows` permission, so the adoption fence refuses to publish those edits from the hive. Grant the App the `workflows` permission and re-run the decision, or have a person rebase and merge it on GitHub, or close it as superseded."}, @@ -17743,16 +17743,16 @@

All labels

"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."}, - "directed": {"kind": "action", "plain": "told the author agent what to change", "detail": "The hive recorded direction for the author agent, which pushes a new commit with that change."}, - "direction": {"kind": "action", "plain": "told the author agent what to change", "detail": "The hive recorded direction for the author agent, which pushes a new commit with that change."}, + "directed": {"kind": "action", "plain": "told the author agent what to change", "detail": "The hive recorded direction for the author agent, which pushes a new commit with that change.", "issue_plain": "gave direction on the issue", "issue_detail": "The hive recorded direction on the issue; the agent that claims it works from that direction."}, + "direction": {"kind": "action", "plain": "told the author agent what to change", "detail": "The hive recorded direction for the author agent, which pushes a new commit with that change.", "issue_plain": "gave direction on the issue", "issue_detail": "The hive recorded direction on the issue; the agent that claims it works from that direction."}, "dirty": {"kind": "reason", "plain": "the branch conflicts with the base branch", "detail": "The branch has merge conflicts with the base branch; it needs a rebase before anything can merge."}, "effect-unknown": {"kind": "reason", "plain": "the hive did not say why", "detail": "The hive could not tell from the lane reason why the decision has not taken effect."}, "fix-then-merge": {"kind": "rule", "plain": "the branch isn't mergeable yet", "detail": "The branch cannot merge as it is (conflicts, red CI or a missing sign-off); the hive told the author agent exactly what to fix."}, "flaky-test": {"kind": "rule", "plain": "a flaky test, quarantined with a retry", "detail": "The failure is a flaky test: it is quarantined with a retry and a separate deflake task is filed, so it blocks nothing."}, "hive-policy": {"kind": "rule", "plain": "this changes the hive's own rules", "detail": "This changes the hive's own settings, governance or security posture; the hive only recommends and the owner confirms."}, - "hold": {"kind": "reason", "plain": "on hold; the hive does nothing until it is released", "detail": "The item is on hold. The hive does nothing with it until a person releases the hold."}, + "hold": {"kind": "reason", "plain": "on hold; the hive does nothing until it is released", "detail": "The PR is on hold. The hive does nothing with it until a person releases the hold.", "issue_detail": "The issue is on hold. No agent claims it until a person releases the hold."}, "human-changes-requested": {"kind": "reason", "plain": "a reviewer asked for changes; a new commit is needed", "detail": "A reviewer asked for changes on this branch. Approving cannot override that: only a new commit, or a maintainer merging by hand, moves it."}, - "human-merge": {"kind": "reason", "plain": "no merge lane vouches for this PR's author; a maintainer merges", "detail": "The PR is ready, but its author is not a collaborator and holds no trusted or merger tier, so no merge lane vouches for them and the hive never merges it unattended. A maintainer merges it (Approve & merge as maintainer, or Approve — let hive merge), or trusts the author under 👥 Contributors."}, + "human-merge": {"kind": "reason", "plain": "no merge lane vouches for this PR's author; a maintainer merges", "detail": "The PR is ready, but its author is not a collaborator and holds no trusted or merger tier, so no merge lane vouches for them and the hive never merges it unattended. A maintainer merges it (Approve \u0026 merge as maintainer, or Approve — let hive merge), or trusts the author under 👥 Contributors."}, "human-only": {"kind": "reason", "plain": "the hive can't do this itself", "detail": "The item is blocked on something the hive cannot do: a permission the GitHub App lacks, or a step only a person may take. No decision clears it; grant the permission (and re-check) or do the step by hand (hivecommons/hive#15099)."}, "label:needs-human": {"kind": "reason", "plain": "marked needs-human; a person must remove the label", "detail": "The item is marked needs-human: automated fixes ran out or a person flagged it. The hive waits until the label is removed."}, "labels-add": {"kind": "action", "plain": "added labels", "detail": "The hive added labels to the item."}, @@ -17766,10 +17766,11 @@

All labels

"not-merged-yet": {"kind": "reason", "plain": "the merge gate hasn't merged it", "detail": "The hive approved it but the merge gate has not merged it; its lane reason says what still blocks it."}, "owner-only": {"kind": "rule", "plain": "only the hive owner can do this", "detail": "This needs a secret, token or organization permission that only the hive owner holds; the hive cannot do it for you."}, "owner_only": {"kind": "rule", "plain": "only the hive owner can do this", "detail": "This needs a secret, token or organization permission that only the hive owner holds; the hive cannot do it for you."}, + "park-label-stuck": {"kind": "reason", "plain": "stage/045-needs-decision is still on the issue; the scanner skips it until that label clears", "detail": "The hive approved the issue and applied approved-direction, but the stage/045-needs-decision park label was never removed, so the scanner still skips the issue. Lift the park (it removes the label through the hive's audited label path) or re-evaluate the issue so the stage engine re-reads it."}, "prefer-contributor": {"kind": "rule", "plain": "a contributor's PR and a hive PR do the same work", "detail": "A contributor's PR and a hive-authored PR cover the same work; the hive prefers the contributor's when it is mergeable and current."}, "quarantine-flaky": {"kind": "action", "plain": "quarantined the flaky test", "detail": "The flaky test is quarantined with a retry and a deflake task is filed."}, "rail-hold": {"kind": "rule", "plain": "the item is on hold", "detail": "The item carries the hold label; the hive never acts on a held item until a person releases the hold."}, - "ready-for-human-merge": {"kind": "reason", "plain": "no merge lane vouches for this PR's author; a maintainer merges", "detail": "The PR is ready, but its author is not a collaborator and holds no trusted or merger tier, so no merge lane vouches for them and the hive never merges it unattended. A maintainer merges it (Approve & merge as maintainer, or Approve — let hive merge), or trusts the author under 👥 Contributors."}, + "ready-for-human-merge": {"kind": "reason", "plain": "no merge lane vouches for this PR's author; a maintainer merges", "detail": "The PR is ready, but its author is not a collaborator and holds no trusted or merger tier, so no merge lane vouches for them and the hive never merges it unattended. A maintainer merges it (Approve \u0026 merge as maintainer, or Approve — let hive merge), or trusts the author under 👥 Contributors."}, "recommend-only": {"kind": "action", "plain": "recommended only; a person confirms", "detail": "The hive only recommended; the item stays parked until a person confirms."}, "recommended": {"kind": "action", "plain": "recommended only; a person confirms", "detail": "The hive only recommended; the item stays parked until a person confirms."}, "red": {"kind": "reason", "plain": "CI is failing on this branch", "detail": "Required checks are failing on this branch; nothing merges until they are green."}, @@ -17790,22 +17791,29 @@

All labels

"still-parked": {"kind": "reason", "plain": "the item is still waiting on a person", "detail": "The item is still parked for a person's decision; the recorded decision did not move it."}, "supersede": {"kind": "action", "plain": "close this PR and open a fresh hive-authored PR with the same commits", "detail": "Supersede means the hive closes this PR and opens a fresh hive-authored PR carrying the same commits and sign-off, then finishes it itself."}, "supersede-now": {"kind": "action", "plain": "close this PR and open a fresh hive-authored PR with the same commits", "detail": "Supersede means the hive closes this PR and opens a fresh hive-authored PR carrying the same commits and sign-off, then finishes it itself."}, - "superseded": {"kind": "action", "plain": "closed because another PR carries the work", "detail": "Closed because another PR carries the same work; the author is credited there."}, - "untrusted-author": {"kind": "reason", "plain": "no merge lane vouches for this PR's author; a maintainer merges", "detail": "The PR is ready, but its author is not a collaborator and holds no trusted or merger tier, so no merge lane vouches for them and the hive never merges it unattended. A maintainer merges it (Approve & merge as maintainer, or Approve — let hive merge), or trusts the author under 👥 Contributors."}, + "superseded": {"kind": "action", "plain": "closed because another PR carries the work", "detail": "Closed because another PR carries the same work; the author is credited there.", "issue_plain": "closed because another issue carries the work", "issue_detail": "Closed because another issue already tracks the same work; the discussion continues there."}, + "untrusted-author": {"kind": "reason", "plain": "no merge lane vouches for this PR's author; a maintainer merges", "detail": "The PR is ready, but its author is not a collaborator and holds no trusted or merger tier, so no merge lane vouches for them and the hive never merges it unattended. A maintainer merges it (Approve \u0026 merge as maintainer, or Approve — let hive merge), or trusts the author under 👥 Contributors."}, "workflow-path": {"kind": "reason", "plain": "the PR edits .github/workflows; the hive's App lacks the `workflows` permission, so it cannot adopt it", "detail": "The PR changes files under .github/workflows. The hive's GitHub App has no `workflows` permission, so the adoption fence refuses to publish those edits from the hive. Grant the App the `workflows` permission and re-run the decision, or have a person rebase and merge it on GitHub, or close it as superseded."}, }; // Pure: plain words for a glossary slug ("supersede" → "close this PR and // open a fresh hive-authored PR with the same commits"). Strips a lane // prefix ("adoption-stalled:", "contributor-lane:"); unknown slugs are - // humanised (dashes/underscores → spaces), never shown raw. - function stageTrackerPlainWords(slug, detail) { + // humanised (dashes/underscores → spaces), never shown raw. itemKind + // 'issue' takes the entry's issue words where it has them: an issue's + // approve is "approved to proceed — an agent may claim it", never + // "approved for merge" (#15021). + function stageTrackerPlainWords(slug, detail, itemKind) { let s = String(slug == null ? '' : slug).trim().toLowerCase(); if (!s) return ''; const hit = k => STAGE_TRACKER_DECISION_GLOSSARY[k] ? STAGE_TRACKER_DECISION_GLOSSARY[k] : null; let e = hit(s); if (!e && s.indexOf(':') > 0) { e = hit(s.slice(0, s.indexOf(':'))) || hit(s.slice(s.indexOf(':') + 1).trim()); } if (!e && s.indexOf('/') > 0) e = hit(s.slice(s.lastIndexOf('/') + 1)); - if (e) return detail ? e.detail : e.plain; + if (e) { + const issue = itemKind === 'issue'; + if (detail) return (issue && e.issue_detail) || e.detail; + return (issue && e.issue_plain) || e.plain; + } return s.replace(/^[a-z-]+:/, '').replace(/[-_]+/g, ' ').trim(); } // Pure: the DCO caveat the merge confirmations print BEFORE acting @@ -19195,7 +19203,7 @@

All labels

adopted: 'adopted', approved: 'approved', recommended: 'recommendation only', closed: 'closed', directed: 'direction recorded', refused: 'refused', 'decided-each': 'decided per PR', merged: 'merged', 'queued-for-merge': 'queued for merge', [STAGE_TRACKER_ACTION_REBASE_QUEUED]: 'rebase queued, merge to follow', held: 'held', released: 'hold released', rescanned: 'rescanned', 'triage-accepted': 'triage accepted', 'needs-human': 'marked needs-human', rerouted: 'rerouted', [STAGE_TRACKER_ACTION_NOOP]: 'no change', - [STAGE_TRACKER_ACTION_NO_EFFECT]: "decided, but it hasn't taken effect", + [STAGE_TRACKER_ACTION_NO_EFFECT]: 'no effect yet', }; function stageTrackerActingCaption(id, item) { if (id === 'decide:merge-now' && item && stageTrackerNeedsRebase(item)) return 'Rebasing, then merging…'; @@ -19222,7 +19230,7 @@

All labels

if (data.status === 'debounced' || data.status === 'in-progress') return { action: STAGE_TRACKER_ACTION_NOOP, target, outcome: 'No change — a rescan ' + (data.status === 'debounced' ? 'finished moments ago' : 'is already running') + '.', next: '' }; if (data.alreadyAccepted) return { action: STAGE_TRACKER_ACTION_NOOP, target, outcome: 'No change — triage was already accepted.', next: '' }; const d = data.decision; - if (d && typeof d === 'object') return { action: d.verdict || 'recommended', rule: d.rule || '', target, outcome: stageTrackerPlainWords(d.verdict || '?') + (d.rule ? ' (' + stageTrackerPlainWords(d.rule) + ')' : '') + (d.keeps_park ? ' — kept for the owner' : ''), next: '' }; + if (d && typeof d === 'object') return { action: d.verdict || 'recommended', rule: d.rule || '', target, outcome: stageTrackerPlainWords(d.verdict || '?', false, item.kind) + (d.rule ? ' (' + stageTrackerPlainWords(d.rule, false, item.kind) + ')' : '') + (d.keeps_park ? ' — kept for the owner' : ''), next: '' }; return { action: id, target, outcome: stageTrackerActionLabel(id) + ' done.', next: '' }; } function stageTrackerErrorResult(id, item, error) { @@ -19247,9 +19255,11 @@

All labels

else head = stageTrackerActionLabel(ctx.id || '') + ' on ' + rowRef + toward; const word = error ? '' : (STAGE_TRACKER_ACTION_WORDS[result.action] || result.action || ''); // The rule in plain words from the glossary, never the bare slug. - const rule = result.rule ? ' (' + stageTrackerPlainWords(result.rule) + ')' : ''; + const tKind = t.kind === 'pr' || t.kind === 'issue' ? t.kind : item.kind; + const rule = result.rule ? ' (' + stageTrackerPlainWords(result.rule, false, tKind) + ')' : ''; if (word) head += ': ' + word + rule; - const local = typeof stageTrackerLocalStamps === 'function' ? stageTrackerLocalStamps : (x => x); + const nowMs = ctx && typeof ctx.nowMs === 'number' ? ctx.nowMs : Date.now(); + const local = typeof stageTrackerLocalStamps === 'function' ? (x => stageTrackerLocalStamps(x, nowMs)) : (x => x); let outcome = local(result.outcome || ''); // A decision's toast leads with its outcome in one line ("Adopted: // hive opened #15123 …"); who decided what, and under which rule, is @@ -19261,7 +19271,7 @@

All labels

// Options ride a no-effect / refused result, and an approval on a PR // that needs a rebase ("Rebase, then merge as maintainer"). const options = (noEffect || refused || result.action === 'approved') && Array.isArray(result.options) ? result.options.filter(o => o && o.action && o.label) : []; - return { head, outcome, next: local(result.next || ''), warn, posted: posted.length ? 'Posted: ' + posted.join(' · ') : '', options, why: noEffect ? stageTrackerPlainWords(result.why || 'no-effect', true) : '', type: error ? 'error' : (noEffect || refused ? 'warning' : (noop ? 'info' : 'success')), url: t.url || item.url || '', linkText: 'Open ' + (t.kind === 'pr' ? 'PR' : 'issue') + ' #' + (t.number || item.number) }; + return { head, outcome, next: local(result.next || ''), warn, posted: posted.length ? 'Posted: ' + posted.join(' · ') : '', options, why: noEffect ? stageTrackerPlainWords(result.why || 'no-effect', true, tKind) : '', type: error ? 'error' : (noEffect || refused ? 'warning' : (noop ? 'info' : 'success')), url: t.url || item.url || '', linkText: 'Open ' + (t.kind === 'pr' ? 'PR' : 'issue') + ' #' + (t.number || item.number) }; } // Pure: the ⚠ sentinel paragraph a result toast carries. The row's // alert is what the action started from, so it is repeated only while diff --git a/src/pkg/delegatedecision/decision_comment.go b/src/pkg/delegatedecision/decision_comment.go index 6d9a425c6e..e4bc37339c 100644 --- a/src/pkg/delegatedecision/decision_comment.go +++ b/src/pkg/delegatedecision/decision_comment.go @@ -58,15 +58,22 @@ func ExpectedEffect(d Decision, kind Kind) Effect { } } -// ActionPlain is the plain-words name of what d does ("close this PR and -// open a fresh hive-authored PR with the same commits"). +// ActionPlain is the plain-words name of what d does on a PR ("close this +// PR and open a fresh hive-authored PR with the same commits"). func ActionPlain(d Decision) string { + return ActionPlainOn(d, KindPR) +} + +// ActionPlainOn is ActionPlain for an item of kind: an issue's `approve` +// is "approved to proceed — an agent may claim it", never "approved for +// merge". +func ActionPlainOn(d Decision, kind Kind) string { switch d.Verdict { case VerdictApprove, VerdictQuarantineFlaky, VerdictAcceptRatchet, VerdictAcceptProposal, VerdictDirection, VerdictCloseDuplicate, VerdictCloseSuperseded, VerdictOwnerOnly, VerdictRecommendOnly, VerdictRefused: - return VerdictPlain(d.Verdict) + return VerdictPlainOn(d.Verdict, kind) case VerdictAdoptSupersede: - return Plain(GlossarySupersede) + return PlainOn(GlossarySupersede, kind) } return humanizeSlug(string(d.Verdict)) } @@ -82,13 +89,13 @@ type CommentOptions struct { // PlainWords renders the four operator lines for d. func PlainWords(d Decision, opts CommentOptions) string { var b strings.Builder - fmt.Fprintf(&b, "**Hive decided:** %s.", capitalizeFirst(ActionPlain(d))) + fmt.Fprintf(&b, "**Hive decided:** %s.", CapitalizeFirst(ActionPlainOn(d, opts.Kind))) if why := RulePlain(d.Rule); why != "" { - fmt.Fprintf(&b, "\n**Why:** %s.", capitalizeFirst(why)) + fmt.Fprintf(&b, "\n**Why:** %s.", CapitalizeFirst(why)) } eff := ExpectedEffect(d, opts.Kind) if eff.Waits { - fmt.Fprintf(&b, "\n**What happens next:** %s", capitalizeFirst(eff.What)) + fmt.Fprintf(&b, "\n**What happens next:** %s", CapitalizeFirst(eff.What)) if opts.EffectTimeout > 0 { fmt.Fprintf(&b, " — expected within %s", humanDuration(opts.EffectTimeout)) } @@ -145,11 +152,11 @@ func IsStalledComment(body, rule string) bool { func StalledCommentBody(d Decision, kind Kind, decidedAt time.Time, whySlug string, options []string, hiveID string) string { eff := ExpectedEffect(d, kind) var b strings.Builder - fmt.Fprintf(&b, "**Hive decided %s at %s, but it hasn't taken effect.**", ActionPlain(d), decidedAt.UTC().Truncate(time.Second).Format(time.RFC3339)) + fmt.Fprintf(&b, "**Hive decided %s at %s, but it hasn't taken effect.**", ActionPlainOn(d, kind), decidedAt.UTC().Truncate(time.Second).Format(time.RFC3339)) if eff.What != "" { - fmt.Fprintf(&b, "\n\n**What should have happened:** %s.", capitalizeFirst(eff.What)) + fmt.Fprintf(&b, "\n\n**What should have happened:** %s.", CapitalizeFirst(eff.What)) } - why := Detail(whySlug) + why := DetailOn(whySlug, kind) if strings.TrimSpace(whySlug) == "" { why = Detail(GlossaryEffectUnknown) } @@ -163,7 +170,8 @@ func StalledCommentBody(d Decision, kind Kind, decidedAt time.Time, whySlug stri return b.String() } -func capitalizeFirst(s string) string { +// CapitalizeFirst upper-cases the first byte of a trimmed phrase. +func CapitalizeFirst(s string) string { s = strings.TrimSpace(s) if s == "" { return s diff --git a/src/pkg/delegatedecision/decision_glossary.go b/src/pkg/delegatedecision/decision_glossary.go index 81a78b393f..02c5b87df4 100644 --- a/src/pkg/delegatedecision/decision_glossary.go +++ b/src/pkg/delegatedecision/decision_glossary.go @@ -37,11 +37,18 @@ const ( // popover, tooltip or PR comment. Aliases are other spellings of the same // slug (lane tokens, label names) that resolve to this entry. type GlossaryEntry struct { - Slug string `json:"slug"` - Kind GlossaryKind `json:"kind"` - Plain string `json:"plain"` - Detail string `json:"detail"` - Aliases []string `json:"aliases,omitempty"` + Slug string `json:"slug"` + Kind GlossaryKind `json:"kind"` + Plain string `json:"plain"` + Detail string `json:"detail"` + // IssuePlain / IssueDetail are the words for the same slug when the + // item is an ISSUE; empty means Plain / Detail fit both kinds. A + // decision of `approve` on a PR is "approved for merge"; on an issue + // nothing merges — it is "approved to proceed — an agent may claim + // it" (hive's own spoke showed the PR words on issue #15021). + IssuePlain string `json:"issue_plain,omitempty"` + IssueDetail string `json:"issue_detail,omitempty"` + Aliases []string `json:"aliases,omitempty"` } // Slugs the glossary and its callers share. Rule slugs live beside the @@ -74,6 +81,7 @@ const ( GlossaryAdoptionExecuting = "adoption-executing" GlossaryAdoptionUndone = "adoption-undone" GlossaryBlocker = "blocker" + GlossaryParkLabelStuck = "park-label-stuck" // 045 park label outlived the approval it recorded (hivecommons/hive#15252) glossaryFallbackUnknown = "the hive did not say why" ) @@ -127,13 +135,22 @@ var glossary = []GlossaryEntry{ {Slug: GlossaryAdopt, Kind: GlossaryAction, Plain: "hive takes over finishing this PR", Detail: "Adopt means the hive takes over finishing this PR: it rebases, fixes CI and merges it, keeping the author's commits and sign-off."}, {Slug: string(VerdictApprove), Kind: GlossaryAction, Plain: "approved for merge", - Detail: "The hive approved it; the merge gate merges it once every check passes.", Aliases: []string{"approved", string(ActionApproveReview)}}, + Detail: "The hive approved it; the merge gate merges it once every check passes.", + IssuePlain: "approved to proceed — an agent may claim it", + IssueDetail: "The hive approved the direction; the issue leaves Needs decision and an agent may claim it. Nothing is merged.", + Aliases: []string{"approved", string(ActionApproveReview)}}, {Slug: string(VerdictDirection), Kind: GlossaryAction, Plain: "told the author agent what to change", - Detail: "The hive recorded direction for the author agent, which pushes a new commit with that change.", Aliases: []string{"directed"}}, + Detail: "The hive recorded direction for the author agent, which pushes a new commit with that change.", + IssuePlain: "gave direction on the issue", + IssueDetail: "The hive recorded direction on the issue; the agent that claims it works from that direction.", + Aliases: []string{"directed"}}, {Slug: string(VerdictCloseDuplicate), Kind: GlossaryAction, Plain: "closed as a duplicate", Detail: "Closed because an older item already tracks the same work.", Aliases: []string{string(ActionCloseDuplicate)}}, {Slug: string(VerdictCloseSuperseded), Kind: GlossaryAction, Plain: "closed because another PR carries the work", - Detail: "Closed because another PR carries the same work; the author is credited there.", Aliases: []string{"closed", "superseded"}}, + Detail: "Closed because another PR carries the same work; the author is credited there.", + IssuePlain: "closed because another issue carries the work", + IssueDetail: "Closed because another issue already tracks the same work; the discussion continues there.", + Aliases: []string{"closed", "superseded"}}, {Slug: string(VerdictQuarantineFlaky), Kind: GlossaryAction, Plain: "quarantined the flaky test", Detail: "The flaky test is quarantined with a retry and a deflake task is filed."}, {Slug: string(VerdictAcceptRatchet), Kind: GlossaryAction, Plain: "accepted as a ratchet", @@ -168,7 +185,8 @@ var glossary = []GlossaryEntry{ {Slug: GlossaryAuthorOnline, Kind: GlossaryReason, Plain: "the author's clanker is connected, so hive won't take the PR over", Detail: "Adoption is for authors whose clanker has gone offline; this author's clanker is connected, so the hive leaves the PR with them."}, {Slug: GlossaryHold, Kind: GlossaryReason, Plain: "on hold; the hive does nothing until it is released", - Detail: "The item is on hold. The hive does nothing with it until a person releases the hold."}, + Detail: "The PR is on hold. The hive does nothing with it until a person releases the hold.", + IssueDetail: "The issue is on hold. No agent claims it until a person releases the hold."}, {Slug: GlossaryDCO, Kind: GlossaryReason, 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.", Aliases: []string{"dco-missing"}}, {Slug: GlossaryNeedsHuman, Kind: GlossaryReason, Plain: "marked needs-human; a person must remove the label", @@ -186,6 +204,8 @@ var glossary = []GlossaryEntry{ {Slug: GlossaryBlocker, Kind: GlossaryReason, Plain: "the hive can't do this itself", Detail: "The item is blocked on something the hive cannot do: a permission the GitHub App lacks, or a step only a person may take. No decision clears it; grant the permission (and re-check) or do the step by hand (hivecommons/hive#15099).", Aliases: []string{"capability", "human-only"}}, + {Slug: GlossaryParkLabelStuck, Kind: GlossaryReason, Plain: "stage/045-needs-decision is still on the issue; the scanner skips it until that label clears", + Detail: "The hive approved the issue and applied approved-direction, but the stage/045-needs-decision park label was never removed, so the scanner still skips the issue. Lift the park (it removes the label through the hive's audited label path) or re-evaluate the issue so the stage engine re-reads it."}, {Slug: GlossaryStillParked, Kind: GlossaryReason, Plain: "the item is still waiting on a person", Detail: "The item is still parked for a person's decision; the recorded decision did not move it."}, {Slug: GlossaryNotMergedYet, Kind: GlossaryReason, Plain: "the merge gate hasn't merged it", @@ -281,6 +301,29 @@ func Detail(slug string) string { return humanizeSlug(slug) } +// PlainOn is Plain for an item of kind: an issue takes the entry's +// IssuePlain when it has one, a PR (or an unknown kind) the PR words. +func PlainOn(slug string, kind Kind) string { + if e, ok := Explain(slug); ok { + if kind == KindIssue && e.IssuePlain != "" { + return e.IssuePlain + } + return e.Plain + } + return humanizeSlug(slug) +} + +// DetailOn is Detail for an item of kind (see PlainOn). +func DetailOn(slug string, kind Kind) string { + if e, ok := Explain(slug); ok { + if kind == KindIssue && e.IssueDetail != "" { + return e.IssueDetail + } + return e.Detail + } + return humanizeSlug(slug) +} + // RulePlain is Plain for a Decision.Rule; "" for an empty rule. func RulePlain(rule string) string { if strings.TrimSpace(rule) == "" { @@ -289,11 +332,16 @@ func RulePlain(rule string) string { return Plain(rule) } -// VerdictPlain is Plain for a verdict. +// VerdictPlain is Plain for a verdict (PR words). func VerdictPlain(v Verdict) string { return Plain(string(v)) } +// VerdictPlainOn is Plain for a verdict on an item of kind. +func VerdictPlainOn(v Verdict, kind Kind) string { + return PlainOn(string(v), kind) +} + func humanizeSlug(slug string) string { s := strings.TrimSpace(slug) if s == "" { @@ -305,19 +353,23 @@ func humanizeSlug(slug string) string { // GlossaryJSON renders the glossary as the JSON object the SPA mirrors // (STAGE_TRACKER_DECISION_GLOSSARY in index.html): slug → {kind, plain, -// detail}, with every alias as its own key pointing at the same words, so -// the browser resolves a token exactly the way Explain does. +// detail[, issue_plain, issue_detail]}, with every alias as its own key +// pointing at the same words, so the browser resolves a token exactly the +// way Explain / PlainOn do. func GlossaryJSON() string { type entry struct { - Kind GlossaryKind `json:"kind"` - Plain string `json:"plain"` - Detail string `json:"detail"` + Kind GlossaryKind `json:"kind"` + Plain string `json:"plain"` + Detail string `json:"detail"` + IssuePlain string `json:"issue_plain,omitempty"` + IssueDetail string `json:"issue_detail,omitempty"` } m := map[string]entry{} for _, e := range glossary { - m[e.Slug] = entry{Kind: e.Kind, Plain: e.Plain, Detail: e.Detail} + v := entry{Kind: e.Kind, Plain: e.Plain, Detail: e.Detail, IssuePlain: e.IssuePlain, IssueDetail: e.IssueDetail} + m[e.Slug] = v for _, a := range e.Aliases { - m[a] = entry{Kind: e.Kind, Plain: e.Plain, Detail: e.Detail} + m[a] = v } } b, err := json.MarshalIndent(m, "", " ") diff --git a/src/pkg/delegatedecision/decision_glossary_test.go b/src/pkg/delegatedecision/decision_glossary_test.go index 937d687314..e13c52fa9b 100644 --- a/src/pkg/delegatedecision/decision_glossary_test.go +++ b/src/pkg/delegatedecision/decision_glossary_test.go @@ -175,3 +175,49 @@ func TestStalledCommentBody(t *testing.T) { t.Error("unknown why falls back to the effect-unknown entry") } } + +// TestGlossaryWordsPerItemKind: an issue's `approve` is never "approved for +// merge" (hivecommons/hive#15021); entries without issue words fall back +// to their plain words; the JSON mirror carries the issue words. +func TestGlossaryWordsPerItemKind(t *testing.T) { + approve := Decision{Verdict: VerdictApprove} + if got := ActionPlainOn(approve, KindIssue); got != "approved to proceed — an agent may claim it" { + t.Fatalf("issue approve = %q", got) + } + if got, want := ActionPlainOn(approve, KindPR), ActionPlain(approve); got != want || got != "approved for merge" { + t.Fatalf("pr approve = %q / %q", got, want) + } + if got := ActionPlainOn(Decision{Verdict: VerdictDirection}, KindIssue); strings.Contains(got, "author agent") { + t.Fatalf("issue direction = %q", got) + } + if got := ActionPlainOn(Decision{Verdict: VerdictCloseSuperseded}, KindIssue); strings.Contains(got, "PR") { + t.Fatalf("issue close-superseded = %q", got) + } + if got, want := PlainOn(string(VerdictCloseDuplicate), KindIssue), Plain(string(VerdictCloseDuplicate)); got != want { + t.Fatalf("fallback = %q, want %q", got, want) + } + if got := DetailOn(GlossaryHold, KindIssue); !strings.Contains(got, "issue") || DetailOn(GlossaryHold, KindPR) == got { + t.Fatalf("hold issue detail = %q", got) + } + if got := PlainOn("unknown-thing", KindIssue); got != "unknown thing" { + t.Fatalf("unknown = %q", got) + } + words := PlainWords(approve, CommentOptions{Kind: KindIssue}) + if strings.Contains(words, "approved for merge") || !strings.Contains(words, "Approved to proceed") { + t.Fatalf("issue PlainWords = %q", words) + } + stalled := StalledCommentBody(approve, KindIssue, time.Date(2026, 10, 28, 20, 41, 22, 0, time.UTC), GlossaryParkLabelStuck, nil, "h1") + if strings.Contains(stalled, "approved for merge") || !strings.Contains(stalled, "stage/045-needs-decision park label was never removed") { + t.Fatalf("stalled = %q", stalled) + } + var m map[string]map[string]string + if err := json.Unmarshal([]byte(GlossaryJSON()), &m); err != nil { + t.Fatal(err) + } + if m["approve"]["issue_plain"] != "approved to proceed — an agent may claim it" || m["approved"]["issue_plain"] != m["approve"]["issue_plain"] { + t.Fatalf("mirror: %v", m["approve"]) + } + if _, has := m["close-duplicate"]["issue_plain"]; has { + t.Fatalf("mirror carries an empty issue_plain: %v", m["close-duplicate"]) + } +}