feat: spec-labels - Align lifecycle tracking with GitHub Spec Kit #1944

Feature Summary

Align this historical lifecycle-label request with GitHub Spec Kit and the existing specification-label consolidation.

The documented target family is spec:*, not speckit:*. Current canonical configuration still declares openspec:*; the target namespace must not be described as already implemented or approved.

This update reconciles the original requirement with existing migration work. It does not establish a second migration owner or authorise implementation.

Context and Sources

Repository: lightspeedwp/.github.

Verified develop revision: b63f9bb.

• Spec 008, FR-011, identifies spec:* as the target successor to openspec:*; current declarations remain authoritative until the approved configuration change is applied.
• FR-013 distinguishes speckit tooling/process terminology from spec/specs artefact and label terminology.
• Canonical labels currently contain nine openspec:* declarations.
• Label-family validation retains openspec: as active and identifies spec: and spec-id: as Stage 2 targets.
• Existing mapping tooling distinguishes straightforward renames from judgement calls requiring approval.

These are repository-source findings, not verification of every live GitHub label, synchronised Linear record or deployed automation.

Linked Stories/Tasks

• GIT-2591 / GitHub #3834: existing approval request covering the namespace migration and gap mappings.
• GIT-2597: separate OpenSpec path-migration work; excluded from this issue.
• feat: Add OpenSpec status labels for specification/implementation lifecycle #1943: closed without merging. Its descriptions of completion, testing and production readiness are historical assertions, not verified current results.

These references do not create native relationships or closing associations.

Proposed Solution

Track the existing consolidation rather than introduce speckit:* or duplicate its implementation.

The nine declared lifecycle labels have the following documented target mapping. This table records the intended mapping; it does not approve or apply it.

The original six-label description includes openspec:specification-pending, which is absent from the inspected canonical declarations. Mapping tooling proposes spec:planning for that gap as a judgement call requiring approval.

Numeric specification identifiers belong to the separately documented spec-id:* family; they are not lifecycle labels.

Label names, including status-production and implementation-complete, do not independently establish deployment, acceptance or release.

Scope and Constraints

Included:

• Reconcile the historical lifecycle requirements with the existing nine-label migration.
• Record mapping decisions, approval dependencies and verified migration evidence.
• Identify any genuinely unmet requirement without automatically creating additional work.

Excluded:

• A second implementation of the existing consolidation.
• Introducing a speckit:* label family.
• Repository edits, live-label changes or synchronisation changes through this issue update.
• Bulk issue/PR description rewriting or execution of the historical auto-update script.
• OpenSpec path migration, organisation-wide cleanup or unrelated template changes.
• Automatic closure, duplicate marking, reparenting or reassignment of any issue.

Milestones & Timeline

No new dates, milestones or delivery commitments are proposed.

Implementation verification depends on the existing migration’s approved mapping and Stage 2 configuration evidence.

Acceptance Criteria

• The nine current declarations and documented target mappings are reconciled against the approved migration decision.
• The historical specification-pending gap has an explicit approved mapping or retirement decision.
• Dated approval and relevant configuration evidence are linked when available; unresolved evidence remains explicitly identified.
• Lifecycle requirement coverage is checked against the existing migration, with residual gaps recorded for a separate scope decision.
• Historical completion claims remain distinguishable from verified current results.
• No duplicate migration, new label family, bulk rewriting or unrelated path migration is introduced.

Designs / References

No design assets are required for this record reconciliation. Repository sources and related work are linked above.

Dependencies

Changes to protected .github/labels.yml require the repository’s [LABEL-UPDATE-REQUEST] process and explicit approval. Approved configuration must precede live renaming.

Existing migration work owns its implementation sequencing and dependencies. This issue update does not alter those relationships.

Testing Approach

This assessment used static repository and record inspection. No commands or tests were executed.

Any later implementation verification must reference the actual approved configuration revision and relevant consumer, validation and migration evidence. Historical test counts are not treated as current passing results.

Branch instructions

Not applicable to this reconciliation-only update: no separate repository change is proposed.

Repository implementation remains within the existing consolidation. Any residual implementation requires separately verified scope, branch/base, naming policy, PR template, implementing targets and approval.

Expected file changes

None proposed by this record update. No branch creation, repository edits or PR associations are authorised.

Definition of Ready — Current Reconciliation

• Existing migration scope and the historical lifecycle requirements have been reconciled.
• Outstanding mapping and approval decisions are explicit.
• Any residual implementation scope is separately agreed before work starts.

Definition of Done — Current Reconciliation

• Acceptance evidence and unresolved findings are recorded without overstating completion.
• Historical claims and checkbox states remain preserved and clearly separated from current evidence.
• No implementation, deployment, acceptance or release is inferred from this record update.

Historical OpenSpec Record — Retained, Not Revalidated

The original description follows unchanged. Its “Delivered”, “COMPLETE”, “Production Ready”, test counts and checked criteria are preserved historical assertions, not endorsed current findings. PR #1943 is closed without merging; this does not by itself prove that equivalent work was never delivered elsewhere.

Overview

Add OpenSpec status labels and comprehensive automation infrastructure to enable tracking of specification and implementation phases for all agents, projects, and initiatives.

Description

The labeling system needed explicit support for tracking OpenSpec lifecycle phases. This feature adds:

1. 6 standardized OpenSpec labels — Track specification/implementation phases
2. Auto-update-all.js script — Automated label and template management

Scope

OpenSpec Status Labels (Delivered)

Auto-Update Script (Delivered)

