From 50c3f4ee541419c6b0b98b97bb2d06db34f7942d Mon Sep 17 00:00:00 2001
From: Marcus Vorwaller <marcus@vorwaller.net>
Date: Sun, 12 Apr 2026 03:09:41 -0700
Subject: [PATCH] chore(repo): normalize commit messages

Nightshift-Task: commit-normalize
Nightshift-Ref: https://github.com/marcus/nightshift
---
 Makefile              |  8 +++++---
 README.md             | 34 ++++++++++++++++++++++++++++------
 scripts/commit-msg.sh | 41 +++++++++++++++++++++++++++++++++++++++++
 3 files changed, 74 insertions(+), 9 deletions(-)
 create mode 100755 scripts/commit-msg.sh

diff --git a/Makefile b/Makefile
index 088be01..d1ac858 100644
--- a/Makefile
+++ b/Makefile
@@ -75,10 +75,12 @@ help:
 	@echo "  check         - Run tests and lint"
 	@echo "  install       - Build and install to Go bin directory"
 	@echo "  calibrate-providers - Compare local Claude/Codex session usage for calibration"
-	@echo "  install-hooks  - Install git pre-commit hook"
+	@echo "  install-hooks - Install git hooks (pre-commit + commit-msg)"
 	@echo "  help          - Show this help"
 
-# Install git pre-commit hook
+# Install git hooks
 install-hooks:
+	@mkdir -p .git/hooks
 	@ln -sf ../../scripts/pre-commit.sh .git/hooks/pre-commit
-	@echo "✓ pre-commit hook installed (.git/hooks/pre-commit → scripts/pre-commit.sh)"
+	@ln -sf ../../scripts/commit-msg.sh .git/hooks/commit-msg
+	@echo "✓ hooks installed (.git/hooks/pre-commit → scripts/pre-commit.sh, .git/hooks/commit-msg → scripts/commit-msg.sh)"
diff --git a/README.md b/README.md
index 84f92cd..c149dfa 100644
--- a/README.md
+++ b/README.md
@@ -258,18 +258,40 @@ Each task has a default cooldown interval to prevent the same task from running
 
 ## Development
 
-### Pre-commit hooks
+### Commit messages
 
-Install the git pre-commit hook to catch formatting and vet issues before pushing:
+Use this format for new local commits:
+
+```text
+type(scope): summary
+```
+
+If a scope does not add clarity, `type: summary` is also valid. Allowed types: `feat`, `fix`, `docs`, `refactor`, `test`, `build`, `chore`, `ci`, `perf`.
+
+Examples:
+- `feat(tasks): add commit message validator`
+- `fix(config): preserve provider YAML keys`
+- `docs: document git hooks`
+- `build(release): bump version to v0.3.5`
+- `chore(release): prepare v0.3.5`
+
+Merge, revert, `fixup!`, and `squash!` commits are exempt. This standard applies to future commits only; existing history stays as-is.
+
+### Git hooks
+
+Install the git hooks to catch formatting, vet, build, and commit-message issues before pushing:
 
 ```bash
 make install-hooks
 ```
 
-This symlinks `scripts/pre-commit.sh` into `.git/hooks/pre-commit`. The hook runs:
-- **gofmt** — flags any staged `.go` files that need formatting
-- **go vet** — catches common correctness issues
-- **go build** — ensures the project compiles
+This symlinks `scripts/pre-commit.sh` into `.git/hooks/pre-commit` and `scripts/commit-msg.sh` into `.git/hooks/commit-msg`.
+
+The hooks run:
+- **gofmt** - flags any staged `.go` files that need formatting
+- **go vet** - catches common correctness issues
+- **go build** - ensures the project compiles
+- **commit-msg** - validates the first line of the commit message
 
 To bypass in a pinch: `git commit --no-verify`
 
diff --git a/scripts/commit-msg.sh b/scripts/commit-msg.sh
new file mode 100755
index 0000000..df83e4c
--- /dev/null
+++ b/scripts/commit-msg.sh
@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# commit-msg hook for nightshift
+# Install: make install-hooks  (or: ln -sf ../../scripts/commit-msg.sh .git/hooks/commit-msg)
+set -euo pipefail
+
+msg_file=${1:?commit message file required}
+subject=""
+
+IFS= read -r subject < "$msg_file" || true
+subject=${subject%$'\r'}
+
+case "$subject" in
+  Merge\ *|Revert\ *|fixup!\ *|squash!\ *)
+    exit 0
+    ;;
+esac
+
+pattern='^(feat|fix|docs|refactor|test|build|chore|ci|perf)(\([a-z0-9._/-]+\))?(!)?: .+'
+
+if [[ "$subject" =~ $pattern ]]; then
+  exit 0
+fi
+
+if [[ -n "$subject" ]]; then
+  echo "invalid commit subject: $subject" >&2
+else
+  echo "invalid commit subject: <empty>" >&2
+fi
+
+cat >&2 <<'EOF'
+use: type(scope): summary
+or:  type: summary
+types: feat fix docs refactor test build chore ci perf
+examples:
+  feat(tasks): add commit message validator
+  docs: document commit hooks
+  build(release): bump version to v0.3.5
+allowed: Merge..., Revert..., fixup! ..., squash! ...
+EOF
+
+exit 1