ci-guard

name	ci-guard
description	Monitor, classify, and budget-safely retry GitHub Actions CI for a PR. Use when the user wants to snapshot CI state, retry failed checks, verify a flaky green, or classify a specific run failure. Requires gh CLI authenticated against the repo's GitHub account.

Guard CI using the scripts in .ci-guard/scripts/. All retries go through ci_watch.py --retry-failed-now — never call gh run rerun directly so budget counters and the flaky ledger stay in sync.

Prerequisite

Before any ci-guard command, confirm gh auth status shows the correct GitHub account. If it fails or shows the wrong account, tell the user to run gh auth login and stop.

Determine the user's intent

Ask or infer one of these modes:

Mode	When to use
snapshot	User wants to see current CI state / what's failing
retry	User wants to re-run failed checks (budget-aware)
verify-flaky-green	User wants to re-confirm a green that has flaky history
classify	User wants to understand why a specific run failed
quarantine-check	User wants to see which tests are quarantine candidates

If still unclear, default to snapshot.

Running each mode

All commands run from the repo root.

snapshot — single JSON dump of all checks with classifications:

python3 .ci-guard/scripts/ci_watch.py --pr auto --once
# or for a specific PR:
python3 .ci-guard/scripts/ci_watch.py --pr <number> --once

retry — budget-safe rerun (refuses if branch_failure or budget exceeded):

python3 .ci-guard/scripts/ci_watch.py --pr auto --retry-failed-now

verify-flaky-green — re-run checks that went green but match the flaky ledger:

python3 .ci-guard/scripts/ci_watch.py --pr auto --verify-flaky-green

classify — heuristic analysis of a specific run log:

python3 .ci-guard/scripts/classify_failure.py --run-id <run-id>

quarantine-check — surface tests that have ≥3 failures in 30d and ≥5% flake rate:

python3 .ci-guard/scripts/flaky_ledger.py quarantine-candidates

Interpreting the output

After running, parse and summarize the JSON for the user:

• actions: ["all_green"] → CI is clean, safe to merge.
• actions: ["branch_failure"] → A real bug in the branch. Never retry; the user must fix the code. Show classification.reason and matched_snippet.
• actions: ["retry_with_budget"] → Infra/test/dependency flake. Show which checks and then run --retry-failed-now if the user confirms.
• actions: ["diagnose_unknown"] → No heuristic matched; show the raw log excerpt and suggest the user investigate before retrying.
• actions: ["verify_flaky_green"] → A green check has ledger matches; run --verify-flaky-green to confirm it wasn't a lucky pass.
• actions: ["budget_exhausted_surface"] → Retry budget spent; surface to the user that manual intervention is needed.
• cost_summary.any_budget_exhausted: true → Always tell the user budget is exhausted when present, regardless of other actions.

Budget defaults (from .ci-guard/config.yml)

Limit	Default
Retries per job	2
Retries per PR	5
Minutes per PR	90

Overrides live in .ci-guard/config.yml (uncomment lines to change).

GitHub Actions wiring (optional)

If the user asks to wire ci-guard into the workflow, add two steps to the test workflow YAML.

Record failures to the ledger (paste into any test job, if: always()):

- name: Update flaky ledger
  if: always()
  run: |
    python3 .ci-guard/scripts/flaky_ledger.py record-failure \
      --test "${TEST_ID}" --sha "${{ github.sha }}" --run-id "${{ github.run_id }}" || true

Warn on quarantine candidates (add as a required status check):

- name: Quarantine guard
  run: |
    candidates=$(python3 .ci-guard/scripts/flaky_ledger.py quarantine-candidates)
    if [ -n "$(echo "$candidates" | jq -r '.[]' 2>/dev/null)" ]; then
      echo "::warning::Quarantine candidates exist; review before merging."
      echo "$candidates"
    fi

When recommending the wiring, always show both steps together and remind the user to replace ${TEST_ID} with the actual test identifier their framework exposes.