build: add commit-msg hook to enforce Conventional Commits

.githooks/README.md

@@ -0,0 +1,72 @@
+# Git Hooks
+
+This directory contains git hooks that enforce code quality and commit message standards.
+
+## Installation
+
+To install these hooks, run from the repository root:
+
+```bash
+# Install commit-msg hook
+cp .githooks/commit-msg .git/hooks/
+chmod +x .git/hooks/commit-msg
+
+# Or configure git to use this hooks directory
+git config core.hooksPath .githooks
+```
+
+## Available Hooks
+
+### commit-msg
+
+Validates that commit messages follow [Conventional Commits](https://www.conventionalcommits.org/) format.
+
+**Required format:**
+```
+type(scope): description
+
+[optional body]
+
+[optional footer(s)]
+```
+
+**Allowed types:**
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation changes
+- `style`: Code style changes (formatting, etc.)
+- `refactor`: Code refactoring
+- `perf`: Performance improvements
+- `test`: Adding or modifying tests
+- `build`: Build system or dependency changes
+- `ci`: CI/CD changes
+
+**Examples:**
+```bash
+fix: resolve WebSocket connection timeout
+feat(network): add peer reputation scoring
+build(deps): bump tokio from 1.0 to 1.1
+fix!: breaking change to API
+```
+
+**Important:**
+- Type must be **lowercase** (e.g., `fix:` not `Fix:`)
+- This matches the CI check on GitHub PRs
+- Breaking changes can be indicated with `!` after the type
+
+### pre-commit
+
+The pre-commit hook (already installed in `.git/hooks/pre-commit`) checks:
+- Code formatting with `cargo fmt`
+- Clippy lints
+- Special TODO comments that block commits
+- Disabled tests using Claude
+
+**Note:** The pre-commit hook is specific to your local setup and is already installed by git hooks installation scripts. It's not included in this directory as it's environment-specific.
+
+## Why This Matters
+
+- **CI Compatibility**: Our GitHub Actions CI checks PR titles for Conventional Commits format
+- **Consistency**: Everyone uses the same commit message style
+- **Automation**: Makes it easier to generate changelogs and release notes
+- **Early Feedback**: Catch issues locally before pushing to GitHub

.githooks/commit-msg

@@ -0,0 +1,41 @@
+#!/bin/bash
+# Commit message hook that validates Conventional Commits format
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Get the commit message file path (passed as first argument)
+COMMIT_MSG_FILE=$1
+
+if [ ! -f "$COMMIT_MSG_FILE" ]; then
+    echo -e "${RED}Error: Commit message file not found${NC}"
+    exit 1
+fi
+
+# Get the first line of the commit message
+FIRST_LINE=$(head -n1 "$COMMIT_MSG_FILE")
+
+# Conventional Commits pattern: type(scope): description OR type: description
+# type must be lowercase and from allowed list
+# type can optionally be followed by ! for breaking changes
+CONVENTIONAL_PATTERN="^(feat|fix|docs|style|refactor|perf|test|build|ci)(\([a-z0-9_-]+\))?!?: .+"
+
+if echo "$FIRST_LINE" | grep -qE "$CONVENTIONAL_PATTERN"; then
+    exit 0
+else
+    echo -e "${RED}✗ Commit message doesn't follow Conventional Commits format${NC}"
+    echo -e "${YELLOW}First line must match pattern: type(scope): description${NC}"
+    echo -e "${YELLOW}Allowed types: feat, fix, docs, style, refactor, perf, test, build, ci${NC}"
+    echo -e "${YELLOW}Type must be lowercase. Examples:${NC}"
+    echo -e "  ${GREEN}fix: resolve WebSocket connection timeout${NC}"
+    echo -e "  ${GREEN}feat(network): add peer reputation scoring${NC}"
+    echo -e "  ${GREEN}build(deps): bump tokio from 1.0 to 1.1${NC}"
+    echo -e "  ${GREEN}fix!: breaking change to API${NC}"
+    echo ""
+    echo -e "${RED}Your commit message:${NC}"
+    echo -e "${YELLOW}$FIRST_LINE${NC}"
+    exit 1
+fi