cursor-guard 1.3.2 → 1.4.0

package/SKILL.md

@@ -20,6 +20,7 @@ Use this skill when any of the following appear:
 - **Parallel context**: Multiple repos or branches; unclear which folder is the workspace root.
 - **Recovery asks**: e.g. "改不回来", "丢版本", "回滚", "reflog", "误删", or English equivalents.
 - **Time/version recovery**: e.g. "恢复到5分钟前", "恢复到前3个版本", "回到上一个版本", "restore to 10 minutes ago", "go back 2 versions", "恢复到下午3点的状态".
+- **Health check**: e.g. "guard doctor", "检查备份配置", "自检", "诊断guard", "check guard setup". Run `guard-doctor.ps1` and report results.
 
 If none of the above, do not expand scope; answer normally.
 
@@ -100,19 +101,22 @@ When the target file of an edit **falls outside the protected scope**, the agent
 Use a **temporary index and dedicated ref** so the user's staged/unstaged state is never touched:
 
 ```bash
+GIT_DIR=$(git rev-parse --git-dir)
+GUARD_IDX="$GIT_DIR/guard-snapshot-index"
+
 # 1. Create temp index from HEAD
-GIT_INDEX_FILE=.git/guard-snapshot-index git read-tree HEAD
+GIT_INDEX_FILE="$GUARD_IDX" git read-tree HEAD
 
 # 2. Stage working-tree files into temp index
-GIT_INDEX_FILE=.git/guard-snapshot-index git add -A
+GIT_INDEX_FILE="$GUARD_IDX" git add -A
 
 # 3. Write tree and create commit on a guard ref (not on the user's branch)
-TREE=$(GIT_INDEX_FILE=.git/guard-snapshot-index git write-tree)
-COMMIT=$(git commit-tree $TREE -p HEAD -m "guard: snapshot before ai edit")
-git update-ref refs/guard/snapshot $COMMIT
+TREE=$(GIT_INDEX_FILE="$GUARD_IDX" git write-tree)
+COMMIT=$(git commit-tree "$TREE" -p HEAD -m "guard: snapshot before ai edit")
+git update-ref refs/guard/snapshot "$COMMIT"
 
 # 4. Cleanup
-rm .git/guard-snapshot-index
+rm -f "$GUARD_IDX"
 ```
 
 **PowerShell equivalent** (for agent Shell calls):
@@ -359,9 +363,12 @@ Then jump to Step 5.
 
 Use the same temp-index plumbing as §2a to avoid polluting the user's staging area:
 
-**Git repo (preferred):**
+**Git repo (preferred) — timestamped ref stack:**
+
+Each pre-restore snapshot writes to a unique ref `refs/guard/pre-restore/<yyyyMMdd_HHmmss>` so consecutive restores never overwrite each other:
 
 ```powershell
+$ts = Get-Date -Format 'yyyyMMdd_HHmmss'
 $guardIdx = Join-Path (git rev-parse --git-dir) "guard-pre-restore-index"
 $env:GIT_INDEX_FILE = $guardIdx
 
@@ -378,10 +385,16 @@ $env:GIT_INDEX_FILE = $null
 Remove-Item $guardIdx -Force -ErrorAction SilentlyContinue
 
 $commit = git commit-tree $tree -p HEAD -m "guard: preserve current before restore to <target>"
+git update-ref "refs/guard/pre-restore/$ts" $commit
+```
+
+Record the short hash and the ref path. Also update `refs/guard/pre-restore` as an alias pointing to the latest:
+
+```powershell
 git update-ref refs/guard/pre-restore $commit
 ```
 
-Record the short hash and the ref `refs/guard/pre-restore`.
+To list all pre-restore snapshots: `git for-each-ref refs/guard/pre-restore/ --sort=-creatordate --format="%(refname:short) %(creatordate:short) %(objectname:short)"`
 
 **Non-Git fallback (shadow copy):**
 
@@ -404,12 +417,14 @@ If the snapshot fails (e.g. disk full, permission error):
 Before executing restore, tell the user:
 ```
 在恢复前，我已保留当前版本：
-- 备份引用: refs/guard/pre-restore (abc1234)
-- 恢复方式: git restore --source=refs/guard/pre-restore -- <file>
+- 备份引用: refs/guard/pre-restore/20260321_163005 (abc1234)
+- 恢复方式: git restore --source=refs/guard/pre-restore/20260321_163005 -- <file>
+- 历史栈: git for-each-ref refs/guard/pre-restore/ --sort=-creatordate
 
 Current version preserved before restore:
-- Backup ref: refs/guard/pre-restore (abc1234)
-- To undo: git restore --source=refs/guard/pre-restore -- <file>
+- Backup ref: refs/guard/pre-restore/20260321_163005 (abc1234)
+- To undo: git restore --source=refs/guard/pre-restore/20260321_163005 -- <file>
+- History: git for-each-ref refs/guard/pre-restore/ --sort=-creatordate
 ```
 
 ### Step 5: Execute Recovery
