audit: align label and issue-type colours #911

Parent Issue: #903

Audit Summary

Audit colour consistency and semantic-family alignment across the canonical labels configuration and issue-type configuration, using the Label Color Strategy Specification as the authority.

In Scope

• Validate every colour in labels.yml against explicit strategy assignment rules.
• Validate each issue type against its companion type:* label in labels.yml.
• Identify strategy gaps, conflicting rules and stale references separately from configuration defects.
• Produce an approved, minimal remediation plan; do not change labels until the colour precedence is confirmed.

Verified Findings

Paired configuration mismatches

The remaining 22 issue-type-to-label pairs match.

Strategy-based recommendations

Apply only where the strategy has an explicit rule:

• Ready/done: status:ready, status:done → 1A7F37.
• Planning/review: standard status:needs-* labels → 0969DA; type:documentation → 3467D3; area:ci → C5DEF5.
• Testing/audit: type:audit → D29922.
• Blocked/impediment: status:blocked, status:duplicate, priority:critical, type:security → CF222E.
• Deferred: status:on-hold, status:wontfix → 9A6700.
• Design: type:design → 8957E5.
• Meta/process: all meta:* labels and type:chore → 57606A.
• Integration/dependency: area:integration and type:dependency → 007580.

Reconciled workspace findings

• The current workspace has 182 active global labels. The strategy’s stated 150-label coverage cannot be verified: its family totals equal 170 and it does not provide an exhaustive mapping.
• All 162 labels in labels.yml already exist globally in Linear. No configured labels need creating.
• Four duplicate canonical type pairs coexist in Linear: type:ai-ops / type:aiops, type:improve / type:improvement, type:compat / type:compatibility, and type:content-model / type:content-modelling.
• labels.yml conflicts with strategy examples, including status:done, area:ci, and meta:stale.
• Current Linear colour values are not available in the inventory response, so the audit defines target colours and requires a later colour-only implementation preview.

Strategy revision suggestions

• Make the colour strategy authoritative over labels.yml and issue-types.yml for colours until those files are reconciled; retain configuration files as the source for canonical names and descriptions.
• Replace conditional shared-label colour rules—such as “feature when merged” and “bug when testing”—with stable label colours and workflow-specific status labels.
• Add deterministic mappings for currently uncovered families: ai-ops:*, area:*, comp:*, compat:*, contrib:*, cpt:*, discussion:*, env:*, release:*, OpenSpec lifecycle labels, priorities, and remaining type:* labels.
• Record explicit exceptions: design-token components → Purple; compatibility → Teal; testing/audit/performance → Yellow; security → Red; meta → Grey; languages and CI → Blue.

Decisions Required

Do not prescribe colours for labels with competing or missing strategy rules, including design-review, QA, testing, accessibility, review, performance, automation and OpenSpec labels. Define precedence for these categories before remediation.

The strategy document also needs separate follow-up for stale label references and inconsistent versions: frontmatter states v1.1.4, while the document body states v1.1.2.

Additional decisions

1. Approve alias merges, rather than renames, for the four duplicate type pairs. The canonical target labels already exist.
2. Decide whether openspec:implementation-complete means completion (Green #1A7F37) or retirement (Orange #9A6700); its name and description conflict.
3. Approve the proposed family defaults before applying colours to labels not presently covered by an explicit strategy rule.
4. Confirm whether type labels should remain colour-aligned with their companion GitHub issue types, where the semantic strategy proposes a different colour.

Next Tasks

1. Define and document colour-precedence rules for design review, QA, testing, accessibility, review, performance, automation and OpenSpec labels.
2. Produce the final colour matrix, then align each issue type with its companion type:* label in one approved change.
3. Reconcile stale strategy references and the v1.1.4/v1.1.2 version mismatch, then validate the final configuration.
4. Validate remaining team-only label references in archived issues and GitHub workflow configuration before further migrations.
5. Review the canonical taxonomy proposal for area:changelog, area:workflows, and scope:website, including colours and descriptions.
6. Keep ambiguous priority, status, and metadata labels unchanged until their intended taxonomy dimension is agreed.
7. Update the colour strategy with deterministic coverage for all active label families and explicit precedence rules.
8. Create a colour matrix containing every active global label, its prescribed target hex, rationale, and source rule.
9. Reconcile labels.yml and issue-types.yml with the approved strategy, including the three existing paired configuration mismatches.
10. Prepare a separate, approval-gated alias-merge plan with issue-usage impact for the four duplicate type pairs.
11. Produce a final Linear colour-only change preview; preserve names, descriptions, grouping, and issue usage.

Acceptance Criteria

• Every label has a documented expected colour or a recorded strategy exception.
• All 25 issue types match their companion type:* labels after approved remediation.
• Ambiguous families have an agreed precedence rule before colours change.
• Strategy versioning and stale references are resolved or tracked separately.
• Remediation changes are limited to approved colour values; names, mappings, ordering and descriptions remain unchanged.
• The strategy has a deterministic colour rule or recorded exception for every active global label.
• The documented inventory count and configuration inventory are reconciled, with any differences explained.
• Alias migrations are separately approved and are not bundled into colour changes.
• Every proposed Linear update is colour-only and has an exact target hex.

Definition of Done

• Audit matrix and evidence are complete.
• Recommended colour changes are reviewed against the strategy.
• Follow-up implementation work is tracked and verified.

Definition of Ready (DoR)

• Clear problem statement and expected outcome
• Acceptance criteria defined
• Related issues/dependencies identified
• Required resources/approvals listed

Owner / Assignee

Responsible Party: [To be assigned]