Cursor rule

1---
2description: "Block dangerous git commands (push, force push, reset --hard, clean, branch -D, checkout/restore .) and enforce Conventional Commits & Branch Protection before an AI agent runs them. Installs hook scripts for Claude Code, Cursor, Cursor CLI, and Gemini CLI; documents Google Antigravity Terminal deny lists. Use when the user wants git safety hooks, to block git push or destructive git in agents, or to mirror the same policy across AI coding tools."
3alwaysApply: false
4---
5 
6# Guard Git
7> **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.
8 
9 
10Installs a shared hook that blocks destructive git operations and enforces workflow discipline. **Requires `jq` on the agent's PATH** when the hook runs.
11 
12## What gets blocked/enforced
13 
14- **Safety**: `git push --force`, `git reset --hard`, `git clean -f`, `git branch -D`, `git checkout .`, `git restore .`.
15- **Discipline**: Blocks direct commits or pushes to protected branches (`main`, `master`) unless `GIT_BIGPOWERS_LAND=1` (set only by `scripts/land-branch.sh`).
16- **Allows**: `git push origin <feature-branch>` for backup/CI; solo land push to `main` only inside `land-branch.sh`.
17- **Standardization**: Enforces [Conventional Commits](https://www.conventionalcommits.org/) for all `git commit` commands.
18- **Secrets**: Blocks commits containing common secret patterns (`sk-`, `ghp_`, `AKIA`, `xoxb-`, `-----BEGIN` private keys) — see [REFERENCE.md](REFERENCE.md).
19 
20## Quick start
21 
221. **Scope**: ask project-only vs global (paths differ per product).
232. **Write the hook bundle** from [REFERENCE.md](REFERENCE.md) into the client's hooks directory.
243. **Run `chmod +x`** on `pre-tool-use.sh`.
254. **Merge** the hook snippet from [REFERENCE.md](REFERENCE.md) into the right settings file — do not wipe unrelated keys.
265. **Verify** with the tests in [REFERENCE.md](REFERENCE.md).
27 
28| Client | Mechanism | Config |
29|--------|-----------|--------|
30| Claude Code | `PreToolUse` (Bash) | `.claude/settings.json` or `~/.claude/settings.json` |
31| Cursor / Cursor CLI | `beforeShellExecution` | `.cursor/hooks.json` or `~/.cursor/hooks.json` |
32| Gemini CLI | `BeforeTool` + `run_shell_command` | `.gemini/settings.json` or `~/.gemini/settings.json` |
33| Google Antigravity | Built-in Terminal **Deny list** | Settings UI (no shell hook) |
34 
35**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.
36 
37## Customization
38 
39To add or remove patterns or protected branches, edit `pre-tool-use.sh`.
40 
41## Advanced
42 
43Full JSON examples, merge rules, Antigravity deny-list entries, and test commands: [REFERENCE.md](REFERENCE.md).
44 
45 
46 
47<!-- story: e01s03 -->
48 
49---
50 
51# Git guardrails — reference
52 
53## Navigation
54 
55| Lines | Section |
56|-------|---------|
57| 1 | Title |
58| 3–16 | Navigation |
59| 17–28 | Secret patterns (audit + pre-commit) |
60| 29–46 | Copy layout |
61| 47–72 | Claude Code |
62| 73–94 | Cursor and Cursor CLI |
63| 95–122 | Gemini CLI |
64| 123–137 | Google Antigravity |
65| 138–180 | Verify (local tests) |
66 
67## Secret patterns (audit + pre-commit)
68 
69Agents must not commit files containing:
70 
71- `sk-` (OpenAI API keys)
72- `ghp_` / `gho_` (GitHub tokens)
73- `AKIA` (AWS access key id)
74- `xoxb-` (Slack bot tokens)
75- `-----BEGIN` private keys
76 
77Use `audit-code` supply-chain checklist before commit. Consider `git-secrets` or custom pre-commit hook in target projects.
78 
79## Copy layout
80 
81The main script is `pre-tool-use.sh`.
82 
83```text
84<hooks-dir>/pre-tool-use.sh
85```
86 
87Example project locations:
88 
89- Claude: `.claude/hooks/`
90- Cursor: `.cursor/hooks/`
91- Gemini: `.gemini/hooks/`
92 
93Use the same layout for user-level hooks (`~/.claude/hooks`, `~/.cursor/hooks`, `~/.gemini/hooks`).
94 
95---
96 
97## Claude Code
98 
99Hook command does **not** need `GIT_GUARDRAILS_MODE` (defaults to `claude`).
100 
101**Project** (`.claude/settings.json`):
102 
103```json
104{
105  "hooks": {
106    "PreToolUse": [
107      {
108        "matcher": "Bash",
109        "hooks": [
110          {
111            "type": "command",
112            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/pre-tool-use.sh"
113          }
114        ]
115      }
116    ]
117  }
118}
119```
120 
121---
122 
123## Cursor and Cursor CLI
124 
125Use `beforeShellExecution`. Set `GIT_GUARDRAILS_MODE=cursor`.
126 
127**Project** (`.cursor/hooks.json`):
128 
129```json
130{
131  "version": 1,
132  "hooks": {
133    "beforeShellExecution": [
134      {
135        "command": "GIT_GUARDRAILS_MODE=cursor .cursor/hooks/pre-tool-use.sh",
136        "matcher": "git"
137      }
138    ]
139  }
140}
141```
142 
143---
144 
145## Gemini CLI
146 
147Use `BeforeTool` with matcher `run_shell_command`. Set **`GIT_GUARDRAILS_MODE=gemini`**.
148 
149**Project** (`.gemini/settings.json`):
150 
151```json
152{
153  "hooks": {
154    "BeforeTool": [
155      {
156        "matcher": "run_shell_command",
157        "hooks": [
158          {
159            "name": "git-guardrails",
160            "type": "command",
161            "command": "GIT_GUARDRAILS_MODE=gemini \"$GEMINI_PROJECT_DIR\"/.gemini/hooks/pre-tool-use.sh",
162            "timeout": 5000
163          }
164        ]
165      }
166    ]
167  }
168}
169```
170 
171---
172 
173## Google Antigravity
174 
175Add **Deny list** entries in **Antigravity → Settings → Terminal**:
176 
177- `git push --force`
178- `git push origin main`
179- `git push origin master`
180- `git reset --hard`
181- `git clean`
182- `git branch -D`
183- `git checkout .`
184- `git restore .`
185 
186---
187 
188## Verify (local tests)
189 
190**1. Block push to main without land mode (Claude mode):**
191```bash
192echo '{"tool_input":{"command":"git push origin main"}}' | ./pre-tool-use.sh
193# Expected: exit 2, protected branch message
194```
195 
196**2. Allow push to main with GIT_BIGPOWERS_LAND=1:**
197```bash
198GIT_BIGPOWERS_LAND=1 echo '{"tool_input":{"command":"git push origin main"}}' | ./pre-tool-use.sh
199# Expected: exit 0 (when on main)
200```
201 
202**3. Allow push to feature branch:**
203```bash
204echo '{"tool_input":{"command":"git push -u origin feat/my-task"}}' | ./pre-tool-use.sh
205# Expected: exit 0
206```
207 
208**4. Conventional Commits (Gemini mode):**
209```bash
210echo '{"tool_input":{"command":"git commit -m \"bad message\""}}' | GIT_GUARDRAILS_MODE=gemini ./pre-tool-use.sh
211# Expected: exit 0, {"decision":"deny", "reason":"..."}
212```
213 
214**5. Protected Branch commit (Cursor mode):**
215```bash
216# Run on 'main' branch
217echo '{"command":"git commit -m \"feat: valid message\""}' | GIT_GUARDRAILS_MODE=cursor ./pre-tool-use.sh
218# Expected: exit 2, "Direct commits to protected branch 'main' are forbidden"
219```
220 
221**6. Land script exists:**
222```bash
223test -x scripts/land-branch.sh && echo OK
224```
225 
226**7. Allow (Gemini mode):**
227```bash
228echo '{"tool_input":{"command":"git status"}}' | GIT_GUARDRAILS_MODE=gemini ./pre-tool-use.sh
229# Expected: exit 0, {"decision":"allow"}
230```
231