agent flagged every cross-reference as changed after the counterparty renumbered the sections - the numbers moved but...

TL;DR

The counterparty renumbered the sections without changing any clause text, and the agent flagged every cross-reference as changed. Align clauses between versions by text similarity instead of by number, emit the renumbering as a single mapping (old 4.2 is now 5.1), and verify the clause texts are identical before calling it renumber-only.

The symptom

agent flagged every cross-reference as changed after the counterparty renumbered the sections  -  the numbers moved but no clause text changed

Steps

1. Align clauses by text, not by number

Parse each version into (section number, clause text) pairs. Match pairs across versions by text similarity (normalized text, ignoring the number). Renumbered clauses match on text. Expected: Each clause in v1 matched to its v2 counterpart despite different numbers.

2. Emit a single renumber map

From the alignment, produce the mapping: 4.1 to 5.1, 4.2 to 5.2, and so on. Present this once instead of flagging each reference. Expected: One renumber table covering all moved sections.

3. Verify the texts are identical

For each aligned pair, diff the clause texts. If all diffs are empty, the change is renumber-only. Any non-empty diff is a real edit hiding inside the renumbering: report it. Expected: Empty text diffs across the board, or a short list of real edits.

4. Rewrite references through the map for the report

Show cross-references resolved through the map so reviewers see 'see Section 5.1 (formerly 4.2)'. Do not list each reference as a change. Expected: References readable under the new numbering with old numbers noted.

When to use

• Every cross-reference is flagged but clause texts are unchanged
• The counterparty renumbered sections, articles, or exhibits
• The diff is number-driven rather than text-driven

When not to use

• Clause text actually changed along with the numbers (report the text edits)
• References point at sections that no longer exist (broken links, different issue)
• Numbering is unchanged (different cause)

Why it happens

Cross-references embed section numbers, so a renumbering touches every reference string. A string diff cannot tell 'number moved' from 'meaning changed'. Aligning on clause text separates the two: identical texts mean the renumbering is the whole story.

Edge cases

• Split or merged sections: one-to-many alignments need human review; do not force a map.
• Exhibit renumbering (Exhibit A to Exhibit 1): same technique, separate map.
• References inside defined terms: apply the map there too, consistently.

Provenance

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