agent's cross-reference map used stale page numbers after an amendment was inserted - every 'see Section X' link broke

TL;DR

An inserted amendment shifted everything after it, but the cross-reference map still used the old page numbers, so every 'see Section X' link broke. Detect structural changes (insertions, renumbering), rebuild the reference map from the current document, and re-resolve every link against the fresh map.

The symptom

agent's cross-reference map used stale page numbers after an amendment was inserted  -  every 'see Section X' link broke

Steps

1. Detect the structural change

Diff the document structure (section list) before and after the amendment. Inserted sections shift all downstream numbering. Expected: The insertion point and the shifted range identified.

2. Rebuild the reference map

Re-parse the current document into a fresh section-to-page (or section-to-location) map. Expected: A map reflecting the amended structure.

3. Re-resolve every cross-reference

Walk all 'see Section X' links and resolve them against the new map. Flag any that still do not resolve. Expected: All links pointing at correct current locations.

4. Add the rebuild trigger

Any structural change (insert, delete, renumber) invalidates the reference map and forces a rebuild before links are used. Expected: Stale maps cannot survive an amendment.

When to use

• Links broke after an amendment or insertion
• Cross-references resolve to wrong locations
• The document structure changed since the map was built

When not to use

• Links were wrong before the amendment (fix the original mapping)
• No structural change occurred (different cause)
• References are by defined term, not number (more stable; still verify)

Why it happens

Cross-reference maps are snapshots of document structure. Inserting an amendment is a structural edit: sections renumber, pages shift, and every snapshot entry downstream goes stale. Links resolved against the stale map point at wherever the old numbering used to be.

Edge cases

• Multiple amendments: rebuild after each, or once after the final composite.
• Deleted sections: links to deleted sections need human review, not silent dropping.
• Exhibit insertions: they shift exhibit numbering the same way.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_CWQUAHVXEegQw--rqtQ31Q