audit: github-label-audit - Specification, Planning & Task Decomposition (007)

reports/audits/2026-09-14-label-audit/audit-report.md

@@ -0,0 +1,79 @@
+# GitHub Label Audit Report
+**Date**: 2026-09-14
+**Repository**: lightspeedwp/.github
+**Scope**: Comprehensive audit of label governance, consistency, and consolidation opportunities
+
+## Executive Summary
+
+This audit analyzed **162** labels across **15** families in the canonical label configuration. The analysis identified governance inconsistencies, documentation gaps, and consolidation opportunities while preserving the immutability of **25** type labels.
+
+### Key Findings
+
+1. **Governance Policy Gaps**: 12 labels exist in governance policy but not in canonical labels.yml
+2. **Type Label Color Mismatches**: 3 of 25 type labels have color discrepancies between issue-types.yml and labels.yml
+3. **Documentation Inconsistencies**: 14 of 18 documentation files reference labels not in canonical configuration
+4. **Consolidation Opportunities**: 28 medium-impact label consolidation candidates identified
+5. **Archived Workflows**: 4 workflows require investigation for potential restoration or retirement
+
+## Detailed Findings
+
+### Finding 1: Governance Policy Inconsistencies
+**Severity**: Medium | **Evidence**: `.github/label-governance-policy.yml` vs `.github/labels.yml`
+
+12 labels are protected by governance policy but missing from canonical configuration:
+- Example missing labels include variations that may have been deprecated or consolidated
+
+**Recommendation**: Reconcile governance policy with canonical labels. Remove obsolete entries or add missing labels to canonical.
+
+### Finding 2: Type Label Validation
+**Severity**: Low | **Evidence**: `.github/issue-types.yml` vs `.github/labels.yml`
+
+All 25 type labels present in canonical, but 3 have color mismatches:
+- type:improve, type:dependency, type:review have different color values
+- Evidence: See `evidence/type-labels-validation.json`
+
+**Recommendation**: Align color definitions between issue-types.yml and labels.yml for consistency.
+
+### Finding 3: Documentation Gaps
+**Severity**: Medium | **Evidence**: `docs/LABEL_*.md`, `docs/ISSUE_*.md`, `docs/PR_*.md`
+
+17 labels mentioned in documentation are not in canonical configuration. 14 documentation files have undefined label references.
+
+**Recommendation**: Either add referenced labels to canonical or update documentation to use only canonical labels.
+
+## Label Inventory Summary
+
+| Metric | Count |
+|--------|-------|
+| Total Labels | 162 |
+| Label Families | 15 |
+| Type Labels (Immutable) | 25 |
+| Governance Protected | 57 |
+| Consolidation Candidates (Medium Impact) | 28 |
+
+## Evidence Location
+
+All detailed findings exported to JSON for analysis:
+- `evidence/canonical-labels.json` - Complete 162-label inventory
+- `evidence/governance-gaps.json` - Governance policy inconsistencies
+- `evidence/type-labels-validation.json` - Type label validation results
+- `evidence/duplicates-analysis.json` - Consolidation candidates ranked by impact
+- `evidence/documentation-gaps.json` - Documentation reference audit
+- `evidence/workflow-analysis.json` - Archived workflow assessment
+
+## Audit Scope & Constraints
+
+✅ **Audit-Only Analysis** - No changes made to production configuration
+✅ **Type Label Immutability** - 25 type labels confirmed immutable
+✅ **Read-Only** - All source files reviewed without modification
+✅ **Evidence-Based** - All findings include specific file references
+
+## Next Steps
+
+1. **Phase 2 (Planning)**: Prioritize which governance gaps to resolve
+2. **Phase 3 (Consolidation)**: Execute label consolidation for medium-impact duplicates
+3. **Phase 4 (Workflow Restoration)**: Investigate and restore archived labeling workflows
+4. **Phase 5 (Validation)**: Re-run audit to confirm improvements
+
+---
+Generated by Claude Code | Session: audit/github-label-audit

reports/audits/2026-09-14-label-audit/audit-summary.json

