lightspeedwp · ashleyshaw · Aug 30, 2026 · Aug 30, 2026 · Aug 30, 2026 · Aug 30, 2026
@@ -63,6 +63,7 @@ routes:
   qa/: pr_chore.md
   uat/: pr_chore.md
   audit/: pr_feature.md
+  codex/: pr_docs.md
 
   # FORBIDDEN PREFIXES: Fallback routing required
   #

@@ -28,6 +28,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **Branch Name Validation & Governance — Phase 3: Complete Implementation — Issues #2544, #2545, #2546** — Comprehensive third phase of AI governance audit establishing branch name validation enforcement, PR template routing, and governance documentation. Phase 3 deliverables include: (1) **Branch Name Validator Script** (`scripts/validation/validate-branch-name.cjs`, 373 LOC) — Enforces strict branch naming pattern `{type}/{scope}-{title}` with: 34 allowed type prefixes (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), semantic versioning support for release branches (release/v1.2.3 or release/1.2.3), strict kebab-case enforcement, 500+ character limit per component, and comprehensive error messages with examples. Exports validator function and all patterns for programmatic use; (2) **Jest Test Suite** (`scripts/validation/__tests__/validate-branch-names.test.js`, 39 comprehensive tests, 100% coverage) — Validates: all 34 allowed types (34 tests), forbidden prefix rejection (claude/, copilot/, openai/), format compliance (hyphen positioning, kebab-case), edge cases (empty strings, special characters, release semantic versioning), and error message formatting. All 39 tests passing locally with complete code path coverage; (3) **GitHub Actions Validation Workflow** (`.github/workflows/branch-name-validation.yml`) — CI/CD integration: Runs on PR open/reopen/synchronize, fetches PR's version of validator for forward-compatibility, creates check runs with pass/fail status, posts helpful comments on validation failure with examples, allowed types list, and branching strategy documentation link; (4) **PR Template Routing Configuration** (`.github/pull_request_template/config.yml`) — Maps branch type prefixes to specific PR templates with fallback routing to default `pr_feature.md` for unmatched types, supporting all 34 allowed types; (5) **Governance Documentation Updates** (`docs/BRANCHING_STRATEGY.md`, `CLAUDE.md`, `.github/instructions/branch-naming.instructions.md`) — Comprehensive guides covering: pattern explanation, all 34 allowed types with examples, forbidden prefix rationale (why claude/, copilot/, openai/ break automation), validation procedures, troubleshooting, and references to downstream workflows; (6) **Schema Definition** (`.schemas/branch-name.schema.json`, 150 LOC) — JSON Schema for branch name validation with pattern constraints, semantic versioning definitions, and type enumerations; (7) **Bug Fix** — Fixed undefined `BRANCH_PATTERN` reference in debug logging by adding backward-compatibility alias: `const BRANCH_PATTERN = BRANCH_PATTERN_STANDARD;`. **Validation Coverage**: 100% of branch types validated (34/34), CI/CD integration on all PR changes, pre-commit hook support via `npm run validate:branch-name`, semantic versioning support for release branches. **Governance Impact**: Enforces Phase 3 governance rules preventing forbidden AI agent prefixes (claude/, copilot/, openai/) that break PR template assignment, labeling workflows, and release automation; unblocks Phase 4 (system-wide enforcement) and Phase 5 (training & adoption). **Test Quality**: 39 tests covering happy path (all types), error cases (forbidden prefixes, format violations), edge cases (semantic versioning, special characters), with 100% code coverage. **Production Ready**: All tests passing, CI/CD integrated, documentation complete, backward-compatible alias prevents regression. Related: Issues #2544 (Phase 3 kickoff), #2545 (Validator implementation), #2546 (Documentation & governance), Branching Strategy (`docs/BRANCHING_STRATEGY.md`), Governance Rules (`CLAUDE.md` § Branch Naming). ([#2544](https://github.com/lightspeedwp/.github/issues/2544), [#2545](https://github.com/lightspeedwp/.github/issues/2545), [#2546](https://github.com/lightspeedwp/.github/issues/2546), [PR #2586](https://github.com/lightspeedwp/.github/pull/2586))
+
 - **PR Labeling Enforcement Initiative — Comprehensive 5-Phase Planning Hub** — Complete planning documentation and governance framework for systematic PR label validation enforcement. Initiative #2352 deliverables include: (1) **README.md** — Navigation hub with role-based guidance (Project Manager, Phase Lead, Engineer, Tech Writer, Developer) directing stakeholders to appropriate documents with quick-start guides and 7–12 business day timeline; (2) **WORK_PLAN.md** — Comprehensive 11,000+ word roadmap documenting all 5 sequential phases with objectives, deliverables, success criteria, dependencies, risk mitigation, and go/no-go gates; (3) **QUICK_REFERENCE.md** — One-page status dashboard with phase overview, issue lookup tables, timeline summary, dependency maps, phase completion checklists, and escalation procedures; (4) **EXECUTION_CHECKLIST.md** — Step-by-step execution tasks with master checklist, hour-by-hour Phase 1 guide, parallel execution maps for Phases 2–3, daily standup template, and progress tracking; (5) **IMPLEMENTATION_ROADMAP.md** — Detailed phase breakdown covering Phases 1–5 with timeline, risk mitigation, success metrics (100% compliance, <2 preventable violations/week by Day 30), and go/no-go gates; (6) **OPENSPEC_STATUS_FRAMEWORK.md** — Governance and automation framework mapping all 5 phases to OpenSpec lifecycle states with specification/implementation status labels (pending/in-progress/complete), component tracking, automated label transitions via GitHub Actions, and escalation procedures. **Phase Dependencies:** Phase 1 (Stop New Violations, 2–3h) blocks Phases 2–5; Phase 2 (Fix Existing, 24–48h) blocks Phases 3–5; Phase 3 (Enforce System-Wide, 3–5d) blocks Phases 4–5; Phase 4 (Documentation, 2–3d) blocks Phase 5; Phase 5 (Training, 1–2d) is final phase. **Parallel Work:** Phase 2 includes 3 concurrent audits (#909, #656, #664); Phase 3 includes 2 concurrent implementations (#1719, #1944) with integration testing gate (#1323). **Labels:** Added 6 new OpenSpec phase labels to canonical schema (specification/implementation pending/in-progress/complete) with colors: pending (C5DEF5 blue), in-progress (F2D06D yellow), complete (1A7F37 green). All documentation role-tested and linked. Project location: `.github/projects/active/pr-labeling-enforcement-issue-2352-plan/`. Related: Issues #2352 (meta), #2283 (Phase 1), #1604 (Phase 2), #1605 (Phase 3), #1606 (Phase 4), #1607 (Phase 5). ([#2352](https://github.com/lightspeedwp/.github/issues/2352), [PR #2521](https://github.com/lightspeedwp/.github/pull/2521), [PR #2549](https://github.com/lightspeedwp/.github/pull/2549))
 
 ### Changed

