fix(telegram): return matrix source gaps as readback

apps/api/src/services/telegram_alert_ai_automation_matrix.py

@@ -81,6 +81,9 @@ def load_latest_telegram_alert_ai_automation_matrix(
     readability_summary = readability_guard["summary"]
     digest_rollups = digest_policy["rollups"]
     source_proof = _inspect_source_contract(repo_root)
+    source_contract_missing_markers = list(
+        source_proof.get("source_contract_missing_markers") or []
+    )
     learning_writeback_refs_present = bool(
         source_proof["ai_alert_card_learning_writeback_refs_present"]
     )
@@ -431,6 +434,8 @@ def load_latest_telegram_alert_ai_automation_matrix(
         "status": (
             "telegram_alert_ai_automation_matrix_ready_with_direct_send_gaps"
             if direct_gap_count
+            else "blocked_telegram_alert_ai_automation_matrix_source_contract_gaps"
+            if source_contract_missing_markers
             else "telegram_alert_ai_automation_matrix_ready"
         ),
         "mode": "metadata_only_no_secret_no_telegram_send_no_runtime_write",
@@ -604,7 +609,7 @@ def _require_safe_boundaries(*payloads: dict[str, Any]) -> None:
                 )
 
 
-def _inspect_source_contract(repo_root: Path) -> dict[str, int | bool]:
+def _inspect_source_contract(repo_root: Path) -> dict[str, Any]:
     source_checks = {
         "telegram_gateway_mirror_present": (
             "apps/api/src/services/telegram_gateway.py",
@@ -681,9 +686,13 @@ def _inspect_source_contract(repo_root: Path) -> dict[str, int | bool]:
                 1 if present else 0
             )
 
-    required = [key for key, value in result.items() if key.endswith("_present") and value is not True]
-    if required:
-        raise ValueError(f"Telegram matrix source contract missing markers: {required}")
+    required = [
+        key
+        for key, value in result.items()
+        if key.endswith("_present") and value is not True
+    ]
+    result["source_contract_ready"] = not required
+    result["source_contract_missing_markers"] = required
     return result
 
 
@@ -823,7 +832,7 @@ def _build_summary(
     migration_summary: dict[str, Any],
     readability_summary: dict[str, Any],
     digest_rollups: dict[str, Any],
-    source_proof: dict[str, int | bool],
+    source_proof: dict[str, Any],
     next_priority_action: dict[str, Any],
 ) -> dict[str, Any]:
     ready = lambda key, prefix: sum(1 for item in matrix if str(item[key]).startswith(prefix))
@@ -872,6 +881,13 @@ def _build_summary(
         "telegram_alert_post_apply_verifier_awooop_surface_count": source_proof[
             "telegram_alert_post_apply_verifier_awooop_surface_count"
         ],
+        "source_contract_ready": bool(source_proof.get("source_contract_ready")),
+        "source_contract_missing_marker_count": len(
+            source_proof.get("source_contract_missing_markers") or []
+        ),
+        "source_contract_missing_markers": list(
+            source_proof.get("source_contract_missing_markers") or []
+        ),
         "next_priority_action_id": next_priority_action["action_id"],
         "next_priority_work_item_id": "CIR-P0-TG-001",
     }