Enforce readiness evidence and unknown ripeness handling

scheduler/core/ripeness.py

@@ -28,7 +28,7 @@ class RipenessStatus(Enum):
     def is_ripe(self) -> bool:
         """Check if status indicates ripeness."""
         return self == RipenessStatus.RIPE
-    
+
     def is_unripe(self) -> bool:
         """Check if status indicates unripeness."""
         return self in {
@@ -54,11 +54,11 @@ RIPE_KEYWORDS = ["ARGUMENTS", "HEARING", "FINAL", "JUDGMENT", "ORDERS", "DISPOSA
 
 class RipenessClassifier:
     """Classify cases as RIPE or UNRIPE for scheduling optimization."""
-    
+
     # Stages that indicate case is ready for substantive hearing
     RIPE_STAGES = [
         "ARGUMENTS",
-        "EVIDENCE", 
+        "EVIDENCE",
         "ORDERS / JUDGMENT",
         "FINAL DISPOSAL"
     ]
@@ -70,6 +70,50 @@ class RipenessClassifier:
         "FRAMING OF CHARGES",
         "INTERLOCUTORY APPLICATION"
     ]
+
+    # Minimum evidence thresholds before declaring a case RIPE
+    MIN_SERVICE_HEARINGS = 1  # At least one hearing to confirm service/compliance
+    MIN_STAGE_DAYS = 7  # Time spent in current stage to show compliance efforts
+    MIN_CASE_AGE_DAYS = 14  # Minimum maturity before assuming readiness
+
+    @classmethod
+    def _has_required_evidence(cls, case: Case) -> tuple[bool, dict[str, bool]]:
+        """Check that minimum readiness evidence exists before declaring RIPE."""
+
+        # Evidence of service/compliance: at least one hearing or explicit purpose text
+        service_confirmed = case.hearing_count >= cls.MIN_SERVICE_HEARINGS or bool(
+            getattr(case, "last_hearing_purpose", None)
+        )
+
+        # Evidence the case has progressed in its current stage
+        days_in_stage = getattr(case, "days_in_stage", 0)
+        compliance_confirmed = (
+            case.current_stage not in cls.UNRIPE_STAGES or days_in_stage >= cls.MIN_STAGE_DAYS
+        )
+
+        # Age-based maturity requirement
+        age_confirmed = getattr(case, "age_days", 0) >= cls.MIN_CASE_AGE_DAYS
+
+        evidence = {
+            "service": service_confirmed,
+            "compliance": compliance_confirmed,
+            "age": age_confirmed,
+        }
+
+        return all(evidence.values()), evidence
+
+    @classmethod
+    def _has_ripe_signal(cls, case: Case) -> bool:
+        """Check if stage or hearing purpose indicates readiness."""
+
+        if case.current_stage in cls.RIPE_STAGES:
+            return True
+
+        if hasattr(case, "last_hearing_purpose") and case.last_hearing_purpose:
+            purpose_upper = case.last_hearing_purpose.upper()
+            return any(keyword in purpose_upper for keyword in RIPE_KEYWORDS)
+
+        return False
     
     @classmethod
     def classify(cls, case: Case, current_date: datetime | None = None) -> RipenessStatus:
@@ -81,13 +125,15 @@ class RipenessClassifier:
             
         Returns:
             RipenessStatus enum indicating ripeness and bottleneck type
-            
+
         Algorithm:
         1. Check last hearing purpose for explicit bottleneck keywords
         2. Check stage (ADMISSION vs ORDERS/JUDGMENT)
         3. Check case maturity (days since filing, hearing count)
         4. Check if stuck (many hearings but no progress)
-        5. Default to RIPE if no bottlenecks detected
+        5. Require readiness evidence (service/compliance/age) else UNKNOWN
+        6. Check explicit ripe signals (stage/purpose)
+        7. Default to UNKNOWN if evidence exists but no ripe signal
         """
         if current_date is None:
             current_date = datetime.now()
@@ -95,7 +141,7 @@ class RipenessClassifier:
         # 1. Check last hearing purpose for explicit bottleneck keywords
         if hasattr(case, "last_hearing_purpose") and case.last_hearing_purpose:
             purpose_upper = case.last_hearing_purpose.upper()
-            
+
             for keyword, bottleneck_type in UNRIPE_KEYWORDS.items():
                 if keyword in purpose_upper:
                     return bottleneck_type
@@ -105,26 +151,28 @@ class RipenessClassifier:
             # New cases in ADMISSION (< 3 hearings) are often unripe
             if case.hearing_count < 3:
                 return RipenessStatus.UNRIPE_SUMMONS
-        
+
         # 3. Check if case is "stuck" (many hearings but no progress)
         if case.hearing_count > 10:
             # Calculate average days between hearings
             if case.age_days > 0:
                 avg_gap = case.age_days / case.hearing_count
-                
+
                 # If average gap > 60 days, likely stuck due to bottleneck
                 if avg_gap > 60:
                     return RipenessStatus.UNRIPE_PARTY
-        
-        # 4. Check stage-based ripeness (ripe stages are substantive)
-        if case.current_stage in cls.RIPE_STAGES:
+
+        # 4. Require explicit readiness evidence before declaring RIPE
+        evidence_ok, _ = cls._has_required_evidence(case)
+        if not evidence_ok:
+            return RipenessStatus.UNKNOWN
+
+        # 5. Check stage-based ripeness (ripe stages are substantive) or explicit RIPE signal
+        if cls._has_ripe_signal(case):
             return RipenessStatus.RIPE
-        
-        # 5. Default to RIPE if no bottlenecks detected
-        # NOTE: Scheduling gap enforcement (MIN_GAP_BETWEEN_HEARINGS) is handled
-        # by the simulation engine, not the ripeness classifier. Ripeness only
-        # detects substantive bottlenecks (summons, dependencies, party issues).
-        return RipenessStatus.RIPE
+
+        # 6. Default to UNKNOWN if no bottlenecks but also no clear ripe signal
+        return RipenessStatus.UNKNOWN
     
     @classmethod
     def get_ripeness_priority(cls, case: Case, current_date: datetime | None = None) -> float:
@@ -183,7 +231,7 @@ class RipenessClassifier:
             RipenessStatus.UNRIPE_DEPENDENT: "Waiting for another case or court order",
             RipenessStatus.UNRIPE_PARTY: "Party or lawyer unavailable",
             RipenessStatus.UNRIPE_DOCUMENT: "Missing documents or evidence",
-            RipenessStatus.UNKNOWN: "Insufficient data to determine ripeness",
+            RipenessStatus.UNKNOWN: "Insufficient readiness evidence; route to manual triage",
         }
         return reasons.get(ripeness_status, "Unknown status")