Skip to content

[Phase 1] ADR: pull-request-limits mechanism + policy decision #506

Closed
#514
Closed
[Phase 1] ADR: pull-request-limits mechanism + policy decision#506
#514
Labels
dev-leadFor dev-lead agent pickupinitiative

Description

@don-petry
don-petry
opened on Jun 21, 2026

Story

As a platform maintainer,
I want a decision record that pins down exactly how GitHub's pull request limits work and the policy we will adopt,
so that the implementation stories encode the right mechanism without guessing the API or baking in unconfirmed numbers.

Acceptance Criteria

  1. A decision doc is added under docs/ (alongside the existing docs/initiatives/*.md analyses) that identifies the exact surface GitHub exposes for pull request limits - repository setting vs. organization setting vs. repository ruleset rule - with a citation to GitHub's official docs/announcement.
  2. The doc records the precise programmatic mechanism (the REST/GraphQL endpoint or settings/ruleset field needed to set the limit), OR explicitly records, with evidence, that the feature is UI-only with no API.
  3. The doc enumerates the automation PR sources this targets (Dependabot, auto-rebase fan-out, dev-lead, initiative-driver), a measured baseline of current open automation-PR volume, and proposes candidate limit value(s) and an exempt-actor list - explicitly marked as proposals pending human sign-off, not final.
  4. The doc states how the chosen mechanism maps onto this repo's existing settings-application pattern (scripts/apply-repo-settings.sh and/or .github/rulesets/) and names the unambiguous integration point for Story 2, including how the new limit reconciles with the existing Dependabot open-pull-requests-limit.
  5. No repository setting, ruleset, or org policy is mutated by this story - it is documentation only.

Tasks / Subtasks

Dev Notes

  • This repo applies repository settings programmatically via scripts/apply-repo-settings.sh (gh api PATCH to repo settings + check-suites preferences); branch rulesets are stored as JSON under .github/rulesets/ (e.g. code-quality.json). The ADR must decide which of these two surfaces PR limits live in.
  • Key gap to record: .github/rulesets/code-quality.json is checked in but NO in-repo workflow applies it, and scripts/apply-repo-settings.sh is not invoked by any workflow in this repo (verified by grep). 'Enabling' a limit therefore requires an apply path (Story 3), not just config (Story 2). The ADR must note where the org actually applies rulesets/settings today (likely the central petry-projects/.github standards repo).
  • The existing Dependabot open-pull-requests-limit: 10 (.github/dependabot.yml) is the current ecosystem-scoped form of a PR limit; the new feature is broader. The ADR must reconcile the two so Dependabot is not double-capped.
  • Cite GitHub's own docs for the exact API/settings field - never guess the API shape (org standard: SHAs and API surfaces are looked up, not guessed). If the feature is UI-only, the ADR must say so and Stories 2/3 adjust accordingly.
  • Output is a doc only; follow the docs/initiatives/*.md style (see idea-to-initiative-pipeline.md). WebFetch of the blog was unavailable to the planner, so first-hand confirmation of the mechanism is part of this story's work.

Project Structure Notes

New doc belongs under docs/initiatives/ alongside the existing initiative analyses. No code paths are touched.

References

  • scripts/apply-repo-settings.sh
  • .github/rulesets/code-quality.json
  • .github/dependabot.yml
  • scripts/list-prs.sh
  • docs/initiatives/idea-to-initiative-pipeline.md
  • .github/copilot-instructions.md

Likely target surface

  • docs/initiatives/

Story prepared by the BMAD Scrum Master (Bob) for epic #505. Status: ready-for-dev.

Activity

  1. don-petry
    added
    initiative
    on Jun 21, 2026
  2. don-petry
    added a parent issue on Jun 21, 2026
  3. don-petry
    marked this as blocking on Jun 21, 2026
  4. don-petry
    added
    dev-leadFor dev-lead agent pickup
    on Jun 21, 2026

  5. don-petry commented on Jun 21, 2026

    @don-petry
    don-petry
    on Jun 21, 2026
    ContributorAuthor

    Dev-Lead Implementation Plan

    Issue: #506 — [Phase 1] ADR: pull-request-limits mechanism + policy decision

    Scope

    Add a documentation-only ADR that records, with first-hand citations to GitHub's official docs, exactly which surface (repo setting / org setting / ruleset rule / API / UI-only) GitHub exposes for a "max open pull requests" limit, the measured automation-PR baseline, proposed (non-final) limit values + exempt-actor list, and the unambiguous Story 2 integration point against this repo's existing settings-application pattern.

    Research findings already gathered (first-hand, this session)

    • Ruleset rules (available-rules-for-rulesets): enumerated all rule types — none limits open-PR count.
    • Repo settings (REST PATCH /repos/{owner}/{repo}): no max-open-PR-count field.
    • Org settings (org PR-review settings): only "code review limits" (who may approve) — no count cap.
    • Conclusion (evidence-based): GitHub exposes no native "max open PRs per repo/org" surface; the only native count cap is Dependabot's ecosystem-scoped open-pull-requests-limit.
    • Measured baseline (gh, org-wide, open + non-draft): 47 total — dev-lead/* 30, dependabot/* 10, claude/* 4, human ~3. In .github repo: 10 (7 agent + 3 dependabot). Auto-rebase authors no PRs (it updates existing branches → CI-load amplifier, not a PR source).
    • Apply-path gap confirmed: no workflow invokes scripts/apply-repo-settings.sh or scripts/apply-rulesets.sh (grep) — they are manual admin runs.
    • Issue premise correction: .github/rulesets/code-quality.json does not exist in this repo; rulesets are generated programmatically by scripts/apply-rulesets.sh (build_ruleset_json).

    Implementation Checklist

    • Create docs/initiatives/pull-request-limits-adr.md (new docs/initiatives/ dir)
      • AC#1: surface identification + citations
      • AC#2: precise mechanism, or evidence it is not API/ruleset/setting-exposed
      • AC#3: automation PR sources + measured baseline + proposed limits/exemptions (marked proposals)
      • AC#4: mapping to apply-repo-settings.sh / apply-rulesets.sh, named Story 2 integration point, Dependabot reconciliation
      • AC#5: documentation only — no settings/ruleset/org mutation

    Tests to Write

    • None — pure documentation (Phase 2 TDD exception). Verification is markdown lint + repo lint.

    Test Command

    bash .dev-lead/scripts/dev-lead-lint.sh and npx markdownlint-cli2 docs/initiatives/pull-request-limits-adr.md

  6. don-petry commented on Jun 21, 2026

    @don-petry
    don-petry
    on Jun 21, 2026
    ContributorAuthor

    Dev-Lead: Implementation Complete

    Plan Execution

    Key findings (verified, not guessed)

    • No native "max open PRs" surface exists. Confirmed against three GitHub doc surfaces: ruleset rules list (no such rule), REST PATCH /repos/{owner}/{repo} (no such field), org PR-review settings (only "who may approve", no count cap). The only native count cap is Dependabot's per-ecosystem open-pull-requests-limit.
    • Decision: the non-Dependabot cap must be a source-side admission gate in the PR-creating automation, NOT a field in either apply script (no GitHub surface to receive it). Story 3 = apply path, since no workflow runs the apply scripts today (confirmed by grep).
    • Measured baseline (2026-06-21, org-wide, open + non-draft): 47 total — dev-lead 30, dependabot 10, claude 4, human ~3 (~94% machine-authored). This repo only: 10.
    • Issue-premise corrections recorded in the ADR: (1) .github/rulesets/code-quality.json does not exist — rulesets are generated programmatically by apply-rulesets.sh; (2) auto-rebase fan-out authors no PRs (it updates existing branches → CI-load amplifier, not a PR source).
    • Honesty note (AC Add multi-agent isolation strategy using git worktrees #2): WebSearch was unavailable and the changelog index 404'd; the three documentation surfaces were fetched first-hand. A human with changelog access should confirm no preview feature exists before Stories 2/3 finalize.

    Test Results

    Pure documentation — Phase 2 (test-first) skipped per the documentation exception. Verification was lint + markdownlint:

    === repo lint (.dev-lead/scripts/dev-lead-lint.sh) ===
  [lint] shellcheck on 14 file(s)...
  [lint] validating .github/CODEOWNERS...
OK: .github/CODEOWNERS
  [lint] all checks passed
lint-exit:0

=== markdownlint-cli2 docs/initiatives/pull-request-limits-adr.md ===
Linting: 1 file(s)
Summary: 0 error(s)

    Files Changed

    • docs/initiatives/pull-request-limits-adr.md (new): the ADR — mechanism research with citations, automation-source inventory, measured baseline, proposed (non-final) limits + exempt list, settings-pattern mapping with the named Story 2 integration point, and Dependabot reconciliation.

    Notes

  7. don-petry
    closed this as completedin #514on Jun 21, 2026
  8. don-petry
    added a commit that references this issue on Jun 21, 2026

    feat: implement issue #506 — [Phase 1] ADR: pull-request-limits mecha…

    91d8a73
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    dev-leadFor dev-lead agent pickupinitiative

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions