Skip to content

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

Merged
castrojo merged 1 commit into
projectbluefin:mainfrom
sramkrishna:strategy/agent-lane-throttle
Sep 23, 2026
Merged

docs(contributing): add agent-lane-throttle.md — demand-side throttle for the hold-gate queue#1197
castrojo merged 1 commit into
projectbluefin:mainfrom
sramkrishna:strategy/agent-lane-throttle

Conversation

@sramkrishna

@sramkrishna sramkrishna commented Sep 23, 2026

Copy link
Copy Markdown
Contributor

Planning Artifact

Adds docs/contributing/agent-lane-throttle.md, the demand-side proposal for the hold-gate review backlog tracked in #1052, plus a discovery entry in CONTRIBUTING.md alongside the existing reviewer-ladder bullet.

Contents

  • Problem — the review bottleneck has three levers; supply ([strategist] Contributor ladder has no reviewer-scaling rung — triage/review capacity is the org bottleneck (74 issues in 1-triage, 32 aged >60d) #1029) and ordering ([strategist] Hold-gated PR queue has no prioritization rubric — 61 PRs (2x in 48h) compete flat for scarce human review #1043) are drafted, demand had no mechanism. Queue depth is the mechanism, not just the symptom.
  • The burst is the failure mode, not the steady state — trajectory 33 → 61 in 48h → 74 in under 24h → 85 (2026-08-29/30) → 32 at the 2026-09-23 snapshot across 14 repos, max 6 in any repo. The 2026-09-23 state is below both thresholds, so the gate would be dormant today — the intended resting state.
  • Proposal — threshold-triggered, self-lifting filing gate: 8 open hold-gated PRs per repo, 60 org-wide. Non-P0 lanes (quality, scanner non-security, refactor/documentation, including this strategist lane) stand down; sec-check and release-gate ci-maintainer work keep filing; human-filed PRs are exempt entirely.
  • Optional per-lane WIP caps — scanner ≤5, quality ≤8 per repo until the org-wide queue drains below the ROADMAP target of <40.
  • Reversibility — a function of queue depth, not a schedule; nothing to switch off. It never closes, relabels, reverts, or deprioritizes an open PR.
  • Pairing with the P0/P1/P2 rubric and compliance with the seven-label contract — a filing gate, not a workflow state; adds no label and changes no transition.
  • Operating metrics and an explicit "what this document deliberately does not do" section.

Files claimed

  • docs/contributing/agent-lane-throttle.md (new, 221 lines)
  • CONTRIBUTING.md (+3 — discovery bullet under "Testing and style")

Conflict check

No overlap with the open prioritization-rubric PR #1188 (different file, different lane) — that draft supplies the P0/P1/P2 vocabulary this one consumes, and the two are independent: either can be adopted without the other. No workflow, CI, CODEOWNERS, branch-protection, or hold-gate enforcement change. No change to docs/skills/ or its generated index. docs/contributing/reviewer-ladder.md is untouched.

Refs #1052

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

— hive: backend=litellm model=deepseek/deepseek-v4.1-flash

🐝 Hive Agent: contributor | SHA: 534b986

@sramkrishna
docs(contributing): add agent-lane-throttle.md — demand-side throttle…
534b986 
… for the hold-gate queue

## What this adds

A planning artifact proposing the demand-side lever for the hold-gate review
backlog tracked in projectbluefin#1052: a threshold-triggered, self-lifting throttle on
agent-filed PRs, rather than a permanent ration.

## Why

The response to the review bottleneck has covered two of the three queueing
levers: supply (projectbluefin#1029 reviewer ladder) and ordering (projectbluefin#1043 prioritization
rubric). Demand — how much work agents file in the first place — had no
mechanism. This document is the concrete proposal for that third lever.

- Thresholds: 8 open hold-gated PRs per repo, 60 org-wide.
- Which lanes stand down: quality, scanner (non-security), refactor and
  documentation lanes, including this strategist lane.
- Which lanes keep filing: sec-check, and ci-maintainer work that repairs a
  release gate.
- Optional per-lane WIP caps (scanner <=5, quality <=8 per repo) until the
  org-wide queue drains below the ROADMAP target of <40.
- Reversibility: the throttle lifts on its own when the queue drains; no
  maintainer action is required to end it.

The burst, not the steady state, is the failure mode: the queue moved 33 -> 61
in 48h -> 74 in under 24h -> 85 over 2026-08-29/30, and sits at 32 across 14
repos at the 2026-09-23 snapshot. At those thresholds the gate would be dormant
today, which is the intended resting state. 121 hive-authored PRs merged since
2026-09-16 show the steady state does not need throttling.

## Scope

Documentation only. No workflow, CI, CODEOWNERS, branch-protection, or
hold-gate enforcement change. Nothing here alters permissions or repository
policy until a maintainer adopts it.

Refs projectbluefin#1052

Hive-Run: projectbluefin#1052
Hive-Plan: phase-0/agent-lane-throttle
Hive-Spec: acmm-hold-gate#agent-lane-throttle
Assisted-by: DeepSeek V4.1 Flash via GitHub Copilot
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: sramkrishna <sramkrishna@users.noreply.github.com>
@sramkrishna
sramkrishna requested review from a team and repires as code owners September 23, 2026 19:51
@sramkrishna sramkrishna mentioned this pull request Sep 23, 2026
Open
@castrojo
castrojo merged commit 70c2a97 into projectbluefin:main Sep 23, 2026
This was referenced Sep 23, 2026
Merged
Closed
castrojo pushed a commit that referenced this pull request Sep 25, 2026
@sramkrishna
docs(contributing): add self-collision preflight draft for intra-lane…
343bdc5 
… 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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@repires repires Awaiting requested review from repires repires is a code owner

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@sramkrishna @castrojo