Comprehensive automation for repository maintenance:

• Auto-detects issue types from titles
• Adds missing labels (65+ issues)
• Injects template sections (104+ issues)
• Updates PR descriptions (15+ PRs)
• Batch processing and statistics tracking

Test Coverage (Delivered)

• 25+ comprehensive test cases
• Label configuration validation
• Template section detection
• Integration testing

Benefits

• Visibility: Clear view of specification/implementation phases
• Standardization: Consistent labeling across all projects
• Automation: Reduces manual maintenance burden
• Coordination: Supports cross-project sequencing
• Testing: Comprehensive validation coverage

Implementation Status

✅ COMPLETE — All acceptance criteria met

• 6 labels defined in .github/labels.yml
• Labels follow openspec:{phase}-{status} naming convention
• Color scheme consistent (Blue→Yellow→Green lifecycle)
• PR created with implementation (feat: Add OpenSpec status labels for specification/implementation lifecycle #1943)
• Auto-update script created and tested
• Comprehensive test suites added (2 test files, 25+ cases)
• All 300+ issues updated with labels and templates
• All 21+ PRs updated with proper templates

Related Issues/PRs

PR: #1943 — OpenSpec Status Labels + Auto-Update Script
Automation Results: 184 updates across 321 items
Test Coverage: 25+ test cases

Definition of Ready (DoR)

✅ COMPLETE

• Issue has clear acceptance criteria (6 labels + script)
• Related issues are linked (feat: Add OpenSpec status labels for specification/implementation lifecycle #1943)
• Scope is well-defined (labels + automation)
• Acceptance criteria documented
• Test cases identified

Definition of Done (DoD)

✅ COMPLETE

• Code is reviewed and approved (PR feat: Add OpenSpec status labels for specification/implementation lifecycle #1943)
• Tests pass (unit + integration, 25+ cases)
• Documentation updated (inline comments, test docs)
• Changelog entry added (PR feat: Add OpenSpec status labels for specification/implementation lifecycle #1943)
• Labels synced to GitHub configuration
• Automation script production-ready
• All team notified of new labels

Version

• Phase: Phase 1A (Labels Infrastructure)
• Status: ✅ Production Ready
• Target Merge: develop branch

Owner / Assignee

Responsible Party: [To be assigned]

Team/Area: [Identify relevant team or codebase area]

Acceptance Criteria

• [Specific, testable requirement 1]
• [Specific, testable requirement 2]
• [Specific, testable requirement 3]

Chat planning decision and namespace conflict — 14 November 2026

Decision required from Chris

This description currently requires spec:* and explicitly excludes speckit:*. The migration chat and GIT-2521 namespace addendum selected speckit:*.

Preserve this conflicting evidence. Chris must explicitly reconcile the intended namespace and dependent requirements before implementation. This section does not silently override the existing requirements.

Accepted B1 planning design

Ash accepted B1 revision 1 as a planning design, not save or implementation authorisation:

• Consolidate openspec:specification-pending into speckit:planning, not discovery.
• Retain six automated progression states within nine recognised labels.
• Preserve existing event wiring and transition/rollback edges.
• Keep additional safeguards as separately proposed scope.

The accepted description changes are:

• speckit:planning: "Spec Kit planning phase - planning/scoping or awaiting specification drafting"
• speckit:specification-in-progress: "Spec Kit specification phase - specification being drafted or revised"

The planning description broadens the old "improvement plan documented" meaning. This is an explicit semantic decision, not merely a prefix replacement.

Nine-label planning candidate

Preserve canonical colours. Existing Linear sources use the corresponding spec:* names and workspace identities. No speckit:specification-pending label is proposed.

Live slash-style testing/production labels require explicit reconciliation. Existing spec:planning and spec:implementation-pending create many-to-one source cases. Migration markers remain separately reviewed retirement candidates.

Numeric spec:001 is a specification identifier, with proposed destination spec-id:001; it must not become speckit:001.

Automation boundary

The inspected PR-driven progression was:

Discovery, testing and production had no inspected automatic edges. Do not invent those transitions or infer deployment evidence from a label.

The inspected workflow synchronises issue labels but does not initialise phase labels or advance phases on status-label additions. No new wiring is included.

Coordinated consumer changes to prepare

• Amend Spec 008 FR-011 after namespace resolution.
• Align .github/labels.yml and scripts/automation/label-mapping.cjs.
• In scripts/automation/includes/phase-state-machine.cjs, classify planning explicitly as specification/pending rather than relying on its suffix.
• Align scripts/automation/handlers/handle-issue-created.cjs with approved state constants and distinguish all recognised labels from progression states.
• Coordinate orchestrate-phase-progression.cjs, sync-labels-on-event.cjs, handle-issue-labeled.cjs and includes/label-validator.cjs.
• Align scripts/validation/lib/label-families.cjs, mapping evidence and affected tests.
• Preserve unknown-gap rejection, identifier separation, historical source keys and existing trust/write boundaries.

Repository inspection was pinned to b63f9bb. Refresh before implementation.

Proposed verification

Verify nine canonical labels, six automated states, canonical initial outputs, planning classification, unchanged transition/rollback edges, safe missing/ambiguous-state handling, assignment preservation and unchanged native Linear fields.

Unknown-state guards, workflow success checks, invalid-transition status writes and terminal-status corrections remain separate proposed safeguards requiring scope decisions. Tests were inspected, not executed; no passing or deployment claim is made.

Live inventory, remaining semantic holds, consumer coverage, synchronisation behaviour and mandatory approvals remain execution gates.