/git-guardrails

name: git-guardrails
description: 'Use when a repository needs Git safety controls: guard destructive commands, set up gitignore or fix gitignore when untracked files keep appearing, or install or repair a repository-local pre-commit hook from project gates, including package-manager-native commit-time checks. Not for remote, credential, publish, deploy, or irreversible changes.'

Manage Git repository guardrails

Contract

| Field | Bound contract | |---|---| | Trigger | A repository needs destructive-command protection, deterministic `.gitignore` composition, or installing or repairing one repository-local pre-commit owner from project gates; this includes `set up gitignore`, `fix gitignore`, `untracked files keep appearing`, and package-manager-native commit-time checks. | | Authority | Reversible local: guard mode writes only the installed hook and one merged settings entry; `setup-gitignore` mode writes only the repository `.gitignore`; `setup-pre-commit` mode writes only hook configuration, dependency manifests, lockfiles, a temporary probe file, a staged trivial change, and the local Git hook. Rollback is mode-specific cleanup or restoration. No remote, credential, or release mutation. | | Side effect | Installs a command guard and settings registration, or deterministically composes `.gitignore`, or selects/installs one pre-commit manager and runs repository-native checks. | | Done | The chosen mode meets its gate: guard mode passes all 16 payloads and registers the hook; `setup-gitignore` mode produces deterministic managed sections and reports before/after untracked counts; `setup-pre-commit` mode has exactly one manager owning the hook, its all-files command passes without formatter residue, a deliberate failing probe blocks, and the restored passing probe exits zero. |

Inputs

• Mode (required, chosen by the user): `guard`, `setup-gitignore`, or `setup-pre-commit`.
• Guard mode: scope (project `.claude/settings.json` plus `.claude/hooks/`, or global `~/.claude/settings.json` plus `~/.claude/hooks/`), the shipped `scripts/block-dangerous-git.py` source, and optional rule additions or removals decided before installation.
• `setup-gitignore` mode: the current Git repository and, optionally, empirical ignore patterns explicitly confirmed by the user after reviewing current untracked-path clusters. Never infer confirmation or add an empirical pattern silently.
• `setup-pre-commit` mode: a repository root with `.git`, repository-native format/lint/type-check/targeted-test commands inferred only from committed scripts and configuration, and any existing hook manager (optional; detect Husky, Lefthook, prek/pre-commit, cargo-husky, and native `.git/hooks/pre-commit`).

Procedure

1. Choose exactly one mode. Mutate nothing before the mode-specific prerequisites are available. Done when: the user has chosen `guard`, `setup-gitignore`, or `setup-pre-commit`, and the required inputs for that mode are identified.

2. For `guard` mode, ask the user to choose project or global scope. Mutate nothing before the choice. Done when: the scope is chosen with no mutation made.

a. Copy `scripts/block-dangerous-git.py` to the chosen location, project: `.claude/hooks/block-dangerous-git.py`; global: `~/.claude/hooks/block-dangerous-git.py`, and run `chmod +x` on the copy. Leave the skill's source copy untouched. Done when: the hook copy exists at the chosen path, is executable, and the source copy is unchanged.

b. Show the default blocked operations, forced pushes and forced refspecs; `reset --hard`; forced `clean`; forced branch deletion; `checkout .` and `restore .`; `stash drop` and `stash clear`; `reflog expire`; `gc --prune=now`, and ask whether to add or remove a rule. On approval, edit only the installed copy. When a rule is added or removed, add or remove the corresponding test case in the verification matrix so the gate covers the modified policy. Done when: the blocked-operations list is shown, any approved rule change is applied to the installed copy only, and the verification matrix matches.

c. Verify before registration. For each payload below, run:

      printf '%s\n' '<payload>' | <path-to-hook>
      printf 'exit=%s\n' "$?"

Must exit 2:

1. `{"tool_input":{"command":"git push --force origin main"}}` 2. `{"tool_input":{"command":"ok && git reset --hard"}}` 3. `{"tool_input":{"command":"echo ok\ngit reset --hard"}}` 4. `{"tool_input":{"command":"bash -c \"git reset --hard\""}}` 5. `{"tool_input":{"command":"bash -lc \"git reset --hard\""}}` 6. `{"tool_input":{"command":"eval \"git reset\" --hard"}}` 7. `{"tool_input":{"command":"git clean --force"}}` 8. `{"tool_input":{"command":"git branch --delete --force"}}` 9. `{"tool_input":{"command":"git checkout ."}}` 10. `{"tool_input":{"command":"git stash clear"}}` 11. `{"tool_input":{"command":"git reflog expire --all"}}` 12. `{"tool_input":{"command":"git gc --prune=now"}}` 13. `{"tool_input":{"command":"git push origin +main"}}`

Must exit 0:

14. `{"tool_input":{"command":"git push origin main"}}` 15. `{"tool_input":{"command":"git commit -m \"oops; git reset --hard\""}}` 16. `{"tool_input":{"command":"git --git-dir=.git status"}}`

All sixteen cases must match before registration. A blocked command prints this to stderr and exits 2:

      BLOCKED: '<command>' matches dangerous pattern '<pattern>'. The user has prevented you from doing this.

Done when: all sixteen payloads exit as expected, the thirteen dangerous commands exit 2, the three safe ones exit 0, and the BLOCKED stderr message is confirmed.

d. After all sixteen cases pass, merge the entry into the existing `hooks.PreToolUse` array of the chosen settings file. Never overwrite the settings file or discard existing hooks. Done when: the entry is merged into the existing `hooks