migration-guidance

1---2name: migration-guidance3description: Use when changing how a v3 public API maps to v4, editing migration annotations, or regenerating migration/v3-to-v4.md.4---5 6Update guidance when a v3 public module or API is renamed, moved, removed,7replaced, or gains a materially different v4 contract. A v4-only API without a8v3 counterpart does not automatically need an annotation.9 101. Account for every affected v3 symbol.112. Read [annotations.md](annotations.md) before adding or changing annotation12   YAML. Verify every suggested replacement against implementation and tests.133. When checking or regenerating the reference, or when the API change exists in14   a committed ref, read [generation.md](generation.md). Otherwise report that15   generation is deferred.164. When output was generated, inspect it for unrelated movement and stale refs.17 18The task is complete when every affected v3 symbol is accounted for, annotation19replacements are verified, checks and generation succeed when the change is in20a committed ref, and every generated difference is explained. Report deferred21checks explicitly for uncommitted API changes.22