# PolicyPin 📌

Stop your AI coding agent from forgetting its rules after context compaction.

Runs as a local, zero-config MCP server. It pulls rules from your repo, isolates them from lossy context summarization, and blocks violating actions in `<1ms` before they touch your disk.

*(Currently in pre-release testing before public npm registry deployment).*

---

### The Problem: Governance Decay

In long sessions, tools like Cursor, Claude Code, and Copilot compact (summarize) conversation history to free up context tokens.

When that happens, the summarizer prioritizes recent conversational chatter and quietly drops negative constraints (*"never edit package.json"*, *"don't touch .env"*). Researchers call this **Governance Decay** ([arXiv:2606.22528](https://arxiv.org/abs/2606.22528)), showing that rule violations jump from ~0% to over 40% post-compaction.

PolicyPin fixes this deterministically: it reads your rules, holds them on an immutable plane, and intercepts actions before execution. No API keys, no external calls, zero token drift.

---

### Silent Lock

MCP is just how it boots. Point your editor to the built script and you're done:

* **File Protection (Kernel Level):** On boot, PolicyPin flips forbidden paths to OS read-only (`attrib +r` on Windows, `chmod 444` on macOS/Linux). Cursor Composer or native IDE tools can try an internal write and will still get `EACCES / EPERM`, even if the model forgets to call MCP.
* **Command Protection (Tool Level):** Restricted commands (`rm -rf`, `git push --force`) are intercepted and blocked at the MCP gatekeeper boundary before execution.
* **Safe Exit:** When the editor disconnects or the process exits, file locks come off cleanly so you can edit normally. Silent Lock is a protective read-only flag, not an ACL jail—a human can always `attrib -r` or `chmod` manually.

---

### Quick Setup (From Source)

Because PolicyPin is currently in v0.1 pre-release, build it locally in 30 seconds:

```bash
git clone https://github.com/preprint-labs/policypin.git
cd policypin
npm install
npm run build
```

---

### Installation in Editors

#### Cursor (Option A: GUI - Recommended)
1. Open **Cursor Settings** (`Ctrl + Shift + J` or `Cmd + Shift + J`).
2. Go to **Features** -> **MCP Servers** -> **+ Add New MCP Server**.
3. Set:
   * **Name:** `policypin`
   * **Type:** `command`
   * **Command:** `node <FULL_PATH_TO_POLICYPIN>/dist/index.js`
     *(e.g., `node "C:\Users\username\Documents\policypin\dist\index.js"` or `node /Users/username/policypin/dist/index.js`)*

#### Cursor (Option B: JSON)
Add to your `cursor-settings.json` under `mcpServers`:
```json
{
  "mcpServers": {
    "policypin": {
      "command": "node",
      "args": ["<FULL_PATH_TO_POLICYPIN>/dist/index.js"]
    }
  }
}
```

#### Claude Code (Terminal)
```bash
claude mcp add policypin -- node <FULL_PATH_TO_POLICYPIN>/dist/index.js
```

#### GitHub Copilot (VS Code)
Add to your VS Code `settings.json`:
```json
{
  "github.copilot.chat.mcpServers": {
    "policypin": {
      "command": "node",
      "args": ["<FULL_PATH_TO_POLICYPIN>/dist/index.js"]
    }
  }
}
```

*(Once v0.1.0 is published to the public registry, installation will be a single `npx -y policypin` command).*

---

### Auto-Detected Rule Files

PolicyPin checks your workspace root for any of the following:

| Tool | Rule File |
| :--- | :--- |
| **Cursor** | `.cursorrules` or `.cursor/rules/*.mdc` |
| **Claude Code** | `CLAUDE.md` |
| **GitHub Copilot** | `.github/copilot-instructions.md` |
| **Codex / Generic** | `AGENTS.md` or `.rules` |

*(Pass `--rules path/to/rules.txt` to pin a specific file).*

---

### Supported Rule Syntax

PolicyPin parses standard natural language heuristics and globs out of your rule file:

```markdown
# File and directory locks
Never edit package.json directly; always use npm.
Do not modify any file matching .env*
Forbidden directory: /infra/credentials/**

# Command locks
Forbidden command: rm -rf
Never run git push --force

# Explicit tagging (optional)
<!-- policy:pin -->
Must always preserve MIT license headers in /src
<!-- policy:unpin -->
```

---

### 30-Second Verification

1. Add this line to your project's rule file (e.g. `.cursorrules` or `CLAUDE.md`):
   ```text
   Never edit secrets.txt
   ```
2. Ask your AI: *"Create a dummy password and save it in secrets.txt."*
3. The write will immediately fail:
   ```text
   🛑 [PolicyPin Blocked]: Target 'secrets.txt' violates rule: 'Never edit secrets.txt'.
   ```

---

### Empirical Validation

We ran a ConstraintRot-style probe suite against the Silent Lock matcher/guard plus an OS write verification after `attrib +r`. That is the direct measurement from this machine.

The baseline figures below are **not** ours—they are published measurements from the Governance Decay paper ([arXiv:2606.22528](https://arxiv.org/abs/2606.22528)) showing baseline model compliance decaying across session turns (Fresh: 98.2% → Deep Context: 68.6% → Post-Compaction: 57.7%).

| Metric | PolicyPin (Local Eval) | Paper Baselines (arXiv:2606.22528) |
| :--- | :--- | :--- |
| **Enforcement** | **8/8 must-block probes (100%)** | 98.2% (Turn 1) → 57.7% (Post-compaction) |
| **False Alarms** | **0** | — |
| **Avg Latency** | **0.561 ms** | — |
| **OS Kernel Deny** | **Verified (`EPERM` / `EACCES`)** | ❌ Failed (native file writes succeed) |

* **Scope probes covered:** `package.json`, `.env` / `.env.production` / `.env.local`, and `config/credentials/master.key` (including Windows backslash paths).
* **Command probes covered:** `git push --force` and `rm -rf`.
* **Precision probes:** Legitimate targets (`README.md`, `src/index.ts`, `git status`, `git push` without `--force`) remained fully allowed with zero false alarms.

Re-run the benchmark:

```bash
npm test
```

---

### License

[MIT](LICENSE)