cursor-guard 2.0.3 → 2.1.0

package/README.md

@@ -179,7 +179,7 @@ npx cursor-guard-backup --path /my/project --interval 30
 ./references/auto-backup.sh /my/project
 ```
 
-The script uses Git plumbing commands to snapshot to `cursor-guard/auto-backup` branch — it never switches branches or touches your working index. Supports `shadow` mode for non-Git directories.
+The script uses Git plumbing commands to snapshot to `refs/guard/auto-backup` — it never switches branches or touches your working index. The ref lives outside `refs/heads/` so `git push --all` won't push it. Supports `shadow` mode for non-Git directories.
 
 ### Health Check
 
@@ -229,7 +229,7 @@ If the pre-restore backup fails, the agent will **not** proceed — it will wait
 ### Recovery priority
 
 1. **Git** — `git restore`, `git reset`, `git reflog`
-2. **Auto-backup branch** — `cursor-guard/auto-backup`
+2. **Auto-backup ref** — `refs/guard/auto-backup`
 3. **Shadow copies** — `.cursor-guard-backup/<timestamp>/`
 4. **Conversation context** — Original file content captured by agent Read calls
 5. **Editor history** — VS Code/Cursor Timeline (auxiliary)

package/README.zh-CN.md

@@ -179,7 +179,7 @@ npx cursor-guard-backup --path /my/project --interval 30
 ./references/auto-backup.sh /my/project
 ```
 
-脚本使用 Git 底层命令快照到 `cursor-guard/auto-backup` 分支——不会切换分支，也不会影响你的工作索引。支持 `shadow` 模式用于非 Git 目录。
+脚本使用 Git 底层命令快照到 `refs/guard/auto-backup`——不会切换分支，也不会影响你的工作索引。该引用位于 `refs/heads/` 之外，`git push --all` 不会推送它。支持 `shadow` 模式用于非 Git 目录。
 
 ### 健康检查
 
@@ -229,7 +229,7 @@ npx cursor-guard-doctor --path /my/project
 ### 恢复优先级
 
 1. **Git** — `git restore`, `git reset`, `git reflog`
-2. **自动备份分支** — `cursor-guard/auto-backup`
+2. **自动备份引用** — `refs/guard/auto-backup`
 3. **影子拷贝** — `.cursor-guard-backup/<时间戳>/`
 4. **对话上下文** — 代理 Read 调用捕获的原始文件内容
 5. **编辑器历史** — VS Code/Cursor Timeline（辅助）

package/SKILL.md

@@ -204,16 +204,16 @@ There are two distinct backup mechanisms. Do not confuse them:
 
 | | **Git branch snapshot** | **Shadow copy** |
 |---|---|---|
-| **What** | Commits to `cursor-guard/auto-backup` branch via plumbing | File copies to `.cursor-guard-backup/<timestamp>/` |
+| **What** | Commits to `refs/guard/auto-backup` via plumbing | File copies to `.cursor-guard-backup/<timestamp>/` |
 | **Who creates** | Auto-backup script (when `backup_strategy` = `git` or `both`) | Auto-backup script (when `backup_strategy` = `shadow` or `both`); or the agent manually (§2b) |
 | **Who cleans up** | `git_retention` config (auto, opt-in); or manual `git branch -D` | `retention` config (auto); or manual |
-| **Restore** | `git restore --source=cursor-guard/auto-backup -- <file>` | Copy file from `.cursor-guard-backup/<ts>/<file>` to original path |
+| **Restore** | `git restore --source=guard/auto-backup -- <file>` | Copy file from `.cursor-guard-backup/<ts>/<file>` to original path |
 | **Requires Git** | Yes | No (fallback for non-git repos) |
 
 **Priority order for the agent:**
 
 1. **Guard ref snapshot** (`refs/guard/snapshot`) — agent creates before each high-risk edit using temp index (§2a). Does not pollute user's branch or staging area.
-2. **Git branch auto-backup** (`cursor-guard/auto-backup`) — periodic snapshots by auto-backup script.
+2. **Git auto-backup ref** (`refs/guard/auto-backup`) — periodic snapshots by auto-backup script. Lives outside `refs/heads/` so `git push --all` won't push it.
 3. **Shadow copy** (`.cursor-guard-backup/`) — fallback for non-git repos, or as extra insurance when `backup_strategy = "both"`.
 4. **Editor habits** — Ctrl+S frequently; optional extensions are user-configured, mention only if asked.
 
@@ -267,7 +267,7 @@ If unclear, ask: "你想恢复哪个文件？还是整个项目？" / "Which fil
 git log --oneline --before="5 minutes ago" -5 -- <file>
 
 # Auto-backup branch (if exists)
