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-review-backlog-dedupe.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- review: one backlog issue per finding per PR across perspectives and heads β€” carried-over "previous/prior … still present" notes and `<!-- hive-refers-to: #N -->` citations are references that never refile (at most one "still present at <head>" comment per head); on merge the blocked sweep checks the base itself and closes items whose file or symbol is gone; the activity monitor folds blocked review notes under their source PR as one muted line and counts the group once; dedupe ignores a leading `[reviewer]` title prefix
2 changes: 2 additions & 0 deletions src/docs/dashboard-sections.md
Original file line number Diff line number Diff line change
Expand Up @@ -1038,6 +1038,8 @@ An issue wearing `blocked` because the hive parked it on a pull request β€” its

The state (`open`, `merged`, `closed`, or absent when nothing knows) comes only from what the hive already holds β€” the status snapshot's open PRs, the ForgeState cache, the recent-merge ring β€” never a GitHub call from the tracker build; a merged or closed-unmerged blocker says so (`merged; the blocked sweep lifts the label next` / `closed unmerged; the blocked sweep re-triages it next`). The server reads the marker from the issue body when it has one, else from the enumeration's `blocked on owner/repo#N` reason, so sidelined rows (which carry only the reason) name it too.

**Review notes fold under their PR.** A `blocked` review-backlog issue (`Review backlog (<perspective>): …`, with or without the `[reviewer]` tag) whose source PR is still open is not a row of its own: the payload marks it `review_note_of: <PR>` and lists it in the PR's `review_notes`, and the tracker draws the PR row with one muted line β€” `3 review notes blocked on this PR Β· #15627, #15628, #15629`, each number a link β€” instead of three first-class rows. When the source PR is not drawn in the current view (the Issues tab, or a PR outside the snapshot), the group collapses into its lowest-numbered note, which carries `+2 more review notes blocked on PR #N`. The activity-monitor counter counts rows, so a group costs it one row, and the header's sum names the difference: `… Β· 4 review notes folded under their PR`; the Overview counter still counts every issue. A note whose PR has merged or closed is about to be lifted or re-triaged by the blocked sweep and stays a row (hivecommons/hive: 16 of 62 open items were such notes).

