## 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
```text
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_S1yGvg6jQeJjTFESPUbBMA