diff --git a/changelog.d/fixed-park-says-why.md b/changelog.d/fixed-park-says-why.md new file mode 100644 index 0000000000..6c26238e21 --- /dev/null +++ b/changelog.d/fixed-park-says-why.md @@ -0,0 +1 @@ +- A 045 park from a hosted contributor's needs-decision verdict now says why. The relay applies the decision label, and the agent was only asked to comment, so projectbluefin/common#1605 and projectbluefin/utah#1036 sat at 045 with no question. When nobody has commented since the task was assigned, the hub now posts the reported question once, marked ``, with the recommendation when the reason names one. The task prompt now asks for `decision: ; recommended: `. diff --git a/src/docs/contributor-relay.md b/src/docs/contributor-relay.md index 08bda94510..dd9a9cfaa9 100644 --- a/src/docs/contributor-relay.md +++ b/src/docs/contributor-relay.md @@ -1621,7 +1621,7 @@ The agent can now say it explicitly, the same way it says `no_work_needed`: ### A maintainer-decision verdict is labelled until a human answers -When the agent determines that nothing is shippable until a maintainer makes a design, policy, or approval decision, it prints `HIVE_VERDICT: no_work_needed — decision: ` ([#8470](https://github.com/hivecommons/hive/issues/8470)). The relay keeps the backward-compatible `no_work_needed` wire verdict and adds `verdict_needs_decision: true`; a verified PR still wins and suppresses the verdict. +When the agent determines that nothing is shippable until a maintainer makes a design, policy, or approval decision, it prints `HIVE_VERDICT: no_work_needed — decision: ; recommended: ` ([#8470](https://github.com/hivecommons/hive/issues/8470)). The relay keeps the backward-compatible `no_work_needed` wire verdict and adds `verdict_needs_decision: true`; a verified PR still wins and suppresses the verdict. The relay applies the decision label; when nobody has commented on the issue since the task was assigned, the hub posts the reported question (and the recommendation, when the reason names one) as a marked `` comment, so the 045 park never sits without a question. The hub books the issue for the full with-PR cooldown immediately and records a `needs_decision` ledger/run-log marker. The relay applies the label advertised by the hub in `auth_ok` (`hub.contribute_needs_decision_label`, default `needs-decision`) using the same task credential path as the `blocked` label. Empty config disables relay labelling, but the cooldown still applies. The relay posts no extra comment: the contributor's assessment comment is the human-readable record. The label is never cleared automatically; removing it is the maintainer signal that the decision has been made. The configured label is also treated as a contributor skip label, so a custom label such as `2-discussing` keeps the issue out of the offer queue until a human removes it. diff --git a/src/docs/notifications.md b/src/docs/notifications.md index 38459f2b2a..4701bc3137 100644 --- a/src/docs/notifications.md +++ b/src/docs/notifications.md @@ -609,6 +609,7 @@ without a class. Review submissions and review requests are always counted as | `mergelane.(*RESTGitHub).CreateIssueComment` | `status` | passthrough wrapper; attributed to its caller | | `dashboard.(*ContributeWSHub).parkWrongBase` | `attention` | | | `dashboard.(*ContributeWSHub).noteAlreadyDoneUnverified` | `attention` | asks a maintainer to verify an unsupported already-done claim | +| `dashboard.(*ContributeWSHub).needsDecisionParkPost` | `attention` | the question a contributor's needs-decision park was left without | | `dashboard.(*Server).handleRepoItemReroute` | `attention` | | | `dashboard.(*Server).handleReviewPipelineSendToHuman` | `attention` | | | `dashboard.(*Server).reroutePickupLapsed` | `attention` | | diff --git a/src/pkg/dashboard/contribute_needs_decision_park.go b/src/pkg/dashboard/contribute_needs_decision_park.go new file mode 100644 index 0000000000..21c2f1c9ed --- /dev/null +++ b/src/pkg/dashboard/contribute_needs_decision_park.go @@ -0,0 +1,152 @@ +package dashboard + +import ( + "context" + "fmt" + "regexp" + "strings" + "time" + + gh "github.com/google/go-github/v72/github" + + ghpkg "github.com/hivecommons/hive/pkg/github" +) + +// A needs-decision verdict parks the issue at 045: the contributor relay +// applies the decision label with the task credential (markIssueNeedsDecision +// in bin/contributor-relay.js), and the task prompt asks the agent to leave +// the question as a comment. Nothing checked that it did. +// projectbluefin/common#1605 (2026-11-01 05:58Z) and projectbluefin/utah#1036 +// (15:36Z) were parked that way with no comment at all, so the maintainer saw +// "Parked until a maintainer decides" and no question. The hub has the +// verdict's reason, so it posts the question itself — once per task, and +// only when nobody explained the park on the issue after the task was +// assigned. + +// needsDecisionParkTimeout bounds the detached GitHub work: one comment +// listing and at most one comment. +const needsDecisionParkTimeout = 30 * time.Second + +// needsDecisionParkMarkerPrefix tags the hub's park comment; with the task id +// it makes a re-delivered completion post nothing twice. +const needsDecisionParkMarkerPrefix = "" +} + +var parkTaskIDUnsafe = regexp.MustCompile(`[^A-Za-z0-9._/#:-]`) + +func sanitizeParkTaskID(id string) string { + return parkTaskIDUnsafe.ReplaceAllString(strings.TrimSpace(id), "") +} + +// parkExplanationMinLen is the shortest comment that counts as the agent's +// own park explanation; a footer or a bare "/hive" line does not. +const parkExplanationMinLen = 40 + +// parkCommentExplains reports whether a comment posted after the task was +// assigned already says why the issue is parked: any non-trivial comment +// that is not one of the hive's own marked notices (a good-first-issue +// withdrawal, a claim, an un-park notice), and the hub's own park comment. +func parkCommentExplains(body string) bool { + if strings.Contains(body, needsDecisionParkMarkerPrefix) { + return true + } + if strings.Contains(body, " now", "stage/045-needs-decision") + if strings.Contains(evil, "@castrojo") || strings.Count(evil, " ") != 1 { + t.Fatalf("task id must not close the marker early: %q", got) + } +} + +func TestParkCommentExplains(t *testing.T) { + for body, want := range map[string]bool{ + "The remaining step needs the owner to pick the queue owner; options below.": true, + " ~~Good first issue~~ — withdrawn": false, + "thanks!": false, + needsDecisionParkMarker("old") + "\n**Parked for a maintainer decision.**": true, + } { + if got := parkCommentExplains(body); got != want { + t.Errorf("parkCommentExplains(%q) = %v, want %v", body, got, want) + } + } +} + +// fakeParkGitHub serves the issue's comments and records any comment the hub +// posts. +func fakeParkGitHub(t *testing.T, comments []map[string]any) (*ghpkg.Client, *[]string, *string) { + t.Helper() + var mu sync.Mutex + var posted []string + var since string + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.Header().Set("Content-Type", "application/json") + if r.URL.Path != "/repos/acme/widgets/issues/77/comments" { + w.WriteHeader(http.StatusNotFound) + return + } + if r.Method == http.MethodPost { + var body struct { + Body string `json:"body"` + } + _ = json.NewDecoder(r.Body).Decode(&body) + mu.Lock() + posted = append(posted, body.Body) + mu.Unlock() + w.WriteHeader(http.StatusCreated) + _, _ = w.Write([]byte(`{"id":1}`)) + return + } + mu.Lock() + since = r.URL.Query().Get("since") + mu.Unlock() + _ = json.NewEncoder(w).Encode(comments) + })) + t.Cleanup(srv.Close) + return ghpkg.NewClientForTest(srv.URL, "acme", []string{"widgets"}, covBLogger()), &posted, &since +} + +func TestNeedsDecisionParkPost(t *testing.T) { + assigned := time.Date(2026, 11, 1, 5, 55, 40, 0, time.UTC) + before := assigned.Add(-time.Hour).Format(time.RFC3339) + after := assigned.Add(2 * time.Minute).Format(time.RFC3339) + for _, tc := range []struct { + name string + comments []map[string]any + want bool + }{ + {name: "no comments: post the question", comments: nil, want: true}, + {name: "only the hive's own good-first-issue notice (utah#1036)", comments: []map[string]any{ + {"id": 1, "body": " ~~Good first issue~~ — withdrawn by the hive", "created_at": after}}, want: true}, + {name: "a comment from before the task does not explain this park", comments: []map[string]any{ + {"id": 2, "body": "This looks insane, I love it! The way I have been doing this is by automating bumps.", "created_at": before}}, want: true}, + {name: "the agent explained the park itself", comments: []map[string]any{ + {"id": 3, "body": "Parking: the owner must choose who admits PRs to the merge queue. Recommended: A.", "created_at": after}}, want: false}, + {name: "already posted for this task", comments: []map[string]any{ + {"id": 4, "body": needsDecisionParkMarker("t") + "\n**Parked for a maintainer decision.**", "created_at": after}}, want: false}, + } { + t.Run(tc.name, func(t *testing.T) { + hub, _ := covK2Hub(t) + client, posted, since := fakeParkGitHub(t, tc.comments) + hub.server.deps.GHClient = client + hub.postNeedsDecisionPark(&WSTaskAssign{Kind: "issue", Repo: "acme/widgets", Number: 77}, "t", "j1mc", parkReason1605, assigned) + if got := len(*posted) == 1; got != tc.want { + t.Fatalf("posted = %v, want a post: %v", *posted, tc.want) + } + if tc.want && !strings.Contains((*posted)[0], "**Question:** "+parkReason1605) { + t.Fatalf("posted the wrong body:\n%s", (*posted)[0]) + } + if *since == "" { + t.Fatal("the comment listing must be bounded by the task's assignment time") + } + }) + } +} + +func TestNeedsDecisionParkSkipsNonIssueTasks(t *testing.T) { + hub, _ := covK2Hub(t) + var calls int + hub.needsDecisionParkPoster = func(context.Context, string, int, time.Time, string) error { + calls++ + return nil + } + for _, task := range []*WSTaskAssign{ + nil, + {Kind: "pr", Repo: "o/r", Number: 5}, + {Kind: "issue", Repo: "", Number: 5}, + {Kind: "issue", Repo: "o/r", Number: 0}, + {Kind: "issue", Repo: "o/r", Number: 5, ExternalID: "LIN-1"}, + } { + hub.postNeedsDecisionPark(task, "t", "u", "r", time.Now()) + } + if calls != 0 { + t.Fatalf("only GitHub-backed issue tasks get a park comment, got %d calls", calls) + } + var nilHub *ContributeWSHub + nilHub.postNeedsDecisionPark(&WSTaskAssign{Kind: "issue", Repo: "o/r", Number: 5}, "t", "u", "r", time.Now()) +} + +// The real task_complete handler posts the question for a needs-decision +// verdict that stands, and not for a gate park the hub releases. +func TestNeedsDecisionParkWireShape(t *testing.T) { + s, ts := setupWSTest(t) + defer ts.Close() + + req := httptest.NewRequest(http.MethodPost, "/api/contribute/register", strings.NewReader(`{"github_username":"j1mc"}`)) + req.Header.Set("Content-Type", "application/json") + w := httptest.NewRecorder() + s.mux.ServeHTTP(w, req) + var reg map[string]string + if err := json.Unmarshal(w.Body.Bytes(), ®); err != nil { + t.Fatalf("register response: %v", err) + } + conn, _, err := websocket.DefaultDialer.Dial(wsURL(ts), nil) + if err != nil { + t.Fatalf("dial: %v", err) + } + defer conn.Close() + readMsg(t, conn) + conn.WriteJSON(WSMessage{Type: "auth_response", RegistrationToken: reg["registration_token"], CLIBackend: "pi"}) + readMsg(t, conn) + + s.statusMu.Lock() + s.status = &StatusPayload{Repos: []FrontendRepo{{ + Name: "widgets", Full: "acme/widgets", + ActionableIssues: []any{noWorkIssue(77, "Owner decision: enable Hive admission to GitHub merge queues", time.Now().Add(-24*time.Hour))}, + }}} + s.statusMu.Unlock() + + hub := s.contributeHub + type call struct { + repo string + number int + since time.Time + body string + } + got := make(chan call, 2) + hub.needsDecisionParkPoster = func(_ context.Context, repo string, number int, since time.Time, body string) error { + got <- call{repo, number, since, body} + return nil + } + hub.gateParkReleaser = newToolingReleaseFixture().release + + conn.WriteJSON(WSMessage{Type: "ready", Seq: 2}) + assign := readMsg(t, conn) + if assign.Type != "task_assign" || assign.Number != 77 { + t.Fatalf("expected task_assign for #77, got %+v", assign) + } + conn.WriteJSON(WSMessage{ + Type: "task_complete", TaskID: assign.TaskID, Result: "completed", + CompletionSignal: completionSignalVerdict, + Verdict: "no_work_needed", VerdictNeedsDecision: true, + VerdictReason: parkReason1605, + }) + select { + case c := <-got: + if c.repo != "acme/widgets" || c.number != 77 || c.since.IsZero() || !strings.Contains(c.body, "@j1mc's agent") || !strings.Contains(c.body, assign.TaskID) { + t.Fatalf("park comment call = %+v", c) + } + case <-time.After(5 * time.Second): + t.Fatal("a standing needs-decision verdict must post its question") + } + + // A gate park is released, not posted. + key := noPRKey("acme/widgets", 77) + hub.completedMu.Lock() + hub.completedTasks[key] = time.Now().Add(-(hub.completedTaskCooldown[key] + time.Minute)) + delete(hub.noWorkVerdicts, key) + hub.completedMu.Unlock() + conn.WriteJSON(WSMessage{Type: "ready", Seq: 3}) + again := readMsg(t, conn) + if again.Type != "task_assign" || again.Number != 77 { + t.Skipf("issue not re-offered in this harness (%+v); the first half is the regression", again) + } + conn.WriteJSON(WSMessage{ + Type: "task_complete", TaskID: again.TaskID, Result: "completed", + CompletionSignal: completionSignalVerdict, + Verdict: "no_work_needed", VerdictNeedsDecision: true, + VerdictReason: gateParkReason, + }) + select { + case c := <-got: + t.Fatalf("a released gate park must not get a park comment: %+v", c) + case <-time.After(300 * time.Millisecond): + } +} diff --git a/src/pkg/dashboard/contribute_task_prompt.go b/src/pkg/dashboard/contribute_task_prompt.go index 46c52b4189..df3c8eb731 100644 --- a/src/pkg/dashboard/contribute_task_prompt.go +++ b/src/pkg/dashboard/contribute_task_prompt.go @@ -656,9 +656,11 @@ func buildTaskPromptBodyWithHintsAndIssueRead(repoFull, issueRef, title, sourceH "only after checking the PR is merged or the commit is on the default branch) "+ "and stop. If the remaining work is waiting on a maintainer-only design, "+ "policy, or approval decision, use the structured reason form "+ - "'HIVE_VERDICT: no_work_needed — decision: ' "+ + "'HIVE_VERDICT: no_work_needed — decision: ; recommended: ' "+ "so hive applies the configured maintainer-decision label and keeps it out "+ - "of the queue until a human removes that label. A repository's own "+ + "of the queue until a human removes that label. Hive posts that question "+ + "and recommendation on the issue when you leave no comment of your own, so "+ + "write them for the maintainer. A repository's own "+ "spec/confirmation gate or a missing companion checkout is never such a "+ "decision (see above); hive re-dispatches a decision verdict that cites one. "+ // hivecommons/hive#7924: the blocked sentinel. utah#100 reached a diff --git a/src/pkg/dashboard/contribute_ws.go b/src/pkg/dashboard/contribute_ws.go index 4dd761d43f..37cdae5118 100644 --- a/src/pkg/dashboard/contribute_ws.go +++ b/src/pkg/dashboard/contribute_ws.go @@ -1213,6 +1213,10 @@ type ContributeWSHub struct { // GHClient. gateParkRekicks records the one re-kick each issue gets. gateParkReleaser func(ctx context.Context, repo string, number int, reporter, reason string) error gateParkRekicks gateParkRekicks + // needsDecisionParkPoster is the seam for posting the question a + // needs-decision park was left without (contribute_needs_decision_park.go); + // nil means use GHClient. + needsDecisionParkPoster func(ctx context.Context, repo string, number int, since time.Time, body string) error // verdictBlockerRecorder is the seam for recording the blocker a blocked // verdict names (contribute_verdict_blocker.go); nil means use GHClient. // verdictBlockersRecorded dedupes re-delivered verdicts per task. @@ -4532,6 +4536,13 @@ func (s *wsSession) handleTaskComplete(msg WSMessage) { go h.releaseGateParkedIssue(completedTask, s.contributor.profile.GitHubUsername, verdictReason) } } + // A needs-decision verdict that stands parks the issue at 045 with + // the relay's label alone; the hub posts the question when the + // agent left none (contribute_needs_decision_park.go). + if verdict == completionVerdictNeedsDecision && completedTask != nil { + taskCopy := *completedTask + go h.postNeedsDecisionPark(&taskCopy, msg.TaskID, s.contributor.profile.GitHubUsername, verdictReason, taskAssignedAt) + } if completedTask != nil { // #2393 item 7 + #2565: the full week-long cooldown is applied // only for a VERIFIED PR; an unverified or no-PR completion gets diff --git a/src/pkg/github/notification_write_sites.go b/src/pkg/github/notification_write_sites.go index 5412ec4a31..f576c9865c 100644 --- a/src/pkg/github/notification_write_sites.go +++ b/src/pkg/github/notification_write_sites.go @@ -78,6 +78,7 @@ var notificationWriteSites = map[string]NotificationWriteSite{ // attention: asks a person to look or act. "dashboard.(*ContributeWSHub).parkWrongBase": {Class: NotificationClassAttention}, "dashboard.(*ContributeWSHub).noteAlreadyDoneUnverified": {Class: NotificationClassAttention}, + "dashboard.(*ContributeWSHub).needsDecisionParkPost": {Class: NotificationClassAttention}, "dashboard.(*Server).handleRepoItemReroute": {Class: NotificationClassAttention}, "dashboard.(*Server).handleReviewPipelineSendToHuman": {Class: NotificationClassAttention}, "dashboard.(*Server).reroutePickupLapsed": {Class: NotificationClassAttention},