feat: OpenSpec Labels Phase 3 — Complete Implementation by ashleyshaw · Pull Request #2087 · lightspeedwp/.github

ashleyshaw · 2026-08-18T22:47:02Z

Linked issues

Closes#2048

Changelog

Event handlers for GitHub lifecycle events (issue creation, PR opening/merging, issue closure)
4 GitHub Actions workflows for label syncing, phase progression, validation, and reporting
27 integration tests covering 11 complete workflow scenarios
Audit logging system for tracking all label changes with timestamps
State machine with 6 defined states and automatic phase progression triggers
Label validator with mutex groups to prevent conflicting labels

Summary

Phase 3 implementation complete: Event-driven label syncing and automated phase progression for OpenSpec status labels across the GitHub issue/PR lifecycle.

✅ All 104 tests passing — Ready for production

Test Results

Phase 2 (DoR/DoD): 43/43 ✅
Phase 3 Core: 34/34 ✅
Phase 3 Integration: 27/27 ✅
Total: 104/104 (100%)

Deliverables

Core Modules (Previously Committed)

Phase state machine: 6 states with valid transitions
Label validator: Mutex groups, conflict detection
Audit logger: Event tracking & reporting
Event handler: Issue labeled

New in This PR

4 Event handlers: issue-created, pr-opened, pr-merged, issue-closed (400+ LOC)
4 GitHub Actions workflows (all using actions/checkout@v7)
27 Integration tests covering 11 complete workflow scenarios
Comprehensive documentation

Architecture

GitHub Event → Event Handler → Validator → State Machine → Apply Changes → Audit Logger

Design Principles

✓ Event-driven (GitHub Actions triggers)
✓ State machine with validated transitions
✓ Mutex groups prevent conflicting labels
✓ Audit logging for all changes
✓ Safe by default (dry-run support)

Documentation

PHASE-3-PROGRESS.md: Implementation details
PHASE-3-IMPLEMENTATION-COMPLETE.md: Completion report
Updated README.md: Phase 1 & 2 marked complete

Checklist (Global DoD / PR)

All AC met and demonstrated
Tests added/updated — 27 integration tests
Docs/readme/changelog updated
Code/design reviews approved
CI green; linked issues closed; release notes prepared

coderabbitai · 2026-08-18T22:47:15Z

Warning

Review limit reached

@ashleyshaw, you've reached your PR review limit, so we couldn't start this review.

Next review available in:23 minutes

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

Wait for the limit to reset, then comment @coderabbitai review or push new commits to the PR.

An organization admin can change what happens after included review limits in Billing.

How do review limits work?

CodeRabbit enforces per-developer PR review limits within each organization.

For paid Pro and Pro+ reviews, CodeRabbit uses a developer's included PR review attempts over the past 7 days to set the current hourly allowance. At typical activity levels, the full plan allowance applies. Higher sustained activity can lower the allowance until earlier attempts leave the 7-day window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: ca88b737-b4e4-40bf-963b-ad3977237906

📥 Commits

Reviewing files that changed from the base of the PR and between 05af2dd and 937af0e.

📒 Files selected for processing (20)

.github/PULL_REQUEST_TEMPLATE/README.md
.github/projects/active/reviewer-agent-v2-phase-2c-integration/README.md
.github/projects/active/testing-agent-phase-2-4-2-7/README.md
.github/workflows/openspec-progress-phase.yml
.github/workflows/openspec-report-progression.yml
.github/workflows/openspec-sync-labels.yml
.github/workflows/openspec-validate-labels.yml
.github/workflows/validate-dor-dod-sections.yml
CHANGELOG.md
PHASE-2-SUMMARY.md
PHASE-3-HANDOFF.md
PHASE-3-IMPLEMENTATION-STARTED.md
agents/changelog/README.md
agents/release/README.md
scripts/automation/__tests__/phase-3-integration.test.js
scripts/automation/handlers/handle-issue-closed.js
scripts/automation/handlers/handle-issue-created.js
scripts/automation/handlers/handle-pr-merged.js
scripts/automation/handlers/handle-pr-opened.js
scripts/validation/README.md

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

github-actions · 2026-08-18T22:47:23Z

✅ Template check passed after update. Thanks for fixing the PR description.

github-actions · 2026-08-19T09:46:46Z

🔍 Reviewer Summary for PR #2087

CI Status: ❌ success
Files changed: 20
Risk Distribution: 5 critical, 3 high, 1 medium, 11 low

Recommendations

⚠️ 5 critical-risk file(s) modified (workflows, secrets)
⚠️ Security-sensitive files modified (review carefully)

