fix(inventory): two reasons that describe something other than what happened

[LukasWodka]

Closes tracebloc/backend#2516
Closes tracebloc/backend#2517

Two Bugbot findings deferred from the .github#334 staging hop under the severity policy. Both verified against source before fixing.

#2516 — the reason described a discovery, not what happened

claude-skills' fr-gate.yml reason framed the caller's absence as the audit discovering a missing caller, and ended:

if the caller was removed by mistake, restore it and flip this back — the remedy runs both ways

It was not a mistake.claude-skills#38 deleted fr-gate-caller.yml deliberately (+0/-15) as the remainder of backend#2347: that repo does not ride the train, so it was carrying a train caller it cannot use. The audit reporting "MISSING required caller" mid-review was that removal surfacing.

The remedy does not run both ways, and the reason no longer says it does — restoring the caller would require a context nothing produces, which is the client#665 defect this file warns about two entries up.

#2517 — a claim about the citation guard that the guard does not back

The rfcsprod cell said reason-citations.py"can at least check that a cited issue is still open" — while naming backend#2501only in a YAML comment, which that script never reads.

reason_strings() collects keys in REASON_KEYS whose value is a string; comments are invisible to it deliberately, because a commented-out example is not a citation. So the follow-up could go stale behind a green run.

The comment now says the opposite, and says why moving the citation into a scanned string is not the fix: the only reason-bearing field in that cell is reason:, an alias to a shared anchor — putting a repo-specific ticket there would either duplicate the anchor inline or leak the note into every other cell citing it.

The guard then caught this very change

The new #2516 text cites backend#2347 — which is CLOSED, so reason-citations.py failed the run:

::error:: tracebloc/backend#2347 is cited by a repo-inventory reason and the issue is CLOSED

That is the guard doing its job on the person editing the file. #2347 is now in EXEMPTwith what it is doing there — provenance, re-read, still true — rather than reworded out of the reason to silence it. Dropping the number would have lost the traceability the reason exists to provide.

Folded in, deliberately

repo-inventory.yml is a GUARDED file: it needs a green org audit on its own SHA, so two PRs touching it cannot both hold one. Rather than race, this PR also flips the fivebugbot-gate rows whose callers merged today (design-system, frontend-app, model-zoo, start-training, tracebloc-website). Five repos remain exempt pending their caller PRs.

