From d9ae32d464c47bef25f657b73d063352ebc8495a Mon Sep 17 00:00:00 2001
From: Rockford lhotka <rocky@lhotka.net>
Date: Tue, 16 Jun 2026 16:46:18 -0500
Subject: [PATCH] chore: add shared pre-commit gofmt hook

Mirror the CI gofmt check locally via .githooks/pre-commit, enabled with
'git config core.hooksPath .githooks'. Blocks a commit when any staged .go file
is not gofmt-clean. Documented under a new Development section in the README.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .githooks/pre-commit | 21 +++++++++++++++++++++
 README.md            | 15 +++++++++++++++
 2 files changed, 36 insertions(+)
 create mode 100755 .githooks/pre-commit

diff --git a/.githooks/pre-commit b/.githooks/pre-commit
new file mode 100755
index 0000000..b00a629
--- /dev/null
+++ b/.githooks/pre-commit
@@ -0,0 +1,21 @@
+#!/bin/sh
+# Pre-commit hook: block the commit if any staged Go file is not gofmt-clean.
+#
+# Enable once per clone:
+#     git config core.hooksPath .githooks
+#
+# This mirrors the CI gofmt check so formatting failures surface locally
+# instead of after a push. It only inspects staged Go files, so it stays fast.
+
+# Added/Copied/Modified staged .go files (skip deletions).
+gofiles=$(git diff --cached --name-only --diff-filter=ACM -- '*.go')
+[ -z "$gofiles" ] && exit 0
+
+unformatted=$(gofmt -l $gofiles)
+if [ -n "$unformatted" ]; then
+	echo "gofmt: these staged files are not formatted:" >&2
+	echo "$unformatted" | sed 's/^/  /' >&2
+	echo "" >&2
+	echo "Fix with:  gofmt -w $unformatted" >&2
+	exit 1
+fi
diff --git a/README.md b/README.md
index 7e07879..b582809 100644
--- a/README.md
+++ b/README.md
@@ -54,6 +54,21 @@ Full instructions:
 | `internal/proc` | Cross-platform helper that hides child-process console windows on Windows |
 | `internal/version` | Version resolution from `-ldflags` override or embedded VCS info |
 | `skills/` | `/distill` and `/distill-apply` Claude Code skills |
+| `.githooks/` | Shared git hooks (pre-commit gofmt check) |
+
+## Development
+
+The repo ships a pre-commit hook that runs the same `gofmt` check as CI, so
+formatting problems surface locally instead of after a push. Enable it once per
+clone:
+
+```sh
+git config core.hooksPath .githooks
+```
+
+It only inspects staged `.go` files and blocks the commit if any are not
+gofmt-clean, printing the `gofmt -w …` command to fix them. (`go vet` and the
+test suite stay in CI, which runs them across Linux/macOS/Windows.)
 
 ## Releasing