feat: Stage A finalizers + #35/#36/#37 — critical-gap closure

Four parallel sub-agents closed the remaining critical gaps from the
26/05 Stage A/B sprint. Each block independently tested; aggregated here.

## #30/#31 finalizers (sub-agent A)
* Auto-derive practice_area in case_create from case_number prefix
  (1xxx→rishuy_uvniya, 8xxx→betterment_levy, 9xxx→compensation_197);
  default for CaseCreateRequest is now "" (the DB constraint catches
  any stray "appeals_committee").
* practice_area.py: derive_subtype now handles axis-B domain values
  (rishuy_uvniya/betterment_levy/compensation_197) without parsing the
  case number; new helper derive_domain_practice_area().
* Halacha re-extraction verified unnecessary — all 6 reclassified
  records already had is_binding=false and approved halachot.
* Regression tests: 6 cases in tests/test_corpus_constraints.py
  covering practice_area enum, internal-committee chair/district,
  external-upload arar prefix, MCP guard.
* UI: district input → Select dropdown (7 districts) in
  precedent-edit-sheet.tsx, preserving legacy free-text values.

## #37 בל"מ subtypes (sub-agent B)
* 3 new appeal_subtypes: extension_request_{building_permit,
  betterment_levy,compensation}. APPEALS_COMMITTEE_SUBTYPES extended,
  SUBTYPES_BY_AREA mappings added.
* New helpers: is_blam_subject(), is_blam_subtype(),
  derive_subtype_with_blam(case_number, subject, practice_area).
  case_create now uses it to auto-detect "בקשה להארכת מועד" subjects.
* 3 methodology templates under docs/methodology/extension-request-*.md.
* paperclip_client.py mapping updated for the 3 new subtypes
  (extension_request_building_permit→CMP, the other two→CMPA).
* Frontend: bilingual "בל"מ" badge + filter dropdown on cases list +
  detail header; appeal-type-bars collapseBlam() merges בל"מ into its
  parent domain for aggregate bars.
* Wizard auto-detects בל"מ from subject during case creation.
* 3 Berlinger cases (1017/1018/1019-03-26) migrated to
  appeal_subtype=extension_request_building_permit via psql.

## #35 missing_precedents feature (sub-agent C)
* Schema V13: missing_precedents table (citation, case_id, party,
  legal_topic, status, linked_case_law_id, claim_quote, ...) +
  FK constraints + 3 indexes. Applied via psql + idempotent migration.
* 6 db.py service functions, 3 MCP tools, 6 FastAPI endpoints
  (POST/GET/PATCH/DELETE/upload — upload routes by citation prefix
  to ingest_internal_decision or ingest_precedent).
* Next.js page /missing-precedents with 5 status tabs + filters +
  sidebar badge counter + detail drawer with metadata edit + smart
  upload form that switches fields per committee/court.
* Bootstrap: 7 rows imported from the JSON file
  (3 citations × cases, all status=closed with linked_case_law_id).
* legal-researcher.md: new §2ב.5 with missing_precedent_create
  usage + dedup semantics + tool grant.

## #36 legal_arguments aggregation (sub-agent D)
* Schema V14: legal_arguments + legal_argument_propositions M:M.
  Applied via psql.
* New service argument_aggregator.py with two functions —
  aggregate_claims_to_arguments() (Claude CLI / claude_session) and
  get_legal_arguments(). Graceful llm_unavailable handling when CLI
  is missing (containers).
* 2 MCP tools + 2 API endpoints (POST .../aggregate-arguments as
  BackgroundTask, GET .../legal-arguments).
* Frontend: shadcn Accordion + new legal-arguments-panel.tsx with
  hierarchical (party → priority badge → arguments) display, "טיעונים"
  tab on the case page, "חשב/חשב מחדש" buttons.
* scripts/backfill_legal_arguments.py + SCRIPTS.md entry — dry-run
  found 8 candidate cases including 1017/1018/1019.

## Open follow-ups (intentionally deferred)
* npm run api:types in web-ui (CLAUDE.md flow) — recommended before
  the next UI commit; not required for backend deployment.
* Run backfill_legal_arguments.py --apply once the container picks up
  the new aggregator service.
* webhook on missing-precedents upload-close to Paperclip (optional).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

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

