cursor-guard 1.2.0 → 1.3.2

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
@@ -157,7 +170,9 @@ The script uses Git plumbing commands to snapshot to `cursor-guard/auto-backup`
 
 ## Recovery
 
-If something goes wrong, just tell the AI agent in natural language:
+If something goes wrong, just tell the AI agent in natural language.
+
+**Default behavior**: Before any restore, the agent automatically preserves your current version so you can undo the restore if needed. You don't need to ask for this — it happens by default. To skip, explicitly say "don't preserve current version" or "skip backup before restore".
 
 ### By time
 
@@ -176,7 +191,14 @@ If something goes wrong, just tell the AI agent in natural language:
 > "restore src/app.py to 10 minutes ago"
 > "restore src/app.py to the previous version"
 
-The agent will automatically search Git history and auto-backup snapshots, show you matching versions to choose from, and restore after your confirmation.
+The agent will:
+1. **Preserve your current version** first (unless you opt out)
+2. Search Git history and auto-backup snapshots
+3. Show matching versions for you to choose
+4. Restore after your confirmation
+5. Report both the pre-restore backup ref and the restore result
+
+If the pre-restore backup fails, the agent will **not** proceed — it will wait for your explicit confirmation before restoring without a safety net.
 
 ### Recovery priority
 

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"`）
+
 ---
 
 ## 自动备份脚本
@@ -157,7 +170,9 @@ cp .cursor/skills/cursor-guard/references/cursor-guard.example.json .cursor-guar
 
 ## 恢复
 
-出问题时，直接用自然语言告诉 AI 代理即可：
+出问题时，直接用自然语言告诉 AI 代理即可。
+
+**默认行为**：执行任何恢复操作前，代理会自动保留你的当前版本，方便恢复后反悔。无需额外请求，这是默认行为。如需跳过，请明确说"不保留当前版本"或"直接覆盖恢复"。
 
 ### 按时间恢复
 
@@ -176,7 +191,14 @@ cp .cursor/skills/cursor-guard/references/cursor-guard.example.json .cursor-guar
 > "把 src/app.py 恢复到10分钟前"
 > "把 src/app.py 恢复到上一个版本"
 
-代理会自动搜索 Git 历史和自动备份快照，列出匹配版本供你选择，确认后执行恢复。
+代理会：
+1. **先保留你的当前版本**（除非你明确选择跳过）
+2. 搜索 Git 历史和自动备份快照
+3. 列出匹配版本供你选择
+4. 确认后执行恢复
+5. 报告恢复前备份引用和恢复结果
+
+如果保留当前版本失败，代理**不会**继续恢复——会等你明确确认后才会在没有安全网的情况下恢复。
 
 ### 恢复优先级
 

package/SKILL.md

@@ -44,6 +44,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 }
 }
@@ -302,7 +308,111 @@ 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: Execute Recovery
+### Step 4: Preserve Current Version Before Restore
+
+> **Rule: `restore_requires_preserve_current_by_default`**
+>
+> The behavior is controlled by `pre_restore_backup` in `.cursor-guard.json` (default: `"always"`).
+
+**4a. Determine preservation mode**
+
+Read `pre_restore_backup` from config (§0). Three modes:
+
+| 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. |
+
+**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**
+
+| Restore scope | What to preserve |
+|---------------|-----------------|
+| Single file | Only that file's current state |
+| Multiple files | All files that will be overwritten |
+| Entire project | Full project snapshot |
+
+**4c. Check if there are changes to preserve**
+
+```bash
+# For single file: check if file differs from the restore target
+git diff <target-commit> -- <file>
+
+# For project: check overall status
+git status --porcelain
+```
+
+If the file/project is **identical** to the restore target (no diff), inform:
+"当前版本与目标版本相同，无需保留，跳过备份。" / "Current version is identical to target, no backup needed."
+Then jump to Step 5.
+
+If the working tree is clean AND HEAD matches the restore target, inform:
+"当前无可保留变更，直接恢复。" / "No changes to preserve, proceeding with restore."
+Then jump to Step 5.
+
+**4d. Create preservation snapshot**
+
+Use the same temp-index plumbing as §2a to avoid polluting the user's staging area:
+
+**Git repo (preferred):**
+
+```powershell
+$guardIdx = Join-Path (git rev-parse --git-dir) "guard-pre-restore-index"
+$env:GIT_INDEX_FILE = $guardIdx
+
+# For single file: read HEAD tree then update just the target file
+git read-tree HEAD
+git add -- <file>
+
+# For project: snapshot everything
+git read-tree HEAD
+git add -A
+
+$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 to <target>"
+git update-ref refs/guard/pre-restore $commit
+```
+
+Record the short hash and the ref `refs/guard/pre-restore`.
+
+**Non-Git fallback (shadow copy):**
+
+```powershell
+$ts = Get-Date -Format 'yyyyMMdd_HHmmss'
+$dir = ".cursor-guard-backup/pre-restore-$ts"
+New-Item -ItemType Directory -Force $dir | Out-Null
+Copy-Item "<file>" "$dir/<file>"
+```
+
+**4e. Handle preservation failure**
+
+If the snapshot fails (e.g. disk full, permission error):
+1. **Do NOT proceed with restore.** Default is to abort.
+2. Inform the user: "当前版本保留失败。默认不继续恢复；如果你确认不保留当前状态也要继续，请明确说明。" / "Failed to preserve current version. Restore aborted by default. If you want to continue without backup, please confirm explicitly."
+3. Only proceed if the user explicitly confirms: "即使不保留也继续" / "continue without backup".
+
+**4f. Inform user of preservation result**
+
+Before executing restore, tell the user:
+```
+在恢复前，我已保留当前版本：
+- 备份引用: refs/guard/pre-restore (abc1234)
+- 恢复方式: git restore --source=refs/guard/pre-restore -- <file>
+
+Current version preserved before restore:
+- Backup ref: refs/guard/pre-restore (abc1234)
+- To undo: git restore --source=refs/guard/pre-restore -- <file>
+```
+
+### Step 5: Execute Recovery
 
 **Single file recovery:**
 
