fix(protocol): בחירת פרוטוקול ועדת-ערר לפי protocol_scope + document_id (#223)

analyze_protocol בחר את מסמך-הפרוטוקול הראשון (doc_type='protocol') והתעלם
מ-protocol_scope. בתיק עם כמה פרוטוקולים — נספח ועדה-מקומית + דיון ועדת-הערר —
הוא ניתח את הלא-נכון (התגלה ב-1043-02-26: ניתח "נספח 18 השתלשלות פרוטוקולים"
במקום "פרוטוקול דיון 23.6.26").

- _find_protocol מעדיף פרוטוקול ועדת-ערר (scope שאינו 'lower'); פרוטוקול
  'lower' (ועדה מקומית/מחוזית) לא נכנס להשוואה — הוא רקע לבלוק ו בלבד.
- כמה פרוטוקולי-ערר → האחרון (created_at) גובר; document_id מכוון במפורש.
- analyze_protocol (service + drafting tool + MCP tool) מקבל document_id/
  target_document_id אופציונלי.
- _protocol_scope: קורא metadata.protocol_scope (ריק=appeal, כמו ה-UI).
- 5 בדיקות חדשות: דילוג-lower, all-lower→None, most-recent, targeting, unknown-id.

טווח: Fix1 (קוד). ניקוי 1043 (תיוג נספח 18 כ-lower + מחיקת 11 רשומות שגויות
+ הרצה מכוונת ל-23.6.26) דורש טעינה-מחדש של ה-MCP — אחרי מיזוג. פרוצדורת
ניתוח-מסמך-נוסף הכללית — המשך ב-#223.

Invariants: G1 (נרמול-במקור — קריאת scope מ-metadata, לא ניחוש-בקריאה) ·
G2 (אותו נתיב ניתוח, בורר מדויק) · §6 (no_protocol מחזיר סטטוס מפורש, לא בליעה).

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

mcp-server/src/legal_mcp/services/protocol_analyzer.py

@@ -120,15 +120,47 @@ HEADER_PROMPT = """אתה מחלץ נתוני-כותרת מפרוטוקול די
 MAX_PROTOCOL_CHARS = 120_000
 
 
-def _find_protocol(docs: list[dict]) -> dict | None:
-    """The protocol document for the case, if present (doc_type or title)."""
-    for d in docs:
-        if d.get("doc_type") == "protocol":
-            return d
-    for d in docs:
-        if "פרוטוקול" in (d.get("title") or ""):
-            return d
-    return None
+def _protocol_scope(doc: dict) -> str:
+    """Protocol scope from ``metadata.protocol_scope``.
+
+    Absent/'' defaults to ``'appeal'`` (ועדת הערר), matching the
+    document-type-editor convention where only the non-default ``'lower'``
+    (ועדה מקומית/מחוזית) is persisted.
+    """
+    meta = doc.get("metadata") or {}
+    return (meta.get("protocol_scope") or "").strip() or "appeal"
+
+
+def _find_protocol(
+    docs: list[dict], document_id: UUID | None = None,
+) -> dict | None:
+    """The ועדת-הערר hearing protocol to compare against the pleadings.
+
+    - ``document_id`` given → return exactly that document (explicit target),
+      so a case with several protocols can be pointed at the right hearing.
+    - Otherwise prefer a protocol scoped to the appeals committee
+      (``scope != 'lower'``). A ``'lower'`` protocol is the local/district
+      committee's proceedings — it feeds background (block ו) only and must NOT
+      drive the hearing-vs-pleadings comparison (#223). If every protocol is
+      lower-scoped there is no ערר-hearing to compare → return None.
+    - Among appeal-scoped protocols the most recent (by ``created_at``) wins —
+      the operative hearing; ties fall back to list order.
+    """
+    if document_id is not None:
+        return next(
+            (d for d in docs if str(d.get("id")) == str(document_id)), None,
+        )
+
+    protocols = [d for d in docs if d.get("doc_type") == "protocol"]
+    if not protocols:
+        # Legacy fallback: untyped docs whose title says "פרוטוקול".
+        protocols = [d for d in docs if "פרוטוקול" in (d.get("title") or "")]
+
+    appeal_scoped = [d for d in protocols if _protocol_scope(d) != "lower"]
+    if not appeal_scoped:
+        return None
+    appeal_scoped.sort(key=lambda d: d.get("created_at") or "", reverse=True)
+    return appeal_scoped[0]
 
 
 def _compact_arguments(arguments: list[dict]) -> list[dict]:
@@ -239,9 +271,15 @@ async def _extract_header(protocol_text: str, case_id: UUID) -> dict:
     }
 
 
-async def analyze_protocol(case_id: UUID) -> dict:
+async def analyze_protocol(
+    case_id: UUID, target_document_id: UUID | None = None,
+) -> dict:
     """Comparative analysis of the case's hearing protocol vs. its pleadings.
 
+    ``target_document_id`` pins the analysis to a specific protocol document —
+    required when a case holds several protocols (e.g. a lower-committee annex
+    plus the ועדת-הערר hearing) and the auto-pick would be ambiguous (#223).
+
     1. Locates the protocol document.
     2. Pulls the aggregated legal_arguments (the written-pleadings baseline).
     3. Asks Claude (Opus 4.8, effort=high) to classify each as dropped /
@@ -252,11 +290,20 @@ async def analyze_protocol(case_id: UUID) -> dict:
     Returns a serializable summary dict.
     """
     docs = await db.list_documents(case_id)
-    protocol = _find_protocol(docs)
+    protocol = _find_protocol(docs, document_id=target_document_id)
     if not protocol:
+        if target_document_id is not None:
+            return {
+                "status": "no_protocol",
+                "message": f"מסמך {target_document_id} לא נמצא בתיק.",
+            }
         return {
             "status": "no_protocol",
-            "message": "לא נמצא פרוטוקול דיון בתיק (doc_type='protocol'). העלה פרוטוקול והרץ שוב.",
+            "message": (
+                "לא נמצא פרוטוקול ועדת-ערר בתיק (doc_type='protocol' עם "
+                "protocol_scope שאינו 'lower'). העלה פרוטוקול-דיון, או תייג את "
+                "הפרוטוקול הקיים כ-appeal, והרץ שוב."
+            ),
         }
 
     document_id = UUID(protocol["id"])