-git log cursor-guard/auto-backup --oneline --before="5 minutes ago" -5 -- <file>
+git log guard/auto-backup --oneline --before="5 minutes ago" -5 -- <file>
 
 # Reflog as fallback (shows all HEAD movements)
 git reflog --before="5 minutes ago" -5
@@ -291,7 +291,7 @@ git log --oneline -<N+5> -- <file>
 git show HEAD~<N>:<file>
 
 # Auto-backup branch
-git log cursor-guard/auto-backup --oneline -<N+5> -- <file>
+git log guard/auto-backup --oneline -<N+5> -- <file>
 ```
 
 ### Step 3: Present Candidates to User
@@ -314,7 +314,7 @@ Recommended: #1 (closest to target time). Restore this one? / 推荐 #1（最接
 - If only ONE candidate is found, confirm with the user before restoring.
 - If MULTIPLE candidates, pre-select #1 (closest before target) but let the user pick another.
 - If NO candidates before the target time:
-  - Check auto-backup branch: `git rev-parse --verify cursor-guard/auto-backup`
+  - Check auto-backup ref: `git rev-parse --verify refs/guard/auto-backup`
   - Check shadow copies: `Get-ChildItem .cursor-guard-backup/ -Directory | Sort-Object Name -Descending`
   - 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.

package/package.json

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

@@ -51,7 +51,7 @@ Blacklist glob patterns. Matching files are excluded from protection even if the
 
 | Value | Description |
 |-------|-------------|
-| `"git"` | Local commits to dedicated branch `cursor-guard/auto-backup` |
+| `"git"` | Local commits to dedicated ref `refs/guard/auto-backup` |
 | `"shadow"` | File copies to `.cursor-guard-backup/<timestamp>/` |
 | `"both"` | Git branch snapshot + shadow copies |
 
@@ -155,7 +155,7 @@ Retention policy for **shadow copies** only. Git branch snapshots are not auto-c
 - **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.
+Retention policy for the **`refs/guard/auto-backup` Git ref**. By default, auto-backup commits accumulate indefinitely. Enable this to automatically prune old commits.
 
 ### Sub-fields
 

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

@@ -51,7 +51,7 @@
 
 | 值 | 说明 |
 |----|------|
-| `"git"` | 提交到专用分支 `cursor-guard/auto-backup` |
+| `"git"` | 提交到专用引用 `refs/guard/auto-backup` |
 | `"shadow"` | 文件拷贝到 `.cursor-guard-backup/<timestamp>/` |
 | `"both"` | Git 分支快照 + 影子拷贝同时进行 |
 
@@ -155,7 +155,7 @@
 - **类型**：`object`
 - **默认值**：`{ "enabled": false, "mode": "count", "max_count": 200 }`
 
-**`cursor-guard/auto-backup` Git 分支**的保留策略。默认情况下自动备份提交会无限累积。启用此项可自动裁剪旧提交。
+**`refs/guard/auto-backup` Git 引用**的保留策略。默认情况下自动备份提交会无限累积。启用此项可自动裁剪旧提交。
 
 ### 子字段
 

package/references/cursor-guard.schema.json

@@ -75,7 +75,7 @@
     },
     "git_retention": {
       "type": "object",
-      "description": "Controls automatic cleanup of old commits on the cursor-guard/auto-backup branch.",
+      "description": "Controls automatic cleanup of old commits on refs/guard/auto-backup.",
       "properties": {
         "enabled": {
           "type": "boolean",

package/references/lib/auto-backup.js

@@ -400,13 +400,24 @@ async function runBackup(projectDir, intervalOverride) {
   process.on('exit', cleanup);
 
   // Git-specific setup
-  const branch = 'cursor-guard/auto-backup';
-  const branchRef = `refs/heads/${branch}`;
+  const branchRef = 'refs/guard/auto-backup';
+  const legacyRef = 'refs/heads/cursor-guard/auto-backup';
   if (repo) {
     const exists = git(['rev-parse', '--verify', branchRef], { cwd: projectDir, allowFail: true });
     if (!exists) {
-      git(['branch', branch, 'HEAD'], { cwd: projectDir, allowFail: true });
-      console.log(color.green(`[guard] Created branch: ${branch}`));
+      // Migrate from legacy refs/heads/ location if it exists
+      const legacyHash = git(['rev-parse', '--verify', legacyRef], { cwd: projectDir, allowFail: true });
+      if (legacyHash) {
+        git(['update-ref', branchRef, legacyHash], { cwd: projectDir, allowFail: true });
+        git(['update-ref', '-d', legacyRef], { cwd: projectDir, allowFail: true });
+        console.log(color.green(`[guard] Migrated ${legacyRef} → ${branchRef}`));
+      } else {
+        const head = git(['rev-parse', 'HEAD'], { cwd: projectDir, allowFail: true });
+        if (head) {
+          git(['update-ref', branchRef, head], { cwd: projectDir, allowFail: true });
+          console.log(color.green(`[guard] Created ref: ${branchRef}`));
+        }
+      }
     }
 
     const excludeFile = path.join(gDir, 'info', 'exclude');
@@ -434,7 +445,7 @@ async function runBackup(projectDir, intervalOverride) {
   // Banner
   console.log('');
   console.log(color.cyan(`[guard] Watching '${projectDir}' every ${interval}s  (Ctrl+C to stop)`));
-  console.log(color.cyan(`[guard] Strategy: ${cfg.backup_strategy}  |  Branch: ${branch}  |  Retention: ${cfg.retention.mode}`));
+  console.log(color.cyan(`[guard] Strategy: ${cfg.backup_strategy}  |  Ref: ${branchRef}  |  Retention: ${cfg.retention.mode}`));
   console.log(color.cyan(`[guard] Log: ${logFilePath}`));
   console.log('');
 

package/references/lib/guard-doctor.js

@@ -81,15 +81,20 @@ function runDoctor(projectDir) {
     check('Strategy compatibility', 'FAIL', `unknown backup_strategy='${strategy}' (must be git/shadow/both)`);
   }
 
-  // 5. Backup branch
+  // 5. Backup ref
   if (repo) {
-    const branchRef = 'refs/heads/cursor-guard/auto-backup';
-    const exists = git(['rev-parse', '--verify', branchRef], { cwd: projectDir, allowFail: true });
+    const guardRef = 'refs/guard/auto-backup';
+    const legacyRef = 'refs/heads/cursor-guard/auto-backup';
+    const exists = git(['rev-parse', '--verify', guardRef], { cwd: projectDir, allowFail: true });
+    const legacyExists = git(['rev-parse', '--verify', legacyRef], { cwd: projectDir, allowFail: true });
     if (exists) {
-      const count = git(['rev-list', '--count', branchRef], { cwd: projectDir, allowFail: true }) || '?';
-      check('Backup branch', 'PASS', `cursor-guard/auto-backup exists (${count} commits)`);
+      const count = git(['rev-list', '--count', guardRef], { cwd: projectDir, allowFail: true }) || '?';
+      check('Backup ref', 'PASS', `refs/guard/auto-backup exists (${count} commits)`);
+    } else if (legacyExists) {
+      const count = git(['rev-list', '--count', legacyRef], { cwd: projectDir, allowFail: true }) || '?';
+      check('Backup ref', 'WARN', `legacy refs/heads/cursor-guard/auto-backup found (${count} commits) — run auto-backup once to migrate`);
     } else {
-      check('Backup branch', 'WARN', 'cursor-guard/auto-backup not created yet (will be created on first backup)');
+      check('Backup ref', 'WARN', 'refs/guard/auto-backup not created yet (will be created on first backup)');
     }
   }
 

package/references/recovery.md

@@ -268,24 +268,24 @@ The `auto-backup.ps1` script stores periodic snapshots on a dedicated branch via
 
 ```bash
 # List recent auto-backup snapshots
