From f33e27cfbf0520955c43e66c669fa0c128a1f18a Mon Sep 17 00:00:00 2001
From: Greg Gauthier <gmgauthier@protonmail.com>
Date: Tue, 3 Mar 2026 20:49:27 +0000
Subject: [PATCH] refactor(safety): replace file backups with Git-based change
 management

Update safety features to leverage Git for version control and rollbacks instead of creating .bak files. This includes:
- Removing backup mentions from README.md, cmd/lint.go, ARCHITECTURE.md, and TROUBLESHOOTING.md
- Adding detailed Git workflow for managing changes in README.md
- Updating troubleshooting guide with Git rollback instructions
- Modifying feature lists and safety descriptions to emphasize Git integration
---
 README.md               | 36 ++++++++++++++++++++++++++++++++++--
 cmd/lint.go             |  1 -
 docs/ARCHITECTURE.md    |  4 ++--
 docs/TROUBLESHOOTING.md | 26 +++++++++++++-------------
 4 files changed, 49 insertions(+), 18 deletions(-)

diff --git a/README.md b/README.md
index cfa09da..2447ad5 100644
--- a/README.md
+++ b/README.md
@@ -72,7 +72,7 @@ grokkit chat --debug            # Enable debug logging
 - Use `--debug` to see API request timing
 
 ### ✏️ `grokkit edit FILE "instruction"`
-AI-powered file editing with preview and automatic backups.
+AI-powered file editing with preview.
 
 ```bash
 # Basic usage
@@ -254,6 +254,38 @@ grokkit lint script.rb -m grok-4
 - Verifies fixes by re-running linter
 - Requires confirmation (unless `--auto-fix`)
 
+## Safety & Change Management
+
+Grokkit is designed to work seamlessly with Git. Rather than creating redundant `.bak` files, we lean on Git's powerful version control to manage changes and rollbacks.
+
+### The Safety Workflow
+
+1.  **Preview**: Every command that modifies files (like `edit`, `lint`, `docs`) shows a diff-style preview first.
+2.  **Confirm**: You must explicitly confirm (`y/N`) before any changes are written to disk.
+3.  **Git Integration**: Use Git to manage the "pre-staged," "staged," and "committed" degrees of change.
+
+### Managing Undesired Changes
+
+If you've applied a change that you don't like, Git makes it easy to roll back:
+
+- **Unstaged changes**: If you haven't `git add`-ed the changes yet:
+  ```bash
+  git restore <file>
+  ```
+- **Staged changes**: If you've already staged the changes:
+  ```bash
+  git restore --staged <file>
+  git restore <file>
+  ```
+- **Committed changes**: If you've already committed the changes:
+  ```bash
+  git revert HEAD
+  # or to reset to a previous state:
+  git reset --hard HEAD~1
+  ```
+
+By using Git, you have a complete audit trail and multiple levels of undo, ensuring your codebase remains stable even when experimenting with AI-driven refactors.
+
 ## Configuration
 
 ### Environment Variables
@@ -448,7 +480,7 @@ grokkit review -v
 - ✅ **Persistent chat history** - Never lose your conversations
 - ✅ **Configurable parameters** - Temperature, timeout, model selection
 - ✅ **Shell completions** - Bash, Zsh, Fish, PowerShell
-- ✅ **Safe file editing** - Automatic backups, preview, confirmation
+- ✅ **Safe file editing** - Preview and confirmation, leverage git for rollbacks
 - ✅ **Git workflow integration** - Commit messages, reviews, PR descriptions
 - ✅ **Multi-language linting** - 9 languages supported with AI-powered fixes
 - ✅ **AI documentation generation** - 8 doc styles (godoc, PEP 257, Doxygen, JSDoc, rustdoc, YARD, Javadoc, shell)
diff --git a/cmd/lint.go b/cmd/lint.go
index 8b70dd7..74f5e2e 100644
--- a/cmd/lint.go
+++ b/cmd/lint.go
@@ -32,7 +32,6 @@ The command will:
 4. (Optional) Use Grok AI to generate and apply fixes
 
 Safety features:
-- Creates backup before modifying files
 - Shows preview of changes before applying
 - Requires confirmation unless --auto-fix is used`,
 	Args: cobra.ExactArgs(1),
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index c269669..77a23a3 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -23,7 +23,7 @@ Grokkit follows these core principles:
 - Single responsibility per package
 
 ### 2. **Safety by Default**
-- File backups before any modification
+- Git-based version control for change management
 - Confirmation prompts for destructive actions
 - Comprehensive error handling
 
@@ -567,7 +567,7 @@ func Run(args []string) (string, error) {
 **Current measures:**
 - API key via environment variable
 - No credential storage
-- Backup files for safety
+- Git-based rollbacks for safety
 
 **Future considerations:**
 - Encrypted config storage
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
index 790ec85..bc36abf 100644
--- a/docs/TROUBLESHOOTING.md
+++ b/docs/TROUBLESHOOTING.md
@@ -322,28 +322,28 @@ pwd
 ls
 ```
 
-### Permission denied on backup creation
+### Rolling back AI changes
 
 **Symptom:**
-```
-Failed to create backup: permission denied
-```
+AI suggested changes are undesired or introduced bugs.
 
 **Solution:**
+Use Git to roll back:
+
 ```bash
-# Check file permissions
-ls -la main.go
+# If not yet added/staged:
+git restore <file>
 
-# Check directory permissions
-ls -ld .
+# If staged:
+git restore --staged <file>
+git restore <file>
 
-# Fix permissions
-chmod 644 main.go    # File
-chmod 755 .          # Directory
-
-# Or run from writable directory
+# If committed:
+git revert HEAD
 ```
 
+Always review changes with `git diff` before and after applying AI suggestions.
+
 ### Failed to write file
 
 **Symptom:**