chore: labels - Consolidate labels across GitHub and Linear [LABEL-UPDATE-REQUEST] #3834

Source of truth: .github/reports/audits/2026-09-14-label-audit/change-requests/label-update-request.md and evidence/linear-labels.json (merged in #3831). Follow-ups: #3832. Nothing is applied until a dated decision is recorded here.

Chore Summary

Approve the mapping that Stage 2 (the .github/labels.yml configuration PR, T059) and later stages apply. It covers 472 source labels and ends with 69 distinct targets. The type family ends at exactly 25.

Nothing changes until @ashleyshaw records a dated decision on this issue. Each repository's deletion has its own later gate (the deletion gate issue, T049).

Decisions needed

1. Spec-listed rules (no judgement). The FR-011 prefix renames, the 32 FR-012 merges, the FR-015 re-prefixes and the team-scope labels follow the spec as written.
2. Proposed by this mapping (spec is silent). The 39 merges and 14 gap entries below are judgement calls. Approve, or replace the target in a comment.

Linked Stories/Tasks

• Spec: .github/specs/008-label-audit-consolidation/spec.md (FR-011, FR-012, FR-014, FR-015, FR-021, FR-023)
• Tasks: T043, T043a, T044, T046, T046a, T059
• Already covers five imports: chore: labels - Add conflict-resolution labels to canonical taxonomy [LABEL-UPDATE-REQUEST] #3554. Also pending: chore: labels - Add area:labels to canonical taxonomy [LABEL-UPDATE-REQUEST] #3757 (area:labels), [TEMPLATE-UPDATE-REQUEST] Replace non-canonical labels in six PR template frontmatters #3548 (PR template frontmatter labels)
• Parent: epic: label-governance - Stabilise canonical labels and harden workflow automation #449

Mapping by action

rename (29)

merge (80)

re-prefix (8)

swap (1)

team-scope (4)

import (41)

retire (62)

Evidence qualification — two generic family-prefix entries

This qualification applies only to openspec:specification and openspec:implementation.

Static inspection at repository commit b63f9bbb0c186f68b0a1cf6cad1b30c89be38f5c found family-prefix checks in phase detection and validation. These uses do not establish standalone aliases or an in-progress step.

Checks on 14 November 2026 found neither exact label definition in lightspeedwp/.github or the enumerated accessible Linear scopes, including archived labels. GitHub returned no exact-label issue or PR assignments. No exact Linear label IDs were available for assignment queries.

Historical standalone usage, deleted labels, inaccessible scopes and GitHub Discussion assignments remain unverified. The retained Items values of 0 are existing mapping evidence, not newly measured universal assignment counts. The retained Rule values of FR-011 preserve the existing references; they do not establish approval of either disputed mapping.

Both replacement mappings remain undecided. Assess consumer-prefix changes separately from label migration. Do not infer an in-progress destination, create replacement labels or approve retirement from these findings alone. The original targets and notes remain recorded in the table notes as proposal history.

Specification-pending mapping remains undecided. At inspected repository commit b63f9bbb0c186f68b0a1cf6cad1b30c89be38f5c, the canonical planning description requires an improvement plan to be documented. The historical specification-pending framework contains conflicting awaiting-start and awaiting-review/approval meanings.

These definitions do not justify a universal pending-to-planning collapse. Define the intended state, inspect affected assignments, and decide transition and rollback behaviour before approving a destination. The retained Items value of 0 is existing mapping evidence, not a fresh assignment count. No replacement namespace or destination is established by this qualification.

Assignment evidence — 15 November 2026

The destination for openspec:specification-pending remains Undecided.

In lightspeedwp/.github, the exact label exists with description “OpenSpec specification needed”, but complete open/closed issue and PR checks returned no assignments. In accessible Linear scopes, no exact definition was found; this is not a measured zero assignment count.

The exact spec:planning label has four GitHub issue assignments and four corresponding Linear issue assignments. Its Linear description is “Specification planning phase — improvement plan documented”. All four records contain documented improvement plans. Inspected content did not explicitly establish specification drafting still needed or specification review currently pending. Conflicting checked success criteria and unchecked deliverables do not establish completion.

These findings support the documented-plan interpretation of planning, but provide no assigned specification-pending examples against which to establish equivalence. They do not justify a universal pending-to-planning collapse.

Coverage limits: GitHub issue/PR enumeration was complete; all four assigned issue bodies and 15 comments were inspected. Discussions were unavailable. Linear checks covered 328 definitions across workspace and 15 accessible team scopes, including archived labels, and all four returned assignments. Stored Linear comment completeness was not independently confirmed. Deleted labels, inaccessible scopes, historical assignments, linked plans and execution evidence remain outside the verified coverage.

This addendum does not change historical mapping counts, approve a destination or authorise migration or implementation.

Gap entries needing a decision

Proposed beyond the spec

Where the FR-015 labels live

FR-015 calls its eight type labels "Linear-only". Checked on 2026-10-06, all eight exist as live GitHub labels in lightspeedwp/.github (evidence/github-live-labels.json). In Linear only type:maintenance exists. Six complete team listings, the workspace listing and the Stage 1 export show none of the other seven. The GitHub team listing was cut off at 250, so that is not absolute. They are not imported into Linear (FR-015 and the 25-label type family), so each row is a GitHub re-prefix. The spec wording should say "GitHub" and not "Linear-only".

Label coverage across the organisation

Source: the weekly label drift check run of 2026-10-04 (283 repositories read, 59 skipped as archived or forks), kept in evidence/github-label-coverage.json. It lists 446 labels that exist in public repositories but not in labels.yml, and counts 57 more that exist only in private repositories and are not named here.

Every one of them now has a row (297 new rows for 446 names, the rest were already approved or mapped): 247 retire, 41 merge, 9 rename. A name that differs only in case or separator is renamed, the earlier bare-label mapping (#2523) is followed through the current renames, and every other label is retired with a stated reason. Run against the real tool, all 374 labels outside the approved set in lightspeedwp/.github have a row.

20 labels carry known items and have no target that the spec or the label documents define, so the tool lists them under needs_decision per repository, as FR-016 requires, until a target is chosen: area:monorepo, agent-audit, migrate:openspec:status/implementation, migrate:openspec:status/planning, migrate:openspec:status/production, migrate:openspec:status/testing, migrate:type:compatibility, ag-p14, ag-phase, bug-fix, code-quality, error-handling, logging, migrate:type:enhancement, phase-1-critical, phase-2-medium, phase-3-polish, phase:1, reliability, reviewer. The item counts are a lower bound, because the drift report caps counted rows.

The 2026-10-06 drift run reports the 85 active public repositories only and summarises the private ones, so it is not comparable; the 2026-10-04 run, which included the private repositories, is the inventory of record.

Impact

• Items carrying a source label move to its target. Open items move first; closed items only where a target exists.
• Retired labels are deleted only after the per-repository dry-run approval on the deletion gate issue.
• Linear: label creation is restricted afterwards (T071), so the imports are the last new labels.

Platform checks (Linear documentation, read 2026-10-06)

• Linear lets duplicate labels be merged into one and rescopes labels between workspace and team (Issue labels). The page does not say whether a merge works across a team label and a workspace label, so a merge row between the two is not confirmed as a native operation; see the team-scoped labels below.
• Deleting a label removes it from every issue and cannot be undone; archiving keeps it on past issues and blocks new use. This matches the spec: Linear labels are retired (archived), never deleted.
• Only one label from a label group can sit on an issue. A live read-only check on 2026-10-06 found no label groups in the workspace, so the type labels are flat and Linear does not enforce one type per issue. The "exactly one type:* per issue" rule must be enforced and verified by the consolidation tool (T064, T069), not assumed from Linear.
• The same check confirmed that type: feature, type:build-ci and type:code-refactor are team-scoped (GIT team, 1, 1 and 3 issues in the export) and type:documentation is workspace-scoped. Counts are from the Stage 1 export and have since moved, so Stage 5 re-reads live counts before it writes.
• Some labels in a merge row are team-scoped, so the merge target and source can sit in different scopes. security (merged into type:security, 11 issues) is three team labels, in the GIT, INF and LS teams (0, 4 and 7 issues in the export). Stage 5 relabels issue by issue by label ID and scope (T069a), which does not depend on a native merge across scopes. A native merge is used only if a test on a throwaway pair of labels shows it works. Converting the team labels to a workspace label is not used, because it would keep an unprefixed security label.
• The GitHub issue sync is bidirectional and includes labels (GitHub Issues Sync). That is why the spec turns the sync off from Stage 3 to Stage 5 (T071, T083).
• Issue label management can be limited to team owners (Teams), which is how T071 restricts label creation.

Approval

Reply on this issue with a comment starting Approved and the date. Edits to individual rows can be listed in the same comment.