Add branch-name validation hook to enforce Branch Naming standard
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 0
- Forks
- 1
- Avg merge
- 1d 3h
- Merged PRs (30d)
- 7
Description
Goal
Machine-enforce the branch naming convention introduced in #5 (branches/<issue-number>-<kebab-case-slug> or branches/<kebab-case-slug>) so compliance does not depend on the developer or Claude remembering the rule.
Current Behavior
After #5 merges, the convention lives in `standards/CLAUDE.md` as advisory text. Existing hooks (`hooks/pre-push`, `hooks/pre-commit`) enforce main-push protection and commit-email validation but do not validate branch names. A developer who creates a branch like `feature/foo` or `my-work` can push it without any feedback.
Proposed Solution
Extend the global `pre-push` hook (or add a companion hook) to reject pushes from branches whose name does not match the documented format. Specifically:
- Accept: `branches/-` where `` is one or more digits and `` is lowercase letters, numbers, and hyphens.
- Accept: `branches/` (no numeric prefix) for branches that have no tracked issue.
- Reject with a helpful error message pointing at the standards doc when the name does not match.
- Skip validation on `main`, `master`, and any branch matching names that predate this rule, to avoid blocking legitimate pushes to already-named branches (list can live in the hook as a regex).
Add a per-repo opt-out file (e.g., `.allow-any-branch-name`) following the same pattern as the existing `.allow-push-main` escape hatch, so personal projects or forks can skip enforcement.
Acceptance Criteria
- Pushing from a compliant branch (`branches/123-my-feature` or `branches/my-feature`) succeeds unchanged.
- Pushing from a non-compliant branch (`feature/foo`, `my-work`) is rejected with an error message that quotes the expected format and links to `standards/CLAUDE.md`.
- The existing main-push protection and commit-email validation are unaffected.
- A repo containing `.allow-any-branch-name` in its root skips the branch-name check.
- `hooks/hooks.json` is updated if a new hook file is introduced.
- `setup-env.sh` and `setup-env.ps1` install the updated hook on re-run.
Open Questions
- Should the hook also validate that `Closes #N` / `Fixes #N` appears in the latest commit message when the branch name contains an issue number? That feels more intrusive; start with branch-name-only and consider extending later.
- Should the hook run on `pre-commit` (catches the problem earlier) or `pre-push` (fewer false positives on in-progress branches that get renamed)? `pre-push` is probably the right trade-off.
Related
- #5 — introduces the Branch Naming and PR Linking standard this hook would enforce.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading hooks/pre-push and hooks/pre-commit to understand the existing protections, then inspect hooks/hooks.json, setup-env.sh, and setup-env.ps1 for installation behavior. Implement branch-name enforcement with the documented opt-out and legacy exceptions, preserving the existing checks. Verify the compliant, rejected, main/master, opt-out, and installer cases against the acceptance criteria.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- powershell, shell
- Domain
- developer-experience, tooling
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 68/100