@@ -330,12 +440,23 @@ Get-ChildItem .cursor-guard-backup/ -Directory | Sort-Object Name -Descending
 Copy-Item ".cursor-guard-backup/<timestamp>/<file>" "<original-path>"
 ```
 
-### Step 5: Verify & Report
+### Step 6: Verify & Report
 
 After restoring, always:
 1. Show the restored file content (or diff) so the user can verify
-2. Report the recovery in the status block (§6)
-3. Suggest creating a new snapshot of the current (restored) state
+2. Report the recovery in the status block (§6a), including **both** the pre-restore backup ref and the restore target
+3. Tell the user how to undo the restore if needed
+
+**Status block for restore operations:**
+
+```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)`
+- **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>`
+```
 
 ---
 
@@ -360,15 +481,17 @@ Skip the block for unrelated turns.
 
 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.
+3. **MUST preserve current version before restore** — every restore operation must first snapshot the current state (§5a Step 4). Skip ONLY when: (a) user explicitly opts out, (b) current state is identical to target, or (c) no changes exist. If preservation fails, abort restore by default.
+4. **Do not** treat Timeline/Checkpoints as the only or primary recovery path.
+5. **Do not** recommend Checkpoints as long-term or sole backup.
+6. **No automatic push** to remotes; local commits only unless user requests push.
+7. **Be honest** about limits: terminal side effects, binary files, and non-tracked paths are not fully reversible without prior commits.
+8. **Do not** run `git clean`, `reset --hard`, or other destructive Git commands unless the user clearly asked; always show what would be affected first.
+9. **Do not** delete files via the Delete tool without explicit per-file confirmation from the user.
+10. **Do not** modify or delete `.cursor-guard.json` unless the user explicitly asks — accidental config changes silently alter protection scope.
+11. **Use `--no-verify`** on all guard snapshot commits to bypass pre-commit hooks that could fail or modify files.
+12. **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.
+13. **Preservation must not pollute** — all pre-restore backups use temp index + dedicated ref (`refs/guard/pre-restore`). The user's staging area, working tree, and commit history on their branch are never modified by the preservation process.
 
 ---
 
@@ -376,7 +499,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).
 
 ---
 
@@ -386,3 +509,5 @@ 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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-guard",
-  "version": "1.2.0",
+  "version": "1.3.2",
   "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/config-reference.md

@@ -0,0 +1,134 @@
+# 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
+}
+```

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

@@ -0,0 +1,134 @@
+# 配置参数说明
+
+本文档说明 `.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
+}
+```

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,19 +18,15 @@
     "*.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,

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.",

package/references/recovery.md

@@ -4,6 +4,72 @@ Replace `<path>` / `<file>` with real paths. Run from repository root. **Review
 
 ---
 
+## Preserve current version before restore / 恢复前保留当前版本
+
+> **Default behavior**: Every restore operation must first preserve current state.
+>
+> **默认行为**：每次恢复操作前必须先保留当前版本。
+
+### Single file / 单文件
+
+```powershell
+# Preserve current file state via temp index (does not touch staging area)
+# 通过临时索引保留当前文件（不影响暂存区）
+$guardIdx = Join-Path (git rev-parse --git-dir) "guard-pre-restore-index"
+$env:GIT_INDEX_FILE = $guardIdx
+git read-tree HEAD
+git add -- <file>
+$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))"
+```
+
+### Entire project / 整个项目
+
+```powershell
+# Same as above but with git add -A
+$guardIdx = Join-Path (git rev-parse --git-dir) "guard-pre-restore-index"
+$env:GIT_INDEX_FILE = $guardIdx
+git read-tree HEAD
+git add -A
+$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))"
+```
+
+### Non-Git fallback (shadow copy) / 非 Git 备选方案
+
+```powershell
+$ts = Get-Date -Format 'yyyyMMdd_HHmmss'
+$dir = ".cursor-guard-backup/pre-restore-$ts"
+New-Item -ItemType Directory -Force $dir | Out-Null
+Copy-Item "<file>" "$dir/<filename>"
+Write-Host "Pre-restore shadow copy: $dir"
+```
+
+### Undo a restore (recover pre-restore state) / 撤销恢复（回到恢复前的状态）
+
+```bash
+# Restore single file to pre-restore state
+# 将单个文件恢复到恢复前的状态
+git restore --source=refs/guard/pre-restore -- <file>
+
+# Restore entire project to pre-restore state
+# 将整个项目恢复到恢复前的状态
+git restore --source=refs/guard/pre-restore -- .
+
+# From shadow copy / 从影子拷贝恢复
+Copy-Item ".cursor-guard-backup/pre-restore-<ts>/<file>" "<original-path>"
+```
+
+---
+
 ## Inspect current state
 
 ```bash