From cc182addfa6f7d04c0fb1be6b9ae538168b572fe Mon Sep 17 00:00:00 2001
From: Lakshman Patel <Lakshmanp230@gmail.com>
Date: Thu, 18 Jun 2026 16:18:20 +0530
Subject: [PATCH] docs: add sync-clone and commit-clean helpers for
 post-rewrite clones

Add scripts to reset stale SHAs and commit without IDE co-author injection,
plus make sync-submodules/sync-clone targets and CONTRIBUTING guidance.
---
 CONTRIBUTING.md         | 14 ++++++++++++++
 Makefile                | 11 ++++++++++-
 scripts/commit-clean.sh |  7 +++++++
 scripts/sync-clone.sh   | 20 ++++++++++++++++++++
 4 files changed, 51 insertions(+), 1 deletion(-)
 create mode 100755 scripts/commit-clean.sh
 create mode 100755 scripts/sync-clone.sh

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 2d811ef8..e9c68510 100644
--- a/CONTRIBUTING.md
+++ b/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.
diff --git a/Makefile b/Makefile
index cb18a32c..f52bdc08 100644
--- a/Makefile
+++ b/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
diff --git a/scripts/commit-clean.sh b/scripts/commit-clean.sh
new file mode 100755
index 00000000..52a2e170
--- /dev/null
+++ b/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 "$@"
diff --git a/scripts/sync-clone.sh b/scripts/sync-clone.sh
new file mode 100755
index 00000000..696374a9
--- /dev/null
+++ b/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