@@ -0,0 +1,358 @@
+"""כינוס פרופוזיציות לטיעונים משפטיים מובחנים — argument de-duplication.
+
+Workflow:
+1. ``claims_extractor`` extracts ~20-30 raw propositions per litigation
+   brief into the ``claims`` table.
+2. This module groups those raw propositions, per party, into 6-12
+   distinct legal arguments via Claude headless (`claude_session`).
+3. The result is stored in ``legal_arguments`` plus ``legal_argument_
+   propositions`` (M:M join) so we keep traceability back to the source
+   claims.
+
+Manually de-duping 184 propositions in 3 cases yielded 82 arguments
+(~24/case) — see ``data/cases/{1017,1018,1019}-03-26/documents/research/
+legal-arguments.md`` for the gold standard.
+
+**Architectural constraint**: ``claude_session`` only works from the local
+MCP server (Claude CLI is not installed in the FastAPI container). Calls
+from ``web/`` must go through MCP tools; calls from MCP tools land here
+directly.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from uuid import UUID
+
+from legal_mcp.services import claude_session, db
+
+logger = logging.getLogger(__name__)
+
+# Allowed enum values mirror the DB CHECK constraints.
+ALLOWED_PARTIES = {"appellant", "respondent", "committee", "permit_applicant", "unknown"}
+ALLOWED_PRIORITIES = {"threshold", "substantive", "procedural", "relief"}
+
+# Hebrew labels for the prompt (Claude needs context in the same
+# language as the source material).
+PARTY_LABELS_HE = {
+    "appellant": "עוררים",
+    "respondent": "משיבים",
+    "committee": "ועדה מקומית",
+    "permit_applicant": "מבקשי היתר",
+    "unknown": "צד לא מזוהה",
+}
+
+
+AGGREGATE_PROMPT_TEMPLATE = """אתה מנתח כתבי טענות בתחום תכנון ובנייה (ועדת ערר).
+
+לפניך {n} פרופוזיציות גולמיות שחולצו ממסמכי {party_he} בתיק ערר.
+מטרתך: לקבץ אותן ל-{target_min}-{target_max} **טיעונים משפטיים מובחנים**
+(ארגומנטים אמיתיים, לא חזרה מילולית של הפרופוזיציות).
+
+## כללי איגוד:
+1. **טיעון אמיתי = רעיון משפטי אחד** — לא רשימה של פרופוזיציות, אלא טענה משפטית עצמאית.
+2. **מקבצים פרופוזיציות שתומכות באותו רעיון משפטי** — גם אם הניסוח שלהן שונה.
+3. **מפרידים בין סוגי טענות**:
+   - **threshold** = טענות סף (זכות עמידה, סמכות, מועדים, שיהוי)
+   - **substantive** = טענות מהותיות (תחולת חוק, פרשנות, חישוב)
+   - **procedural** = פגמי הליך (פרסום, פרוטוקול, ניגוד עניינים)
+   - **relief** = סעדים מבוקשים / סיכומים
+4. **כותרת קצרה ובהירה** — תיאורית, לא משפטית מפורטת. 5-15 מילים.
+5. **גוף הטיעון בפסקה אחת** — 3-7 שורות עברית, נאמן למקור.
+6. **שמירת ה-claim_ids המקוריים** — לכל טיעון, רשום אילו פרופוזיציות תומכות בו.
+
+## פלט:
+החזר JSON בלבד (ללא markdown, ללא הסברים), array של אובייקטים:
+```
+[
+  {{
+    "title": "כותרת קצרה של הטיעון",
+    "body": "גוף הטיעון בפסקה אחת",
+    "topic": "סוגיה משפטית קצרה (לדוגמה: 'זכות עמידה', 'תחולת תמ\\"א 38')",
+    "priority": "threshold|substantive|procedural|relief",
+    "claim_ids": ["uuid-1", "uuid-2"]
+  }}
+]
+```
+
+## הפרופוזיציות:
+{propositions_json}
+"""
+
+
+def _build_prompt(party: str, propositions: list[dict]) -> str:
+    """Compose the per-party aggregation prompt."""
+    n = len(propositions)
+    # Conservative target: ~1 argument per 2-3 propositions, clamped 4-12.
+    target_min = max(4, n // 4)
+    target_max = max(target_min + 1, min(12, n // 2 + 1))
+
+    party_he = PARTY_LABELS_HE.get(party, party)
+    # Strip noise from propositions for the prompt — Claude only needs
+    # the id and the text to do the grouping.
+    compact = [
+        {"id": str(p["id"]), "text": p["claim_text"]}
+        for p in propositions
+    ]
+    propositions_json = json.dumps(compact, ensure_ascii=False, indent=2)
+
+    return AGGREGATE_PROMPT_TEMPLATE.format(
+        n=n,
+        party_he=party_he,
+        target_min=target_min,
+        target_max=target_max,
+        propositions_json=propositions_json,
+    )
+
+
+def _normalize_argument(raw: dict, fallback_topic: str = "") -> dict | None:
+    """Validate & normalize a single argument dict from Claude.
+
+    Returns None if the row is unusable (missing required fields).
+    """
+    if not isinstance(raw, dict):
+        return None
+    title = (raw.get("title") or "").strip()
+    body = (raw.get("body") or "").strip()
+    if not title or not body:
+        return None
+    priority = raw.get("priority", "substantive")
+    if priority not in ALLOWED_PRIORITIES:
+        priority = "substantive"
+    topic = (raw.get("topic") or fallback_topic or "").strip() or None
+    claim_ids_raw = raw.get("claim_ids") or []
+    claim_ids: list[UUID] = []
+    if isinstance(claim_ids_raw, list):
+        for cid in claim_ids_raw:
+            try:
+                claim_ids.append(UUID(str(cid)))
+            except (ValueError, TypeError):
+                continue
+    return {
+        "title": title,
+        "body": body,
+        "topic": topic,
+        "priority": priority,
+        "claim_ids": claim_ids,
+    }
+
+
+async def _aggregate_party(
+    party: str, propositions: list[dict],
+) -> list[dict]:
+    """Ask Claude to group one party's propositions; return normalized rows."""
+    if not propositions:
+        return []
+    prompt = _build_prompt(party, propositions)
+
+    try:
+        raw_result = await claude_session.query_json(prompt)
+    except RuntimeError as e:
+        # Surface CLI-unavailable specifically so the caller can report
+        # cleanly instead of crashing the whole job.
+        raise RuntimeError(
+            f"argument_aggregator: claude_session.query_json failed for party "
+            f"'{party}': {e}"
+        ) from e
+
+    if not isinstance(raw_result, list):
+        logger.warning(
+            "argument_aggregator: Claude returned non-list (%s) for party '%s'",
+            type(raw_result).__name__, party,
+        )
+        return []
+
+    out: list[dict] = []
+    for entry in raw_result:
+        norm = _normalize_argument(entry)
+        if norm:
+            out.append(norm)
+    return out
+
+
+async def aggregate_claims_to_arguments(
+    case_id: UUID, force: bool = False,
+) -> dict:
+    """For a given case, group existing claims into distinct legal arguments.
+
+    Args:
+        case_id: The case UUID.
+        force: If True, delete existing ``legal_arguments`` for the case
+            before aggregating. Otherwise short-circuit if any rows exist.
+
+    Returns:
+        A summary dict:
+        ``{"status": "completed"|"skipped"|"no_claims"|"llm_unavailable",
+           "by_party": {party: count}, "total": int, "message": ...}``
+    """
+    pool = await db.get_pool()
+
+    async with pool.acquire() as conn:
+        existing = await conn.fetchval(
+            "SELECT COUNT(*) FROM legal_arguments WHERE case_id = $1",
+            case_id,
+        )
+        if existing and not force:
+            return {
+                "status": "skipped",
+                "message": f"Found {existing} existing arguments. Use force=True to re-run.",
+                "total": existing,
+            }
+
+        if force and existing:
+            await conn.execute(
+                "DELETE FROM legal_arguments WHERE case_id = $1", case_id,
+            )
+
+        # Pull all claims for this case, grouped by party.
+        rows = await conn.fetch(
+            """SELECT id, party_role, claim_text, claim_index, source_document
+               FROM claims
+               WHERE case_id = $1
+               ORDER BY party_role, claim_index""",
+            case_id,
+        )
+
+    if not rows:
+        return {
+            "status": "no_claims",
+            "message": "No claims found for this case. Run extract_claims first.",
+            "total": 0,
+        }
+
+    # Group propositions by party.
+    by_party: dict[str, list[dict]] = {}
+    for r in rows:
+        party = r["party_role"]
+        # Map deprecated 'appraiser' or unknown labels to 'unknown'.
+        if party not in ALLOWED_PARTIES:
+            party = "unknown"
+        by_party.setdefault(party, []).append(dict(r))
+
+    party_counts: dict[str, int] = {}
+    inserted = 0
+    errors: list[str] = []
+
+    for party, props in by_party.items():
+        try:
+            arguments = await _aggregate_party(party, props)
+        except RuntimeError as e:
+            # Most likely cause: Claude CLI not installed (running from
+            # the container). Don't crash — record the gap and continue.
+            msg = str(e)
+            if "Claude CLI not found" in msg:
+                return {
+                    "status": "llm_unavailable",
+                    "message": (
+                        "Claude CLI not available. This service must run from "
+                        "the local MCP server (not the FastAPI container)."
+                    ),
+                    "total": 0,
+                }
+            errors.append(f"{party}: {msg}")
+            continue
+
+        if not arguments:
+            party_counts[party] = 0
+            continue
+
+        async with pool.acquire() as conn:
+            async with conn.transaction():
+                for idx, arg in enumerate(arguments):
+                    arg_id = await conn.fetchval(
+                        """INSERT INTO legal_arguments
+                            (case_id, party, argument_index, argument_title,
+                             argument_body, legal_topic, priority)
+                           VALUES ($1, $2, $3, $4, $5, $6, $7)
+                           RETURNING id""",
+                        case_id,
+                        party,
+                        idx + 1,
+                        arg["title"],
+                        arg["body"],
+                        arg["topic"],
+                        arg["priority"],
+                    )
+                    for cid in arg["claim_ids"]:
+                        try:
+                            await conn.execute(
+                                """INSERT INTO legal_argument_propositions
+                                    (argument_id, claim_id)
+                                   VALUES ($1, $2)
+                                   ON CONFLICT DO NOTHING""",
+                                arg_id, cid,
+                            )
+                        except Exception as e:  # noqa: BLE001
+                            # Likely FK violation if the LLM hallucinated
+                            # a claim_id. Log and continue.
+                            logger.warning(
+                                "argument_aggregator: skipped bad claim_id %s for arg %s: %s",
+                                cid, arg_id, e,
+                            )
+                    inserted += 1
+        party_counts[party] = len(arguments)
+
+    result: dict = {
+        "status": "completed",
+        "total": inserted,
+        "by_party": party_counts,
+        "propositions_processed": len(rows),
+    }
+    if errors:
+        result["errors"] = errors
+        result["status"] = "completed_with_errors"
+    return result
+
+
+async def get_legal_arguments(
+    case_id: UUID, party: str = "",
+) -> list[dict]:
+    """Return aggregated legal arguments for a case, optionally filtered by party.
+
+    Each row includes ``supporting_claims`` (list of source claim_ids).
+    """
+    pool = await db.get_pool()
+    async with pool.acquire() as conn:
+        if party and party in ALLOWED_PARTIES:
+            rows = await conn.fetch(
+                """SELECT id, case_id, party, argument_index, argument_title,
+                          argument_body, legal_topic, priority, cited_precedents,
+                          created_at, updated_at
+                   FROM legal_arguments
+                   WHERE case_id = $1 AND party = $2
+                   ORDER BY priority, argument_index""",
+                case_id, party,
+            )
+        else:
+            rows = await conn.fetch(
+                """SELECT id, case_id, party, argument_index, argument_title,
+                          argument_body, legal_topic, priority, cited_precedents,
+                          created_at, updated_at
+                   FROM legal_arguments
+                   WHERE case_id = $1
+                   ORDER BY party, priority, argument_index""",
+                case_id,
+            )
+
+        # Pull supporting claim ids for each argument in one round-trip.
+        arg_ids = [r["id"] for r in rows]
+        supporting: dict[UUID, list[str]] = {}
+        if arg_ids:
+            joins = await conn.fetch(
+                """SELECT argument_id, claim_id
+                   FROM legal_argument_propositions
+                   WHERE argument_id = ANY($1::uuid[])""",
+                arg_ids,
+            )
+            for j in joins:
+                supporting.setdefault(j["argument_id"], []).append(str(j["claim_id"]))
+
+    out: list[dict] = []
+    for r in rows:
+        d = dict(r)
+        d["id"] = str(d["id"])
+        d["case_id"] = str(d["case_id"])
+        d["supporting_claims"] = supporting.get(r["id"], [])
+        out.append(d)
+    return out