refactor review-plan safety and validation

src/vlm/duplicate_resolve.py

@@ -9,6 +9,10 @@ from vlm.models import MovieIdentity, SeriesIdentity
 from vlm.utils import is_sample_path
 
 
+class DuplicateResolutionError(ValueError):
+    """Raised when a duplicate group cannot be resolved deterministically."""
+
+
 def choose_keep_index(
     items: list[tuple[Path, Union[MovieIdentity, SeriesIdentity]]],
     strategy: str,
@@ -38,14 +42,20 @@ def choose_keep_index(
     if strategy == "first_seen":
         return 0
     if strategy == "by_quality":
-        if quality_comparison is None or len(quality_comparison) != len(items):
-            return 0  # Fallback to first if quality data missing/mismatched
+        if quality_comparison is None:
+            raise DuplicateResolutionError(
+                "by_quality strategy requires quality comparison data"
+            )
+        if len(quality_comparison) != len(items):
+            raise DuplicateResolutionError(
+                "by_quality strategy requires quality data aligned with duplicate items"
+            )
         return _by_quality_index(items, quality_comparison)
     if strategy == "by_reputation":
         return _by_reputation_index(items, quality_comparison=quality_comparison)
     if strategy == "by_reputation_quality_time":
         return _by_reputation_quality_time_index(items, quality_comparison=quality_comparison)
-    return 0
+    raise DuplicateResolutionError(f"Unsupported duplicate strategy: {strategy}")
 
 
 def _parse_resolution_tier(resolution: Optional[str], path: Path) -> int: