docs(contributing): add reviewer-ladder.md — concrete proposal for the reviewer-scaling rung

[hivecommons-hive]

Planning Artifact

Adds docs/contributing/reviewer-ladder.md (new file) — the concrete proposal for the reviewer-scaling rung identified in #1029 and scheduled in Phase 0 of the org-wide roadmap (#1073).

Contents:

• Four-rung ladder (Contributor → Triager → Domain Reviewer → Maintainer) with observable promotion criteria
• Domain-scoped reviewer model matched to the measured repo-concentration of the hold-gate bottleneck ([strategist] Reviewer coverage map: hold-gate growth is repo-concentrated, not volume-driven (common/server/actions/dakota-iso at ~zero throughput) #1058)
• Hold-gate interaction: domain-reviewer approval satisfies the review requirement; maintainer still merges (safety property preserved)
• Operating metrics with verified 2026-09-05 baselines: 88 hold-gated PRs, 32 triage issues >60d, bluefin stable frozen 47d

Files claimed (2 files, +111/-0):

• docs/contributing/reviewer-ladder.md (new, +108) — the proposal itself.
• CONTRIBUTING.md (+3) — one index entry linking the new doc from the existing
  "contributing docs" list, marked as a draft/unadopted proposal. In scope for [strategist] Contributor ladder has no reviewer-scaling rung — triage/review capacity is the org bottleneck (74 issues in 1-triage, 32 aged >60d) #1029.

Conflict check: both paths were re-checked against every open PR in this
repository (32 open at check time, including all hold-gated ones) — no other open
PR touches CONTRIBUTING.md or docs/contributing/reviewer-ladder.md. Also
disjoint from my own ROADMAP PR (#1073, ROADMAP.md only).

Refs #1029
Refs #1073

---

Filed by strategist agent (ACMM L5 — hold-gated mode). Hold-gated: human review required. NEVER merge without human approval.

— hive: agent=strategist backend=copilot model=kimi-k3 copilot=1.0.78

[hanthor]

Mechanically clean; the new doc is an orphan, and it can't land before #1073

Verified against current main:

• merges clean (no conflicts)
• validate green
• python3 scripts/check-doc-links.sh → exit 0
• python3 scripts/generate_skill_index.py --check → docs/skills/index.json and index.md are up to date (40 skills) — correctly untouched, unlike several other open docs PRs here
• nothing under system_files/, so zero image blast radius across bluefin / bluefin-lts / dakota

Two things before this is mergeable.

1. docs/contributing/reviewer-ladder.md is linked from nothing

check-doc-links.sh only verifies that existing links resolve; it does not catch a new page that nothing points at. The docs/contributing/ directory currently holds exactly one other file, and it is indexed:

$ ls docs/contributing/
style-guide.md
$ grep -n "contributing/" CONTRIBUTING.md
58:- [`docs/contributing/style-guide.md`](docs/contributing/style-guide.md) —

Add the matching entry to CONTRIBUTING.md so the proposal is discoverable by the people expected to act on it. As it stands the document exists only for whoever remembers this PR number.

2. It forward-references an unmerged PR as if it were adopted

The header says this "tracks common#1029; Phase 0 item of the org-wide roadmap (common#1073)", and the Problem section says "The ROADMAP puts 'reviewer-scaling rung' in Phase 0." #1073 is an open, hold-labelled PR — there is no ROADMAP.md on main. So this document asserts a Phase 0 that the repo has not adopted, and if #1073 is closed or reshaped this text is wrong with nothing to catch it. Either land #1073 first and rephrase these as references to a file that exists, or soften them to "proposed alongside #1073".

Not blocking, but worth a maintainer's eye

The substance is a governance proposal — new Triager and Domain Reviewer rungs with approving-review rights on hold-gated PRs. The document is careful to repeat that nothing changes until a maintainer adopts it, and that framing is right. But note the tension with docs/skills/human-gates.md, where the Merge gate requires "an approving review from a human reviewer": granting rung-2 approval rights redefines who satisfies that gate. That is a maintainer decision, not a docs review, and it is the actual thing to say yes or no to here. Flagging it so it doesn't get waved through as "just a docs PR".

Statistical nit: the snapshots are dated 2026-08-27 through 2026-09-05 and the counts disagree across sources within the same document (74 issues in 1-triage vs 50 human-authored in triage; 32 aged >60d vs 17 aged >90d). They are reconcilable, but a reader will trip over them — consider one table with one as-of date.

---

Generated by Claude Code

[castrojo]

K3 final batch audit: approved as maintainer decision #1 of 2 required.

hanthor's 2026-09-12 blocking items, verified against head 0d48857:

1. Orphan doc: FIXED in 9ebbdf2 — CONTRIBUTING.md now indexes docs/contributing/reviewer-ladder.md with accurate 'unadopted until a maintainer decision' framing.
2. Forward-references to unmerged #1073: FIXED — softened in 9ebbdf2 ('proposed alongside...'), and the two parentheticals that would have gone stale on landing were patched in 0d48857 (now '(landed as ROADMAP.md; its phases remain proposals)' / '(Phase 0 parent)').

Cross-PR coherence: this lands AFTER #1073 (per hanthor's coupling note). The rung-2 Domain Reviewer approval-rights proposal does not conflict with #970's merge-gate carve-out — rung 2 grants approval rights to humans; #970 constrains tool-executed actions; the maintainer-still-merges invariant holds in both.

Batch verification: all 4 PRs squash-merge onto main (56d81ef) with zero conflicts; check-doc-links.sh, generate_skill_index.py --check, check-skill-frontmatter.sh, and test_skill_docs.py all green on the combined tree. The doc's operating-metrics snapshots are dated and labeled as drafts; the doc repeatedly states nothing changes until maintainer adoption — that framing survives landing intact.

Auto-merge armed, pinned to head 0d48857 — enters the squash merge queue when the second maintainer approval lands (ruleset requires 2; this is 1). validate is running on 0d48857.

[castrojo]

Approved: reviewer-ladder proposal is cleanly indexed in CONTRIBUTING.md, validate checks pass, and auto-merge is armed.

[castrojo]

Automated review approval: diff audited, invariants verified, ready for landing.

[castrojo]

Approved: reviewer ladder proposal verified and indexed, compatible with roadmap.

[castrojo]

Reviewed and approved documentation addition for reviewer ladder proposal.

[Danathar]

Holding off on a second approval for now, for one reason: the document says it is "proposed alongside the org-wide roadmap in common#1073 (landed as ROADMAP.md)". #1073 was closed unmerged today — the ROADMAP.md approach was declined on #958 in favour of tracking strategic items as issues — so that sentence is no longer true, and the proposal's framing leans on a plan that doesn't exist. The ladder idea itself is tracked in #1029 and is a maintainer decision. If the text is reworded to stand on its own (drop the #1073 reference, point at #1029), I'm happy to look again.

[hivecommons-hive]

Reviewed (correctness) — one minor body/diff gap, no blockers.

• The PR body states "Files claimed: docs/contributing/reviewer-ladder.md (new) only" and says the disjointness check against the 88 hold-gated PRs covered "this path" — but the diff also adds 3 lines to CONTRIBUTING.md:61-63. The CONTRIBUTING.md hunk is a benign index entry, but it was not part of the claimed/checked file set, so the conflict-disjointness claim doesn't cover it.

Doc content itself is internally consistent (e.g. "46 days" at the 2026-09-04 snapshot in reviewer-ladder.md:30-31 vs "47" in the body's 2026-09-05 baseline is a one-day difference, not an error). Docs-only, no behavior change, nothing testable.

— hive: agent=reviewer backend=copilot model=claude-fable-5 copilot=1.0.78

[Danathar]

I read this in full before deciding whether to add the second approval it needs. Two things in the text are out of date, and one part of the proposal I think needs a maintainer conversation rather than a document merge. Details below so anyone can check them without re-reading the whole PR.

What this PR is

A 108-line proposal in docs/contributing/reviewer-ladder.md, plus a three-line index entry in CONTRIBUTING.md. It suggests two new contributor roles between "opens PRs" and "maintainer":

• Triager — can label issues, mark duplicates, and confirm reproductions.
• Domain Reviewer — can give an approving review on agent-filed ("hold-gated") PRs within one area of the repo, such as justfiles or CI workflows. A maintainer would still do the merge.

The document says nothing changes until a maintainer adopts it. That is true: merging it changes no permissions.

What is out of date

1. It says the org roadmap (docs(roadmap): add org-wide ROADMAP.md consolidating 17 strategic findings into 3 phases #1073) "landed as ROADMAP.md". docs(roadmap): add org-wide ROADMAP.md consolidating 17 strategic findings into 3 phases #1073 was closed without merging, and there is no ROADMAP.md on main today. The document refers to that roadmap's "Phase 0" and its "targets" in several places. Those references point at something that does not exist, so a reader who follows them will be confused. They should be rewritten as "proposed in docs(roadmap): add org-wide ROADMAP.md consolidating 17 strategic findings into 3 phases #1073 (not adopted)" or removed.

2. The motivating numbers are three weeks old and the headline one has changed. The "Problem" section says bluefin's stable release was frozen for 46 days. Since then bluefin has shipped four stable releases (stable-20260909 through stable-20260917). The other snapshots (88 hold-gated PRs, 74 issues in triage) are from late August and should be re-measured or clearly dated as historical.

The part that needs a decision, not a merge

The Triager role looks safe and useful. Labelling, deduplicating, and confirming reproductions do not change code, and the triage backlog is real.

The Domain Reviewer role is different: it would let a non-maintainer's approval count toward the two approving reviews this repo requires before an agent-filed PR can merge. I would be careful with that. Reviewing three hive-filed PRs in this repo today, I found:

• fix(ci): retry transient GHCR errors in check-oci-refs.py #1122 replaces the GitHub API Authorization header with the literal string ******, which makes every request fail and silently disables the check the PR is meant to make more reliable.
• fix: polkit org.ublue.privileged.user.setup defaults no/no/auth_admin — system_files/shared/usr/share/polkit-1/actions/org.ublue.privileged.user.setup.policy #1108 changes a polkit default in a way that would show a password dialog to every user at every login, because the accompanying rule never matches.
• feat(countme): report to countme.projectbluefin.io from the images #1112's main feature (bootc status) cannot run as the unprivileged user the service is configured with, so it falls back to exactly the behaviour it says it fixes.

None of those were visible from the PR description or from CI being green. Those are the PRs a Domain Reviewer would be approving. That is not an argument against the idea, but it is an argument that "who counts as a reviewer for agent PRs" is a maintainer decision to make out loud, not a consequence of merging a document.

What I suggest

• Fix the two factual problems above (the docs(roadmap): add org-wide ROADMAP.md consolidating 17 strategic findings into 3 phases #1073 references and the stale numbers).
• Split the decision: the Triager role could be adopted on its own; the Domain Reviewer role should be discussed by maintainers first.
• There is no rush. This PR only touches docs/, and docs-only PRs currently cannot enter the merge queue at all — see ci: docs-only PRs can never merge — required build checks are path-ignored on docs changes #1149.

I am not adding an approval yet; I will once the text is corrected.

[hivecommons-hive]

intent-alignment

• The PR body states "Files claimed: docs/contributing/reviewer-ladder.md (new) only" and that the disjointness check against the 88 hold-gated PRs covered that path, but the diff also modifies CONTRIBUTING.md (lines 61–63, new index entry). The change itself is in scope for #1029's governance-docs cluster, but the file claim is inaccurate and CONTRIBUTING.md was not covered by the stated conflict check. Please update the body/claim to include both files.

No findings from: security, style, docs-currency.

— hive: agent=reviewer backend=copilot model=claude-fable-5 copilot=1.0.78

[Danathar]

This is a careful document and I want to say that first: it is explicit that it is unadopted, it marks every permission as a proposal rather than policy, and it dates its snapshots instead of asserting a timeless truth. That last part is what lets me check it, so here is that check.

The Problem section rests on "reviewer coverage is the binding constraint in several repos", evidenced by snapshots from 2026-08-27 through 2026-09-05. I ran a full census of the org tonight, 2026-09-22, and reviewing does not come out as the constraint. Merging does.

All 227 open non-draft PRs, by what is actually holding each one, reading mergeStateStatus per PR rather than inferring from approval counts:

 70  CLEAN      green, approved, no conflicts, no policy gate: needs a merge press
 43  needs an approval
 33  merge conflicts        author's move
 27  changes requested      author's move
 25  no CI has ever run     fork runs held at action_required
 15  failing CI
 14  in flight

Of the 88 approvals sitting on open PRs org-wide, 70 are mine. castrojo has 12, hanthor 4. So approvals are being produced in volume by one person and are not what the queue is short of.

Tonight also happened to run the experiment this proposal implies. We reviewed roughly 90 previously unreviewed PRs in one evening. CLEAN went from 31 to 70 and the number of PRs with two or more approvals stayed at 3. Nothing drained. Adding review capacity moved PRs from one queue into a longer one.

That matters specifically for rung 2, because Domain Reviewer is defined as "cannot merge". If the binding constraint is the merge press, a rung that explicitly excludes merging adds to the pile it is meant to drain. The proposal's own framing, "directly attack the two measured bottlenecks: triage age (rung 1) and hold-gate depth (rung 2)", is half supported by what I see: hold-gate depth is not where PRs are stuck today.

Rung 1 is a different story and I think it stands on its own. The issue-starvation numbers cited here (74 in 1-triage, 32 aged past 60 days, 50 human-authored with 17 past 90 days) describe a problem nothing I measured tonight touches, and nothing else in the org is addressing it. A Triager rung attacks that directly and does not depend on the reviewer premise at all.

What I would suggest, rather than blocking: re-run the census before adopting rung 2, and if it still shows the CLEAN pile dominating, the rung that would actually help is a scoped merge right rather than a scoped review right. Those are close to opposite proposals and the data should pick between them.

Not approving yet, only because the Problem section would become this repo's written understanding of its own bottleneck, and I would rather it be corrected before it lands than after. The method is repeatable if someone wants to check me: read mergeStateStatus per open PR and bucket it.

[castrojo]

Status check: Approved by @castrojo. Waiting on a 2nd maintainer review (@hanthor or @Danathar) to satisfy +2 approvals before landing.

[castrojo]

LGTM. Docs update for reviewer-ladder.md.