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/changed-review-backlog-min-severity.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Review backlog: findings below the new `review.backlog.min_severity` (default `P2`) are no longer filed as issues but collected in one upserted `hive:review-followups` comment on the PR; the issue cap `review.backlog.max_per_pr` (default 3) now applies over the PR's lifetime instead of per day (`max_per_pr_per_day` is a retired alias); and new findings sharing a perspective are filed as one checklist item. Set `min_severity: P3` to file every finding as before (hivecommons/hive#17065).
3 changes: 2 additions & 1 deletion src/docs/operator-reference/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -269,7 +269,8 @@ Go callers keep reading `cfg.Agents`, `cfg.Governor.Gateways` and so on through
| `review.severity.block_at` | Unset; owner-only. | Lowest finding priority that blocks merge: `P1` (ship fast, P0–P1 block), `P2` (strict, P0–P2 block) or `P3` (everything blocks). Also drives `classification.review_bots.min_priority` when that key is not set in `hive.yaml` or `hive-project.yaml`. Any other value fails load naming the field. Features -> Review gate -> Severity & backlog. See [review-swarm.md](../review-swarm.md#blocking-line-reviewseverity-reviewbacklog). |
| `review.severity.comment_below` / `backlog_below` | `true` / `true`; owner-only. | Whether findings below the blocking line are posted as non-blocking comments and filed to `review.backlog`. |
| `review.backlog.destination` | `github_issue`; owner-only. | `github_issue`, `github_project`, `linear` or `jira`. The last three need the matching `governor.work_source.type` (`github_projects`, `linear`, `jira`); on a mismatch the hive falls back to `github_issue`. Destination fields: `project_column_id` (required for `github_project`), `linear_state`, `jira_status`. |
| `review.backlog.labels` / `max_per_pr_per_day` | `[agent/reviewer]` / `10`; owner-only. `from-review`, `origin/review`, and `origin/reviewer` are accepted and mapped to `agent/reviewer`. | Labels on every backlog item and the per-PR-per-day cap (negative fails load; 0 = default). Reviewer is an agent lane, so `agent/reviewer` is the routing/ownership/provenance label. Non-lane hive issue filers continue to use `origin/selfreport`, `origin/governor`, `origin/dashboard`, `origin/forge`, or `origin/convergence`; the one-time startup migration (`/data/origin-label-migration-v4.done`) removes redundant lane-origin labels and backfills only non-lane origins. |
| `review.backlog.labels` / `max_per_pr` | `[agent/reviewer]` / `3`; owner-only. `from-review`, `origin/review`, and `origin/reviewer` are accepted and mapped to `agent/reviewer`. | Labels on every backlog item and the per-PR lifetime cap on items filed (negative fails load; 0 = default; `max_per_pr_per_day` is a retired alias for the size). New findings from one pass sharing a perspective collapse into one checklist item. Reviewer is an agent lane, so `agent/reviewer` is the routing/ownership/provenance label. Non-lane hive issue filers continue to use `origin/selfreport`, `origin/governor`, `origin/dashboard`, `origin/forge`, or `origin/convergence`; the one-time startup migration (`/data/origin-label-migration-v4.done`) removes redundant lane-origin labels and backfills only non-lane origins. |
| `review.backlog.min_severity` | `P2`; owner-only. `P0`–`P3`; invalid fails load. | Lowest finding priority that is filed as a backlog item. Findings below it (P3 `low`/`info` by default, every docs-currency nit included) go to one upserted `hive:review-followups` comment on the PR instead. `P3` files every finding, as before [#17065](https://github.com/hivecommons/hive/issues/17065). |
| `review.reviewers.autoscale.*` | `enabled: false`; when on: `min: 1`, `max: 4` (≤ the replicas cap 5), `target_backlog_per_reviewer: 2`, `scale_up_cycles: 2`, `scale_down_cycles: 5`, `cooldown: 5m`, `cpu_per_reviewer: 1.0`, `mem_per_reviewer_mb: 2048`, `agent` unset (first `role: reviewer` agent, else `reviewer_agents[0]`); owner-only. | Sizes the reviewer lane to its backlog ([#14685](https://github.com/hivecommons/hive/issues/14685)): adds a `reviewer-N` replica after `scale_up_cycles` cycles with more PRs waiting for a free reviewer than `target_backlog_per_reviewer` per reviewer (or a wait older than the review-pending stage dwell), drains the top replica after `scale_down_cycles` idle cycles and retires it only when its turn ends. Scale-ups are refused by named guards (`at-max`, `cooldown`, `saturated` kicks, `provider-budget`, `provider-headroom`, `max-parallel-reviews`, cgroup `cpu` / `memory`). Decisions log as `reviewer autoscale: 2→3 reason=…`; state is in `/api/status.reviewerAutoscale`. See [review-swarm.md](../review-swarm.md#reviewer-autoscale-reviewreviewersautoscale). |
| `review.contributor_prs.base_sync` | Off by default; owner-only. | Lets PR follow-up use GitHub's update-branch API on hive-authored lane PRs whose head is in a contributor fork, whose `mergeable_state` is `behind`/`dirty`, and whose author enabled "allow edits by maintainers". `behind` PRs get a GitHub-authored merge commit; `dirty`/422 falls back to the `hive-base-moved` repair note and kick. This requires an agent/proxy mode with `ISSUES_PRS_MERGE` because `PUT /pulls/{n}/update-branch` is merge-scoped. It does not rewrite history and does not add a human/bot-authored DCO commit; the repository's "Sign-off survives the squash" check examines the PR's own commits, not GitHub's update-branch merge commit. |
| `governor.advisory.post_retry_backoff_s` | `3600` seconds. `HIVE_ADVISORY_POST_RETRY_BACKOFF_S` overrides the default when the key is unset; a negative value disables the pause. | How long the advisory digest write is paused after GitHub refuses it with `403 Resource not accessible by integration`. That refusal is structural (foreign-authored comment, repo dropped from the installation, or repo transferred to another owner), so per-cycle retries only burn API quota. The failed edit first falls back to creating a fresh App-authored comment; if the create is refused too, the error is recorded for the hub health row — naming the new `owner/repo` when the repository has moved — and attempts pause for this window. See [advisory.md](../advisory.md#when-the-write-is-refused). |
Expand Down
10 changes: 7 additions & 3 deletions src/docs/review-swarm.md
Original file line number Diff line number Diff line change
Expand Up @@ -208,7 +208,8 @@ review:
backlog:
destination: github_issue # github_issue | github_project | linear | jira
labels: [agent/reviewer] # default [agent/reviewer]; from-review, origin/review, and origin/reviewer are mapped to it
max_per_pr_per_day: 10 # default 10
min_severity: P2 # default P2; P0 | P1 | P2 | P3 — findings below it go to the PR's Follow-ups comment, not the tracker
max_per_pr: 3 # default 3; items per PR over the PR's lifetime (max_per_pr_per_day is a retired alias)
```

### Blocking line (`review.severity`, `review.backlog`)
Expand Down Expand Up @@ -264,7 +265,8 @@ Semantics:
| `linear_state` | team default | Linear workflow state for new items. |
| `jira_status` | project initial status | Jira status for new tickets. |
| `labels` | `[agent/reviewer]` | Applied to every item. The retired `from-review`, `origin/review`, and `origin/reviewer` are accepted and mapped to `agent/reviewer`. |
| `max_per_pr_per_day` | `10` | Cap per PR per day. |
| `min_severity` | `P2` | Lowest finding priority that still becomes a backlog item. Findings below it (P3 `low`/`info` by default — every docs-currency nit, for example) are appended to one upserted `hive:review-followups` comment on the PR instead, so nothing is lost and nothing is filed. `P3` restores filing every finding ([#17065](https://github.com/hivecommons/hive/issues/17065)). |
| `max_per_pr` | `3` | Items filed per PR over the PR's lifetime, not per day. `max_per_pr_per_day` is accepted as a retired alias for the size when `max_per_pr` is unset. |

**Precedence with `classification.review_bots.min_priority`.** One blocking line governs both the hive reviewer and external review bots. The bot threshold resolves in this order, first non-empty wins: `hive.yaml` `classification.review_bots.min_priority` (including an explicit `all`), then `hive-project.yaml` `classification.review_bots.min_priority`, then `review.severity.block_at`. With none set, every bot finding is routed. `block_at` is never copied into `min_priority`; clearing the explicit override hands control back to `block_at`. Invalid values fail config load with an error naming the field (for example `review.severity.block_at`, `review.backlog.project_column_id`).

Expand All @@ -277,7 +279,9 @@ When `block_at` is set and `backlog_below` is on, every cited in-scope finding (
- **Fingerprint dedup.** Each finding is fingerprinted as `sha256(rule | path | snippet)`: the title, the cleaned file path and the summary, lower-cased with whitespace collapsed. Line numbers are left out, so the same nit at a shifted line still matches. `/data/review-backlog-issues.json` keeps a per-repo map of fingerprint → item. When another PR raises a known fingerprint, the hive comments on the existing item with the new PR link and permalink instead of filing a second one. The same PR raising it again changes nothing. When the destination folds a new finding into an existing open item instead, the item receives the full finding — title, `file:line`, summary, severity, PR link and fingerprint — under an "Additional finding (folded in — same finding area and category)" heading with an unchecked task-list line, still tagged with the `hive:review-backlog-link` marker; the PR summary lists it as `#T (folded into an existing issue) — <finding title>` ([#13604](https://github.com/hivecommons/hive/issues/13604)). The `github_issue` sink folds into an open hive-filed issue that cites the same files only when that issue is in the same category (its `Review backlog (<perspective>)` title or `Perspective:` line matches the finding's perspective) and it either cites the same file within 10 lines of the finding or names a symbol the finding's title names. The same check applies to an open issue whose title differs from the finding's only after its `Review backlog (<perspective>):` prefix; only an exact title match is reused unconditionally. Sharing a file alone is not enough: the finding is filed as its own issue, which gets a `hive:review-backlog-same-file` comment reading "Same file as #N" ([#13906](https://github.com/hivecommons/hive/issues/13906)).
- **One item per finding per PR.** Each item filed from a PR is also remembered under that PR with its evidence file, line and title (`pr_findings` in the ledger). A later report from any perspective or at any head that names the same finding — same file and the same line, a shared code symbol, or the same title once its wrapping is stripped — is tracked against the existing item, never filed again. A report whose title is only a carry-over wrapper ("Previous style finding still present (non-blocking)", "Prior correctness note still present: …", "Previous security finding (…) unchanged at new head") or that carries the `<!-- hive-refers-to: #N -->` marker is a *reference*, not a finding: it is matched against the PR's tracked items and otherwise dropped with a log line, so one finding on one PR can no longer become three issues from three perspectives (hivecommons/hive#15627, #15628, #15629). The hive notes a tracked finding's persistence at most once per head, with one `Still present at <head> (<perspectives>).` comment on the item (counted against the daily cap). Title matching ignores a leading `[reviewer]` role tag, so an existing issue dedupes whichever filing path titled it.
- **Split on host close.** A folded finding lives only in its `hive:review-backlog-link` comment, so closing the host used to close it too. Every ten minutes, alongside the closed-issue stage sweep, the hive reads the hive-authored link comments on recently closed backlog hosts (the issues the ledger points findings at) and re-files each still-unchecked `- [ ]` finding as its own `github_issue` backlog item headed `hive:review-backlog-split` and "Split from #N (host closed)", comments the new link on the host under the same marker, and moves the finding's ledger item and fingerprint records to the new issue (or to the open twin the sink folded it into, which then carries the folded comment so its own close splits it again). A checked `- [x]` finding stays with the host. A host closed as not planned or duplicate keeps the findings that match it by the fold rule above and only splits out unrelated ones; the host itself is exempt from the issue filer's rejected-twin gate for that filing (a fold cites the host's own files, so the just-rejected host would otherwise always count as the rejection), while a rejection elsewhere still suppresses the finding and is logged and counted as `skipped`. `/data/review-backlog-issues.json` also keeps `split_keys`, link-marker key → the closed hosts it was split out of, so re-runs are idempotent. One pass files at most 20 findings across all repos; hosts the pass did not reach once that cap was hit are counted and logged as `deferred`. A host that received at least one split is bumped by its cross-link comment and re-surfaces in the next pass, but a deferred host keeps its old `updated_at` and is only revisited while it stays inside the pass window (the last ten-minute interval plus ten minutes of slack), so a backlog of more than 20 unchecked findings closing within one window may leave the trailing hosts unsplit; the `deferred` count in the sweep log is the signal to look for ([#13914](https://github.com/hivecommons/hive/issues/13914)). Hosts closed before the windowed sweep reached them are covered by a backfill pass that runs after each split sweep: it walks the ledger's host index, fetches each host directly and splits every closed one through the same idempotent path. A backfill pass that split, skipped or deferred anything logs `review backlog split backfill pass complete` with those counts. Once a pass visits every host without hitting the per-pass cap (including a host left part-split when the cap ran out) or a transient error, `/data/review-backlog-issues.json` records `split_backfilled` and later passes are no-ops; an incomplete pass logs `review backlog split backfill incomplete, retrying next pass` and the next pass retries. Clearing `split_backfilled` re-runs the walk ([#13947](https://github.com/hivecommons/hive/issues/13947)).
- **Cap.** At most `max_per_pr_per_day` items are filed or updated per PR per UTC day. Findings over the cap are retried on the next review. Out-of-scope findings also stay within `review.max_out_of_scope_backlog_issues` per PR.
- **Severity floor.** Findings below `review.backlog.min_severity` (default `P2`, so `low`/`info`) are never filed. They are listed as `- [ ]` task lines in one `<!-- hive:review-followups-comment v1 -->` comment on the PR, edited in place on every pass: ticked lines stay ticked, a re-reported nit is not listed twice, and new nits are appended. Operators who want every finding filed set `min_severity: P3` ([#17065](https://github.com/hivecommons/hive/issues/17065)).
- **Same-family collapse.** New findings from one pass that share a perspective and scope (for example three docs-currency nits from one PR) become one item titled `[reviewer] Review backlog (<perspective>): <repo>#<pr> — N follow-ups` whose body is a checklist, one `- [ ]` per finding with `file:line`, severity and summary. Each finding's fingerprint is recorded against that one item, so another PR raising any of them comments on it instead of filing again. A single new finding keeps the per-finding title.
- **Cap.** At most `max_per_pr` items (default 3) are filed per PR over the PR's lifetime; the count is persisted in `/data/review-backlog-issues.json` (`pr_item_count`) and never resets. A collapsed item counts once. Findings over the cap are retried on the next review and may land after a human closes an item. Out-of-scope findings also stay within `review.max_out_of_scope_backlog_issues` per PR.
- **Audit.** Each filing pass that wrote anything records one `review_backlog_batch_routed` entry on the PR (`destination`, `filed`, `updated`, `capped`). Each new GitHub issue also gets its own `review_backlog_issue_filed` entry; an issue split out of a closed host carries `split_from=<host>` and `reused`, and the dashboard audit log records one `review-backlog-split` entry per split. The PR receives one summary comment that lists the items filed.
- **Blocked on the PR.** Every item the backlog creates is parked on the reviewed PR with the `blocked` label and the `<!-- hive:blocked-on pr=owner/repo#N -->` marker, in every destination ([#13833](https://github.com/hivecommons/hive/issues/13833)). A below-line or out-of-scope finding is almost always about lines the PR changes, so working it on the base branch first is wrong or conflicts. When the cited file only exists in the PR the note says so ([#13093](https://github.com/hivecommons/hive/issues/13093)); otherwise it says the finding is about code the PR is changing, and tells whoever picks it up to check it still applies after the merge and to close it without a PR if it is already fixed. The ledger records the PR each item waits on, and `ReconcileReviewBacklogBlocks` (every governor cycle) resolves it: when the PR **merged** the hive itself checks whether the finding still applies on the PR's base branch — the evidence file gone, or none of the code symbols the finding's title names left in it, closes the item as completed with a one-line note (`review_backlog_issue_closed` audit entry; GitHub-issue destination only); otherwise, or when the check cannot tell, the block is lifted with a one-line note and the item becomes actionable; the PR **closed unmerged** also lifts the block, with a `<!-- hive:review-backlog-retriage -->` note ("source PR #N closed unmerged — re-triage against current base"), and leaves the item open for normal triage and dedupe. The hive never closes or cancels a backlog item because its PR closed: a closed PR is often superseded by one that lands the same lines, so the finding may still apply. Closing it as not planned stays a human (or `/fixed`) action. Destinations without a resolver (Jira, GitHub Projects) get the note only. A finding folded into an existing open twin keeps the twin's own state ([#13364](https://github.com/hivecommons/hive/issues/13364)).
- **Heads mode.** With [review heads](#review-heads-several-models-per-perspective), only the decision step's decided reports file backlog items; raw head reports never do, so two heads' wordings of one finding cannot become two items. Instead of the once-per-PR summary comment, the relay appends a **Follow-ups filed** section to the decided review itself (edited in place, the App's own COMMENTED review only), listing every item that head's findings map to — filed, re-raised onto an existing item, or already tracked — so each head commit's review says where its nits went.
Expand Down
Loading
Loading