[Phase 2] standards/agent-rate-limits.json config + standard doc (single source of truth)

[don-petry]

Story

As a platform engineer,
I want add standards/agent-rate-limits.json as the machine-readable single source of truth for per-agent-type limits, with a standards/agent-rate-limits.md companion and a JSON contract test,
so that every gate and workflow reads limits from one signed-off file instead of hardcoding them in scripts.

Acceptance Criteria

1. standards/agent-rate-limits.json exists and mirrors the shape of standards/pr-limits.json: a _schema_version, inline _note fields recording the human sign-off + rationale, a per-agent-type map of controls, and exempt-actor / exempt-label lists.
2. Per the ADR taxonomy, each in-scope agent type carries max_concurrent_runs, max_runtime_minutes, cooldown_minutes, daily_run_budget, and a circuit_breaker (consecutive_failure_threshold + pause/backoff duration); plus an org_wide token_budget block with the 5-hour-window threshold (default 90%) and a Claude-priority flag.
3. The config is inert on merge: values are documented as requiring human sign-off before any gate enforces them (mirroring the pr-limits sign-off gate), and no workflow reads it yet.
4. A bats contract test asserts the file is parseable JSON, required keys are present, numeric limits are positive integers, and the token threshold is within range — mirroring the pr-limits config contract.
5. standards/agent-rate-limits.md documents each control and cites the ADR as the decision record and, like pr-limits.md, does NOT restate the changeable numeric values in prose (it points readers at the JSON).
6. The AGENTS.md standards table gains a row linking the new standard, keeping standards discoverable.
7. The per-agent daily_run_budget is documented in agent-rate-limits.md as the concrete per-agent cost bound, so the epic's cost cap is traceable to a specific config key.

Tasks / Subtasks

• Author standards/agent-rate-limits.json mirroring pr-limits.json (schema_version, _note sign-off, per-agent map, exempt lists) (AC: Addressing PR comments #1, Add multi-agent isolation strategy using git worktrees #2)
• Encode the org_wide token_budget block (5-hour window, 90% default, Claude priority) (AC: Add multi-agent isolation strategy using git worktrees #2)
• Mark the config inert pending human sign-off; add no consumer wiring (AC: Add coding standards & principles section to AGENTS.md #3)
• Add tests/test_agent_rate_limits_config.bats contract test (parseable, keys, ranges) (AC: Add workflow, environment, and orchestration guidance #4)
• Write standards/agent-rate-limits.md companion citing the ADR, without restating numbers, and naming daily_run_budget as the per-agent cost bound (AC: Add stacked PR strategy and Epic-level workflow guidance #5, docs: document branch protection rules, rulesets, and auto-merge policy #7)
• Add the standard to the AGENTS.md standards table (AC: feat: add Structured Logging and CQRS standards #6)

Dev Notes

• Mirror standards/pr-limits.json (petry-projects/.github) in spirit: it carries status: signed-off, a top-level _note with the human sign-off date + epic/gate reference, a _schema_version, an org_wide block, an (intentionally empty) per_source_caps map, and exempt_actors / exempt_labels. Reuse the exempt_actors set (dependabot[bot], @petry-projects/org-leads break-glass, etc.) so the same actors bypass rate limits.
• The pr-limits standard doc deliberately does NOT restate the numeric cap in prose ('a changeable value stated in prose is a second place to forget to update'); the reader runs jq over the JSON. Follow that convention exactly in agent-rate-limits.md.
• Per AGENTS.md: 'all standards and rulesets belong in .github/standards/'; the standards table at the top of AGENTS.md is the discovery index — add a row like the existing 'PR limits' row.
• Tests: the repo uses bats under tests/ (e.g. canary_rollout.bats, test_bootstrap_new_repo.bats); TDD is mandatory per AGENTS.md (tests in the same PR). The config contract test mirrors how pr-limits.json validity is asserted.
• Do NOT activate values: like the pr-limits config's sign-off gate (epic Enable GitHub pull request limits to cut automation-PR noise #505 gate [Phase 3 gate] Human sign-off: final PR-limit caps + exempt list + rollout scope #566), the numbers require human sign-off. The config is a data file; the gate library (Phase 3) and wiring (Phases 4-5) consume it later.

Project Structure Notes

New files land under standards/ in the target public repo, next to pr-limits.json / pr-limits.md. Test lands under tests/ per the repo bats convention.

References

• standards/pr-limits.json (petry-projects/.github — config shape and single-source-of-truth pattern to mirror)
• standards/pr-limits.md (petry-projects/.github — companion-doc convention: never restate numbers)
• AGENTS.md

Likely target surface

• standards/agent-rate-limits.json (new — machine-readable per-agent limits)
• standards/agent-rate-limits.md (new — companion standard doc)
• tests/test_agent_rate_limits_config.bats (new — JSON contract test)
• AGENTS.md

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