# PROJECT_STATE.md Locking Protocol

This protocol prevents conflicts between concurrent Claude sessions. Follow it for every significant action on any project that has a PROJECT_STATE.md.

## What Requires a Lock

- 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

Reading files, planning, and answering questions do NOT require a lock.

## The Protocol

**Step 1 — Read before acting**
Re-read PROJECT_STATE.md before starting:
- Check Active Session Locks: is anything locked that you need to touch?
- Conflicting lock < 2 hours old: stop, report to user, ask how to proceed.
- Lock > 2 hours old (stale): note it to user, clear the row, proceed.

**Step 2 — Claim your lock**
Add a row to Active Session Locks before performing the action:

| 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 the Session identifier.

**Step 3 — Perform the action**

**Step 4 — Update on completion OR failure**
1. Remove your lock row
2. Add a Recent Changes entry with status: `COMPLETE`, `FAILED`, `PARTIAL`, or `ROLLED_BACK`
3. Update Current Project State if any component status changed
4. Check off completed Pending items

## Stale Lock Rule

A lock older than 2 hours with no timestamp update is abandoned. Clear it, note `[Cleared stale lock from {session}]` in Recent Changes, then proceed.