cursor-guard 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,105 @@
+# Cursor Guard
+
+Protects your code from accidental AI overwrite or deletion in [Cursor](https://cursor.com).
+
+## What It Does
+
+When Cursor's AI agent edits your files, there's a risk of accidental overwrites, deletions, or loss of work. **Cursor Guard** enforces a safety protocol:
+
+- **Mandatory pre-write snapshots** — Git commit or shadow copy before any destructive operation
+- **Read before Write** — The agent must read a file before overwriting it
+- **Review before apply** — Diff previews and explicit confirmation for dangerous ops
+- **Deterministic recovery** — Clear priority-ordered recovery paths (Git → shadow copies → conversation context → editor history)
+- **Configurable scope** — Protect only what matters via `.cursor-guard.json`
+- **Secrets filtering** — Sensitive files (`.env`, keys, certificates) are auto-excluded from backups
+- **Auto-backup script** — A PowerShell watcher that periodically snapshots to a dedicated Git branch without disturbing your working tree
+
+## Installation
+
+### For Cursor (as an Agent Skill)
+
+Copy the `cursor-guard/` folder into your Cursor skills directory:
+
+```
+~/.cursor/skills/cursor-guard/
+```
+
+Or per-project:
+
+```
+<project-root>/.cursor/skills/cursor-guard/
+```
+
+The skill activates automatically when the AI agent detects risky operations (file edits, deletes, renames) or when you mention recovery-related terms.
+
+### Project Configuration (Optional)
+
+Copy the example config to your workspace root and customize:
+
+```bash
+cp .cursor/skills/cursor-guard/references/cursor-guard.example.json .cursor-guard.json
+```
+
+Edit `.cursor-guard.json` to define which files to protect:
+
+```json
+{
+  "protect": ["src/**", "lib/**", "package.json"],
+  "ignore": ["node_modules/**", "dist/**"],
+  "auto_backup_interval_seconds": 60,
+  "secrets_patterns": [".env", ".env.*", "*.key", "*.pem"],
+  "retention": { "mode": "days", "days": 30 }
+}
+```
+
+## Auto-Backup Script
+
+Run in a separate terminal while working in Cursor:
+
+```powershell
+.\auto-backup.ps1 -Path "D:\MyProject"
+
+# Custom interval (default 60s):
+.\auto-backup.ps1 -Path "D:\MyProject" -IntervalSeconds 30
+```
+
+The script uses Git plumbing commands to snapshot to `cursor-guard/auto-backup` branch — it never switches branches or touches your working index.
+
+## Recovery
+
+If something goes wrong, recovery follows this priority:
+
+1. **Git** — `git restore`, `git reset`, `git reflog`
+2. **Shadow copies** — `.cursor-guard-backup/<timestamp>/`
+3. **Conversation context** — Original file content captured by agent Read calls
+4. **Editor history** — VS Code/Cursor Timeline (auxiliary)
+
+See [references/recovery.md](references/recovery.md) for detailed commands.
+
+## Trigger Keywords
+
+The skill activates on these signals:
+
+- File edits, deletes, renames by the AI agent
+- Recovery requests: "回滚", "误删", "丢版本", "rollback", "undo", "recover"
+- History issues: checkpoints missing, Timeline not working, save failures
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | Main skill instructions for the AI agent |
+| `references/auto-backup.ps1` | PowerShell auto-backup watcher script |
+| `references/recovery.md` | Recovery command templates |
+| `references/cursor-guard.example.json` | Example project configuration |
+| `references/cursor-guard.schema.json` | JSON Schema for config validation |
+
+## Requirements
+
+- **Git** (for primary backup strategy)
+- **PowerShell 5.1+** (for auto-backup script; Windows built-in)
+- **Cursor IDE** with Agent mode enabled
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: cursor-guard
+description: >-
+  Protects code from accidental AI overwrite or deletion in Cursor: mandatory
+  pre-write snapshots, review-before-apply, local Git safety net, and
+  deterministic recovery. Trigger on code loss, rollback, checkpoints,
+  Timeline/local history, tool vs editor saves, multi-root workspaces, or safe
+  AI editing workflows (including Chinese phrases like 回滚, 误删, 丢版本).
+---
+
+# Cursor Guard — Strong Protection Mode
+
+## When This Skill Applies (Triggers)
+
+Use this skill when any of the following appear:
+
+- **Auto disk writes**: Agent/tools edit files without the user reviewing a diff first.
+- **Deletes or renames**: Bulk delete, `rm`, refactor that removes paths.
+- **History confusion**: Checkpoints missing, Timeline/local history not rolling back, "save failed" after external writes.
+- **Parallel context**: Multiple repos or branches; unclear which folder is the workspace root.
+- **Recovery asks**: e.g. "改不回来", "丢版本", "回滚", "reflog", "误删", or English equivalents.
+
+If none of the above, do not expand scope; answer normally.
+
+---
+
+## 0. Load Project Config (If Exists)
+
+On first trigger in a session, check if the workspace root contains `.cursor-guard.json`. If found, **read it** and apply throughout:
+
+```jsonc
+{
+  "protect": ["src/**", "lib/**", "package.json"],
+  "ignore": ["node_modules/**", "dist/**", "*.log"],
+
+  "backup_strategy": "git",
+  "auto_backup_interval_seconds": 60,
+
+  // Sensitive file patterns — auto-excluded from backup even if in protect scope.
+  // Built-in defaults: .env, .env.*, *.key, *.pem, *.p12, *.pfx, credentials*
+  "secrets_patterns": [".env", ".env.*", "*.key", "*.pem"],
+
+  // Retention for shadow copies. mode: "days" | "count" | "size"
+  "retention": { "mode": "days", "days": 30, "max_count": 100, "max_size_mb": 500 }
+}
+```
+
+**Resolution rules:**
+- `protect` set + `ignore` set → file must match a `protect` pattern AND not match any `ignore` pattern.
+- Only `protect` set → only matching files are protected.
+- Only `ignore` set → everything is protected except matching files.
+- Neither set → protect everything (same as before).
+
+**`secrets_patterns`**: Glob patterns for sensitive files (`.env`, keys, certificates). Matching files are **auto-excluded** from backup commits, even within `protect` scope. Built-in defaults: `.env`, `.env.*`, `*.key`, `*.pem`, `*.p12`, `*.pfx`, `credentials*`. Set this field to override.
+
+**`retention`**: Controls automatic cleanup of old shadow-copy snapshots in `.cursor-guard-backup/`:
+- `"days"` (default): keep snapshots from the last N days (default **30**).
+- `"count"`: keep the N most recent snapshots (default 100).
+- `"size"`: keep total shadow-copy folder under N MB (default 500).
+
+**If no config file exists**, the agent operates in "protect everything" mode (backward compatible). Mention to the user that they can create `.cursor-guard.json` to narrow scope — see [references/cursor-guard.example.json](references/cursor-guard.example.json).
+
+When the target file of an edit **falls outside the protected scope**, the agent:
+- Still applies "Read before Write" (Hard Rule §2).
+- Skips the mandatory git snapshot / shadow copy step.
+- Notes `outside protection scope` in the status block.
+
+---
+
+## 1. Assess Risk (First)
+
+| Signal | Risk |
+|--------|------|
+| Multi-file edits, `delete_file`, terminal `rm`, or **Write** to existing file | **High** |
+| Single small edit (`StrReplace` with narrow scope), user explicitly asked | **Medium** |
+| Read-only explanation, no writes | **Low** |
+
+---
+
+## 2. Mandatory Pre-Write Backup Protocol (ENFORCED)
+
+> **This is not optional.** The agent MUST execute these steps before making
+> destructive or high-risk changes. Skipping is only allowed when the user
+> explicitly says "不用备份" / "skip backup".
+
+### 2a. If workspace IS a Git repo
+
+**Before any High-risk operation on a protected file:**
+
+```
+git add -A && git commit -m "guard: snapshot before ai edit" --no-verify
+```
+
+- Run this via Shell tool BEFORE the first Write / StrReplace / Delete call.
+- If `.cursor-guard.json` exists with `protect` patterns, the agent may scope the commit: `git add <protected-paths>` instead of `-A` to keep the snapshot focused.
+- If `git status` shows nothing to commit, that's fine — the existing HEAD is the rollback point.
+- Record the commit hash (short) and report it to the user.
+- Before committing, check staged files against `secrets_patterns` (§0). Exclude any matches and warn the user.
+
+**Before any Medium-risk operation:**
+
+- At minimum, run `git diff -- <target_file>` and `git status` so the user sees current state.
+- Recommend a snapshot commit; proceed without it only if the user confirms.
+
+### 2b. If workspace is NOT a Git repo
+
+**Before any High-risk operation, offer TWO options (pick one):**
+
+1. **Quick git init** (preferred):
+   ```
+   git init && git add -A && git commit -m "guard: initial snapshot" --no-verify
+   ```
+2. **Shadow copy** (fallback if user declines git):
+   - Copy the target file(s) to `.cursor-guard-backup/<timestamp>/` via Shell.
+   - Example:
+     ```powershell
+     $ts = Get-Date -Format 'yyyyMMdd_HHmmss'
+     New-Item -ItemType Directory -Force ".cursor-guard-backup/$ts"
+     Copy-Item "src/app.py" ".cursor-guard-backup/$ts/app.py"
+     ```
+   - Add `.cursor-guard-backup/` to `.gitignore` if git is later initialized.
+
+**If user declines BOTH:** document refusal in the status block (§6), state the file cannot be recovered if lost, and proceed only with explicit "我了解风险，继续" confirmation.
+
+### 2c. Multi-file batch operations
+
+When editing 3+ files in one task:
+
+1. Create the snapshot commit covering ALL files first.
+2. Apply changes file-by-file; if any step fails, offer to `git restore` all files back to the snapshot.
+3. After all edits succeed, offer a clean commit with a real message.
+
+---
+
+## 3. Protection Strategy During Edits
+
+**Before applying AI changes:**
+
+1. **Preview**: Show a clear **diff-style summary** (paths + intent). For substantial edits, prefer patch-sized chunks.
+2. **Destructive ops**: For deletes or large rewrites, **confirm explicitly** (one short question). Do not assume "cleanup" permission.
+3. **Workspace root**: State which directory is treated as project root; avoid touching paths outside it unless the user asked.
+4. **Read before Write**: The agent MUST Read a file's current content before using Write to overwrite it. This ensures the full original content is captured in conversation context as a last-resort recovery source.
+5. **Rename / Move**: Treat renames and moves as a delete + create. Snapshot the original path before proceeding; note both old and new paths in the status block so history can be traced.
+
+**After tool writes (agent wrote to disk directly):**
+
+- Tell the user: editor buffer may be stale → **`Revert File`** (Ctrl+Shift+P → "Revert File") or close & reopen tab.
+- Do **not** claim Timeline/Checkpoints will capture tool writes.
+
+---
+
+## 4. Backup Strategy (Priority)
+
+1. **Git local commits** — primary safety net. Short WIP commits before risky AI runs.
+2. **Shadow copy** (`.cursor-guard-backup/`) — fallback for non-git or when user wants extra insurance.
+3. **Auto-backup script** — see [references/auto-backup.ps1](references/auto-backup.ps1) for a PowerShell watcher that auto-commits on file change.
+4. **Editor habits** — Ctrl+S frequently; optional extensions are user-configured, mention only if asked.
+
+**Hard default:** Do NOT `git push` unless the user explicitly asks. Scope = **local only**.
+
+**Retention:** Shadow copies are auto-cleaned by `auto-backup.ps1` per the `retention` config (default: keep 30 days). For manual cleanup of the backup branch, see [references/recovery.md](references/recovery.md).
+
+---
+
+## 5. Recovery Strategy (Priority Order)
+
+1. **Git**: `git status` → `git diff` → `git restore` → `git reset` → `git reflog` — see [references/recovery.md](references/recovery.md).
+2. **Shadow copies**: Check `.cursor-guard-backup/` for timestamped copies.
+3. **Conversation context**: If the agent Read the file before overwriting, the original content is in this chat — offer to re-write it back.
+4. **Editor Local History / Timeline**: auxiliary, per-file; unreliable for tool-only disk writes.
+5. **Cursor Checkpoints**: auxiliary; tied to Agent UI; not a long-term backup.
+
+---
+
+## 6. Output to User (When This Skill Was Used)
+
+When you followed this skill's workflow, end with a short **status block**:
+
+```markdown
+**Cursor Guard — status**
+- **Risk**: low / medium / high
+- **Snapshot**: `<short-hash>` or `shadow copy at .cursor-guard-backup/<ts>/` or `none (user declined)`
+- **Done**: (e.g. snapshot committed / diff previewed / recovery completed)
+- **Next step**: (one concrete command or one UI action)
+- **Recovery ref**: `references/recovery.md` in this skill folder
+```
+
+Skip the block for unrelated turns.
+
+---
+
+## Hard Rules (Non-Negotiable)
+
+1. **MUST snapshot before high-risk ops** — git commit or shadow copy. No exceptions unless user explicitly declines.
+2. **MUST Read before Write** — never overwrite a file the agent hasn't read in the current turn.
+3. **Do not** treat Timeline/Checkpoints as the only or primary recovery path.
+4. **Do not** recommend Checkpoints as long-term or sole backup.
+5. **No automatic push** to remotes; local commits only unless user requests push.
+6. **Be honest** about limits: terminal side effects, binary files, and non-tracked paths are not fully reversible without prior commits.
+7. **Do not** run `git clean`, `reset --hard`, or other destructive Git commands unless the user clearly asked; always show what would be affected first.
+8. **Do not** delete files via the Delete tool without explicit per-file confirmation from the user.
+9. **Do not** modify or delete `.cursor-guard.json` unless the user explicitly asks — accidental config changes silently alter protection scope.
+10. **Use `--no-verify`** on all guard snapshot commits to bypass pre-commit hooks that could fail or modify files.
+11. **Concurrent agents**: if multiple Agent threads are active, warn the user to avoid simultaneous writes to the same file. Snapshots cannot prevent race conditions between parallel agents.
+
+---
+
+## Optional: Project Conventions
+
+- If the workspace has `.cursor-guard.json`, the agent MUST read and follow it (see §0).
+- If `.cursor-guard-backup/` folder exists, align shadow copy paths with it.
+- Template config: [references/cursor-guard.example.json](references/cursor-guard.example.json) — copy to workspace root and customize.
+
+---
+
+## Further Reading
+
+- Recovery commands: [references/recovery.md](references/recovery.md)
+- Auto-backup script: [references/auto-backup.ps1](references/auto-backup.ps1)
+- Config JSON Schema: [references/cursor-guard.schema.json](references/cursor-guard.schema.json)
+- Example config: [references/cursor-guard.example.json](references/cursor-guard.example.json)

package/package.json

@@ -0,0 +1,29 @@
+{
+    "name":  "cursor-guard",
+    "version":  "1.0.0",
+    "description":  "Protects code from accidental AI overwrite or deletion in Cursor IDE 鈥?mandatory pre-write snapshots, review-before-apply, local Git safety net, and deterministic recovery.",
+    "keywords":  [
+                     "cursor",
+                     "cursor-ide",
+                     "ai-safety",
+                     "code-protection",
+                     "git-backup",
+                     "snapshot",
+                     "recovery",
+                     "agent-skill"
+                 ],
+    "author":  "zhangqiang8vipp",
+    "license":  "MIT",
+    "repository":  {
+                       "type":  "git",
+                       "url":  "https://github.com/zhangqiang8vipp/cursor-guard.git"
+                   },
+    "homepage":  "https://github.com/zhangqiang8vipp/cursor-guard",
+    "files":  [
+                  "SKILL.md",
+                  "README.md",
+                  "LICENSE",
+                  "references/"
+              ],
+    "main":  "SKILL.md"
+}

package/references/auto-backup.ps1

@@ -0,0 +1,295 @@
+<#
+.SYNOPSIS
+    Auto-backup script for Cursor Guard.
+    Periodically snapshots protected files to a local Git branch using
+    plumbing commands — never switches branches or disturbs the main index.
+    Reads .cursor-guard.json for scope, secrets, and retention settings.
+
+.USAGE
+    # Run in a separate PowerShell window while working in Cursor:
+    .\auto-backup.ps1 -Path "D:\MyProject"
+
+    # Custom interval (default 60 seconds):
+    .\auto-backup.ps1 -Path "D:\MyProject" -IntervalSeconds 30
+
+    # Stop: Ctrl+C or close the PowerShell window.
+
+.NOTES
+    - Snapshots go to branch `cursor-guard/auto-backup` via plumbing commands.
+    - Never switches branches, never touches the main index.
+    - Does NOT push to any remote.
+    - Sensitive files matching secrets_patterns are auto-excluded.
+    - Shadow copies are cleaned per retention policy (default: keep 30 days).
+    - Log file: .cursor-guard-backup/backup.log
+    - IMPORTANT: Run this script in a SEPARATE PowerShell window, NOT inside
+      Cursor's integrated terminal. Cursor's terminal injects --trailer flags
+      into git commit commands, which corrupts plumbing calls like commit-tree.
+#>
+
+param(
+    [Parameter(Mandatory)]
+    [string]$Path,
+
+    [int]$IntervalSeconds = 0
+)
+
+$ErrorActionPreference = "Stop"
+$resolved = (Resolve-Path $Path).Path
+Set-Location $resolved
+
+# ── Paths ──────────────────────────────────────────────────────────
+$gitDir      = Join-Path $resolved ".git"
+$lockFile    = Join-Path $gitDir   "cursor-guard.lock"
+$guardIndex  = Join-Path $gitDir   "cursor-guard-index"
+$backupDir   = Join-Path $resolved ".cursor-guard-backup"
+$logFilePath = Join-Path $backupDir "backup.log"
+
+# ── Cleanup on exit ───────────────────────────────────────────────
+function Invoke-Cleanup {
+    $env:GIT_INDEX_FILE = $null
+    Remove-Item $guardIndex -Force -ErrorAction SilentlyContinue
+    Remove-Item $lockFile   -Force -ErrorAction SilentlyContinue
+}
+trap { Invoke-Cleanup; break }
+
+# ── Defaults ──────────────────────────────────────────────────────
+$protectPatterns  = @()
+$ignorePatterns   = @()
+$secretsPatterns  = @(".env", ".env.*", "*.key", "*.pem", "*.p12", "*.pfx", "credentials*")
+$retentionMode    = "days"
+$retentionDays    = 30
+$retentionMaxCnt  = 100
+$retentionMaxMB   = 500
+
+# ── Load .cursor-guard.json ──────────────────────────────────────
+$cfgPath = Join-Path $resolved ".cursor-guard.json"
+if (Test-Path $cfgPath) {
+    try {
+        $cfg = Get-Content $cfgPath -Raw | ConvertFrom-Json
+        if ($cfg.protect)                       { $protectPatterns = @($cfg.protect) }
+        if ($cfg.ignore)                        { $ignorePatterns  = @($cfg.ignore) }
+        if ($cfg.secrets_patterns)              { $secretsPatterns = @($cfg.secrets_patterns) }
+        if ($cfg.auto_backup_interval_seconds -and $IntervalSeconds -eq 0) {
+            $IntervalSeconds = $cfg.auto_backup_interval_seconds
+        }
+        if ($cfg.retention) {
+            if ($cfg.retention.mode)        { $retentionMode   = $cfg.retention.mode }
+            if ($cfg.retention.days)        { $retentionDays   = $cfg.retention.days }
+            if ($cfg.retention.max_count)   { $retentionMaxCnt = $cfg.retention.max_count }
+            if ($cfg.retention.max_size_mb) { $retentionMaxMB  = $cfg.retention.max_size_mb }
+        }
+        Write-Host "[guard] Config loaded  protect=$($protectPatterns.Count)  ignore=$($ignorePatterns.Count)  retention=$retentionMode" -ForegroundColor Cyan
+    }
+    catch {
+        Write-Host "[guard] WARNING: .cursor-guard.json parse error - using defaults." -ForegroundColor Yellow
+        Write-Host "  $_" -ForegroundColor Yellow
+    }
+}
+if ($IntervalSeconds -eq 0) { $IntervalSeconds = 60 }
+
+# ── Git repo check ───────────────────────────────────────────────
+if (-not (Test-Path $gitDir)) {
+    $ans = Read-Host "Directory is not a Git repo. Initialize? (y/n)"
+    if ($ans -eq 'y') {
+        git init
+        $gi = Join-Path $resolved ".gitignore"
+        $entry = ".cursor-guard-backup/"
+        if (Test-Path $gi) {
+            $content = Get-Content $gi -Raw
+            if ($content -notmatch [regex]::Escape($entry)) {
+                Add-Content $gi "`n$entry"
+            }
+        } else {
+            Set-Content $gi $entry
+        }
+        git add -A; git commit -m "guard: initial snapshot" --no-verify
+        Write-Host "[guard] Repo initialized with snapshot." -ForegroundColor Green
+    } else {
+        Write-Host "[guard] Git is required. Exiting." -ForegroundColor Red
+        exit 1
+    }
+}
+
+# ── Lock file (prevent multiple instances) ───────────────────────
+if (Test-Path $lockFile) {
+    Write-Host "[guard] ERROR: Lock file exists ($lockFile)." -ForegroundColor Red
+    Write-Host "  If no other instance is running, delete it and retry." -ForegroundColor Red
+    exit 1
+}
+Set-Content $lockFile "pid=$PID`nstarted=$(Get-Date -Format 'o')"
+
+# ── Backup branch ───────────────────────────────────────────────
+$branch    = "cursor-guard/auto-backup"
+$branchRef = "refs/heads/$branch"
+if (-not (git rev-parse --verify $branchRef 2>$null)) {
+    git branch $branch HEAD 2>$null
+    Write-Host "[guard] Created branch: $branch" -ForegroundColor Green
+}
+
+# ── Log directory & helpers ──────────────────────────────────────
+if (-not (Test-Path $backupDir)) { New-Item -ItemType Directory -Force $backupDir | Out-Null }
+
+function Write-Log {
+    param([string]$Msg, [ConsoleColor]$Color = "Green")
+    $line = "$(Get-Date -Format 'yyyy-MM-dd HH:mm:ss')  $Msg"
+    Add-Content -Path $logFilePath -Value $line -ErrorAction SilentlyContinue
+    Write-Host "[guard] $line" -ForegroundColor $Color
+}
+
+# ── Secrets filter ───────────────────────────────────────────────
+function Remove-SecretsFromIndex {
+    $files = git ls-files --cached 2>$null
+    if (-not $files) { return }
+    $excluded = @()
+    foreach ($f in $files) {
+        $leaf = Split-Path $f -Leaf
+        foreach ($pat in $secretsPatterns) {
+            $re = '^' + [regex]::Escape($pat).Replace('\*','.*').Replace('\?','.') + '$'
+            if ($f -match $re -or $leaf -match $re) {
+                git rm --cached --ignore-unmatch -q -- $f 2>$null
+                $excluded += $f
+                break
+            }
+        }
+    }
+    if ($excluded.Count -gt 0) {
+        Write-Log "Secrets auto-excluded: $($excluded -join ', ')" Yellow
+    }
+}
+
+# ── Retention cleanup ────────────────────────────────────────────
+function Invoke-RetentionCleanup {
+    # Clean shadow-copy directories named yyyyMMdd_HHmmss
+    $dirs = Get-ChildItem $backupDir -Directory -ErrorAction SilentlyContinue |
+            Where-Object { $_.Name -match '^\d{8}_\d{6}$' } |
+            Sort-Object Name -Descending
+    if ($dirs -and $dirs.Count -gt 0) {
+        $removed = 0
+        switch ($retentionMode) {
+            "days" {
+                $cutoff = (Get-Date).AddDays(-$retentionDays)
+                foreach ($d in $dirs) {
+                    try {
+                        $dt = [datetime]::ParseExact($d.Name, "yyyyMMdd_HHmmss", $null)
+                        if ($dt -lt $cutoff) { Remove-Item $d.FullName -Recurse -Force; $removed++ }
+                    } catch {}
+                }
+            }
+            "count" {
+                if ($dirs.Count -gt $retentionMaxCnt) {
+                    $dirs | Select-Object -Skip $retentionMaxCnt |
+                        ForEach-Object { Remove-Item $_.FullName -Recurse -Force; $removed++ }
+                }
+            }
+            "size" {
+                $totalMB = (Get-ChildItem $backupDir -Recurse -File -ErrorAction SilentlyContinue |
+                            Measure-Object Length -Sum).Sum / 1MB
+                $oldest = $dirs | Sort-Object Name
+                foreach ($d in $oldest) {
+                    if ($totalMB -le $retentionMaxMB) { break }
+                    $sz = (Get-ChildItem $d.FullName -Recurse -File |
+                           Measure-Object Length -Sum).Sum / 1MB
+                    Remove-Item $d.FullName -Recurse -Force
+                    $totalMB -= $sz; $removed++
+                }
+            }
+        }
+        if ($removed -gt 0) {
+            Write-Log "Retention ($retentionMode): cleaned $removed old snapshot(s)" DarkGray
+        }
+    }
+
+    # Disk-space warning
+    try {
+        $letter = (Split-Path $resolved -Qualifier) -replace ':$',''
+        $drv    = Get-PSDrive $letter
+        $freeGB = [math]::Round($drv.Free / 1GB, 1)
+        if     ($freeGB -lt 1) { Write-Log "WARNING: disk critically low - ${freeGB} GB free" Red }
+        elseif ($freeGB -lt 5) { Write-Log "Disk note: ${freeGB} GB free" Yellow }
+    } catch {}
+}
+
+# ── Banner ───────────────────────────────────────────────────────
+Write-Host ""
+Write-Host "[guard] Watching '$resolved' every ${IntervalSeconds}s  (Ctrl+C to stop)" -ForegroundColor Cyan
+Write-Host "[guard] Branch: $branch  |  Retention: $retentionMode ($retentionDays days / $retentionMaxCnt count / ${retentionMaxMB} MB)" -ForegroundColor Cyan
+Write-Host "[guard] Log: $logFilePath" -ForegroundColor Cyan
+Write-Host ""
+
+# ── Main loop ────────────────────────────────────────────────────
+$cycle = 0
+try {
+    while ($true) {
+        Start-Sleep -Seconds $IntervalSeconds
+        $cycle++
+
+        $dirty = git status --porcelain 2>$null
+        if (-not $dirty) { continue }
+
+        try {
+            # Use a temporary index file — the main index and branch are never touched
+            $env:GIT_INDEX_FILE = $guardIndex
+
+            # Seed temp index from the current backup-branch tree
+            $parentHash = git rev-parse --verify $branchRef 2>$null
+            if ($parentHash) { git read-tree $branchRef 2>$null }
+
+            # Stage protected files from the working tree into temp index
+            if ($protectPatterns.Count -gt 0) {
+                foreach ($p in $protectPatterns) { git add -- $p 2>$null }
+            } else {
+                git add -A 2>$null
+            }
+            foreach ($ig in $ignorePatterns) {
+                git rm --cached --ignore-unmatch -rq -- $ig 2>$null
+            }
+
+            Remove-SecretsFromIndex
+
+            # Build tree object and compare with parent
+            $newTree    = git write-tree
+            $parentTree = if ($parentHash) { git rev-parse "${branchRef}^{tree}" 2>$null } else { $null }
+
+            if ($newTree -eq $parentTree) {
+                Write-Host "[guard] $(Get-Date -Format 'HH:mm:ss') tree unchanged, skipped." -ForegroundColor DarkGray
+                continue
+            }
+
+            # Create commit via plumbing — no checkout, no hooks, no branch switch
+            $ts  = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
+            $msg = "guard: auto-backup $ts"
+            $commitHash = if ($parentHash) {
+                git commit-tree $newTree -p $parentHash -m $msg
+            } else {
+                git commit-tree $newTree -m $msg
+            }
+            git update-ref $branchRef $commitHash
+
+            if (-not $commitHash) {
+                Write-Log "ERROR: commit-tree failed, snapshot skipped" Red
+                continue
+            }
+
+            $short = $commitHash.Substring(0, 7)
+            if ($parentTree) {
+                $diff  = git diff-tree --no-commit-id --name-only -r $parentTree $newTree 2>$null
+                $count = if ($diff) { @($diff).Count } else { 0 }
+            } else {
+                $all   = git ls-tree --name-only -r $newTree 2>$null
+                $count = if ($all) { @($all).Count } else { 0 }
+            }
+            Write-Log "Snapshot $short ($count files)"
+        }
+        finally {
+            $env:GIT_INDEX_FILE = $null
+            Remove-Item $guardIndex -Force -ErrorAction SilentlyContinue
+        }
+
+        # Periodic retention cleanup every 10 cycles
+        if ($cycle % 10 -eq 0) { Invoke-RetentionCleanup }
+    }
+}
+finally {
+    Invoke-Cleanup
+    Write-Host "`n[guard] Stopped." -ForegroundColor Cyan
+}

package/references/cursor-guard.example.json

@@ -0,0 +1,45 @@
+{
+  "_comment_schema": "Optional: add \"$schema\" pointing to cursor-guard.schema.json for IDE validation. Adjust the path to where you placed the schema file.",
+
+  "_comment_mode": "Two modes: whitelist (set 'protect') or blacklist (set 'ignore'). If both are set, 'protect' is checked first, then 'ignore' excludes from it.",
+
+  "protect": [
+    "src/**",
+    "lib/**",
+    "*.config.js",
+    "*.config.ts",
+    "package.json",
+    "tsconfig.json",
+    ".env.example"
+  ],
+
+  "ignore": [
+    "node_modules/**",
+    "dist/**",
+    "build/**",
+    ".next/**",
+    "coverage/**",
+    "*.log",
+    "*.tmp",
+    ".cursor-guard-backup/**"
+  ],
+
+  "backup_strategy": "git",
+  "auto_backup_interval_seconds": 60,
+
+  "_comment_secrets": "Glob patterns for sensitive files — auto-excluded from backup even if matched by 'protect'. Built-in defaults: .env, .env.*, *.key, *.pem, *.p12, *.pfx, credentials*",
+  "secrets_patterns": [
+    ".env",
+    ".env.*",
+    "*.key",
+    "*.pem"
+  ],
+
+  "_comment_retention": "Retention policy for shadow copies. mode: 'days' (default, keep N days), 'count' (keep N newest snapshots), 'size' (keep total under N MB).",
+  "retention": {
+    "mode": "days",
+    "days": 30,
+    "max_count": 100,
+    "max_size_mb": 500
+  }
+}

package/references/cursor-guard.schema.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Cursor Guard Configuration",
+  "description": "Controls which files are protected, backup strategy, secrets filtering, and retention policy for the cursor-guard skill.",
+  "type": "object",
+  "properties": {
+    "protect": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Whitelist glob patterns relative to workspace root. Only matching files get backup protection. If empty or missing, all files are protected."
+    },
+    "ignore": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Blacklist glob patterns. Matching files are excluded even if they match 'protect'. Applied on top of .gitignore."
+    },
+    "backup_strategy": {
+      "type": "string",
+      "enum": ["git", "shadow", "both"],
+      "default": "git",
+      "description": "Primary backup method: 'git' (local commits), 'shadow' (.cursor-guard-backup/ copies), or 'both'."
+    },
+    "auto_backup_interval_seconds": {
+      "type": "integer",
+      "minimum": 5,
+      "default": 60,
+      "description": "Interval in seconds for auto-backup.ps1 to check for changes."
+    },
+    "secrets_patterns": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Glob patterns for sensitive files auto-excluded from backups. Built-in defaults: .env, .env.*, *.key, *.pem, *.p12, *.pfx, credentials*"
+    },
+    "retention": {
+      "type": "object",
+      "description": "Controls automatic cleanup of old shadow-copy snapshots.",
+      "properties": {
+        "mode": {
+          "type": "string",
+          "enum": ["days", "count", "size"],
+          "default": "days",
+          "description": "'days': keep snapshots from the last N days. 'count': keep N newest snapshots. 'size': keep total size under N MB."
+        },
+        "days": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 30,
+          "description": "Number of days to retain snapshots (when mode='days')."
+        },
+        "max_count": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 100,
+          "description": "Maximum number of snapshots to keep (when mode='count')."
+        },
+        "max_size_mb": {
+          "type": "integer",
+          "minimum": 10,
+          "default": 500,
+          "description": "Maximum total size in MB for shadow copies (when mode='size')."
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": true
+}

