Phase 1: Stop New Label Prefix Violations (Governance Documentation) by ashleyshaw · Pull Request #2474 · lightspeedwp/.github

ashleyshaw · 2026-08-29T14:40:39Z

Linked issues

Relates to #2283 (Epic: Phase 1 - Stop New Label Prefix Violations)

Changelog

Added

New "Label Creation Rules (CRITICAL)" section in CLAUDE.md with valid/invalid examples
New "Label Creation Governance (CRITICAL)" section in AGENTS.md with programmatic issue creation guidance
Explicit validation checklist for canonical label usage
References to label validation script and canonical label sources

Changed

CLAUDE.md: Added governance documentation for label creation
AGENTS.md: Added implementation guidance for AI agents creating issues

Fixed

(No bug fixes in this PR)

Removed

(No removals in this PR)

Milestone

Phase 1: Label Prefix Enforcement - Governance & Documentation

Risk Assessment

Risk Level: Low

Potential Impact:

Documentation-only changes; no code logic modifications
Establishes baseline governance rules for future compliance
No breaking changes to existing workflows or automation

Mitigation Steps:

Changes are purely documentation; no runtime impact
Reviewed against existing labeling system implementation
Aligns with existing .github/scripts/validation/validate-labels-before-creation.cjs script

How to Test

Prerequisites

Repository cloned and on develop branch

Test Steps

Review CLAUDE.md changes:
- Verify new "Label Creation Rules (CRITICAL)" section is present after "Key Conventions"
- Confirm valid/invalid label examples are clearly formatted
- Check that references point to correct files
Review AGENTS.md changes:
- Verify new "Label Creation Governance (CRITICAL)" section is present after "Contribution Guidelines & Indexes"
- Confirm bash examples show correct vs incorrect label formats
- Check validation checklist is clear
Verify markdown validation:
```bash
npm run lint:md CLAUDE.md AGENTS.md
```
Expected: 0 errors

Expected Results

Both files validate without errors
Documentation clearly communicates canonical label requirement
Examples are accurate and helpful for developers

Edge Cases to Verify

Markdown linting passes
No broken links to referenced files
Examples accurately reflect actual label taxonomy

Checklist (Global DoD / PR)

References

Generated by Claude Code

Summary by CodeRabbit

New Features
- Added an automated tool to audit issue labels, identify non-standard labels, and suggest or apply canonical replacements.
- Supports dry-run previews, targeted issue ranges, live updates, and summary reports.
Documentation
- Added guidance for label governance, including required label prefixes, validation steps, usage examples, and manual-review recommendations.
- Expanded references and contributor guidance for maintaining consistent labels.

…forcement) This commit adds explicit governance rules for label creation to prevent new non-canonical label violations. Labels MUST use required family prefixes (type:, status:, priority:, area:, meta:). Changes: - CLAUDE.md: New 'Label Creation Rules (CRITICAL)' section with valid/invalid examples - AGENTS.md: New 'Label Creation Governance (CRITICAL)' section for programmatic issue creation Reference: .github/projects/active/label-prefix-enforcement-2026-08-05/ Resolves: Issue #2283 Phase 1 (Stop New Label Prefix Violations)

coderabbitai · 2026-08-29T14:40:49Z

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro Plus

Run ID: a8aaccac-c52f-49a1-be80-769a45b168cc

📥 Commits

Reviewing files that changed from the base of the PR and between 7cbe1f4 and b91a560.

📒 Files selected for processing (4)

AGENTS.md
CLAUDE.md
scripts/agents/includes/BARE_LABEL_FIXER_README.md
scripts/agents/includes/bare-label-fixer.js

📝 Walkthrough

Walkthrough

The changes document canonical label governance and add a Node.js agent that audits GitHub issues, plans bare-label replacements or removals, optionally applies updates, and saves a JSON report.

Changes

Label governance and remediation

