Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/added-attention-pilot-issue-status-card.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- `github.notifications.attention_pilot` (default off) opts a hive in to the attention pilot ([#16358](https://github.com/hivecommons/hive/issues/16358), part of [#16270](https://github.com/hivecommons/hive/issues/16270)): routine issue notes — partial work, close/auto-close narration (merged fix, decomposed parent), reopened-after-merge, stage regressions, the covering-PR note and the blocker-settled note — fold into the issue's single `hive:status` card through the shared status writer, and a newly required action (confirming a merged fix) is still announced by exactly one notifying write. With the flag off nothing changes.
3 changes: 3 additions & 0 deletions src/cmd/hive/main_sweeps.go
Original file line number Diff line number Diff line change
Expand Up @@ -1986,6 +1986,9 @@ func installReviewRelaySettings(client *github.Client, cfg *config.Config, logge
// github.notifications.shadow (hivecommons/hive#16264): would-notify
// instrumentation only, read live; nothing is suppressed.
client.SetNotificationsShadow(func() bool { return cfg.GitHub.Notifications.Shadow })
// github.notifications.attention_pilot (hivecommons/hive#16358): fold
// routine issue notes into the issue's hive:status card. Read live.
client.SetAttentionPilot(func() bool { return cfg.GitHub.Notifications.AttentionPilot })
// review.require_labels (PR approval allow-list): the relay's half of the
// gate, read live so a Features-tab edit applies to the next request.
client.SetReviewRequireLabels(func() []string { return cfg.Review.RequireLabels })
Expand Down
56 changes: 56 additions & 0 deletions src/docs/notifications.md
Original file line number Diff line number Diff line change
Expand Up @@ -415,6 +415,7 @@ without a class. Review submissions and review requests are always counted as
| `github.(*Client).SweepLegacyFleetReportIssues` | `status` | |
| `github.(*Client).UpsertIssueMarkerComment` | `status` | passthrough wrapper; attributed to its caller |
| `github.(*clientStatusForge).CreateComment` | `status` | passthrough wrapper (status-comment forge under `prstatus.Write`); attributed to its caller |
| `github.(*Client).PostIssueNote` | `status` | passthrough wrapper (issue status card, `attention_pilot`); attributed to its caller |
| `github.(*Client).closeDecomposedParent` | `status` | |
| `github.(*Client).closeIssueForMergedPRClaimWithIssue` | `status` | |
| `github.(*Client).closeSupersededPRDecision` | `status` | |
Expand All @@ -440,6 +441,7 @@ without a class. Review submissions and review requests are always counted as
| `dashboard.(*Server).handleReviewPipelineSendToHuman` | `attention` | |
| `dashboard.(*Server).reroutePickupLapsed` | `attention` | |
| `dashboard.(*Server).settleRebaseMergeLedger` | `attention` | |
| `github.(*Client).PostIssueAttention` | `attention` | the one explicit announcement of a newly required action (`attention_pilot`) |
| `github.(*Client).NudgeTrackingIssueClosingRefs` | `attention` | |
| `github.(*Client).appendFoldedFinding` | `attention` | |
| `github.(*Client).bindProwLgtm` | `attention` | |
Expand Down Expand Up @@ -483,3 +485,57 @@ Go client; listed for completeness):
| `promote-stable.yml` | `attention` | Emergency stable-promotion exception note. |
| `weekly-competitor-report.md` (`.lock.yml`) | `status` | Weekly report comment on the tracking issue. |
| `hive-ok-to-test.yml` | `protocol_command` | The `/ok-to-test` command that releases held workflow runs. |

## Attention pilot and the issue status card (`github.notifications.attention_pilot`)

The attention pilot is the opt-in gate for the attention changes in
[#16270](https://github.com/hivecommons/hive/issues/16270); every
attention-pilot behaviour reads this one flag. It is **off by default**, and
with it off the hive behaves exactly as before.

```yaml
github:
notifications:
attention_pilot: true # default false
```

Quiet mode (`github.notifications.mode: quiet`) folds the hive's PR
bookkeeping into one edited `hive:status` comment but leaves issue notes as
comments of their own, so one issue lifecycle (partial merge, remainder,
close) could still email its watchers several times. With the pilot on, the
issue gets the same card, written through the same single status writer
(`prstatus.Write`, serialised per item, duplicates merged into the oldest):

- **Folded into the card** (section key in brackets): partial work left by a
non-closing merged PR (`issue-partial:<pr>`), close/auto-close narration —
"Fixed by #N … Reply /reopen if the problem persists" and the decomposed
parent's all-children-delivered close — (`issue-close`),
reopened-after-merge (`issue-reopened`), a lapsed claim's stage regression
(`stage-regressed`), the covering-PR stage note (`issue-pr-link`) and the
blocker-settled note (`unblocked`, whatever `mode` says). Claim notes
already fold under `claim` in quiet mode. The legacy markers stay inside
each section, so every reader that greps for them still finds them, and
the reopen/release guidance stays visible on the card.
- **Native events notify instead.** The issue is still closed (with its
state reason) by the API call, which is GitHub's own notification; the
hive no longer adds a "for visibility" comment beside it.
- **A newly required action is still announced once.** Editing a comment
notifies nobody, so an action asked of a person (today: confirming a
merged fix with `/fixed` or `/reopen`) is recorded on the card under
`attention:<cause>` *and* announced by exactly one notifying write —
creating the card when the issue has none, otherwise one explicit
comment tagged `<!-- hive:attention cause=<cause> -->`. A later pass that
sees the tag only refreshes the card; a new cause gets its own single
announcement. The explicit comment consults the write-back gate like
every other unsolicited comment; a refusal is returned to the caller as
`writeback.ErrSuppressed` before anything is written (no comment, no tag
on the card), so the action is not reported as announced and the next
pass retries once the policy admits it.
- **Not folded:** the blocked sweep's re-target note (`<!-- hive:blocked-on … -->`)
stays a comment, because the sweep reads the *newest* blocked-on marker
by comment order and a section in an older card would not be newest.

Acknowledge/snooze commands, reminders and the per-repo attention queue are
separate pilot steps ([#16359](https://github.com/hivecommons/hive/issues/16359),
[#16361](https://github.com/hivecommons/hive/issues/16361)–[#16363](https://github.com/hivecommons/hive/issues/16363))
and are not part of this flag's first behaviour.
6 changes: 6 additions & 0 deletions src/docs/operator-reference/sweeps-and-operations.md
Original file line number Diff line number Diff line change
Expand Up @@ -594,6 +594,12 @@ exported on `/metrics`. See [GitHub writes: inventory and shadow
mode](../notifications.md#github-writes-inventory-and-shadow-mode-githubnotificationsshadow)
for the write-site inventory and how to compare baseline windows.

`github.notifications.attention_pilot: true` (default off) opts the hive in
to the attention pilot: routine issue notes fold into the issue's single
`hive:status` card, and a newly required action is still announced by
exactly one notifying write. See [Attention pilot and the issue status
card](../notifications.md#attention-pilot-and-the-issue-status-card-githubnotificationsattention_pilot).

## Suspicious-activity alerts (`sentinel`)

The sentinel evaluates open PRs in the watched repos — human, bot, or agent —
Expand Down
2 changes: 1 addition & 1 deletion src/docs/scale-envelope.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ ones to:
2. **Truncation must preserve the prioritization signal, not cut an arbitrary slice.**
This holds today and is easy to assume backwards:
- Issues are sorted by actionable rank tier, then **oldest first** within each tier before any cap is applied
(`RankActionableIssues`, `src/pkg/github/client.go:5068-5078`, descending `AgeMinutes` within each tier).
(`RankActionableIssues`, `src/pkg/github/client.go:5075-5085`, descending `AgeMinutes` within each tier).
- PRs are sorted by **review class then oldest-first within class**
(`SortPullRequestsForReview`, `src/pkg/github/review_priority.go:334`;
fixes → refactors/docs → tests).
Expand Down
8 changes: 8 additions & 0 deletions src/pkg/config/github_notifications.go
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,14 @@ type GitHubNotificationsConfig struct {
// decision is recorded for repeats of the same condition. Measurement
// only — nothing is suppressed or rerouted. Default off.
Shadow bool `yaml:"shadow,omitempty" json:"shadow,omitempty"`
// AttentionPilot opts this hive in to the attention pilot
// (hivecommons/hive#16270): the single gate every attention-pilot
// change reads. With it on, routine issue notes (partial work,
// dependency progress, close/auto-close narration, regressions, PR
// links) fold into the issue's one hive:status card, and a newly
// required action is still announced by exactly one notifying write.
// Default off: behaviour is unchanged.
AttentionPilot bool `yaml:"attention_pilot,omitempty" json:"attention_pilot,omitempty"`
}

// Quiet reports whether the hive should fold its PR notes into one edited
Expand Down
23 changes: 22 additions & 1 deletion src/pkg/config/github_notifications_test.go
Original file line number Diff line number Diff line change
@@ -1,6 +1,10 @@
package config

import "testing"
import (
"testing"

"gopkg.in/yaml.v3"
)

func TestGitHubNotificationsConfig(t *testing.T) {
for mode, quiet := range map[string]bool{"": true, "quiet": true, "Quiet": true, "normal": false, "NORMAL": false} {
Expand All @@ -22,3 +26,20 @@ func TestGitHubNotificationsShadowDefaultsOff(t *testing.T) {
t.Fatal("github.notifications.shadow must default to off")
}
}

func TestGitHubNotificationsAttentionPilotDefaultsOff(t *testing.T) {
if (GitHubNotificationsConfig{}).AttentionPilot {
t.Fatal("github.notifications.attention_pilot must default to off")
}
var c struct {
GitHub struct {
Notifications GitHubNotificationsConfig `yaml:"notifications"`
} `yaml:"github"`
}
if err := yaml.Unmarshal([]byte("github:\n notifications:\n attention_pilot: true\n"), &c); err != nil {
t.Fatal(err)
}
if !c.GitHub.Notifications.AttentionPilot {
t.Fatal("github.notifications.attention_pilot: true must parse as on")
}
}
1 change: 1 addition & 0 deletions src/pkg/dashboard/settings_parity_allowlist.txt
Original file line number Diff line number Diff line change
Expand Up @@ -198,6 +198,7 @@ evidence.complexity.static_analysis # TODO #11854
github.additional_bot_logins[] # TODO #11854
github.attention.admitter.<key> # single-admitter ownership and flap window are YAML-only rollout controls; see src/docs/attention-episodes.md
github.attention.flap_window # single-admitter ownership and flap window are YAML-only rollout controls; see src/docs/attention-episodes.md
github.notifications.attention_pilot # opt-in attention-pilot issue status card; yaml-only, see docs/notifications.md (#16358)
github.notifications.mode # quiet|normal PR notification mode; yaml-only, see operator-reference.md
github.shared_uid_read_token # shared-UID App read-token opt-in; yaml-only, restart required (#14778)
good_first_issue.exclude_labels[] # advanced scorer tuning; yaml-only (#12185)
Expand Down
4 changes: 4 additions & 0 deletions src/pkg/github/client.go
Original file line number Diff line number Diff line change
Expand Up @@ -286,6 +286,10 @@ type Client struct {
// recorded in notificationShadow. nil reads as off.
shadowNotificationsFn func() bool
notificationShadow notificationShadow
// attentionPilotFn is github.notifications.attention_pilot, read live:
// when it returns true routine issue notes fold into the issue's
// hive:status card (issue_status_card.go). nil reads as off.
attentionPilotFn func() bool
// reviewRequireLabelsFn returns review.require_labels, read live so a
// Features-tab edit gates the next relay request without a rebuild. nil
// or empty means the gate is off.
Expand Down
19 changes: 16 additions & 3 deletions src/pkg/github/close_on_merge.go
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ import (
gh "github.com/google/go-github/v72/github"
"github.com/hivecommons/hive/pkg/claims"
"github.com/hivecommons/hive/pkg/config"
"github.com/hivecommons/hive/pkg/prstatus"
"github.com/hivecommons/hive/pkg/stagelabels"
)

Expand Down Expand Up @@ -624,7 +625,11 @@ func (c *Client) closeIssueForMergedPRClaimWithIssue(ctx context.Context, issueR
}
if closeOnMergeReopenedAfter(events, opts.Identity) {
res.Action, res.Reason = CloseOnMergeSkipped, "reopened_after_merge"
if _, _, err := c.client.Issues.CreateComment(WithRESTCaller(ctx, "hive:close_on_merge"), owner, repoName, issueNumber, &gh.IssueComment{Body: gh.Ptr(closeOnMergeReopenedComment(pr))}); err != nil && opts.Logger != nil {
body := closeOnMergeReopenedComment(pr)
if _, err := c.PostIssueNote(WithRESTCaller(ctx, "hive:close_on_merge"), issueRepo, issueNumber, prstatus.KeyIssueReopened, body, func(ctx context.Context) error {
_, _, err := c.client.Issues.CreateComment(ctx, owner, repoName, issueNumber, &gh.IssueComment{Body: gh.Ptr(body)})
return err
}); err != nil && opts.Logger != nil {
opts.Logger.Warn("close-on-merge: posting reopened-after-merge marker failed", "repo", issueRepo, "issue", issueNumber, "pr", pr.GetNumber(), "error", err)
}
return res
Expand All @@ -636,7 +641,12 @@ func (c *Client) closeIssueForMergedPRClaimWithIssue(ctx context.Context, issueR
return res
}
body := closeOnMergeAwaitingComment(pr)
if _, _, err := c.client.Issues.CreateComment(WithRESTCaller(ctx, "hive:close_on_merge"), owner, repoName, issueNumber, &gh.IssueComment{Body: gh.Ptr(body)}); err != nil {
// Confirming the fix is an action asked of a person, so under the
// attention pilot it is announced once rather than only edited in.
if _, err := c.PostIssueAttention(WithRESTCaller(ctx, "hive:close_on_merge"), issueRepo, issueNumber, fmt.Sprintf("close-on-merge-awaiting-%d", pr.GetNumber()), body, func(ctx context.Context) error {
_, _, err := c.client.Issues.CreateComment(ctx, owner, repoName, issueNumber, &gh.IssueComment{Body: gh.Ptr(body)})
return err
}); err != nil {
res.Action, res.Reason = CloseOnMergeNoop, "awaiting_comment_failed"
return res
}
Expand All @@ -658,7 +668,10 @@ func (c *Client) closeIssueForMergedPRClaimWithIssue(ctx context.Context, issueR
// comment per issue is enough (hivecommons/hive#15727 vs #15843).
if stageNoted {
c.noteCommentSuppressed()
} else if _, _, err := c.client.Issues.CreateComment(WithRESTCaller(ctx, "hive:close_on_merge"), owner, repoName, issueNumber, &gh.IssueComment{Body: gh.Ptr(closeOnMergeCloseComment(pr))}); err != nil {
} else if _, err := c.PostIssueNote(WithRESTCaller(ctx, "hive:close_on_merge"), issueRepo, issueNumber, prstatus.KeyIssueClose, closeOnMergeCloseComment(pr), func(ctx context.Context) error {
_, _, err := c.client.Issues.CreateComment(ctx, owner, repoName, issueNumber, &gh.IssueComment{Body: gh.Ptr(closeOnMergeCloseComment(pr))})
return err
}); err != nil {
res.Action, res.Reason = CloseOnMergeNoop, "close_comment_failed"
return res
}
Expand Down
6 changes: 5 additions & 1 deletion src/pkg/github/decomposed_parents.go
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ import (
"strings"

gh "github.com/google/go-github/v72/github"
"github.com/hivecommons/hive/pkg/prstatus"
"github.com/hivecommons/hive/pkg/stagelabels"
)

Expand Down Expand Up @@ -296,7 +297,10 @@ func (c *Client) closeDecomposedParent(ctx context.Context, in IssueStageInput,
if store != nil {
store.Forget(key)
}
if err := c.CreateIssueCommentBudgeted(ctx, in.Repo, in.Number, decomposedParentCloseComment(children, closers)); err != nil && logger != nil {
note := decomposedParentCloseComment(children, closers)
if _, err := c.PostIssueNote(ctx, in.Repo, in.Number, prstatus.KeyIssueClose, note, func(ctx context.Context) error {
return c.CreateIssueCommentBudgeted(ctx, in.Repo, in.Number, note)
}); err != nil && logger != nil {
logger.Warn("issue stage labels: decomposed parent close comment failed", "repo", in.Repo, "issue", in.Number, "error", err)
}
if logger != nil {
Expand Down
4 changes: 3 additions & 1 deletion src/pkg/github/issue_blocked.go
Original file line number Diff line number Diff line change
Expand Up @@ -661,7 +661,9 @@ func (c *Client) postUnblockedNote(ctx context.Context, repo string, number int,
return
}
}
if c.notificationsQuiet() {
// The attention pilot folds dependency progress into the issue's
// status card whatever github.notifications.mode says.
if c.notificationsQuiet() || c.attentionPilot() {
if created, err := c.UpsertPRStatusSection(ctx, repo, number, prstatus.KeyUnblocked, note); err != nil {
logger.Warn("blocked sweep: unblock note not recorded on status comment", "repo", repo, "issue", number, "error", err)
} else if !created {
Expand Down
18 changes: 14 additions & 4 deletions src/pkg/github/issue_stage_labels.go
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,7 @@ import (
gh "github.com/google/go-github/v72/github"
"github.com/hivecommons/hive/pkg/authorkind"
"github.com/hivecommons/hive/pkg/config"
"github.com/hivecommons/hive/pkg/prstatus"
"github.com/hivecommons/hive/pkg/stageengine"
"github.com/hivecommons/hive/pkg/stagelabels"
)
Expand Down Expand Up @@ -604,7 +605,10 @@ func SyncIssueStageLabelsWith(ctx context.Context, client *Client, result *Actio
// note; a covering PR's own falls are narrated on the PR.
if tr.Regressed && !covered && tr.Prev.Before(stagelabels.CoveredByPR) {
if rec, ok := store.Get(key); ok && !rec.RegressionCommented {
if err := client.CreateIssueComment(ctx, in.Repo, in.Number, stagelabels.RegressionComment(tr.Prev, tr.Next, reason)); err != nil {
note := stagelabels.RegressionComment(tr.Prev, tr.Next, reason)
if _, err := client.PostIssueNote(ctx, in.Repo, in.Number, prstatus.KeyStageRegressed, note, func(ctx context.Context) error {
return client.CreateIssueComment(ctx, in.Repo, in.Number, note)
}); err != nil {
if logger != nil {
logger.Warn("issue stage labels: regression comment failed", "repo", in.Repo, "issue", in.Number, "error", err)
}
Expand Down Expand Up @@ -680,7 +684,9 @@ func handleMergedPRIssueStage(ctx context.Context, client *Client, in IssueStage
url = fmt.Sprintf("#%d", in.Claim.PRNumber)
}
body := fmt.Sprintf("%s\nPR #%d has merged: %s\n\nHive is moving this issue back to the actionable lane because the PR used a non-closing reference (`Refs` / `Part of`) and therefore landed partial work without closing the issue.", marker, in.Claim.PRNumber, url)
if err := client.CreateIssueComment(ctx, in.Repo, in.Number, body); err != nil {
if _, err := client.PostIssueNote(ctx, in.Repo, in.Number, prstatus.KeyIssuePartial(in.Claim.PRNumber), body, func(ctx context.Context) error {
return client.CreateIssueComment(ctx, in.Repo, in.Number, body)
}); err != nil {
if logger != nil {
logger.Warn("issue stage labels: merged partial PR comment failed", "repo", in.Repo, "issue", in.Number, "pr", in.Claim.PRNumber, "error", err)
}
Expand All @@ -706,7 +712,9 @@ func handleMergedPRIssueStage(ctx context.Context, client *Client, in IssueStage
if strings.TrimSpace(in.Claim.PRURL) != "" {
body = fmt.Sprintf("%s\nFixed by #%d (%s, merged). Closing because Hive's PR claim metadata says this PR was the full fix.", marker, in.Claim.PRNumber, in.Claim.PRURL)
}
if err := client.CreateIssueComment(ctx, in.Repo, in.Number, body); err != nil {
if _, err := client.PostIssueNote(ctx, in.Repo, in.Number, prstatus.KeyIssueClose, body, func(ctx context.Context) error {
return client.CreateIssueComment(ctx, in.Repo, in.Number, body)
}); err != nil {
if logger != nil {
logger.Warn("issue stage labels: merged full-fix PR close comment failed", "repo", in.Repo, "issue", in.Number, "pr", in.Claim.PRNumber, "error", err)
}
Expand Down Expand Up @@ -766,7 +774,9 @@ func ensureIssueStagePRLink(ctx context.Context, client *Client, in IssueStageIn
if !ok || rec.EntryCommented {
return false, false, false
}
if err := client.CreateIssueComment(ctx, in.Repo, in.Number, link.StageComment); err != nil {
if _, err := client.PostIssueNote(ctx, in.Repo, in.Number, prstatus.KeyIssuePRLink, link.StageComment, func(ctx context.Context) error {
return client.CreateIssueComment(ctx, in.Repo, in.Number, link.StageComment)
}); err != nil {
owner, name := client.splitRepo(in.Repo)
if client.noteArchivedWrite(strings.ToLower(owner+"/"+name), err) {
if logger != nil {
Expand Down
Loading
Loading