@@ -451,11 +466,12 @@ After restoring, always:
 
 ```markdown
 **Cursor Guard — restore status**
-- **Pre-restore backup**: `refs/guard/pre-restore` (`<short-hash>`) or `shadow copy at .cursor-guard-backup/pre-restore-<ts>/` or `skipped (user opted out)` or `skipped (no changes)`
+- **Pre-restore backup**: `refs/guard/pre-restore/<ts>` (`<short-hash>`) or `shadow copy at .cursor-guard-backup/pre-restore-<ts>/` or `skipped (user opted out)` or `skipped (no changes)`
 - **Restored to**: `<target-hash>` / `<target description>`
 - **Scope**: single file `<path>` / N files / entire project
 - **Result**: success / failed
-- **To undo restore**: `git restore --source=refs/guard/pre-restore -- <file>`
+- **To undo restore**: `git restore --source=refs/guard/pre-restore/<ts> -- <file>`
+- **All pre-restore snapshots**: `git for-each-ref refs/guard/pre-restore/ --sort=-creatordate`
 ```
 
 ---
@@ -511,3 +527,4 @@ Skip the block for unrelated turns.
 - Example config: [references/cursor-guard.example.json](references/cursor-guard.example.json)
 - Config field reference (EN): [references/config-reference.md](references/config-reference.md)
 - 配置参数说明（中文）: [references/config-reference.zh-CN.md](references/config-reference.zh-CN.md)