Layer / File(s)	Summary
Canonical label governance `AGENTS.md`, `CLAUDE.md`	Documents prefixed-label requirements, validation steps, canonical sources, and the label-prefix audit reference.
Agent configuration and issue discovery `scripts/agents/includes/bare-label-fixer.js`, `scripts/agents/includes/BARE_LABEL_FIXER_README.md`	Defines label mappings, parses CLI and environment options, loads canonical labels, discovers matching issues, and documents usage and output behavior.
Label updates and reporting `scripts/agents/includes/bare-label-fixer.js`	Calculates changes, applies removals and additions outside dry-run mode, reports results, saves timestamped JSON output, and handles unrecoverable failures.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant bareLabelFixer
  participant GitHubIssuesAPI
  participant JSONReport
  bareLabelFixer->>GitHubIssuesAPI: Discover issues with configured bare labels
  GitHubIssuesAPI-->>bareLabelFixer: Return issues and current labels
  bareLabelFixer->>GitHubIssuesAPI: Remove bare labels and add mapped labels
  GitHubIssuesAPI-->>bareLabelFixer: Return update results
  bareLabelFixer->>JSONReport: Save timestamped remediation report

Suggested reviewers: lightspeedwp, claude

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

Create stacked PR
Commit on current branch

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch docs/label-prefix-governance-k9e0xd

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-29T14:41:36Z

🔍 Reviewer Summary for PR #2474

CI Status: ✅ success
Files changed: 2

Recommendations

Ready to proceed pending human review

mergify · 2026-08-29T14:41:48Z

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

Queue this pull request

github-actions · 2026-08-29T14:41:56Z

⚠️ PR Governance Issues

❌ Milestone Issue

No milestone assigned. Please select a milestone from the right sidebar.

View PR Governance Check

Implements automated auditing and fixing of bare labels (e.g., 'bug', 'feature', 'documentation') to their proper prefixed equivalents (e.g., 'type:bug', 'type:feature', 'type:documentation'). Features: - Comprehensive bare label detection across repository - Configurable issue number range filtering - Dry-run mode for safe verification - Detailed reporting of changes - High-confidence auto-mapping with manual review fallback Phase 2: Stop New Label Prefix Violations - Fix Existing Issues Relates to #2283 Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JsQ2HQ1m9uzKD8bEQhN9xp

github-actions · 2026-08-29T14:45:35Z

📄 README Validation

❌ One or more README checks failed.

Check	Result
❌ Frontmatter	Failed
✅ Structure	Passed

github-actions · 2026-08-29T14:47:23Z

🔍 Reviewer Summary for PR #2474

CI Status: ✅ success
Files changed: 4

Recommendations

Ready to proceed pending human review

…DE.md label governance conflict

github-actions · 2026-08-30T02:51:35Z

❌ Branch Name Validation Failed

The branch name docs/label-prefix-governance-k9e0xd does not follow the LightSpeed branching strategy.

Required Format

{type}/{scope}-{short-title}

type: one of the allowed prefixes (lowercase)
scope: lowercase, hyphens only (no underscores or uppercase)
title: lowercase, hyphens only (no underscores or uppercase)

Allowed Branch Types

feat, fix, hotfix, release, refactor, chore, docs, test, perf, ci, build, deps, security, revert, research, design, a11y, ux, i18n, ops, proto, ds, api, schema, telemetry, content, seo, config, migrate, qa, uat, audit, codex

Valid Examples

✓ feat/branch-naming-enforcement
✓ fix/validation-script-bug
✓ chore/update-dependencies
✓ docs/branching-strategy-guide
✓ hotfix/critical-security-patch

Invalid Examples

✗ claude/my-branch (type "claude" not allowed)
✗ Feature/MyBranch (uppercase not allowed)
✗ fix-bug (missing type prefix)
✗ feat/my_feature (underscores not allowed)
✗ feat/MyFeature (uppercase not allowed)

Solution

Rename your branch to follow the pattern and update the PR.

For more information, see docs/BRANCHING_STRATEGY.md.

github-actions · 2026-08-30T02:51:44Z

🔍 Reviewer Summary for PR #2474

CI Status: ❌ pending
Files changed: 4

Recommendations

CI checks not green

github-actions · 2026-08-30T02:52:17Z

Milestone Allocation

