cicd-squabbler — an intelligent, detachable CI/CD fighter

A standalone, per-repo CI/CD fighter that drives a stuck pipeline to a legitimate green — or improves red→yellow, or fails and hands the human a structured report. It wins the gate; it never cheats past it.

Note

Status — v0.1 in active development (updated 2026-07-17). The engine and its formal invariant are real and verified (see below); live gate fetch via gh landed in #6; squabble fight (classify each red as self-win | escalate | assign-owner), the squabble-app loopback HTTP backend, and the boj-server expert summoning (--summon, feature boj) landed in #13. squabble fight --apply now enacts the first appliable self-win — stripping an on..paths trigger filter that strands a required check — by writing the workflow file (propose remains the default; --apply never commits, pushes, or re-runs CI). Still open: applying the other self-wins (required-context reconcile, reusable-workflow re-pin — these need the GitHub ruleset API / a target SHA) and the GitHub App *webhook leg (pending the owner’s hosting decision). See docs/CHARTER.adoc for the design and open owner decisions.

Table of Contents

• Core principle: squabble ≠ bypass
• What’s in the box
• Verify it yourself
• The v0.1 fight playbook (gate-deadlock class only)
• Licensing

Core principle: squabble ≠ bypass

Every "green" the squabbler declares is backed by the gate’s own required check passing legitimately — never by an admin override, an enforce_admins toggle, or removal/rename-away of a required context. An admin-merge cheats past the gate; a squabble wins it.

This is not a code-review promise. It is a machine-checked invariant: the SPARK package in spark/ proves that the only transition into Green is "a required check actually ran and passed" — dropping the required set, renaming a check away, or any override are provably not paths to green.

What’s in the box

crates/squabble-core	The fight engine. Pure, detachable, no hypatia/estate dependency — diagnose → propose move → apply → verify-satisfied. The valuable reusable part.
crates/squabble-fight	The shared host brain: a2ml ecosystem-context reader + workflow ground-truth + the fight planner. One planner for the CLI and the App, so they cannot drift.
crates/squabble-cli	squabble — runs locally or as a CI step. fetch, diagnose, and fight (with --summon under the boj feature to put expert verdicts on the report, and --apply to enact the path-filter self-win by editing the workflow — no commit/push).
crates/squabble-app	The loopback HTTP backend (axum, 127.0.0.1:7741): serves the shared planner to the boj-server cicd-squabbler-mcp cartridge. The GitHub App webhook leg (trigger button + octocrab) is still to come — no webhook route is registered.
spark/	The formal heart. Gate_Machine + the proved theorem green ⇔ (non-empty ∧ all passed).

Verify it yourself

just test    # 7 engine tests pass
just prove   # gnatprove: postcondition proved (squabble ≠ bypass)
just demo    # diagnose a stale-required-context deadlock

The v0.1 fight playbook (gate-deadlock class only)

Mined from the 2026-06-22 rsr-template-repo lockdown (effectively a manual squabbler run). Every move satisfies the gate:

1. Stale required-context — reconcile the required name to the real emitted name.

2. Path-filter deadlock — inject the documented job-level pass-through.

3. Reusable-workflow pin drift — re-pin a stale/broken SHA to current.

4. Modify/delete & rebase conflicts — resolve and re-run.

5. Check-name ground-truthing — the shared substrate for moves 1 and 2.

6. Licence-policy drift — doctrine-constrained: adding a missing canonical LICENSES/ text is authoring (may apply); rewriting an existing file’s SPDX header is relicensing (flag, owner-only — never edit).

7. Non-functional gate — the required check’s own script fails unconditionally (cannot be won from the PR side; mined from hypatia#566): recognise, stop re-diagnosing, escalate with evidence.

Red→green code fixes are deliberately out of scope for v0.1: "fixing" a failing test by weakening it would violate squabble ≠ bypass.

Licensing

Code MPL-2.0; documentation CC-BY-SA-4.0. An RSR-shaped repository of the hyperpolymath estate.