Auto-heal v2¶

Self-healing CI on main. When a required check fails, the v2 workflow classifies the failure, picks a repair strategy via a multi-arm bandit, applies it inside a cordoned worktree, opens a PR, and lets standard branch protection decide.

TL;DR¶

All state files are gitignored. The workflow never commits state.

Architecture¶

flowchart LR
    CI[CI failure on main] --> T[Triage]
    T --> KS{Kill switch?}
    KS -- on --> S1[Skip]
    KS -- off --> ID{Existing PR?}
    ID -- yes --> S1
    ID -- no --> BUC[Bucketize jobs]
    BUC --> BAY[Bayesian confidence]
    BAY --> FL[Flake detector]
    FL -- flake --> RT[Retry, no patch]
    FL -- real --> BANDIT[Bandit select strategy]
    BANDIT --> APPLY[Apply strategy]
    APPLY --> CO[Cordon check]
    CO -- block --> S2[Abort]
    CO -- ok --> ST[Self-test]
    ST --> BR[Blast-radius gate]
    BR -- ok --> PR[Open heal PR]
    PR --> AT[SLSA attestation]
    PR --> LOG[Audit + lineage + decision + calibration]
    LOG --> TG[Telegram alert]

The 26-capability matrix¶

status is one of: shipped (works in this PR), partial (module shipped, workflow wiring deferred), deferred (planned for v3).

Shipped: 16. Partial: 5. Deferred: 5. Total surface: 26.

Forward-compat env knobs¶

Operators can route observability sidecars to alternative storage without forking this package:

State files¶

CLI surface (used by the workflow)¶

python scripts/auto_heal_v2_run.py triage
python scripts/auto_heal_v2_run.py check-kill-switch
python scripts/auto_heal_v2_run.py select-strategy --candidates a,b,c
python scripts/auto_heal_v2_run.py record-outcome \
    --strategy ruff-format --cls safe --job Lint --outcome success
python scripts/auto_heal_v2_run.py log < record.json
python scripts/auto_heal_v2_cordon.py <path> [--whitespace-only]
python scripts/auto_heal_v2_imports.py <alias>

Operator workflow¶

Disable for an incident¶

mkdir -p .sdd
echo "2026-05-20T12:00:00Z" > .sdd/autoheal-disabled   # disable until time
echo "forever" > .sdd/autoheal-disabled                # disable indefinitely
rm .sdd/autoheal-disabled                              # re-enable

Read the audit ledger¶

jq -r '"\(.ts | localtime) \(.outcome) \(.strategy) \(.cls) \(.rationale)"' \
    .sdd/autoheal-history.jsonl

Emergency revert¶

The frozen v1 workflow lives at .github/workflows/auto-heal-v1.yml with all jobs gated by if: false. To revert, swap the v2 file out of the workflows directory and re-enable v1 by replacing the static false gates with the original guards from git history.

v1 vs v2¶