package/references/recovery.md

@@ -0,0 +1,177 @@
+# Recovery Command Templates
+
+Replace `<path>` / `<file>` with real paths. Run from repository root. **Review output before destructive commands.**
+
+---
+
+## Inspect current state
+
+```bash
+git status
+git diff
+git log --oneline -10
+```
+
+## Recent commits (compact)
+
+```bash
+git log --oneline -20 --decorate
+```
+
+## Restore one file to last commit (discard working tree changes)
+
+```bash
+git restore --source=HEAD -- <path/to/file>
+```
+
+## Restore one file from a specific commit
+
+```bash
+git restore --source=<commit> -- <path/to/file>
+```
+
+> Avoid shell redirects (`git show <commit>:file > file`) on Windows — they can corrupt encoding. Prefer `git restore --source`.
+
+## Undo uncommitted changes (entire repo) — **destructive**
+
+```bash
+git restore .
+git clean -fd   # removes untracked files/dirs — DANGEROUS
+```
+
+Only suggest `git clean -fd` if the user explicitly wants untracked removal; warn about data loss.
+
+## Recover "lost" commits / after reset
+
+```bash
+git reflog
+# find the commit hash, then:
+git branch recover-branch <hash>
+# or (destructive — discards uncommitted work):
+git reset --hard <hash>
+```
+
+## Restore deleted file from HEAD (if it was committed)
+
+```bash
+git restore --source=HEAD -- <path/to/deleted/file>
+```
+
+## Stash (quick shelter before experiments)
+
+```bash
+git stash push -m "wip before experiment"
+git stash list
+git stash pop
+```
+
+## Recover from auto-backup branch
+
+The `auto-backup.ps1` script stores periodic snapshots on a dedicated branch via plumbing commands:
+
+```bash
+# List recent auto-backup snapshots
+git log cursor-guard/auto-backup --oneline -20
+
+# Restore a file from the latest auto-backup
+git restore --source=cursor-guard/auto-backup -- <path/to/file>
+
+# Restore from a specific auto-backup snapshot
+git restore --source=<commit-hash> -- <path/to/file>
+
+# Diff your working copy against the auto-backup version
+git diff cursor-guard/auto-backup -- <path/to/file>
+```
+
+## If not a Git repo yet
+
+```bash
+git init
+git add -A
+git commit -m "guard: initial snapshot" --no-verify
+```
+
+This does **not** recover past work from before `init`.
+
+---
+
+## Shadow Copy Recovery (Non-Git Fallback)
+
+If `.cursor-guard-backup/` exists, find snapshots:
+
+```powershell
+# List all backup timestamps
+Get-ChildItem .cursor-guard-backup/ -Directory | Sort-Object Name -Descending
+
+# Restore a specific file from a timestamp
+Copy-Item ".cursor-guard-backup/<timestamp>/<filename>" "<original-path>"
+```
+
+---
+
+## Windows-Specific Notes
+
+- **Long paths**: If you get path errors, enable long path support:
+  ```powershell
+  git config --local core.longpaths true   # use --global for system-wide
+  ```
+- **Line endings**: Git may show spurious diffs due to CRLF/LF. Check with:
+  ```bash
+  git diff --check
+  ```
+  Fix with `git config --local core.autocrlf true` if desired (or `--global` for system-wide).
+- **PowerShell quoting**: Use single quotes for paths with spaces in PowerShell:
+  ```powershell
+  git restore --source=HEAD -- 'src/my file.py'
+  ```
+- **File locks**: If a file is locked by another process (e.g. Cursor still has it open), `git restore` may fail. Close the tab first or use:
+  ```powershell
+  # Force close file handle (admin required, use with caution)
+  # Prefer: just close the file tab in Cursor, then retry git restore.
+  ```
+
+---
+
+## Non-Git Auxiliary Recovery
+
+- **VS Code / Cursor Timeline (Local History)**: per-file; access via right-click file tab → "Open Timeline". May miss tool-only writes (Write/StrReplace via agent).
+- **Checkpoints**: inside Agent thread UI only. Not guaranteed for all edit paths. Not long-term storage.
+- **Conversation context**: if the agent used the Read tool on a file before overwriting it, the original content exists in the chat history. Ask the agent to re-write the original content back.
+- **Recycle Bin (Windows)**: only catches files deleted via Explorer, NOT via `rm` / `Remove-Item` / agent Delete tool.
+
+---
+
+## Backup Cleanup
+
+### Shadow copies
+
+```powershell
+# List all shadow copy snapshots (newest first)
+Get-ChildItem .cursor-guard-backup/ -Directory | Sort-Object Name -Descending
+
+# Delete snapshots older than 30 days
+$cutoff = (Get-Date).AddDays(-30)
+Get-ChildItem .cursor-guard-backup/ -Directory | Where-Object {
+    try { [datetime]::ParseExact($_.Name, "yyyyMMdd_HHmmss", $null) -lt $cutoff } catch { $false }
+} | Remove-Item -Recurse -Force
+```
+
+### Auto-backup branch
+
+```bash
+# View auto-backup history
+git log cursor-guard/auto-backup --oneline -30
+
+# Delete the branch entirely (script will recreate it on next run)
+git branch -D cursor-guard/auto-backup
+
+# Reclaim disk space after removing old branches
+git gc --prune=now
+```
+
+### Log file
+
+```powershell
+# View recent backup log entries
+Get-Content .cursor-guard-backup/backup.log -Tail 30
+```