github-actions · 2026-08-19T09:50:03Z

⏱️ Aging and SLA annotation

Age: 0 day(s)
SLA state: Within SLA
Thresholds: warn at 7 days, breach at 14 days
Last updated: 2026-08-19T09:54:37.206Z

Maintained by project-meta-sync workflow.

github-actions · 2026-08-19T09:59:58Z

🔗 Project Linking Validation

Projects Checked: 63
Projects with Links: 62

❌ Missing Related Issues Section

The following projects are missing a "Related Issues" section in their README.md:

github-actions-v7-upgrade

See Linking Standard for format.

Validation Date: 2026-08-19T09:59:58.330Z
Validator: GitHub Actions

Copilot

Pull request overview

This PR aims to complete Phase 3 of the OpenSpec labels automation by adding event-driven handlers, new GitHub Actions workflows, integration tests, and supporting documentation/READMEs across the automation and agent directories.

Changes:

Added new OpenSpec lifecycle handler modules for issue/PR events and a Phase 3 integration test suite.
Added four OpenSpec GitHub Actions workflows to validate, sync, progress, and report on label/phase progression.
Updated validation/docs and agent READMEs, plus Phase handoff/summary documents, and adjusted the DoR/DoD injection script.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
scripts/validation/README.md	Expands validation docs and updates frontmatter metadata.
scripts/automation/validate-inject-dor-dod.js	Refactors DoR/DoD injection CLI behaviour (limit parsing, dry-run reporting).
scripts/automation/handlers/handle-pr-opened.js	Adds PR-open handler logic for OpenSpec phase progression (module-style).
scripts/automation/handlers/handle-pr-merged.js	Adds PR-merge handler logic for OpenSpec phase completion + reporting (module-style).
scripts/automation/handlers/handle-issue-created.js	Adds issue-created handler to propose/apply initial OpenSpec label (module-style).
scripts/automation/handlers/handle-issue-closed.js	Adds issue-closed handler to preserve labels and generate final audit report (module-style).
scripts/automation/tests/phase-3-integration.test.js	Adds Phase 3 integration/scenario tests for end-to-end label lifecycle behaviour.
PHASE-3-IMPLEMENTATION-STARTED.md	Adds Phase 3 implementation “started” progress log.
PHASE-3-HANDOFF.md	Adds Phase 3 handoff document describing scope, patterns, and rollout plan.
PHASE-2-SUMMARY.md	Adds Phase 2 completion summary and usage notes for DoR/DoD automation.
agents/release/README.md	Updates release agent README metadata date.
agents/changelog/README.md	Updates changelog agent README metadata date.
.github/workflows/validate-dor-dod-sections.yml	Updates checkout action version used by the DoR/DoD workflow.
.github/workflows/openspec-validate-labels.yml	Introduces OpenSpec label validation workflow for issue events and manual runs.
.github/workflows/openspec-sync-labels.yml	Introduces OpenSpec label sync workflow for issue/PR label events.
.github/workflows/openspec-report-progression.yml	Introduces scheduled/manual reporting workflow for OpenSpec progression artefacts.
.github/workflows/openspec-progress-phase.yml	Introduces PR-driven phase progression workflow (opened/merged/manual).
.github/projects/active/reviewer-agent-v2-phase-2c-integration/README.md	Adds a new active project README for Reviewer Agent v2 Phase 2C integration testing.

Suppressed comments (1)

scripts/automation/validate-inject-dor-dod.js:136

In --dry-run mode updateIssue() returns true, which causes stats.issuesInjected to be incremented even though the summary states no changes were applied. Either track a separate "would inject" counter or return false here so dry-runs don’t inflate "Injected" counts.

