chore: enforce single-purpose commits via pre-commit batch guard

[singyichen]

Summary

• The one-logical-change-per-commit rule existed in CLAUDE.md but had no mechanical enforcement — large batch commits could slip through
• Adds a native git pre-commit hook (scripts/git-hooks/pre-commit) blocking staged changes > 10 files or > 300 non-test lines; merge commits exempt; ALLOW_BATCH_COMMIT=1 bypass requires prior user approval
• Native git hook chosen over a Claude PreToolUse hook: chained git add && git commit has nothing staged at PreToolUse time, and git hooks also cover manual commits
• session-init.sh sets core.hooksPath idempotently, so the guard activates on every clone without manual setup

Changed Files

File	Change
scripts/git-hooks/pre-commit	New batch-commit guard (thresholds, merge exemption, approved bypass)
.claude/hooks/session-init.sh	Idempotent core.hooksPath setup at session start
CLAUDE.md	Commit Convention gains "Single purpose per commit (enforced)" paragraph

Test Plan

Verified in a throwaway git repo with core.hooksPath pointed at the new hook:

• Small commit (1 file) passes
• 11 staged files blocked with exit 1 and actionable message
• 301 non-test lines blocked
• 301 lines under tests/ pass (test exclusion works)
• ALLOW_BATCH_COMMIT=1 bypass works and prints warning
• 12-file merge commit exempt
• Dogfooded: this branch's own commit went through the active guard
• No pytest/Playwright suites exist yet (backend//frontend/ not scaffolded) — no regression surface

🤖 Generated with Claude Code

[qodo-code-review]

Qodo reviews are paused for this user.

Troubleshooting steps vary by plan Learn more →

On a Teams plan?
Reviews resume once this user has a paid seat and their Git account is linked in Qodo.
Link Git account →

Using GitHub Enterprise Server, GitLab Self-Managed, or Bitbucket Data Center?
These require an Enterprise plan - Contact us
Contact us →

[amazon-q-developer]

This PR introduces a mechanical enforcement mechanism for the single-purpose-per-commit rule through a native git pre-commit hook. The implementation is mostly sound with clear thresholds and exemptions.

Critical Issue Identified:

• The pre-commit hook lacks error handling for git operations that could fail outside a repository context, which could cause unexpected behavior.

Recommendation: Address the identified issue before merging to ensure the hook behaves correctly in all scenarios.

---

You can now have the agent implement changes and create commits directly on your pull request's source branch. Simply comment with /q followed by your request in natural language to ask the agent to make changes.

[gemini-code-assist]

Code Review

This pull request introduces a git pre-commit hook to enforce a "single purpose per commit" rule by blocking commits with more than 10 staged files or 300 non-test lines. It also updates the session initialization script to automatically configure the git hooks path and documents this rule in CLAUDE.md. The review feedback highlights potential issues in the pre-commit hook script, specifically regarding the pipefail behavior when grep finds no matches and the use of a literal tab character in the regex, suggesting a refactored awk command to address both concerns.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.