[ci] Add git hooks and PR validation (#32)

* [ci] Add pre-commit and commit-msg git hooks

* [ci] Add PR title and description validation workflow

* [docs] Add hooks target and development section

Author: lugassawan

.githooks/commit-msg

@@ -0,0 +1,30 @@
+#!/bin/sh
+# Commit-msg hook: enforce [type] prefix convention.
+
+SUBJECT=$(head -1 "$1")
+
+# Allow merge commits and reverts
+case "$SUBJECT" in
+    Merge*|Revert*) exit 0 ;;
+esac
+
+# Keep in sync with .github/workflows/pr.yml
+PATTERN='^\[(feat|fix|refactor|test|ci|docs|perf|chore|polish|breaking)\] .+'
+
+if ! echo "$SUBJECT" | grep -qE "$PATTERN"; then
+    echo ""
+    echo "ERROR: Invalid commit message:"
+    echo "  $SUBJECT"
+    echo ""
+    echo "Expected format:"
+    echo "  [type] Description"
+    echo ""
+    echo "Allowed types:"
+    echo "  feat, fix, refactor, test, ci, docs, perf, chore, polish, breaking"
+    echo ""
+    echo "Examples:"
+    echo "  [feat] Add worktree sync command"
+    echo "  [fix] Resolve branch detection on Windows"
+    echo "  [ci] Add coverage gate to CI pipeline"
+    exit 1
+fi

.githooks/pre-commit

@@ -0,0 +1,15 @@
+#!/bin/sh
+# Pre-commit hook: format staged Go files and run linter.
+
+set -e
+
+# Format staged Go files
+STAGED_GO_FILES=$(git diff --cached --name-only --diff-filter=ACM -- '*.go')
+
+if [ -n "$STAGED_GO_FILES" ]; then
+    echo "$STAGED_GO_FILES" | xargs gofmt -l -w
+    echo "$STAGED_GO_FILES" | xargs git add
+fi
+
+# Run linter
+make lint

.github/workflows/pr.yml

@@ -0,0 +1,33 @@
+name: PR Validation
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize]
+    branches: [main]
+
+jobs:
+  validate-pr:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Validate PR title
+        env:
+          PR_TITLE: ${{ github.event.pull_request.title }}
+        run: |
+          # Keep in sync with .githooks/commit-msg
+          PATTERN='^\[(feat|fix|refactor|test|ci|docs|perf|chore|polish|breaking)\] .+'
+          if ! echo "$PR_TITLE" | grep -qE "$PATTERN"; then
+            echo "::error::PR title must match format: [type] Description (e.g. [feat] Add new feature)"
+            echo ""
+            echo "Allowed types: feat, fix, refactor, test, ci, docs, perf, chore, polish, breaking"
+            exit 1
+          fi
+
+      - name: Validate PR description
+        env:
+          PR_BODY: ${{ github.event.pull_request.body }}
+        run: |
+          TRIMMED=$(echo "$PR_BODY" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+          if [ -z "$TRIMMED" ]; then
+            echo "::error::PR description must not be empty"
+            exit 1
+          fi

Makefile

@@ -6,7 +6,7 @@ LDFLAGS  = -s -w \
 	-X github.com/lugassawan/rimba/cmd.commit=$(COMMIT) \
 	-X github.com/lugassawan/rimba/cmd.date=$(DATE)
 
-.PHONY: build test test-short test-e2e test-coverage clean lint bench
+.PHONY: build test test-short test-e2e test-coverage clean lint bench hooks
 
 build:
 	go build -ldflags '$(LDFLAGS)' -o bin/rimba .
@@ -32,3 +32,7 @@ lint:
 
 bench:
 	go test -bench=. -benchmem -run=^$$ ./...
+
+hooks:
+	git config core.hooksPath .githooks
+	@echo "Git hooks activated from .githooks/"

README.md

@@ -21,6 +21,7 @@
 - [Commands](#commands)
 - [Configuration](#configuration)
 - [Environment Variables](#environment-variables)
+- [Development](#development)
 - [License](#license)
 
 ## Features
@@ -396,6 +397,43 @@ work_dir = 'api'
 | `RIMBA_QUIET` | Suppress pre-execution hints (set to any value, e.g. `RIMBA_QUIET=1`) |
 | `NO_COLOR` | Disable colored output globally (per [no-color.org](https://no-color.org)) |
 
+## Development
+
+### Setup
+
+```sh
+git clone https://github.com/lugassawan/rimba.git
+cd rimba
+make hooks  # Activate git hooks
+make build  # Build the binary
+```
+
+### Git Hooks
+
+Running `make hooks` configures Git to use the hooks in `.githooks/`:
+
+- **pre-commit** — formats staged Go files with `gofmt` and runs `make lint`
+- **commit-msg** — enforces the `[type] Description` commit message format
+
+### Commit Convention
+
+All commit messages must follow the format `[type] Description`, where type is one of:
+
+| Type | Purpose |
+|------|---------|
+| `feat` | New feature |
+| `fix` | Bug fix |
+| `refactor` | Code restructuring (no behavior change) |
+| `test` | Adding or updating tests |
+| `ci` | CI/CD changes |
+| `docs` | Documentation |
+| `perf` | Performance improvement |
+| `chore` | Maintenance tasks |
+| `polish` | Minor improvements and cleanups |
+| `breaking` | Breaking changes |
+
+This convention is enforced locally by git hooks and in CI by PR title validation.
+
 ## License
 
 [MIT](LICENSE)