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-19299-verified-close.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- A partially-addressed issue the scanner verified complete is now closed by the hive instead of sitting at `stage/010-actionable` until a person closes it (#17157 and #19177 both carried a scanner note saying "this can be closed"; #19299). The verify-once kick asks the scanner to end its note with `<!-- hive:verification verdict=complete prs=N -->` (or `verdict=partial`), and the issue stage sweep reads that marker from the hive's own comments. When two reads 15 minutes apart agree, every cited PR is merged and no linked PR is still open, it closes the issue as completed with an evidence comment citing the merged PRs. When a guard is not met it parks the issue at 045 with the new `hive/verify-close` label, shown on the activity monitor with a one-click **Close as completed**. `verdict=partial` labels `hive/verified-open`. Held, `hive/tracking`, umbrella or tracker issues, parents with an open child, issues a person reopened and issues a person took out of the lane are never touched. Scanner claims are still released on an agent relaunch (a fresh CLI never resumes the old session); the marker now carries the verdict across it.
18 changes: 17 additions & 1 deletion src/docs/labels-and-control-signals/reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -623,7 +623,7 @@ A merged PR covered only part of the issue ([#11931](https://github.com/hivecomm

**Checked by:** Close-on-merge sweep, PR-claim label sync and task-list sweep. **When:** Close-on-merge sweep for issues behind a confirmation gate.

**Release or override.** Hive removes it when a later merged PR fully covers the issue and `hive/likely-done` is applied; humans may remove it
**Release or override.** Hive removes it when a later merged PR fully covers the issue and `hive/likely-done` is applied; the hive closes the issue when the scanner's verification marker says complete and the guards hold, or parks it in `hive/verify-close`; humans may remove it

**Configuration and implementation.** Fixed label (`src/pkg/github/close_on_merge.go`, `src/pkg/github/task_list_sweep.go`)

Expand All @@ -641,6 +641,22 @@ A `hive/likely-done` / already-done claim from a merged PR was checked and the i

**Configuration and implementation.** Fixed label (`src/pkg/github/prclaims.go` `VerifiedOpenLabel`, `src/cmd/hive/verifyonce.go`)

#### `hive/verify-close`

**Applies to:** Issues. **Kind:** Hard suppress (the 045 park); dashboard one-click Close.

The verify-close lane. The scanner's verify-once note ends with a machine-readable verdict, `<!-- hive:verification verdict=complete prs=19172,19179 -->` (nothing left; `prs` names the merged PRs that delivered it) or `<!-- hive:verification verdict=partial prs=19172 -->` (work remains). For an open issue labelled `hive/partially-addressed`, the issue stage sweep reads the marker from the hive's own comments only (an agent note is relayed under the hive identity; a marker anyone else writes is ignored) and, once two reads `verifyCloseSettleInterval` (15 minutes, the tracker auto-close's settle interval) apart see the same evidence: closes the issue as *completed* with an evidence comment citing the merged PRs when every cited PR (the marker's plus the merged claim's) is merged and no PR linked from the timeline is still open; otherwise applies this label with one status note naming the unmet guard (a cited PR not merged, an open linked PR, notes that disagree, no cited PR, more than 20 PRs, or a human-filed bug whose reporter confirms the close). `verdict=partial` adds `hive/verified-open` instead. Never touched: a held or `hive/tracking` issue, an umbrella or tracker (the tracker auto-close owns those), a decomposed parent with an open child, an issue a person reopened, and an issue a person took out of the lane by removing this label. While the label is on, the issue derives `stage/045-needs-decision`, no agent is offered it, and the activity monitor row asks *The scanner verified this issue complete* and leads with **Close as completed** (one click, `decide:close-issue`).

**Who applies it:** Hive.

**Checked by:** Issue stage sweep (`closeVerifiedComplete`). **When:** Every stage sweep, at most one read of a candidate per settle interval.

**Release or override.** A person closes the issue from the row, or removes the label when work remains (the hive does not re-apply it after that); the hive removes it when it closes the issue itself once the guards hold

**Configuration and implementation.** Fixed label (`src/pkg/github/verified_close.go`, `src/pkg/config/issue_filter.go` `VerifyCloseLabel`, `src/pkg/scheduler/kickmessage.go` verify-once wording)

**Claims across a relaunch.** A scanner claim on a partially-addressed issue is still released when its agent's CLI is relaunched (`releaseClaimsOnAgentRelaunch`): the relaunch notice fires only when a fresh CLI replaces the old one (a surviving pane never releases), and crux does not resume the previous session on a fresh launch, so "the same agent resumes" never reaches that path; keeping the claim would park the issue at 020 on a context that no longer exists (the #13083 incident the release was added for). The verdict no longer depends on the claim: it is on the issue as the marker, the verify-once gate still withholds the issue from a second verification (it reads the ledger's last attempt, which the release keeps), and this sweep acts on the marker whoever holds the issue next.

#### `hive/already-done`

**Applies to:** Issues. **Kind:** Contributor hard skip; dashboard display; conditional close.
Expand Down
13 changes: 12 additions & 1 deletion src/docs/labels-and-control-signals/stage-labels.md
Original file line number Diff line number Diff line change
Expand Up @@ -1467,7 +1467,7 @@ These existing labels qualify a stage and may coexist with any stage label;
the reconciler never touches them: `hold` / `hold/*`, `needs-human`,
`blocked`, `needs-rebase`, `hive:unauthorized` (the App lacks a permission
for the next step; see the reference table),
`hive/likely-done`, `hive/partially-addressed`, `hive/verified-open`,
`hive/likely-done`, `hive/partially-addressed`, `hive/verified-open`, `hive/verify-close` (a 045 park, see below),
`hive/claimed-by-<who>` (the grey "who" modifier a stage cannot carry),
`lgtm`, `role/*`, `author/*`, `dco` / `no-dco`, and the agent provenance
labels.
Expand All @@ -1484,6 +1484,17 @@ implement the remainder (`src/pkg/scheduler/kickmessage.go`,
`src/cmd/hive/verifyonce.go`). They are not a second stage and are not
retired.

A partially-addressed issue the scanner verified complete leaves that
loop: its verify-once note ends with
`<!-- hive:verification verdict=complete prs=N -->`, and the issue stage
sweep closes it as completed (evidence comment citing the merged PRs) or,
when a guard is not met, parks it at `stage/045-needs-decision` with
`hive/verify-close`, the verify-close lane the activity monitor shows with
a one-click **Close as completed** (`src/pkg/github/verified_close.go`).
The lane is a park label rather than a numbered stage: issue stages run
010 to 045 and PR stages 050 to 100, so a `stage/050-…` issue stage would
cross the kinds the stage table keeps disjoint.

#### `hive/claimed-by-<who>`: one rule for the suffix

`<who>` names the **kind of party** accountable for the claim, derived from
Expand Down
2 changes: 2 additions & 0 deletions src/docs/notifications.md
Original file line number Diff line number Diff line change
Expand Up @@ -491,6 +491,8 @@ without a class. Review submissions and review requests are always counted as
| `github.(*Client).PostInformationalIssueNote` | `status` | passthrough wrapper (issue status card in quiet mode or under `attention_pilot`, for notes nobody acts on); attributed to its caller |
| `github.(*Client).closeDecomposedParent` | `status` | |
| `github.(*Client).closeDoneTracker` | `status` | |
| `github.(*Client).closeVerified` | `status` | |
| `github.(*Client).parkVerifiedForClose` | `status` | |
| `github.(*Client).closeIssueForMergedPRClaimWithIssue` | `status` | |
| `github.(*Client).closeSupersededPRDecision` | `status` | |
| `github.(*Client).fileReviewBacklog` | `status` | |
Expand Down
9 changes: 9 additions & 0 deletions src/pkg/config/issue_filter.go
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,12 @@ const (
// suppress — no agent claims a parked issue — and it is not configurable:
// the stage table owns the spelling (stagelabels contract tests pin it).
PossiblyExistsStageLabel = "stage/017-possible-existing"
// VerifyCloseLabel is the verify-close lane: the scanner verified the
// issue complete (`<!-- hive:verification verdict=complete … -->`) but a
// guard kept the hive from closing it itself, so a person confirms the
// close. It parks the issue in the decision bucket (045) like the
// stage label, and it is not configurable.
VerifyCloseLabel = "hive/verify-close"

// LegacyNeedsDecisionLabel and LegacyNeedsDirectionLabel are the retired
// park labels. Every hive still reads them as the decision bucket so an
Expand Down Expand Up @@ -290,6 +296,9 @@ func (f IssueFilterConfig) HardSuppressIssueBucket(labels []string) string {
if labelMatches(PossiblyExistsStageLabel, actual) {
return PossiblyExistsStageLabel
}
if labelMatches(VerifyCloseLabel, actual) {
return DefaultNeedsDecisionLabel
}
}
return ""
}
Expand Down
42 changes: 42 additions & 0 deletions src/pkg/dashboard/stage_tracker_decision.go
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ import (
"strings"
"time"

ghpkg "github.com/hivecommons/hive/pkg/github"
"github.com/hivecommons/hive/pkg/review"
"github.com/hivecommons/hive/pkg/stagelabels"
)
Expand Down Expand Up @@ -219,6 +220,10 @@ func stageTrackerDecisionNeededWith(it StageTrackerItem, verdict *review.Aggrega
return decisionForPR(it, verdict, sentinelLabel, held)
case it.Kind == "pr" && it.Stage == stagelabels.ReadyForHumanMerge.Number():
return decisionForHumanMerge(it, held)
case it.Kind == "issue" && stageTrackerHasLabel(it.Labels, ghpkg.VerifyCloseLabel):
// The scanner verified it complete; the hive only stopped short of
// closing it. The answer is Close, one click.
return decisionForVerifyClose(it, held)
case it.Kind == "issue" && it.Mirrored:
// The issue rides its covering PR; the PR's own row (nested under
// the issue) carries the decision.
Expand Down Expand Up @@ -264,3 +269,40 @@ func stageTrackerWithoutHold(it StageTrackerItem) StageTrackerItem {
it.Modifiers = slices.DeleteFunc(slices.Clone(it.Modifiers), func(m string) bool { return m == modHold })
return it
}

// The verify-close lane's action id and asker (hivecommons/hive#19299).
const (
decisionActionCloseIssue = "decide:close-issue"
decisionAskedByScanner = "the scanner's verification"
)

// stageTrackerHasLabel reports whether labels carries want (case-insensitive).
func stageTrackerHasLabel(labels []string, want string) bool {
for _, l := range labels {
if strings.EqualFold(strings.TrimSpace(l), want) {
return true
}
}
return false
}

// decisionForVerifyClose is the verify-close lane's popover: the scanner
// verified the issue complete, a guard kept the hive from closing it
// itself (its status card says which), and Close leads, one click.
func decisionForVerifyClose(it StageTrackerItem, held bool) *StageTrackerDecision {
d := &StageTrackerDecision{Since: it.StageSince, AskedBy: decisionAskedByScanner, BlockerReason: "label:" + ghpkg.VerifyCloseLabel}
d.Question = "The scanner verified this issue complete. Close it, or remove " + ghpkg.VerifyCloseLabel + " if work remains?"
d.Blocker = "The hive did not close it on its own; the reason is in the issue's status card. No agent picks it up while it waits here."
if held {
d.Blocker += " " + decisionHeldBlocker(it.Hold)
}
closeOpt := decisionOption(decisionActionCloseIssue, "Close as completed", true, "")
closeOpt.Lead = true
closeOpt.Consequence = "Closes this issue as completed, attributed to you"
d.Options = []StageTrackerDecisionOption{
closeOpt,
decisionOption(decisionActionDirection, "Send back", true, ""),
decisionHoldOption(held),
}
return d
}
30 changes: 30 additions & 0 deletions src/pkg/dashboard/stage_tracker_verify_close_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
package dashboard

import (
"testing"
"time"

ghpkg "github.com/hivecommons/hive/pkg/github"
"github.com/hivecommons/hive/pkg/stagelabels"
)

// The verify-close lane: the scanner verified the issue complete and the
// hive stopped short of closing it, so the row leads with a one-click Close.
func TestVerifyCloseIssueDecisionLeadsWithClose(t *testing.T) {
it := StageTrackerItem{Kind: "issue", Number: 17157, Stage: stagelabels.IssueNeedsDecision.Number(),
Labels: []string{ghpkg.PartiallyAddressedLabel, ghpkg.VerifyCloseLabel}}
d := stageTrackerDecisionNeededWith(it, nil, "", time.Date(2026, 11, 19, 12, 0, 0, 0, time.UTC), blockerOptionsContext{})
if d == nil || d.AskedBy != decisionAskedByScanner || len(d.Options) == 0 {
t.Fatalf("decision = %+v, want the verify-close decision", d)
}
lead := d.Options[0]
if lead.Action != decisionActionCloseIssue || !lead.Lead || !lead.Enabled {
t.Fatalf("lead option = %+v, want an enabled one-click %s", lead, decisionActionCloseIssue)
}

it.Labels = []string{ghpkg.PartiallyAddressedLabel}
d = stageTrackerDecisionNeededWith(it, nil, "", time.Date(2026, 11, 19, 12, 0, 0, 0, time.UTC), blockerOptionsContext{})
if d != nil && d.AskedBy == decisionAskedByScanner {
t.Fatal("control: without the lane label the ordinary 045 decision applies")
}
}
10 changes: 10 additions & 0 deletions src/pkg/github/issue_stage_labels.go
Original file line number Diff line number Diff line change
Expand Up @@ -148,6 +148,10 @@ type IssueStageResult struct {
// issue and PR they reference is finished (trackers_too,
// hivecommons/hive#19071).
TrackersClosed int
// VerifiedClosed counts issues closed because the scanner's
// verification marker said complete and every guard held
// (closeVerifiedComplete).
VerifiedClosed int
}

// issueStageRESTCaller tags the writes for /api/gh-rate-limits.
Expand Down Expand Up @@ -608,6 +612,12 @@ func SyncIssueStageLabelsWith(ctx context.Context, client *Client, result *Actio
res.Comments++
continue
}
if !awaitingChildren && client.closeVerifiedComplete(ctx, in, store, key, now, logger) {
res.VerifiedClosed++
res.Writes++
res.Comments++
continue
}
if closed, commented := handleMergedPRIssueStage(ctx, client, in, logger); closed {
res.MergedPRIssuesClosed++
res.Writes++
Expand Down
13 changes: 12 additions & 1 deletion src/pkg/github/issue_stage_labels_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,9 @@ type issueStageServer struct {
// default); timelineGets counts the reads.
timelines map[int][]map[string]any
timelineGets int
// pullRequests marks numbers GET /issues/N reports as pull requests,
// with their merged_at ("" = not merged), for the verified-close sweep.
pullRequests map[int]string
}

func newIssueStageServer(t *testing.T) *issueStageServer {
Expand Down Expand Up @@ -184,7 +187,15 @@ func newIssueStageServer(t *testing.T) *issueStageServer {
if _, done := s.closed[n]; done {
state = "closed"
}
_ = json.NewEncoder(w).Encode(map[string]any{"number": n, "labels": labels, "state": state, "body": s.bodies[n], "user": map[string]any{"login": "hive[bot]", "type": "Bot"}})
resp := map[string]any{"number": n, "labels": labels, "state": state, "body": s.bodies[n], "user": map[string]any{"login": "hive[bot]", "type": "Bot"}}
if mergedAt, ok := s.pullRequests[n]; ok {
link := map[string]any{"url": "https://api.example/pulls"}
if mergedAt != "" {
link["merged_at"] = mergedAt
}
resp["pull_request"] = link
}
_ = json.NewEncoder(w).Encode(resp)
case r.Method == http.MethodGet && strings.HasSuffix(rest, "/timeline"):
var n int
_, _ = sscanIssue(rest, &n)
Expand Down
5 changes: 5 additions & 0 deletions src/pkg/github/labels.go
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,7 @@ var hardSuppressIssueLabels = []string{
issueNeedsDecisionLabel,
issueNeedsDirectionLabel,
PossiblyExistsStageLabel,
VerifyCloseLabel,
}

// PossiblyExistsStageLabel is the prior-art gate's park: the issue stage
Expand Down Expand Up @@ -160,6 +161,10 @@ var escalationIssueLabelDefinitions = map[string]issueLabelDefinition{
color: LikelyDoneLabelColor,
description: LikelyDoneLabelDescription,
},
VerifyCloseLabel: {
color: VerifyCloseLabelColor,
description: VerifyCloseLabelDescription,
},
"meta": {
color: "5319e7",
description: "Tracker for multiple open items sharing one root cause",
Expand Down
2 changes: 2 additions & 0 deletions src/pkg/github/notification_write_sites.go
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,8 @@ var notificationWriteSites = map[string]NotificationWriteSite{
"github.(*Client).closeDecomposedParent": {Class: NotificationClassStatus},
"github.(*Client).closeIssueForMergedPRClaimWithIssue": {Class: NotificationClassStatus},
"github.(*Client).closeDoneTracker": {Class: NotificationClassStatus},
"github.(*Client).closeVerified": {Class: NotificationClassStatus},
"github.(*Client).parkVerifiedForClose": {Class: NotificationClassStatus},
"github.(*Client).closeSupersededPRDecision": {Class: NotificationClassStatus},
"github.(*Client).fileReviewBacklog": {Class: NotificationClassStatus},
"github.(*Client).foldSentinelNotice": {Class: NotificationClassStatus},
Expand Down
Loading
Loading