docs: add sync-clone and commit-clean helpers for post-rewrite clones (#57)

Add scripts to reset stale SHAs and commit without IDE co-author injection,
plus make sync-submodules/sync-clone targets and CONTRIBUTING guidance.

Author: Patel230

CONTRIBUTING.md

@@ -81,6 +81,20 @@ only the human author. Hooks are auto-installed by `make setup` via
 make hooks
 ```
 
+**Cursor / IDE commits:** some editors inject `Co-authored-by: Cursor` via their
+own git hooks. Use the clean commit helper to bypass IDE hooks while keeping
+lefthook checks on normal commits:
+
+```bash
+./scripts/commit-clean.sh -m "fix(scope): your message"
+```
+
+**After a history rewrite:** reset stale local SHAs with:
+
+```bash
+./scripts/sync-clone.sh
+```
+
 ## Commit signing
 
 Signed commits are required in this repo.

Makefile

@@ -205,10 +205,19 @@ compat-test: ## Validate testdata/compatibility-matrix.json and report the 'next
 compat-check: ## Strict validation — non-zero exit if any component lacks a version.
 	@go run ./cmd/compat-test -matrix=next -strict -file=testdata/compatibility-matrix.json
 
-.PHONY: hooks
+.PHONY: hooks sync-submodules sync-clone
 hooks: ## Install git hooks via lefthook (formatting, linting, conventional commits).
 	@command -v lefthook >/dev/null 2>&1 || (echo "install: go install github.com/evilmartians/lefthook@latest" && exit 1)
 	lefthook install
+
+sync-submodules: ## Fetch and checkout latest origin/main for all external/ submodules.
+	git submodule foreach 'git fetch origin && git checkout origin/main 2>/dev/null || git checkout origin/HEAD'
+	@echo "Submodule heads:"
+	@git submodule status
+
+sync-clone: ## Hard-reset hawk and submodules to origin/main (post history rewrite).
+	@chmod +x scripts/sync-clone.sh scripts/commit-clean.sh
+	@./scripts/sync-clone.sh
 # === Cross-platform binary targets (add after existing 'build' target) ===
 
 .PHONY: build-all build-static size-check

scripts/commit-clean.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# Commit without IDE-injected Co-authored-by trailers (Cursor, etc.).
+# Usage: ./scripts/commit-clean.sh [-m "message"] [other git commit args...]
+set -euo pipefail
+
+cd "$(git rev-parse --show-toplevel)"
+exec git -c core.hooksPath=/dev/null commit "$@"

scripts/sync-clone.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Hard-reset hawk and all external/ submodules to origin/main.
+# Use after a history rewrite or when your clone has stale SHAs.
+set -euo pipefail
+
+cd "$(git rev-parse --show-toplevel)"
+
+echo "==> Fetching origin"
+git fetch origin
+
+echo "==> Resetting hawk to origin/main"
+git checkout main
+git reset --hard origin/main
+
+echo "==> Updating submodules"
+git submodule update --init --recursive
+git submodule foreach 'git fetch origin && git checkout origin/main 2>/dev/null || git checkout origin/HEAD'
+
+echo "==> Done. hawk: $(git rev-parse --short HEAD)"
+git submodule status