[Phase 5] Token-budget circuit breaker: pause at the configured % of the 5-hour Claude window

[don-petry]

Story

As a platform engineer / org-lead,
I want implement the token-budget circuit breaker that pauses new agentic dispatch when the rolling 5-hour Claude subscription budget reaches the configured threshold (default 90%), prioritizing Claude-backed agents, using the telemetry source selected in the Phase-1 ADR,
so that agents stop before they exhaust the shared 5-hour Claude budget, so a runaway cannot fully block the fleet and humans — the failure mode raised in the discussion.

Acceptance Criteria

1. A token-budget check, reading the org_wide token_budget block from standards/agent-rate-limits.json (threshold default 90%, Claude-priority flag), integrates into the agent-rate-limit gate so a dispatch is deferred when the rolling 5-hour Claude subscription budget is at/over the threshold.
2. The check consumes the telemetry source selected in the Phase-1 ADR for the 5-hour window, behind a small adapter; if that source is unavailable at runtime it fails safe (documented default) rather than crashing the dispatch.
3. When the breaker is tripped, Claude-backed agents are prioritized on the remaining budget / recovery per the config flag, and the pause is surfaced via the human-clearable marker/label used by the rest of the library.
4. The breaker is exercised by tests with a mocked telemetry source (at-threshold defers, under-threshold allows, source-unavailable fails safe) — no live network in unit tests.
5. Rollout is canary/dry-run first with a documented promotion path, and activation respects the Phase-2 human sign-off gate; the threshold stays config-driven (no hardcoded 90%).
6. Story 5 is completable regardless of the ADR's telemetry finding: if no windowed 5-hour source exists, the gate hook still ships — either backed by a coarse proxy (the private-repo per-run token totals) or shipped disabled behind the config flag — with the chosen degraded mode documented, so no AC depends on a source that may not exist.

Tasks / Subtasks

• Add a token-budget evaluation to the gate reading the org_wide token_budget block (AC: Addressing PR comments #1)
• Consume the ADR-selected 5-hour telemetry source behind an adapter; fail safe when unavailable (AC: Add multi-agent isolation strategy using git worktrees #2)
• Implement Claude-priority-on-recovery and marker/label surfacing on trip (AC: Add coding standards & principles section to AGENTS.md #3)
• Add tests/test_agent_rate_limit_token_budget.bats with a mocked telemetry source (AC: Add workflow, environment, and orchestration guidance #4)
• Canary/dry-run rollout + promotion doc; keep the threshold config-driven (AC: Add stacked PR strategy and Epic-level workflow guidance #5)
• Guarantee a completable degraded path (coarse proxy or disabled-behind-flag) when no windowed telemetry exists, per the ADR (AC: feat: add Structured Logging and CQRS standards #6)

Dev Notes

• This implements the discussion comment's explicit ask: 'Pause agentic work when the 5 hour budget reaches 90%. Claude as priority.' The 5-hour window is the rolling Claude subscription cap shared across all Claude models (private repo scripts/engine.sh, issue Monitor and Optimize Token Usage #206). Today the engine only reacts AFTER hitting the cap (exit-2 walks the model fallback chain); this story adds the PROACTIVE pre-dispatch check.
• The telemetry source is unresolved until the Phase-1 ADR selects it — do NOT assume a native GitHub surface exists (there is none for the 5-hour Claude budget; the Actions Data Stream is a 2026 roadmap item, and the private repo's token-metrics.sh emits per-run ET/JSONL, not a windowed budget %). Build the check against the ADR's selected source behind a small adapter so the source can change without touching the gate.
• Token accounting lives in the PRIVATE repo (token-metrics.sh ET formula + JSONL, model-pricing.tsv, token_report.sh aggregation). Reading a 5-hour windowed % from it is a cross-repo concern flagged as an untracked prerequisite; the adapter boundary keeps this story shippable in the public repo while the telemetry wiring lands separately.
• Fail-safe: mirror the defensive degradation in the existing libs — a missing/malformed telemetry read must not crash the dispatch; choose a documented default (allow-with-warning vs defer) in the ADR and encode it.
• TDD (AGENTS.md): unit tests mock the telemetry source; no live network.

Project Structure Notes

Extends scripts/lib/agent-rate-limit.sh (from Phase 3) with a token-budget evaluation + adapter; new test under tests/. The actual 5-hour telemetry wiring is cross-repo (private) and tracked as an untracked prerequisite.

References

• standards/pr-limits.json (petry-projects/.github — org_wide config block pattern reused for token_budget)
• scripts/engine.sh (private repo — 5-hour subscription-cap handling / exit-2 fallback, Monitor and Optimize Token Usage #206, cross-repo)
• scripts/lib/token-metrics.sh (private repo — ET formula + JSONL token telemetry, cross-repo)

Likely target surface

• scripts/lib/agent-rate-limit.sh (extend — add token-budget evaluation)
• tests/test_agent_rate_limit_token_budget.bats (new — mocked-telemetry tests)

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