cursor-guard 1.3.0 → 1.4.0

package/README.md

@@ -132,10 +132,23 @@ Edit `.cursor-guard.json` to define which files to protect:
   "ignore": ["node_modules/**", "dist/**"],
   "auto_backup_interval_seconds": 60,
   "secrets_patterns": [".env", ".env.*", "*.key", "*.pem"],
+  "pre_restore_backup": "always",
   "retention": { "mode": "days", "days": 30 }
 }
 ```
 
+#### `pre_restore_backup` — restore behavior control
+
+| Value | Behavior |
+|-------|----------|
+| `"always"` (default) | Automatically preserve current version before every restore. No prompt. |
+| `"ask"` | Prompt you each time: "Preserve current version before restore? (Y/n)" — you decide per restore. |
+| `"never"` | Never preserve current version before restore (not recommended). |
+
+Regardless of config, you can always override per-request:
+- Say "don't preserve current version" to skip even when config is `"always"`
+- Say "preserve current first" to force even when config is `"never"`
+
 ---
 
 ## Auto-Backup Script

package/README.zh-CN.md

@@ -132,10 +132,23 @@ cp .cursor/skills/cursor-guard/references/cursor-guard.example.json .cursor-guar
   "ignore": ["node_modules/**", "dist/**"],
   "auto_backup_interval_seconds": 60,
   "secrets_patterns": [".env", ".env.*", "*.key", "*.pem"],
+  "pre_restore_backup": "always",
   "retention": { "mode": "days", "days": 30 }
 }
 ```
 
+#### `pre_restore_backup` — 恢复前保留行为控制
+
+| 值 | 行为 |
+|----|------|
+| `"always"`（默认） | 每次恢复前自动保留当前版本，无需确认。 |
+| `"ask"` | 每次恢复前询问你："恢复前是否保留当前版本？(Y/n)"——由你逐次决定。 |
+| `"never"` | 恢复前不保留当前版本（不推荐）。 |
+
+无论配置如何，你始终可以在单次请求中覆盖：
+- 说"不保留当前版本"可跳过保留（即使配置为 `"always"`）
+- 说"先保留当前版本"可强制保留（即使配置为 `"never"`）
+
 ---
 
 ## 自动备份脚本

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.
 
