stacks-guard

# /stacks-guard - Safety Rails Prevent destructive actions and enforce focus during debugging sessions. ## Destructive Command Detection ### 🔴 CRITICAL - Block and require confirmation | Pattern | Risk | |---------|------| | `rm -rf /`, `rm -rf ~`, `rm -rf .` | Catastrophic file deletion | | `DROP TABLE`, `DROP DATABASE`, `TRUNCATE` | Irreversible data loss | | `git push --force` to `main`/`master` | Overwrites shared history | | `git reset --hard` with uncommitted changes | Loses uncommitted work | | `git clean -fd` | Deletes untracked files permanently | | `buddy migrate:fresh` on production | Drops ALL tables | | `buddy seed --fresh` on production | Truncates all data | Response: ``` 🔴 GUARD: Destructive command detected Command: [command] Risk: [what will be destroyed] Reversible: [yes/no] ``` ### 🟡 WARNING - Warn but allow | Pattern | Risk | |---------|------| | `git push --force` (non-main) | Overwrites remote branch | | `rm -rf [specific dir]` | Deletes directory tree | | `bun remove [core dep]` | May break build | | `git checkout -- .` | Discards all unstaged changes | | Bulk file moves/renames | May break imports/aliases | | Modifying `config/services.ts` | Contains API keys | | Modifying `storage/framework/core/*/src/index.ts` | Public package API | ### 🟢 INFORMATIONAL - Note but don't block | Pattern | Note | |---------|------| | `git rebase` | History rewrite - ensure not shared | | `bun update` (major versions) | May introduce breaking changes | | Modifying CI/CD config | Affects deployment pipeline | | Changing auth/permissions code | Security-sensitive | | Modifying migration files | Database schema change | ## Freeze Mode Restrict edits during focused debugging. ### Activate ``` /stacks-guard freeze [file or directory pattern] ``` When active: 1. **Block edits outside the freeze scope** 2. **Track all changes** made during the session 3. **Warn if changes grow large** (>5 files or >50 lines) ### Deactivate ``` /stacks-guard thaw ``` Produces a summary of all changes. ## Pre-Commit Safety Before commits, scan for: 1. **Secrets**: API keys, tokens, passwords in staged files 2. **Debug artifacts**: `console.log`, `debugger`, `TODO: remove` 3. **Large files**: >1MB being committed 4. **Lockfile consistency**: `package.json` changed → `bun.lock` should too ## Stacks-Specific Guards - **Don't edit `storage/framework/types/*.d.ts`** - these are auto-generated - **Don't edit `storage/framework/defaults/app/Models/`** without also generating migrations - **Don't modify `config/services.ts` in commits** - contains API keys - **Check `storage/framework/core/*/package.json` versions** - workspace packages should stay in sync ## Make it enforcing Everything above is advisory: it works only while the agent is paying attention. A **PreToolUse hook** turns it into enforcement, because the harness runs it on every Bash call before the command executes. [scripts/block-destructive.sh](scripts/block-destructive.sh) is the hook. It reads the tool call on stdin, exits 2 with a message on stderr when the command matches a blocked pattern, and exits 0 otherwise. It blocks two lists: commands that are unrecoverable anywhere (`rm -rf /` or `~` or `.`, force-push, `reset --hard`, `clean -f`, `branch -D`, `DROP TABLE`, `TRUNCATE TABLE`), and commands that are routine locally but destructive against production (`migrate:fresh`, `seed --fresh`, `cloud:remove`, `cloud:cleanup`, gated on the command naming a production env). Deliberately not blocked: a plain `git push`, `rm -rf node_modules`, `buddy migrate:fresh` locally. A guard that fires on regenerable things gets turned off, and a guard that is off protects nothing. Credit: adapted from Matt Pocock's `git-guardrails-claude-code` skill (MIT), <https://github.com/mattpocock/skills>. ### Install 1. **Ask the scope.** This project (`.claude/settings.json`) or every project (`~/.claude/settings.json`)? 2. **Copy the script** to `.claude/hooks/block-destructive.sh` or `~/.claude/hooks/block-destructive.sh`, and `chmod +x` it. 3. **Register it.** Merge into the existing `hooks.PreToolUse` array rather than overwriting the file: ```json { "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-destructive.sh" } ] } ] } } ``` For the global install, the command is `~/.claude/hooks/block-destructive.sh`. 4. **Tune the lists.** Ask the user what to add or remove. A repo that never deploys does not need the production list. A repo with a protected `main` may want a plain `git push` blocked too. 5. **Verify.** Each of these should print a BLOCKED line and exit 2: ```bash echo '{"tool_input":{"command":"git push --force origin main"}}' | .claude/hooks/block-destructive.sh ``` And each of these should exit 0 silently: ```bash echo '{"tool_input":{"command":"rm -rf node_modules"}}' | .claude/hooks/block-destructive.sh ``` `.claude/` is gitignored in a Stacks project, so a project-scope install is per-developer. To make it a team rule, commit the script under `scripts/` and have `buddy setup:ai` users point their hook at that path. ## Rules - **Never silently allow destructive commands.** - **Don't be annoying.** `rm file.txt` doesn't need a warning. `rm -rf node_modules` is fine - it's regenerable. - **Respect user intent.** After warning once, if confirmed, proceed. - **Context matters.** Force-push to a personal branch is not force-push to main. ## Downstream > Guard installed? `/stacks-retro` is where a near-miss becomes a permanent > check, and `/stacks-wizard` is for the production steps a human should be > doing by hand anyway.