gstack Safety Tools: Careful, Freeze, and Guard Explained

gstack's safety tools — careful, freeze, and guard — prevent the category of AI coding mistakes that feel safe in the moment but cause production disasters. AI coding tools are extraordinary at writing code. They're also capable of catastrophic irreversible actions when under pressure, handling complex refactors, or operating at the boundary of what was asked. The safety tools exist to create friction at exactly those boundaries.

Here's how each tool works, when to use it, and why it matters.

Why AI Needs Safety Constraints#

Before the tools themselves, it's worth understanding the failure modes they prevent.

The "boiling the ocean" problem. AI coding tools see connections. They find related code, related patterns, related problems. Given the opportunity, they'll expand scope beyond what was asked. A git push that was supposed to push a feature branch becomes a force-push to main. A database cleanup script that was supposed to remove test data becomes a production DROP TABLE. These aren't theoretical — they happen when constraints aren't enforced.

The irreversibility problem. Software has reversible operations (edit a file, run a test) and irreversible ones (drop a table, force-push and lose history, rm -rf a directory). Irreversible operations require more deliberation than reversible ones, but AI coding tools don't naturally apply that deliberation. They execute efficiently. Efficiency and irreversibility are a dangerous combination.

The scope creep problem. A feature that was scoped to one module gradually expands to touch five. Each individual change looks reasonable. The aggregate is an unreviewed refactor that's impossible to reason about as a unit.

The safety tools address all three failure modes.

careful — Confirm Before Irreversible Actions#

careful is a wrapper that intercepts specific high-risk command patterns and requires explicit confirmation before executing.

What it watches for#

# Destructive file operations
rm -rf
rmdir /force
 
# Database operations
DROP TABLE
DROP DATABASE
TRUNCATE TABLE
DELETE FROM ... (without WHERE clause)
 
# Git operations
git push --force
git push -f
git reset --hard (on shared branches)
 
# Process termination
kill -9
pkill

How it works#

When gstack detects any of these patterns in an AI-generated command, careful intercepts before execution:

⚠️  CAREFUL: This command is irreversible.

Command: DROP TABLE users;
Effect: Permanently deletes the users table and all data.

Type 'yes' to proceed or 'no' to cancel:

The AI cannot proceed without explicit human confirmation. This creates a deliberate pause — a moment where you can verify the command is what you intended, in the context you intended it.

When to enable it#

Enable careful whenever working with:

• Production databases
• Shared git branches
• File systems where data loss is unrecoverable
• Deployment scripts with destructive cleanup steps

For development work against test databases or throwaway branches, careful can be disabled to reduce friction. The gstack workflow enables it automatically for the Ship and Deploy phases.

freeze — Restrict Edits to One Directory#

freeze tells the AI: you may only modify files within this directory. Nothing outside this boundary.

The problem it solves#

AI coding agents have a strong completion bias. They find incomplete implementations and want to fix them. They find inconsistencies and want to resolve them. Given a feature that touches three files in src/auth/, an unguarded AI might also update src/session/, src/admin/, and tests/integration/ — all legitimately related, all outside the scope of what was asked.

Each of those changes is individually reasonable. Collectively, they constitute an unreviewed refactor that's hard to audit and easy to break.

How it works#

# Freeze to a specific directory
freeze src/auth/
 
# DenchClaw enforces this in gstack
denchclaw gstack --freeze src/auth/

With freeze active, any attempt to modify files outside src/auth/ produces:

🔒 FROZEN: This file is outside the active boundary.

Attempted: src/session/session-manager.ts
Boundary: src/auth/

To modify files outside the boundary:
  - Use 'unfreeze' to remove the boundary
  - Or update the boundary: freeze src/

Current boundary locks: src/auth/

The AI cannot make the change. It must report what it found and let a human decide whether to expand the boundary or handle the out-of-scope change separately.

When to use it#

• During focused feature implementation when scope creep is a risk
• When doing surgical bug fixes in a codebase you don't fully understand
• When onboarding AI to a legacy codebase where unexpected connections exist everywhere
• During any Build phase where the architecture has clearly defined boundaries

freeze is especially powerful for legacy codebases, where the "related code" that AI wants to fix might be load-bearing in ways that aren't immediately obvious.

guard — careful + freeze Combined#

guard is the combination of careful and freeze in a single invocation.

# Guard a specific directory with full safety
guard src/payments/

