docs(contributing): add hold-gate PR queue prioritization rubric by repires · Pull Request #1188 · projectbluefin/common

repires · 2026-09-23T17:47:45Z

bluefin-common PR

What does this change?

Adds a concrete 3-tier hold-gate PR queue prioritization rubric proposal (docs/contributing/hold-gate-rubric.md) and updates contributing and review skill documentation.

Why?

Closes #1043
Addresses #1082

Hold-gated PR inventory grew rapidly to 95 PRs competing flatly on a FIFO basis for scarce human review. This planning artifact establishes:

Three-Tier Prioritization Rubric:
- Tier P0 (Security & Integrity): Immediate review (<48h) for permissions, secret handling, cosign/OTA signatures, and org-wide blast radius files (system_files/shared/**, Containerfile).
- Tier P1 (Release Gates, Defects & Blockers): Expedited processing for user defects, SSOT blockers, and a Release-Gate Expedite Lane (<48h turnaround for approved release/ready or ci(promote) PRs, carrying forward the consensus from [strategist] Hold-gate drawdown (-21%, 95→75) not redirected to release gates: bluefin#1115 approved + release/ready, unmerged 17 days #1082).
- Tier P2 (Tests, Docs & Refactors): Standardized acceptance bar and size-sorted batch sweeps for test coverage PRs (~40% of the queue).
Factory Seven-Label Contract Compliance: Clarifies that priority tiers are review metadata and triage signals, not new workflow state labels, preserving docs/skills/label-workflow.md.
Preflight Obsolescence Check: Incorporates collision checks against main ([strategist] Hold-gated agent PRs silently superseded by merged human fixes — no obsolescence detection #1054) to close dead PRs before burning review cycles.
Operating Metrics: Targets aligned with Phase 0 of the roadmap (docs(roadmap): add org-wide ROADMAP.md consolidating 17 strategic findings into 3 phases #1073) to reduce the hold-gated queue below 40 PRs.

PR pipeline

opened ──▶ 4-review ──▶ approved ──▶ merged

A maintainer reviews and approves; merge goes through the merge queue.
Select blocked or hold to pause the work.

Checklist

PR title follows Conventional Commits (fix:, feat:, docs:, ci:, refactor:, etc.)
just check passes
pre-commit run --all-files passes (all skill frontmatter, index, and doc-link validators pass)
Skill doc updated if the change affects agent-facing conventions or behavior (see docs/skills/skill-improvement.md — updated docs/skills/pr-review/SKILL.md and triage-operations.md)
AGENTS.md / docs/SKILL.md / docs/skills/ links remain valid
CI is green after push: gh run list --repo projectbluefin/common --limit 5

AI attribution

Assisted-by: Gemini 3.8 via GitHub Copilot
Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com

— hive: backend=agy

🐝 Hive Agent: contributor | SHA: 24a57d5

## Planning Artifact Adds docs/contributing/hold-gate-rubric.md (new file) — the concrete proposal for the hold-gate PR queue prioritization rubric identified in #1043, incorporating the release-gate expedite policy consolidated from #1082, and scheduled in Phase 0 of the org-wide roadmap (#1073). Contents: - Three-tier prioritization rubric (P0: security/supply-chain/core integrity, P1: release-gate/defects/SSOT blockers, P2: tests/docs/routine refactors) - Release-gate expedite lane (<48h turnaround for approved release/ready PRs per common#1082 consolidation) - Streamlined acceptance criteria for test coverage PRs (~40% of queue backlog) - Factory seven-label contract compliance (tiers as review metadata/sorting signals, preserving canonical labels in docs/skills/label-workflow.md) - Preflight obsolescence check (#1054) to eliminate dead PRs - Operating metrics aligned with Phase 0 targets (<40 PR queue depth) Cross-references added in CONTRIBUTING.md, docs/contributing/reviewer-ladder.md, docs/skills/pr-review/SKILL.md, and docs/skills/pr-review/references/triage-operations.md. Refs #1043 Refs #1082 Refs #1029 Refs #1073 Hive-Run: #1043 Hive-Plan: phase-0/prioritization-rubric Hive-Spec: acmm-hold-gate#prioritization-rubric Assisted-by: Gemini 3.8 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: repires <repires@users.noreply.github.com>

… duplicate PRs (#1201) # bluefin-common PR ## What does this change? Adds `docs/contributing/self-collision-preflight.md` — a planning draft for a preflight step that intersects a lane's own open PRs before it files again — and links it from `CONTRIBUTING.md`, `docs/factory/agentic-model.md`, and `docs/skills/pr-review/references/duplicate-cluster.md`. ## Why? Closes #1060 The hold-gated protocol lists open PRs at kick time precisely so a lane can prove its new filing is disjoint from work already in flight. Within one lane that check failed: the quality lane opened two duplicate pairs covering identical file clusters within three days (`finpilot#285`/`#303`, `finpilot#296`/`#299`), costing four review slots for two pieces of work. **All four named PRs are already resolved** — `#285` merged 2026-09-04, `#296` merged 2026-09-05, `#299` merged 2026-09-06, `#303` closed 2026-09-06 without merge. The queue adjudicated them rather than any rule preventing the second filing, so the actionable remainder is the rule. ### Why this is a draft and not a direct edit to the hard rules The issue proposes "a lane may not open a PR whose file cluster intersects its own open hold-gated PRs." I re-audited the **31 open app-authored PRs** across the ten repositories tracked in #1058 on 2026-09-23 and found **no confirmed intra-lane duplicate cluster**. Every file-cluster intersection that exists is legitimate work the prohibition would have blocked: | Intersecting pair | Same lane? | Why it is not a duplicate | |---|---|---| | `bluefin#1227` / `#1310` | `app/mergeraptor` | Distinct dependency digest bumps (`projectbluefin/common:latest` vs `ublue-os/brew:latest`) sharing `image-versions.yml` | | `server#238` / `#239` | `app/mergeraptor` | Distinct dependency digest bumps (`projectbluefin/actions` vs `taiki-e/install-action`) sharing `.github/workflows/build.yml` | | `dakota-iso#142` / `#146` | `app/hivecommons-hive` | A cosign-verification security fix and a host-side config SSOT refactor, both touching `justfile` | | `common#1186` / `#1187` | human (`repires`) | Two human PRs closing different issues (#1161, #1160) sharing `Justfile` and `.github/workflows/unit-tests.yml` | A shared file is not proof of duplication — that is already the factory's rule at review time ([`common-rationalizations.md`](https://github.com/projectbluefin/common/blob/main/docs/skills/pr-review/references/common-rationalizations.md), [`duplicate-cluster.md`](https://github.com/projectbluefin/common/blob/main/docs/skills/pr-review/references/duplicate-cluster.md)). The real finpilot duplicates shared an *intent and closing issue*, not merely a path. So the draft proposes the evidenced alternative: **intersect, compare hunks and closing-issue sets, then either comment on the existing PR or disclose the overlap in the new body** — a disclosure rule rather than a prohibition, which keeps the judgment where the evidence is and makes it visible to the reviewer. It is drafted rather than applied because it binds filing behavior org-wide. That matches the precedent set for the sibling strategist findings: #1043 → `hold-gate-rubric.md` (#1188) and #1052 → `agent-lane-throttle.md` (#1197), both merged as drafts pending a maintainer decision. Nothing in the draft changes agent runtime behavior, adds a label, or adds a CI gate. ## PR pipeline ``` opened ──▶ 4-review ──▶ approved ──▶ merged ``` > A maintainer reviews and approves; merge goes through the merge queue. > Select `blocked` or `hold` to pause the work. ## Checklist - [x] PR title follows Conventional Commits (`fix:`, `feat:`, `docs:`, `ci:`, `refactor:`, etc.) - [x] `just check` passes - [x] `pre-commit run --all-files` passes (all 15 hooks green, including skill front-matter, `docs/SKILL.md` index, internal markdown links, and the generated `docs/skills/index.json` catalog) - [x] Skill doc updated if the change affects agent-facing conventions or behavior — `docs/skills/pr-review/references/duplicate-cluster.md` gained a prevention pointer to the draft; `docs/factory/agentic-model.md` gained a pointer from the existing duplicate-PR rule - [x] `AGENTS.md` / `docs/SKILL.md` / `docs/skills/` links remain valid (`scripts/check-doc-links.sh` passes) - [ ] CI is green after push — pending ## AI attribution This change was not authored via GitHub Copilot, so the Copilot-specific `Co-authored-by` trailer is deliberately omitted rather than asserted. The attribution trailer names the actual model: ``` Assisted-by: deepseek/deepseek-v4.1-flash via Hive ``` — hive: backend=litellm model=deepseek/deepseek-v4.1-flash --- 🐝 **Hive Agent**: `contributor` | **SHA:** `a8fcea8` Signed-off-by: sramkrishna <sramkrishna@users.noreply.github.com> Co-authored-by: sramkrishna <sramkrishna@users.noreply.github.com>

repires requested a review from a team as a code owner September 23, 2026 17:47

castrojo approved these changes Sep 23, 2026

View reviewed changes

This was referenced Sep 23, 2026

docs(contributing): add agent-lane-throttle.md — demand-side throttle for the hold-gate queue #1197

Merged

[strategist] Agent lanes have no output throttle — demand-side lever missing from review-bottleneck response #1052

Open

castrojo merged commit 0989380 into main Sep 23, 2026
1 check passed

castrojo deleted the strategy/hold-gate-rubric branch September 23, 2026 21:32

This was referenced Sep 23, 2026

docs(contributing): add self-collision preflight draft for intra-lane duplicate PRs #1201

Merged

[strategist] Agent lanes self-colliding: duplicate hold-gated PRs for identical clusters (finpilot #285/#303, #296/#299) #1060

Closed

Navigation Menu

docs(contributing): add hold-gate PR queue prioritization rubric - #1188

docs(contributing): add hold-gate PR queue prioritization rubric#1188
castrojo merged 1 commit into
mainfrom
strategy/hold-gate-rubric

repires commented Sep 23, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

repires commented Sep 23, 2026

bluefin-common PR

What does this change?

Why?

PR pipeline

Checklist

AI attribution

— hive: backend=agy

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants