feat(ci): required conformance gate — a contract change cannot merge on a failed audit

[LukasWodka]

First increment of backend#1608.

The hole

caller-drift.yml has run on PRs touching repo-inventory.yml since #1415, and it correctly fails when the inventory disagrees with reality. But it is not a required status check — .github/develop requires only actionlint. So a PR that adds a repo to the train with drift goes red and can still be merged. The gate existed in trigger form with no teeth.

That is the concrete version of the worry driving #1608: we keep adding repos to the train, and nothing stops one arriving that doesn't meet the contract.

Why not just mark caller-drift required

It carries a paths: filter. A path-filtered required check never reports on a PR that misses the filter, leaving it pending forever — the trap actionlint.yml's own header documents. Dropping the filter would run a 20-repo API audit on every PR in this repo, which is exactly why the filter exists.

So this adds a job that always runs and always reports:

• PR doesn't touch the contract → green in seconds, zero audit API calls
• PR does touch it → requires caller-drift's verdict for that exact head sha

Two details that are load-bearing

It keys on the workflow file, not the check name. Check-run names are not unique across workflows — caller-drift.yml and standards-sync.yml both expose a job called selftest, so polling by name would happily accept the wrong workflow's verdict. actions/workflows/caller-drift.yml/runs?head_sha=… cannot be confused that way.

--paginate on the changed-files query. A PR over one page would otherwise look like it touches only its first 30 files, and a truncated read reporting "not guarded" is precisely the silent pass this file exists to prevent. An empty list is treated as unreadable, not as "no files".

Every non-success branch is red with a named reason: no run within the poll budget, non-success conclusion, unreadable API, unreadable file list.

Verification

Path matching is exact (grep -qxF), dry-run offline:

README.md -> not guarded
repo-inventory.yml -> GUARDED
scripts/caller-drift.py + README-> GUARDED
docs/repo-inventory.yml -> not guarded <- suffix/prefix cannot sneak in
repo-inventory.yml.bak -> not guarded

This PR edits repo-inventory.yml's header on purpose, so it exercises its own guarded path rather than shipping a gate whose interesting branch never ran. Expect the gate to wait for caller-drift here and pass on its success — which also proves the poll works against a real concurrent run. caller-drift has been green on all five most recent runs, so arming imports no backlog.

After merge

Add gate to .github/develop's required checks. Not done in this PR: the check must exist on the base branch before it can be required, or every open PR blocks on a status that will never report.

Parent backend#1405.

---

Note

Medium Risk
Changes merge policy for contract files and depends on GitHub Actions API polling; misconfiguration could block PRs or allow bypass if not added to required checks after merge.

Overview
Adds .github/workflows/conformance-gate.yml, a PR check meant to be required so inventory/contract edits cannot merge while caller-drift only ran optionally. The job always reports: if the PR does not touch guarded paths it exits green with no audit API calls; if it touches repo-inventory.yml, scripts/caller-drift.py, related selftests, or caller-drift.yml, it pollsactions/workflows/caller-drift.yml/runs?head_sha=… until that workflow completes with success on the PR head (40m poll budget, 45m job timeout).

Guard detection is fail-closed: paginated changed-files (current and previous names for renames), empty/unreadable file lists fail, and guarded-path matching uses here-string grep instead of a pipe to avoid SIGPIPE false “not guarded” greens on large PRs.

repo-inventory.yml documents the new gate in its header and flips .githubcode-quality.yml from exempt to required, reflecting that the hosting repo now runs the code-quality caller.

^{Reviewed by Cursor Bugbot for commit 2022566. Bugbot is set up for automated code reviews on this repo. Configure here.}

[LukasWodka]

Confirmed and fixed in c4c4480. Reproduced before fixing, because a claim about SIGPIPE deserves a measurement:

20,000 filenames (~349 KB), guarded path FIRST
printf '%s\n' "$FILES" | grep -qxF repo-inventory.yml
-> pipeline rc 141
-> if-branch: NOT GUARDED <- silent pass
grep -qxF repo-inventory.yml <<< "$FILES"
-> if-branch: GUARDED <- correct

Exactly as described: grep -q exits on first match and closes the pipe, printf takes SIGPIPE and exits 141, and pipefail promotes that to the pipeline's status, so a real hit reads as a miss.

What makes it worse than a normal bug and worth the Medium: the gate would report "not guarded" and pass green, and the failure gets more likely as the diff gets bigger — so it would have been most wrong on exactly the large refactor PRs where an inventory change is most likely to be buried. It fails open, the one direction this file exists to rule out. A here-string is one command, so the status is grep's own.

I swept the rest of the repo for the pattern rather than fixing only the reported line. Two instances in fr-gate.yml:

ifecho"$LABELS"| grep -q '"skip-fr-gate"';thenifecho"$LABELS"| grep -q '"hotfix"';then

Both are safe, on two independent counts, and I left them alone deliberately rather than changing them for symmetry:

1. A PR's label JSON is orders of magnitude below the 64 KB pipe buffer, so echo finishes writing before grep can exit — SIGPIPE never fires.
2. Even if it did, a false negative there means the gate does not skip. It fails closed. Same pattern, opposite consequence.

