Compute(): append mode — partition, squatters, convergence

[Ilyes512]

Goal

internal/plan/plan.go:

func Compute(desired []config.Label, current []github.Label, mode Mode, renames []Rename) Plan

Pure, no I/O. This is the heart of the tool and the reason internal/plan imports no client.

Design reference

docs/design.md § Reconciliation algorithm,
§ Ordering, § Steps

Scope

• Partition remote labels into matched and unconfigured, comparing names
  case-insensitively
• Reserve every desired colour
• Detect squatters — unconfigured labels sitting on a reserved colour — and emit a recolour for
  each, sorted by name ascending, feeding each new colour back into used
• Converge configured labels in ascending name order: Create when absent; Update when
  colour, description, or casing differs; NoOp otherwise (retained for reporting, never
  sent to the API)
• Emit actions in the design's order — renames, recolours, creates, updates, deletes. Recolours
  precede the claim so every intermediate state is clean if the run aborts mid-repository.
  GitHub permits duplicate colours, so this is about crash-consistency, not validity
• Descriptions are authoritative: an omitted description means "", which means clear it

Tests

The core suite. Table-driven over (desired, current, mode, renames) → expected actions, covering
squatter detection, casing drift, description clearing, and action ordering.

Depends on

#19, #24, #25

Done when

task lint and task test pass, every box above is ticked, and the change ships with its tests and documentation in the same PR (per AGENTS.md).

[Ilyes512]

The #16 spike is resolved and it settles two things for Compute() —
findings,
written up in docs/design.md by #54.

Step 2's case-insensitive partition is safe. GitHub enforces label-name uniqueness
case-insensitively (POST of a case variant → 422 already_exists), so at most one remote label
can match a given configured name. No tie-break rule, no multiple-candidate handling.

Step 5's m.name != d.name casing-drift branch is a real code path, not dead code. This was the
genuinely open part. A repo holding bug while config asks for Bug is a perfectly reachable
state, and PATCH with new_name: Bug fixes it in one call — 200, same label id, associations
preserved. So the drift check earns its place; it should not be simplified away on the theory that
uniqueness makes it impossible.

One implementation detail worth getting right in the emitted action: address the label by its
observed remote name in Action.Name, with the config's spelling in NewName. The API path
segment resolves case-insensitively either way, but using the observed name keeps the request
consistent with the state the plan was computed against, and keeps the ETag cache keyed on what the
API actually returned.

No scope change to this issue — the algorithm as designed is correct as written.

[Ilyes512]

Implemented in #63. Recording one scope decision and one departure here, so neither has to be found in the diff.

Signature. This issue quotes Compute(desired []config.Label, current []github.Label, mode Mode, renames []Rename) Plan. What shipped is:

func Compute(repo string, desired []config.Label, current []Label, mode Mode, renames []config.Rename) RepoPlan

• current []plan.Label, not []github.Label — AGENTS.md states that internal/plan never imports internal/github and takes plain structs, which a github.Label parameter cannot satisfy. That package also does not exist yet (auth.go: the four-step token resolution chain #31–cache.go: the ETag store and conditional requests #35), so the sketch was not compilable either way. Converting an API response into a plan.Label is the caller's job.
• repo string — both Action and RepoPlan carry the repository, and a pure function has nowhere else to get it.
• Returns RepoPlan — Compute reconciles one repository; a run assembles the Plan from the per-repository results.

docs/design.md now shows the built signature with the original recorded next to it, and the argument is in Architecture § Planner.

Renames. Every box above is ticked except the rename half of the ordering bullet: renames are #27 and prune is #28. Both parameters are accepted and ignored for now, so those issues are a change to this function rather than to every call site.