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/fixed-18889-no-decision-on-midflight-head.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Stop offering Decide…, Approve as-is and Let hive decide on a PR whose CI is running or whose review is incomplete on its current head (#18889): the verbs stay on the row, disabled, with the reason (`mid_flight`: *CI running 2/5*, *review queued on abc1234*), and a park from an earlier head no longer counts after a push; `Let hive decide — all N PRs` skips the PRs still in flight; the server answers `no-effect` before any decider runs and the policy's `default-release` / `small-low-risk` now require CI that is not pending; and the row says why a PR with no linked issue is parked (`contributor-lane:no-linked-issue`) instead of a bare *decision*.
12 changes: 12 additions & 0 deletions src/docs/api-reference/dashboard-misc.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,18 @@ filters or routing. Consumers must not turn either display field into a gate.
The monitor renders CI and Review concurrently on one shared PR row; see
[Reading the tracks](../streaming-the-activity-monitor.md#reading-the-tracks).

Every open PR row (and each `linked_prs[]` entry) whose CURRENT head is still being
checked also carries `mid_flight`: `{kind, text, head?, park?}`, `kind` one of
`ci-running`, `review-in-progress`, `head-moved` (the CI / review on file belong to
an earlier head). While it is set the decision options that rest on the head
(`decide:delegate`, `decide:approve`, `decide:direction`) arrive in
`decision_needed.options` with `enabled: false` and the reason, the SPA draws
*Decide…*, *Approve as-is* and *Let hive decide* disabled, and
`POST …/decide-delegated` answers `no-effect` (rule `mid-flight`, nothing
written, `force` does not lift it). `park` is the plain reason the hive parked the
PR when a person was asked for a decision. The field is absent on a PR whose CI and
review are settled.

| Method | Path | Auth | Purpose | Source |
|---|---|---|---|---|
| `GET` | `/api/audit` | Read-write role | Audit Log — `{"entries": [...]}` envelope, newest first, capped at 200; response shape and the serve-time `user_name` field in [audit-log.md](../audit-log.md#get-apiaudit) | `pkg/dashboard/api.go:63` |
Expand Down
2 changes: 1 addition & 1 deletion src/docs/api-reference/packs-and-acmm.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f
| `GET` | `/api/notes` | Signed-in GitHub user (or verified owner) | Maintainer notes — the private per-item notes maintainers leave each other on Activity Monitor rows ([#maintainer-notes](../operator-reference.md#maintainer-notes)). `?repo=owner/name&number=N` lists one item's live notes oldest first; with no query, every live note in the hive (the SPA's count badges). `{notes: [{id, repo, number, author, text, created_at}]}`. Never read from or written to GitHub. | `pkg/dashboard/api.go:336`, `pkg/dashboard/api_maintainer_notes.go` |
| `POST` | `/api/notes` | Owner or repo write/maintain/admin, signed-in GitHub user | Append a maintainer note. Body `{repo, number, text}` — `text` is plain text up to 2000 characters; the author is the dashboard session's GitHub login, never a body field. `401` signed out, `403` without write on the repo, `400` for an empty/oversized note or a bad item. `201 {ok, note}`; appended to `/data/maintainer-notes.jsonl`, audited as `maintainer_note_add`, and broadcast as the `maintainer-notes` SSE event `{seq, repo, number, count, action}` so other maintainers' browsers refresh the row. | `pkg/dashboard/api.go:337`, `pkg/dashboard/api_maintainer_notes.go` |
| `DELETE` | `/api/notes/{id}` | The note's author, or a verified owner | Tombstone a maintainer note (append-only store: a `deleted_at` record, never a rewrite). `404` unknown or already deleted, `403` for anyone else. `{ok, note}`; audited as `maintainer_note_delete`, broadcast as `maintainer-notes`. | `pkg/dashboard/api.go:338`, `pkg/dashboard/api_maintainer_notes.go` |
| `POST` / `GET` | `/api/repos/{owner}/{repo}/items/{number}/decide-delegated` | Same as `…/hold` (owner or repo write), signed-in GitHub user; `decisions.delegate.enabled` (403 when off) | *Let hive decide*: enqueue a delegated-decision job in which the hive decides the parked item itself as the owner's delegate under `pkg/delegatedecision.PolicyText` and records it as a human decision (`/hive decision` comment with the `<!-- hive:delegated-decision … -->` marker, park labels off, `triage/accepted`, queue approval on a PR head). Body `{"type": "issue"|"pr", "reason", "caption", "sentinel_reason"}`. `POST` answers 202 with the job (`{id, status: "running"|"done"|"failed", decision: {verdict, rule, text, rationale, actions, keeps_park, ladder?: {decision, reason, ruled_out[]}}, notes, error}`; `ladder` is set on contributor-PR decisions and names the rung that decided — `already-fixed` → `mergeable-as-is` → `rebase-then-merge` → `return-to-contributor` → `contributor-offline` — and why each rung above it did not apply); 409 with the running job while one is in flight; `GET` reads it. Rails: never merges, refuses items wearing `hold`, never grants secrets/permissions (`needs-owner` + `hold` instead), recommends only on hive policy/governance questions (keeps 085). Audited as `repo_item_decision_delegated[_failed]`. See [dashboard-sections.md](../dashboard-sections.md#let-hive-decide). | `pkg/dashboard/api.go:329`, `pkg/dashboard/api_repo_item_decide_delegated.go` |
| `POST` / `GET` | `/api/repos/{owner}/{repo}/items/{number}/decide-delegated` | Same as `…/hold` (owner or repo write), signed-in GitHub user; `decisions.delegate.enabled` (403 when off) | *Let hive decide*: enqueue a delegated-decision job in which the hive decides the parked item itself as the owner's delegate under `pkg/delegatedecision.PolicyText` and records it as a human decision (`/hive decision` comment with the `<!-- hive:delegated-decision … -->` marker, park labels off, `triage/accepted`, queue approval on a PR head). Body `{"type": "issue"|"pr", "reason", "caption", "sentinel_reason"}`. `POST` answers 202 with the job (`{id, status: "running"|"done"|"failed", decision: {verdict, rule, text, rationale, actions, keeps_park, ladder?: {decision, reason, ruled_out[]}}, notes, error}`; `ladder` is set on contributor-PR decisions and names the rung that decided — `already-fixed` → `mergeable-as-is` → `rebase-then-merge` → `return-to-contributor` → `contributor-offline` — and why each rung above it did not apply); 409 with the running job while one is in flight; `GET` reads it. Rails: never merges, refuses items wearing `hold`, never grants secrets/permissions (`needs-owner` + `hold` instead), recommends only on hive policy/governance questions (keeps 085), and never decides a PR whose CI is running or whose review is incomplete on the current head — it answers `no-effect` (rule `mid-flight`, nothing written; fails closed, "review state not yet loaded", when the PR's review state cannot be read from the tracker; per PR in the `prs` fan-out, where the PR is skipped and counted as such), and the policy itself never releases (`default-release`, `small-low-risk`) a head whose checks are pending (rule `ci-pending`). Audited as `repo_item_decision_delegated[_failed]`. See [dashboard-sections.md](../dashboard-sections.md#let-hive-decide). | `pkg/dashboard/api.go:329`, `pkg/dashboard/api_repo_item_decide_delegated.go` |
| `POST` | `/api/repos/{owner}/{repo}/items/{number}/decide-delegated/plan` | Same as `…/decide-delegated` | Preview for *Let hive decide*: runs the same owner-delegate policy with **no side effects** (nothing written, no job) and answers `{would, rule, acting, title, summary, why, consequences[], ladder, mergeable_as_is, alternatives[], writes: false, prior, notes}` — `summary` is one verb-first sentence with no "Hive would:" prefix (*Send #15332 back to its author with one instruction: make CI green, nothing else.*), `why` one short line (*CI is red.*), `consequences` at most two items, `ladder` the rung that decided with its `ruled_out` list, and `mergeable_as_is` whether an as-is merge is honest (the queue-merge and merge-now alternatives are dropped when it is not). The dialog shows **Cancel** / **Let hive do that**, plus **Approve and let hive merge** (or **Merge now as maintainer** when the hive would approve anyway) only when `mergeable_as_is`; only then does the SPA post `…/decide-delegated` with `chosen` naming the button. A transient GitHub failure (5xx, rate limit, timeout) is retried twice with backoff before the plan gives up. A failure answers `{ok: false, error, reason, retryable, attempts, elapsed_ms, hive, hint}` under **409** when the item is no longer open (`reason: not-open`) or **424** when a read it depends on failed (`github`), is not configured (`config`) or the plan itself failed (`plan`) — never 502/503, which the hosted Ingress intercepts and replaces with its generic *hive unavailable* page (hivecommons/hive#16776). See [dashboard-sections.md](../dashboard-sections.md#let-hive-decide). | `pkg/dashboard/api.go:341`, `pkg/dashboard/api_repo_item_decide_delegated_plan.go` |
| `POST` | `/api/repos/{owner}/{repo}/items/{number}/blocker/recheck` | Same as `…/hold` (owner or repo write), signed-in GitHub user | *Re-check permissions* on an issue parked on a capability blocker (#15099): probes the GitHub App installation's permissions; when the missing permission is granted, clears every ledger entry blocked on it and un-parks the item (`{result: {outcome: "released", …}}`), otherwise `{result: {outcome: "no-effect", reason: "blocker", options: [...]}}`; 404 when the item has no blocker, 409 when the blocker is not a capability gap | `pkg/dashboard/api.go:342` |
| `POST` | `/api/repos/{owner}/{repo}/items/{number}/blocker/close-partial` | Same as `…/hold` (owner or repo write), signed-in GitHub user | Option (c) on a capability blocker (#15099): labels the issue `hive/partially-addressed`, posts the operator's `{"comment"}` naming what remains and closes it; the ledger entry is cleared | `pkg/dashboard/api.go:343` |
Expand Down
10 changes: 7 additions & 3 deletions src/docs/dashboard-sections/activity-monitor.md
Original file line number Diff line number Diff line change
Expand Up @@ -276,6 +276,10 @@ Every verb runs `runRowAction` — the row menu's own path: the in-app confirm o

When no decision is pending the row names what it actually waits on (`human_gate.waiting_on`), the first that applies: a merge conflict with the base; the author's turn; required checks failing (named); required checks **stuck** (named); required checks not reported (named); CI running (*n/m*); the review re-run on the new head; the merge queue. A required check that has been queued or in progress longer than `HIVE_TRACKER_CHECK_STUCK_AFTER` (default two hours — well past the slowest pipeline) is **stuck**, not running: the CI track reads *CI 67/69 · 'PR Type', 'PR Issue' stuck* (*13 running · 2 stuck (…)* while other checks still move), its hover says nothing finishes a stuck check on its own, and when every pending check is stuck the track stops pulsing. A verb clicked from a stale view — the row re-rendered between the paint and the click — answers *nothing to act on — #N is waiting on required checks stuck: PR Type, PR Issue* and the tracker re-reads the server at once so the row drops the verb.

**No decision on a head that is still being checked** ([#18889](https://github.com/hivecommons/hive/issues/18889)). A decision is a call on the head as it stands, so while the **current** head's CI is running (queued, running, or required checks not yet reported), its review is queued or in progress, or the CI / review on file belong to an earlier head (a push restarted both), the row carries `mid_flight` (`{kind, text, head, park?}`; `kind` is `ci-running`, `review-in-progress` or `head-moved`). Then **Decide…**, **Approve as-is**, **Let hive decide** and *Give direction…* stay on the pill and the menu but are **disabled with the reason** (*Waiting on CI running 2/5: the decision opens when CI and review finish on the current head*), and the pill says it in words (*waiting on CI running 2/5*). A park recorded for an earlier head does not count: the old park's pill stays, nothing on it is live until the new head has been checked. *Release hold*, *Confirm safe* and the close options are unaffected (a person may always close a PR). Checks stuck far past a normal run do not hold the row (they will not finish on their own, and the person may have to act). `park` is, when a person was asked for a decision, the plain reason the hive parked the PR (*it links no issue, so the hive cannot tell which claim it fulfils and does not trust its author yet*), so the row says why it is parked at all instead of a bare *decision*.

**Why a PR with no linked issue reads "Needs human · decision".** `needs-decision` on a PR has three sources: the 085 stage itself (the lane parked it; its reason is the lane reason, e.g. `contributor-lane:no-linked-issue`, a trust-family reason for a contributor PR whose claim the hive cannot match to an issue); the `pr-needs-decision` label; and, for a 085 PR whose chevron is its real stage (CI / Review) because its head is not merge-ready yet, the pill the tracker adds back so the ask stays visible (`stageTrackerApplyPersonActsOnPRPill`, [#17453](https://github.com/hivecommons/hive/issues/17453)). None of them looks at the Prow label path: a repo without Prow gets the same park. The ask is real, but it cannot be answered until CI and review finish, which is what `mid_flight` now says on the row.

A **secondary row of a shared PR** — an issue drawn under another listed issue's row because one PR closes both ([#17333](https://github.com/hivecommons/hive/issues/17333)) — never renders a gate pill or an amber chevron of its own; its *decision pending on #N* chip is a link that scrolls to and focuses the row that carries the gate.

#### Unauthorized pill
Expand Down Expand Up @@ -746,7 +750,7 @@ The item leaves 085/045 and proceeds without the owner. The action is audited as

Permission is the same as **Hold**: owner, or a signed-in user with repository write access. The recorded decision names the requesting user as the person who delegated it.

**Multiple PRs.** An issue with two or more open nested PRs offers **Let hive decide — all N PRs**. It never silently chooses one ([#15009](https://github.com/hivecommons/hive/issues/15009)). Each PR has its own job and result toast; the issue toast summarizes them. For example: “Decided each of the 2 nested pull requests: #15017 approved (small low risk); #15020 no change (already decided).” The next-step summary can read “2 sent · 1 decided · 1 no-op. Each PR's own toast says what happens next.” The aggregate fails only if every PR failed. With one nested PR or none, the issue's own decision path is unchanged.
**Multiple PRs.** An issue with two or more open nested PRs offers **Let hive decide — all N PRs**. It never silently chooses one ([#15009](https://github.com/hivecommons/hive/issues/15009)). Each PR has its own job and result toast; the issue toast summarizes them. For example: “Decided each of the 2 nested pull requests: #15017 approved (small low risk); #15020 no change (already decided).” The next-step summary can read “2 sent · 1 decided · 1 no-op. Each PR's own toast says what happens next.” A PR whose CI is running or whose review is incomplete on its current head is skipped, not decided ([#18889](https://github.com/hivecommons/hive/issues/18889)): it gets its own `no-effect` result (rule `mid-flight`, nothing written) and the issue toast words it “#15020 skipped (CI running 1/4)” and adds “· 1 skipped (CI or review still running)” to the summary; the button itself says “skips N still running”, and is disabled with the reasons when every PR is in flight. The aggregate fails only if every PR failed. With one nested PR or none, the issue's own decision path is unchanged.

**Request/response reference.**

Expand Down Expand Up @@ -780,7 +784,7 @@ The rules live in one place — `src/pkg/delegatedecision/policy.go` (`PolicyTex
| a hive-filed proposal **without** such evidence | `proposal-not-now` (verdict `not-now`) | Declined for now: a comment saying "no incident or recurrence justifies the cost yet; re-propose with evidence", then closed as not planned (the established declined-proposal path). Never applied to a person's proposal (those keep `default-approve`), never to the hive's own policy (`hive-policy` stays recommend-only). |
| a change to the hive's own policy (for example an RFC to hold unacknowledged hive-filed proposals) | `hive-policy` (recommend-only) | Unchanged in shape, but the recommendation is a real sentence in the owner's terms — "approve `<title>` as proposed — proposals nobody has acknowledged should not be actionable; make it default-on for the lanes it names rather than opt-in; owner to confirm" — never "no special rule applies". |

Each decision names the rule that fired (`dedupe`, `owner-only`, `flaky-test`, `ci-ratchet`, `design-proposal`, `review-backlog`, `selfreport-operator-action`, `proposal-approve-evidence`, `proposal-not-now`, `default-approve`, `prefer-contributor`, `contributor-offline`, `sentinel-trusted`, `small-low-risk`, `reporter-trust`, `fix-then-merge`, `default-release`, `hive-policy`, `sentinel-untrusted`, `rail-hold`, `one-pr-per-issue`) in the comment and in the job's `decision.rule`.
Each decision names the rule that fired (`dedupe`, `owner-only`, `flaky-test`, `ci-ratchet`, `design-proposal`, `review-backlog`, `selfreport-operator-action`, `proposal-approve-evidence`, `proposal-not-now`, `default-approve`, `prefer-contributor`, `contributor-offline`, `sentinel-trusted`, `small-low-risk`, `reporter-trust`, `fix-then-merge`, `default-release`, `hive-policy`, `sentinel-untrusted`, `rail-hold`, `one-pr-per-issue`, `ci-pending`, `mid-flight`) in the comment and in the job's `decision.rule`.

**Safety rails** (`ApplyRails`, applied after the policy and before anything is written): the delegate never merges a PR — it only records the approval the auto-merge engine already acts on per repository settings (a merger/owner requester's approval is written as the queue line the sweep parses; anyone else's as `/lgtm` + `/approve` comments attributed to them); it does not touch an item wearing `hold` (refused, nothing written — release the hold first if you want it decided); it never grants org membership, secrets or permissions (those items get `needs-owner` + `hold` and the one owner-action comment, and keep their park); and a question that is a policy or scope change to the hive itself (settings, governance docs, security posture — the `governance` label or those words in the park reason) is left parked: the delegate posts "hive recommends: …; owner to confirm" and keeps 085.

Expand Down Expand Up @@ -844,7 +848,7 @@ See [operator-reference.md](../operator-reference.md).

#### What this release decides mechanically

The decider is rules-first: the cases above that are mechanically decidable (dedupe, owner-only, flaky, CI ratchet, design proposal, review backlog, contributor-offline, sentinel-trusted, small-low-risk, reporter-trust, hive-policy) are decided from the item itself; anything else falls to the reversible default (approve direction on an issue; release a green hive PR; ask for the fix first when the head is red or conflicting). Competing-PR comparisons and adopt-supersede requests are implemented. The same safety rails still decide whether the proposed action can run.
The decider is rules-first: the cases above that are mechanically decidable (dedupe, owner-only, flaky, CI ratchet, design proposal, review backlog, contributor-offline, sentinel-trusted, small-low-risk, reporter-trust, hive-policy) are decided from the item itself; anything else falls to the reversible default (approve direction on an issue; release a green hive PR; ask for the fix first when the head is red or conflicting; write nothing while its checks are still pending — rule `ci-pending`, so `default-release` and `small-low-risk` need a green head, not merely one without failures). Competing-PR comparisons and adopt-supersede requests are implemented. The same safety rails still decide whether the proposed action can run.

#### LLM step for the non-mechanical cases

Expand Down
Loading
Loading