-git log cursor-guard/auto-backup --oneline -20
+git log guard/auto-backup --oneline -20
 
 # Restore a file from the latest auto-backup
-git restore --source=cursor-guard/auto-backup -- <path/to/file>
+git restore --source=guard/auto-backup -- <path/to/file>
 
 # Restore from a specific auto-backup snapshot
 git restore --source=<commit-hash> -- <path/to/file>
 
 # Diff your working copy against the auto-backup version
-git diff cursor-guard/auto-backup -- <path/to/file>
+git diff guard/auto-backup -- <path/to/file>
 
 # Time-based: find auto-backup snapshot from before N minutes ago
 # 按时间查找：N 分钟前之前最近的自动备份快照
-git log cursor-guard/auto-backup --oneline --before="5 minutes ago" -5 -- <path/to/file>
+git log guard/auto-backup --oneline --before="5 minutes ago" -5 -- <path/to/file>
 
 # Version-based: list recent N auto-backup snapshots
 # 按版本查找：最近 N 个自动备份快照
-git log cursor-guard/auto-backup --oneline -10 -- <path/to/file>
+git log guard/auto-backup --oneline -10 -- <path/to/file>
 ```
 
 ## If not a Git repo yet
@@ -374,10 +374,10 @@ Get-ChildItem .cursor-guard-backup/ -Directory | Where-Object {
 
 ```bash
 # View auto-backup history
-git log cursor-guard/auto-backup --oneline -30
+git log guard/auto-backup --oneline -30
 
 # Delete the branch entirely (script will recreate it on next run)
-git branch -D cursor-guard/auto-backup
+git update-ref -d refs/guard/auto-backup
 
 # Reclaim disk space after removing old branches
 git gc --prune=now