@@ -44,6 +45,12 @@ On first trigger in a session, check if the workspace root contains `.cursor-gua
   // Built-in defaults: .env, .env.*, *.key, *.pem, *.p12, *.pfx, credentials*
   "secrets_patterns": [".env", ".env.*", "*.key", "*.pem"],
 
+  // Controls behavior before restore operations.
+  // "always" (default): automatically preserve current version before every restore.
+  // "ask": prompt the user each time to decide.
+  // "never": skip preservation entirely (not recommended).
+  "pre_restore_backup": "always",
+
   // Retention for shadow copies. mode: "days" | "count" | "size"
   "retention": { "mode": "days", "days": 30, "max_count": 100, "max_size_mb": 500 }
 }
@@ -94,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):
@@ -302,19 +312,26 @@ Recommended: #1 (closest to target time). Restore this one? / 推荐 #1（最接
   - If still nothing, report clearly: "No snapshot found before that time. The earliest available is [hash] at [time]. Do you want to use it?"
 - **Never silently pick a version.** Always show and confirm.
 
-### Step 4: Preserve Current Version Before Restore (MANDATORY)
+### Step 4: Preserve Current Version Before Restore
 
 > **Rule: `restore_requires_preserve_current_by_default`**
 >
-> Every restore operation MUST first preserve the current state, THEN restore. This is non-negotiable unless the user explicitly opts out.
+> The behavior is controlled by `pre_restore_backup` in `.cursor-guard.json` (default: `"always"`).
+
+**4a. Determine preservation mode**
 
-**4a. Check if user opted out**
+Read `pre_restore_backup` from config (§0). Three modes:
 
-Skip preservation ONLY if the user explicitly said one of:
-- "不保留当前版本" / "不用备份当前版本" / "直接覆盖恢复"
-- "skip backup before restore" / "don't preserve current" / "just restore"
+| Config value | Behavior |
+|-------------|----------|
+| `"always"` (default) | Automatically preserve current version. No prompt. Jump to 4b. |
+| `"ask"` | Prompt the user: "恢复前是否保留当前版本？(Y/n)" / "Preserve current version before restore? (Y/n)". If user answers yes/default → jump to 4b. If user answers no → inform and jump to Step 5. |
+| `"never"` | Skip preservation entirely. Inform: "配置已设为不保留当前版本 (pre_restore_backup=never)，直接恢复。" and jump to Step 5. |
 
-If opted out, inform: "你已明确表示不保留当前版本，我将直接恢复。" and jump to Step 5.
+**Override rules** (apply regardless of config):
+- If the user **explicitly** says "不保留当前版本" / "skip backup before restore" in the current message → skip, even if config is `"always"`.
+- If the user **explicitly** says "先保留当前版本" / "preserve current first" → preserve, even if config is `"never"`.
+- User's explicit instruction in the current message always takes priority over config.
 
 **4b. Determine preservation scope**
 
@@ -346,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
 
@@ -365,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):**
 
@@ -391,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
@@ -438,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`
 ```
 
 ---
@@ -486,7 +515,7 @@ Skip the block for unrelated turns.
 
 - 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.
+- Template config: [references/cursor-guard.example.json](references/cursor-guard.example.json) — copy to workspace root and customize. Field docs: [references/config-reference.md](references/config-reference.md).
 
 ---
 
@@ -496,3 +525,6 @@ Skip the block for unrelated turns.
 - 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)
+- 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.0",
+  "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

@@ -0,0 +1,160 @@
+# Configuration Reference
+
+This document explains every field in `.cursor-guard.json`.
+
+> Example file: [cursor-guard.example.json](cursor-guard.example.json)
+>
+> JSON Schema: [cursor-guard.schema.json](cursor-guard.schema.json)
+
+---
+
+## `protect`
+
+- **Type**: `string[]` (glob patterns)
+- **Default**: not set (all files protected)
+
+Whitelist glob patterns relative to workspace root. Only matching files get backup protection. If empty or missing, all files are protected.
+
+```json
+"protect": ["src/**", "lib/**", "package.json"]
+```
+
+---
+
+## `ignore`
+
+- **Type**: `string[]` (glob patterns)
+- **Default**: not set
+
+Blacklist glob patterns. Matching files are excluded from protection even if they match `protect`. Applied on top of `.gitignore`.
+
+**Resolution rules**:
+
+| Scenario | Behavior |
+|----------|----------|
+| Both `protect` and `ignore` set | File must match `protect` AND not match `ignore` |
+| Only `protect` set | Only matching files are protected |
+| Only `ignore` set | Everything protected except matches |
+| Neither set | Protect everything |
+
+```json
+"ignore": ["node_modules/**", "dist/**", "*.log"]
+```
+
+---
+
+## `backup_strategy`
+
+- **Type**: `string`
+- **Allowed**: `"git"` | `"shadow"` | `"both"`
+- **Default**: `"git"`
+
+| Value | Description |
+|-------|-------------|
+| `"git"` | Local commits to dedicated branch `cursor-guard/auto-backup` |
+| `"shadow"` | File copies to `.cursor-guard-backup/<timestamp>/` |
+| `"both"` | Git branch snapshot + shadow copies |
+
+```json
+"backup_strategy": "git"
+```
+
+---
+
+## `auto_backup_interval_seconds`
+
+- **Type**: `integer`
+- **Minimum**: `5`
+- **Default**: `60`
+
+Interval in seconds for `auto-backup.ps1` to check for changes and create snapshots.
+
+```json
+"auto_backup_interval_seconds": 60
+```
+
+---
+
+## `secrets_patterns`
+
+- **Type**: `string[]` (glob patterns)
+- **Default**: built-in list (see below)
+
+Glob patterns for sensitive files. Matching files are **auto-excluded** from backup, even if within `protect` scope. Built-in defaults (always active): `.env`, `.env.*`, `*.key`, `*.pem`, `*.p12`, `*.pfx`, `credentials*`. Set this field to override with your own patterns.
+
+```json
+"secrets_patterns": [".env", ".env.*", "*.key", "*.pem"]
+```
+
+---
+
+## `pre_restore_backup`
+
+- **Type**: `string`
+- **Allowed**: `"always"` | `"ask"` | `"never"`
+- **Default**: `"always"`
+
+| Value | Description |
+|-------|-------------|
+| `"always"` | Auto-preserve current version before every restore. No prompt. |
+| `"ask"` | Prompt user each time: "Preserve current version?" |
+| `"never"` | Skip preservation entirely (not recommended). |
+
+Regardless of this config, the user's explicit instruction in the current message always takes priority. Say "don't preserve" to skip, or "preserve first" to force.
+
+```json
+"pre_restore_backup": "always"
+```
+
+---
+
+## `retention`
+
+- **Type**: `object`
+- **Default**: `{ "mode": "days", "days": 30 }`
+
+Retention policy for **shadow copies** only. Git branch snapshots are not auto-cleaned — manage them manually. Controls automatic cleanup of old `.cursor-guard-backup/` directories.
+
+### Sub-fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `mode` | `"days"` \| `"count"` \| `"size"` | `"days"` | Cleanup strategy |
+| `days` | `integer` | `30` | Keep snapshots from last N days (when mode=days) |
+| `max_count` | `integer` | `100` | Keep N newest snapshots (when mode=count) |
+| `max_size_mb` | `integer` | `500` | Keep total size under N MB (when mode=size) |
+
+```json
+"retention": {
+  "mode": "days",
+  "days": 30,
+  "max_count": 100,
+  "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

@@ -0,0 +1,160 @@
+# 配置参数说明
+
+本文档说明 `.cursor-guard.json` 中的每个配置项。
+
+> 示例文件：[cursor-guard.example.json](cursor-guard.example.json)
+>
+> JSON Schema：[cursor-guard.schema.json](cursor-guard.schema.json)
+
+---
+
+## `protect`
+
+- **类型**：`string[]`（glob 模式）
+- **默认值**：未设置（保护所有文件）
+
+白名单 glob 模式，相对于工作区根目录。只有匹配的文件才会被保护。留空或不设置则保护所有文件。
+
+```json
+"protect": ["src/**", "lib/**", "package.json"]
+```
+
+---
+
+## `ignore`
+
+- **类型**：`string[]`（glob 模式）
+- **默认值**：未设置
+
+黑名单 glob 模式。匹配的文件即使被 `protect` 包含也会排除。在 `.gitignore` 基础上额外生效。
+
+**解析规则**：
+
+| 场景 | 行为 |
+|------|------|
+| 同时设置 `protect` 和 `ignore` | 文件须匹配 protect 且不匹配 ignore |
+| 仅设置 `protect` | 仅匹配文件被保护 |
+| 仅设置 `ignore` | 除匹配文件外全部保护 |
+| 都不设置 | 保护全部文件 |
+
+```json
+"ignore": ["node_modules/**", "dist/**", "*.log"]
+```
+
+---
+
+## `backup_strategy`
+
+- **类型**：`string`
+- **可选值**：`"git"` | `"shadow"` | `"both"`
+- **默认值**：`"git"`
+
+| 值 | 说明 |
+|----|------|
+| `"git"` | 提交到专用分支 `cursor-guard/auto-backup` |
+| `"shadow"` | 文件拷贝到 `.cursor-guard-backup/<timestamp>/` |
+| `"both"` | Git 分支快照 + 影子拷贝同时进行 |
+
+```json
+"backup_strategy": "git"
+```
+
+---
+
+## `auto_backup_interval_seconds`
+
+- **类型**：`integer`
+- **最小值**：`5`
+- **默认值**：`60`
+
+自动备份脚本 `auto-backup.ps1` 检查变更并创建快照的间隔秒数。
+
+```json
+"auto_backup_interval_seconds": 60
+```
+
+---
+
+## `secrets_patterns`
+
+- **类型**：`string[]`（glob 模式）
+- **默认值**：内置列表（见下）
+
+敏感文件 glob 模式。匹配的文件**自动排除**备份，即使在 `protect` 范围内。内置默认值（始终生效）：`.env`、`.env.*`、`*.key`、`*.pem`、`*.p12`、`*.pfx`、`credentials*`。设置此字段可覆盖为自定义模式。
+
+```json
+"secrets_patterns": [".env", ".env.*", "*.key", "*.pem"]
+```
+
+---
+
+## `pre_restore_backup`
+
+- **类型**：`string`
+- **可选值**：`"always"` | `"ask"` | `"never"`
+- **默认值**：`"always"`
+
+| 值 | 说明 |
+|----|------|
+| `"always"` | 恢复前自动保留当前版本，无需确认。 |
+| `"ask"` | 每次恢复前询问用户是否保留当前版本。 |
+| `"never"` | 不保留当前版本（不推荐）。 |
+
+无论此配置如何，用户在当前消息中的明确指令始终优先。说"不保留当前版本"可跳过，说"先保留当前版本"可强制保留。
+
+```json
+"pre_restore_backup": "always"
+```
+
+---
+
+## `retention`
+
+- **类型**：`object`
+- **默认值**：`{ "mode": "days", "days": 30 }`
+
+仅针对**影子拷贝**的保留策略。Git 分支快照不会自动清理，需手动管理。控制 `.cursor-guard-backup/` 旧目录的自动清理。
+
+### 子字段
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `mode` | `"days"` \| `"count"` \| `"size"` | `"days"` | 清理策略 |
+| `days` | `integer` | `30` | 保留最近 N 天的快照（mode=days 时生效） |
+| `max_count` | `integer` | `100` | 保留最新 N 份快照（mode=count 时生效） |
+| `max_size_mb` | `integer` | `500` | 总大小不超过 N MB（mode=size 时生效） |
+
+```json
+"retention": {
+  "mode": "days",
+  "days": 30,
+  "max_count": 100,
+  "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

@@ -1,8 +1,4 @@
 {
-  "_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/**",
@@ -12,7 +8,6 @@
     "tsconfig.json",
     ".env.example"
   ],
-
   "ignore": [
     "node_modules/**",
     "dist/**",
@@ -23,23 +18,25 @@
     "*.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).",
+  "pre_restore_backup": "always",
   "retention": {
     "mode": "days",
     "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

@@ -31,6 +31,12 @@
       "items": { "type": "string" },
       "description": "Glob patterns for sensitive files auto-excluded from backups. Built-in defaults: .env, .env.*, *.key, *.pem, *.p12, *.pfx, credentials*"
     },
+    "pre_restore_backup": {
+      "type": "string",
+      "enum": ["always", "ask", "never"],
+      "default": "always",
+      "description": "'always' (default): automatically preserve current version before every restore. 'ask': prompt the user each time to choose whether to preserve. 'never': skip preservation entirely (not recommended)."
+    },
     "retention": {
       "type": "object",
       "description": "Controls automatic cleanup of old shadow-copy snapshots.",
@@ -61,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