task-graph-commit-lock

Git Commit Lock Pattern

Serialize git operations across multiple concurrent agents using a well-known sentinel task as a mutex. This pattern uses existing task-graph primitives (claim/release) -- no code changes or new tools are needed.

Prerequisite: Understand task-graph-basics for tool reference.

---

The Problem

When multiple agents work in the same repository concurrently, their git operations can collide:

• Two agents run git add + git commit simultaneously
• One agent's git pull --rebase conflicts with another's in-flight commit
• Merge conflicts arise from interleaved staging and committing

Git's index is a shared mutable resource. Without serialization, concurrent agents produce merge conflicts, lost commits, or corrupted state.

---

The Solution: Sentinel Task as Mutex

Create a well-known task with a reserved ID (e.g., _lock:git-commit) that serves as a mutex. Agents must claim this task before performing git operations and release it immediately after.

How It Works

The task-graph claiming system already provides the semantics we need:

1. claim() transitions a task to working (a timed state), which sets exclusive ownership. If another agent already owns it, the claim fails.
2. update(status="pending") releases ownership by transitioning to a non-timed state, making the task claimable again.

This is exactly a mutex lock/unlock pattern.

---

Setup: Create the Sentinel Task

The coordinator (or any agent during project setup) creates the sentinel task once:

create(
  id="_lock:git-commit",
  title="[LOCK] Git Commit Serialization",
  description="Sentinel task for serializing git operations. Claim before git add/commit/push, release after. Do NOT complete or delete this task.",
  tags=["lock", "infrastructure"],
  priority=0
)

Important properties of the sentinel task:

• Fixed well-known ID: _lock:git-commit -- all agents reference this exact ID
• Never completed: It stays in pending/working cycle forever
• Priority 0: Should not appear in normal task listings as actionable work
• Tag lock: Clearly identifies it as infrastructure, not real work