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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/fixed-16579.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Stage controller: an issue a maintainer already decided (`approved-direction`) whose remaining work is human-only (`needs-human`) is no longer re-parked on `stage/045-needs-decision` with the ack stripped; it keeps `approved-direction` and is held out of the pipeline, ending the decide β†’ re-park bounce loop; a newer, different `/hive decision` still lets an agent's park through and clears the stale ack ([#16579](https://github.com/hivecommons/hive/issues/16579)).
2 changes: 1 addition & 1 deletion src/docs/maintainer-commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ https://github.com/hivecommons/hive/blob/v5/src/docs/maintainer-commands.md
| Command | What it does | Who may use it | Where it works | Pickup speed | Labels changed |
| --- | --- | --- | --- | --- | --- |
| `/hive approve` | Accepts the recommendation already written on a parked issue. | Human commenter with `write`, `maintain`, or `admin` repository permission. | Open issues carrying `needs-human` or `stage/045-needs-decision` (or the retired `needs-decision` / `needs-direction` / a pre-045 `stage/085-needs-decision`, until migrated). On an open pull request the command gets one acknowledgement or explanation reply and changes no labels (see [PR approval command feedback](#pr-approval-command-feedback)). | Next un-park sweep, normally within 5 minutes. | Removes `stage/045-needs-decision` (and the retired spellings) when present; adds `approved-direction`; removes `needs-human` **whoever added it** β€” your approval is the human input the label asked for ([#13075](https://github.com/hivecommons/hive/issues/13075), [docs#419](https://github.com/hivecommons/docs/issues/419)); the reply names who had added it. Never removes `hold`: add `hold` to keep agents off an issue through a decision. |
| `/hive decision <text>` | Gives explicit direction for a parked issue. | Human commenter with `write`, `maintain`, or `admin` repository permission. | Open issues carrying `needs-human` or `stage/045-needs-decision` (or the retired `needs-decision` / `needs-direction` / a pre-045 `stage/085-needs-decision`, until migrated); pull requests are ignored. | Next un-park sweep, normally within 5 minutes. | Removes `stage/045-needs-decision` (and the retired spellings) when present; adds `approved-direction`; removes `needs-human` **whoever added it** β€” your decision is the human input the label asked for, and left in place it would re-derive 045 two minutes later ([#13075](https://github.com/hivecommons/hive/issues/13075), [docs#419](https://github.com/hivecommons/docs/issues/419)); the reply names who had added it. Never removes `hold`: add `hold` to keep agents off an issue through a decision. An agent's later re-park on 085 is refused while `approved-direction` is present and the recorded decision text is unchanged. |
| `/hive decision <text>` | Gives explicit direction for a parked issue. | Human commenter with `write`, `maintain`, or `admin` repository permission. | Open issues carrying `needs-human` or `stage/045-needs-decision` (or the retired `needs-decision` / `needs-direction` / a pre-045 `stage/085-needs-decision`, until migrated); pull requests are ignored. | Next un-park sweep, normally within 5 minutes. | Removes `stage/045-needs-decision` (and the retired spellings) when present; adds `approved-direction`; removes `needs-human` **whoever added it** β€” your decision is the human input the label asked for, and left in place it would re-derive 045 two minutes later ([#13075](https://github.com/hivecommons/hive/issues/13075), [docs#419](https://github.com/hivecommons/docs/issues/419)); the reply names who had added it. Never removes `hold`: add `hold` to keep agents off an issue through a decision. An agent's later re-park on 085 is refused while `approved-direction` is present and the recorded decision text is unchanged; an agent's later `needs-human` (the remaining work is human-only) keeps `approved-direction` and holds the issue out of the pipeline instead of re-deriving `stage/045-needs-decision` ([#16579](https://github.com/hivecommons/hive/issues/16579)). A newer `/hive decision` with different text means direction is changing: an agent's park goes through, the stale `approved-direction` is cleared, and the issue waits at `stage/045-needs-decision` until the sweep applies the new decision. |
| `/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. |
Expand Down
23 changes: 15 additions & 8 deletions src/pkg/github/issue_request_label.go
Original file line number Diff line number Diff line change
Expand Up @@ -208,34 +208,41 @@ func (c *Client) reservedLabelRefusal(add, remove []string) (string, bool) {
// the agent what to do instead: follow the decision, or β€” when it reserves
// the work for people β€” add `needs-human` and unclaim. A lookup failure is
// returned so the caller retries rather than reading "unknown" as allowed.
func (c *Client) reparkDecisionRefusal(ctx context.Context, repo string, number int, add []string) (string, bool, error) {
//
// superseded is true when the park is allowed through on that newer,
// different decision: the issue still wears `approved-direction` for the
// old one, and the stage engine must read the ack as stale
// (FactSink.ReparkedOnNewDecision) rather than as a standing decision the
// agent is standing down on (hivecommons/hive#16579), or the park never
// lands.
func (c *Client) reparkDecisionRefusal(ctx context.Context, repo string, number int, add []string) (reason string, refused, superseded bool, err error) {
if number <= 0 || !containsDecisionParkLabel(add, c.needsDecisionLabel()) {
return "", false, nil
return "", false, false, nil
}
owner, name := c.splitRepo(repo)
issue, _, err := c.client.Issues.Get(ctx, owner, name, number)
if err != nil {
return "", false, fmt.Errorf("checking issue park labels: %w", err)
return "", false, false, fmt.Errorf("checking issue park labels: %w", err)
}
labels := extractLabels(issue.Labels)
if !labelPresent(labels, HumanAckLabel) {
return "", false, nil
return "", false, false, nil
}
comments, err := c.listIssueComments(ctx, owner, name, number)
if err != nil {
return "", false, err
return "", false, false, err
}
decision, at, ok := c.lastRecordedUnparkDecision(comments)
if !ok {
return "", false, nil
return "", false, false, nil
}
if hasNewerDifferentDecisionCommand(comments, at, decision) {
return "", false, nil
return "", false, true, nil
}
return fmt.Sprintf("a maintainer already decided on %s#%d (recorded by Hive: %q) and `%s` is applied; "+
"re-parking it on `%s` asks for a decision that has been given. Follow the decision. "+
"If it reserves the work for people, add `%s` through this relay and `/unclaim` instead.",
repo, number, decision, HumanAckLabel, c.needsDecisionLabel(), issueNeedsHumanLabel), true, nil
repo, number, decision, HumanAckLabel, c.needsDecisionLabel(), issueNeedsHumanLabel), true, false, nil
}

func containsDecisionParkLabel(labels []string, configured string) bool {
Expand Down
16 changes: 12 additions & 4 deletions src/pkg/github/issue_request_label_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -420,7 +420,9 @@ func TestNormalizeLabelList(t *testing.T) {
// With `approved-direction` applied and Hive's own un-park reply recording
// the decision, the re-park is refused and the agent is told to add
// `needs-human` and unclaim instead. A newer `/hive decision` with different
// text means direction is changing, and the park goes through.
// text means direction is changing, and the park goes through β€” as a
// ReparkedOnNewDecision fact, so the stale ack does not read as a standing
// decision that would hold the issue out of 045 (hivecommons/hive#16579).
func TestIssueRequestWatcher_LabelRefusesReparkOnRecordedDecision(t *testing.T) {
const decision = "Agents stand down; owner/Console owners handle this"
reply := unparkWireComment{
Expand Down Expand Up @@ -456,9 +458,15 @@ func TestIssueRequestWatcher_LabelRefusesReparkOnRecordedDecision(t *testing.T)

resp := readIssueResultFile(t, reqPath)
if tc.wantAdded {
if !resp.OK || len(rec.added[12680]) != 1 {
if !resp.OK || len(rec.added[12680]) != 1 || rec.added[12680][0] != NeedsDecisionStageLabel {
t.Fatalf("expected the park to go through, resp=%+v added=%v", resp, rec.added[12680])
}
// Direction is changing, so the old `approved-direction`
// is stale: the park re-derives 045 with it cleared rather
// than standing down on the old decision (#16579).
if got := strings.Join(rec.removed[12680], ","); !strings.Contains(got, HumanAckLabel) {
t.Fatalf("expected the stale %s cleared with the re-park, removed=%v", HumanAckLabel, rec.removed[12680])
}
return
}
if resp.OK || len(rec.added[12680]) != 0 {
Expand Down Expand Up @@ -489,11 +497,11 @@ func TestReparkDecisionRefusalRecognizesRetiredDecisionLabels(t *testing.T) {
server, _ := newUnparkServer(t, "org", "repo", []unparkWireIssue{issue}, nil)
c := newTestClient(t, server, "org", []string{"repo"})

reason, refused, err := c.reparkDecisionRefusal(context.Background(), "org/repo", 12680, []string{label})
reason, refused, superseded, err := c.reparkDecisionRefusal(context.Background(), "org/repo", 12680, []string{label})
if err != nil {
t.Fatalf("reparkDecisionRefusal: %v", err)
}
if !refused || !strings.Contains(reason, "already decided") || !strings.Contains(reason, issueNeedsHumanLabel) {
if !refused || superseded || !strings.Contains(reason, "already decided") || !strings.Contains(reason, issueNeedsHumanLabel) {
t.Fatalf("label %q refused=%v reason=%q, want recorded-decision refusal", label, refused, reason)
}
})
Expand Down
14 changes: 10 additions & 4 deletions src/pkg/github/issue_request_watcher.go
Original file line number Diff line number Diff line change
Expand Up @@ -698,10 +698,12 @@ func (c *Client) handleOneIssueRequest(ctx context.Context, path string, nowFn f
}
case "label":
// A re-park on a decision a maintainer already gave is refused; a
// failed lookup takes the retry path like the claim gate.
// failed lookup takes the retry path like the claim gate. One let
// through on a newer, different decision is submitted as such so
// the stale `approved-direction` does not read as a standing one.
var reason string
var refused bool
reason, refused, err = c.reparkDecisionRefusal(ctx, req.Repo, req.Number, addLabels)
var refused, superseded bool
reason, refused, superseded, err = c.reparkDecisionRefusal(ctx, req.Repo, req.Number, addLabels)
if err != nil {
break
}
Expand All @@ -726,7 +728,11 @@ func (c *Client) handleOneIssueRequest(ctx context.Context, path string, nowFn f
err = c.StageFacts().Unparked(ctx, c.IssueStageRef(req.Repo, req.Number), req.Agent)
}
if err == nil && parkLabel != "" {
err = c.StageFacts().Parked(ctx, c.IssueStageRef(req.Repo, req.Number), parkLabel)
if superseded {
err = c.StageFacts().ReparkedOnNewDecision(ctx, c.IssueStageRef(req.Repo, req.Number), parkLabel)
} else {
err = c.StageFacts().Parked(ctx, c.IssueStageRef(req.Repo, req.Number), parkLabel)
}
if err == nil {
err = c.verifyIssueParkLanded(ctx, req.Repo, req.Number, parkLabel)
}
Expand Down
36 changes: 29 additions & 7 deletions src/pkg/stageengine/derive_issue.go
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,10 @@ const (
// reasonIssueOpenPRPartial is 040 under a PR that references the issue
// without closing it (ClaimFact.Partial); ReasonIsPartialCover reads it.
reasonIssueOpenPRPartial = "open PR addresses part of it (references it without a closing keyword)"
// reasonIssueDecidedHumanWork prefixes the reason of an issue whose
// direction a person already gave and whose remainder is held for a
// person (hivecommons/hive#16579).
reasonIssueDecidedHumanWork = "decided; remaining work held for a person: "
)

// ReasonIsPartialCover reports whether a 040 reason describes a PR that
Expand Down Expand Up @@ -94,13 +98,14 @@ func deriveIssue(f Facts) Decision {
}
}

// issueParkClear reconciles `needs-human` against `approved-direction`,
// which cannot both stand (hivecommons/hive#15099). The un-park that
// applies the ack removes `needs-human` in the same write, so a
// `needs-human` found next to the ack was applied after it β€” the later
// signal (DecisionLiftsNeedsHuman's own rule), whether an agent parked the
// issue on a blocker or a person asked again. The ack is the stale one:
// the issue stays 045 and the writer clears `approved-direction`.
// issueParkClear reconciles `needs-human` against `approved-direction` on
// an issue parked at 045 (hivecommons/hive#15099). That happens for a
// structured blocker β€” no decision grants the App a permission β€” and for a
// park let through because a newer, different `/hive decision` is pending
// (Park.DecisionSuperseded): either way the ack is the stale one and the
// writer clears it. A plain `needs-human` next to a standing ack derives
// out of the pipeline instead and keeps it (hivecommons/hive#16579), so
// nothing is cleared for it.
func issueParkClear(f Facts, stage stagelabels.Stage) []string {
is := f.Issue
label := strings.TrimSpace(is.ApprovedDirectionLabel)
Expand Down Expand Up @@ -161,6 +166,23 @@ func issueStage(f Facts) (stage stagelabels.Stage, covered bool, reason string)
}
return stagelabels.IssueNeedsDecision, false, "blocked: " + short
}
// A decision is already recorded (`approved-direction`): a
// `needs-human` next to it is the agent standing down on work only
// a person can do (a cluster rollout, a backup, an out-of-repo
// step) β€” what the re-park refusal tells agents to do β€” not a new
// question. Re-deriving 045 stripped the ack and re-opened the
// decision inbox on every scanner pass, and the un-park sweep
// re-applied the same old decision: a bounce loop
// (hivecommons/hive#16579, seen on hivecommons/dibs#567). The
// issue is held out of the pipeline like a hold and keeps the ack;
// a person who wants to decide again removes `approved-direction`
// β€” or posts a new `/hive decision`: the label relay lets an
// agent's park through on that newer, different decision
// (Park.DecisionSuperseded), the ack is stale again, and the issue
// re-parks at 045 with it cleared until the un-park sweep answers.
if strings.TrimSpace(is.ApprovedDirectionLabel) != "" && !f.Park.DecisionSuperseded {
return stagelabels.None, false, reasonIssueDecidedHumanWork + is.NeedsHumanLabel
}
return stagelabels.IssueNeedsDecision, false, "held for a person: " + is.NeedsHumanLabel
}
// The prior-art gate's park is its own stage, 017, not 045: nothing is
Expand Down
69 changes: 65 additions & 4 deletions src/pkg/stageengine/derive_issue_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -134,9 +134,10 @@ func TestDeriveIssueFlags(t *testing.T) {
}

// hivecommons/hive#15099: `needs-human` with a structured blocker stays
// 045 and names the blocker. `approved-direction` next to `needs-human`
// is the stale label either way (the un-park that applies the ack removes
// the park label, so a surviving park label came later) and is cleared.
// 045 and names the blocker, and `approved-direction` next to it is the
// stale label and is cleared. A plain `needs-human` next to the ack is the
// agent standing down on human-only work after a decision and stays out of
// 045 with the ack kept (hivecommons/hive#16579).
func TestDeriveIssueBlockerAndApprovedDirection(t *testing.T) {
blocked := func(f *Facts) {
f.Issue.Bucket = BucketFiltered
Expand All @@ -160,8 +161,20 @@ func TestDeriveIssueBlockerAndApprovedDirection(t *testing.T) {
f.Park.NeedsHuman = true
f.Issue.ApprovedDirectionLabel = "approved-direction"
}))
if d.Stage != stagelabels.None || d.Reason != "decided; remaining work held for a person: needs-human" || len(d.Clear) != 0 {
t.Fatalf("a plain needs-human after a decision keeps the ack out of 045 (#16579): %+v", d)
}
// A newer, different `/hive decision` is pending (the label relay let
// an agent's park through on it): the ack is stale again, the issue
// re-parks at 045 and the writer clears it.
d = DeriveIssue(derivedIssueFacts(func(f *Facts) {
f.Issue.Bucket = BucketFiltered
f.Park.NeedsHuman = true
f.Park.DecisionSuperseded = true
f.Issue.ApprovedDirectionLabel = "approved-direction"
}))
if d.Stage != stagelabels.IssueNeedsDecision || d.Reason != "held for a person: needs-human" || len(d.Clear) != 1 || d.Clear[0] != "approved-direction" {
t.Fatalf("a later needs-human outranks the ack: %+v", d)
t.Fatalf("a park on a newer decision outranks the stale ack: %+v", d)
}
d = DeriveIssue(derivedIssueFacts(func(f *Facts) { blocked(f); f.Issue.BlockerShort = "" }))
if d.Reason != "blocked: capability:workflows-permission" {
Expand All @@ -177,3 +190,51 @@ func TestDeriveIssueBlockerAndApprovedDirection(t *testing.T) {
t.Fatalf("held: %+v", d)
}
}

// hivecommons/hive#16579 (seen on hivecommons/dibs#567): parked β†’
// `/hive decision` β†’ `approved-direction` + 010 β†’ a later scanner pass
// finds the remaining checklist human-only and adds `needs-human`. That
// evaluation must neither re-derive 045 nor strip the ack β€” doing so put
// the decision back in the inbox and the un-park sweep re-applied the same
// decision, bouncing the issue every pass.
func TestDeriveIssueDecisionSticksOverHumanOnlyRemainder(t *testing.T) {
steps := []struct {
name string
mutate func(f *Facts)
wantStage stagelabels.Stage
}{
{"agent parks", func(f *Facts) {
f.Issue.Bucket = BucketFiltered
f.Park.NeedsHuman = true
}, stagelabels.IssueNeedsDecision},
{"maintainer decides", func(f *Facts) {
f.Park.ApprovedDirection = true
f.Issue.ApprovedDirectionLabel = "approved-direction"
}, stagelabels.Actionable},
{"remainder is human-only", func(f *Facts) {
f.Issue.Bucket = BucketFiltered
f.Park.NeedsHuman = true
f.Issue.ApprovedDirectionLabel = "approved-direction"
}, stagelabels.None},
{"next pass re-evaluates", func(f *Facts) {
f.Issue.Bucket = BucketFiltered
f.Park.NeedsHuman = true
f.Issue.ApprovedDirectionLabel = "approved-direction"
f.Issue.Stalled = true
}, stagelabels.None},
}
for _, tc := range steps {
d := DeriveIssue(derivedIssueFacts(tc.mutate))
if d.Stage != tc.wantStage {
t.Fatalf("%s: stage = %v, want %v (%+v)", tc.name, d.Stage, tc.wantStage, d)
}
for _, c := range d.Clear {
if c == "approved-direction" {
t.Fatalf("%s: stripped approved-direction: %+v", tc.name, d)
}
}
if d.Terminal {
t.Fatalf("%s: an open decided issue is not terminal: %+v", tc.name, d)
}
}
}
Loading
Loading