@@ -80,6 +80,8 @@ For all repos (client, product, infra, etc.), use:
 - `ux/` — user experience
 - `i18n/` — internationalization
 - `ops/` — operations
+- `audit/` — governance audits and compliance reviews
+- `codex/` — codex, knowledge base, or reference documentation
 
 ### 3.2 Product-specific Prefixes (optional)
 
@@ -124,9 +126,26 @@ hotfix/ga4-purchase-duplicate
 Use a single regex in a workflow to enforce naming discipline:
 
 ```regex
-^(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)/[a-z0-9._-]+$
+^(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)/[a-z0-9._-]+$
 ```
 
+### 4.1 Forbidden Prefixes (AI Agent Governance)
+
+The following prefixes are **strictly forbidden** for all branches to enforce proper governance of AI-assisted development:
+
+- `claude/` — Reserved for governance audits only; blocks automated routing
+- `copilot/` — GitHub Copilot-specific branches not permitted
+- `openai/` — OpenAI-related work must use appropriate type prefixes
+
+**Rationale:** Forbidden prefixes act as circuit-breakers for AI agents (Claude Code, GitHub Copilot). When detected, they trigger fallback routing to default PR templates and prevent type-based automation. This ensures:
+
+- AI agents cannot bypass branch naming governance
+- Explicit type prefixes drive proper automation routing
+- Governance audits are tracked and auditable
+- No silent acceptance of non-conforming branch names
+
+**Enforcement:** CI will reject any branch matching `claude/`, `copilot/`, or `openai/` prefixes, even if followed by valid scope-title patterns.
+
 Example workflow (`.github/workflows/validate-branch-name.yml`):
 
 ```yaml
@@ -143,7 +162,7 @@ jobs:
           BRANCH="${{ github.head_ref }}"
           # Allow dependabot/renovate
           if [[ "$BRANCH" =~ ^(dependabot|renovate)/ ]]; then exit 0; fi
-          if [[ ! "$BRANCH" =~ ^(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)/[a-z0-9._-]+$ ]]; then
+          if [[ ! "$BRANCH" =~ ^(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)/[a-z0-9._-]+$ ]]; then
             echo "❌ Branch '$BRANCH' must match the required pattern."
             exit 1
           fi
@@ -154,6 +173,31 @@ jobs:
 - For monorepos, ensure branch naming applies to each package/subproject, or use a consistent prefix (e.g. `feat/frontend-...`, `fix/api-...`).
 - For forked repos, always clean up branches after merging upstream PRs, and avoid duplicating branch names across forks to prevent confusion.
 
+### 4.3 PR Template Routing & Fallback Behavior
+
+PR template selection is automatically routed based on branch type prefix:
+
+| Branch Type | PR Template |
+|---|---|
+| `feat/` | `pr_feature.md` |
+| `fix/` | `pr_bug.md` |
+| `hotfix/` | `pr_hotfix.md` |
+| `release/` | `pr_release.md` |
+| `refactor/` | `pr_refactor.md` |
+| `chore/` | `pr_chore.md` |
+| `docs/` | `pr_docs.md` |
+| `ci/` | `pr_ci.md` |
+| `deps/` | `pr_dep_update.md` |
+| Other types | `pr_chore.md` (default) |
+| Forbidden prefixes | `pr_chore.md` (fallback) |
+
+**Fallback Logic:** If a branch uses a forbidden prefix (e.g., `claude/governance-audit-implementation`), the PR template resolver detects the violation and routes to the default `pr_chore.md` template. This ensures:
+
+- No PR is left without template guidance
+- Forbidden prefixes trigger visible fallback routing (auditable)
+- Authors are prompted to re-open PR with proper branch naming
+- Type detection hierarchy: branch type → linked issue type → default
+
 ---
 
 ## 5. Prefixes Drive Automation
@@ -197,6 +241,8 @@ Ensure `.github/labeler.yml` seeds new PRs with `status:needs-review` when appro
         "^migrate/.*",
         "^qa/.*",
         "^uat/.*",
+        "^audit/.*",
+        "^codex/.*",
       ]
 ```
 

