Document named ref routing guardrail

dumas_h3_longvideos.py

@@ -4639,6 +4639,10 @@ def resolve_shot_references(text, ref_list, ref_mode, shot_index, handoff, conne
     Each beat should be able to pick up character names on its own. A stray
     <Picture N> tag in some other beat should not make name-matched characters
     disappear from the untagged beats in the same chain."""
+    # Keep name matching local to the beat. Earlier versions used a chain-wide
+    # "any tags anywhere" gate here, which accidentally turned off character
+    # identity matching on untagged beats as soon as one tagged beat existed.
+    # That regression is exactly what this helper prevents.
     refs = connected_refs if connected_refs is not None else _connected_refs(ref_list, normalized_refs=normalized_refs)
     if not refs:
         return text, [], [], False, ref_mode
@@ -6940,6 +6944,8 @@ class H3LongVideos:
                 # text names <Picture N> gets image N, renumbered to match what that
                 # shot actually carries. Named character matches are already included
                 # in the same pass; the tag only makes the slot mapping explicit.
+                # Do not reintroduce a chain-wide tag gate here. Named character
+                # refs must still route on beats that do not use <Picture N>.
                 for n in dropped:
                     if n not in ref_missing:
                         ref_missing.append(n)