@@ -0,0 +1,26 @@
+{
+  "audit_date": "2026-09-14",
+  "statistics": {
+    "total_labels": 162,
+    "label_families": 15,
+    "type_labels_immutable": 25,
+    "governance_protected_labels": 57,
+    "documented_labels": 17,
+    "documentation_gaps": 17,
+    "potential_duplicates": 73,
+    "archived_workflows": 11
+  },
+  "key_findings": {
+    "governance_label_gaps": 12,
+    "type_label_color_mismatches": 3,
+    "medium_consolidation_candidates": 28,
+    "workflows_to_investigate": 4
+  },
+  "phases_complete": {
+    "phase_1_setup": true,
+    "phase_2_extraction": true,
+    "phase_3_analysis": true,
+    "phase_4_workflow_analysis": true,
+    "phase_5_integration": "in_progress"
+  }
+}

reports/audits/2026-09-14-label-audit/duplicates-analysis.md

@@ -0,0 +1,54 @@
+# Label Consolidation Analysis
+**Date**: 2026-09-14
+**Focus**: Identifying and ranking label consolidation opportunities
+
+## Overview
+
+This report identifies **73** potential label consolidation candidates ranked by consolidation impact. This analysis supports governance planning for label taxonomy simplification and reduction.
+
+### Consolidation Summary
+
+| Impact Level | Count | Action |
+|--------------|-------|--------|
+| HIGH | 0 | Immediate consolidation recommended |
+| MEDIUM | 28 | Review for consolidation during next cycle |
+| LOW | 45 | Low priority, consolidate if convenient |
+
+## Consolidation Candidates (Ranked by Impact)
+
+### Medium Impact Candidates
+
+These labels show moderate similarity and represent consolidation opportunities:
+
+| Label 1 | Label 2 | Similarity | Recommendation |
+|---------|---------|------------|----------------|
+| lang:js | lang:json | 0.875 | Consider consolidation |
+| status:needs-design | status:needs-testing | 0.872 | Consider consolidation |
+| meta:needs-changelog | meta:no-changelog | 0.865 | Consider consolidation |
+| status:needs-design | status:needs-dev | 0.857 | Consider consolidation |
+| status:needs-dev | status:needs-review | 0.857 | Consider consolidation |
+| area:ci | area:ai | 0.857 | Consider consolidation |
+| status:needs-qa | status:needs-audit | 0.848 | Consider consolidation |
+| release:minor | release:major | 0.846 | Consider consolidation |
+| status:needs-design | status:needs-design-review | 0.844 | Consider consolidation |
+| status:needs-design-review | status:needs-review | 0.844 | Consider consolidation |
+
+
+## Consolidation Strategy
+
+### Approach
+1. **Preserve Immutable Labels**: Type labels (type:*) cannot be changed
+2. **Preserve Governance Protected**: Labels in governance policy must be maintained
+3. **Consolidate Similar Labels**: Within same family, merge similar naming/purpose
+
+### Example Consolidation Patterns
+- Abbreviations: `type:documentation` → `type:docs`
+- Variant spellings: Different naming conventions unified
+- Overlapping purposes: Related labels merged
+
+## Evidence
+- Full duplicate analysis: `evidence/duplicates-analysis.json`
+- Canonical labels: `evidence/canonical-labels.json`
+
+---
+Generated by Claude Code | Session: audit/github-label-audit

reports/audits/2026-09-14-label-audit/evidence/archived-workflows.json

