Open-PR cap: refuse new-branch pushes at/above AUTOBOT_OPEN_PR_CAP (default 40) #17006

Owner decision (2026-09-18)

Sessions are opening new branches faster than PRs merge — 58 PRs were open at
the time of this decision. The owner capped open PRs, not branches: a
session must finish and merge (or close) existing work before starting new
work. CLAUDE.md:49 currently says the opposite ("There is no open-PR
limit...") and must be corrected in the same change that adds the gate.

Design

Where: the pre-push hook chain (tools/git-hooks/pre-push, installed by
scripts/install-git-hooks.sh into the shared .git/hooks/ dir used by the
main checkout and every worktree). This is where Phase 0c/Phase 6 already
enforce push-time policy, so the new gate rides the same chain rather than
adding a second, uninstalled one.

When it applies: only when the pushed ref is a refs/heads/* branch that
does not yet exist on the remote (remote_sha from git's pre-push stdin
protocol is all-zero) — i.e. a brand-new branch. A brand-new tag has a zero
remote_sha too but is exempt (a tag is never a PR head). A push to a branch
that already has an open PR is never blocked, so fixing existing work is
always possible.

What counts: open PRs in this repo whose head branch lives in this repo
(not a fork), excluding bot authors. Measured against this repo's own
dependabot history: gh's GraphQL author.login for a bot reports the
App-slug form app/dependabot (never the REST-style dependabot[bot]), with
is_bot: true — that field is what actually does the excluding; a
[bot]-suffixed-login check is kept only as a defensive fallback for a shape
not observed in this API. One gh pr list --state open --limit 1000 --json number,title,createdAt,author,isCrossRepository --jq '...' call, time-boxed,
returns both the filtered count and the oldest 10 (by createdAt) in one
round trip.

Cap: AUTOBOT_OPEN_PR_CAP, default 40. Documented in the hook's own
header comment (the precedent for a hook-only, bash-read AUTOBOT_* var is
AUTOBOT_PREPUSH_ALLOW_TIMEOUT in the same file — it is not in the Python
env_registry/ENV_VARS.md because that registry's pre-commit check
(pipeline-scripts/check_env_var_registry.py) only AST-scans .py files for
os.getenv("AUTOBOT_..."); a bash-only var has no home there).

At or above the cap: refuse the push. Message states the current count,
the cap, that pushes to existing PR branches still work, and lists the oldest
10 open PRs (number + title) to act on.

Fail closed: if gh is missing, unauthenticated, or the query fails, the
push is refused with a message saying the count could not be determined —
distinct from "under the cap" (measurement discipline: an empty/failed read
is not a true negative). No bypass flag, no env override that skips the
check — the only knob is the cap value.

Acceptance criteria

• tools/git-hooks/pre-push refuses a new-branch push once the
  filtered open-PR count is >= AUTOBOT_OPEN_PR_CAP (default 40), with a
  message giving the count, the cap, remediation, and the oldest 10 open
  PRs.
• A push to a branch that already exists on the remote is never
  blocked by this gate, even at/above the cap.
• The count excludes fork PRs (isCrossRepository == true) and bot
  authors (is_bot or a [bot]-suffixed login).
• gh missing / unauthenticated / query failure refuses the push with a
  "could not determine" message, never "allowed".
• No env var or flag bypasses the check; AUTOBOT_OPEN_PR_CAP is the only
  configurable input.
• The check is reachable from a clean clone via
  scripts/install-git-hooks.sh (proof it is wired into the installed
  chain, not just present in tools/git-hooks/).
• CLAUDE.md:49's "There is no open-PR limit" line is replaced with the
  new rule; docs/developer/*.md has no remaining contradicting text.
• Tests under repo_tests/ drive the real hook script (not a
  reimplementation) with a stubbed gh on PATH, covering: below cap
  (allowed), at cap (refused, message has count+cap), existing-branch
  push at cap (allowed), gh failure (refused, "could not determine"),
  bot-authored PRs excluded from the count.

Non-goals

• No change to branch/worktree limits — only open PRs are capped.
• No dispatch-side enforcement in this issue; that is a CLAUDE_BATCH.md /
  AGENT_COORDINATION.md doc note, not new code.