From 41dd545e7680a0c817797863a255ddd809b15f8f Mon Sep 17 00:00:00 2001 From: "strategist[bot]" Date: Sat, 5 Sep 2026 09:37:00 -0400 Subject: [PATCH 1/4] [strategist] planning: add reviewer-ladder contribution strategy doc (common#1029) Signed-off-by: strategist[bot] --- docs/contributing/reviewer-ladder.md | 87 ++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 docs/contributing/reviewer-ladder.md diff --git a/docs/contributing/reviewer-ladder.md b/docs/contributing/reviewer-ladder.md new file mode 100644 index 00000000..8e9ca902 --- /dev/null +++ b/docs/contributing/reviewer-ladder.md @@ -0,0 +1,87 @@ +# Reviewer Ladder — Contribution Strategy (Planning Draft) + +> **Status**: hold-gated planning artifact. Human review required before adoption. +> Filed by the strategist agent. Tracks common#1029; Phase 0 item of the org-wide +> roadmap (common#1073). + +## Problem + +Review capacity is the org's binding constraint, and the contributor ladder has +no rung between "opens PRs" and "maintainer" that grows it. + +Verified state as of 2026-09-05: + +- **88 open hold-gated agent PRs** across 9 repos compete for the same small + pool of human reviewers (common#1043: no prioritization rubric). +- Queue growth is **repo-concentrated, not volume-driven** — common, server, + actions, and dakota-iso show ~zero review throughput while other repos drain + (common#1058). +- Human-filed issues starve alongside: 74 issues in triage, 32 aged >60 days + (common#1029); 50 human issues waiting, 17 aged >90 days (common#1067). +- Downstream release impact: bluefin stable frozen 47 days (stable-20260720), + bluefin-lts 29 days stale, common missed its v2026.09 monthly tag, while + dakota — with active review attention — ships daily (common#1078). + +The ROADMAP (common#1073) puts "reviewer-scaling rung" in Phase 0. This document +is the concrete proposal for that rung. + +## Proposal: a four-rung ladder + +| Rung | Role | Scope | Grants | +|------|------|-------|--------| +| 0 | Contributor | any | fork PRs | +| 1 | **Triager** | per-repo | label, dedupe, reproduce, close-as-duplicate | +| 2 | **Domain Reviewer** | per-repo, per-domain | approving review on hold-gated PRs within an owned domain (e.g. justfiles, CI workflows, tests); cannot merge | +| 3 | Maintainer | per-repo | merge, release | + +Rungs 1–2 are the new rungs. Both are **additive permissions**, reachable +without full maintainer trust, and directly attack the two measured +bottlenecks: triage age (rung 1) and hold-gate depth (rung 2). + +### Promotion criteria (observable, no nomination-by-vibes) + +- **Contributor → Triager**: 5+ merged PRs in the repo **or** 10 substantive + triage actions (reproduction notes, dedupe links, label corrections) on + others' issues. Any maintainer confirms; no vote. +- **Triager → Domain Reviewer**: 30 days as Triager **and** 10 reviewed + hold-gated PRs in the claimed domain with maintainer sign-off on review + quality. Domain is recorded in the repo's contributor doc. +- **Domain Reviewer → Maintainer**: existing org process; unchanged. + +### Why domain-scoped review + +common#1058 shows throughput is near-zero in specific repos, not uniformly +low. Domain-scoped reviewers let a trusted contributor unblock, say, +`justfiles` in common or `workflows` in dakota-iso without granting org-wide +merge rights — matching permission scope to the measured bottleneck. + +### Interaction with the hold-gate + +Agent-filed hold-gated PRs require human review before merge. A Domain +Reviewer's approval satisfies the *review* requirement; a maintainer still +merges. This preserves the hold-gate's safety property while multiplying +review bandwidth — the scarce resource. + +## Operating metrics + +Adoption is measurable against the ROADMAP success table (common#1073): + +- Hold-gated PR count (baseline: 88 on 2026-09-05) — target: declining trend +- Median hold-gated PR review latency — target: < 7 days +- Human-issue triage age (baseline: 32 issues >60d, 17 >90d) — target: 0 >60d +- Zero-throughput repos from common#1058 — target: ≥1 merged agent PR/repo/month + +## What this document deliberately does not do + +- No workflow/CI changes (ci-maintainer lane). +- No changes to merge protection or CODEOWNERS (maintainer decision). +- No agent-lane throttling mechanics (tracked separately in common#1052). + +## Related + +- common#1029 — reviewer-scaling rung finding (this doc's tracker) +- common#1073 — org-wide ROADMAP.md (Phase 0 parent) +- common#1058 — reviewer coverage map / repo-concentration data +- common#1067 — user-issue triage starvation +- common#1043 — hold-gate prioritization rubric +- common#1078 — release cadence breakdown (downstream symptom) From 8f2f1ae9af5d42921a32967ab698e442322dbab7 Mon Sep 17 00:00:00 2001 From: castrojo Date: Thu, 10 Sep 2026 19:31:00 -0400 Subject: [PATCH 2/4] docs(contributing): correct reviewer ladder draft evidence Clarify source snapshots, link live references, and keep proposed permissions and hold-gate behavior explicitly non-adopted. Assisted-by: GPT-5.6 Luna via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/contributing/reviewer-ladder.md | 114 ++++++++++++++++----------- 1 file changed, 67 insertions(+), 47 deletions(-) diff --git a/docs/contributing/reviewer-ladder.md b/docs/contributing/reviewer-ladder.md index 8e9ca902..8fbff442 100644 --- a/docs/contributing/reviewer-ladder.md +++ b/docs/contributing/reviewer-ladder.md @@ -1,87 +1,107 @@ # Reviewer Ladder — Contribution Strategy (Planning Draft) > **Status**: hold-gated planning artifact. Human review required before adoption. -> Filed by the strategist agent. Tracks common#1029; Phase 0 item of the org-wide -> roadmap (common#1073). +> Filed by the strategist agent. Tracks [common#1029](https://github.com/projectbluefin/common/issues/1029); +> Phase 0 item of the org-wide roadmap ([common#1073](https://github.com/projectbluefin/common/pull/1073)). +> +> Nothing below changes GitHub roles, branch protection, CODEOWNERS, workflow behavior, +> or hold-gate enforcement until a maintainer adopts it. ## Problem -Review capacity is the org's binding constraint, and the contributor ladder has -no rung between "opens PRs" and "maintainer" that grows it. - -Verified state as of 2026-09-05: - -- **88 open hold-gated agent PRs** across 9 repos compete for the same small - pool of human reviewers (common#1043: no prioritization rubric). -- Queue growth is **repo-concentrated, not volume-driven** — common, server, - actions, and dakota-iso show ~zero review throughput while other repos drain - (common#1058). -- Human-filed issues starve alongside: 74 issues in triage, 32 aged >60 days - (common#1029); 50 human issues waiting, 17 aged >90 days (common#1067). -- Downstream release impact: bluefin stable frozen 47 days (stable-20260720), - bluefin-lts 29 days stale, common missed its v2026.09 monthly tag, while - dakota — with active review attention — ships daily (common#1078). - -The ROADMAP (common#1073) puts "reviewer-scaling rung" in Phase 0. This document -is the concrete proposal for that rung. +Reviewer coverage is the binding constraint in several repos, and the contributor +ladder has no rung between "opens PRs" and "maintainer" that grows it. Org-wide +throughput is healthy, but reviewer coverage is uneven across repos. + +Reported state, using snapshots dated 2026-08-27 through 2026-09-05: + +- **88 open hold-gated agent PRs** across 10 repos compete for limited + per-repo reviewer coverage ([common#1043](https://github.com/projectbluefin/common/issues/1043): no + prioritization rubric; the repo-concentration breakdown is in [common#1058](https://github.com/projectbluefin/common/issues/1058)). +- The lowest throughput is concentrated in common (4 merges), server (1), + actions (0), and dakota-iso (0) while other repos drain ([common#1058](https://github.com/projectbluefin/common/issues/1058), + last-7-day snapshot). +- Human-filed issues starve alongside: 74 issues in `1-triage`, 32 aged >60 + days ([common#1029](https://github.com/projectbluefin/common/issues/1029), + 2026-08-27 snapshot); 50 human-authored issues in triage, 17 aged >90 + days ([common#1067](https://github.com/projectbluefin/common/issues/1067), + 2026-08-31 snapshot). +- Downstream release impact at the 2026-09-04 snapshot: bluefin stable frozen + 46 days (stable-20260720), bluefin-lts 28 days stale, common missed its + v2026.09 monthly tag, while dakota stable was current (0 days old) + ([common#1078](https://github.com/projectbluefin/common/issues/1078)). + +The ROADMAP ([common#1073](https://github.com/projectbluefin/common/pull/1073)) +puts "reviewer-scaling rung" in Phase 0. This document is the concrete proposal +for that rung. ## Proposal: a four-rung ladder -| Rung | Role | Scope | Grants | +| Rung | Role | Scope | Proposed grants | |------|------|-------|--------| | 0 | Contributor | any | fork PRs | | 1 | **Triager** | per-repo | label, dedupe, reproduce, close-as-duplicate | | 2 | **Domain Reviewer** | per-repo, per-domain | approving review on hold-gated PRs within an owned domain (e.g. justfiles, CI workflows, tests); cannot merge | | 3 | Maintainer | per-repo | merge, release | +All permissions in this table are proposals, not current repository policy. + Rungs 1–2 are the new rungs. Both are **additive permissions**, reachable without full maintainer trust, and directly attack the two measured bottlenecks: triage age (rung 1) and hold-gate depth (rung 2). ### Promotion criteria (observable, no nomination-by-vibes) -- **Contributor → Triager**: 5+ merged PRs in the repo **or** 10 substantive - triage actions (reproduction notes, dedupe links, label corrections) on - others' issues. Any maintainer confirms; no vote. -- **Triager → Domain Reviewer**: 30 days as Triager **and** 10 reviewed - hold-gated PRs in the claimed domain with maintainer sign-off on review - quality. Domain is recorded in the repo's contributor doc. +- **Contributor → Triager** (proposed): 5+ merged PRs in the repo **or** 10 + substantive triage actions (reproduction notes, dedupe links, label + corrections) on others' issues. A maintainer would confirm; no vote. +- **Triager → Domain Reviewer** (proposed): 30 days as Triager **and** 10 + reviewed hold-gated PRs in the claimed domain with maintainer sign-off on + review quality. The domain would be recorded in the repo's contributor doc. - **Domain Reviewer → Maintainer**: existing org process; unchanged. ### Why domain-scoped review -common#1058 shows throughput is near-zero in specific repos, not uniformly -low. Domain-scoped reviewers let a trusted contributor unblock, say, -`justfiles` in common or `workflows` in dakota-iso without granting org-wide -merge rights — matching permission scope to the measured bottleneck. +[common#1058](https://github.com/projectbluefin/common/issues/1058) shows +throughput is uneven across specific repos, not uniformly low. Domain-scoped +reviewers could let a trusted contributor unblock, say, `justfiles` in common +or `workflows` in dakota-iso without granting org-wide merge rights — matching +permission scope to the measured bottleneck. ### Interaction with the hold-gate -Agent-filed hold-gated PRs require human review before merge. A Domain -Reviewer's approval satisfies the *review* requirement; a maintainer still -merges. This preserves the hold-gate's safety property while multiplying -review bandwidth — the scarce resource. +Agent-filed hold-gated PRs currently require human review before merge. Under +this draft, a Domain Reviewer's approval would satisfy the review requirement, +while a maintainer would still merge. This is a proposal only: it does not +change current permissions, branch protection, CODEOWNERS, or workflow +enforcement. ## Operating metrics -Adoption is measurable against the ROADMAP success table (common#1073): +Adoption can be measured alongside the ROADMAP success table +([common#1073](https://github.com/projectbluefin/common/pull/1073)); these are +draft operating measures: -- Hold-gated PR count (baseline: 88 on 2026-09-05) — target: declining trend -- Median hold-gated PR review latency — target: < 7 days -- Human-issue triage age (baseline: 32 issues >60d, 17 >90d) — target: 0 >60d -- Zero-throughput repos from common#1058 — target: ≥1 merged agent PR/repo/month +- Open hold-gated PR count (baseline: 88 on 2026-09-05) — ROADMAP target: <40 + and shrinking +- Median hold-gated PR review latency — draft target: <7 days +- Human-issue triage age — ROADMAP baseline: 50+ issues >30d on 2026-09-02, + target: 0; supporting snapshots report 32 issues >60d on 2026-08-27 and + 17 >90d on 2026-08-31 +- Zero-throughput repos ([common#1058](https://github.com/projectbluefin/common/issues/1058)) + — draft target: ≥1 merged agent PR per repo/month ## What this document deliberately does not do - No workflow/CI changes (ci-maintainer lane). - No changes to merge protection or CODEOWNERS (maintainer decision). -- No agent-lane throttling mechanics (tracked separately in common#1052). +- No agent-lane throttling mechanics (tracked separately in [common#1052](https://github.com/projectbluefin/common/issues/1052)). ## Related -- common#1029 — reviewer-scaling rung finding (this doc's tracker) -- common#1073 — org-wide ROADMAP.md (Phase 0 parent) -- common#1058 — reviewer coverage map / repo-concentration data -- common#1067 — user-issue triage starvation -- common#1043 — hold-gate prioritization rubric -- common#1078 — release cadence breakdown (downstream symptom) +- [common#1029](https://github.com/projectbluefin/common/issues/1029) — reviewer-scaling rung finding (this doc's tracker) +- [common#1073](https://github.com/projectbluefin/common/pull/1073) — org-wide ROADMAP.md (Phase 0 parent) +- [common#1058](https://github.com/projectbluefin/common/issues/1058) — reviewer coverage map / repo-concentration data +- [common#1067](https://github.com/projectbluefin/common/issues/1067) — user-issue triage starvation +- [common#1043](https://github.com/projectbluefin/common/issues/1043) — hold-gate prioritization rubric +- [common#1078](https://github.com/projectbluefin/common/issues/1078) — release cadence breakdown (downstream symptom) From 9ebbdf2f99439c81cd37ddf9297fcd8338d542d1 Mon Sep 17 00:00:00 2001 From: "kubestellar-hive[bot]" <280983584+kubestellar-hive[bot]@users.noreply.github.com> Date: Fri, 11 Sep 2026 22:59:27 -0400 Subject: [PATCH 3/4] docs(contributing): index reviewer-ladder and soften roadmap references Address hanthor's review on #1080: - Index docs/contributing/reviewer-ladder.md from CONTRIBUTING.md next to the style-guide entry, framed as an unadopted draft proposal, so the document is discoverable instead of orphaned. - Soften the forward references to #1073: the roadmap is an open, unadopted PR, so describe it as proposed-alongside rather than as an adopted Phase 0 parent. The ladder text now stands on its own if #1073 is reshaped or closed. The governance question (whether Domain Reviewer approvals satisfy the hold-gate) remains a maintainer decision; this change is structural only. check-doc-links.sh passes. Assisted-by: Kimi K3 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- CONTRIBUTING.md | 3 +++ docs/contributing/reviewer-ladder.md | 15 ++++++++------- 2 files changed, 11 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d4b06c8f..3f4a6529 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -58,3 +58,6 @@ Full layer validation (the `common` behave suite from - [`docs/contributing/style-guide.md`](docs/contributing/style-guide.md) — coding and configuration conventions for shell scripts, Just recipes, JSON/YAML, and the Containerfile. +- [`docs/contributing/reviewer-ladder.md`](docs/contributing/reviewer-ladder.md) — + draft proposal for a four-rung contributor ladder (Triager, Domain + Reviewer); unadopted until a maintainer decision. diff --git a/docs/contributing/reviewer-ladder.md b/docs/contributing/reviewer-ladder.md index 8fbff442..1a6ea307 100644 --- a/docs/contributing/reviewer-ladder.md +++ b/docs/contributing/reviewer-ladder.md @@ -2,7 +2,7 @@ > **Status**: hold-gated planning artifact. Human review required before adoption. > Filed by the strategist agent. Tracks [common#1029](https://github.com/projectbluefin/common/issues/1029); -> Phase 0 item of the org-wide roadmap ([common#1073](https://github.com/projectbluefin/common/pull/1073)). +> Proposed alongside the org-wide roadmap in [common#1073](https://github.com/projectbluefin/common/pull/1073) (open, not yet adopted). > > Nothing below changes GitHub roles, branch protection, CODEOWNERS, workflow behavior, > or hold-gate enforcement until a maintainer adopts it. @@ -31,9 +31,10 @@ Reported state, using snapshots dated 2026-08-27 through 2026-09-05: v2026.09 monthly tag, while dakota stable was current (0 days old) ([common#1078](https://github.com/projectbluefin/common/issues/1078)). -The ROADMAP ([common#1073](https://github.com/projectbluefin/common/pull/1073)) -puts "reviewer-scaling rung" in Phase 0. This document is the concrete proposal -for that rung. +The roadmap proposed in [common#1073](https://github.com/projectbluefin/common/pull/1073) +places "reviewer-scaling rung" in Phase 0. This document is the concrete +proposal for that rung; both are pending maintainer decision, and this text +stands on its own if the roadmap is reshaped. ## Proposal: a four-rung ladder @@ -78,8 +79,8 @@ enforcement. ## Operating metrics -Adoption can be measured alongside the ROADMAP success table -([common#1073](https://github.com/projectbluefin/common/pull/1073)); these are +If the roadmap proposed in [common#1073](https://github.com/projectbluefin/common/pull/1073) +is adopted, its success table can track adoption; either way these are draft operating measures: - Open hold-gated PR count (baseline: 88 on 2026-09-05) — ROADMAP target: <40 @@ -100,7 +101,7 @@ draft operating measures: ## Related - [common#1029](https://github.com/projectbluefin/common/issues/1029) — reviewer-scaling rung finding (this doc's tracker) -- [common#1073](https://github.com/projectbluefin/common/pull/1073) — org-wide ROADMAP.md (Phase 0 parent) +- [common#1073](https://github.com/projectbluefin/common/pull/1073) — proposed org-wide ROADMAP.md (open PR; Phase 0 parent if adopted) - [common#1058](https://github.com/projectbluefin/common/issues/1058) — reviewer coverage map / repo-concentration data - [common#1067](https://github.com/projectbluefin/common/issues/1067) — user-issue triage starvation - [common#1043](https://github.com/projectbluefin/common/issues/1043) — hold-gate prioritization rubric From 0d488573a51b2dcc8528b8b9d6dde313853063c0 Mon Sep 17 00:00:00 2001 From: castrojo <1264109+castrojo@users.noreply.github.com> Date: Sat, 12 Sep 2026 08:34:24 -0400 Subject: [PATCH 4/4] docs(contributing): mark roadmap reference as landed #1073 lands first in this batch; update the two parentheticals that described it as open/not-yet-adopted. Assisted-by: Kimi K3 via GitHub Copilot --- docs/contributing/reviewer-ladder.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/contributing/reviewer-ladder.md b/docs/contributing/reviewer-ladder.md index 1a6ea307..40d48528 100644 --- a/docs/contributing/reviewer-ladder.md +++ b/docs/contributing/reviewer-ladder.md @@ -2,7 +2,7 @@ > **Status**: hold-gated planning artifact. Human review required before adoption. > Filed by the strategist agent. Tracks [common#1029](https://github.com/projectbluefin/common/issues/1029); -> Proposed alongside the org-wide roadmap in [common#1073](https://github.com/projectbluefin/common/pull/1073) (open, not yet adopted). +> Proposed alongside the org-wide roadmap in [common#1073](https://github.com/projectbluefin/common/pull/1073) (landed as ROADMAP.md; its phases remain proposals). > > Nothing below changes GitHub roles, branch protection, CODEOWNERS, workflow behavior, > or hold-gate enforcement until a maintainer adopts it. @@ -101,7 +101,7 @@ draft operating measures: ## Related - [common#1029](https://github.com/projectbluefin/common/issues/1029) — reviewer-scaling rung finding (this doc's tracker) -- [common#1073](https://github.com/projectbluefin/common/pull/1073) — proposed org-wide ROADMAP.md (open PR; Phase 0 parent if adopted) +- [common#1073](https://github.com/projectbluefin/common/pull/1073) — org-wide ROADMAP.md (Phase 0 parent) - [common#1058](https://github.com/projectbluefin/common/issues/1058) — reviewer coverage map / repo-concentration data - [common#1067](https://github.com/projectbluefin/common/issues/1067) — user-issue triage starvation - [common#1043](https://github.com/projectbluefin/common/issues/1043) — hold-gate prioritization rubric