agent diffed against the wrong baseline - it compared the redline to v2 instead of v3 and every real change showed...

TL;DR

The agent compared the redline against v2 instead of v3, so every change between v2 and v3 showed up twice. Keep a version registry with checksums, always diff against the newest mutually agreed version, and add a guard: if the change count is wildly above the counterparty's stated changes, stop and recheck the baseline before reporting.

The symptom

agent diffed against the wrong baseline  -  it compared the redline to v2 instead of v3 and every real change showed twice

Steps

1. Build a version registry

Record every version received or produced: version label, timestamp, source, and a checksum (sha256) of the file. v2 and v3 must be distinguishable even if the filenames are similar. Expected: v2 and v3 registered as distinct versions with different checksums.

2. Identify the correct baseline

The baseline is the latest version both sides confirmed (usually the counterparty's previous round). Confirm v3 is the right baseline for this diff, not v2. Expected: Baseline explicitly set to v3 with its checksum.

3. Re-run the diff against v3

Diff the redline against the v3 file. The duplicated changes collapse: each real edit appears once. Expected: Change count roughly halves to the true number.

4. Add the count-sanity guard

Before reporting, compare the diff count to the counterparty's stated change count. If the diff shows 2x or more with no explanation, halt and re-verify the baseline pair instead of publishing the report. Expected: Stale-baseline diffs get caught before they reach a reviewer.

When to use

• Each change appears twice in the diff
• The change count is roughly double what the counterparty described
• Filenames are similar (v2/v3, draft/final) and easy to mix up

When not to use

• The edits genuinely are duplicated in the document (rare; verify)
• There is no agreed version history (first exchange: establish it)
• The duplication comes from text-layer plus OCR double extraction (different fix)

Why it happens

Version files accumulate with unhelpful names, and the agent picks the baseline by recency or filename guess. Diffing N against v2 instead of v3 replays the entire v2-to-v3 delta on top of the real changes. Checksums and an explicit registry remove the guesswork.

Edge cases

• Counterparty sends 'final_v2' after 'v3': trust the registry order, not the filename.
• Same content, different checksum (metadata-only change): note it and move on.
• Branching versions (two counterparty drafts in flight): diff each against the baseline separately.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_lIx5iD0FVF6NM4q0a6o50w