diff --git a/changelog.d/added-19078-contributor-umbrella-exclusion.md b/changelog.d/added-19078-contributor-umbrella-exclusion.md new file mode 100644 index 0000000000..4aa79c4651 --- /dev/null +++ b/changelog.d/added-19078-contributor-umbrella-exclusion.md @@ -0,0 +1 @@ +- Umbrella, epic, tracker and owner-only issues are never handed to a contributor relay, and are counted separately. A shared classifier (`hub.contribute_umbrella`, with per-repo overrides) recognises an umbrella by label (default `umbrella`, `tracker`, `epic`, `meta-tracker`), the `` body marker, a `[Tracking]` / `[Epic]` / `[Umbrella]` / `[Tracker]` title prefix, a checklist of two or more issue or PR references, or sub-issues, and an owner-only issue by `needs-human`, `human-only`, `human-only:*` or ``. `/contribute` selection and the ready-work queue refuse them; `/api/contribute/status` gains `umbrella_items`, `human_only_items` and `candidate_items_raw`, and `actionable_items` / `candidate_items` count only contributor-workable work; the contributor page shows "N workable" and how many umbrella and owner-only items are not offered. The good-first-issue sweep withdraws `help wanted` and `good first issue` from an umbrella on the next sweep (switchable, logged), and the dashboard row shows an "Umbrella · owner" pill. They stay actionable for the owner and the hive and, unlike `hive/tracking`, stay closable under `parent_autoclose` and the tracker-closing rule ([#19078](https://github.com/hivecommons/hive/issues/19078)). diff --git a/dashboard/openapi.json b/dashboard/openapi.json index c8a753cccc..a6cf4fdc2e 100644 --- a/dashboard/openapi.json +++ b/dashboard/openapi.json @@ -9381,7 +9381,7 @@ "Contributors" ], "summary": "Contributor hub status", - "description": "Returns contributor hub registration state and work counts. actionable_items is the uncapped number of issues currently offerable after contributor admission; candidate_items is the raw pre-admission scanner population.", + "description": "Returns contributor hub registration state and work counts. actionable_items is the uncapped number of issues currently offerable after contributor admission; candidate_items is the contributor-workable scanner population (the raw population minus umbrella and owner-only issues); candidate_items_raw is the raw pre-admission scanner population; umbrella_items and human_only_items count the umbrella/tracker and owner-only issues that are never offered to a contributor.", "responses": { "200": { "description": "Hub status", @@ -9405,7 +9405,19 @@ }, "candidate_items": { "type": "integer", - "description": "Raw scanner candidate count before contributor admission" + "description": "Scanner candidate count before contributor admission, excluding umbrella and owner-only issues (contributor-workable candidates)" + }, + "candidate_items_raw": { + "type": "integer", + "description": "Raw scanner candidate count before contributor admission and before the umbrella and owner-only exclusion (the previous meaning of candidate_items)" + }, + "umbrella_items": { + "type": "integer", + "description": "Umbrella, epic, tracker and decomposed-parent issues. They stay actionable for the owner and the hive and are never offered to a contributor" + }, + "human_only_items": { + "type": "integer", + "description": "Owner-only issues (needs-human, human-only, human-only marker). They are never offered to a contributor" }, "surface": { "type": "string" diff --git a/src/cmd/hive/gfi_wire.go b/src/cmd/hive/gfi_wire.go index 2e8791dfcb..5413ea8582 100644 --- a/src/cmd/hive/gfi_wire.go +++ b/src/cmd/hive/gfi_wire.go @@ -107,6 +107,10 @@ func gfiSweepOptions(cfg *config.Config, dashSrv *dashboard.Server, logger *slog Template: gc.CommentTemplate, Logger: logger, } + // hivecommons/hive#19078: umbrella and owner-only issues are never + // advertised and lose `help wanted` / `good first issue`, per the hive's + // hub.contribute_umbrella block and its per-repo overrides. + opts.Policy.UmbrellaFor = func(repo string) gfi.UmbrellaPolicy { return cfg.Hub.UmbrellaPolicyFor(repo) } if dashSrv != nil { opts.Audit = func(e gfi.Event) { detail := fmt.Sprintf("repo=%s, issue=%d", e.Repo, e.Number) @@ -143,6 +147,9 @@ func gfiCandidates(org string, result *github.ActionableResult, allowed func(str Repo: repo, Number: is.Number, Title: is.Title, Body: is.Body, URL: is.URL, Labels: is.Labels, Assignees: is.Assignees, CreatedAt: is.CreatedAt, } + if is.Children != nil { + c.Children = is.Children.Total + } if is.State != "" && !strings.EqualFold(is.State, "open") { continue } diff --git a/src/docs/agent-configuration.md b/src/docs/agent-configuration.md index 8556769458..eda0952baf 100644 --- a/src/docs/agent-configuration.md +++ b/src/docs/agent-configuration.md @@ -1428,6 +1428,14 @@ Issues managed by [GitHub Agentic Workflows](https://github.com/github/gh-aw) (` The `hive/tracking` label also satisfies the tracker-issue check used by `/contribute`, so a tracking issue is never handed to an external contributor either. +### Umbrella and owner-only issues + +Umbrella, epic, tracker and decomposed-parent issues, and issues that wait on a person, are the opposite of a tracking archive: they stay actionable for the owner and the hive and **can be closed**. They are never handed to a contributor relay. Mark one with a label (`umbrella`, `tracker`, `epic`, `meta-tracker`), the body marker ``, a `[Tracking]` / `[Epic]` / `[Umbrella]` / `[Tracker]` title prefix, a task list of two or more issue or PR references, or sub-issues; owner-only by `needs-human`, `human-only`, `human-only:*` or ``. The rules, defaults and per-repo overrides live under `hub.contribute_umbrella` (see the [label reference](labels-and-control-signals/reference.md) and [Contributor relay](contributor-relay.md#umbrella-and-owner-only-issues-are-never-handed-to-a-relay)). + +- **Not offered.** `/contribute` selection and the ready-work queue refuse them (withheld reasons `umbrella` and `human_only`); `/api/contribute/status` counts them as `umbrella_items` and `human_only_items` and leaves them out of `actionable_items` and `candidate_items`. +- **Not advertised.** The good-first-issue sweep scores them `umbrella:` / `human-only:` and withdraws `help wanted` and `good first issue` on the next sweep (logged and audited as `gfi-withdraw`; `withdraw_advertisement: false` opts out). +- **Still closable.** Unlike `hive/tracking`, none of these markers blocks `CloseIssue`, `parent_autoclose` or the tracker-closing rule. + **Not the same thing as the contribute filters.** `hub.contribute_labels_mode` + its label list gate which issues are *handed out to external contributors* over `/contribute` — they have never gated the hive's **own** agents, so an operator who allow-listed a queue label there (a common setup for routing labeled issues to contributors) still had a hive whose own scanner could work every other open issue. `project.issue_filter.require_labels` is the agent-side gate; configure both if you want the same label to govern both lanes. ## Write-back containment (`writeback`) diff --git a/src/docs/contributor-relay.md b/src/docs/contributor-relay.md index 13b5fe9a30..85888fff8c 100644 --- a/src/docs/contributor-relay.md +++ b/src/docs/contributor-relay.md @@ -990,6 +990,8 @@ Withheld rows carry a stable reason code and, where the refusing gate had one, t | `dependency_unknown` | A declared dependency could not be resolved, so satisfaction cannot be asserted. | Blocker keys, observed record/generation | | `disabled_repo` | The repository is switched off for contribution (`disabled_repos`). | — | | `tracker` | A tracker/umbrella issue; its children carry the work and queue independently. Recognised by an `epic`/`tracker`/`tracking`/`meta-tracker` label (including prefixed spellings such as `kind/epic`), an `[Epic]`/`[Tracker]` title prefix, or a body listing three or more child issues. | — | +| `umbrella` | An umbrella, epic, tracker or decomposed parent under the `hub.contribute_umbrella` rules: a label (default `umbrella`, `tracker`, `epic`, `meta-tracker`), the `` body marker, a title prefix (default `[Tracking]`, `[Epic]`, `[Umbrella]`, `[Tracker]`), a task list of two or more issue or PR references, or sub-issues. It stays actionable for the owner and the hive and is never offered to a contributor ([#19078](https://github.com/hivecommons/hive/issues/19078)). | Matched rule | +| `human_only` | The issue waits on a person: label `needs-human`, `human-only` or `human-only:*`, or the `` body marker. Never offered to a contributor. | Matched rule | | `cooldown` | The issue completed recently and is inside its post-completion cooldown. | Expiry timestamp | | `failure_cooldown` | The issue failed recently and is inside its failure cooldown or quarantine window. | Expiry timestamp | | `no_work_needed` | A live `no_work_needed` verdict is suppressing the issue until it changes again. | — | @@ -1199,7 +1201,7 @@ sequenceDiagram R->>H: result (PR opened / success / failure) ``` -- The **work queue** includes monitored-repository candidates that pass disabled-repository, hold, cooldown, in-flight, dependency, assignment, and title/author/label gates. `GET /api/contribute/status` reports the offerable total as `actionable_items` and the raw scanner population as `candidate_items`. `GET /api/contribute/queue` returns bounded ordered rows, uncapped `queue_total`, and separate `held_total`. +- The **work queue** includes monitored-repository candidates that pass disabled-repository, hold, cooldown, in-flight, dependency, assignment, and title/author/label gates. `GET /api/contribute/status` reports the offerable total as `actionable_items` and the contributor-workable scanner population as `candidate_items`; umbrella and owner-only issues are counted separately as `umbrella_items` and `human_only_items` and are never offered, and the raw scanner population stays available as `candidate_items_raw` ([#19078](https://github.com/hivecommons/hive/issues/19078)). The contributor page shows "N workable" and one line, "M umbrella and owner-only items are not offered to contributors". `GET /api/contribute/queue` returns bounded ordered rows, uncapped `queue_total`, and separate `held_total`, `umbrella_total` and `human_only_total`. - The **relay** authenticates with its registration token and renews heartbeats every 30 s, reconnecting with exponential backoff. No forward progress for 30 minutes abandons a task; an absolute 4-hour backstop also applies. A task GitHub token lasts 55 minutes and is re-minted before expiry, so the task may outlive one token; see [token renewal](#the-github-token-outlives-the-task-because-the-hub-re-mints-it). - A **trust tier** controls per-tier rate limits; see [trust tiers and delegated roles](contributor-trust-and-roles.md). - Hives advertise small, well-specified issues with `good first issue` and `help wanted` labels and a welcome link (`/contribute?issue=/%23`). A label is not a reservation: claim before starting, sign the PR with DCO, and use `Fixes #n`. See [Hive-curated good first issues](good-first-issue.md). @@ -2295,3 +2297,24 @@ That checklist is design history, not a statement that today's relay lacks deliv ## Custom stylesheets The contributor leaderboard and spoke dashboard accept a shareable custom stylesheet parameter, letting a hive brand its public surfaces from a public GitHub repo. See [Custom stylesheets](custom-stylesheets.md) for the accepted `owner/repo/path.css@ref` form, the server-side sanitizer rules, scoping, and the size cap. + +## Umbrella and owner-only issues are never handed to a relay + +A relay cannot finish an umbrella (its children carry the work) or an issue that waits on a person, and a claim on one wastes a task. The hub therefore refuses both at offer time, drops them from `actionable_items` / `candidate_items`, and counts them as `umbrella_items` / `human_only_items`. Nothing is edited on the issue: it keeps its stage, stays actionable for the owner and the hive in the dashboard, and an umbrella is closable (the owner, the per-repo `parent_autoclose` policy, the tracker-closing sweep). This is deliberately not the `hive/tracking` marker, which blocks every automatic close. + +```yaml +hub: + contribute_umbrella: + enabled: true # default; false restores the old tracker check only + labels: [umbrella, tracker, epic, meta-tracker] + title_prefixes: ["[Tracking]", "[Epic]", "[Umbrella]", "[Tracker]"] + task_list_min: 2 # issue or PR references in a checklist + human_only_labels: [needs-human, human-only] + withdraw_advertisement: true # remove help wanted / good first issue from an umbrella on the next sweep + per_repo: + owner/repo: + labels: [umbrella, program] + withdraw_advertisement: false +``` + +A per-repo field that is left out inherits the hive-wide value. The relay's own empty-queue message can name these counts; that is a relay-side follow-up. diff --git a/src/docs/labels-and-control-signals/reference.md b/src/docs/labels-and-control-signals/reference.md index e76636ea44..cc916a6cfe 100644 --- a/src/docs/labels-and-control-signals/reference.md +++ b/src/docs/labels-and-control-signals/reference.md @@ -543,6 +543,24 @@ Umbrella issue is never a unit of agent work: every automated claim producer (re **Configuration and implementation.** `src/pkg/github/issue_claim_gate.go`, `src/pkg/github/issue_stage_labels.go`, `src/pkg/claims/neverclaim.go` +#### `umbrella` (also `tracker`, `epic`, `meta-tracker`), ``, `human-only` + +**Applies to:** Issues. **Kind:** Hard for contributors; display-only for the hive. + +An umbrella, epic, tracker or decomposed parent is coordination work: its children carry the code. An owner-only issue waits on a person. Neither is ever handed to a contributor relay, listed as workable, or advertised with `help wanted` / `good first issue` ([#19078](https://github.com/hivecommons/hive/issues/19078)). Both stay actionable for the owner and the hive and keep their stage; the dashboard row reads **Umbrella · owner** or **Owner only**. + +An issue is an umbrella when ANY of these holds: a label from `hub.contribute_umbrella.labels` (default `umbrella`, `tracker`, `epic`, `meta-tracker`; case-insensitive, last segment so `kind/epic` counts), the body marker ``, a title opening with one of `title_prefixes` (default `[Tracking]`, `[Epic]`, `[Umbrella]`, `[Tracker]`, after any emoji), a task list with at least `task_list_min` (default 2) issue or PR references (`- [ ] #123`), sub-issues, or the legacy tracker detector. It is owner-only when it carries `needs-human`, `human-only` or `human-only:*` (`human_only_labels`), or the body marker ``. + +**Who applies it:** Human or hive (a label or marker the owner writes; nothing is applied automatically). + +**Checked by:** Contributor selection, the ready-work queue, `GET /api/contribute/status` counts, the good-first-issue sweep and the dashboard tracker row. **When:** Contributor admission, sweep, render. + +**Not the `hive/tracking` marker.** `hive/tracking` issues are never auto-closed by any path. An umbrella is: the owner can close it, it is closable under the per-repo `parent_autoclose` policy (an `epic` label still needs `parent_autoclose: epics_too`, as before) and by the tracker-closing sweep, and closing it removes its stage labels like any other close. + +**Release or override.** Remove the label or marker; or `hub.contribute_umbrella.enabled: false` (hive-wide or under `per_repo.`) to restore the previous tracker check only; `withdraw_advertisement: false` keeps `help wanted` on an umbrella. + +**Configuration and implementation.** `hub.contribute_umbrella` (`src/pkg/config/contribute_umbrella.go`), classifier `src/pkg/gfi/umbrella.go`, offer gate `src/pkg/dashboard/contribute_umbrella.go`, sweep `src/pkg/gfi/gfi.go` + #### `hive-plan`, `hive-design` **Applies to:** Issues. **Kind:** Gate when enabled. diff --git a/src/docs/labels-and-control-signals/stage-labels.md b/src/docs/labels-and-control-signals/stage-labels.md index 9c8080240d..8d179bc544 100644 --- a/src/docs/labels-and-control-signals/stage-labels.md +++ b/src/docs/labels-and-control-signals/stage-labels.md @@ -217,6 +217,8 @@ stateDiagram-v2 s100 --> [*]: merged (labels removed) ``` +**Umbrella and owner-only issues have no stage of their own.** An umbrella or tracker issue (and an issue that waits on a person) keeps whatever stage the engine derives (`010`, `018`, `040`, `045`) and stays actionable for the owner and the hive; it is shown with a derived **Umbrella · owner** or **Owner only** pill and is never handed to a contributor relay (`hub.contribute_umbrella`, [reference](reference.md#umbrella-also-tracker-epic-meta-tracker----hiveumbrella----human-only)). A dedicated `stage/0NN-umbrella` label was considered and not added: a stage is keyed in the engine table, the transition table, the dashboard column and filter vocabulary and every stage-aware harness (the `018` change touched more than fifty files), and the umbrella property is orthogonal to pipeline progress (a decomposed parent is still `010` while it waits on children and `040` while a PR covers it). The pill reads the same rules the contributor gate uses, so nothing can disagree. Because an umbrella is not a tracking archive, it is closable and closing it removes its stage labels like any other close. + #### The regressed marker: when it is set, when it clears The dashboard's `regressed` chip and the `` diff --git a/src/hive.yaml.example b/src/hive.yaml.example index c89075cb6c..229fee51db 100644 --- a/src/hive.yaml.example +++ b/src/hive.yaml.example @@ -1095,6 +1095,20 @@ dashboard: # deny_titles: ["WIP*"] # authors_mode: deny # deny_authors: [dependabot[bot]] +# # Umbrella / tracker / owner-only issues are never handed to a contributor relay +# # (they stay actionable for the owner and the hive, and stay closable). All keys +# # are optional; per_repo fields left out inherit the hive-wide value. +# contribute_umbrella: +# enabled: true +# labels: [umbrella, tracker, epic, meta-tracker] +# title_prefixes: ["[Tracking]", "[Epic]", "[Umbrella]", "[Tracker]"] +# task_list_min: 2 # issue or PR references in a checklist +# human_only_labels: [needs-human, human-only] +# withdraw_advertisement: true # drop help wanted / good first issue from an umbrella on the next sweep +# per_repo: +# owner/repo: +# labels: [umbrella, program] +# withdraw_advertisement: false # contribute_needs_decision_label: needs-decision # label relays apply for no_work_needed — decision: ...; empty disables # # Relay audit level this hive ASKS contributors to share (lifecycle | # # commands | reasoning), shown on auth_ok and /contribute. A request only: diff --git a/src/internal/testutil/dashboard_import_allowlist.txt b/src/internal/testutil/dashboard_import_allowlist.txt index 908416ab14..56f701db7c 100644 --- a/src/internal/testutil/dashboard_import_allowlist.txt +++ b/src/internal/testutil/dashboard_import_allowlist.txt @@ -43,6 +43,7 @@ github.com/hivecommons/hive/pkg/feedbackbundle github.com/hivecommons/hive/pkg/fixqueue github.com/hivecommons/hive/pkg/fleetreport github.com/hivecommons/hive/pkg/forgestate +github.com/hivecommons/hive/pkg/gfi github.com/hivecommons/hive/pkg/github github.com/hivecommons/hive/pkg/governor github.com/hivecommons/hive/pkg/hiveadvisor diff --git a/src/pkg/config/config.go b/src/pkg/config/config.go index 3e2b7b1b54..cf1705ce70 100644 --- a/src/pkg/config/config.go +++ b/src/pkg/config/config.go @@ -5045,6 +5045,10 @@ type HubConfig struct { // ContributeRepoFilters are optional, full owner/name keyed admission // filters layered on top of the hive-wide title/author/label filters. ContributeRepoFilters map[string]ContributeRepoFilter `yaml:"contribute_repo_filters,omitempty" json:"contribute_repo_filters,omitempty"` + // ContributeUmbrella decides which issues are umbrella, tracker or + // owner-only work that a contributor relay is never handed, with a + // per-repo override map (hivecommons/hive#19078). See ContributeUmbrella. + ContributeUmbrella ContributeUmbrella `yaml:"contribute_umbrella,omitempty" json:"contribute_umbrella,omitempty"` // ContributeSkipAssignedToOthers, when true, makes the /contribute queue // skip any issue that is already assigned to someone OTHER than the // contributor requesting work. An issue assigned to the contributor diff --git a/src/pkg/config/contribute_umbrella.go b/src/pkg/config/contribute_umbrella.go new file mode 100644 index 0000000000..1dca76c23d --- /dev/null +++ b/src/pkg/config/contribute_umbrella.go @@ -0,0 +1,97 @@ +package config + +import ( + "strings" + + "github.com/hivecommons/hive/pkg/gfi" +) + +// ContributeUmbrella (hub.contribute_umbrella) decides which issues are +// umbrella / tracker / owner-only work that a contributor relay is never +// handed (hivecommons/hive#19078). Everything is optional: an omitted block +// is the default behaviour (enabled, gfi.DefaultUmbrellaLabels, +// gfi.DefaultUmbrellaTitlePrefixes, gfi.DefaultHumanOnlyLabels, a task list +// of two issue references, advertisement withdrawn). The excluded issues stay +// actionable for the owner and the hive and stay closable: this is NOT the +// `hive/tracking` vocabulary, which no hive path may close. +// +// PerRepo overrides the hive-wide value for one full `owner/name` +// repository; a field a repo leaves unset inherits the hive-wide value. +type ContributeUmbrella struct { + ContributeUmbrellaRepo `yaml:",inline"` + // PerRepo is keyed by full owner/name, matched case-insensitively. + PerRepo map[string]ContributeUmbrellaRepo `yaml:"per_repo,omitempty" json:"per_repo,omitempty"` +} + +// ContributeUmbrellaRepo is the set of knobs both scopes share. +type ContributeUmbrellaRepo struct { + // Enabled is a pointer so an omitted key inherits (nil). False turns the + // classification off for the scope. + Enabled *bool `yaml:"enabled,omitempty" json:"enabled,omitempty"` + // Labels replaces the accepted umbrella label set (default umbrella, + // tracker, epic, meta-tracker). + Labels []string `yaml:"labels,omitempty" json:"labels,omitempty"` + // TitlePrefixes replaces the accepted title prefixes (default [Tracking], + // [Epic], [Umbrella], [Tracker]), compared case-insensitively. + TitlePrefixes []string `yaml:"title_prefixes,omitempty" json:"title_prefixes,omitempty"` + // TaskListMin is how many issue- or PR-referencing checklist entries make + // an umbrella. Zero inherits (default 2). + TaskListMin int `yaml:"task_list_min,omitempty" json:"task_list_min,omitempty"` + // HumanOnlyLabels replaces the accepted owner-only label set (default + // needs-human, human-only; `