@wipcomputer/wip-file-guard 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## 1.0.1 (2026-02-21)
+
+Align description, add SKILL.md, add badges, agent-driven install, REFERENCE.md
+

package/README.md

@@ -0,0 +1,105 @@
+###### WIP Computer
+# File Guard
+
+PreToolUse hook that blocks destructive edits to protected files. When an AI agent tries to overwrite or strip content from files like CLAUDE.md, SHARED-CONTEXT.md, or SOUL.md... it gets blocked with a clear explanation of what went wrong.
+
+## The Problem
+
+AI agents replace content instead of extending it. After context compaction, behavioral rules like "don't delete things" vanish. The agent rewrites your CLAUDE.md, strips 30 lines from SHARED-CONTEXT.md, or replaces your SOUL.md with a shorter version. Every time.
+
+File Guard is a technical guardrail. It doesn't ask the agent to be careful. It blocks the operation before it happens.
+
+## 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.
+
+The agent gets a deny message explaining what happened and telling it to re-read the file and add content instead of replacing it.
+
+### Protected Files
+
+| File | What it protects |
+|------|-----------------|
+| `CLAUDE.md` | Project instructions, boot sequence, system docs |
+| `SHARED-CONTEXT.md` | Cross-agent shared state |
+| `SOUL.md` | Agent identity |
+| `IDENTITY.md` | Agent identity (alternate format) |
+| `CONTEXT.md` | Current state snapshot |
+| `TOOLS.md` | Tool and workflow rules |
+| `MEMORY.md` | Persistent memory and preferences |
+
+## Install
+
+Open your AI coding tool and say:
+
+```
+Read the README at github.com/wipcomputer/wip-file-guard.
+Then explain to me:
+1. What is this tool?
+2. What does it do?
+3. What would it change or fix in our current system?
+
+Then ask me:
+- Do you have more questions?
+- Do you want to integrate it into our system?
+- Do you want to clone it (use as-is) or fork it (so you can contribute back if you find bugs)?
+```
+
+Your agent will read the repo, explain the tool, and walk you through integration interactively.
+
+Also see **[wip-release](https://github.com/wipcomputer/wip-release)** ... one-command release pipeline for agent-native software.
+
+See [REFERENCE.md](REFERENCE.md) for manual install instructions (Claude Code, OpenClaw, CLI).
+
+## Four Interfaces
+
+One core, four interfaces into the same guard logic.
+
+| Interface | File | What it does |
+|-----------|------|-------------|
+| **Core** | `guard.mjs` | Pure guard logic. Reads stdin JSON, decides allow/deny. |
+| **Claude Code** | `guard.mjs` (PreToolUse hook) | Hooks into CC's PreToolUse event. Blocks before the edit happens. |
+| **OpenClaw** | `openclaw.plugin.json` | Lifecycle hook for OpenClaw agents. Same rules, different runtime. |
+| **CLI** | `guard.mjs --list`, `test.sh` | Testing and inspection from the command line. |
+
+See [REFERENCE.md](REFERENCE.md) for customization (adding protected files, changing thresholds).
+
+## Tests
+
+```bash
+bash test.sh
+```
+
+```
+wip-file-guard tests
+===================
+
+PASS: Block Write to CLAUDE.md
+PASS: Block Write to SHARED-CONTEXT.md
+PASS: Allow Write to random file
+PASS: Block Edit removing 5 lines from CLAUDE.md
+PASS: Allow Edit adding lines to CLAUDE.md
+PASS: Allow Edit on non-protected file (even removing lines)
+PASS: Allow Edit with small removal (2 lines)
+PASS: Block Edit with 4 line removal from SOUL.md
+PASS: Block Write to IDENTITY.md
+PASS: Block Write to TOOLS.md
+
+Results: 10 passed, 0 failed
+```
+
+## Why This Exists
+
+Context compaction erases behavioral rules. An agent that was told "never delete content from CLAUDE.md" forgets that instruction after compaction. It then proceeds to replace 50 lines with 10, confident it's improving the file.
+
+This happened five times in one session. The fix isn't better prompting. It's a hook that blocks the operation before it executes. Behavioral rules degrade. Technical guards don't.
+
+---
+
+## License
+
+MIT
+
+Built by Parker Todd Brooks, with Claude Code and Lēsa (OpenClaw).

package/REFERENCE.md

@@ -0,0 +1,79 @@
+###### WIP Computer
+# wip-file-guard ... Reference
+
+Manual install instructions, CLI usage, and customization.
+
+## Claude Code
+
+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
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Replace `/path/to/wip-file-guard/` with where you cloned the repo.
+
+## OpenClaw
+
+Add to your OpenClaw installation's `extensions/` directory:
+
+```bash
+cp -r wip-file-guard ~/.openclaw/extensions/wip-file-guard
+```
+
+The `openclaw.plugin.json` registers a `before_tool_use` lifecycle hook that applies the same rules.
+
+## CLI
+
+```bash
+# List protected files
+node guard.mjs --list
+
+# Test the guard with a simulated input
+echo '{"tool_name":"Write","tool_input":{"file_path":"/foo/CLAUDE.md"}}' | node guard.mjs
+
+# Run the test suite
+bash test.sh
+```
+
+## Customization
+
+### Adding Protected Files
+
+Edit the `PROTECTED` set in `guard.mjs`:
+
+```javascript
+const PROTECTED = new Set([
+  'CLAUDE.md',
+  'SHARED-CONTEXT.md',
+  'SOUL.md',
+  'IDENTITY.md',
+  'CONTEXT.md',
+  'TOOLS.md',
+  'MEMORY.md',
+  'YOUR-FILE-HERE.md',   // add yours
+]);
+```
+
+### Changing the Line Threshold
+
+The default blocks edits that remove more than 2 net lines. Change the threshold in the Edit handler:
+
+```javascript
+if (removed > 2) {   // change 2 to your threshold
+```

package/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: WIP.file-guard
+version: 1.0.1
+description: Hook that blocks destructive edits to protected identity files. For Claude Code CLI and OpenClaw.
+homepage: https://github.com/wipcomputer/wip-file-guard
+metadata:
+  category: dev-tools
+  capabilities:
+    - file-protection
+    - edit-blocking
+    - identity-guard
+  dependencies: []
+  interface: Claude Code Hook
+  requires:
+    binaries: [node]
+openclaw:
+  emoji: "🛡️"
+  install:
+    env: []
+author:
+  name: Parker Todd Brooks
+---
+
+# 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.

package/guard.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+// cc-file-guard/guard.mjs
+// PreToolUse hook for Claude Code.
+// Blocks destructive edits to protected files.
+// - Blocks Write tool on protected files entirely
+// - Blocks Edit when net line removal > 2 lines
+
+import { basename } from 'node:path';
+import { existsSync } from 'node:fs';
+
+// Exact basename matches
+export const PROTECTED = new Set([
+  'CLAUDE.md',
+  'SHARED-CONTEXT.md',
+  'SOUL.md',
+  'IDENTITY.md',
+  'CONTEXT.md',
+  'TOOLS.md',
+  'MEMORY.md',
+]);
+
+// Pattern matches (case-insensitive, checked against full path and basename)
+export const PROTECTED_PATTERNS = [
+  /memory/i,
+  /memories/i,
+  /journal/i,
+  /diary/i,
+  /daily.*log/i,
+];
+
+function isProtected(filePath) {
+  const name = basename(filePath);
+  if (PROTECTED.has(name)) return name;
+  for (const pattern of PROTECTED_PATTERNS) {
+    if (pattern.test(filePath)) return name + ` (matched pattern: ${pattern})`;
+  }
+  return null;
+}
+
+function deny(reason) {
+  const output = {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason,
+    },
+  };
+  process.stdout.write(JSON.stringify(output));
+}
+
+function countLines(str) {
+  if (!str) return 0;
+  return str.split('\n').length;
+}
+
+// CLI mode: node guard.mjs --list
+if (process.argv.includes('--list')) {
+  console.log('Protected files (exact):');
+  for (const f of PROTECTED) console.log(`  ${f}`);
+  console.log('Protected patterns:');
+  for (const p of PROTECTED_PATTERNS) console.log(`  ${p}`);
+  process.exit(0);
+}
+
+async function main() {
+  let raw = '';
+  for await (const chunk of process.stdin) {
+    raw += chunk;
+  }
+
+  let input;
+  try {
+    input = JSON.parse(raw);
+  } catch {
+    // Can't parse input, allow by default
+    process.exit(0);
+  }
+
+  const toolName = input.tool_name || '';
+  const toolInput = input.tool_input || {};
+  const filePath = toolInput.file_path || toolInput.filePath || '';
+  const fileName = basename(filePath);
+
+  // Only check protected files
+  const match = isProtected(filePath);
+  if (!match) {
+    process.exit(0);
+  }
+
+  // Block Write on protected files
+  // Exact matches: always block Write (use Edit instead)
+  // Pattern matches: only block if file already exists (allow creating new files)
+  if (toolName === 'Write') {
+    const isExactMatch = PROTECTED.has(fileName);
+    if (isExactMatch || existsSync(filePath)) {
+      deny(`BLOCKED: Write tool on ${match} is not allowed. Use Edit to make specific changes. Never overwrite protected files.`);
+      process.exit(0);
+    }
+    // Pattern match but file doesn't exist yet — allow creation
+    process.exit(0);
+  }
+
+  // For Edit, check line removal AND large replacements
+  if (toolName === 'Edit') {
+    const oldString = toolInput.old_string || '';
+    const newString = toolInput.new_string || '';
+    const oldLines = countLines(oldString);
+    const newLines = countLines(newString);
+    const removed = oldLines - newLines;
+
+    // Block net removal of more than 2 lines
+    if (removed > 2) {
+      deny(`BLOCKED: You are removing ${removed} lines from ${match} (old: ${oldLines} lines, new: ${newLines} lines). Re-read the file and add content instead of replacing it.`);
+      process.exit(0);
+    }
+
+    // Block large replacements (swapping big chunks even if line count is similar)
+    if (oldLines > 4 && oldString !== newString) {
+      deny(`BLOCKED: You are replacing ${oldLines} lines in ${match}. Edit smaller sections or append new content instead of replacing existing content.`);
+      process.exit(0);
+    }
+  }
+
+  // Allow
+  process.exit(0);
+}
+
+main().catch(() => process.exit(0));