The bugbot_gate_rollout_pending anchor stops enumerating repos. That list has gone stale twice in three days; it is now derived with the anchored grep (backend#2507) and carries its own delete condition.

Verification

• reason-citations.py: 0 findings (13 dead, 13 exempted — all pre-existing and already exempted)
• reason-citations-selftest.py: 33 passed, 0 failed
• reason-citations-mutations.py --dry: 23 mutations, 0 stale
• YAML parses; the anchor was checked by loading the file and reading the rendered value, not by eyeballing the diff — an earlier edit today broke a folded scalar's indentation in a way the diff looked fine for

---

Note

Medium Risk
Changes org-wide CI inventory contracts (required bugbot-gate callers) and exemption prose that gates merges via conformance audit; mis-flipping a row would redden repos or leave gates unwired, though the PR aligns rows with merged callers and tightens documentation rather than altering runtime auth.

Overview
Fixes two Bugbot-deferred inventory reason defects (#2516, #2517) and folds in bugbot-gate rollout updates so repo-inventory.yml stays accurate and auditable.

claude-skillsfr-gate exemption (#2516): The reason no longer treats a missing caller as an audit “discovery” or suggests restoring fr-gate-caller.yml. It now records that claude-skills#38 deliberately removed the caller under backend#2347 (non-train repo), says DO NOT RESTORE, and notes restoring would recreate the client#665 “required context nothing reports” failure.

rfcs prod protection comment (#2517): Removes the incorrect claim that reason-citations.py guards backend#2501 when that ticket is named only in a YAML comment. The comment now explains why moving the citation into a scanned reason: string is not viable (shared anchor alias).

reason-citations.py: Adds EXEMPT entries for backend#2347 (provenance in the new fr-gate text) and client-runtime#192 (closed-unmerged PR cited as history in blocked_gate_rollout_pending), and softens backend#1752 to past tense (“would have reddened”).

Bugbot-gate inventory: Flips bugbot-gate.yml from rollout-pending exempt to required on repos whose callers merged (including design-system, frontend-app, model-zoo, start-training, tracebloc-website and others in the diff). Updates bugbot_gate_rollout_pending and blocked_gate_rollout_pending anchor prose—no stale repo lists, blocked-gate arming rationale updated for merged/closed PRs—with grep-derived roster for remaining exempt repos (e.g. design-system-v2).

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

[LukasWodka]

Scope grew while this sat unmerged, deliberately rather than by accident.

Four more bugbot-gate callers merged at 07:46 — averaging-service, data-ingestors, tracebloc-engine, tracebloc-py-package. Their rows are now flipped here too, so 19 of 20 read required.

Only design-system-v2 is left exempt, and its caller PR (design-system-v2#12) is held by a pre-existing Code Connect (Figma) failure on that repo's own develop — backend#2523, unrelated to this rollout.

Why fold them in rather than open a second PR:repo-inventory.yml is a GUARDED file needing a green org audit on its own SHA. Two PRs both touching it cannot both hold one — that is a deadlock, not a queue.

Worth recording: this PR had already passed audit, before those four merged. That green was stale the moment they landed. It is the same re-run trap the release-train README documents for promotion PRs — required checks are latest-per-context, so a verdict describes the fleet at the moment it ran and not the fleet you are merging into. I would not have caught it by looking at the check row; I caught it because a local audit run came back red for repos this PR had not touched.

[LukasWodka]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

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

[saqlainsyed007]

The two reason corrections are correct and well-argued — verified:

• #2517:reason-citations.py parses the inventory with a YAML loader, which discards comments outright, so a ticket named only in a # comment genuinely can't be seen by the guard. The new comment states that honestly, and correctly notes that moving it into reason: (an alias to a shared anchor) would leak the note fleet-wide — so "the ticket tracks itself" is the right call.
• #2516: removing the "restore it, the remedy runs both ways" language is right — the caller's absence is deliberate (claude-skills#38, +0/-15), and framing it as a possible mistake invited undoing a deliberate change.

One scope concern, holding on it: beyond the two reason strings this PR is described as fixing, the diff also flips bugbot-gate.yml from exempt: *bugbot_gate_rollout_pending to required across ~19 repos — a fleet-wide inventory change not mentioned in the body or either linked ticket. It looks considered (you left 2 repos on the anchor, so it's not a blanket sweep, and it leaves no dangling anchor), and required here is an inventory "repo must carry this caller" assertion rather than a branch-protection status — so it won't break dependabot PRs. But:

1. Each flipped row asserts that repo's bugbot-gate-caller.yml has actually merged; a row flipped ahead of its caller makes the audit report false non-compliance. Please confirm all 19 have landed.
2. Per the org "one self-contained change per PR" rule, please note this in the body (or split it) so a 19-repo required-flip isn't riding invisibly inside a two-reason-string fix.

Happy to approve once the rollout-complete claim is confirmed and the body names the flip.

[saqlainsyed007]

Re-review of d07b031 — approving. My scope question is fully resolved: you described the bugbot-gate flips in the PR body, named the five repos still exempt, and explained the bundling — repo-inventory.yml is a guarded file that needs a green audit on its own SHA, so two PRs touching it can't both hold, which is a sound reason not to split. And the confirmation I asked for is now mechanical: CI is green, meaning the org conformance audit passed on this SHA — the exact check that reddens a required row whose caller is absent — so every flipped row's caller is verified present.

The latest commit also correctly retires the dead citations that were reddening the fleet (client-runtime#192 closed, client#490 already merged): restated in the past tense with the citation kept, so the deadness is the content rather than a lean on something that never landed.

Both original reason fixes (#2516/#2517) verified correct last pass. Green, no open threads. LGTM.

[LukasWodka]

This PR became load-bearing after it was opened — flagging it so the review is prioritised, not to change its content.

tracebloc/client-runtime#192 was closed unmerged at 08:26 today. It is cited by blocked_gate_rollout_pending in 21 repos, so reason-citations.py (required since #329) now fails on the live inventory — measured directly on origin/develop, exit 1. develop's last selftests run was 08:15, nine minutes earlier, which is the only reason it still reads green.

This branch already carries the fix, written before the close was known: the anchor is restated in the past tense, and #192 is recorded in EXEMPT as "the deadness is the content" rather than having its number dropped to silence the guard. Guard output on this branch:

34 distinct citation(s) across 113 written reason(s)
14 dead, 0 malformed, 14 exempted, 0 finding(s) -- exit 0

So this PR now unblocks two separate reds at once: the fleet audit (the 19 bugbot-gate row flips it was opened for) and selftests fleet-wide. Until it lands, no .github PR can go green — #340 is already blocked on it, and #343 after that.

Nothing here needs changing; it just wants an approval sooner than it did an hour ago.