fix(labels): the triage labels exist fleet-wide, and now a check says so (backend#2598)

[LukasWodka]

What

caller-drift.py asserts a repo carriescustomer-priority-bump.yml. It says
nothing about whether the labels that workflow fires on exist there — and GitHub
silently drops a template label the target repo lacks: no error, no annotation, no
run. So a repo can pass the conformance audit as fully wired while the bug-to-ready
rule cannot fire in it at all. The issue is filed unlabelled and the card sits in
Backlog, the refinement queue nobody pulls from.

Measured before / after

Derived from repo-inventory.yml (20 repos declare customer-priority-bump.yml: required, none exempt) — not from a hand-written list.

repo	before	after
design-system-v2	0 of 7	7 of 7
release-train	0 of 7	7 of 7
rfcs	0 of 7	7 of 7
e2e-test-agent	2 of 7	7 of 7
the other 16	7 of 7	7 of 7

e2e-test-agent is a fourth repo the ticket could not see. backend#2598 derived
over the work-type:*prefix and reported three repos. That repo had
work-type:bug and priority and none of the other five, so a prefix sweep called it
covered while four labels its templates apply were being dropped on the floor.
Deriving a domain from a prefix rather than from the producers is CLAUDE.md rule 6's
vocabulary gap — committed by the ticket written to close it. Two of the labels it was
missing (from:customer, and the three template labels) mean the bump job was
equally dead there and in the other three; the ticket recorded only the bug half.

The labels were created out of band

26 labels created with gh label create, plus one colour/description alignment
(e2e-test-agent's work-type:bug was GitHub's ad-hoc grey ededed with no
description — the tell that it was created by hand rather than by the rollout). Names,
colours and descriptions were read from the fleet, not invented: 16 of 17
already-labelled repos agreed byte-for-byte on all seven.

That is deliberate sequencing, per arm while green: had the check landed first it
would have been red on four repos on its first run. The labels are a repo-settings
change and cannot travel in a PR, so this PR carries only the check and the prose.
No branch protection, ruleset or other repo setting was touched.

The check

scripts/triage-labels-check.py + .github/workflows/triage-labels.yml, in the
caller-drift / kanban-columns audit tier (selftest job gates the audit job; PR
paths on both producers, plus a daily cron — a label can be deleted in a repo's
Settings UI with no PR to hang a check on).

It holds no label list. The domain is derived from two producers:

• customer-priority-bump.yml — every workflow_call input whose name ends in
  -label contributes its default, and every --add-label X its run: blocks
  execute contributes X.
• .github/ISSUE_TEMPLATE/*.yml — every entry of each template's top-level labels:.

Add a template, rename an input, or add a third label rule and the domain moves with
it. Deriving over the suffix rather than over two known input names is what makes
that true, and there is a case for it.

Fails closed. Exit 2 — never 0, and deliberately never 1 — on: an unreadable or
unparseable inventory / workflow / template; zero enrolled repos; a zero-length
derived domain in either family; a stale matcher (--add-label present but unmatched);
and any repo whose label list cannot be read. A 403 is UNKNOWN, never "this repo
has no labels" — that conflation is the backend#1415 failure one layer along. A repo
answering 200 with an empty list is a successful read, and every label is then missing
by the ordinary path.

Evidence

make check — green (ruff, shellcheck, house-rules, action-pins, mint-scope,
actionlint, mutations-dry, selftests-cover, 20 selftests):

triage-labels-selftest: 29/29 passed
==> check: green (gitleaks runs in 'make check-all')

make credential-scan: 438 commits scanned. no leaks found.

The live check, green across the fleet:

Derived 7 triage label(s) that must exist in each of the 20 enrolled repo(s):
from:customer <- input `trigger-label` default
needs-refinement <- applied by `feature.yml`
priority <- written by `--add-label`
work-type:bug <- applied by `bug.yml`; input `bug-label` default
work-type:docs <- applied by `docs.yml`
work-type:feature <- applied by `feature.yml`
work-type:tech-debt <- applied by `tech-debt.yml`
...
All 7 derived label(s) exist in all 20 enrolled repo(s): every label rule can fire everywhere it is declared.

Mutation proof, two tiers.

1. make mutation-triage-labels — 21/21 caught, every anchor resolved exactly
   once. Every mutation edits scripts/triage-labels-check.py or org-standards.md
   and the suite is re-run against them; there is no inline copy of the rule
   (CLAUDE.md rule 9). Covered: an exempt repo audited as enrolled, an empty fleet
   passing, the suffix derivation broken, --add-label dropped, each fail-closed
   refusal softened, audit() folding an unreadable repo into "complies", the
   comparison inverted, and the canon renaming the label out from under the workflow.

2. The real thing, on a real repo. Deleted needs-refinement from
   tracebloc/rfcs, ran the live check, restored it:

--- MUTATE: delete needs-refinement from tracebloc/rfcs ---
deleted
EXIT=2
x rfcs missing needs-refinement
ERROR: these enrolled repos are missing a triage label the org's automation fires on:
- rfcs: needs-refinement
--- RESTORE ---
restored
All 7 derived label(s) exist in all 20 enrolled repo(s)
EXIT=0

Prose this change makes false

• org-standards.md:37 — the exception sentence is deleted, not kept accurate by
  hand. It named two repos while the inventory said three, which is the argument the
  reviewer on client#848 made: a hand-written exception list drifts on every entry, so
  empty it rather than re-write it. This repo's CLAUDE.md is re-spliced from the
  canon using standards-sync.py's own build_desired, so the block is IN_SYNC; the
  other 19 copies need a standards-sync.ymlcreate-prs dispatch.
• .github/workflows/customer-priority-bump.yml header — the block recording the live
  defect now records the fix, the daily assertion, and the two derivation lessons.

Not done, stated rather than left implicit

• The App token scope is unverified until the first run.permission-issues: read,
  org-scoped, no repositories: narrowing. The evidence that the installation covers
  all twenty at that scope is add-to-kanban.yml — a per-repo copy in every enrolled
  repo minting exactly permission-issues: read (backend#2166). An under-scoped token
  fails at the call, not at the mint, so the first scheduled run is the test. This is
  an audit, not a required status context, so a red first run is a finding to fix that
  day rather than a merge blocker.
• Colour and description are not asserted, only existence. They agree fleet-wide
  today, but a wrong colour drops no label and blocks no automation.
• from:customer's description is stale across all 21 repos: "auto-bumps Priority
  to P1", while RFC-BACKEND-0008 D5 removed the Priority field and the workflow adds
  a binary priority label. Replicated verbatim into the four new repos deliberately —
  a fleet that agrees on a wrong string is fixable in one sweep, four repos disagreeing
  is not. Worth its own ticket.
• repo-inventory.yml was not extended with a label family. That was the ticket's
  open question. Adding a property means a row for all 20 repos and passing
  conformance-gate.yml on an exact head sha every other merge invalidates — the same
  reason customer-priority-bump.yml's own header gives for not splitting the reusable.
  A standalone sibling audit gets the assertion running now and does not stand in the
  way of folding it in later.

Closes tracebloc/backend#2598

---

Note

Low Risk
New advisory CI audit and local test tooling; no changes to merge gates or runtime triage workflows beyond documentation comments.

Overview
Adds ongoing enforcement that every repo declaring customer-priority-bump.yml actually has the labels automation and issue templates depend on—closing the gap where caller-drift only proved the workflow file existed while GitHub could still drop missing labels with no error.

scripts/triage-labels-check.py derives the required label set from two producers (no hard-coded list): customer-priority-bump.yml*-label defaults plus live --add-label writes (parsed YAML/shell, not comments), and .github/ISSUE_TEMPLATE/*.ymllabels:. It audits enrolled repos from repo-inventory.yml via gh api and fails closed (exit 2) on unreadable inputs, stale matchers, API failures, or gaps.

.github/workflows/triage-labels.yml runs a selftest-gated fleet check on PRs touching producers/inventory/check code and on a daily cron (labels deleted in Settings have no PR trigger). It is an advisory audit tier like kanban-columns, not a required merge context.

Makefile wires selftest-triage-labels and mutation-triage-labels into the existing selftest/mutation tiers. org-standards.md / CLAUDE.md drop the drifting per-repo bug-label exception and document fleet-wide labels plus this guard. customer-priority-bump.yml header comments are updated to record wiring complete, label gap closed, and derivation lessons (work-type:* prefix sweeps miss partial coverage).

Offline selftest (29 cases) and mutation harness (21 anchors) cover derivations, staleness guards (including parsed-vs-raw-text fixes from .github#364), and fail-open API paths.

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

[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 babb48c. Configure here.}

[LukasWodka]

Bugbot finding addressed in e0cbc7d — and it was a real defect of the class this repo catalogues, not a nit.

stale_idiom asked whether the strings -label and --add-label appeared anywhere in the workflow text, which a comment satisfies — including the comments this PR itself added. The cost is specific: rename the *-label inputs away and the backstop stays quiet, the caller family silently loses from:customer (no template applies it), the derived domain shrinks, and the check goes green over a dead bump rule. kanban-columns-check.py's names_in carries the same lesson from e2e#176; I had read that file and still wrote the raw-text version.

Both halves are now answered from the parsed document, by the same functions the derivation itself uses, so no comment can feed either:

• label_inputs(doc) — the workflow_call inputs whose names end in -label (and on: push parsing to a string is handled rather than crashed on).
• run_scripts(doc) — every run: body with shell comment lines stripped. ADD_LABEL matches over this, never over the file, so a commented-out --add-label ghost cannot put a name that exists nowhere under a fleet-wide assertion.

Three new cases, one per direction the raw-text version got wrong:

PASS: a `*-label` mentioned only in a COMMENT does NOT satisfy the guard
PASS: an `--add-label` mentioned only in a COMMENT raises no false finding
PASS: a commented-out `--add-label` does not enter the domain

The second exists because the two halves fail in opposite directions — the *-label half fails open (false green), the --add-label half fails closed (bogus red). One case could not cover both, and my first attempt at the mutation went UNCAUGHT for exactly that reason before I added it.

Evidence: suite 32/32; mutation tier 25/25 caught, including a mutation that reverts each half to the precise raw-text shape flagged here. make check green. Live check still green across all 20 enrolled repos.