Reconcile labels from settings.yml

[gavinbee]

Closes #46

What & why

#47 added the labels: block to settings.yml as a documented-but-inert key: it named the canonical set, but apply-settings.py read only repository, branches and rulesets, so no-issue still had to be created by hand in every repo. This wires it up — the rest of #46.

apply-settings.py now creates a label that is missing and corrects one whose colour or description drifted. Labels do not depend on visibility, so private repos get them too.

Two decisions worth reviewing

Reconciliation is additive. A label named in settings.yml is created or corrected; labels the YAML does not mention are left alone. Repos carry GitHub's defaults plus the ones Dependabot creates (dependencies, python), and deleting a label strips it from every issue and PR that used it — not something a weekly scheduled job should do unprompted. settings.yml is the minimum set, not the whole set. Making it authoritative and pruning is a different and much more destructive script; if that is wanted, it should be its own decision.

Verification re-reads and compares. verify_labels lists the labels again and diffs them against the YAML, rather than assuming the write took. That is deliberately not the shape of verify_ruleset, which only checks that a ruleset name exists — the subject of #45. Adding a second instance of that blind spot while #45 is open seemed like the wrong move.

Normalisation

Three ways a naive comparison would report false drift, all covered by tests:

• GitHub stores colours as six lowercase hex digits with no #, so #EDEDED in YAML and ededed from the API are the same colour.
• The API returns null, not "", for a label with no description; that compares equal to an absent description in YAML.
• A YAML entry with no color does not blank the colour already on the repo.

Label names are matched case-insensitively, since GitHub treats them that way — a No-Issue on the repo will not read as missing against a no-issue here.

list_labels pages with --paginate --jq '.[]', which emits one compact object per line; --paginate alone concatenates raw JSON arrays into something json.loads cannot read.

Testing

ruff check . clean. pytest -q — 22 passed, up from 11; the 11 new tests cover normalize_color and label_updates, both pure.

Dry-run against real repos, read-only, no writes:

swimblocks/deck-eval-gen: 12 labels; has no-issue = True
  -> 'no-issue' present; in sync
swimblocks/.github: 9 labels; has no-issue = False
  -> would CREATE 'no-issue'

The first case is the useful one: deck-eval-gen's no-issue was created by hand with gh label create, and the reconciler reads it as already in sync — so the normalisation and comparison agree with what GitHub actually stores.

Once this merges, the next reconciler run creates no-issue everywhere and the per-repo gh label create step goes away.

Checklist

• Linked the issue this PR closes
• Tests added/updated and passing
• ruff check . clean (Python repos)
• Docs/README updated if user-facing behaviour changed — settings.yml's comment now says the block is applied, and describes the additive rule

🤖 Generated with Claude Code

[gavinbee]

Why is there all this commentary about being applied by apply-settings.py ... we don't have that for other parts of this file that apply-settings applies?

[gavinbee]

Agreed — the file header already says "Applied by scripts/apply-settings.py", and no other block repeats it. That line was a leftover from #47, where the block genuinely was inert and needed the "NOT YET APPLIED" caveat; once it stopped being inert I updated the caveat instead of deleting it.

Trimmed to the part that is actually non-obvious — that the values seed a new label rather than govern an existing one, and that unlisted labels are never removed:

# Labels that should exist in every repo. Created when missing and then left alone —
# the values here seed a new label, they don't govern an existing one. Labels not
# listed are untouched: repos carry GitHub's defaults and Dependabot's too, and
# deleting a label strips it from every issue and PR that used it.

8ff34d2.

[gavinbee]

Should we really care if the color has drifted? Like what if a repo has 50 labels and adjusts colors to distinguish between them better? Do we care?

[gavinbee]

No, we should not — and the fifty-label case is the right test. Someone recolouring to group labels visually is doing something useful, and a weekly job silently reverting it is churn and faintly hostile. Colour carries no policy weight. What does is that the label exists, since a PR cannot be given a label the repo lacks.

I took it further than colour: the same argument mostly covers description, so this is now create-if-missing and nothing else. settings.yml seeds a new label; the repo owns it afterwards. If we ever change the canonical description that is rare and deliberate, and better as a one-off than as update machinery carried for a case that may not arise.

Removes label_updates outright, and with it the false-drift handling it needed — #EDEDED vs ededed, a null description vs an absent one. normalize_color stays for the create path so a # in YAML never reaches the API.

One consequence worth naming, since the PR body made a point of it: verify_labels is now a presence check, which looks like verify_ruleset — the thing #45 criticises. The distinction holds, though. Verification should cover exactly what the tool asserts. This only ever creates, so presence is the whole assertion. verify_ruleset is different because the rules are the substance and it never looks at them.

Net 34 lines lighter. Dry-run still reads real repos correctly:

swimblocks/deck-eval-gen: 12 labels -> nothing to do
swimblocks/.github: 9 labels -> would create ['no-issue']

8ff34d2.