Skip to content

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.

  • Safety: force push (-f, --force, +refspec), reset with --hard, clean with any -f*, branch -D / --delete --force, checkout/restore that 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 — so git -C repo reset -q --hard is blocked, while git push --force-with-lease is allowed. Rules live in scripts/lib/git-argv.py, mirrored in extensions/omp-hooks.ts; scripts/test-guard-git-normalize.sh fails if the two disagree.
  • Discipline: Blocks direct commits or pushes to protected branches (main, master) unless GIT_BIGPOWERS_LAND=1 (set only by scripts/land-branch.sh).
  • Allows: git push origin <feature-branch> for backup/CI; solo land push to main only inside land-branch.sh.
  • Standardization: Enforces Conventional Commits for all git commit commands.
  • Secrets: Blocks commits containing common secret patterns (sk-, ghp_, AKIA, xoxb-, -----BEGIN private keys) — see REFERENCE.md.
  1. Scope: ask project-only vs global (paths differ per product).
  2. Write the hook bundle from REFERENCE.md into the client’s hooks directory.
  3. Run chmod +x on pre-tool-use.sh.
  4. Merge the hook snippet from REFERENCE.md into the right settings file — do not wipe unrelated keys.
  5. 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.

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.

Full JSON examples, merge rules, Antigravity deny-list entries, and test commands: REFERENCE.md.

<!– story: e01s03 –>