refactor: PR label automation as a proper state machine

[cmeans-claude-dev]

Summary

• Rewrites the PR label automation as a clean state machine with defined states, transitions, and cleanup rules
• Splits workflow_run trigger into separate file to eliminate failure emails on merges to main
• Adds CI Failed label for CI failures (covers both hard failures and Codecov)
• Removes QA Invalidated label (push comment is sufficient)
• Dev Active now coexists with Awaiting CI instead of blocking it

State Machine

stateDiagram-v2
    [*] --> Awaiting_CI : PR opened / push
    Dev_Active --> Awaiting_CI : push (coexist)
    Awaiting_CI --> Ready_for_QA : CI pass (no Dev Active)
    Awaiting_CI --> CI_Failed : CI fail (no Dev Active)
    CI_Failed --> Awaiting_CI : push (fix)
    Ready_for_QA --> QA_Active : QA starts
    QA_Active --> Ready_for_QA_Signoff : signoff
    QA_Active --> QA_Failed : fail
    Ready_for_QA_Signoff --> QA_Failed : fail at signoff
    Ready_for_QA_Signoff --> QA_Approved : approved
    QA_Approved --> [*] : merge
    QA_Failed --> Dev_Active : dev picks up

Loading

Design spec

docs/superpowers/specs/2026-03-30-pr-label-state-machine-design.md

Changes

File	What
pr-labels.yml	Rewritten: on-push keeps Dev Active, removes all others, adds Awaiting CI. on-unlabel promotes if CI passed. on-label has full cleanup matrix.
pr-labels-ci.yml	Rewritten: on-ci-pass promotes (skips if Dev Active). on-ci-fail adds CI Failed (skips if Dev Active). Safe 404 handling.
Labels	Created CI Failed. Deleted QA Invalidated.

QA

Prerequisites

• Review both workflow files against the spec

Manual tests

1. • New PR without Dev Active — create a test PR, verify it gets Awaiting CI on open, Ready for QA after CI passes (note: on-ci-pass runs from main, so this tests the OLD code until merge)
2. • Push with Dev Active — add Dev Active to a PR, push a commit, verify both Dev Active and Awaiting CI are present
3. • Remove Dev Active after CI passed — remove Dev Active, verify Ready for QA appears within 15s
4. • CI failure without Dev Active — push a commit that breaks lint, verify CI Failed appears (post-merge test only — on-ci-fail runs from main)
5. • Label cleanup — add Ready for QA manually, verify Awaiting CI is removed
6. • QA Failed at signoff — add QA Failed while Ready for QA Signoff is present, verify Ready for QA Signoff is removed
7. • No failure emails on merge — merge a PR, verify no "PR Label Automation (CI)" failure email

Note: Tests 1, 4, and 7 depend on the workflow_run trigger which runs from main. These can only be fully verified after merge.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[cmeans]

QA Review — PR #108: PR label automation state machine

Reviewer: QA Agent
Date: 2026-03-30
Spec verified: docs/superpowers/specs/2026-03-30-pr-label-state-machine-design.md

Code Review: PASS

All transition rules, cleanup matrix entries, and edge cases from the design spec are faithfully implemented. The workflow_run split eliminates the merge-to-main failure email issue. Dev Active coexistence with Awaiting CI is correctly implemented across all jobs.

Findings

1. Substantive — Unrelated files in PR

3 files are not related to the label state machine and were committed to this branch before the label work started:

• .gitignore (+3 lines, .worktrees/)
• docs/superpowers/plans/2026-03-30-high-findings-fixes.md (+1064 lines — audit findings implementation plan)
• docs/superpowers/specs/2026-03-30-high-findings-fixes-design.md (+171 lines — audit findings design spec)

These belong with PRs #103–105 or in their own docs commit. Recommend rebasing them out of this PR.

2. Observation — QA CLAUDE.md needs update after merge

The QA project's CLAUDE.md still references QA Invalidated in the label table and state machine. After merge, update to remove QA Invalidated, add CI Failed, and reflect the new Dev Active coexistence behavior.

3. Observation — Post-merge-only tests

Tests 1, 4, and 7 from the QA section depend on workflow_run (runs from main). Acknowledged — these can only be verified after merge.

CI Status

• lint: ✅
• test (3.10, 3.11, 3.12): ✅
• typecheck: ✅
• codecov/patch: ✅

Verdict

Finding #1 (unrelated files) is substantive but not a blocker if the owner accepts the scope. The workflow code itself is correct and ready. Pending owner decision on the unrelated files.

[cmeans]

QA Audit — PR #108

CI: All green (lint, test 3.10/3.11/3.12, typecheck, codecov)
Code review: PASS — all transitions match spec
Manual tests: Cannot execute — tests 2/3 require Dev pushing commits, tests 1/4/7 are post-merge only, tests 5/6 require label manipulation that would disrupt the active QA state

Findings Summary

#	Severity	Finding	Status
1	Substantive	3 unrelated files in PR (.gitignore, audit findings plan+spec)	Awaiting owner decision
2	Observation	QA CLAUDE.md needs QA Invalidated → CI Failed update after merge	Follow-up
3	Observation	3/7 QA tests are post-merge only (acknowledged in PR body)	Noted

Blocking: Finding #1 — owner should decide whether to rebase out the unrelated files or accept the scope.

[cmeans]

QA Update — Finding #1 Withdrawn

Retracting finding #1 (unrelated files). The high-findings-fixes docs and .gitignore change are on main — they appear in the diff due to the branch divergence point, not because they're part of this PR. The 4 actual PR files are all related.

Revised findings:

#	Severity	Finding	Status
1	Substantive	Unrelated files	Withdrawn
2	Observation	QA CLAUDE.md needs QA Invalidated → CI Failed update after merge	Follow-up
3	Observation	3/7 QA tests are post-merge only (acknowledged in PR body)	Noted

Zero blocking findings. Code review passes, CI green, spec fully implemented.

Adding Ready for QA Signoff.

[cmeans]

QA Re-Review — Round 2

CI: All green (lint, test 3.10/3.11/3.12, typecheck, codecov)
Code review: PASS — all transitions match spec
Unrelated files: Removed by Dev (finding resolved)

Manual Test Results

Test	Result	Notes
1. New PR without Dev Active	⏳ Post-merge	workflow_run from main
2. Push with Dev Active	✅ PASS	Pushed commit, both Dev Active + Awaiting CI present, Ready for QA removed
3. Remove Dev Active after CI passed	✅ PASS	Promoted to Ready for QA within 15s
4. CI failure without Dev Active	⏳ Post-merge	workflow_run from main
5. Label cleanup	✅ PASS	Ready for QA removed both Awaiting CI and CI Failed
6. QA Failed at signoff	✅ PASS	QA Failed removed Ready for QA Signoff
7. No failure emails	⏳ Post-merge	Can only verify after merge

4/7 tests passed. 3/7 are post-merge only (documented).

Bonus: Test 2 also verified that Dev Active on-label cleanup removes QA Failed (the preceding test's residual label).

Remaining Findings

#	Severity	Finding	Status
1	Substantive	Unrelated files	Resolved by Dev
2	Observation	QA CLAUDE.md needs QA Invalidated → CI Failed update after merge	Follow-up
3	Observation	3/7 tests post-merge only	Documented

Zero blocking findings. Adding Ready for QA Signoff.

[cmeans]

LGTM