Skip to content
Closed
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 CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ Thank you for helping improve Hive. This guide is for contributing code and docu
- Not sure why the hive has not picked up your issue? It automatically works issues only from OWNER, MEMBER, and COLLABORATOR authors; anyone else waits for a maintainer to add `triage/accepted`. See [Reporter trust and escalation](GOVERNANCE.md#reporter-trust-and-escalation) for what those roles mean, [how to become a trusted reporter](GOVERNANCE.md#how-to-become-a-trusted-reporter), and how to escalate.
- Pull requests are welcome too, and nothing above changes how they are reviewed.
- Discuss design and review questions in public issues and pull requests so decisions remain public and searchable.
- A proposal or design question goes in an issue labelled `proposal` (or `kind/design`). Until someone claims it, the hive shows it as **Open for discussion** (`stage/018-open-for-discussion`), not as agent work waiting to be picked up; `/claim` it when you want to take it on, and it moves through the pipeline like any other issue. See [stage labels](src/docs/labels-and-control-signals/stage-labels.md).
- Follow the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/main/code-of-conduct.md), adopted in [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md), and [Hive governance](GOVERNANCE.md).
- Report vulnerabilities privately; see [SECURITY.md](SECURITY.md).
- Extending Hive? Start with the [Integration guide](src/docs/integration-guide.md) for the current work source, ClankeR/Flue-style external execution, and Spektacular Project Inception seams.
Expand Down
1 change: 1 addition & 0 deletions changelog.d/fixed-17150-open-for-discussion.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- An open issue labelled `proposal` or `kind/design` that nobody has claimed now derives the new `stage/018-open-for-discussion` and reads **Open for discussion** in the activity monitor instead of sitting at `stage/010-actionable` as agent work no lane will usefully pick up β€” including a proposal whose `Refs` RFC PR merged and left it `hive/partially-addressed`, a `040 β†’ 018` fall booked as progress, not a regression. The stage reason names the label (`open for discussion: proposal`). The issue stays claimable: the claim gate is unchanged, a `/claim`, relay or agent claim stages it 020 / 030 as before, and removing the label returns it to 010 ([#17150](https://github.com/hivecommons/hive/issues/17150)).
9 changes: 9 additions & 0 deletions src/docs/adr/0025-central-stage-engine.md
Original file line number Diff line number Diff line change
Expand Up @@ -425,6 +425,15 @@ enumerator's filtered-reason) the way it reproduces 045 from `needs-spec`,
and the resume sweep removes it on `/hive decision proceed` / `exists`.
Leaving 017 for 010 or closed is never a regression.

**Open for discussion (`stage/018-open-for-discussion`, #17150).** Added
after the epic: an issue-only stage between 017 and 020 with no dwell.
Unlike 017 it is derived, not written by a gate: `DeriveIssue` returns it
for an open issue labelled `proposal` or `kind/design` with no live claim
(`IssueFacts.DiscussionLabel`, resolved in `pkg/github`), reason
`open for discussion: <label>`. It is not a suppress: the claim gate is
unchanged and a claim stages 020/030. `040 β†’ 018` under
`hive/partially-addressed` is progress; leaving 018 is never a regression.

## Consequences

- A taxonomy change (new stage, renamed stage, new author kind) touches the
Expand Down
1 change: 1 addition & 0 deletions src/docs/dashboard-sections/activity-monitor.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,7 @@ Side stages share a column rather than adding columns:
| Stage | Column / meaning |
| --- | --- |
| 015 Triage needed | Actionable; a human must triage. From `needs-triage` or the reporter-trust `reporter_triage` bucket, never merely the reporter's identity. |
| 018 Open for discussion | Actionable; an unclaimed `proposal` / `kind/design` issue whose remainder is a discussion, not agent work. The caption names the label (*Open for discussion (proposal); no agent work is queued β€” claim it to take it on*); a claim moves it to Claimed as usual ([#17150](https://github.com/hivecommons/hive/issues/17150)). |
| 045 Needs human decision | Actionable on an issue. A pre-045 issue still wearing 085 is drawn here until reconciliation. |
| 070 Fixing / 071 Needs author / 072 Returned to contributor | CI / Review: Hive repairs its own PR at 070; a human author acts at 071; a contributor agent gets its PR back at 072. `needs-rebase` explains a repair here, not at 050. |
| 074 Adopted by hive | CI / Review while the Hive repairs adopted work; pending, green or red pushes remain 074 until the merge gate takes it. |
Expand Down
2 changes: 2 additions & 0 deletions src/docs/governor-thresholds.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

The governor picks a mode β€” **idle β†’ quiet β†’ busy β†’ surge** β€” by comparing queue depth (actionable issues + open PRs, summed across every repo the hive watches) against three thresholds. The mode then selects each agent's kick cadence, so the thresholds are what decide how hard the hive works.

Queue depth counts the enumerated work queue, not stage labels: an issue at `stage/018-open-for-discussion` (an unclaimed `proposal` / `kind/design` issue, [#17150](https://github.com/hivecommons/hive/issues/17150)) is still an open, claimable issue and still counts toward the actionable issue depth, exactly as it did when it read `stage/010-actionable`. The stage only changes how the activity monitor labels it.

## The problem the scaling solves

Queue depth scales with how many repos a hive watches; the thresholds did not. A fixed `surge: 20` therefore encoded an implicit repo count:
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 @@ -93,8 +93,9 @@ referenced it) a lone `stage/050-review-pending`
| Label | Applies to | Meaning | Expected dwell (then `stage/stalled`) |
|---|---|---|---|
| `stage/010-actionable` | issue | triaged; eligible for the hive to pick up. A human-filed issue without `needs-triage` counts as triaged by its trusted reporter | 24h |
| `stage/015-triage-needed` | issue | actionable, but no maintainer has looked at it yet. Derived instead of 010 only when the reporter-trust gate is holding the issue: it carries the awaiting label `needs-triage` (`reporter_trust.awaiting_label` default) or sits in the #9665 gate's `reporter_triage` bucket. Who filed it is never consulted β€” issues from hive agents and from trusted humans are triaged by construction and stay 010. A **display and tracking state, not a gate**: the scanner and relay claim a 015 issue exactly as a 010 one (the reporter-trust gate withholds `needs-triage` issues separately, and that is unchanged), and 015 lights the activity monitor's *Actionable* column as "Triage needed". `015 β†’ 010` (a maintainer triages) is never a regression; `010 β†’ 015` is a reclassification. Because 015 is not a gate, a claim settles triage: whenever the sweep (or an out-of-cycle claim fact) writes a stage of 020 or later β€” 020, 030, 040 or a PR-mirrored stage β€” it removes `needs-triage` in the same label write, and an open issue already at 020+ still wearing it is reconciled on the next sweep; the label survives at 010, 017 and 045, which the table lets fall back to 015 (hivecommons/hive#14586). The Open column is untouched: an issue with no stage stays "Open" | 24h |
| `stage/015-triage-needed` | issue | actionable, but no maintainer has looked at it yet. Derived instead of 010 only when the reporter-trust gate is holding the issue: it carries the awaiting label `needs-triage` (`reporter_trust.awaiting_label` default) or sits in the #9665 gate's `reporter_triage` bucket. Who filed it is never consulted β€” issues from hive agents and from trusted humans are triaged by construction and stay 010. A **display and tracking state, not a gate**: the scanner and relay claim a 015 issue exactly as a 010 one (the reporter-trust gate withholds `needs-triage` issues separately, and that is unchanged), and 015 lights the activity monitor's *Actionable* column as "Triage needed". `015 β†’ 010` (a maintainer triages) is never a regression; `010 β†’ 015` is a reclassification. Because 015 is not a gate, a claim settles triage: whenever the sweep (or an out-of-cycle claim fact) writes a stage of 020 or later β€” 020, 030, 040 or a PR-mirrored stage β€” it removes `needs-triage` in the same label write, and an open issue already at 020+ still wearing it is reconciled on the next sweep; the label survives at 010, 017, 018 and 045, which the table lets fall back to 015 (hivecommons/hive#14586). The Open column is untouched: an issue with no stage stays "Open" | 24h |
| `stage/017-possible-existing` | issue | **Possibly exists Β· needs author.** The prior-art gate found something that looks like the request already (knowledge bead, setting, merged PR, closed issue, doc or code) and parked the issue with the findings; the author confirms the gap (`/hive decision proceed β€” <gap>`) or closes it (`/hive decision exists`, label `already-exists`). The label itself is the park signal and an issue-level hard suppress, so no agent claims it; clanker-filed parks auto-close after `runs.triage.prior_art.bot_close_ttl`; hive-filed issues never wear it ([#13575](https://github.com/hivecommons/hive/issues/13575)) | none |
| `stage/018-open-for-discussion` | issue | **Open for discussion.** An open issue labelled `proposal` or `kind/design` with no live claim: what is left on it is a discussion, not agent work, so it is derived here instead of 010 / 015 and the activity monitor's *Actionable* column reads "Open for discussion", the caption naming the label. The stage reason is `open for discussion: <label>`. **Not a gate**: the claim gate does not refuse these labels, so a person's `/claim`, the contribute relay or an agent claim stages it 020 / 030 as on any issue; parks, holds, `blocked` and a covering PR outrank it as they do 010. Removing the label returns the issue to plain 010 derivation (never a regression), and a covering `Refs #N` PR that merges and leaves `hive/partially-addressed` lands it back here as progress ([#17150](https://github.com/hivecommons/hive/issues/17150)) | none |
| `stage/020-claimed` | issue | a live claim by anyone β€” a human, a relay contributor or a hive agent's `hive-open-issue claim` / start mark β€” with no PR evidence yet (replaces `claimed`, `hive/in-progress`) | 2h |
| `stage/030-pr-in-progress` | issue | the claimant has a PR under way: its `hive-open-pr --issues` request named the issue or its start marker named a branch / PR (`pr_started=true` on the `hive:claim` marker). A claim or start mark without that evidence β€” the scanner's bare `hive-open-issue claim` included β€” stays at 020 ([#13069](https://github.com/hivecommons/hive/issues/13069)). If the in-progress evidence includes an open Hive-authored PR, the issue-stage lane applies the same PR-link safeguard described for 040: default-branch PRs that fully address the issue get a `Fixes #N` trailer when missing, while partial or non-default-branch PRs get an issue stage-entry comment linking the PR and explaining GitHub's icon limitation. If the claiming PR has already merged, the issue leaves 030: full-fix claims close it with one `<!-- hive:closed-by-merged-pr pr=N -->` comment (checked before posting, so a close that fails after the comment is retried without a duplicate), while `Refs` / `Part of` claims move back to 010 with a partial-landed note. | 90m |
| `stage/040-covered-by-pr` | issue | an open PR covers it (replaces `🐝 covered by PR`), or β€” when the hive's PR only *references* the issue without a closing keyword (`Refs #N`) β€” "an open PR addresses part of it": the issue is still parked here but its stage reason and tracker caption say the remainder stays open when the PR merges ([#15008](https://github.com/hivecommons/hive/issues/15008)). Coverage is derived only from a closing reference in the PR body or commits, a hive claim-ledger entry, or an explicit hive marker β€” a bare cross-reference (an incident deferral comment, `see also`, a backlog link) never puts an issue here; the issue stays here while the PR is open β€” the PR's own stage is named in the issue's stage reason, never written as its label ([#12451](https://github.com/hivecommons/hive/issues/12451)). For Hive-authored PRs on the repository default branch, the stage and claim-label sweeps append `Fixes #N` to the PR body when the PR appears to fully address the issue but lacks a closing keyword, so GitHub can show the Development sidebar link and issue-list PR icon. They also retrofit older Hive-authored default-branch PRs whose only claim line is `Refs #N` by rewriting that one keyword to `Fixes #N` once and stamping `<!-- hive:issue-link-fixed -->`; human-authored PR bodies are never edited. `Part of` / leave-open partial work and non-default-branch PRs get one issue stage-entry comment with the PR link and GitHub limitation instead. Merged full-fix claims close the issue; merged reference claims remove stale 040/030 and return the issue to 010 with a partial-landed note. | n/a (the PR carries health) |
Expand All @@ -121,8 +122,10 @@ stateDiagram-v2
direction LR
[*] --> s010: issue triaged
[*] --> s015: issue from an untrusted reporter (needs-triage / reporter_triage)
[*] --> s018: proposal / kind/design issue with no live claim
s010: 010 actionable
s015: 015 triage-needed
s018: 018 open-for-discussion
s020: 020 claimed
s030: 030 pr-in-progress
s040: 040 covered-by-pr
Expand All @@ -144,6 +147,14 @@ stateDiagram-v2
s015 --> s010: maintainer triages: triage/accepted, hive/verified-open or approved-direction added, or needs-triage removed (not a regression)
s015 --> s020: scanner / relay claim (015 is not a gate; needs-triage removed in the same write)
s015 --> s045: needs-human / park label (agent escalates)
s010 --> s018: proposal / kind/design label added to an unclaimed issue (reclassification)
s018 --> s010: proposal / kind/design label removed (not a regression)
s018 --> s020: a person, relay contributor or agent claims it (018 is not a gate)
s018 --> s045: needs-human / park label
s045 --> s018: /hive approve or /hive decision on a proposal
s020 --> s018: claim released or lapsed with no PR on a proposal (not a regression)
s030 --> s018: PR request failed / start mark lapsed with no PR on a proposal
s040 --> s018: covering PR merged with Refs (hive/partially-addressed; progress, not a regression) or closed unmerged on a proposal
s020 --> s045: claim lapses on a parked issue
s045 --> s010: eligible /hive approve or /hive decision (ordinary un-park; needs-human lifts for every applier; hold remains)
s045 --> s015: park label removed by hand on an untriaged issue (approved-direction itself counts as triage, so /hive approve lands on 010)
Expand Down
16 changes: 16 additions & 0 deletions src/docs/stage-engine-plan.md
Original file line number Diff line number Diff line change
Expand Up @@ -270,6 +270,22 @@ Shipped as three PRs (hivecommons/hive#13011):
`040 β†’ 020` (covering PR closed with nothing / a start marker / the claim
still live) and `030 β†’ 020` (PR evidence lapsed, claim held).

- **018 open for discussion** ([#17150](https://github.com/hivecommons/hive/issues/17150)):
an open issue labelled `proposal` or `kind/design` with no live claim
derives `stage/018-open-for-discussion` instead of 010 / 015.
`pkg/github` resolves the label into `IssueFacts.DiscussionLabel`; the
deriver applies it wherever the issue would otherwise sit unclaimed (the
actionable / reporter-triage buckets, and an umbrella whose claim is not
staged), and names the label in the reason (`open for discussion:
proposal`). Claims, PR coverage, parks, holds and `blocked` are
unchanged, and the claim gate does not refuse the labels, so a claim
still stages 020 / 030. `issueProgress` books `040 β†’ 018` under
`hive/partially-addressed` as progress (a `Refs` RFC PR merged, the
discussion remains), and leaving 018 is never a regression. The diagram
and `transition_table.go` gained `010 ↔ 018`, `018 β†’ 020`, `018 ↔ 045`,
`020 β†’ 018`, `030 β†’ 018` and `040 β†’ 018`. The stage engine reads labels
only, never titles: a πŸ“ RFC without either label stays 010.

## Tracking

Tracking issue: [#12999](https://github.com/hivecommons/hive/issues/12999) *Central stage engine (ADR-0025)* β€” one checkbox per PR
Expand Down
8 changes: 7 additions & 1 deletion src/pkg/dashboard/stage_tracker.go
Original file line number Diff line number Diff line change
Expand Up @@ -931,7 +931,11 @@ const (
// lights the Actionable column with the word "Possibly exists" and
// waits on its author (hivecommons/hive#13575).
trackerNumberPossiblyExists = 17
stageTrackerHistoryMaxItems = stagelabels.HistoryLimit
// trackerNumberOpenForDiscussion is the unclaimed proposal / design
// issue (018): it lights the Actionable column with the words "Open for
// discussion" β€” no agent work is queued on it (hivecommons/hive#17150).
trackerNumberOpenForDiscussion = 18
stageTrackerHistoryMaxItems = stagelabels.HistoryLimit
)

// Modifier names (also the CSS hooks in index.html).
Expand Down Expand Up @@ -1025,6 +1029,8 @@ func stageTrackerShort(s stagelabels.Stage) string {
return "Triage needed"
case stagelabels.PossiblyExisting:
return "Possibly exists"
case stagelabels.OpenForDiscussion:
return "Open for discussion"
case stagelabels.Claimed:
return "Claimed"
case stagelabels.PRInProgress:
Expand Down
2 changes: 1 addition & 1 deletion src/pkg/dashboard/stage_tracker_activity.test.js
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ const STAGE_TRACKER_PATH = [0, 10, 20, 30, 50, 80];
const STAGE_TRACKER_TERMINAL = 110;
const STAGE_TRACKER_PR_COLUMN = 30, STAGE_TRACKER_MERGE_COLUMN = 80;
const STAGE_TRACKER_NEEDS_DECISION = 85, STAGE_TRACKER_ISSUE_NEEDS_DECISION = 45;
const STAGE_TRACKER_ISSUE_DECISION_COLUMN = 10, STAGE_TRACKER_TRIAGE_NEEDED = 15, STAGE_TRACKER_POSSIBLY_EXISTS = 17;
const STAGE_TRACKER_ISSUE_DECISION_COLUMN = 10, STAGE_TRACKER_TRIAGE_NEEDED = 15, STAGE_TRACKER_POSSIBLY_EXISTS = 17, STAGE_TRACKER_OPEN_FOR_DISCUSSION = 18;
const STAGE_TRACKER_PRE_MERGE_SOAK = 95;
`;
function constLine(source, name) {
Expand Down
4 changes: 4 additions & 0 deletions src/pkg/dashboard/stage_tracker_actor.go
Original file line number Diff line number Diff line change
Expand Up @@ -189,6 +189,8 @@ func stageTrackerStageActorOf(it StageTrackerItem, workers map[string]stageTrack
k = StageActorHuman
}
return set(k, it.Author, "prior art found β€” the author must confirm the gap or close it")
case stagelabels.OpenForDiscussion:
return set(StageActorHuman, "", "open for discussion β€” no agent work is queued; anyone may claim it")
case stagelabels.Claimed:
switch it.ClaimantKind {
case authorKindHive, authorKindClanker, authorKindHuman:
Expand Down Expand Up @@ -280,6 +282,8 @@ func stageTrackerHumanAsk(stage stagelabels.Stage) string {
return "needs triage"
case stagelabels.PossiblyExisting:
return "author confirms the gap"
case stagelabels.OpenForDiscussion:
return "open for discussion"
case stagelabels.Claimed:
return "a person holds the claim"
case stagelabels.Fixing, stagelabels.NeedsAuthor, stagelabels.ReturnedToContributor:
Expand Down
1 change: 1 addition & 0 deletions src/pkg/dashboard/stage_tracker_adopted_column.test.js
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@ const src = [
pick(/const STAGE_TRACKER_ISSUE_DECISION_COLUMN = \d+;/, 'STAGE_TRACKER_ISSUE_DECISION_COLUMN'),
pick(/const STAGE_TRACKER_TRIAGE_NEEDED = \d+;/, 'STAGE_TRACKER_TRIAGE_NEEDED'),
pick(/const STAGE_TRACKER_POSSIBLY_EXISTS = \d+;/, 'STAGE_TRACKER_POSSIBLY_EXISTS'),
pick(/const STAGE_TRACKER_OPEN_FOR_DISCUSSION = \d+;/, 'STAGE_TRACKER_OPEN_FOR_DISCUSSION'),
pick(/const STAGE_TRACKER_PRE_MERGE_SOAK = \d+;/, 'STAGE_TRACKER_PRE_MERGE_SOAK'),
pick(/const STAGE_TRACKER_TERMINAL = \d+;/, 'STAGE_TRACKER_TERMINAL'),
pick(/const STAGE_TRACKER_ADOPTED_BY_HIVE = \d+;/, 'STAGE_TRACKER_ADOPTED_BY_HIVE'),
Expand Down
1 change: 1 addition & 0 deletions src/pkg/dashboard/stage_tracker_advisory_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -196,6 +196,7 @@ func TestStageTrackerAdvisoryChipAndAction(t *testing.T) {
jsConstLine(t, html, "STAGE_TRACKER_ISSUE_DECISION_COLUMN"),
jsConstLine(t, html, "STAGE_TRACKER_TRIAGE_NEEDED"),
jsConstLine(t, html, "STAGE_TRACKER_POSSIBLY_EXISTS"),
jsConstLine(t, html, "STAGE_TRACKER_OPEN_FOR_DISCUSSION"),
jsConstLine(t, html, "STAGE_TRACKER_PRE_MERGE_SOAK"),
jsConstLine(t, html, "STAGE_TRACKER_ACTIVE_WORD"),
jsConstLine(t, html, "STAGE_TRACKER_ACTOR"),
Expand Down
1 change: 1 addition & 0 deletions src/pkg/dashboard/stage_tracker_attention_order_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -108,6 +108,7 @@ func TestStageTrackerAttentionOrderJS(t *testing.T) {
jsConstLine(t, html, "STAGE_TRACKER_ISSUE_DECISION_COLUMN"),
jsConstLine(t, html, "STAGE_TRACKER_TRIAGE_NEEDED"),
jsConstLine(t, html, "STAGE_TRACKER_POSSIBLY_EXISTS"),
jsConstLine(t, html, "STAGE_TRACKER_OPEN_FOR_DISCUSSION"),
jsConstLine(t, html, "STAGE_TRACKER_PRE_MERGE_SOAK"),
jsConstLine(t, html, "STAGE_TRACKER_HUMAN_MODS"),
stageTrackerTierJS(t, html),
Expand Down
Loading
Loading