friction: issue audit exhausts GitHub core API quota before closure coverage

[ll7]

Archetype Metadata

archetype: workflow
evidence_tier: idea
linked_policy:
  - docs/maintainer_values.md
  - docs/dev/agents/relocated-agents-guidance.md

Goal / Problem

Make the autonomous issue audit quota-aware when GitHub core REST capacity is exhausted. On
2026-09-02, the bounded command below returned a partial plan with 208 open issues but exited
fail-closed after the first closed-PR request and many issue-timeline requests hit HTTP 403 core API
rate limits. The artifact correctly withheld label mutations, but the audit spent its budget on
per-issue historical coverage and did not produce a useful complete queue result.

Observed command:

uv run python scripts/dev/issue_audit_core.py plan --mode autonomous --include-comments \
  --max-closed-pr-pages 50 --max-wall-seconds 420 --output <artifact>.json

Observed artifact: output/issue_audit_plan-20260902-after-8298.json at
origin/main=31704e5a110e77298390bc53d3f70077991d9d67.

Scope

• Add a quota-aware preflight and bounded fallback/skip path for closed-PR and issue-timeline
  enrichment.
• Preserve explicit inventory_uncertainties/incomplete coverage and fail-closed mutation behavior
  when the required inventory cannot be read.
• Add deterministic tests for exhausted, low, and recovered core quota responses, including the
  stable exit/report contract.
• Document the retry boundary or reset-aware next action in the audit output.

Out of scope: bypassing GitHub rate limits, mutating issue labels from incomplete evidence, changing
issue classification policy, or treating a partial audit as complete queue evidence.

Inputs

• scripts/dev/issue_audit_core.py and its existing inventory helpers.
• scripts/dev/github_quota.py and the repository GitHub transport policy.
• Existing issue-audit and GitHub transport tests.
• GitHub core-rate-limit response fields and reset timestamp when available.

Definition of Done

• The audit checks available core capacity before high-volume enrichment and bounds additional
  requests under the configured budget.
• Exhausted or insufficient quota yields a machine-readable incomplete/uncertain result with a
  reset-aware next action and zero unsafe mutations.
• A recovered quota permits the normal complete path without stale uncertainty leaking into a
  later run.
• Tests cover exhausted, low-budget, and recovered quota paths and assert no readiness or blocked
  label write is planned from incomplete evidence.
• Focused tests, lint/format, and the repository readiness path pass.

Success Metrics

• No audit run spends unbounded requests on historical enrichment after core capacity is known to be
  unavailable.
• Partial inventory is never reported as complete or used to promote an issue.
• The next retry time/reason is visible in the JSON artifact and concise CLI output.

Validation / Testing

• Run the focused issue-audit and GitHub-quota test modules with uv run pytest.
• Exercise the audit command with a mocked exhausted-core response and inspect the JSON schema.
• Run Ruff, format, git diff --check, and PR_READY_MODE=final in a fresh linked worktree.

Risk / Rollback

The change is workflow-control-plane code. The primary risk is suppressing useful enrichment too
early; retain a conservative fallback that keeps ordinary audit behavior when quota is healthy.
Rollback is a single commit revert. No scientific, benchmark, model, or paper-facing claim is made.

Related Work

• friction: make open_issue_closure_audit REST-first and search-quota independent #6610 addressed search-quota-independent closure auditing; this issue covers core REST exhaustion
  during current closed-PR/timeline enrichment.
• friction: PR merge gate cannot evaluate review threads during GraphQL quota exhaustion #8282 covers merge-gate review-thread behavior under GraphQL quota exhaustion.

Project Metadata

• Priority: triage required.
• Effort (h): 4.
• Reviewed: no.

[ll7]

Template audit — needs-triage retained, author estimates needed

Ran the canonical template audit (scripts/tools/issue_template_audit.py) against the live body.
## Archetype Metadata is valid, but 6 required sections are missing:

• Added Value Estimation, Effort Estimation, Complexity Estimation, Risk Assessment,
  Affected Files, Estimate Discussion.

These gaps need author judgment (value/effort/risk sizing for a quota-preflight feature), so per
the template-auditor contract I am not inventing them or clearing needs-triage. The observed
command, artifact reference, scope, inputs, and definition of done are already solid; filling in
the six estimation sections (a rough size guess anchored on the adjacent quota-handoff work in
scripts/dev/github_quota.py would suffice) will make this admittable. No state or label mutation
made by this pass.