A `blocked` issue with neither (a human-applied label) keeps the bare pill. This is distinct from `blocked_on`, the open GitHub "blocked by" dependencies of a sequenced sub-issue ([#14765](https://github.com/hivecommons/hive/issues/14765)); when a row has both, the chevron tooltip lists them together.

#### Blocked pill β€” capability gaps
Expand Down
1 change: 1 addition & 0 deletions src/docs/github-write-surface.md
Original file line number Diff line number Diff line change
Expand Up @@ -151,6 +151,7 @@ writes no entry.
| Review backlog issues | `review_backlog.go` | yes (`review_backlog_issue_filed`, one per GitHub issue, with `pr`, `perspective`, `reused`, `destination`) | yes / backlog issue number |
| Review backlog summary comment | `review_backlog.go` | yes (`review_backlog_summary_posted`) | yes / PR number |
| Review backlog routing batch | `review_backlog.go` | yes (`review_backlog_batch_routed`, one per filing pass, with `destination`, `filed`, `updated`, `capped`) | yes / PR number |
| Review backlog self-check close | `review_backlog_selfcheck.go` | yes (`review_backlog_issue_closed`, with `pr`, `why`) | yes / backlog issue number |
| Human-decision and review-priority labels | `human_decision_label.go` | yes (`hive_label_applied`, with `label`) | yes / PR number |
| Recommendations issue | `recommendations.go` | yes (`recommendations_posted`, `outcome=created` or `updated`) | yes / issue number |
| Fleet report issue | `fleet_report.go` | yes (`fleet_report_posted`, `outcome=created` or `commented`) | yes / issue number |
Expand Down
3 changes: 2 additions & 1 deletion src/docs/review-swarm.md
Original file line number Diff line number Diff line change
Expand Up @@ -267,10 +267,11 @@ When `block_at` is set and `backlog_below` is on, every cited in-scope finding (
- **Destination.** `github_issue` files an issue in the PR's repo. `github_project` also adds that issue to the `governor.work_source.github_projects` project and sets its Status to `project_column_id`. `linear` files an issue on the Linear team mapped to the repo, in `linear_state` when set (an unknown state is an error naming it; label names the team lacks are skipped). `jira` files a Task in the first `work_source.jira.project_keys` project and moves it to `jira_status` when set. All three use the work-source credentials. If the destination's work source is not active or cannot be built, the item is filed as a GitHub issue with the `agent/reviewer` label added, and the hive logs why.
- **Item body.** The finding title and summary, the PR link, a `file:line` permalink at the reviewed head SHA, the severity with its P-level, the fingerprint, and the line `filed by Hive review backlog`. `labels` are applied to every item.
- **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.
- **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: the PR **merged** lifts the block with a one-line note, 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)).
- **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.

### Verdict labels (`review.verdict_labels`)
Expand Down
11 changes: 11 additions & 0 deletions src/pkg/dashboard/stage_tracker.go
Original file line number Diff line number Diff line change
Expand Up @@ -522,6 +522,17 @@ type StageTrackerItem struct {
// NestedUnder is, on a PR, the issue in the same repo whose row nests
// it (0 when the PR has no listed issue and stands on its own).
NestedUnder int `json:"nested_under,omitempty"`
// ReviewNoteOf is, on a `blocked` review-backlog issue ("Review backlog
// (<perspective>): …", with or without the `[reviewer]` prefix), the
// open source PR in the same repo it waits on. The SPA folds such issues
// under the PR's row as one muted "N review notes blocked on this PR"
// line β€” or, when the PR is not a row, into the lowest-numbered note of
// the group β€” instead of N first-class rows (hivecommons/hive: 16 of 62
// open items were blocked review notes). 0 on every other item.
ReviewNoteOf int `json:"review_note_of,omitempty"`
// ReviewNotes lists, on a PR, the blocked review-backlog issues folded
// under it (ReviewNoteOf == this PR), lowest number first.
ReviewNotes []StageTrackerReviewNote `json:"review_notes,omitempty"`
// LinkedIssues lists, on a PR, the issues GitHub says it closes
// (closingIssuesReferences, i.e. the PR body's Fixes/Closes/Resolves
// keywords) in the same repo, so a PR whose issue is not listed β€”
Expand Down
2 changes: 1 addition & 1 deletion src/pkg/dashboard/stage_tracker_gutter_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -251,7 +251,7 @@ stageTrackerSetMenuOpen(el, true); assert.ok(el.classList.contains('ham-menu-ope
stageTrackerSetMenuOpen(el, false); assert.ok(!el.classList.contains('ham-menu-open'));
stageTrackerSetMenuOpen(null, true); // tolerant of a missing panel
`
if out, err := exec.Command(node, "-e", script).CombinedOutput(); err != nil {
if out, err := runNodeStdin(node, script); err != nil {
t.Fatalf("node gutter invariant fixture failed: %v\n%s", err, out)
}
}
1 change: 1 addition & 0 deletions src/pkg/dashboard/stage_tracker_links.go
Original file line number Diff line number Diff line change
Expand Up @@ -396,6 +396,7 @@ func stageTrackerResolveLinkedPRs(items []StageTrackerItem, open func(repo strin
items[i].ClosedIssue = stageTrackerClosedIssueAnchor(items[i])
}
}
stageTrackerFoldReviewNotes(items)
}

// Link evidence arrives after the issue's stage/new narration, including
Expand Down
16 changes: 14 additions & 2 deletions src/pkg/dashboard/stage_tracker_repo_grouping_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,14 @@ func TestStageTrackerRepoGroupingWiring(t *testing.T) {
}
}

// runNodeStdin feeds the script to node over stdin: the lifted harnesses
// are past Linux's per-argument limit for -e.
func runNodeStdin(node, script string) ([]byte, error) {
cmd := exec.Command(node, "-")
cmd.Stdin = strings.NewReader(script)
return cmd.CombinedOutput()
}

func stageTrackerRepoGroupingHarness(t *testing.T, html string) string {
t.Helper()
return strings.Join([]string{
Expand Down Expand Up @@ -195,6 +203,10 @@ func stageTrackerRepoGroupingHarness(t *testing.T, html string) string {
jsFunc(t, html, "stageTrackerMoveAttrs"),
jsFunc(t, html, "stageTrackerNeedsAttention"),
jsFunc(t, html, "stageTrackerVisible"),
jsFunc(t, html, "stageTrackerIsReviewNote"),
jsFunc(t, html, "stageTrackerFoldedReviewNotes"),
jsFunc(t, html, "stageTrackerReviewNotesHtml"),
jsFunc(t, html, "stageTrackerFoldedCount"),
jsFunc(t, html, "stageTrackerRepoTint"),
jsFunc(t, html, "stageTrackerRepoShort"),
jsFunc(t, html, "stageTrackerIsPrimary"),
Expand Down Expand Up @@ -317,7 +329,7 @@ const section = stageTrackerRepoSectionHtml('always', 'repo');
assert.ok(section.includes('id="sts-repos"') && /value="always" checked/.test(section) && !/value="multi" checked/.test(section), section);
assert.ok(/<option value="repo" selected>Repo<\/option>/.test(section) && /<option value="none">None<\/option>/.test(section), section);
`
if out, err := exec.Command(node, "-e", script).CombinedOutput(); err != nil {
if out, err := runNodeStdin(node, script); err != nil {
t.Fatalf("node repo chip fixture failed: %v\n%s", err, out)
}
}
Expand Down Expand Up @@ -440,7 +452,7 @@ assert.strictEqual(_stageTrackerGroup, 'repo');
assert.deepStrictEqual(_stageTrackerCollapsed, { 'hivecommons/docs': true });
assert.strictEqual(stageTrackerPrimaryRepo(), 'hivecommons/hive');
`
if out, err := exec.Command(node, "-e", script).CombinedOutput(); err != nil {
if out, err := runNodeStdin(node, script); err != nil {
t.Fatalf("node group-by-repo fixture failed: %v\n%s", err, out)
}
}
Expand Down
Loading
Loading