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/added-19078-contributor-umbrella-exclusion.md
Original file line number Diff line number Diff line change
@@ -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 `<!-- hive:umbrella -->` 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 `<!-- hive:human-only -->`. `/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)).
16 changes: 14 additions & 2 deletions dashboard/openapi.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand All @@ -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"
Expand Down
7 changes: 7 additions & 0 deletions src/cmd/hive/gfi_wire.go
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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
}
Expand Down
8 changes: 8 additions & 0 deletions src/docs/agent-configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<!-- hive:umbrella -->`, 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 `<!-- hive:human-only -->`. 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:<rule>` / `human-only:<rule>` 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`)
Expand Down
25 changes: 24 additions & 1 deletion src/docs/contributor-relay.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<!-- hive:umbrella -->` 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 `<!-- hive:human-only -->` 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. | — |
Expand Down Expand Up @@ -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=<owner>/<repo>%23<n>`). 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).
Expand Down Expand Up @@ -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.
18 changes: 18 additions & 0 deletions src/docs/labels-and-control-signals/reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`), `<!-- hive:umbrella -->`, `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 `<!-- hive:umbrella -->`, 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 `<!-- hive:human-only -->`.

**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.<owner/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.
Expand Down
2 changes: 2 additions & 0 deletions src/docs/labels-and-control-signals/stage-labels.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<!-- hive:stage-regressed -->`
Expand Down
14 changes: 14 additions & 0 deletions src/hive.yaml.example
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
1 change: 1 addition & 0 deletions src/internal/testutil/dashboard_import_allowlist.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 4 additions & 0 deletions src/pkg/config/config.go
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading
Loading