epic: milestone-allocation - Automate allocation #1762

Component: Team Rollout, Monitoring & Adoption

Parent Issue: #1755

Objective: Deploy branch naming enforcement system to production and monitor team adoption

Status: 🚀 PHASE 4 — IN PROGRESS (Starting 2026-08-22)
Related Deliverable: PR #2302 — Unified validators and agent branch guidance (Phases 1-3 complete)

Summary of Completed Foundation Work (Phases 1-3)

Before Phase 4 rollout can begin, the following foundational work is complete:

Phase 1 (Validators & Spec):

• ✅ Unified validators: .cjs and .js to strict {type}/{scope}-{short-title} pattern
• ✅ All 38 unit tests passing
• ✅ Pattern enforced across all validation points

Phase 2 (Agent Guidance & Safety):

• ✅ Branch naming guidance added to 19 spec-based agents
• ✅ Release agent pre-creation validation implemented
• ✅ Integrated into 7-layer safety gates (Gate 1)

Phase 3 (Discoverability):

• ✅ Quick reference guide: docs/QUICK_REFERENCE_BRANCH_NAMING.md
• ✅ CLAUDE.md: Before Every Push checklist (7 steps)
• ✅ AGENTS.md: Expanded Branch Governance (120+ lines, 31 prefixes)
• ✅ 19 portable agents: Added branch naming sections
• ✅ Portable instructions: instructions/branch-naming.instructions.md
• ✅ Branch naming guidance in 40+ files across codebase

Phase 4: Team Rollout & Monitoring

Phase 4.1: Workflow Deployment & Configuration

Tasks:

• Configure workflow as required status check in branch protection rules
• Set up GitHub Actions notifications for failures
• Create dashboard to monitor violation rate over time
• Verify workflow is running on all new PRs
• Test that merge is blocked on validation failure
• Document rollout completion in project README

Acceptance Criteria:

• ✅ Workflow is required for PR merge
• ✅ Notifications working
• ✅ Monitoring dashboard active
• ✅ Cannot merge without passing validation
• ✅ Team notified of status

Phase 4.2: Team Announcement & Training

Tasks:

• Draft announcement email with setup instructions
• Include npm run setup:hooks instructions
• Link to docs/QUICK_REFERENCE_BRANCH_NAMING.md
• Link to instructions/branch-naming.instructions.md
• Explain two-layer enforcement system (hooks + workflow)
• Provide FAQ and troubleshooting link
• Schedule team meeting or office hours Q&A
• Answer questions in real-time

Announcement content:

• What changed? New two-layer branch naming enforcement system
• Why? Prevent naming violations before they reach PRs
• How does it work? Local pre-commit hook + GitHub Actions workflow
• How to install? npm run setup:hooks
• What if it fails? Refer to troubleshooting section and quick reference
• Questions? Contact channel or office hours

Phase 4.3: Monitoring & Feedback (2026-08-22 onwards)

Metrics to track:

1. Hook adoption rate (target: >80% within 2 weeks)

   • Track number of developers who ran setup:hooks
   • Survey team on adoption status

2. PR validation metrics (target: drop violations from ~30% to <5%)

   • Number of PRs with validation failures
   • Failure rate over time
   • Types of violations (most common invalid prefixes)

3. User experience

   • Time to fix validation failure (measure in minutes)
   • Survey team on error message clarity (target: 4/5 rating)
   • Gather feedback on setup process

4. Performance

   • Monitor workflow execution time (should be <30s)
   • Check for any regressions in PR creation speed

Daily tasks:

• Monitor issue tracker for related problems
• Answer setup questions
• Collect feedback from team
• Document any bugs/edge cases
• Update troubleshooting guide as needed

Weekly review (first week: 2026-08-29; second week: 2026-09-05):

• Analyze adoption and violation metrics
• Update project dashboard
• Assess whether additional support needed
• Plan next phase (if applicable)

Related Resources

Documentation:

• PR refactor(validation): P1-P2 - Unified validators and agent branch guidance #2302: Phases 1-3 implementation (50 files, 893 additions)
• docs/QUICK_REFERENCE_BRANCH_NAMING.md — Quick setup guide
• docs/SETUP_BRANCH_VALIDATION.md — Comprehensive setup instructions
• instructions/branch-naming.instructions.md — Portable reusable guide
• docs/BRANCHING_STRATEGY.md — Full branching discipline
• CLAUDE.md — Before Every Push validation checklist
• AGENTS.md — Branch Governance & Validation sections

Key Issues:

• [Initiative] Branch Naming Enforcement Workflow #1755 — Branch Naming Enforcement Epic (parent)
• [Phase 2.1] Create branch name validation script #1756-feat: Phase 3 — GitHub Workflows for Label Management #1761 — Phase 1-3 implementation tasks (completed)

Acceptance Criteria:

Phase 4 acceptance criteria:

• ✅ Workflow deployed and required for merge
• ✅ Team announcement sent with setup instructions
• ✅ >80% adoption within 2 weeks
• ✅ Violation rate drops to <5% from current ~30%
• ✅ No unexpected issues or regressions
• ✅ Team feedback collected and documented
• ✅ Support processes in place

Effort: 4 hours/week ongoing

Related: #1755, PR #2302

Definition of Ready (DoR)

• Clear problem statement and expected outcome
• Acceptance criteria defined
• Related issues/dependencies identified
• Required resources/approvals listed
• All Phase 1-3 foundation work complete

Definition of Done (DoD)

• All acceptance criteria met
• Workflow deployed and required
• Team announcement sent
• Team adoption >80%
• Violation rate <5%
• Monitoring dashboard active
• Support processes documented
• Project marked Phase 4 complete