@@ -0,0 +1,162 @@
+{
+  "total_archived_workflows": 11,
+  "location": ".github/workflows/archived/2026-09-11/labeling",
+  "workflows": [
+    {
+      "filename": "batch-label-prs.yml",
+      "path": ".github/workflows/archived/2026-09-11/labeling/batch-label-prs.yml",
+      "name": "Batch Label PRs",
+      "purpose": "",
+      "labels_referenced": [],
+      "triggers": [
+        "name",
+        true,
+        "jobs"
+      ],
+      "raw_content_lines": 68
+    },
+    {
+      "filename": "issue-labeling-automation.yml",
+      "path": ".github/workflows/archived/2026-09-11/labeling/issue-labeling-automation.yml",
+      "name": "Issue Labeling Automation",
+      "purpose": "",
+      "labels_referenced": [],
+      "triggers": [
+        "name",
+        true,
+        "jobs"
+      ],
+      "raw_content_lines": 166
+    },
+    {
+      "filename": "label-audit-report.yml",
+      "path": ".github/workflows/archived/2026-09-11/labeling/label-audit-report.yml",
+      "name": "Label Audit Report",
+      "purpose": "",
+      "labels_referenced": [],
+      "triggers": [
+        "name",
+        true,
+        "permissions",
+        "jobs"
+      ],
+      "raw_content_lines": 111
+    },
+    {
+      "filename": "labeling-governance.yml",
+      "path": ".github/workflows/archived/2026-09-11/labeling/labeling-governance.yml",
+      "name": "Labeling \u2022 Unified Governance (PRs, Issues, Discussions & Cleanup)",
+      "purpose": "",
+      "labels_referenced": [],
+      "triggers": [
+        "name",
+        true,
+        "permissions",
+        "concurrency",
+        "env",
+        "jobs"
+      ],
+      "raw_content_lines": 499
+    },
+    {
+      "filename": "labeling.yml",
+      "path": ".github/workflows/archived/2026-09-11/labeling/labeling.yml",
+      "name": "Labeling \u2022 Discussions, Issues & PRs (Unified)",
+      "purpose": "",
+      "labels_referenced": [],
+      "triggers": [
+        "name",
+        true,
+        "permissions",
+        "concurrency",
+        "env",
+        "jobs"
+      ],
+      "raw_content_lines": 124
+    },
+    {
+      "filename": "manage-blocking-status-labels.yml",
+      "path": ".github/workflows/archived/2026-09-11/labeling/manage-blocking-status-labels.yml",
+      "name": "Manage Blocking Status Labels",
+      "purpose": "",
+      "labels_referenced": [],
+      "triggers": [
+        "name",
+        true,
+        "permissions",
+        "jobs"
+      ],
+      "raw_content_lines": 124
+    },
+    {
+      "filename": "meta-labels-sync.yml",
+      "path": ".github/workflows/archived/2026-09-11/labeling/meta-labels-sync.yml",
+      "name": "Meta Labels Sync",
+      "purpose": "",
+      "labels_referenced": [],
+      "triggers": [
+        "name",
+        true,
+        "permissions",
+        "jobs"
+      ],
+      "raw_content_lines": 112
+    },
+    {
+      "filename": "openspec-sync-labels.yml",
+      "path": ".github/workflows/archived/2026-09-11/labeling/openspec-sync-labels.yml",
+      "name": "OpenSpec Sync Labels",
+      "purpose": "",
+      "labels_referenced": [],
+      "triggers": [
+        "name",
+        true,
+        "permissions",
+        "jobs"
+      ],
+      "raw_content_lines": 55
+    },
+    {
+      "filename": "openspec-validate-labels.yml",
+      "path": ".github/workflows/archived/2026-09-11/labeling/openspec-validate-labels.yml",
+      "name": "OpenSpec Validate Labels",
+      "purpose": "",
+      "labels_referenced": [],
+      "triggers": [
+        "name",
+        true,
+        "permissions",
+        "jobs"
+      ],
+      "raw_content_lines": 72
+    },
+    {
+      "filename": "remediate-bare-labels.yml",
+      "path": ".github/workflows/archived/2026-09-11/labeling/remediate-bare-labels.yml",
+      "name": "Remediate Bare Labels (Phase 2)",
+      "purpose": "",
+      "labels_referenced": [],
+      "triggers": [
+        "name",
+        true,
+        "permissions",
+        "jobs"
+      ],
+      "raw_content_lines": 240
+    },
+    {
+      "filename": "validate-issue-labels.yml",
+      "path": ".github/workflows/archived/2026-09-11/labeling/validate-issue-labels.yml",
+      "name": "Issue Label Validation",
+      "purpose": "",
+      "labels_referenced": [],
+      "triggers": [
+        "name",
+        true,
+        "permissions",
+        "jobs"
+      ],
+      "raw_content_lines": 121
+    }
+  ]
+}