@@ -1,9 +1,9 @@
 ---
 file_type: "documentation"
-name: "Frontmatter Validation"
-description: "Comprehensive frontmatter validation scripts for LightSpeedWP .github repository ensuring schema compliance and consistency"
-version: "1.0.0"
-last_updated: "2025-12-04"
+name: "Validation Scripts & Tests"
+description: "Comprehensive validation scripts and tests for frontmatter, JSON, YAML, and branch naming in LightSpeedWP .github repository ensuring schema compliance and governance"
+version: "1.1.0"
+last_updated: "2026-08-30"
 owners:
   - "LightSpeedWP Team"
 tags:
@@ -12,10 +12,12 @@ tags:
   - "schema"
   - "testing"
   - "automation"
+  - "branch-governance"
 apply_to:
   - "repository maintenance"
   - "documentation standards"
   - "quality assurance"
+  - "branch naming governance"
 ---
 
 
@@ -34,9 +36,15 @@ The validation system provides automated checking of:
 All schema files are stored in `../../.schemas/`.
 
 ```mermaid
+---
+config:
+  theme: default
+  look: handDrawn
+  layout: elk
+  accTitle: Validation System Flow
+  accDescr: Flowchart showing file discovery through log output with configuration, schema, and pattern inputs
+---
 graph TD
-  accTitle: Frontmatter validation pipeline
-  accDescr: Top-down graph showing the frontmatter validation pipeline from discovery through report generation
     A[File Discovery] --> B[Frontmatter Extraction]
     B --> C[Schema Validation]
     C --> D[LightSpeed Rules Check]
@@ -63,6 +71,7 @@ graph TD
 ## Test Files
 
 - **`__tests__/validate-frontmatter.test.js`** — Test suite for frontmatter validation
+- **`__tests__/validate-branch-names.test.js`** — Jest test suite for branch name validation (34 allowed types, forbidden prefix rejection, format validation)
 - **`validate-coderabbit-yml.test.js`** — Jest test suite for the CodeRabbit YAML validator
 
 ## Features