wip-file-guard

阻止对受保护的身份文件进行破坏性编辑的挂钩。适用于 Claude Code CLI 和 OpenClaw。

# wip-file-guard

Hook that blocks destructive edits to protected identity files. For Claude Code CLI and OpenClaw.

## When to Use This Skill

**Use wip-file-guard for:**
- Protecting CLAUDE.md, SOUL.md, IDENTITY.md, MEMORY.md, and other identity files from being overwritten
- Blocking AI agents from replacing file content instead of extending it
- Surviving context compaction (behavioral rules get erased, but hooks don't)

**This is a technical guardrail, not a prompt.** It blocks the operation before it happens.

### Do NOT Use For

- Protecting binary files or images
- Blocking all edits (it allows small edits, only blocks destructive ones)
- Repos without identity files

## How It Works

Two rules:

1. **Write is blocked** on protected files. Always. Use Edit instead.
2. **Edit is blocked** when it removes more than 2 net lines from a protected file.

### Protected Files

CLAUDE.md, SHARED-CONTEXT.md, SOUL.md, IDENTITY.md, CONTEXT.md, TOOLS.md, MEMORY.md

### Protected Patterns

Any file matching: memory, memories, journal, diary, daily log

## API Reference

### CLI

```bash
node guard.mjs --list          # list protected files
bash test.sh                   # run test suite
```

### Claude Code Hook

Add to `~/.claude/settings.json`:

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "node \"/path/to/wip-file-guard/guard.mjs\"",
            "timeout": 5
          }
        ]
      }
    ]
  }
}
```

## Troubleshooting

### Agent keeps trying to Write

The deny message tells the agent to re-read the file and use Edit instead. If the agent ignores it, it's likely post-compaction and has lost context. The hook will keep blocking.

### Edit blocked unexpectedly

Check the net line removal. Edits that remove more than 2 lines from a protected file are blocked. Small edits (adding or replacing 1-2 lines) are allowed.

---

## 中文说明

# wip-file-guard

阻止对受保护身份文件进行破坏性编辑的挂钩。适用于 Claude Code CLI 和 OpenClaw。

## 何时使用此技能

**在以下情况使用 wip-file-guard：**
- 保护 CLAUDE.md、SOUL.md、IDENTITY.md、MEMORY.md 及其他身份文件不被覆盖
- 阻止 AI 代理替换文件内容（而非扩展它）
- 在上下文压缩中存活（行为规则会被抹除，但挂钩不会）

**这是一道技术护栏，而非提示词。** 它在操作发生之前就将其阻止。

### 请勿用于

- 保护二进制文件或图像
- 阻止所有编辑（它允许小幅编辑，只阻止破坏性编辑）
- 没有身份文件的仓库

## 工作原理

两条规则：

1. **Write 被阻止** 于受保护文件。始终如此。请改用 Edit。
2. **Edit 被阻止** 当它从受保护文件中净删除超过 2 行时。

### 受保护文件

CLAUDE.md、SHARED-CONTEXT.md、SOUL.md、IDENTITY.md、CONTEXT.md、TOOLS.md、MEMORY.md

### 受保护模式

任何匹配以下内容的文件：memory、memories、journal、diary、daily log

## API 参考

### CLI

```bash
node guard.mjs --list          # list protected files
bash test.sh                   # run test suite
```

### Claude Code 挂钩

添加到 `~/.claude/settings.json`：

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "node \"/path/to/wip-file-guard/guard.mjs\"",
            "timeout": 5
          }
        ]
      }
    ]
  }
}
```

## 故障排查

### 代理不断尝试 Write

拒绝消息会告诉代理重新阅读文件并改用 Edit。如果代理忽略它，很可能是在压缩之后丢失了上下文。挂钩会持续阻止。

### Edit 意外被阻止

检查净删除行数。从受保护文件中删除超过 2 行的编辑会被阻止。小幅编辑（添加或替换 1-2 行）是允许的。