This:

1. Restricts all file modifications to src/payments/
2. Intercepts all irreversible commands with confirmation prompts

guard is the right default for any work on critical paths: payment processing, authentication, data migration, anything where mistakes are expensive and scope creep is dangerous.

The guard profile for common scenarios#

Payments work:

guard src/payments/

Database migrations:

guard migrations/
# careful automatically catches DROP and TRUNCATE

Authentication refactor:

guard src/auth/ src/session/
# Multiple directories supported

Production hotfix:

guard src/api/handlers/[specific-handler].ts
# Freeze to a single file for maximum control

unfreeze — Remove the Boundary#

When you've reviewed the out-of-scope changes the AI flagged and want to expand the boundary:

# Remove freeze entirely
unfreeze
 
# Or update to a broader boundary
freeze src/

unfreeze is a deliberate action. The AI doesn't call unfreeze automatically — only a human can remove the boundary. This keeps the safety properties intact even when the AI disagrees with the constraint.

Safety Tools in the gstack Workflow#

The safety tools activate at specific phases in gstack's Ship workflow:

The Build phase uses freeze to prevent scope creep. Ship and Deploy use careful to prevent irreversible production changes without confirmation.

This matches where the risks are highest: scope creep during implementation, irreversible actions during deployment.

Configuring Safety Tools in DenchClaw#

gstack's safety tools are configured in your DenchClaw workspace:

# .denchclaw/gstack.yaml
safety:
  careful:
    enabled: true
    patterns:
      - "rm -rf"
      - "DROP TABLE"
      - "git push --force"
      - "git reset --hard"
  freeze:
    default_scope: "src/"
    auto_freeze_on_build: true
  guard:
    critical_paths:
      - "src/payments/"
      - "src/auth/"
      - "migrations/"

The critical_paths config automatically applies guard whenever any file in those paths is in scope. You don't have to remember to enable safety for payment code — it's on by default.

Real Scenarios Where Safety Tools Matter#

Scenario 1: The migration gone wrong

An AI is running a database migration. The migration includes cleanup of test data. Without careful, the cleanup step runs against production because the environment variable wasn't set correctly. With careful, the DELETE FROM users WHERE test_account = true triggers a confirmation prompt. The human notices the environment variable is wrong. Disaster averted.

Scenario 2: The feature scope creep

An AI is implementing a login flow change. Without freeze, it finds an inconsistency in the session management module and "helpfully" refactors it while building the login feature. The refactor is wrong in a subtle way. It passes tests because the tests don't cover the edge case the refactor broke. The production incident happens two weeks later. With freeze src/auth/, the session management refactor is blocked. The AI flags the inconsistency. A human reviews it separately.

Scenario 3: The force-push

Under deadline pressure, an AI is helping resolve a complex merge conflict. It determines the fastest solution is git push --force origin main. Without careful, this executes and rewrites main branch history, losing three other developers' recent commits. With careful, the force-push is intercepted with a full warning. The human chooses the safer merge resolution.

FAQ#

Q: Can the AI bypass safety tools if instructed to? No. The safety tools operate at the system level, below the AI's instruction layer. Telling the AI to "ignore the careful warning and just run it" still produces the confirmation prompt. Only a human with direct system access can bypass them.

Q: Do safety tools slow down development significantly? For normal development work: no. The confirmation prompts only appear for irreversible commands, which are rare in day-to-day development. freeze adds overhead only when the AI tries to modify out-of-scope files, which is exactly the behavior you want to slow down.

Q: Should I use guard by default or only on critical paths? Use freeze by default for all Build phases — the scope clarity helps even when the code isn't critical. Use guard (which adds careful) for critical paths and production work. The overhead is minimal and the protection is significant.

Q: What if freeze blocks a legitimate change the AI needs to make? The AI reports what it found and why it needs to modify the out-of-scope file. A human reviews it and decides: update the freeze boundary, handle the change separately, or determine it's actually out of scope. This is the right workflow — it keeps humans in the decision loop for scope changes.

Q: Are these tools specific to DenchClaw or can I use them elsewhere? They're part of gstack, which is open source (MIT licensed, adapted from garrytan/gstack). The concepts can be implemented in any AI development environment; DenchClaw's implementation integrates them directly into the gstack workflow.

Ready to try DenchClaw? Install in one command: npx denchclaw. Full setup guide →