The | head -1 chains in version-bump-gate.yml and the kanban workflows are likewise safe — each is either terminated by || true or fed by output far under the buffer.

Good find. It survived my own review because I was looking at the logic of the match and not at what pipefail does to a pipeline whose consumer exits early.

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit c4c4480. Configure here.}

[LukasWodka]

Both fixed in 2022566. Both were real, and the first one is the better catch of the two.

Rename escaping the guard (High) — confirmed

I read only .filename, and a rename reports the new path there. So git mv repo-inventory.yml elsewhere.yml sailed through as "not guarded" — the contract file moves out from under the audit and the gate waves it past. Exactly the silent pass this workflow exists to close, via a path I did not think about.

Proven on a synthetic rename payload, since no open PR has one:

old jq .filename only -> NOT GUARDED <- the hole
new jq + .previous_filename -> GUARDED

and verified against a real PR that (.previous_filename // empty) emits nothing extra when the field is absent, so ordinary PRs are unaffected.

You are right that the precedent was already here: promote-repo.sh's publishable_delta matches both fields, because a file renamed out of a published tree is still a publish-path change. I read that exact comment yesterday while building the version-bump gate and did not carry it across.

Poll budget shorter than the audit (Medium) — confirmed, arithmetic checked

gate budget 40 x 30s = 20 min
caller-drift selftest (timeout 5m) + audit (30m) = 35 min worst case

So a legitimately slow audit would have made the gate go red as though no verdict ever arrived, blocking a contract change until someone re-ran it by hand. Now 80 × 30s = 40 min, job timeout raised 25 → 45 so the named error surfaces instead of an opaque job timeout.

Worth stating the principle, because it generalises to every fail-closed poll we have: fail-closed on a budget that cannot cover the wait is just fail-annoying — and a gate people must re-run by hand is a gate they campaign to remove. The budget has to exceed the worst case of the thing it waits on, and it should be re-derived whenever that thing's timeout changes.

That is three genuine findings from Bugbot on this PR — SIGPIPE, rename, budget — all of which survived my own review. The common thread is that I checked the logic of each step and not the behaviour of the machinery underneath it: what pipefail does to an early-exiting consumer, what the files API reports for a rename, and what the thing I poll can actually take.

[saqlainsyed007]

Solid, well-reasoned gate — the fail-closed discipline (pagination, previous_filename for renames, here-string vs. SIGPIPE, absence≠success) is exactly right, and editing repo-inventory.yml here so the interesting branch actually runs is a nice touch.

Two issues to address (details inline):

1. GUARDED and caller-drift.yml's paths: are two copies of one invariant with nothing keeping them in sync. Both divergence directions are harmful — one is the exact silent-pass this file exists to prevent.
2. The poll's real wall-clock exceeds the nominal 40m budget (80 sleeps + 80 API round-trips + one wasted trailing sleep), narrowing the 40→45m margin the design leans on so the "opaque job timeout" it tried to avoid can still fire first.

Requesting changes on #1 in particular.

[saqlainsyed007]

The whole gate's correctness rests on GUARDED being identical to caller-drift.yml's pull_request.paths:, and nothing enforces that. They are two hand-maintained copies of one invariant:

repo-inventory.yml
scripts/caller-drift.py
scripts/tests/caller-drift-selftest.py
.github/workflows/caller-drift.yml

They happen to match today, but a future edit to either list silently breaks the gate in one of two ways:

• Path in caller-drift.yml but not in GUARDED → a PR touching only that path runs the audit but the gate reports "not guarded" and passes green without waiting. That is precisely the silent pass this file was written to prevent.
• Path in GUARDED but not in caller-drift.yml → the gate declares the PR guarded, polls for a run that will never be triggered, and fails closed after 40m, blocking the PR with no way to make it go green.

Given how carefully every other branch here is made fail-closed, this unguarded coupling is the weak point. Suggest at minimum a cross-referencing comment in both files ("keep in lockstep with …"), and ideally an assertion in caller-drift-selftest.py that the two sets are equal — or derive GUARDED from the workflow's paths: so there is a single source of truth.

[saqlainsyed007]

Two timing issues in the poll loop.

1. Wasted trailing sleep. On the 80th attempt the body increments i to 80, prints waiting (80/80) as if it will keep waiting, then sleeps 30s before the while condition finally fails. That last sleep buys nothing and the message is misleading. Guard it, e.g. [ "$i" -lt "${POLL_TRIES}" ] && sleep "${POLL_SECONDS}".

2. Real budget > nominal 40m. The comment above sizes the budget as 80×30s = 40m and sets timeout-minutes: 45 specifically "so the budget's own error message is what a caller sees rather than an opaque job timeout." But wall-clock is 80 sleeps plus 80 gh api round-trips (plus the wasted sleep above) — comfortably 42–43m+ and variable under API latency. Against caller-drift's stated 35m worst case with any queueing, the 45m job timeout can trip before the poll budget's named error fires, defeating the exact reason the timeout was set above the budget. Either lower POLL_TRIES so real wall-clock stays under 45m with margin, or raise timeout-minutes to sit clearly above the true worst case.