ACID for Agent Repository State¶

Apply database transaction theory — Atomicity, Consistency, Isolation, Durability — as the operating contract for how an agent commits, verifies, partitions, and persists repository work.

Why ACID, not another mnemonic¶

"Save your state," "commit progress," "leave the repo clean" — each phrase is vague. ACID, Codd and Gray's four-property contract for database transactions, gives you a precise mapping instead. Each letter names a discipline you can observe, with a verification step. Together they describe a repository that survives both context compaction and concurrent writers.

The WalkingLabs harness-engineering lecture applies ACID directly to agent state. The four properties are not metaphors — they are the operating contract.

Atomicity¶

Each logical operation maps to exactly one commit; a partial failure rolls the working tree back to a clean state.

The unit is the logical operation, not the file. "Add new endpoint and update tests" is one commit. The WalkingLabs lecture is explicit: "Each 'logical operation' (e.g., 'add new endpoint and update tests') gets one git commit." On partial failure, the agent stashes or resets to the pre-operation state. Half-applied changes do not persist.

Atomicity is what makes Rollback-First Design tractable. If a commit holds one logical unit, git revert <sha> undoes that unit cleanly. If a commit holds three half-finished units, revert is ambiguous.

Consistency¶

A verification predicate runs before every commit; broken invariants never persist.

Tests pass, lint passes, build passes — the predicate. The WalkingLabs lecture states it directly: "all tests pass, lint reports zero errors" before committing, with "the agent runs verification after each operation; inconsistent intermediate states don't get committed."

This turns the agent's self-report into an external contract. Per Anthropic's harness post, agents are optimistic about completion when nothing verifies them. They "make code changes, and even do testing with unit tests or curl commands against a development server, but would fail to recognize that the feature didn't work end-to-end." A predicate satisfied through tool calls, not through the agent's claim that it ran, closes that optimism loop. Pair this with a Feature List File and the predicate becomes auditable.

Isolation¶

Concurrent agents work on disjoint branches or per-agent progress files; neither observes the other's in-flight state.

The WalkingLabs lecture prescribes: "each agent uses its own progress file, or use git branches for isolation." Branches isolate file writes; per-agent progress files isolate scratchpad state.

Git provides no transaction manager. Isolation here is partitioning by convention, not serialization. If two agents target the same file on different branches, the conflict surfaces at merge time, not at write time. Treat branch-per-agent as write-disjoint coordination, not serialization. See Worktree Isolation for filesystem-level enforcement.

Durability¶

Cross-session knowledge lives in git-tracked files; nothing critical exists only in chat history, Slack, or human memory.

Per the WalkingLabs lecture, "critical project knowledge lives in git-tracked files" and "cross-session knowledge must be persisted to files." Anthropic's harness post supplies the operational form: a claude-progress.txt log committed alongside code so subsequent sessions read the prior session's state from the repo, not from an absent context window.

Durability defeats compaction. The context window forgets; git does not. The corollary is Discoverable vs Non-Discoverable Context. Once knowledge is in the repo, the agent finds it by reading files instead of re-loading it every turn.

When strict ACID backfires¶

The four properties are not equally valuable in every workflow:

Single-session greenfield tasks: no cross-session continuity and no shared workspace, so durability and isolation are overhead. Atomicity and consistency carry the work.
Throwaway environments: per-task containers reset on each invocation, so durability through git is duplicative. The environment is already ephemeral.
High-frequency inner loops: one commit per logical operation inflates history at sub-minute cadences. Squash-on-merge or commit-per-task scales better than strict per-operation atomicity.
Multi-agent with shared file ownership: branch isolation handles write-disjoint tasks but does not coordinate writes to the same file. Git has no transaction manager, so the conflict surfaces at rebase, not at write (see Worktree Isolation).

Consistency and durability carry the most weight in a typical single-agent workflow. Atomicity and isolation matter more at scale and across sessions.

Example¶

A long-running agent implements three features against a Python service. The system prompt installs the four properties as the operating contract:

Your repository is your system of record. Follow ACID:

- Atomicity: one logical change per commit. On failure, `git stash` and revert
  the working tree before retrying.
- Consistency: before every commit run `uv run pytest && uv run ruff check`.
  Do not commit if either fails.
- Isolation: work on branch `agent/<feature-id>`. Maintain progress in
  `agent-progress/<feature-id>.md`. Do not read or write other agents' files.
- Durability: at session end, commit progress notes and push the branch.
  Cross-session knowledge lives in git-tracked files, not in your context window.

Session 1 starts feature auth-reset. The agent creates branch agent/auth-reset, writes the endpoint and tests, runs the predicate, commits, writes agent-progress/auth-reset.md noting the next step is integration tests, commits, pushes. Context compacts.

Session 2 starts on the same task. The agent reads agent-progress/auth-reset.md and git log agent/auth-reset to recover state — no chat history required. It resumes at integration tests, runs the predicate, commits, marks the feature passing in features.json. A concurrent agent on agent/payment-retry sees no in-flight state from auth-reset because both writes are partitioned by branch and progress file.

Key Takeaways¶

ACID is a documented operating model for agent repository state, not a metaphor — each letter has a citable agent discipline
Atomicity binds the commit to a logical operation, not a file boundary; partial failures stash or reset
Consistency runs the verification predicate via tool calls before commit, closing the agent-optimism gap
Isolation partitions concurrent agents by branch and progress file — convention, not transaction-manager enforcement
Durability puts cross-session knowledge in git-tracked files so context compaction does not destroy state
Consistency and durability carry most workflows; atomicity and isolation matter most at scale and across sessions