diff --git a/changelog.d/fixed-decide-workflow-path-capability-gap.md b/changelog.d/fixed-decide-workflow-path-capability-gap.md
new file mode 100644
index 0000000000..9685ff2659
--- /dev/null
+++ b/changelog.d/fixed-decide-workflow-path-capability-gap.md
@@ -0,0 +1 @@
+- Delegated decisions now recommend a permission grant, instead of a doomed supersede, for contributor PRs that edit `.github/workflows/`
diff --git a/src/pkg/dashboard/api_repo_item_decide_workflow_path_test.go b/src/pkg/dashboard/api_repo_item_decide_workflow_path_test.go
new file mode 100644
index 0000000000..de5c785f3a
--- /dev/null
+++ b/src/pkg/dashboard/api_repo_item_decide_workflow_path_test.go
@@ -0,0 +1,46 @@
+package dashboard
+
+import (
+ "net/http"
+ "strings"
+ "testing"
+
+ "github.com/hivecommons/hive/pkg/delegatedecision"
+)
+
+// hivecommons/hive#15203: a contributor head that edits `.github/workflows/`
+// cannot be adopted (the App has no `workflows` permission), so "Let hive
+// decide" must answer capability-gap, never queue an adopt-supersede.
+func TestDelegatedDecisionWorkflowPathHeadAnswersCapabilityGap(t *testing.T) {
+ mock := &repoItemDecisionMock{prForeign: true, prRedCI: true, prMergeState: "blocked", prFiles: []string{"README.md", ".github/workflows/ci.yml"}}
+ srv := newDelegatedServer(t, mock)
+ w := postDelegated(t, srv, 8, "writer", `{"type":"pr","reason":"contributor-lane:decision-requested","caption":"Needs human decision"}`, nil)
+ if w.Code != http.StatusOK {
+ t.Fatalf("code=%d body=%s", w.Code, w.Body.String())
+ }
+ job := decodeDelegatedJob(t, w)
+ if job.Decision == nil || job.Decision.Rule != "capability-gap" || job.Decision.Verdict != delegatedecision.VerdictRecommendOnly || !job.Decision.KeepsPark {
+ t.Fatalf("decision = %+v status=%s err=%s", job.Decision, job.Status, job.Error)
+ }
+ if job.Result == nil || job.Result.Action != rowActionRecommended {
+ t.Fatalf("result = %+v", job.Result)
+ }
+ if strings.Contains(strings.Join(mock.added, ","), delegatedecision.LabelAdoptSupersede) {
+ t.Fatalf("adoption queued for a head the App cannot push: %v", mock.added)
+ }
+}
+
+// The same offline contributor with an ordinary diff still adopts: the file
+// list, not the park alone, decides capability-gap.
+func TestDelegatedDecisionNonWorkflowHeadStillAdopts(t *testing.T) {
+ mock := &repoItemDecisionMock{prForeign: true, prRedCI: true, prMergeState: "blocked", prFiles: []string{"src/main.go"}}
+ srv := newDelegatedServer(t, mock)
+ w := postDelegated(t, srv, 8, "writer", `{"type":"pr","reason":"contributor-lane:decision-requested","caption":"Needs human decision"}`, nil)
+ if w.Code != http.StatusOK {
+ t.Fatalf("code=%d body=%s", w.Code, w.Body.String())
+ }
+ job := decodeDelegatedJob(t, w)
+ if job.Decision == nil || job.Decision.Verdict != delegatedecision.VerdictAdoptSupersede {
+ t.Fatalf("decision = %+v status=%s err=%s", job.Decision, job.Status, job.Error)
+ }
+}
diff --git a/src/pkg/dashboard/api_repo_item_decision_test.go b/src/pkg/dashboard/api_repo_item_decision_test.go
index 952e327907..803067b374 100644
--- a/src/pkg/dashboard/api_repo_item_decision_test.go
+++ b/src/pkg/dashboard/api_repo_item_decision_test.go
@@ -31,6 +31,9 @@ type repoItemDecisionMock struct {
// labels pulls/8 reports.
prForeign bool
prLabels []string
+ // prFiles are the paths GET pulls/8/files (and pulls/9/files) list; a
+ // `.github/workflows/` path is a head the App cannot adopt.
+ prFiles []string
// prMergeState is PR #8's mergeable_state ("" = clean); prRedCI and
// prNoCI shape the head's combined status when the state alone does not
// settle CI (e.g. "blocked").
@@ -109,6 +112,12 @@ func newRepoItemDecisionServer(t *testing.T, m *repoItemDecisionMock) *Server {
_, _ = io.WriteString(w, `{"sha":"0ddba11","merged":true,"message":"Pull Request successfully merged"}`)
case r.Method == http.MethodGet && strings.HasSuffix(path, "/pulls/8/reviews"):
_, _ = io.WriteString(w, `[]`)
+ case r.Method == http.MethodGet && (strings.HasSuffix(path, "/pulls/8/files") || strings.HasSuffix(path, "/pulls/9/files")):
+ files := make([]map[string]any, 0, len(m.prFiles))
+ for _, f := range m.prFiles {
+ files = append(files, map[string]any{"filename": f, "status": "modified", "additions": 1, "deletions": 0})
+ }
+ _ = json.NewEncoder(w).Encode(files)
case r.Method == http.MethodPost && strings.HasSuffix(path, "/pulls/8/reviews"):
var body map[string]any
_ = json.NewDecoder(r.Body).Decode(&body)
diff --git a/src/pkg/dashboard/delegated_pr_context.go b/src/pkg/dashboard/delegated_pr_context.go
index 74895d8177..140fdd7a2f 100644
--- a/src/pkg/dashboard/delegated_pr_context.go
+++ b/src/pkg/dashboard/delegated_pr_context.go
@@ -92,6 +92,15 @@ func (s *Server) gatherDelegatedPRContext(ctx context.Context, repo string, pr *
// snapshot alone does not; the live tracker reads it the same way.
items := s.buildStageTracker(status, s.stageStoreOrShared(), now).Items
api := s.deps.GHClient.GoGitHub()
+ // A partial list could miss a workflow path, so an incomplete one fails closed.
+ files, err := github.ListPRChangedFiles(ctx, api, owner, name, pr)
+ if err != nil {
+ return fmt.Errorf("reading changed files for %s#%d: %w", repo, pr.GetNumber(), err)
+ }
+ in.ChangedFiles = make([]string, 0, len(files))
+ for _, f := range files {
+ in.ChangedFiles = append(in.ChangedFiles, f.Filename)
+ }
for _, number := range delegatedCompetingNumbers(items, repo, pr) {
other, _, err := api.PullRequests.Get(ctx, owner, name, number)
if err != nil {
diff --git a/src/pkg/dashboard/static/index.html b/src/pkg/dashboard/static/index.html
index 2f1f6c6b7d..0394bdca34 100644
--- a/src/pkg/dashboard/static/index.html
+++ b/src/pkg/dashboard/static/index.html
@@ -17199,7 +17199,7 @@
All labels
"author-association": {"kind": "reason", "plain": "no merge lane vouches for this PR's author; a maintainer merges", "detail": "The PR is ready, but its author is not a collaborator and holds no trusted or merger tier, so no merge lane vouches for them and the hive never merges it unattended. A maintainer merges it (Approve & merge as maintainer, or Approve — let hive merge), or trusts the author under 👥 Contributors."},
"author-online": {"kind": "reason", "plain": "the author's hive is connected, so hive won't take the PR over", "detail": "Adoption is for authors whose hive has gone offline; this author's hive is connected, so the hive leaves the PR with them."},
"behind": {"kind": "reason", "plain": "the branch is behind the base branch", "detail": "The branch is behind the base branch and must be updated before it can merge."},
- "capability-gap": {"kind": "rule", "plain": "the GitHub App lacks a permission; deciding cannot clear it", "detail": "The blocker is a missing GitHub App permission (for example `workflows`). Approving a direction would only re-apply needs-human, so the park stays until the owner grants the permission or a person applies the change."},
+ "capability-gap": {"kind": "rule", "plain": "the GitHub App lacks a permission; deciding cannot clear it", "detail": "The blocker is a missing GitHub App permission (for example `workflows`), including a contributor PR that edits `.github/workflows/`. Approving a direction would only re-apply needs-human, so the park stays until the owner grants the permission or a person applies the change."},
"changes-requested": {"kind": "reason", "plain": "a reviewer asked for changes; a new commit is needed", "detail": "A reviewer asked for changes on this branch. Approving cannot override that: only a new commit, or a maintainer merging by hand, moves it."},
"changes_requested": {"kind": "reason", "plain": "a reviewer asked for changes; a new commit is needed", "detail": "A reviewer asked for changes on this branch. Approving cannot override that: only a new commit, or a maintainer merging by hand, moves it."},
"checks-failing": {"kind": "reason", "plain": "CI is failing on this branch", "detail": "Required checks are failing on this branch; nothing merges until they are green."},
diff --git a/src/pkg/delegatedecision/decision_glossary.go b/src/pkg/delegatedecision/decision_glossary.go
index 809c9bbba5..b0b63c8aa1 100644
--- a/src/pkg/delegatedecision/decision_glossary.go
+++ b/src/pkg/delegatedecision/decision_glossary.go
@@ -92,7 +92,7 @@ var glossary = []GlossaryEntry{
{Slug: "hive-policy", Kind: GlossaryRule, Plain: "this changes the hive's own rules",
Detail: "This changes the hive's own settings, governance or security posture; the hive only recommends and the owner confirms."},
{Slug: "capability-gap", Kind: GlossaryRule, Plain: "the GitHub App lacks a permission; deciding cannot clear it",
- Detail: "The blocker is a missing GitHub App permission (for example `workflows`). Approving a direction would only re-apply needs-human, so the park stays until the owner grants the permission or a person applies the change."},
+ Detail: "The blocker is a missing GitHub App permission (for example `workflows`), including a contributor PR that edits `.github/workflows/`. Approving a direction would only re-apply needs-human, so the park stays until the owner grants the permission or a person applies the change."},
{Slug: "review-backlog", Kind: GlossaryRule, Plain: "the PR closed without merging, so the issue stays open",
Detail: "The fixing PR closed unmerged; the issue stays open and is re-triaged rather than auto-closed."},
{Slug: "flaky-test", Kind: GlossaryRule, Plain: "a flaky test, quarantined with a retry",
diff --git a/src/pkg/delegatedecision/policy.go b/src/pkg/delegatedecision/policy.go
index ee90a454c0..eba5cce9a8 100644
--- a/src/pkg/delegatedecision/policy.go
+++ b/src/pkg/delegatedecision/policy.go
@@ -172,6 +172,8 @@ type Input struct {
// LowRiskPaths: every changed file is CI config, workflow, docs, text or
// read-only RBAC.
LowRiskPaths bool
+ // ChangedFiles are the PR's changed paths, when known.
+ ChangedFiles []string
// ContributorOnline: the author is reachable (relay heartbeat / recent
// activity); false for an external author who went quiet.
ContributorOnline bool
@@ -313,6 +315,25 @@ func CapabilityGap(in Input) bool {
in.Kind == KindIssue && capabilityGapRE.MatchString(firstLines(in.Body, 12))
}
+// WorkflowPath reports a PR that edits `.github/workflows/` or whose adoption
+// parked on the workflow-path fence; the App cannot push such a head.
+func (in Input) WorkflowPath() bool {
+ for _, f := range in.ChangedFiles {
+ if strings.HasPrefix(strings.TrimPrefix(f, "./"), ".github/workflows/") {
+ return true
+ }
+ }
+ for _, r := range in.Reasons {
+ if strings.Contains(r, workflowPathParkSlug) {
+ return true
+ }
+ }
+ return false
+}
+
+// workflowPathParkSlug is the adoption fence reason for a workflow-path head.
+const workflowPathParkSlug = "adoption-stalled:contributor-lane:workflow-path"
+
// OwnerOnly reports a secrets / PAT / org-permission item.
func OwnerOnly(in Input) bool {
if secretsRE.MatchString(in.headline()) {
@@ -460,6 +481,10 @@ func decidePR(in Input) Decision {
return d
}
}
+ if !in.HiveAuthored && in.Kind == KindPR && in.WorkflowPath() && (in.AdoptionGraceElapsed || (!in.ContributorOnline && (in.AdoptionStalled || in.Conflicting || !in.CIGreen || in.DCOMissing))) {
+ return recommendOnly("capability-gap", "the head edits `.github/workflows/`, which the App has no `workflows` permission to push; adopting it would be refused before it is recorded, so the park stays until the permission changes",
+ "grant the App the `workflows` permission or have a human apply the workflow change, then re-check; hive cannot clear this by deciding")
+ }
if !in.HiveAuthored && in.Kind == KindPR && in.AdoptionGraceElapsed {
text := "adopt now: the offline grace on " + ref + " has already elapsed; adopt in supersede mode at once, preserving the author's commits and sign-off"
return Decision{
diff --git a/src/pkg/delegatedecision/policy_test.go b/src/pkg/delegatedecision/policy_test.go
index 0f49450436..9daf5f9dde 100644
--- a/src/pkg/delegatedecision/policy_test.go
+++ b/src/pkg/delegatedecision/policy_test.go
@@ -236,6 +236,26 @@ func TestDecidePRRules(t *testing.T) {
in: Input{Kind: KindPR, Number: 54, Title: "Contributor fix", AdoptionStalled: true, CIGreen: true},
verdict: VerdictAdoptSupersede, rule: "contributor-offline", kinds: []ActionKind{ActionCommentDecision, ActionAdoptSupersede},
},
+ {
+ name: "workflow-path PR gets capability-gap",
+ in: Input{Kind: KindPR, Number: 54, Title: "Contributor fix", AdoptionStalled: true, CIGreen: true, ChangedFiles: []string{"README.md", ".github/workflows/ci.yml"}},
+ verdict: VerdictRecommendOnly, rule: "capability-gap", keepsPark: true,
+ },
+ {
+ name: "row parked on workflow-path gets capability-gap",
+ in: Input{Kind: KindPR, Number: 54, Title: "Contributor fix", CIGreen: true, Conflicting: true, Reasons: []string{"adoption-stalled:contributor-lane:workflow-path"}},
+ verdict: VerdictRecommendOnly, rule: "capability-gap", keepsPark: true,
+ },
+ {
+ name: "grace-elapsed workflow-path PR gets capability-gap, not adopt-now",
+ in: Input{Kind: KindPR, Number: 54, Title: "Contributor fix", AdoptionGraceElapsed: true, ContributorOnline: true, CIGreen: true, ChangedFiles: []string{".github/workflows/ci.yml"}},
+ verdict: VerdictRecommendOnly, rule: "capability-gap", keepsPark: true,
+ },
+ {
+ name: "non-workflow offline PR still adopts",
+ in: Input{Kind: KindPR, Number: 54, Title: "Contributor fix", AdoptionStalled: true, CIGreen: true, ChangedFiles: []string{"src/main.go"}},
+ verdict: VerdictAdoptSupersede, rule: "contributor-offline",
+ },
{
name: "offline contributor with red CI adopts",
in: Input{Kind: KindPR, Number: 54, Title: "Contributor fix", DCOMissing: true, CIGreen: true},