feat: unified fiscal coverage - PIS/COFINS applicability + conditional RTC in one definition, one queue, one panel

- central/app/unified_fiscal_coverage.py: pure rules (PIS/COFINS NOT_APPLICABLE/REQUIRED/OPTIONAL/NEEDS_REVIEW, RTC only when the ERP switch is on)
- agent: read-only loader (unified_fiscal.py) replaces the legacy/expanded module; findings feed the single operational state, coverage and blocker queue
- hub: BLOCKED_FISCAL_DATA blockers (PIS/COFINS/RTC) share the queue; stale ones close on the next full pass; dashboard breakdown gains CEST/PIS/COFINS/RTC
- panel: legacy/expanded coverage block removed; discreet 'Reforma Tributaria: Ativa/Desativada'
- docs: unified_fiscal_completeness, pis_cofins_applicability, rtc_pis_cofins_model + official source manifests; read-only E2E script

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

agent/src/gti_fiscal_agent/unified_fiscal.py

@@ -0,0 +1,102 @@
+"""READ-ONLY ERP loader for the unified fiscal completeness (PIS/COFINS applicability + RTC when the ERP has the reform on).
+
+The rules live in central/app/unified_fiscal_coverage.py (pure). This module only observes the ERP through an already open
+READ ONLY connection (SELECT only): schema capabilities, RTC catalog, PARAMETROS.USAR_REFORMA_TRIBUTARIA and the product columns.
+Nothing is written and no value is ever filled in.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+from datetime import date
+
+from central.app.unified_fiscal_coverage import PIS_COFINS_FIELDS, catalog_integrity, evaluate_product, rtc_enabled
+
+PRODUCT_TABLE = "C000025"
+RTC_CCLASSTRIB_TABLE = "RTC_CCLASSTRIB"
+RTC_CST_TABLE = "RTC_CST"
+PRODUCT_COLUMNS = ("CODIGO", "CCLASSTRIB") + PIS_COFINS_FIELDS + ("PISCOFINS", "INCIDENCIA_PISCOFINS")
+TRUTHY = {"1", "S", "T", "TRUE"}
+
+
+def detect_rtc_capabilities(schema: dict, *, param_value=None, catalog: dict | None = None, physical_fk: bool | None = None) -> dict:
+    """schema: {TABLE: {COLUMN, ...}}. Fail-closed: anything not proven is False. Old databases without RTC simply report False."""
+    product_cols = set(schema.get(PRODUCT_TABLE, ()))
+    class_cols = set(schema.get(RTC_CCLASSTRIB_TABLE, ()))
+    cst_cols = set(schema.get(RTC_CST_TABLE, ()))
+    has_product = "CCLASSTRIB" in product_cols
+    has_class = {"CCLASSTRIB", "CSTIBSCBS"} <= class_cols
+    has_cst = "CSTIBSCBS" in cst_cols
+    caps = {
+        "HAS_PRODUCT_CCLASSTRIB": has_product, "HAS_RTC_CCLASSTRIB_TABLE": has_class, "HAS_RTC_CST_TABLE": has_cst,
+        "HAS_RTC_RELATIONSHIP": bool(has_product and has_class and has_cst), "HAS_PHYSICAL_RTC_FK": bool(physical_fk),
+        "RTC_ENABLED_BY_PARAM": False if param_value is None else str(param_value).strip().upper() in TRUTHY,
+        "RTC_CATALOG_VALID": False,
+    }
+    if catalog is not None and has_class and has_cst:
+        caps["RTC_CATALOG_VALID"] = catalog_integrity(catalog)["valid"]
+    return caps
+
+
+def load_rtc_context(cursor) -> tuple[dict, dict | None, dict]:
+    """Schema + catalog + ERP parameter through a READ ONLY cursor. Never raises for a database that lacks RTC."""
+    schema: dict[str, set] = {}
+    cursor.execute("SELECT TRIM(rf.RDB$RELATION_NAME), TRIM(rf.RDB$FIELD_NAME) FROM RDB$RELATION_FIELDS rf WHERE rf.RDB$RELATION_NAME IN ('C000025','RTC_CCLASSTRIB','RTC_CST','PARAMETROS')")
+    for table, column in cursor.fetchall():
+        schema.setdefault(table, set()).add(column)
+    extras: dict = {"param_value": None, "physical_fk": False}
+    if "USAR_REFORMA_TRIBUTARIA" in schema.get("PARAMETROS", ()):
+        try:
+            cursor.execute("SELECT FIRST 1 USAR_REFORMA_TRIBUTARIA FROM PARAMETROS")
+            row = cursor.fetchone()
+            extras["param_value"] = None if row is None or row[0] is None else row[0]
+        except Exception:  # noqa: BLE001 - unreadable parameter => RTC stays off (not enabled by the ERP)
+            extras["param_value"] = None
+    try:
+        cursor.execute("SELECT COUNT(*) FROM RDB$RELATION_CONSTRAINTS WHERE RDB$RELATION_NAME = 'C000025' AND RDB$CONSTRAINT_TYPE = 'FOREIGN KEY' AND RDB$CONSTRAINT_NAME CONTAINING 'CCLASSTRIB'")
+        extras["physical_fk"] = cursor.fetchone()[0] > 0
+    except Exception:  # noqa: BLE001
+        pass
+    catalog = None
+    class_cols = schema.get(RTC_CCLASSTRIB_TABLE, set())
+    if {"CCLASSTRIB", "CSTIBSCBS"} <= class_cols and "CSTIBSCBS" in schema.get(RTC_CST_TABLE, set()):
+        validity = "INICIO_VIGENCIA" in class_cols and "FIM_VIGENCIA" in class_cols
+        cursor.execute("SELECT TRIM(CCLASSTRIB), TRIM(CSTIBSCBS)" + (", INICIO_VIGENCIA, FIM_VIGENCIA" if validity else "") + " FROM RTC_CCLASSTRIB")
+        rows = cursor.fetchall()
+        classes = {r[0]: (r[1] or None) for r in rows}
+        cursor.execute("SELECT TRIM(CSTIBSCBS) FROM RTC_CST")
+        catalog = {"classes": classes, "cst": {r[0] for r in cursor.fetchall()}, "duplicates": len(rows) - len(classes)}
+        if validity:
+            catalog["validity"] = {r[0]: (r[2], r[3]) for r in rows}
+    return schema, catalog, extras
+
+
+def read_products(cursor, schema: dict) -> list[dict]:
+    """SELECT of only the columns that exist (old schemas keep working)."""
+    have = schema.get(PRODUCT_TABLE, set())
+    columns = [c for c in PRODUCT_COLUMNS if c in have]
+    if "CODIGO" not in columns:
+        return []
+    cursor.execute(f"SELECT {', '.join(columns)} FROM {PRODUCT_TABLE} ORDER BY CODIGO")
+    return [dict(zip(columns, row)) for row in cursor.fetchall()]
+
+
+def assess_from_connection(conn, company: dict | None, *, today: date | None = None, rtc_override: bool | None = None) -> dict:
+    """One read-only pass. Returns {"context": {...}, "findings": {product_code: evaluate_product(...)}}.
+    rtc_override forces RTC on/off for simulations WITHOUT touching the ERP parameter (tests / what-if only)."""
+    cursor = conn.cursor()
+    schema, catalog, extras = load_rtc_context(cursor)
+    caps = detect_rtc_capabilities(schema, param_value=extras["param_value"], catalog=catalog, physical_fk=extras["physical_fk"])
+    enabled = rtc_enabled(caps) if rtc_override is None else bool(rtc_override and caps["HAS_RTC_RELATIONSHIP"])
+    rtc = {"enabled": enabled, "catalog": catalog, "catalog_valid": caps["RTC_CATALOG_VALID"]}
+    today = today or date.today()
+    products = read_products(cursor, schema)
+    findings = {}
+    for p in products:
+        found = evaluate_product(p, company, rtc, today)
+        found["input_fingerprint"] = hashlib.sha256(json.dumps({k: (None if v is None else str(v).strip()) for k, v in p.items()} | {"rtc": enabled}, sort_keys=True).encode()).hexdigest()
+        findings[str(p.get("CODIGO") or "")] = found
+    integrity = catalog_integrity(catalog) if catalog else None
+    return {"context": {"rtc_enabled": enabled, "rtc_supported": caps["HAS_RTC_RELATIONSHIP"], "rtc_catalog_valid": caps["RTC_CATALOG_VALID"], "rtc_param": extras["param_value"],
+                        "catalog_integrity": integrity, "crt": (company or {}).get("crt"), "capabilities": caps, "products_evaluated": len(products)},
+            "findings": findings}