…ements Implements all 5 priority improvements from CI/CD validation audit: 1. Add blocking PR label validation to pr-validation.yml - Load canonical labels from labels.yml - Detect bare (non-prefixed) labels on PR - Fail check if bare labels found - Provide actionable error messages 2. Create new issue label validation workflow (validate-issue-labels.yml) - Triggers on issue opened/edited/labeled/unlabeled - Detects bare labels on issues - Posts warning comment with canonical label guidance - Skips bot-authored issues (dependabot, renovate) 3. Enhance labeling-governance.yml with bare label detection - Add new detect-bare-labels job - Runs on PR and issue events - Logs warnings for bare labels found - Complements automatic labeling with detection 4. Setup scheduled bare label remediation (weekly) - Add schedule trigger to remediate-bare-labels.yml - Runs every Monday at 08:00 UTC - Enables automatic weekly scanning and reporting - Maintains manual dispatch option 5. Add PR template validation for required structure and labels - Create validate-pr-template-structure.cjs script - Validates required sections (Linked issues, Changelog, etc.) - Checks for canonical label references in template - Add to pr-validation.yml workflow Validation stack now includes: - Automated label assignment (labeler.yml - all canonical) - Template validation (check-template-labels.js) - PR label validation (pr-validation.yml - blocks bare labels) - Issue label validation (validate-issue-labels.yml - warns on bare) - Bare label detection (labeling-governance.yml - logs findings) - Scheduled remediation (remediate-bare-labels.yml - weekly) Relates to #2474 (Phase 1: Governance) Relates to #2524 (Phase 2: Remediation) Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RZBSsykLxBKFqa5Hxq8xKh

ashleyshaw added migrate:priority:critical Production/launch-blocking migrate:status:needs-review Awaiting code review migrate:type:documentation Documentation area:labels Label governance and routing labels Aug 29, 2026 — with Claude

ashleyshaw enabled auto-merge August 30, 2026 02:04

Merge develop into docs/label-prefix-governance-k9e0xd - resolve CLAU…

b91a560

…DE.md label governance conflict

ashleyshaw merged commit 7e8a291 into develop Aug 30, 2026
20 of 39 checks passed

ashleyshaw deleted the docs/label-prefix-governance-k9e0xd branch August 30, 2026 02:51

This was referenced Aug 30, 2026

fix: Phase 2: Bare Label Remediation — Fix Existing Label Prefix Violations #2524

Merged

Phase 3: Label Prefix Governance — Bare Label Scan & CI/CD Audit #2554

Merged

Navigation Menu

Uh oh!

Phase 1: Stop New Label Prefix Violations (Governance Documentation) - #2474

Phase 1: Stop New Label Prefix Violations (Governance Documentation)#2474
ashleyshaw merged 3 commits into
developfrom
docs/label-prefix-governance-k9e0xd

ashleyshaw commented Aug 29, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Aug 29, 2026 •

edited

Loading

Review failed

Walkthrough

Changes

Sequence Diagram(s)

Uh oh!

github-actions Bot commented Aug 29, 2026

Uh oh!

mergify Bot commented Aug 29, 2026

Uh oh!

github-actions Bot commented Aug 29, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Aug 29, 2026

Uh oh!

github-actions Bot commented Aug 29, 2026

Uh oh!

Uh oh!

github-actions Bot commented Aug 30, 2026

Uh oh!

github-actions Bot commented Aug 30, 2026

Uh oh!

github-actions Bot commented Aug 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

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

Uh oh!

Linked issues

Changelog

Added

Changed

Fixed

Removed

Milestone

Risk Assessment

How to Test

Prerequisites

Test Steps

Expected Results

Edge Cases to Verify

Checklist (Global DoD / PR)

References

Summary by CodeRabbit

Uh oh!

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

Uh oh!

Review failed

Walkthrough

Changes

Sequence Diagram(s)

Uh oh!

github-actions Bot commented Aug 29, 2026

🔍 Reviewer Summary for PR #2474

Recommendations

Uh oh!

mergify Bot commented Aug 29, 2026

Uh oh!

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

Uh oh!

⚠️ PR Governance Issues

❌ Milestone Issue

Uh oh!

github-actions Bot commented Aug 29, 2026

📄 README Validation

Uh oh!

github-actions Bot commented Aug 29, 2026

🔍 Reviewer Summary for PR #2474

Recommendations

Uh oh!

Uh oh!

github-actions Bot commented Aug 30, 2026

❌ Branch Name Validation Failed

Required Format

Allowed Branch Types

Valid Examples

Invalid Examples

Solution

Uh oh!

github-actions Bot commented Aug 30, 2026

🔍 Reviewer Summary for PR #2474

Recommendations

Uh oh!

github-actions Bot commented Aug 30, 2026

Milestone Allocation

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ashleyshaw commented Aug 29, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Aug 29, 2026 •

edited

Loading

github-actions Bot commented Aug 29, 2026 •

edited

Loading