+- Health check: [references/guard-doctor.ps1](references/guard-doctor.ps1) — run `.\guard-doctor.ps1 -Path .` to verify setup

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-guard",
-  "version": "1.3.2",
+  "version": "1.4.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. | 保护代码免受 Cursor AI 代理意外覆写或删除——强制写前快照、预览再执行、本地 Git 安全网、确定性恢复。",
   "keywords": [
     "cursor",

package/references/auto-backup.ps1

@@ -37,18 +37,27 @@ $ErrorActionPreference = "Stop"
 $resolved = (Resolve-Path $Path).Path
 Set-Location $resolved
 
-# ── Paths (worktree-safe: uses git rev-parse instead of hard-coding .git) ──
-$gitDir      = (git rev-parse --git-dir 2>$null)
-if (-not $gitDir) {
-    $gitDir = Join-Path $resolved ".git"
-} else {
-    $gitDir = (Resolve-Path $gitDir -ErrorAction SilentlyContinue).Path
-    if (-not $gitDir) { $gitDir = Join-Path $resolved ".git" }
+# ── Git availability check ────────────────────────────────────────
+$hasGit = $false
+$gitDir = $null
+$isRepo = $false
+if (Get-Command git -ErrorAction SilentlyContinue) {
+    $hasGit = $true
+    $isRepo = (git rev-parse --is-inside-work-tree 2>$null) -eq "true"
+    if ($isRepo) {
+        $gitDir = (git rev-parse --git-dir 2>$null)
+        if ($gitDir) {
+            $gitDir = (Resolve-Path $gitDir -ErrorAction SilentlyContinue).Path
+        }
+        if (-not $gitDir) { $gitDir = Join-Path $resolved ".git" }
+    }
 }
-$lockFile    = Join-Path $gitDir "cursor-guard.lock"
-$guardIndex  = Join-Path $gitDir "cursor-guard-index"
+
+# ── Paths ─────────────────────────────────────────────────────────
 $backupDir   = Join-Path $resolved ".cursor-guard-backup"
 $logFilePath = Join-Path $backupDir "backup.log"
+$lockFile    = if ($gitDir) { Join-Path $gitDir "cursor-guard.lock" } else { Join-Path $backupDir "cursor-guard.lock" }
+$guardIndex  = if ($gitDir) { Join-Path $gitDir "cursor-guard-index" } else { $null }
 
 # ── Cleanup on exit ───────────────────────────────────────────────
 function Invoke-Cleanup {
@@ -67,6 +76,10 @@ $retentionMode    = "days"
 $retentionDays    = 30
 $retentionMaxCnt  = 100
 $retentionMaxMB   = 500
+$gitRetEnabled    = $false
+$gitRetMode       = "count"
+$gitRetDays       = 30
+$gitRetMaxCnt     = 200
 
 # ── Load .cursor-guard.json ──────────────────────────────────────
 $cfgPath = Join-Path $resolved ".cursor-guard.json"
@@ -86,7 +99,13 @@ if (Test-Path $cfgPath) {
             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
+        if ($cfg.git_retention) {
+            if ($cfg.git_retention.enabled -eq $true)  { $gitRetEnabled = $true }
+            if ($cfg.git_retention.mode)               { $gitRetMode   = $cfg.git_retention.mode }
+            if ($cfg.git_retention.days)               { $gitRetDays   = $cfg.git_retention.days }
+            if ($cfg.git_retention.max_count)           { $gitRetMaxCnt = $cfg.git_retention.max_count }
+        }
+        Write-Host "[guard] Config loaded  protect=$($protectPatterns.Count)  ignore=$($ignorePatterns.Count)  retention=$retentionMode  git_retention=$(if($gitRetEnabled){'on'}else{'off'})" -ForegroundColor Cyan
     }
     catch {
         Write-Host "[guard] WARNING: .cursor-guard.json parse error - using defaults." -ForegroundColor Yellow
@@ -95,12 +114,21 @@ if (Test-Path $cfgPath) {
 }
 if ($IntervalSeconds -eq 0) { $IntervalSeconds = 60 }
 
-# ── Git repo check ───────────────────────────────────────────────
-$isRepo = git rev-parse --is-inside-work-tree 2>$null
-if ($isRepo -ne "true") {
+# ── Git repo check (only required for git/both strategy) ─────────
+$needsGit = ($backupStrategy -eq "git" -or $backupStrategy -eq "both")
+if ($needsGit -and -not $isRepo) {
+    if (-not $hasGit) {
+        Write-Host "[guard] ERROR: backup_strategy='$backupStrategy' requires Git, but git is not installed." -ForegroundColor Red
+        Write-Host "  Either install Git or set backup_strategy to 'shadow' in .cursor-guard.json." -ForegroundColor Yellow
+        exit 1
+    }
     $ans = Read-Host "Directory is not a Git repo. Initialize? (y/n)"
     if ($ans -eq 'y') {
         git init
+        $isRepo = $true
+        $gitDir = (Resolve-Path (git rev-parse --git-dir)).Path
+        $lockFile   = Join-Path $gitDir "cursor-guard.lock"
+        $guardIndex = Join-Path $gitDir "cursor-guard-index"
         $gi = Join-Path $resolved ".gitignore"
         $entry = ".cursor-guard-backup/"
         if (Test-Path $gi) {
@@ -114,10 +142,16 @@ if ($isRepo -ne "true") {
         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
+        Write-Host "[guard] Git is required for '$backupStrategy' strategy. Exiting." -ForegroundColor Red
         exit 1
     }
 }
+if (-not $isRepo -and $backupStrategy -eq "shadow") {
+    Write-Host "[guard] Non-Git directory detected. Running in shadow-only mode." -ForegroundColor Cyan
+}
+
+# ── Ensure backup dir exists ──────────────────────────────────────
+if (-not (Test-Path $backupDir)) { New-Item -ItemType Directory -Force $backupDir | Out-Null }
 
 # ── Lock file (prevent multiple instances) ───────────────────────
 if (Test-Path $lockFile) {
@@ -127,30 +161,30 @@ if (Test-Path $lockFile) {
 }
 Set-Content $lockFile "pid=$PID`nstarted=$(Get-Date -Format 'o')"
 
-# ── Backup branch ───────────────────────────────────────────────
+# ── Git-specific setup (skip entirely for shadow-only) ───────────
 $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
-}
+if ($isRepo) {
+    if (-not (git rev-parse --verify $branchRef 2>$null)) {
+        git branch $branch HEAD 2>$null
+        Write-Host "[guard] Created branch: $branch" -ForegroundColor Green
+    }
 
-# ── Ensure .cursor-guard-backup/ is git-ignored ─────────────────
-$excludeFile = Join-Path $gitDir "info/exclude"
-$excludeDir  = Split-Path $excludeFile
-if (-not (Test-Path $excludeDir)) { New-Item -ItemType Directory -Force $excludeDir | Out-Null }
-$excludeEntry = ".cursor-guard-backup/"
-if (Test-Path $excludeFile) {
-    $content = Get-Content $excludeFile -Raw -ErrorAction SilentlyContinue
-    if (-not $content -or $content -notmatch [regex]::Escape($excludeEntry)) {
-        Add-Content $excludeFile "`n$excludeEntry"
+    $excludeFile = Join-Path $gitDir "info/exclude"
+    $excludeDir  = Split-Path $excludeFile
+    if (-not (Test-Path $excludeDir)) { New-Item -ItemType Directory -Force $excludeDir | Out-Null }
+    $excludeEntry = ".cursor-guard-backup/"
+    if (Test-Path $excludeFile) {
+        $content = Get-Content $excludeFile -Raw -ErrorAction SilentlyContinue
+        if (-not $content -or $content -notmatch [regex]::Escape($excludeEntry)) {
+            Add-Content $excludeFile "`n$excludeEntry"
+        }
+    } else {
+        Set-Content $excludeFile $excludeEntry
     }
-} else {
-    Set-Content $excludeFile $excludeEntry
 }
 
-# ── Log directory & helpers ──────────────────────────────────────
-if (-not (Test-Path $backupDir)) { New-Item -ItemType Directory -Force $backupDir | Out-Null }
+# ── Log & helpers ────────────────────────────────────────────────
 
 function Write-Log {
     param([string]$Msg, [ConsoleColor]$Color = "Green")
@@ -232,30 +266,93 @@ function Invoke-RetentionCleanup {
     } catch {}
 }
 
+# ── Git branch retention ─────────────────────────────────────────
+function Invoke-GitRetention {
+    if (-not $gitRetEnabled -or -not $isRepo) { return }
+    $commits = git rev-list $branchRef 2>$null
+    if (-not $commits) { return }
+    $commitList = @($commits)
+    $total = $commitList.Count
+
+    $keepCount = $total
+    switch ($gitRetMode) {
+        "count" {
+            $keepCount = [math]::Min($total, $gitRetMaxCnt)
+        }
+        "days" {
+            $cutoff = (Get-Date).AddDays(-$gitRetDays).ToString("yyyy-MM-ddTHH:mm:ss")
+            $keepCommits = git rev-list $branchRef --after=$cutoff 2>$null
+            $keepCount = if ($keepCommits) { @($keepCommits).Count } else { 0 }
+            $keepCount = [math]::Max($keepCount, 10)
+        }
+    }
+
+    if ($keepCount -ge $total) { return }
+
+    $newTip = $commitList[$keepCount - 1]
+    $orphanTree = git rev-parse "${newTip}^{tree}" 2>$null
+    if (-not $orphanTree) { return }
+
+    $orphanCommit = git commit-tree $orphanTree -m "guard: retention truncation point"
+    if (-not $orphanCommit) { return }
+
+    $keptCommits = $commitList[0..($keepCount - 2)]
+    $grafts = @()
+    foreach ($i in 0..($keptCommits.Count - 1)) {
+        if ($i -lt ($keptCommits.Count - 1)) {
+            $grafts += "$($keptCommits[$i]) $($commitList[$i + 1])"
+        } else {
+            $grafts += "$($keptCommits[$i]) $orphanCommit"
+        }
+    }
+
+    $infoDir = Join-Path $gitDir "info"
+    if (-not (Test-Path $infoDir)) { New-Item -ItemType Directory -Force $infoDir | Out-Null }
+    $graftsFile = Join-Path $infoDir "grafts"
+    $grafts | Set-Content $graftsFile
+    git filter-branch -f --tag-name-filter cat -- $branchRef 2>$null
+    Remove-Item $graftsFile -Force -ErrorAction SilentlyContinue
+
+    $pruned = $total - $keepCount
+    Write-Log "Git retention ($gitRetMode): pruned $pruned old commit(s), kept $keepCount" DarkGray
+}
+
 # ── Shadow copy helper ────────────────────────────────────────────
 function Invoke-ShadowCopy {
     $ts = Get-Date -Format 'yyyyMMdd_HHmmss'
     $snapDir = Join-Path $backupDir $ts
     New-Item -ItemType Directory -Force $snapDir | Out-Null
 
+    $allFiles = Get-ChildItem $resolved -Recurse -File -ErrorAction SilentlyContinue |
+                Where-Object { $_.FullName -notmatch '[\\/](\.git|\.cursor-guard-backup|node_modules)[\\/]' }
+
     $files = if ($protectPatterns.Count -gt 0) {
-        $protectPatterns | ForEach-Object { Get-ChildItem $resolved -Recurse -File -Filter $_ -ErrorAction SilentlyContinue }
+        $allFiles | Where-Object {
+            $rel = $_.FullName.Substring($resolved.Length + 1) -replace '\\','/'
+            $matched = $false
+            foreach ($pat in $protectPatterns) {
+                $p = $pat -replace '\\','/'
+                if ($rel -like $p -or (Split-Path $rel -Leaf) -like $p) { $matched = $true; break }
+            }
+            $matched
+        }
     } else {
-        Get-ChildItem $resolved -Recurse -File -ErrorAction SilentlyContinue |
-            Where-Object { $_.FullName -notmatch '[\\/](\.git|\.cursor-guard-backup|node_modules)[\\/]' }
+        $allFiles
     }
 
     $copied = 0
     foreach ($f in $files) {
-        $rel = $f.FullName.Substring($resolved.Length + 1)
+        $rel = $f.FullName.Substring($resolved.Length + 1) -replace '\\','/'
+        $leaf = $f.Name
         $skip = $false
         foreach ($ig in $ignorePatterns) {
-            $re = '^' + [regex]::Escape($ig).Replace('\*\*','.*').Replace('\*','[^/\\]*').Replace('\?','.') + '$'
-            if ($rel -match $re) { $skip = $true; break }
+            $p = $ig -replace '\\','/'
+            if ($rel -like $p -or $leaf -like $p) { $skip = $true; break }
         }
-        foreach ($pat in $secretsPatterns) {
-            $re = '^' + [regex]::Escape($pat).Replace('\*','.*').Replace('\?','.') + '$'
-            if ($rel -match $re -or $f.Name -match $re) { $skip = $true; break }
+        if (-not $skip) {
+            foreach ($pat in $secretsPatterns) {
+                if ($rel -like $pat -or $leaf -like $pat) { $skip = $true; break }
+            }
         }
         if ($skip) { continue }
         $dest = Join-Path $snapDir $rel
@@ -286,8 +383,28 @@ try {
         Start-Sleep -Seconds $IntervalSeconds
         $cycle++
 
-        $dirty = git status --porcelain 2>$null
-        if (-not $dirty) { continue }
+        # ── Detect changes ────────────────────────────────────────
+        $hasChanges = $false
+        if ($isRepo) {
+            $dirty = git status --porcelain 2>$null
+            $hasChanges = [bool]$dirty
+        } else {
+            # Non-Git: compare file timestamps against last snapshot
+            $lastSnap = Get-ChildItem $backupDir -Directory -ErrorAction SilentlyContinue |
+                        Where-Object { $_.Name -match '^\d{8}_\d{6}$' } |
+                        Sort-Object Name -Descending | Select-Object -First 1
+            if (-not $lastSnap) {
+                $hasChanges = $true
+            } else {
+                $latest = Get-ChildItem $resolved -Recurse -File -ErrorAction SilentlyContinue |
+                          Where-Object { $_.FullName -notmatch '[\\/](\.cursor-guard-backup)[\\/]' } |
+                          Sort-Object LastWriteTime -Descending | Select-Object -First 1
+                if ($latest -and $latest.LastWriteTime -gt $lastSnap.CreationTime) {
+                    $hasChanges = $true
+                }
+            }
+        }
+        if (-not $hasChanges) { continue }
 
         # ── Git branch snapshot ──────────────────────────────────
         if ($backupStrategy -eq "git" -or $backupStrategy -eq "both") {
@@ -350,7 +467,10 @@ try {
         }
 
         # Periodic retention cleanup every 10 cycles
-        if ($cycle % 10 -eq 0) { Invoke-RetentionCleanup }
+        if ($cycle % 10 -eq 0) {
+            Invoke-RetentionCleanup
+            Invoke-GitRetention
+        }
     }
 }
 finally {

package/references/config-reference.md

@@ -132,3 +132,29 @@ Retention policy for **shadow copies** only. Git branch snapshots are not auto-c
   "max_size_mb": 500
 }
 ```
+
+---
+
+## `git_retention`
+
+- **Type**: `object`
+- **Default**: `{ "enabled": false, "mode": "count", "max_count": 200 }`
+
+Retention policy for the **`cursor-guard/auto-backup` Git branch**. By default, auto-backup commits accumulate indefinitely. Enable this to automatically prune old commits.
+
+### Sub-fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `enabled` | `boolean` | `false` | Enable automatic pruning. When false, branch grows without limit. |
+| `mode` | `"days"` \| `"count"` | `"count"` | Pruning strategy |
+| `days` | `integer` | `30` | Keep commits from last N days (when mode=days) |
+| `max_count` | `integer` | `200` | Keep N newest commits (when mode=count, minimum 10) |
+
+```json
+"git_retention": {
+  "enabled": true,
+  "mode": "count",
+  "max_count": 200
+}
+```

package/references/config-reference.zh-CN.md

@@ -132,3 +132,29 @@
   "max_size_mb": 500
 }
 ```
+
+---
+
+## `git_retention`
+
+- **类型**：`object`
+- **默认值**：`{ "enabled": false, "mode": "count", "max_count": 200 }`
+
+**`cursor-guard/auto-backup` Git 分支**的保留策略。默认情况下自动备份提交会无限累积。启用此项可自动裁剪旧提交。
+
+### 子字段
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `enabled` | `boolean` | `false` | 启用自动裁剪。关闭时分支无限增长。 |
+| `mode` | `"days"` \| `"count"` | `"count"` | 裁剪策略 |
+| `days` | `integer` | `30` | 保留最近 N 天的提交（mode=days 时生效） |
+| `max_count` | `integer` | `200` | 保留最新 N 个提交（mode=count 时生效，最少 10） |
+
+```json
+"git_retention": {
+  "enabled": true,
+  "mode": "count",
+  "max_count": 200
+}
+```

package/references/cursor-guard.example.json

@@ -32,5 +32,11 @@
     "days": 30,
     "max_count": 100,
     "max_size_mb": 500
+  },
+  "git_retention": {
+    "enabled": false,
+    "mode": "count",
+    "days": 30,
+    "max_count": 200
   }
 }

package/references/cursor-guard.schema.json

@@ -67,6 +67,36 @@
         }
       },
       "additionalProperties": false
+    },
+    "git_retention": {
+      "type": "object",
+      "description": "Controls automatic cleanup of old commits on the cursor-guard/auto-backup branch.",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": false,
+          "description": "Enable automatic pruning of old auto-backup commits. Default false (manual cleanup)."
+        },
+        "mode": {
+          "type": "string",
+          "enum": ["days", "count"],
+          "default": "count",
+          "description": "'days': keep commits from the last N days. 'count': keep N newest commits."
+        },
+        "days": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 30,
+          "description": "Number of days to keep auto-backup commits (when mode='days')."
+        },
+        "max_count": {
+          "type": "integer",
+          "minimum": 10,
+          "default": 200,
+          "description": "Maximum number of auto-backup commits to keep (when mode='count')."
+        }
+      },
+      "additionalProperties": false
     }
   },
   "additionalProperties": true

package/references/guard-doctor.ps1

@@ -0,0 +1,226 @@
+<#
+.SYNOPSIS
+    Cursor Guard Doctor — one-command health check for your guard setup.
+
+.USAGE
+    .\guard-doctor.ps1 -Path "D:\MyProject"
+
+.NOTES
+    Checks: Git availability, worktree layout, .cursor-guard.json validity,
+    backup strategy vs environment compatibility, ignore effectiveness,
+    pre-restore refs, shadow copy directory, disk space, and more.
+#>
+
+param(
+    [Parameter(Mandatory)]
+    [string]$Path
+)
+
+$ErrorActionPreference = "Continue"
+$resolved = (Resolve-Path $Path -ErrorAction Stop).Path
+Set-Location $resolved
+
+$pass = 0; $warn = 0; $fail = 0
+
+function Write-Check {
+    param([string]$Name, [string]$Status, [string]$Detail = "")
+    switch ($Status) {
+        "PASS" { $color = "Green";  $script:pass++ }
+        "WARN" { $color = "Yellow"; $script:warn++ }
+        "FAIL" { $color = "Red";    $script:fail++ }
+        default { $color = "Gray" }
+    }
+    $line = "  [$Status] $Name"
+    if ($Detail) { $line += " — $Detail" }
+    Write-Host $line -ForegroundColor $color
+}
+
+Write-Host ""
+Write-Host "=== Cursor Guard Doctor ===" -ForegroundColor Cyan
+Write-Host "  Target: $resolved" -ForegroundColor Cyan
+Write-Host ""
+
+# ── 1. Git availability ──────────────────────────────────────────
+$hasGit = [bool](Get-Command git -ErrorAction SilentlyContinue)
+if ($hasGit) {
+    $gitVer = (git --version 2>$null) -replace 'git version ',''
+    Write-Check "Git installed" "PASS" "version $gitVer"
+} else {
+    Write-Check "Git installed" "WARN" "git not found in PATH; only shadow strategy available"
+}
+
+# ── 2. Git repo status ───────────────────────────────────────────
+$isRepo = $false
+$gitDir = $null
+if ($hasGit) {
+    $isRepo = (git rev-parse --is-inside-work-tree 2>$null) -eq "true"
+    if ($isRepo) {
+        $gitDir = (Resolve-Path (git rev-parse --git-dir 2>$null) -ErrorAction SilentlyContinue).Path
+        $isWorktree = (git rev-parse --is-inside-work-tree 2>$null) -eq "true" -and
+                      (git rev-parse --git-common-dir 2>$null) -ne (git rev-parse --git-dir 2>$null)
+        if ($isWorktree) {
+            Write-Check "Git repository" "PASS" "worktree detected (git-dir: $gitDir)"
+        } else {
+            Write-Check "Git repository" "PASS" "standard repo"
+        }
+    } else {
+        Write-Check "Git repository" "WARN" "not a Git repo; git/both strategies won't work"
+    }
+}
+
+# ── 3. .cursor-guard.json ────────────────────────────────────────
+$cfgPath = Join-Path $resolved ".cursor-guard.json"
+$cfg = $null
+if (Test-Path $cfgPath) {
+    try {
+        $cfg = Get-Content $cfgPath -Raw | ConvertFrom-Json
+        Write-Check "Config file" "PASS" ".cursor-guard.json found and valid JSON"
+    } catch {
+        Write-Check "Config file" "FAIL" "JSON parse error: $_"
+    }
+} else {
+    Write-Check "Config file" "WARN" "no .cursor-guard.json found; using defaults (protect everything)"
+}
+
+# ── 4. Strategy vs environment ────────────────────────────────────
+$strategy = "git"
+if ($cfg -and $cfg.backup_strategy) { $strategy = $cfg.backup_strategy }
+if ($strategy -eq "git" -or $strategy -eq "both") {
+    if (-not $isRepo) {
+        Write-Check "Strategy compatibility" "FAIL" "backup_strategy='$strategy' but directory is not a Git repo"
+    } else {
+        Write-Check "Strategy compatibility" "PASS" "backup_strategy='$strategy' and Git repo exists"
+    }
+} elseif ($strategy -eq "shadow") {
+    Write-Check "Strategy compatibility" "PASS" "backup_strategy='shadow' — no Git required"
+} else {
+    Write-Check "Strategy compatibility" "FAIL" "unknown backup_strategy='$strategy' (must be git/shadow/both)"
+}
+
+# ── 5. Backup branch ─────────────────────────────────────────────
+if ($isRepo) {
+    $branchRef = "refs/heads/cursor-guard/auto-backup"
+    $branchExists = git rev-parse --verify $branchRef 2>$null
+    if ($branchExists) {
+        $commitCount = (git rev-list --count $branchRef 2>$null)
+        Write-Check "Backup branch" "PASS" "cursor-guard/auto-backup exists ($commitCount commits)"
+    } else {
+        Write-Check "Backup branch" "WARN" "cursor-guard/auto-backup not created yet (will be created on first backup)"
+    }
+}
+
+# ── 6. Guard refs ────────────────────────────────────────────────
+if ($isRepo) {
+    $guardRefs = git for-each-ref refs/guard/ --format="%(refname)" 2>$null
+    if ($guardRefs) {
+        $refCount = @($guardRefs).Count
+        $preRestoreRefs = @($guardRefs | Where-Object { $_ -match 'pre-restore/' })
+        Write-Check "Guard refs" "PASS" "$refCount ref(s) found ($($preRestoreRefs.Count) pre-restore snapshots)"
+    } else {
+        Write-Check "Guard refs" "WARN" "no guard refs yet (created on first snapshot or restore)"
+    }
+}
+
+# ── 7. Shadow copy directory ─────────────────────────────────────
+$backupDir = Join-Path $resolved ".cursor-guard-backup"
+if (Test-Path $backupDir) {
+    $snapDirs = Get-ChildItem $backupDir -Directory -ErrorAction SilentlyContinue |
+                Where-Object { $_.Name -match '^\d{8}_\d{6}$' -or $_.Name -match '^pre-restore-' }
+    $snapCount = if ($snapDirs) { @($snapDirs).Count } else { 0 }
+    $totalMB = [math]::Round(((Get-ChildItem $backupDir -Recurse -File -ErrorAction SilentlyContinue |
+                Measure-Object Length -Sum).Sum / 1MB), 1)
+    Write-Check "Shadow copies" "PASS" "$snapCount snapshot(s), ${totalMB} MB total"
+} else {
+    Write-Check "Shadow copies" "WARN" ".cursor-guard-backup/ not found (will be created on first shadow backup)"
+}
+
+# ── 8. .gitignore / exclude coverage ────────────────────────────
+if ($isRepo) {
+    $checkIgnored = git check-ignore ".cursor-guard-backup/test" 2>$null
+    if ($checkIgnored) {
+        Write-Check "Backup dir ignored" "PASS" ".cursor-guard-backup/ is git-ignored"
+    } else {
+        Write-Check "Backup dir ignored" "WARN" ".cursor-guard-backup/ may NOT be git-ignored — backup changes could trigger commits"
+    }
+}
+
+# ── 9. Config field validation ────────────────────────────────────
+if ($cfg) {
+    $validStrategies = @("git", "shadow", "both")
+    if ($cfg.backup_strategy -and $cfg.backup_strategy -notin $validStrategies) {
+        Write-Check "Config: backup_strategy" "FAIL" "invalid value '$($cfg.backup_strategy)'"
+    }
+
+    $validPreRestore = @("always", "ask", "never")
+    if ($cfg.pre_restore_backup -and $cfg.pre_restore_backup -notin $validPreRestore) {
+        Write-Check "Config: pre_restore_backup" "FAIL" "invalid value '$($cfg.pre_restore_backup)'"
+    } elseif ($cfg.pre_restore_backup -eq "never") {
+        Write-Check "Config: pre_restore_backup" "WARN" "set to 'never' — restores won't auto-preserve current version"
+    }
+
+    if ($cfg.auto_backup_interval_seconds -and $cfg.auto_backup_interval_seconds -lt 5) {
+        Write-Check "Config: interval" "WARN" "$($cfg.auto_backup_interval_seconds)s is below minimum (5s), will be clamped"
+    }
+
+    if ($cfg.retention -and $cfg.retention.mode) {
+        $validModes = @("days", "count", "size")
+        if ($cfg.retention.mode -notin $validModes) {
+            Write-Check "Config: retention.mode" "FAIL" "invalid value '$($cfg.retention.mode)'"
+        }
+    }
+}
+
+# ── 10. Protect / Ignore effectiveness ───────────────────────────
+if ($cfg -and $cfg.protect) {
+    $allFiles = Get-ChildItem $resolved -Recurse -File -ErrorAction SilentlyContinue |
+                Where-Object { $_.FullName -notmatch '[\\/](\.git|\.cursor-guard-backup|node_modules)[\\/]' }
+    $protectedCount = 0
+    foreach ($f in $allFiles) {
+        $rel = $f.FullName.Substring($resolved.Length + 1) -replace '\\','/'
+        foreach ($pat in @($cfg.protect)) {
+            $p = $pat -replace '\\','/'
+            if ($rel -like $p -or (Split-Path $rel -Leaf) -like $p) { $protectedCount++; break }
+        }
+    }
+    $totalCount = if ($allFiles) { @($allFiles).Count } else { 0 }
+    Write-Check "Protect patterns" "PASS" "$protectedCount / $totalCount files matched by protect patterns"
+}
+
+# ── 11. Disk space ────────────────────────────────────────────────
+try {
+    $letter = (Split-Path $resolved -Qualifier) -replace ':$',''
+    $drv = Get-PSDrive $letter -ErrorAction Stop
+    $freeGB = [math]::Round($drv.Free / 1GB, 1)
+    if ($freeGB -lt 1) {
+        Write-Check "Disk space" "FAIL" "${freeGB} GB free — critically low"
+    } elseif ($freeGB -lt 5) {
+        Write-Check "Disk space" "WARN" "${freeGB} GB free"
+    } else {
+        Write-Check "Disk space" "PASS" "${freeGB} GB free"
+    }
+} catch {
+    Write-Check "Disk space" "WARN" "could not determine free space"
+}
+
+# ── 12. Lock file ────────────────────────────────────────────────
+$lockFile = if ($gitDir) { Join-Path $gitDir "cursor-guard.lock" } else { Join-Path $backupDir "cursor-guard.lock" }
+if (Test-Path $lockFile) {
+    $lockContent = Get-Content $lockFile -Raw -ErrorAction SilentlyContinue
+    Write-Check "Lock file" "WARN" "lock file exists — another instance may be running. Content: $lockContent"
+} else {
+    Write-Check "Lock file" "PASS" "no lock file (no running instance)"
+}
+
+# ── Summary ──────────────────────────────────────────────────────
+Write-Host ""
+Write-Host "=== Summary ===" -ForegroundColor Cyan
+Write-Host "  PASS: $pass  |  WARN: $warn  |  FAIL: $fail" -ForegroundColor $(if ($fail -gt 0) { "Red" } elseif ($warn -gt 0) { "Yellow" } else { "Green" })
+Write-Host ""
+if ($fail -gt 0) {
+    Write-Host "  Fix FAIL items before relying on Cursor Guard." -ForegroundColor Red
+} elseif ($warn -gt 0) {
+    Write-Host "  Review WARN items to ensure everything works as expected." -ForegroundColor Yellow
+} else {
+    Write-Host "  All checks passed. Cursor Guard is ready." -ForegroundColor Green
+}
+Write-Host ""

package/references/recovery.md

@@ -13,8 +13,7 @@ Replace `<path>` / `<file>` with real paths. Run from repository root. **Review
 ### Single file / 单文件
 
 ```powershell
-# Preserve current file state via temp index (does not touch staging area)
-# 通过临时索引保留当前文件（不影响暂存区）
+$ts = Get-Date -Format 'yyyyMMdd_HHmmss'
 $guardIdx = Join-Path (git rev-parse --git-dir) "guard-pre-restore-index"
 $env:GIT_INDEX_FILE = $guardIdx
 git read-tree HEAD
@@ -23,14 +22,15 @@ $tree = git write-tree
 $env:GIT_INDEX_FILE = $null
 Remove-Item $guardIdx -Force -ErrorAction SilentlyContinue
 $commit = git commit-tree $tree -p HEAD -m "guard: preserve current before restore"
-git update-ref refs/guard/pre-restore $commit
-Write-Host "Pre-restore backup: $($commit.Substring(0,7))"
+git update-ref "refs/guard/pre-restore/$ts" $commit
+git update-ref refs/guard/pre-restore $commit   # alias to latest
+Write-Host "Pre-restore backup: refs/guard/pre-restore/$ts ($($commit.Substring(0,7)))"
 ```
 
 ### Entire project / 整个项目
 
 ```powershell
-# Same as above but with git add -A
+$ts = Get-Date -Format 'yyyyMMdd_HHmmss'
 $guardIdx = Join-Path (git rev-parse --git-dir) "guard-pre-restore-index"
 $env:GIT_INDEX_FILE = $guardIdx
 git read-tree HEAD
@@ -39,8 +39,9 @@ $tree = git write-tree
 $env:GIT_INDEX_FILE = $null
 Remove-Item $guardIdx -Force -ErrorAction SilentlyContinue
 $commit = git commit-tree $tree -p HEAD -m "guard: preserve current before restore"
-git update-ref refs/guard/pre-restore $commit
-Write-Host "Pre-restore backup: $($commit.Substring(0,7))"
+git update-ref "refs/guard/pre-restore/$ts" $commit
+git update-ref refs/guard/pre-restore $commit   # alias to latest
+Write-Host "Pre-restore backup: refs/guard/pre-restore/$ts ($($commit.Substring(0,7)))"
 ```
 
 ### Non-Git fallback (shadow copy) / 非 Git 备选方案
@@ -53,21 +54,40 @@ Copy-Item "<file>" "$dir/<filename>"
 Write-Host "Pre-restore shadow copy: $dir"
 ```
 
+### List all pre-restore snapshots / 列出所有恢复前快照
+
+```bash
+git for-each-ref refs/guard/pre-restore/ --sort=-creatordate \
+  --format="%(refname:short) %(creatordate:short) %(objectname:short)"
+```
+
 ### Undo a restore (recover pre-restore state) / 撤销恢复（回到恢复前的状态）
 
 ```bash
-# Restore single file to pre-restore state
-# 将单个文件恢复到恢复前的状态
+# Undo using a specific timestamped snapshot
+# 使用特定时间戳快照撤销恢复
+git restore --source=refs/guard/pre-restore/<yyyyMMdd_HHmmss> -- <file>
+
+# Undo using the latest pre-restore snapshot (alias)
+# 使用最近一次的恢复前快照撤销
 git restore --source=refs/guard/pre-restore -- <file>
 
-# Restore entire project to pre-restore state
-# 将整个项目恢复到恢复前的状态
-git restore --source=refs/guard/pre-restore -- .
+# Restore entire project / 恢复整个项目
+git restore --source=refs/guard/pre-restore/<yyyyMMdd_HHmmss> -- .
 
 # From shadow copy / 从影子拷贝恢复
 Copy-Item ".cursor-guard-backup/pre-restore-<ts>/<file>" "<original-path>"
 ```
 
+### Clean up old pre-restore refs / 清理旧的恢复前快照
+
+```bash
+# Delete all pre-restore refs (keep only the latest alias)
+# 删除所有时间戳快照（仅保留 latest alias）
+git for-each-ref refs/guard/pre-restore/ --format="%(refname)" |
+  xargs -n1 git update-ref -d
+```
+
 ---
 
 ## Inspect current state