fixup(migrate): wire migration anchor + add doc section for pending_activation

Per review on #523:
- REMOVED_ENUM_VALUES gains the (hint, anchor) tuple shape so findings
  carry a migration_anchor like REMOVED_TYPES do.
- New MIGRATION_v3_to_v4.md § ``MediaBuyStatus.pending_activation`` →
  split with the cause-to-replacement mapping and a code example,
  matching the anchor the codemod now emits.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: bokelley

MIGRATION_v3_to_v4.md

@@ -211,6 +211,40 @@ if package.status == PackageStatus.active: ...
 if media_buy.status == MediaBuyStatus.active: ...
 ```
 
+### `MediaBuyStatus.pending_activation` → split
+
+The single `pending_activation` enum value was split into two distinct
+states based on cause. The codemod flags every reference; the correct
+replacement is per-call-site.
+
+| Cause | Replacement |
+| --- | --- |
+| Buy is scheduled and waiting for its start time | `MediaBuyStatus.pending_start` |
+| Buy is waiting on creative approval / asset processing | `MediaBuyStatus.pending_creatives` |
+
+**Before (v3.x):**
+```python
+if media_buy.status == MediaBuyStatus.pending_activation:
+    notify_trafficker(media_buy)
+```
+
+**After (v4.0):**
+```python
+if media_buy.status in (
+    MediaBuyStatus.pending_start,
+    MediaBuyStatus.pending_creatives,
+):
+    notify_trafficker(media_buy)
+```
+
+When the original branch only fired for one cause, narrow to the right
+state (e.g. only `pending_creatives` for creative-review notifications).
+A blanket replacement to either single value is almost always wrong —
+the spec split was driven by adopters needing distinct behaviour for
+the two cases. The wire enum still accepts `pending` as a legacy alias
+for `pending_start`, so existing buyer clients reading older payloads
+keep working without code changes.
+
 ### `ResolvedBrand.brand_manifest` field removed
 
 `RegistryClient.lookup_brand()` returns a `ResolvedBrand` whose

src/adcp/migrate/v3_to_v4.py

@@ -108,11 +108,12 @@
 
 # Enum values removed or split between v3 and v4. Flagged (not rewritten)
 # because the correct replacement depends on call-site semantics.
-REMOVED_ENUM_VALUES: dict[str, str] = {
+REMOVED_ENUM_VALUES: dict[str, tuple[str, str]] = {
     "MediaBuyStatus.pending_activation": (
         "`pending_activation` split in v4: use `pending_start` if the buy hasn't reached "
         "its scheduled start date, or `pending_creatives` if creatives haven't been "
-        "submitted. Check `valid_actions` on the MediaBuy response to confirm which applies."
+        "submitted. Check `valid_actions` on the MediaBuy response to confirm which applies.",
+        "mediabuystatuspending_activation--split",
     ),
 }
 
@@ -422,7 +423,7 @@ def scan_file(path: Path, *, apply_changes: bool) -> tuple[list[Finding], str |
         # class-qualified form is anchored tightly enough that false positives
         # are unlikely; trailing word boundary prevents suffix matches like
         # ``MediaBuyStatus.pending_activation_v2``.
-        for enum_val, hint in REMOVED_ENUM_VALUES.items():
+        for enum_val, (enum_hint, enum_anchor) in REMOVED_ENUM_VALUES.items():
             for match in _REMOVED_ENUM_VALUE_PATTERNS[enum_val].finditer(line):
                 findings.append(
                     Finding(
@@ -431,7 +432,8 @@ def scan_file(path: Path, *, apply_changes: bool) -> tuple[list[Finding], str |
                         line=lineno,
                         column=match.start() + 1,
                         before=enum_val,
-                        hint=hint,
+                        hint=enum_hint,
+                        migration_anchor=enum_anchor,
                     )
                 )