fix(fr-gate): fail closed on an unreadable or absent Status

[LukasWodka]

Closes tracebloc/backend#1266. RFC-BACKEND-0008 D27-L2/L6.

The defect

fr-gate.yml treated "could not evaluate this item" as "this item is fine":

STATUS=$(gh api graphql ... 2>/dev/null | jq ...)|| STATUS=""if [ -z"$STATUS" ];thenecho" ⚪ #$num — not on kanban, skipping"
MISSING="$MISSING #$num"continue# ← not a blockfi

2>/dev/null and || STATUS="" collapsed every failure into a silent pass — missing/expired
PROJECTS_KANBAN_TOKEN, a repo secret shadowing the org one, a transient 5xx, or the item genuinely
absent. If every item was unreadable, the gate printed ✓ PASSED. The only promotion gate disarmed
itself, and failure looked exactly like success.

It was a race, not an edge case

fr-gate-caller.yml and add-to-kanban.yml both fire on pull_request: opened and run
concurrently, so the gate regularly queried the board before the card existed. On
tracebloc/.github#61 the gate finished at 16:48:09 and the card was created at 16:48:14 — it
won by one second and passed. Measured on real promotion runs: 4 of 32 items skipped this way, 3 of
20, 3 of 17.

The fix

• resolve_status() retries up to 5× (2s, 4s, 6s, 8s backoff) and returns a distinct code for
  an API failure (1) vs a PR genuinely not on the board (2). The empty-result retry is the half
  that closes the race.
• The verdict fails closed on BLOCKED, MISSING, orUNREADABLE, each with its own
  actionable message — an infra failure now reads differently from a review failure.

Also closes L6 (delete card → add label → pass): the label trigger re-runs the gate,
add-to-kanban doesn't recreate the card, and the retry now waits for it rather than passing on its
absence.

Verification

• Return-code contract exercised under a stubbed gh: card → 0, no-card → 2, API-failure → 1.
• actionlint (now a required check on this repo) passes — shellcheck included.

⚠️ Overlaps #68

#68 ("make the FR gate self-clearing") also rewrites fr-gate.yml. Whichever merges first, the
other must rebase. They are not independent. I'd also flag that #68's approach — automating the
manual retry — needs reconciling with this: the retry-passes-96%-of-the-time pattern it automates is
in several cases the card being moved between attempts, i.e. the L3 bypass, not a transient blip.
This PR retries the read, not the verdict, which is the safe half.

I could not run the full workflow end-to-end (no kanban token locally); the logic is unit-tested as
above and CI is the real integration run.

---

Note

Medium Risk
Changes promotion merge-blocking behavior for staging/main; misconfigured tokens or slow kanban card creation could block merges until retry succeeds or override is used, which is intentional but operationally sensitive.

Overview
The reusable FR gate workflow no longer treats “could not read kanban Status” as a pass. It adds resolve_status(), which retries GraphQL reads up to five times with backoff (including empty results from racing add-to-kanban on pull_request: opened), and separates API failure from PR not on the board.

Items that stay unreadable or missing after retries now fail the check via new UNREADABLE and MISSING handling, with targeted ::error:: messages (token/infra vs missing card vs wrong column). The old path that skipped off-board PRs and could print PASSED when every item was unevaluated is removed. Jq parsing is hardened so transient parse/pipe errors do not abort retries under set -euo pipefail.

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

[LukasWodka]

👋 Heads-up — Code review queue is at 41 / 30

Above the WIP limit. The team convention is to review existing PRs before opening new work.

Open PRs currently in Code review (oldest first):

• .github#64 — fix(closure-router): add GH_TOKEN to closing-PR lookup so issues mirror their closing PR's Status · author: @LukasWodka · no reviewer assigned
• .github#65 — feat(quality): shared code-quality reusable workflow + house-rules checker · author: @LukasWodka · no reviewer assigned
• .github#68 — feat(fr-gate): make the FR gate self-clearing and self-explanatory · author: @LukasWodka · no reviewer assigned
• averaging-service#207 — Promote develop → staging · author: @shujaatTracebloc · no reviewer assigned
• backend#1201 — docs(rfc): Data spaces & federated dataset composition (draft) · author: @LukasWodka · no reviewer assigned
• backend#1217 — docs(rfc): Dataset integrity & score reproducibility (draft) · author: @LukasWodka · no reviewer assigned
• backend#1228 — Promote develop → staging · author: @shujaatTracebloc · reviewer: @saadqbal
• backend#1244 — fix(experiments): surface save-time failures as 5xx + guard new NOT NULL columns · author: @LukasWodka · reviewer: @saqlainsyed007
• backend#1251 — docs(bugbot): add .cursor/BUGBOT.md project context (#930) · author: @LukasWodka · no reviewer assigned
• backend#1254 — docs(pr-template): owner-qualify cross-repo closing keywords · author: @LukasWodka · no reviewer assigned

Pull from review before opening new work. (This is a nudge from the kanban WIP check, not a block.)

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

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

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

[LukasWodka]

Bugbot finding addressed. It was right, and both bugs were mine from this PR:

1. 2>&1 on the gh capture merged stderr into the JSON body → jq parsed garbage on an otherwise-good call. Now 2>/dev/null (stdout only).
2. The jq | head pipeline was unguarded under set -euo pipefail, so a parse error or head SIGPIPE aborted resolve_status mid-loop — skipping the retries and returning an ambiguous code the caller mislabelled as MISSING. Parse is now non-fatal.

Re-verified the return-code contract, including a new case where gh writes to stderr but returns 0 (proves fix #1). actionlint green.

bugbot run