epic: label-governance - Stabilise canonical labels and harden workflow automation #449

Epic Summary

Stabilise label governance by resolving orphan labels, enforcing canonical label definitions, and hardening workflow policies that consume label metadata.

The epic also tracks the Audit routing and Review title-handling correction in #3737. This description update does not authorise implementation or locked-configuration changes.

Linked Child Issues/Stories/Tasks/PRs

Current child issues

• #3554 — Canonical conflict-resolution labels and approval-gate policy.
• #3737 — Align Audit routing and Review title handling.

Original related work

• #95 — Orphan labels audit and remediation.
• #66 — Canonical labels and seeding workflow.
• #67 — README regeneration scoping and concurrency guard.
• #69 — CodeRabbit-before-Copilot review order enforcement.

These four original issues are closed. Their historical closure does not establish completion of the reopened epic or its current children.

Milestones & Timeline

The existing GitHub milestone is v1.3. No new milestone, deadline or estimate is proposed.

The original sequencing placed #95 before #66, #67 and #69. Current child dependencies remain defined in their own issues.

For #3737, any separately approved metadata correction on PR #3725 must follow the fix’s merge.

Acceptance Criteria

• Orphan label set is remediated and documented.
• Canonical label source of truth and seeding workflow are aligned.
• README regeneration automation is scoped to changed paths and race-safe.
• Review order policy is codified and validated in workflows.
• The Audit routing and Review title-handling acceptance criteria in fix: label-governance - Align Audit routing and Review title handling #3737 are met.
• All linked stories/tasks completed
• Documentation and changelog updated
• Tests/QA complete
• PR description updated with relevant details
• Changelog entry prepared for PR (if applicable)
• Labels/types match org standards

Criteria remain unchecked; this update does not claim completed implementation, QA or approval.

Dependencies / Blockers

• The original cleanup dependency required current inventory output from #95. Its historical audit does not establish a fresh inventory for further cleanup.
• Workflow validation in CI-compatible local commands remains required.
• chore: labels - Add conflict-resolution labels to canonical taxonomy [LABEL-UPDATE-REQUEST] #3554 contains separate approval and delivery requirements for locked canonical-label changes.
• fix: label-governance - Align Audit routing and Review title handling #3737 does not authorise locked taxonomy or template edits, new review/ branches, or the separate PR audit: label-consolidation - Export Linear labels and draft Stage 1 change requests #3725 metadata change.
• Chris has been asked to review the child and parent. No completed review is recorded by this update.

Additional Context

The original description assigns this epic to .github/projects/active/label-governance-stabilisation-2026-05-27/.

That directory was not found on current develop. The reference is retained for traceability; its current location requires confirmation.

The epic was historically reported complete in May 2026, but is currently open with active children. Historical inventory counts and completion comments are not current validation.

This concerns repository governance and automation, not a WordPress application runtime. Locked taxonomy and template files are not being edited.

Definition of Ready (DoR)

• Epic goal and scope defined
• Linked stories/tasks listed
• Milestones and timeline mapped
• Dependencies/blockers identified
• Estimate added (if applicable)
• Stakeholders/approvers listed
• Success criteria and measurable outcomes documented
• Timeline and resource estimates provided
• Stakeholder alignment confirmed

Definition of Done (DoD)

• Approved by at least one maintainer
• All linked stories/tasks completed and closed
• Documentation/changelog updated
• QA and testing complete
• All child issues closed before epic can be closed
• Epic issue must be updated with latest status before being closed
• Epic acceptance criteria met
• Epic documentation and summary updated
• Release notes and announcement prepared
• Post-launch monitoring and support plan in place
• Retrospective completed (if applicable)

Label governance and expansion — planning consolidation, 14 November 2026

Approved delivery approach

Accurate labels and canonical-source-driven automation are a high-importance delivery outcome. Chris leads unresolved decisions, subject to existing mandatory approvals.

Distinguish shared workflow labels, GitHub-only labels and Linear-only labels. Absence from another platform must not automatically trigger creation or deletion.

Proposed lasting expansion procedure

1. Request the purpose, name, description, colour, scope, applicable systems and automation consumers.
2. Check reusable labels, duplicate meanings, collisions, source/target assignments and dependent rules.
3. Record Chris's decision and all mandatory approvals against an exact candidate.
4. Change the appropriate authoritative definition: approved repository sources for shared/GitHub-workflow labels; separately governed Linear definitions with exact identities/scopes and synchronisation exclusions for Linear-only labels.
5. Apply changes only to applicable systems, preserving assignments and native Linear fields.
6. Verify routing, synchronisation, metadata and recovery; retain evidence and a future drift/change path.

This is the proposed operational procedure for the approved approach. It is not evidence that the procedure has been implemented or tested.

Legacy disposition amendment revision 2

The following exact-source dispositions remain proposals. They replace generic retirement reasoning at planning level only:

The adjacent openspec:status/implementation label retains its separate unresolved hold.

Saved audit rows proposing retirement with null targets are not approval or proof of semantic equivalence. Generator fragment rules such as openspec:domain do not establish mappings for concrete slash labels.

Existing targets and dependencies

The ten proposed shared targets already have distinct workspace-scoped, active, ungrouped Linear identities. Resolve and preserve those exact identities before execution; do not create same-named replacements or collapse separate migrate labels.

Eight targets are canonical and live in GitHub. area:workflows exists live but lacks a canonical declaration; its current live colour ededed differs from the proposed import colour 0F448A. Import and metadata changes require exact approval.

aiops:agents exists in Linear but was absent from canonical/live GitHub, where ai-ops:agents remains the current spelling. Do not silently substitute or duplicate these identities.

Several live GitHub descriptions are empty despite canonical definitions. These are recorded discrepancies, not incidental repair authorisation.

Linear priority-label descriptions preserve native priority as authoritative. status:blocked does not change native status, establish completion or grant approval.

Consolidation and retirement gates

• Inventory source and occupied-target assignments and overlap before choosing a procedure.
• Preserve target identity, assignments and metadata unless separately approved.
• Verify destination assignments before source retirement.
• Check Discussions, active metadata, generic prefix consumers and external dependencies.
• Preserve historical source names and evidence; do not rewrite historical snapshots as current findings.
• Obtain exact per-label disposition and applicable repository approvals.

The 12 November investigation found no GitHub issue/PR assignments on the 14 sources, but target usage was substantial. Zero assignments do not authorise deletion. No retirement, consolidation or metadata change is approved by this section.