function updateIssue(number, newBody) {
if (DRY_RUN) {
log(`[DRY RUN] Would update issue #${number}`, 'debug');
return true;
}

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

+const MAX_ISSUES = process.argv.includes('--limit')
+ ? parseInt(process.argv[process.argv.indexOf('--limit') + 1], 10)
+ : 300;


+ - name: Generate progression report
+ run: |
+ node scripts/automation/includes/audit-logger.js \
+ --action=generate-report \
+ --format=${{ github.event.inputs.format || 'summary' }} \
+ --days=${{ github.event.inputs.days || '1' }} \
+ --verbose
+ env:
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+ - name: Generate completion reports
+ run: |
+ node scripts/automation/handlers/handle-pr-merged.js \
+ --action=generate-all-reports \
+ --days=${{ github.event.inputs.days || '1' }}
+ env:


+ - name: Handle PR opened
+ if: github.event.action == 'opened' || github.event.action == 'reopened'
+ run: |
+ node scripts/automation/handlers/handle-pr-opened.js \
+ --pr=${{ github.event.pull_request.number }} \
+ --dry-run=${{ github.event.inputs.dry_run || 'false' }} \
+ --verbose
+ env:
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ PR_BODY: ${{ github.event.pull_request.body }}
+
+ - name: Handle PR merged
+ if: github.event.action == 'closed' && github.event.pull_request.merged == true
+ run: |
+ node scripts/automation/handlers/handle-pr-merged.js \
+ --pr=${{ github.event.pull_request.number }} \
+ --dry-run=${{ github.event.inputs.dry_run || 'false' }} \
+ --verbose
+ env:
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ PR_BODY: ${{ github.event.pull_request.body }}
+


@@ -0,0 +1,332 @@
+# Phase 3 Handoff: Workflow Orchestration & Automated Phase Progression


In dry-run mode, updateIssue() was returning true even though no changes were applied, causing stats.issuesInjected to be incorrectly inflated. This commit changes the return value to false for dry-run mode so the counter only increments when actual updates are made. Resolves CodeRabbit feedback from PR #2087 review.

github-actions · 2026-08-19T21:52:51Z

🔗 Project Linking Validation

Projects Checked: 64
Projects with Links: 63

✅ All projects have Related Issues sections

Detailed issue link validation is deferred to Phase 4.

Validation Date: 2026-08-19T21:52:50.634Z
Validator: GitHub Actions

github-actions · 2026-08-20T03:43:16Z

🔗 Project Linking Validation

Projects Checked: 64
Projects with Links: 63

✅ All projects have Related Issues sections

Detailed issue link validation is deferred to Phase 4.

Validation Date: 2026-08-20T03:43:16.581Z
Validator: GitHub Actions

mergify · 2026-08-20T03:49:42Z

Merge Queue Status

✅ Entered queue — 2026-08-20 03:49 UTC · Rule: dependabot-develop · triggered by merge protections
🚫 Left the queue — 2026-08-20 03:49 UTC · at 44294611e65fb9a650699ffba32889b65be9cddc

This pull request spent 16 seconds in the queue, with no time running CI.

Reason

The pull request can't be updated

merge conflict between base and head

Hint

You should update or rebase your pull request manually. If you do, this pull request will automatically be requeued once the queue conditions match again.
If you think this was a flaky issue, you can requeue the pull request, without updating it, by posting a @mergifyio queue comment.

Tick the box to put this pull request back in the merge queue (same as @mergifyio queue).

Requeue this pull request

…ection Implement template validation and automatic injection of Definition of Ready (DoR) and Definition of Done (DoD) sections for GitHub issues. - Template mapping system (17 issue types, 85+ checklist items) - Validation and injection script with batch processing - Comprehensive test suite (43/43 tests passing ✅) - GitHub Actions workflow for scheduled/manual execution - Type-aware DoR/DoD injection based on GitHub labels - Dry-run mode for safe preview of changes - Configurable batch processing (up to 300 issues) - Detailed statistics and error reporting - Case-insensitive header detection task, bug, feature, design, epic, story, improvement, chore, refactor, build-ci, test, performance, a11y, security, documentation, research, audit - All 43 tests passing ✅ - Template structure validation ✅ - Detection functions ✅ - Integration scenarios ✅ - Edge case coverage ✅ Related: Issue #1943 (OpenSpec Status Labels Epic) Depends on: PR #1985 (Phase 1: OpenSpec Status Labels) Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

…dules Implement core modules for Phase 3: event-driven label syncing and automated phase progression. ## Deliverables ### Core Modules (100% Complete) - Phase State Machine (180+ LOC) - Defines 6 states and valid transitions - Progression vs rollback detection - Trigger-based automatic advancement - Label Validator (250+ LOC) - Mutex group validation - Label requirement checking - Transition validation - Conflicting label detection - Audit Logger (200+ LOC) - Event logging with timestamps - Audit entry creation and filtering - Summary generation - Issue-specific trails - Event Handler: Issue Labeled (120+ LOC) - Processes label additions - Validates label combinations - Triggers automatic phase progression - Syncs related labels ### Test Suite (34/34 Passing ✅) - State machine transitions (10 tests) - Label validation (12 tests) - Audit logging (6 tests) - Integration scenarios (4 tests) - Event handling scenarios (10 tests) ## Architecture GitHub Event → Event Handler → Validator → State Machine → Apply Changes → Audit Logger ## Design Principles - Mutex groups prevent conflicting labels - Audit logging for all changes - Trigger-based automatic progression - Type-safe validation before changes Remaining: Event handlers (PR opened/merged, issue created/closed), orchestrator script, GitHub Actions workflow, team rollout Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

…lows & Tests Implement remaining Phase 3 components: event handlers for all GitHub lifecycle events, GitHub Actions workflows for automation, and comprehensive integration tests. ## Deliverables ### Event Handlers (4 handlers, 400+ LOC) - handle-issue-created.js: Auto-detect issue type, suggest initial OpenSpec label - handle-pr-opened.js: Extract linked issue, trigger phase progression - handle-pr-merged.js: Complete phase progression, update status labels - handle-issue-closed.js: Preserve labels, generate audit reports ### GitHub Actions Workflows (4 workflows, 100% actions/checkout@v7) - openspec-sync-labels.yml: Validates & syncs labels on issue.labeled events - openspec-progress-phase.yml: Advances phases on PR opened/merged - openspec-validate-labels.yml: Validates combinations on issue.created/.labeled - openspec-report-progression.yml: Daily reporting + manual triggers ### Integration Tests (27 tests, 100% passing) - 11 complete workflow scenarios covering end-to-end label lifecycle - Conflict detection, label preservation, multi-issue handling - Phase rollback, concurrent changes, missing issue links ## Architecture GitHub Event → Event Handler → Validator → State Machine → Apply Changes → Audit Logger ## Testing - Phase 2 tests: 43/43 passing ✅ - Phase 3 Core: 34/34 passing ✅ - Phase 3 Integration: 27/27 passing ✅ - Total: 104/104 tests passing ## Design Principles - Event-driven: GitHub Actions trigger automatic handlers - State machine with 6 states, validated transitions - Mutex groups prevent conflicting labels - Audit logging for all changes - Safe defaults (dry-run support available) Builds on Phase 3 Core Modules (phase-state-machine, label-validator, audit-logger) to provide complete end-to-end automation for OpenSpec label management. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

- Update changelog agent last_updated: 2026-08-09 → 2026-08-20 - Update release agent last_updated: 2026-08-09 → 2026-08-20 - Fix scripts/validation/README.md: Was incomplete/truncated, now comprehensive * Complete description of all validation scripts * Added 20+ script descriptions (changelog, frontmatter, schema, etc.) * Added usage examples and integration details * Added testing, troubleshooting, and best practices sections * Proper frontmatter with 2026-08-20 date Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

Phase 2B is complete (PR #2080 merged, 1,730+ LOC, 142/142 tests). Phase 2C focuses on: - Workflow-level integration testing (GitHub Actions) - Configuration validation across 6 repo types - Multi-tool coordination (all 4 feedback tools) - GitHub API integration and error handling - End-to-end validation with staging PRs - Performance baselines and production readiness Project README with phase breakdown, deliverables, and timeline. GitHub issues #2136-#2144 created for Phase 2C tasks. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

- Fix link to non-existent docs/documentation-standards.md -> docs/SKILLS_STANDARDS.md - Fix link to non-existent skills/SKILL_TEMPLATE.md -> skills/SKILLS_STANDARDS.md - Fix link to non-existent .github/agents/agent.md -> AGENTS.md These broken links were causing lint-and-links CI check failures.

github-actions · 2026-08-20T11:15:48Z

Milestone Allocation

github-actions · 2026-08-20T11:16:05Z

🔗 Project Linking Validation

Projects Checked: 67
Projects with Links: 66

✅ All projects have Related Issues sections

Detailed issue link validation is deferred to Phase 4.

Validation Date: 2026-08-20T11:16:05.485Z
Validator: GitHub Actions

github-actions · 2026-08-20T11:16:17Z

🎨 Mermaid Diagram Validation

❌ One or more Mermaid diagram checks failed.

Check	Result
✅ Syntax	Passed
❌ Accessibility	Failed
✅ Colour Contrast	Passed

Co-authored-by: Claude <noreply@anthropic.com>

github-code-qualityBot found potential problems Aug 18, 2026
View reviewed changes

ashleyshaw force-pushed the feat/openspec-labels-phase3 branch from f6684f3 to 5edd851Compare August 19, 2026 09:45

ashleyshaw added the meta:no-changelog No changelog needed label Aug 19, 2026

ashleyshaw force-pushed the feat/openspec-labels-phase3 branch from 5edd851 to 316c646Compare August 19, 2026 09:52

github-actionsBot removed the type:chore Chore / small hygiene change label Aug 19, 2026

ashleyshaw self-assigned this Aug 19, 2026

ashleyshaw enabled auto-merge (squash) August 19, 2026 10:46

ashleyshaw disabled auto-merge August 19, 2026 10:46

ashleyshaw enabled auto-merge (squash) August 19, 2026 10:46

ashleyshaw requested a lite review from Copilot August 19, 2026 10:48

Copilotstarted reviewing on behalf of ashleyshaw August 19, 2026 10:50 View session

CopilotAI reviewed Aug 19, 2026
View reviewed changes

ashleyshaw force-pushed the feat/openspec-labels-phase3 branch from e6db756 to 1be4d33Compare August 19, 2026 21:51

ashleyshaw pushed a commit that referenced this pull request Aug 20, 2026
docs: Add changelog entries for PRs#2087,#2099,#2118,#2117
4429461

mergifyBot added the dequeued label Aug 20, 2026

This was referenced Aug 20, 2026
Investigate and fix lint-and-links failures on open PRs #2165
Closed
Investigate and fix test failures on open PRs #2166
Closed

mergifyBot removed the dequeued label Aug 20, 2026

ashleyshaw mentioned this pull request Aug 20, 2026
fix: resolve CodeRabbit feedback and lint-and-links check failures across 4 PRs #2170
Merged
7 tasks

Test Userand others added 7 commits August 20, 2026 11:13

docs: Add changelog entries for PRs#2087,#2099,#2118,#2117
9ff80c4

ashleyshaw force-pushed the feat/openspec-labels-phase3 branch from 03616f6 to 937af0eCompare August 20, 2026 11:14

ashleyshaw merged commit 7046740 into developAug 20, 2026
24 of 34 checks passed

ashleyshaw deleted the feat/openspec-labels-phase3 branch August 20, 2026 11:14

This was referenced Aug 20, 2026
fix: correct corrupted path in mermaid accessibility validation #2173
Merged
OpenSpec Labels Automation — Phase 2–3 Epic #2048
Closed

ashleyshaw pushed a commit that referenced this pull request Aug 22, 2026
docs: Add changelog entries for PRs#2087,#2099,#2118,#2117
8dceb34

ashleyshaw added a commit that referenced this pull request Aug 22, 2026
docs: Add changelog entries for PRs#2087,#2099,#2118,#2117(#2294)
b1e9f52
Co-authored-by: Claude <noreply@anthropic.com>

		@@ -0,0 +1,332 @@
		# Phase 3 Handoff: Workflow Orchestration & Automated Phase Progression

Uh oh!

Conversation

ashleyshaw commented Aug 18, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Linked issues

Changelog

Summary

Test Results

Deliverables

Core Modules (Previously Committed)

New in This PR

Architecture

Design Principles

Documentation

Checklist (Global DoD / PR)

Uh oh!

coderabbitaiBot commented Aug 18, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review limit reached

Uh oh!

github-actionsBot commented Aug 18, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actionsBot commented Aug 19, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Reviewer Summary for PR #2087

Recommendations

Uh oh!

github-actionsBot commented Aug 19, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⏱️ Aging and SLA annotation

Uh oh!

github-actionsBot commented Aug 19, 2026

🔗 Project Linking Validation

❌ Missing Related Issues Section

Uh oh!

CopilotAI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

github-actionsBot commented Aug 19, 2026

🔗 Project Linking Validation

✅ All projects have Related Issues sections

Uh oh!

github-actionsBot commented Aug 20, 2026

🔗 Project Linking Validation

✅ All projects have Related Issues sections

Uh oh!

mergifyBot commented Aug 20, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge Queue Status

Reason

Hint

Uh oh!

Uh oh!

github-actionsBot commented Aug 20, 2026

Milestone Allocation

Uh oh!

github-actionsBot commented Aug 20, 2026

🔗 Project Linking Validation

✅ All projects have Related Issues sections

Uh oh!

github-actionsBot commented Aug 20, 2026

🎨 Mermaid Diagram Validation

Uh oh!

Reviewers

Assignees

Labels

Projects

ashleyshaw commented Aug 18, 2026•
edited
Loading

coderabbitaiBot commented Aug 18, 2026•
edited
Loading

github-actionsBot commented Aug 18, 2026•
edited
Loading

github-actionsBot commented Aug 19, 2026•
edited
Loading

github-actionsBot commented Aug 19, 2026•
edited
Loading

mergifyBot commented Aug 20, 2026•
edited
Loading