chore: add PROJECT_STATE.md action protocol to CLAUDE.md

Formalizes the read → lock → act → release cycle for any project
that has a PROJECT_STATE.md. Every Claude instance must:
- Re-read state before any action (not just at session start)
- Claim a lock row before touching any component
- Release lock + log result on completion or failure
- Clear stale locks (>2h) before proceeding
Applies to code edits, git ops, SSH/deploy, DB migrations, builds.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.claude/CLAUDE.md

@@ -213,6 +213,74 @@ At session start:
 
 ---
 
+## PROJECT_STATE.md Action Protocol (MANDATORY for any project that has this file)
+
+This protocol prevents conflicts between concurrent Claude sessions working on the same project. It is **not optional** — follow it for every significant action.
+
+### What counts as an action
+
+Any of the following requires the full read → lock → update → release cycle:
+- Editing or creating source code files
+- Git commit or push
+- SSH command that modifies a server (deploy, install, config change, service restart)
+- Database schema change or data migration
+- Build pipeline modification
+- Any operation listed in the project's Component Ownership Map
+
+Reading files, planning, and answering questions do NOT require a lock.
+
+### The protocol
+
+**Step 1 — Read before acting**
+Before starting any action, re-read PROJECT_STATE.md:
+- Check Active Session Locks: is anything locked that you need to touch?
+- If there is a conflicting lock that is NOT stale (< 2 hours old): stop, report the conflict to the user, ask how to proceed.
+- If locks are stale (> 2 hours, last updated timestamp): note it to the user, clear the stale row, proceed.
+
+**Step 2 — Claim your lock**
+Immediately before performing the action, add a row to the Active Session Locks table:
+
+| Session | Working On | Status | Blocks | Started |
+|---------|-----------|--------|--------|---------|
+| DESKTOP-0O8A1RL/Claude | Brief description | IN_PROGRESS | What others must avoid | HH:MM UTC |
+
+Use `{machine}/{Claude or agent description}` as Session identifier.
+Use the machine name from identity.json.
+
+**Step 3 — Perform the action**
+
+**Step 4 — Update on completion OR failure**
+Immediately after the action finishes (regardless of outcome):
+1. Remove your lock row from Active Session Locks
+2. Add an entry to Recent Changes:
+   - Status: `COMPLETE`, `FAILED`, `PARTIAL`, or `ROLLED_BACK`
+   - If FAILED or PARTIAL: describe what state things were left in
+3. Update the Current Project State table if any component status changed
+4. Check off completed items in Pending / Next Up if applicable
+
+### Anti-patterns (never do these)
+
+❌ Starting work without reading PROJECT_STATE.md first
+❌ Forgetting to claim a lock before touching a component
+❌ Leaving a lock row in place after finishing (even on failure)
+❌ Skipping the Recent Changes entry when work completes
+❌ Letting a lock go stale — update the timestamp if a task takes longer than expected
+
+### Stale lock rule
+
+A lock older than 2 hours with no timestamp update is considered abandoned. Any session may clear it and claim the component, but must note in Recent Changes: `[Cleared stale lock from {session}]` before proceeding.
+
+### Example — correct flow
+
+```
+[Reading PROJECT_STATE.md — no active locks on server/src/]
+[Updating PROJECT_STATE.md — adding lock: "DESKTOP-0O8A1RL/Claude | POST /api/enroll endpoint | IN_PROGRESS | server/src/, migrations/ | 14:32 UTC"]
+[... writing code, running migration ...]
+[Updating PROJECT_STATE.md — removing lock, adding Recent Changes: "POST /api/enroll implemented | COMPLETE", updating component status: "Enrollment endpoint | IMPLEMENTED"]
+```
+
+---
+
 ## Projects
 
 **ClaudeTools** -- MSP Work Tracking System (Production-Ready)