mmxagent-guardian

# File Protection and Version Management This Skill uses MiniVCS to track all file operations with version history. **Runtime requirement**: Python 3 is required to run `scripts/minivcs/minivcs.py`. **Script location**: `scripts/minivcs/minivcs.py` in the same directory as this `SKILL.md` (Before executing, first determine the directory containing this file. It is referred to as `$SKILL_DIR` below.) **Core mechanism:** - **Modify**: Saves an incremental diff plus a full snapshot from before the modification, **supporting rollback** - **Delete**: Moves the full file into `~/.openclaw/minivcs/trash/`, **supporting restore** - **All files are indexed**, with different retention periods based on importance - **After every operation, the full record table is scanned automatically** to find expired records and ask the user for confirmation **Usage limitations:** - **Binary files (images, PDFs, audio/video, etc.)**: Text diffs cannot be generated. For binary-file protection, MiniVCS stores a full local `.bak` copy instead. This applies to binary-file backup/rollback protection, and deletion protection also stores a full local copy in `~/.openclaw/minivcs/trash/`. The user must be informed before the operation because storage usage may be relatively high. - **The first record cannot be rolled back**: When a file is recorded for the first time, there is not yet any historical baseline, so that record has no snapshot. After that, each call to `record_modify` following an edit automatically saves a snapshot, allowing rollback to the state before any edit. - **Local storage notice**: Protection data is stored locally under `~/.openclaw/minivcs/`. This Skill does not provide encryption or remote sync. --- ## Prerequisite Check: Confirm Python Is Installed **Before performing any operation, you must first check whether Python 3 is installed in the user's environment. This Skill requires Python 3 and should not run without it.** ### How to check ```bash # macOS / Linux python3 --version # Windows (PowerShell) python --version ``` - If the output is `Python 3.x.x`, it is installed and you can continue - If it says `command not found` or `is not recognized as an internal or external command`, stop and tell the user that this Skill requires Python 3 ### Dependency boundary If Python 3 is missing: - Do **not** run dependency installation commands from this Skill - Do **not** run remote install scripts such as `curl | bash` - Do **not** write to shell config files such as `~/.zshrc` or `~/.bash_profile` - Do **not** modify global environment variables on the user's behalf from this Skill - Tell the user that Python 3 is required, and ask them to install it first or explicitly authorize a separate environment-setup flow > **Note**: On some Windows systems the command is `python`, while on macOS/Linux it is `python3`. > In all commands below that use `python`, replace it with the correct command for the actual environment. --- ## Retention Policy | File Type | Retention Days | Decision Rule | |---------|---------|---------| | Important files | **14 days** | System paths (`/etc/`, `/root/`, `/usr/local/etc/`, `/opt/`), user config directories (`~/.ssh/`, `~/.gnupg/`, `~/.config/`, `~/.openclaw/`, `~/.kube/`, `~/.docker/`, `~/.aws/`, `~/.azure/`, `~/.local/share/`), Windows system directories (`C:\Windows\`, `C:\ProgramData\`, `C:\Program Files\`), config files (`.yaml/.toml/.env`, etc.), entry files (`main.py/index.ts`, etc.) | | Normal files | **7 days** | All other files | When each record is created, the `expireAt` (expiration timestamp) and `expireAtDatetime` (human-readable time) fields are set automatically. --- ## Excluded Paths (Auto-Skip) Files whose path contains any of the following segments are **automatically skipped** by `record_modify` and `record_delete`. These are generated, vendored, or cache directories that should not be version-tracked: `node_modules`, `.git`, `__pycache__`, `.venv`, `venv`, `.tox`, `.mypy_cache`, `.pytest_cache`, `.ruff_cache`, `dist`, `build`, `.next`, `.nuxt`, `.turbo` When a file is skipped, the return value will contain `"skipped": true` and a `"reason"` field. The Agent should inform the user that the file was not tracked and explain why. --- ## Binary File Size Warning When a binary file exceeds **50 MB**, the return value from `record_modify` (binary backup) will include: - `"sizeWarning": true` - `"sizeWarningMessage"`: a human-readable description of the file size and threshold **When `sizeWarning` is present, the Agent must explicitly inform the user of the file size and ask for confirmation before proceeding with any further binary backup operations on similarly large files.** --- ## Operation Flow ### Step 1: Initialize the MiniVCS Working Directory On first use, the storage directory is created automatically. No extra action is required: ```bash python "$SKILL_DIR/scripts/minivcs/minivcs.py" history --project-root <project_root> ``` All data is stored uniformly in `~/.openclaw/minivcs/`: ``` ~/.openclaw/minivcs/ logs.json # operation log (includes the expireAt field) diffs/ # incremental patches for text file modifications bases/ # baseline for the next comparison (named by full relative path, so no same-name conflicts) snapshots/ # full snapshots before text file modifications (used for rollback) trash/ # full backups of deleted files (used for restore) backups/ # full `.bak` copies of binary files (used for rollback) ``` --- ### Step 2: Ask the User for Confirmation Before the Operation **Before deleting or modifying a file, you must explain the following to the user and wait for confirmation:** 1. The file path to be operated on 2. The operation type (modify / delete) 3. The purpose and intent of the operation 4. The possible impact 5. **Explain the local storage behavior: this Skill stores protection data under `~/.openclaw/minivcs/`** 6. **For text-file modifications, explain that MiniVCS stores diffs and snapshots so the file can be rolled back** 7. **For deletions, explain that MiniVCS stores a full local copy in `~/.openclaw/minivcs/trash/` so the file can be restored** 8. **If the file is binary, explicitly explain that protection uses a full local copy rather than a text diff, and ask whether the user wants that local copy to be stored before deletion or binary-file protection** 9. **If a binary backup returns `sizeWarning: true`, the Agent must display the file size and warning message to the user, and ask for explicit confirmation before proceeding** If the file is binary and the user does **not** want a local stored copy, do not treat the operation as a protected delete/rollback flow under this Skill. If the path is auto-skipped (return contains `"skipped": true`), inform the user that the file was not tracked and state the reason. Example before the operation: ``` I am about to operate on the following file. Please confirm: - File: /path/to/file.py - Operation: delete - Reason: This file has been replaced by a newer version and is no longer used - Impact: Need to confirm that no other module imports this file - Local storage: A full local copy will be stored under ~/.openclaw/minivcs/trash/ so the file can be restored later - Protection: The stored copy will be retained for 7 days (14 days for important files), and can be restored at any time during that period Do you want to continue? ``` Example for a binary file before deletion: ``` I am about to delete the following binary file. Please confirm: - File: /path/to/file.pdf - Operation: delete - Reason: This file is no longer needed - Impact: The original file will be removed from its current location - Local storage: To protect this binary file, I need to store one full local copy under ~/.openclaw/minivcs/trash/ - Note: Binary files are protected with full copies rather than text diffs, so this may use more disk space Do you want me to keep that local backup before deletion? ``` After the operation completes, **you must inform the user of the record result**, for example: ``` # After a modification is completed The modification to path/to/file.py has been completed, and this change has been recorded (Record ID: 1710000000000). - Change summary: +5 lines, -2 lines - Retention period: 7 days (expires at: 2026-03-20 10:00:00) - Rollback available: yes (use restore 1710000000000 to recover the state before the modification) If you want to view the diff or roll it back, let me know. # After a deletion is completed path/to/file.py has been moved to the trash and backed up (Record ID: 1710000001000). - Retention period: 14 days (expires at: 2026-03-27 10:00:00) [important file] If you want to restore this file, let me know. ``` --- ### Step 3: Operate on Files with MiniVCS #### Modify a file (supports rollback) **Just call `record` once after each edit**. The snapshot chain is formed automatically and supports rolling back to any historical state: ``` First time using this file → record() → base established (no snapshot, first record cannot be rolled back) Edit → C1 → record() → snapshot=initial content, R1 rollback available Edit → C2 → record() → snapshot=C1, R2 rollback available → restoring R2 gives C1 Edit → C3 → record() → snapshot=C2, R3 rollback available → restoring R3 gives C2 (that is, the state at time t2) ``` ```bash # Run once after each edit is completed python "$SKILL_DIR/scripts/minivcs/minivcs.py" record <file_path> --project-root <project_root> # Output containing "Rollback: available" means the snapshot has been saved and can be rolled back ``` Python API: ```python import sys, os sys.path.insert(0, os.path.join(SKILL_DIR, "scripts", "minivcs")) from minivcs import MiniVCS vcs = MiniVCS(project_root="/path/to/project") # Call once after each edit result = vcs.record_modify("path/to/file.py") # result includes: # { # "success": True, # "recordId": "...", # "summary": "+5 lines, -2 lines", # "canRollback": True, # True when a snapshot exists; False for the first record # "snapshotFile": "...", # "isImportant": False, # "retentionDays": 7, # "due_for_cleanup": [...] # } ``` #### Delete a file (supports restore) **Do not delete the file directly**. Use `record_delete` instead, and the file is moved into `trash` automatically. Before running `record_delete`: - Tell the user that a full local copy will be stored in `~/.openclaw/minivcs/trash/` - If the file is binary, explicitly ask whether they want that local copy to be stored - Only proceed with protected deletion after the user confirms the local storage behavior ```bash python "$SKILL_DIR/scripts/minivcs/minivcs.py" delete <file_path> --project-root <project_root> ``` Python API: ```python result = vcs.record_delete("path/to/file.py") # result includes: # { # "success": True, # "recordId": "...", # "trashFile": "~/.openclaw/minivcs/trash/1234567_file.py.bak", # "isImportant": True, # "retentionDays": 14, # "due_for_cleanup": [...] # } ``` #### Restore / Roll back The same `restore` command handles both scenarios: ```bash # DELETE record -> restore the file to its original path # MODIFY record (with snapshot) -> roll back to the state before the modification python "$SKILL_DIR/scripts/minivcs/minivcs.py" restore <record_id> --project-root <project_root> ``` Python API: ```python result = vcs.restore_file(record_id="...") # After DELETE succeeds: the record is marked as RESTORED and no longer appears in the trash list # After MODIFY succeeds: the record is marked as ROLLED_BACK # Repeated restore: returns {"success": False, "error": "already been restored/rolled_back"} ``` --- ### Step 4: Handle Expired Cleanup Notifications (must be done after every operation) After each call to `record_modify` or `record_delete`, the return value contains the `due_for_cleanup` field. **If `due_for_cleanup` is not empty, the Agent must:** 1. Show the user the list of expired records (sorted from earliest to latest) 2. Ask which ones can be deleted and which ones need an extension Example display format: ``` The following N historical records have expired. Please confirm whether they can be cleaned up: [1] ID=1710000000000 File=src/old.py Action=MODIFY Recorded at=2026-03-01 10:00:00 Expires at=2026-03-08 10:00:00 [2] ID=1710000001000 File=config.yaml Action=DELETE [important file] Recorded at=2026-02-28 09:00:00 Expires at=2026-03-14 09:00:00 Can these records be deleted? (delete all / specify which ones to extend) ``` Handling after the user responds: ```python # The user confirms deleting all result = vcs.delete_due_records(record_ids=["id1", "id2"]) # The user says not to delete one record yet -> extend by one retention cycle (7 days or 14 days) result = vcs.extend_record_expiry(record_id="id1") ``` Command line: ```bash # View all expired records python "$SKILL_DIR/scripts/minivcs/minivcs.py" cleanup --project-root <project_root> # Confirm cleanup python "$SKILL_DIR/scripts/minivcs/minivcs.py" cleanup --confirm --project-root <project_root> # Extend one record python "$SKILL_DIR/scripts/minivcs/minivcs.py" extend <record_id> --project-root <project_root> ``` --- ## Other Common Operations ```bash # View operation history (records marked [rollback available] can be rolled back) python "$SKILL_DIR/scripts/minivcs/minivcs.py" history --project-root <project_root> python "$SKILL_DIR/scripts/minivcs/minivcs.py" history <file_path> -d --project-root <project_root> # View files in trash that have not yet been restored python "$SKILL_DIR/scripts/minivcs/minivcs.py" trash --project-root <project_root> # Delete a specified record (clean both the log and the physical file) python "$SKILL_DIR/scripts/minivcs/minivcs.py" remove <record_id> --project-root <project_root> ``` --- ## Record Field Reference | Field | Type | Description | |------|------|------| | `recordId` | string | Unique record ID (millisecond timestamp) | | `filePath` | string | Relative or absolute path | | `action` | string | `MODIFY` / `DELETE` / `BINARY_BACKUP` / `RESTORED` / `ROLLED_BACK` | | `timestamp` | number | Creation time (milliseconds) | | `datetime` | string | Creation time (human-readable) | | `isImportant` | bool | Whether the file is important | | `retentionDays` | number | Retention days (7 or 14) | | `expireAt` | number | Expiration time (milliseconds) | | `expireAtDatetime` | string | Expiration time (human-readable) | | `diffFile` | string | Diff patch path (MODIFY only) | | `snapshotFile` | string | Pre-modification snapshot path (only present when MODIFY has a snapshot) | | `trashFile` | string | Trash backup path (DELETE only) | | `backupFile` | string | `.bak` copy path (BINARY_BACKUP only) | | `summary` | string | Change summary | --- ## Full Operation Flow Diagram ``` The user requests a modification/deletion │ ▼ [Ask for confirmation] Explain the purpose, impact, and existing protection -> wait for user confirmation │ ├─── Modify file ───────────────────────────────────────────────┐ │ 1. Perform the actual modification │ │ 2. record_modify (Diff + snapshot -> canRollback=True) │ │ snapshot = content before this modification, so │ │ historical states can be rolled back step by step │ │ │ └─── Delete file ──────────────────────────────────────────────┤ record_delete (move to trash, do not delete directly) │ │ ┌─────────────────────────────────────────┘ ▼ Tell the user: Record ID / retention period / rollback or restore availability │ ▼ Check the returned value `due_for_cleanup` │ ┌───────────┴───────────┐ Expired records exist No expired records │ │ ▼ ▼ Show expired records Operation complete (from earliest to latest) Ask the user for confirmation │ ┌───────┴──────────┐ Confirm deletion Do not delete yet │ │ ▼ ▼ delete_due_records extend_record_expiry (extend by one retention cycle) ------- When the user needs rollback/restore ------- User: "Help me restore/roll back xxx" │ ▼ restore_file(record_id) ├── DELETE record -> restore from trash and mark as RESTORED └── MODIFY record (with snapshot) -> write back snapshot content and mark as ROLLED_BACK ```