CLAUDE.md

@@ -29,6 +29,19 @@ td session --new         # force a new session in the same terminal context
 
 Task state is stored in `.todos/issues.db` (SQLite).
 
+## Git Hooks
+
+A commit-msg hook normalizes commit messages on every commit (capitalizes subject, strips trailing period, trims whitespace, warns when subject exceeds 72 characters). The hook never blocks a commit.
+
+**Wire hooks after cloning:**
+```bash
+sh scripts/install-hooks.sh
+# or via npm script:
+cd scripts && npm run hooks:install
+```
+
+The hook script lives at `scripts/commit-msg` and is invoked by `.git/hooks/commit-msg`. The normalizer logic is in `scripts/normalize-commit-msg.js` with unit tests in `scripts/__tests__/normalize-commit-msg.test.js` (run with `cd scripts && npm test`).
+
 ## Development
 
 **Run production stack (Docker):**

scripts/__tests__/normalize-commit-msg.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-const { normalizeSubject, normalizeMessage } = require('../normalize-commit-msg.js');
+import { normalizeSubject, normalizeMessage } from '../normalize-commit-msg.js';
 
 describe('normalizeSubject', () => {
   it('passes an already-valid subject unchanged', () => {