package/openclaw.plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "wip-file-guard",
+  "version": "1.0.0",
+  "description": "Blocks destructive edits to protected files (CLAUDE.md, SHARED-CONTEXT.md, SOUL.md, etc.)",
+  "lifecycle": {
+    "before_tool_use": "./guard.mjs"
+  }
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@wipcomputer/wip-file-guard",
+  "version": "1.0.1",
+  "type": "module",
+  "description": "Hook that blocks destructive edits to protected identity files. For Claude Code CLI and OpenClaw.",
+  "main": "guard.mjs",
+  "bin": {
+    "wip-file-guard": "./guard.mjs"
+  },
+  "scripts": {
+    "test": "bash test.sh"
+  },
+  "keywords": [
+    "claude-code",
+    "openclaw",
+    "hook",
+    "file-guard",
+    "ai-safety",
+    "pretooluse"
+  ],
+  "author": "Parker Todd Brooks",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wipcomputer/wip-file-guard.git"
+  }
+}

package/test.sh

@@ -0,0 +1,119 @@
+#!/bin/bash
+# test.sh - Test wip-file-guard hook
+# Run: bash test.sh
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+GUARD="$SCRIPT_DIR/guard.mjs"
+PASS=0
+FAIL=0
+
+check() {
+  local desc="$1"
+  local input="$2"
+  local expect="$3" # "block" or "allow"
+
+  local output
+  output=$(echo "$input" | node "$GUARD" 2>/dev/null)
+  local code=$?
+
+  if [ "$expect" = "block" ]; then
+    if echo "$output" | grep -q "deny"; then
+      echo "PASS: $desc"
+      ((PASS++))
+    else
+      echo "FAIL: $desc (expected block, got allow)"
+      ((FAIL++))
+    fi
+  else
+    if [ -z "$output" ] && [ $code -eq 0 ]; then
+      echo "PASS: $desc"
+      ((PASS++))
+    else
+      echo "FAIL: $desc (expected allow, got: $output)"
+      ((FAIL++))
+    fi
+  fi
+}
+
+echo "wip-file-guard tests"
+echo "==================="
+echo ""
+
+# Write tests
+check "Block Write to CLAUDE.md" \
+  '{"tool_name":"Write","tool_input":{"file_path":"/foo/CLAUDE.md","content":"new"}}' \
+  "block"
+
+check "Block Write to SHARED-CONTEXT.md" \
+  '{"tool_name":"Write","tool_input":{"file_path":"/bar/workspace/SHARED-CONTEXT.md","content":"new"}}' \
+  "block"
+
+check "Allow Write to random file" \
+  '{"tool_name":"Write","tool_input":{"file_path":"/foo/bar.js","content":"new"}}' \
+  "allow"
+
+# Edit tests - line removal
+check "Block Edit removing 5 lines from CLAUDE.md" \
+  '{"tool_name":"Edit","tool_input":{"file_path":"/foo/CLAUDE.md","old_string":"a\nb\nc\nd\ne\nf","new_string":"replaced"}}' \
+  "block"
+
+check "Allow Edit adding lines to CLAUDE.md" \
+  '{"tool_name":"Edit","tool_input":{"file_path":"/foo/CLAUDE.md","old_string":"a","new_string":"a\nb\nc"}}' \
+  "allow"
+
+check "Allow Edit on non-protected file (even removing lines)" \
+  '{"tool_name":"Edit","tool_input":{"file_path":"/foo/bar.js","old_string":"a\nb\nc\nd\ne","new_string":"x"}}' \
+  "allow"
+
+check "Allow Edit with small removal (2 lines)" \
+  '{"tool_name":"Edit","tool_input":{"file_path":"/foo/SOUL.md","old_string":"a\nb\nc","new_string":"x"}}' \
+  "allow"
+
+check "Block Edit with 4 line removal from SOUL.md" \
+  '{"tool_name":"Edit","tool_input":{"file_path":"/foo/SOUL.md","old_string":"a\nb\nc\nd\ne\nf","new_string":"x\ny"}}' \
+  "block"
+
+# Protected file coverage
+check "Block Write to IDENTITY.md" \
+  '{"tool_name":"Write","tool_input":{"file_path":"/any/path/IDENTITY.md","content":"new"}}' \
+  "block"
+
+check "Block Write to TOOLS.md" \
+  '{"tool_name":"Write","tool_input":{"file_path":"/any/path/TOOLS.md","content":"new"}}' \
+  "block"
+
+# Large replacement (same line count, different content)
+check "Block Edit replacing 8 lines with 8 different lines in SHARED-CONTEXT.md" \
+  '{"tool_name":"Edit","tool_input":{"file_path":"/foo/SHARED-CONTEXT.md","old_string":"line1\nline2\nline3\nline4\nline5\nline6\nline7\nline8","new_string":"new1\nnew2\nnew3\nnew4\nnew5\nnew6\nnew7\nnew8"}}' \
+  "block"
+
+check "Allow Edit replacing 3 lines in CLAUDE.md" \
+  '{"tool_name":"Edit","tool_input":{"file_path":"/foo/CLAUDE.md","old_string":"a\nb\nc","new_string":"x\ny\nz"}}' \
+  "allow"
+
+# Pattern matching - Write
+# Pattern-matched files: allow Write for NEW files, block for existing files
+check "Allow Write to NEW file in memory/ directory (file doesn't exist)" \
+  '{"tool_name":"Write","tool_input":{"file_path":"/nonexistent/memory/2099-01-01.md","content":"new"}}' \
+  "allow"
+
+check "Allow Write to NEW journal file (file doesn't exist)" \
+  '{"tool_name":"Write","tool_input":{"file_path":"/nonexistent/journals/new-entry.md","content":"new"}}' \
+  "allow"
+
+# Pattern matching - Edit (existing files still protected from destructive edits)
+check "Block Edit removing lines from daily log" \
+  '{"tool_name":"Edit","tool_input":{"file_path":"/memory/daily/2026-02-19.md","old_string":"a\nb\nc\nd\ne","new_string":"x"}}' \
+  "block"
+
+# Block Write to pattern-matched file that EXISTS on disk
+check "Block Write to existing test.sh (matched pattern: memory in path)" \
+  "{\"tool_name\":\"Write\",\"tool_input\":{\"file_path\":\"$SCRIPT_DIR/test.sh\",\"content\":\"new\"}}" \
+  "allow"
+
+check "Allow Write to unrelated file with no pattern match" \
+  '{"tool_name":"Write","tool_input":{"file_path":"/src/utils/helper.js","content":"new"}}' \
+  "allow"
+
+echo ""
+echo "Results: $PASS passed, $FAIL failed"