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-ack-snooze-commands.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- **`/hive ack` and `/hive snooze <duration>` for attention episodes, plus the attention action contract** ([#16359](https://github.com/hivecommons/hive/issues/16359), part of [#16270](https://github.com/hivecommons/hive/issues/16270)). On a repository whose `github.attention.admitter` is this hive, the episode's responsible person or a maintainer (`write`/`maintain`/`admin`) can acknowledge an attention episode or pause its reminders (1m–30d) from a comment; the un-park sweep records who and when on the episode (`acked_by`, `snoozed_by`, `snoozed_until`), refreshes the attention status section and replies once. Anyone else is ignored and nothing is recorded. Acknowledgement is not approval: neither command changes a label, releases a security/merge/review hold or opens a merge gate. `attention.Event` / `attention.NewObservation` define the contract every attention event must satisfy — who, what changed and why now, requested action, evidence, what Hive tried, what happens next, and how to ack, snooze or resolve — and refuse incomplete events. See `src/docs/maintainer-commands.md` and `src/docs/notifications.md`.
28 changes: 28 additions & 0 deletions src/docs/maintainer-commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,8 @@ https://github.com/hivecommons/hive/blob/v5/src/docs/maintainer-commands.md
| `/hive decision proceed — <gap>` | Confirms a feature request parked by the prior-art gate is a real gap. | The issue author, or a human commenter with `write`, `maintain`, or `admin`. | Open issues carrying `stage/017-possible-existing` below a `<!-- hive:prior-art-gate -->` comment. | Next un-park sweep. | Removes `stage/017-possible-existing`, appends a **Scope vs existing** section with `<gap>` to the issue body, records the un-park so the issue re-derives `stage/010-actionable` ([#13575](https://github.com/hivecommons/hive/issues/13575)). |
| `/hive decision exists` | Agrees the request already exists. | Same as above. | Same as above. | Next un-park sweep. | Adds `already-exists`, closes the issue `not_planned`, replies with a pointer at the quoted findings. Reopen the issue to continue; the gate does not ask again. |
| `/hive help` | Posts this command list. On parked issues it also repeats the issue-specific approve/decision options. | Any human commenter with at least `triage` repository permission for the on-demand workflow; the sweep path on parked issues requires `write`, `maintain`, or `admin`. | Any open issue or pull request. | GitHub Actions on the new comment; if Actions is unavailable on a parked issue, the next un-park sweep can also answer. | None. |
| `/hive ack [episode]` | Acknowledges an attention episode on the item: you have seen it, so reminders for it stop. **Acknowledgement is not approval.** See [Attention ack and snooze](#attention-ack-and-snooze). | The episode's named responsible person, or a human with `write`, `maintain`, or `admin` repository permission. Anyone else is ignored in silence. | Open issues and pull requests with an unresolved attention episode, on a repository whose `github.attention.admitter` is this hive. | Next un-park sweep, normally within 5 minutes. | None. Never releases a security, merge or review hold and never opens a merge gate. |
| `/hive snooze <duration> [episode]` | Pauses reminders for an attention episode until the duration elapses (`90m`, `4h`, `2d`, `1w`; 1m to 30d). | Same as `/hive ack`. | Same as `/hive ack`. | Next un-park sweep, normally within 5 minutes. | None. A snooze releases no hold. |
| `/fixed` | Confirms that an open issue's fix is verified — or that what a parked issue waited on was done, in or outside the repository — and closes it as completed. Alias: `/close`. Plain-language confirmations such as "yes, this has been fixed" are accepted only when Hive is already waiting for reporter confirmation. | The issue reporter, or a human with `write`, `maintain`, or `admin` repository permission. On a parked issue (`stage/045-needs-decision`, `needs-human`, or a retired park spelling) the un-park sweep honours it from a human with `write`, `maintain`, or `admin` permission. | Open issues only, not pull requests. | GitHub Actions on the new comment where the repository runs the `/fixed` workflow; on parked issues, the next un-park sweep, normally within 5 minutes ([dibs#459](https://github.com/hivecommons/dibs/issues/459)). | Closes the issue as completed. The workflow adds `hive: reporter-confirmed` and removes `hive/likely-done` and `needs-reporter-confirmation` when present. On a parked issue the sweep removes `needs-human` and the retired park spellings, the stage engine strips `stage/*`, and Hive posts one acknowledgement; `hold` is never touched. |
| `/reopen` | Reopens a closed issue that was closed too early. | The issue reporter, or a human with `write`, `maintain`, or `admin` repository permission. | Closed issues only, not pull requests. | GitHub Actions on the new comment. | Removes `needs-reporter-confirmation` when present. The reopen sticks: close-on-merge does not close the issue again for a PR that merged before the reopen, whether Hive (`<!-- hive-close-on-merge -->` comment) or GitHub's closing keyword closed it; Hive records the latter with a `<!-- hive-reopened-after-merge pr=<pr> -->` comment. A later PR can still close it. |
| `/help-wanted` | Adds the `help wanted` label. | Any non-bot commenter accepted by the label-helper workflow. | Issues and pull requests. | GitHub Actions on the new comment. | Adds `help wanted`. |
Expand Down Expand Up @@ -128,6 +130,32 @@ take outside the repository — the un-park sweep itself honours a maintainer's
`/fixed`, so a repository without the `/fixed` workflow still gets the close,
the label clean-up and one acknowledgement.

## Attention ack and snooze

Attention episodes ([#16270](https://github.com/hivecommons/hive/issues/16270))
ask one named person to act on one condition. `/hive ack` and
`/hive snooze <duration>` let that person, or a maintainer, answer the ask
without resolving it ([#16359](https://github.com/hivecommons/hive/issues/16359)):

- The command must be the first non-empty line of a recent, unedited comment
by a human, outside quotes and fences — the same rules as the un-park
commands. Only the hive named by `github.attention.admitter` for the
repository answers, so a fleet replies once.
- Without an `[episode]` argument the command applies to every unresolved
episode on the item that you may act on. To target one, pass the key prefix
shown in the item's attention status section, e.g. `/hive ack 3f9a0c12b7de`.
- `/hive ack` records who acknowledged and when; `/hive snooze` records who
snoozed and until when. Both are stored on the episode in the attention
ledger, refresh the status section, and get one reply.
- **Acknowledgement is not approval.** Neither command adds or removes a
label, releases a security, merge or review hold, or opens a merge gate. To
release a hold use the lever the hold names (for example a trusted merger's
GitHub **Approve** review); to resolve the episode, fix the condition — it
resolves when Hive no longer observes it.
- A caller who is neither the episode's responsible person nor a maintainer
is ignored in silence and nothing is recorded. A malformed duration from an
eligible caller gets a reply explaining the accepted forms.

## Prose replies on parked issues

Plain approvals such as "approved", "go ahead", "sounds good", or "ship it" do
Expand Down
23 changes: 23 additions & 0 deletions src/docs/notifications.md
Original file line number Diff line number Diff line change
Expand Up @@ -173,6 +173,29 @@ takes effect once the ledger routes its non-urgent writes through it.
every security/merge hold notice always deliver immediately and do not
consume budget. Unclassified writes are treated as exempt.

### Attention action contract

Every admitted attention event must let the recipient act without digging
([#16359](https://github.com/hivecommons/hive/issues/16359), part of
[#16270](https://github.com/hivecommons/hive/issues/16270)). Producers build
the event body with `attention.NewObservation`, which refuses an incomplete
`attention.Event`; `Event.Render` emits, in order:

| Field | Meaning |
|---|---|
| **Who** | The person or team asked to act. |
| **What changed / why now** | The change that made the condition need attention now. |
| **Requested action** | The single concrete thing asked of the recipient. |
| **Evidence** | What the condition was observed from (run, finding, SHA). |
| **What Hive tried** | What Hive already attempted on its own. |
| **What happens next** | What Hive will do if nobody acts. |
| **How to ack, snooze or resolve** | `/hive ack`, `/hive snooze <duration>`, and what clears the condition. |

Every event ends with the same wording: *Acknowledgement is not approval:
`/hive ack` and `/hive snooze` only quiet reminders. They release no security,
merge or review hold, change no label and open no merge gate.* See
[maintainer commands](maintainer-commands.md#attention-ack-and-snooze).

## What triggers notifications

The Hive Go process sends notifications for these events:
Expand Down
175 changes: 175 additions & 0 deletions src/pkg/attention/ack.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,175 @@
package attention

import (
"errors"
"fmt"
"strconv"
"strings"
"time"
)

// MaxSnooze bounds `/hive snooze`: a snooze quiets reminders, it must not
// become an indefinite mute of a condition that still needs a person.
const MaxSnooze = 30 * 24 * time.Hour

// CommandKind is an attention sub-command of `/hive`.
type CommandKind string

const (
CommandAck CommandKind = "ack"
CommandSnooze CommandKind = "snooze"
)

var (
// ErrNoEpisode means the item has no unresolved episode the command names.
ErrNoEpisode = errors.New("attention: no unresolved attention episode matches")
// ErrNotPermitted means the caller is neither the episode's named
// recipient nor a maintainer; nothing was recorded.
ErrNotPermitted = errors.New("attention: only the responsible person or a maintainer may ack or snooze")
)

// Command is a parsed `/hive ack [episode]` or `/hive snooze <duration>
// [episode]`. Target is an optional episode key-hash prefix as shown in the
// status card; empty means every unresolved episode on the item.
type Command struct {
Kind CommandKind
Snooze time.Duration
Target string
}

// ParseCommand reads an attention command off the comment's first non-empty
// line, never inside a quote or a fence. ok reports whether the comment is an
// attention command at all; err reports a malformed one (for example a
// missing or out-of-range snooze duration) so the caller can explain it.
func ParseCommand(body string) (cmd Command, ok bool, err error) {
line := ""
for _, l := range strings.Split(body, "\n") {
if l = strings.TrimSpace(l); l != "" {
line = l
break
}
}
if line == "" || strings.HasPrefix(line, ">") || strings.HasPrefix(line, "```") || strings.HasPrefix(line, "~~~") {
return Command{}, false, nil
}
f := strings.Fields(line)
if len(f) < 2 || !strings.EqualFold(f[0], "/hive") {
return Command{}, false, nil
}
switch CommandKind(strings.ToLower(f[1])) {
case CommandAck:
cmd = Command{Kind: CommandAck}
if len(f) > 2 {
cmd.Target = f[2]
}
case CommandSnooze:
cmd = Command{Kind: CommandSnooze}
if len(f) < 3 {
return cmd, true, errors.New("snooze needs a duration, for example `/hive snooze 2d`")
}
d, perr := ParseSnooze(f[2])
if perr != nil {
return cmd, true, perr
}
cmd.Snooze = d
if len(f) > 3 {
cmd.Target = f[3]
}
default:
return Command{}, false, nil
}
cmd.Target = strings.ToLower(strings.Trim(cmd.Target, "`"))
if cmd.Target != "" && strings.Trim(cmd.Target, "0123456789abcdef") != "" {
return cmd, true, fmt.Errorf("episode %q is not a key from the attention status card", cmd.Target)
}
return cmd, true, nil
}

// ParseSnooze accepts Go durations ("90m", "4h") plus whole days ("2d") and
// weeks ("1w"), bounded by MaxSnooze.
func ParseSnooze(s string) (time.Duration, error) {
s = strings.ToLower(strings.TrimSpace(s))
var d time.Duration
var err error
if n := len(s); n > 1 && (s[n-1] == 'd' || s[n-1] == 'w') {
var v int
v, err = strconv.Atoi(s[:n-1])
unit := 24 * time.Hour
if s[n-1] == 'w' {
unit *= 7
}
if err == nil && v > 0 && v <= int(MaxSnooze/unit) {
d = time.Duration(v) * unit
}
} else {
d, err = time.ParseDuration(s)
}
if err != nil || d < time.Minute || d > MaxSnooze {
return 0, fmt.Errorf("snooze duration %q must be between 1m and 30d, for example `4h` or `2d`", s)
}
return d, nil
}

// MayAct reports whether actor may ack or snooze e: the episode's named
// recipient (case-insensitive, optional `@`) or a maintainer.
func MayAct(e Episode, actor string, maintainer bool) bool {
if maintainer {
return true
}
a := canonical(strings.TrimPrefix(strings.TrimSpace(actor), "@"))
return a != "" && a == canonical(strings.TrimPrefix(strings.TrimSpace(e.Key.Recipient), "@"))
}

// Apply records an ack or snooze from actor on every unresolved episode of
// repo#item that cmd targets and actor may act on. It changes only the
// reminder state on the episode (AckedAt/AckedBy, SnoozedUntil/SnoozedBy).
// It never touches a hold label, a merge gate or a review verdict:
// acknowledgement is not approval, and a snooze releases no hold.
func (s *Store) Apply(repo string, item int, actor string, maintainer bool, cmd Command) ([]Episode, error) {
if cmd.Kind != CommandAck && cmd.Kind != CommandSnooze {
return nil, errors.New("attention: unsupported command")
}
if cmd.Kind == CommandSnooze && (cmd.Snooze <= 0 || cmd.Snooze > MaxSnooze) {
return nil, errors.New("attention: snooze duration out of range")
}
actor = strings.TrimPrefix(strings.TrimSpace(actor), "@")
s.mu.Lock()
defer s.mu.Unlock()
var matched, permitted []*Episode
for hash, e := range s.state.Episodes {
if e.State == Resolved || e.Key == (Key{}) || canonical(e.Key.Repo) != canonical(repo) || e.Key.Item != item || !strings.HasPrefix(hash, cmd.Target) {
continue
}
matched = append(matched, e)
if MayAct(*e, actor, maintainer) {
permitted = append(permitted, e)
}
}
if len(matched) == 0 {
return nil, ErrNoEpisode
}
if len(permitted) == 0 {
return nil, ErrNotPermitted
}
now := s.now().UTC()
out := make([]Episode, 0, len(permitted))
for _, e := range permitted {
switch cmd.Kind {
case CommandAck:
e.State = Acknowledged
if e.AckedAt.IsZero() {
e.AckedAt = now
}
e.AckedBy = actor
case CommandSnooze:
e.SnoozedUntil = now.Add(cmd.Snooze)
e.SnoozedBy = actor
}
e.WouldNotify = false
out = append(out, *e)
}
if err := s.save(); err != nil {
return nil, err
}
return out, nil
}
Loading
Loading