[Phase 6] Weekly-budget glide-path breaker: pause at 100 − 2×days-until-reset of the 7-day Claude window

[don-petry]

Story

As a platform engineer / org-lead,
I want the agent fleet to pause automatically when the rolling 7-day Claude subscription budget crosses a threshold that tightens as the weekly reset approaches — reserving ~2% of the weekly budget per remaining day — so that the fleet cannot burn the whole week's budget in the first two days,
so that a human always has usable Claude headroom for the rest of the week, and the maintainer no longer has to notice budget pressure manually and withhold a secret to stop the bleeding.

Context — why this is separate from #641

Phase 5 (#641) breaks on the 5-hour window at a static threshold (default 90%). That protects against a short burst, but it is blind to the shape of the week: the fleet can sit under 90% of every 5-hour window and still exhaust the 7-day budget by Thursday, leaving four days with nothing for humans.

This story adds the orthogonal control — a time-varying threshold on the 7-day window:

pause when  weekly_all.percent  >=  100 - (reserve_pct_per_day * days_until_weekly_reset)

With reserve_pct_per_day = 2 and the reset derived from the API's resets_at (Tuesday ~11:00 America/Chicago, confirmed by live probe — see #637):

Day (relative to reset)	Days left	Pause at
Tuesday (reset day)	0	100%
Monday	1	98%
Sunday	2	96%
Saturday	3	94%
Friday	4	92%
Thursday	5	90%
Wednesday	6	88%
Tuesday (just reset)	7	86%

The floor of 86% immediately after a reset is intentional: it is the "don't spend the whole week on day one" guard. The ceiling of 100% on reset day is also intentional: with the budget minutes from refilling, there is nothing left to protect.

Motivating observation (2026-08-20): a live probe of the usage endpoint showed the account-wide weekly window at 85% with five days left before reset — one point under this story's Thursday threshold, with a model-scoped weekly limit already exhausted. The #641 5-hour breaker would not have fired at any point on that path.

Prerequisites

• Phase 1 ADR ([Phase 1] ADR: agent rate-limit & circuit-breaker taxonomy (decision record) #637) — telemetry source. Resolved: GET https://api.anthropic.com/api/oauth/usage verified first-hand; see the ADR comment for endpoint, headers, response schema, and risks.
• Phase 2 config ([Phase 2] standards/agent-rate-limits.json config + standard doc (single source of truth) #638) — this story adds a seven_day block beside Phase 5's five_hour block.
• Phase 3 gate library ([Phase 3] scripts/lib/agent-rate-limit.sh gate + circuit-breaker library (guard-only) #639) — this story extends the same gate.
• Shares the telemetry adapter introduced by Phase 5 ([Phase 5] Token-budget circuit breaker: pause at the configured % of the 5-hour Claude window #641). If [Phase 5] Token-budget circuit breaker: pause at the configured % of the 5-hour Claude window #641 lands first, extend its adapter; if this lands first, build the adapter to serve both windows from the single call.
• Cross-repo companion (private): the hourly poller, the credential, and the org-variable write live in petry-projects/.github-private. Filed separately.
• The pause switch itself already exists: AGENTS_PAUSED=true (Actions variable, chosen because variables are visible where secrets are not), delivered by .github-private#1525. This story automates setting and clearing it; it does not redesign it.

Acceptance Criteria

1. The gate evaluates a 7-day glide-path threshold from an org_wide.token_budget.seven_day block in standards/agent-rate-limits.json — at minimum enabled, reserve_pct_per_day (default 2), floor_pct, and ceiling_pct. No threshold is hardcoded, and the schedule is expressible purely as config.
2. days_until_reset is derived from the telemetry payload's resets_at, never from a hardcoded weekday, cron expression, or timezone constant. Partial days round up, so the day before reset evaluates as 1 day left (98%), not 0.
3. The evaluation keys on the account-wide weekly window (limits[].kind == "weekly_all"). A weekly_scoped (per-model) limit at critical / is_active must not trip a fleet pause — the correct response to scoped exhaustion is the engine's existing model-fallback chain. This distinction is asserted by a test.
4. On trip, the pause is surfaced through the existing human-clearable marker/label convention used by the rest of the library, and the reason is machine-readable (which window, observed percent, threshold, reset timestamp) rather than prose buried in a log line.
5. Telemetry failure (non-200, malformed body, missing weekly_all entry) degrades to allow-with-warning per the ADR's documented default — an outage of an undocumented third-party endpoint must never stop the fleet.
6. tests/test_agent_rate_limit_weekly_glide.bats exercises a mocked telemetry source: threshold at each day-offset 0–7, boundary conditions (exactly at threshold trips; one point under does not), partial-day rounding, scoped-limit-must-not-trip (AC Add coding standards & principles section to AGENTS.md #3), and telemetry-unavailable fail-safe (AC Add stacked PR strategy and Epic-level workflow guidance #5). No live network.
7. Rollout is dry-run first — the gate logs the decision it would have made for a full week before it can defer anything — and activation respects the epic's Phase-2 human sign-off gate.

Tasks / Subtasks

• Add the seven_day glide-path block to standards/agent-rate-limits.json + companion doc (AC: Addressing PR comments #1)
• Implement days_until_reset from resets_at with round-up semantics (AC: Add multi-agent isolation strategy using git worktrees #2)
• Add the glide-path evaluation to scripts/lib/agent-rate-limit.sh, keyed on weekly_all and ignoring weekly_scoped (AC: Add coding standards & principles section to AGENTS.md #3)
• Emit a structured trip reason through the existing marker/label convention (AC: Add workflow, environment, and orchestration guidance #4)
• Wire the allow-with-warning degradation path (AC: Add stacked PR strategy and Epic-level workflow guidance #5)
• Write tests/test_agent_rate_limit_weekly_glide.bats with a mocked source (AC: feat: add Structured Logging and CQRS standards #6)
• Dry-run rollout + promotion doc; keep everything config-driven (AC: docs: document branch protection rules, rulesets, and auto-merge policy #7)

Dev Notes

• Pause semantics: the breaker gates new dispatch only. In-flight runs finish under the existing per-tier engine timeouts — killing work mid-flight wastes the tokens already spent and leaves PRs in a partial state.
• Auto-clear is the subtle half. The pause must record that it set AGENTS_PAUSED, so the auto-resume after the weekly reset clears only its own pause and never a pause a human set deliberately. A companion marker (e.g. AGENTS_PAUSE_SOURCE=weekly-glide) is the cheapest way; the resume path checks it before clearing. Without this, an automated resume silently overrides a maintainer's decision — the inverse of the failure .github-private#1525 was filed to fix.
• Hysteresis: once tripped, do not un-trip merely because usage percentage ticks back under the line (it will not — utilization is monotonic within a window). The only clean resume is the window reset, which is exactly what resets_at gives.
• Non-goal: this story does not change model selection, the engine fallback chain, or the 5-hour breaker.
• TDD (AGENTS.md): unit tests mock the telemetry source; no live network.

Project Structure Notes

Extends scripts/lib/agent-rate-limit.sh (Phase 3) and standards/agent-rate-limits.json (Phase 2), reusing Phase 5's telemetry adapter. New test under tests/. The poller and the org-variable write are cross-repo (private).

References

• Epic Agentic Activity Circuit Breakers & Org-Wide Rate-Limiting Standard #636 — Agentic Activity Circuit Breakers & Org-Wide Rate-Limiting Standard
• [Phase 1] ADR: agent rate-limit & circuit-breaker taxonomy (decision record) #637 — Phase 1 ADR (telemetry source; see the usage-endpoint finding comment)
• [Phase 5] Token-budget circuit breaker: pause at the configured % of the 5-hour Claude window #641 — Phase 5, the 5-hour static breaker this complements
• petry-projects/.github-private#1525 — AGENTS_PAUSED as a first-class state (the switch this automates)

Likely target surface

• standards/agent-rate-limits.json (extend — seven_day glide block)
• scripts/lib/agent-rate-limit.sh (extend — weekly glide evaluation)
• tests/test_agent_rate_limit_weekly_glide.bats (new)

Filed as the follow-on to #641 for epic #636. Inert until a maintainer arms the epic.

---

⚠️ Post-ADR / post-#641 clarification (added 2026-08-31 — read before implementing)

Phases 1–5 are all merged: the ADR (#637/PR #995), the config (#638/PR #1017), the gate library (#639/PR #1018), and the token-budget breaker (#641/PR #1020). This story's ACs are already consistent with the ADR — the notes below are about reusing what now exists rather than rebuilding it.

1. The adapter already exists and already serves this window — extend it

#641 landed with the adapter built to serve both session and weekly_all from a single call (ADR §4.1: "Both breakers share one call"), specifically so this story extends rather than refactors. scripts/lib/agent-rate-limit.sh on main now carries the arl_token_* family, including:

• percent extraction preferring the limits[] array with the flattened five_hour/seven_day keys as fallback — weekly_all already maps to seven_day;
• an is_active check and the pause_worthy scope guard (weekly_scoped is false in config);
• fail-safe degradation to allow on malformed/missing/unreadable telemetry, plus a timeout on the telemetry command;
• a stale-429 guard — a cached 429 envelope whose retry_until (or observed_at + retry_after) has passed is treated as expired degraded telemetry and allows, rather than deferring forever.

Add the glide-path threshold on top of this. Do not introduce a second telemetry path, a second fail-safe convention, or a second percent extractor.

2. Terminology

The story says "rolling 7-day". The weekly_all window is a fixed window with an authoritative resets_at (ADR §4.1) — it accumulates until the reset; old usage does not age out continuously. Please use "fixed" / "weekly window" in code comments and the standard doc. (AC #2's round-up days_until_reset derivation from resets_at is already correct and unaffected.)

3. What makes this breaker genuinely different — keep it explicit

Unlike the session breaker, this one can close before resets_at — but never because utilization fell. The glide-path threshold 100 - (reserve_pct_per_day * days_until_reset) rises as the reset approaches, so the breaker re-evaluates each poll and may close because the threshold moved past a static percent. State that in the code comment; it is the single most misread part of the design, and conflating it with the session breaker's "resets_at only" rule in either direction is the bug to avoid. There is still no percentage resume mark for either breaker.

4. reserve_pct_per_day is already in config

standards/agent-rate-limits.json carries org_wide.token_budget.limits.weekly_all.reserve_pct_per_day (default 2), inert pending sign-off. Read it; never hardcode. Its _note already records the rising-threshold semantics.

5. Actuation stays out of scope

AC-wise this story is the gate/threshold. Writing the org-level AGENTS_PAUSED variable, the poller, and the AGENTS_PAUSE_SOURCE marker are the private companion (.github-private#1565), which additionally needs admin:org or fine-grained org Variables: write — plain repo/workflow/read:org gets 403 even for an org admin. The auto-clear invariant in the Dev Notes (an automated resume must never clear a pause a human set) still belongs to that companion; keep this story's surface to the decision.

[don-petry]

Cross-repo companion filed: petry-projects/.github-private#1565 — the usage-telemetry adapter, the scheduled poller, and the AGENTS_PAUSED set/clear actuation (they need the Claude credential, which lives in the private repo). It also carries the two open verification items from the spike: whether the long-lived claude setup-token credential is accepted by the usage endpoint, and whether GH_PAT_DON_PETRY can write org-level Actions variables.

[don-petry]

Dev-Lead Implementation Plan

Issue: #994 — [Phase 6] Weekly-budget glide-path breaker: pause at 100 − 2×days-until-reset of the 7-day Claude window

Scope

Add a config-driven, time-varying glide-path breaker on the account-wide weekly_all (7-day, fixed) Claude window — pausing new dispatch when weekly_all.percent >= clamp(ceiling_pct − reserve_pct_per_day × days_until_reset, floor_pct, ceiling_pct) — extending the Phase-5 telemetry adapter/gate rather than rebuilding it.

Implementation Checklist

• standards/agent-rate-limits.json — extend org_wide.token_budget.limits.weekly_all with enabled (inert), floor_pct (86), ceiling_pct (100); keep reserve_pct_per_day (2). Update its _note (rising-threshold, no percentage resume).
• scripts/lib/agent-rate-limit.sh — add glide config accessors, days_until_reset (round-up, pure), iso_to_epoch, resets_at extractor, glide_threshold (pure clamp), arl_token_weekly_glide_gate, structured glide_trip_reason (AC Add workflow, environment, and orchestration guidance #4); extract a shared telemetry-transport precheck reused by both breakers (single fail-safe convention).
• Wire the glide gate into arl_admission_gate behind the existing AGENT_TOKEN_BUDGET_ENABLED arm (defer surfaces the human-clearable marker/label).
• standards/agent-rate-limits.md — document the weekly glide gate + config keys + staged dry-run rollout (AC docs: document branch protection rules, rulesets, and auto-merge policy #7), no restated numbers.
• .github/workflows/agent-rate-limits-tests.yml — add the new test file to paths + run step.

Tests to Write

• tests/test_agent_rate_limit_weekly_glide.bats (mocked telemetry, no network):
  • threshold at each day-offset 0–7 (100→86); floor/ceiling clamp
  • days_until_reset round-up (partial day → 1, not 0); at/after reset → 0
  • boundary: exactly at threshold trips, one point under does not
  • scoped-limit-must-not-trip (AC Add coding standards & principles section to AGENTS.md #3): weekly_scoped critical/is_active does not trip
  • telemetry-unavailable / non-200 / missing window / missing resets_at fail-safe → allow (AC Add stacked PR strategy and Epic-level workflow guidance #5); fresh 429 → defer
  • structured machine-readable trip reason fields (AC Add workflow, environment, and orchestration guidance #4)
  • integration: inert when config enabled=false or env flag unset; defers when armed+tripped; DRY_RUN prints would-be defer but returns allow; set -euo pipefail-safe

Test Command

bats --print-output-on-failure tests/test_agent_rate_limit_weekly_glide.bats tests/test_agent_rate_limits_config.bats tests/test_agent_rate_limit_token_budget.bats tests/test_agent_rate_limit.bats

[don-petry]

Dev-Lead: Implementation Complete

Extended the Phase-5 (#641) telemetry adapter/gate with the 7-day weekly-budget glide-path breaker — no second telemetry path, no second fail-safe convention, no second percent extractor.

Plan Execution

• Extended org_wide.token_budget.limits.weekly_all with enabled (inert), floor_pct (86), ceiling_pct (100); kept reserve_pct_per_day (2); updated _note (rising-threshold, no percentage resume) (AC Addressing PR comments #1)
• days_until_reset from resets_at with round-up semantics — pure arl_token_days_until_reset + arl_token_iso_to_epoch (AC Add multi-agent isolation strategy using git worktrees #2)
• Glide evaluation keyed on weekly_all, ignoring weekly_scoped — arl_token_weekly_glide_gate reusing the pure decision core + pause-worthy scope guard (AC Add coding standards & principles section to AGENTS.md #3)
• Machine-readable trip reason arl_token_glide_trip_reason → {window, observed_percent, threshold_pct, days_until_reset, resets_at}, surfaced through the existing arl_token_breaker_marker weekly_all / arl_breaker_label marker+label convention (AC Add workflow, environment, and orchestration guidance #4)
• Allow-with-warning degradation on non-200 / malformed / missing window / missing-or-unparseable resets_at; fresh 429 still blocks — via the shared arl_token_transport_decision extracted from the session gate (AC Add stacked PR strategy and Epic-level workflow guidance #5)
• tests/test_agent_rate_limit_weekly_glide.bats — mocked telemetry, no live network (AC feat: add Structured Logging and CQRS standards #6)
• Dry-run rollout: config-level weekly_all.enabled arm (independent of the AGENT_TOKEN_BUDGET_ENABLED env flag) + DRY_RUN path; documented in standards/agent-rate-limits.md §4.1/§4.2 (AC docs: document branch protection rules, rulesets, and auto-merge policy #7)
• Wired into arl_admission_gate behind the existing env arm; added the new test to agent-rate-limits-tests.yml

Test Results

test_agent_rate_limit_weekly_glide.bats   44 tests, 0 failed
test_agent_rate_limit_token_budget.bats   49 tests, 0 failed   (unchanged after shared-helper refactor)
test_agent_rate_limits_config.bats        27 tests, 0 failed
test_agent_rate_limit.bats                51 tests, 0 failed
canary_rollout.bats                      257 tests, 0 failed
persona_mention.bats                      42 tests, 0 failed
test_bootstrap_new_repo.bats              15 tests, 0 failed
test_seed_repo_template_gitignore.bats     4 tests, 0 failed
test_seed_repo_template_workflows.bats    10 tests, 0 failed
TOTAL FAILED across all bats: 0

dev-lead-lint.sh: all checks passed (shellcheck 30 files + CODEOWNERS)
shellcheck -S warning scripts/lib/agent-rate-limit.sh: clean

Files Changed

• standards/agent-rate-limits.json — weekly_all glide block gains enabled/floor_pct/ceiling_pct; threshold clamp(ceiling_pct − reserve_pct_per_day × days_until_reset, floor_pct, ceiling_pct) fully config-expressible.
• scripts/lib/agent-rate-limit.sh — new: arl_token_glide_{int,reserve,floor,ceiling,enabled}, arl_token_iso_to_epoch, arl_token_days_until_reset (pure, round-up), arl_token_glide_threshold (pure clamp), arl_token_extract_resets_at, arl_token_glide_trip_reason, arl_token_weekly_glide_gate; extracted shared arl_token_transport_decision (one 429/non-200 convention); wired glide into arl_admission_gate.
• standards/agent-rate-limits.md — §4.1 documents the glide gate + the "can close before resets_at because the threshold rose, never because usage fell" differentiator; §4.2 documents the config-level enabled dry-run arm.
• .github/workflows/agent-rate-limits-tests.yml — new test file added to paths + run step + header comment.

Notes

• No hardcoded threshold or weekday. The whole schedule is weekly_all config keys; days_until_reset is derived from the payload resets_at.
• Stateless per-poll, no resume mark. The breaker can close before resets_at only because the rising threshold passed a static (monotonic) percent — a dedicated test asserts this (same 91% trips at 5 days-left/threshold 90, closes at 4 days-left/threshold 92). A downward percentage dip (impossible in a fixed window) is structurally unable to un-trip it.
• Boundary + rounding coverage: threshold at each day-offset 0–7 (100→86), floor/ceiling clamp, exactly-at-threshold trips, one-point-under does not, 12h-left rounds up to 1 day (98%).
• Fail-safe: telemetry-unavailable / non-200 / missing window / missing resets_at all allow-with-warning; fresh 429 blocks; expired 429 window allows.
• Ships inert: off unless both AGENT_TOKEN_BUDGET_ENABLED=true (env) and weekly_all.enabled=true (config, provisional, pending epic Agentic Activity Circuit Breakers & Org-Wide Rate-Limiting Standard #636 sign-off).
• Out of scope (private companion #1565): writing AGENT_TOKEN_PAUSED/AGENTS_PAUSED, the poller, AGENTS_PAUSE_SOURCE, and the auto-clear invariant. This story is the gate/threshold only.