refactor(validation): P1.1 - Unify branch name validators

[ashleyshaw]

Linked issues

Relates to #1967 (CI Validation Issues: Branch Naming & Gitleaks Discrepancies)
Relates to #1755 (Branch Naming Enforcement Workflow)

Summary

Unified the branch name validation scripts to enforce identical strict pattern across all validation layers. This eliminates the divergence between .cjs (strict) and .js (permissive) validators that was causing inconsistent branch naming enforcement.

Problem Addressed:

• .cjs validator enforced strict {type}/{scope}-{title} pattern
• .js validator allowed permissive {type}/{anything} pattern with dots
• Workflow used .js (permissive), allowing invalid branches to pass validation
• Test matrix from Phase 2 showed divergence: release/v1.0.0 failed .cjs but passed .js

Safety Nets

• Existing tests covering behaviour: 38 tests in scripts/validation/__tests__/validate-branch-name.test.js
• New/refined tests added: Updated tests for strict pattern (no dots allowed)
• Static analysis/lint rules touched: Validation regex pattern unified

Approach

• Structural changes (APIs, patterns):

  • Updated .js validator regex from ^(${ALLOWED_PREFIXES.join("|")})/[a-z0-9.-]+$ to strict ^(${ALLOWED_PREFIXES.join("|")})/([a-z0-9]+(?:-[a-z0-9]+)*)-([a-z0-9]+(?:-[a-z0-9]+)*)$
  • Updated workflow to use .cjs instead of .js (strict validator is canonical)
  • Updated error messages to reference correct pattern format

• Dead code removed: No (both validators remain; .js may be used elsewhere)

Testing

Unit Tests: ✅ All 38 tests pass

Test Suites: 1 passed, 1 total
Tests: 38 passed, 38 total

Validation Test Matrix:

Branch	.cjs	.js	Result
release/v1.0.0	✗	✗	Now unified (dots rejected)
chore/release	✗	✗	Now unified (missing separator)
feat/-dash-start	✗	✗	Now unified (invalid format)
feat/my-feature-with-long-name	✓	✓	Consistent ✓
claude/my-feature	✗	✗	Consistent ✓
release/v1-0-0	✓	✓	Now accepted (hyphens)

Verification

• Unit tests pass locally (38/38)
• Both validators tested with Phase 2 test matrix
• Workflow updated to use strict validator
• Error messages clarified

Risk & Rollback

• Risk level: Low

  • No user-facing changes; internal validation improvement
  • Stricter pattern may reject previously-created branches with dots in version numbers
  • Validators now reject release/v1.0.0; must use release/v1-0-0

• Rollback plan: Revert commit (single commit; clean history)

Changelog

Changed

• Unified branch name validation pattern across .cjs and .js validators to enforce strict {type}/{scope}-{title} format
• Updated GitHub Actions workflow to use .cjs (strict) validator instead of .js (permissive)
• Updated validator tests to reflect strict kebab-case requirement (no dots, no underscores)
• Clarified error messages to reference correct pattern: {type}/{scope}-{short-title}

Fixed

• Resolved validator divergence: both now reject permissive patterns like release/v1.0.0, chore/release, feat/-dash-start

---

Checklist (Global DoD / PR)

• All AC met and demonstrated
• Tests added/updated (38 tests all passing)
• No accessibility/security implications (validation only)
• Docs updated: test changes clarify strict pattern requirement
• Code review ready (self-review complete)
• CI green; related to branch-naming-validation audit project

---

Phase: P1.1 of 6-phase remediation plan

[github-actions]

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

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro Plus

Run ID: b3cb3b73-cdfd-483a-802d-7e12930832ec

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[github-actions]

❌ Branch Name Validation Failed

The branch name claude/branch-naming-audit-7w84rv 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.