guard-git
Guard Git
Section titled “Guard Git”HARD GATE — HARD GATE — Before committing, verify: branch is not main/master, author is correct, git user is configured. Bad commits are hard to fix.
Installs a shared hook that blocks destructive git operations and enforces workflow discipline. Requires jq on the agent’s PATH when the hook runs.
What gets blocked/enforced
Section titled “What gets blocked/enforced”- Safety: force push (
-f,--force,+refspec),resetwith--hard,cleanwith any-f*,branch -D/--delete --force,checkout/restorethat discard work (-f,.pathspec). - Argv, not substrings: the hook tokenizes each command, strips git’s global options (
-C <path>,-c k=v,--no-pager,--git-dir=…) and judges the(subcommand, arguments)pair — sogit -C repo reset -q --hardis blocked, whilegit push --force-with-leaseis allowed. Rules live inscripts/lib/git-argv.py, mirrored inextensions/omp-hooks.ts;scripts/test-guard-git-normalize.shfails if the two disagree. - Discipline: Blocks direct commits or pushes to protected branches (
main,master) unlessGIT_BIGPOWERS_LAND=1(set only byscripts/land-branch.sh). - Allows:
git push origin <feature-branch>for backup/CI; solo land push tomainonly insideland-branch.sh. - Standardization: Enforces Conventional Commits for all
git commitcommands. - Secrets: Blocks commits containing common secret patterns (
sk-,ghp_,AKIA,xoxb-,-----BEGINprivate keys) — see REFERENCE.md.
Quick start
Section titled “Quick start”- Scope: ask project-only vs global (paths differ per product).
- Write the hook bundle from REFERENCE.md into the client’s hooks directory.
- Run
chmod +xonpre-tool-use.sh. - Merge the hook snippet from REFERENCE.md into the right settings file — do not wipe unrelated keys.
- Verify with the tests in REFERENCE.md.
| Client | Mechanism | Config |
|---|---|---|
| Claude Code | PreToolUse (Bash) |
.claude/settings.json or ~/.claude/settings.json |
| Cursor / Cursor CLI | beforeShellExecution |
.cursor/hooks.json or ~/.cursor/hooks.json |
| Gemini CLI | BeforeTool + run_shell_command |
.gemini/settings.json or ~/.gemini/settings.json |
| Google Antigravity | Built-in Terminal Deny list | Settings UI (no shell hook) |
Modes (env on the hook command): GIT_GUARDRAILS_MODE is claude (default) or cursor → stderr + exit 2 on block. Set gemini for Gemini CLI → JSON decision on stdout.
Customization
Section titled “Customization”The rule table lives in scripts/lib/git-argv.py (shell hooks) and is mirrored in extensions/omp-hooks.ts. Add a rule to both and a row to specs/verifications/fixtures/guard-git-normalize.yaml.
The TS side is judged through evaluateBashCall() — the single pure function the tool_call handler calls — so the fixture covers every rule (destructive argv, protected-branch push, Conventional Commits), not just the argv table. The gate (bash scripts/test-guard-git-normalize.sh) runs both implementations with GIT_BIGPOWERS_LAND unset and fails if they disagree, so a verdict can never depend on the developer’s shell.
Protected-branch rules answer differently on main than on a feature branch, so a row that touches commit/push semantics states its branch: and both sides are run in it (the shell hook in a throwaway repo checked out on that branch). A row without branch: is judged on a feature branch. Do not pin the branch inside either implementation — that is what made the gate pass on PRs and fail on main.
Advanced
Section titled “Advanced”Full JSON examples, merge rules, Antigravity deny-list entries, and test commands: REFERENCE.md.
<!– story: e01s03 –>