Patches & Diffs

Pimsy agents never write to a working tree directly. Every modification is expressed as a patch — a structured, reviewable, reversible description of an edit that is validated before it is applied.

Why not direct writes#

Direct file writes make three failure modes unavoidable. A partially-completed sequence of writes leaves the repository in a state that neither the agent nor a human intended. An edit based on a stale read silently clobbers concurrent work. And a write carries no record of intent, so a reviewer sees what changed but not why.

Patches address all three. They are atomic as a set, they carry the content hash of what the agent believed it was editing, and every hunk is annotated with the plan step that produced it.

Patch structure#

Symbol-anchored hunks#

A conventional diff addresses lines. If anything above a hunk changes, the hunk no longer applies. Pimsy hunks address symbols: "the body of this function", "this parameter in this signature". Unrelated edits elsewhere in the file are irrelevant, and a patch authored an hour ago still applies cleanly after a reformat.

hunk 2 of 4
  anchor     auth/session.resolveSessionToken  (body)
  base       sha256:9f2c…  verified
  rationale  step 3 — token comparison must be constant-time;
             the previous equality check leaked length through
             early return

- if (provided !== expected) return null
+ if (!constantTimeEquals(provided, expected)) return null

  invariant  returns null for every non-matching token
  invariant  no change to the success path

Conflict resolution#