# Policy Monitoring und Metrik-Dokumentation

## Purpose

Dokumentation der Metriken, Schwellenwerte und Metadaten zur Überwachung eines Policy-Rollouts.

**Problemstellung:** Zur Laufzeitüberwachung von Policy-Rollouts müssen Zustände, Fehler und Unbekannte robust gezählt und dokumentiert werden, um fundierte Aktivierungsentscheidungen zu treffen.

**Ziele:**
- Definieren von Go/No-Go-Schwellenwerten für Policy-Aktivierung
- Absicherung der Fehlertoleranz in der Metrikerfassung
- Sicherstellung reproduzierbarer CI-Ausgaben über Versions-Hashes

## Kontext & Hintergrund

Aggregierte Auswertung von drift_report.json und rollout_metrics.json während des Policy‑Tests.

**Gruppierung:**
- pinned
- unpinned
- unknowns

**Trace-Metadaten / zusätzliche Tags:**
- policy_hash
- policy_constants.json
- drift_report.json
- rollout_metrics.json

**Domänenkontext:**
- Policy-Rollout-Überwachung
- CI-Auswertung
- Fehlerklassifikation

**Motivation:**
- Reduktion zufälliger Policy‑Fehler durch frühe Metrikprüfung
- Verbesserte Vergleichbarkeit und Nachvollziehbarkeit zwischen Policy‑Versionen

## Methode / Spezifikation

**Übersicht:**
- Verwendung von Go/No-Go‑Regeln für die Policy‑Aktivierung nach 30 Runs oder 7 Tagen
- Aggregieren der Metriken WARN, FAIL, Unknowns und Overrides pro Stratum
- Einbindung eines policy_hash zur Versions‑Nachvollziehbarkeit

**Algorithmen / Verfahren:**
- Zählen von WARN und FAIL pro Stratum aus den Drift‑Reports
- Ermittlung der Unknown‑Rate und Ursache (Contract/Schema)
- Erfassen von Overrides pro Run mit Flag oder Defaultwert
- Einordnung fehlender Felder als Unknown‑Klasse unknown_field_missing
- Sortierung der Ausgabe alphabetisch nach Keys und namenbasiert in Arrays

## Input / Output

### Input-Anforderungen

**Hardware:**
**Software:**
- Python (policy_eval.py)
- CI‑System mit Zugriff auf drift_report.json

**Konfiguration:**
- Schema‑Definition für Drift‑Reports
- Konfigurierbare Policy‑Schwellenwerte

### Erwartete Rohdaten

**Felder pro Run:**
- run_id
- policy_state
- WARN_count
- FAIL_count
- Unknown_count
- Overrides_count

**Formatbeispiele:**
- {"run_id": "r001", "policy_state": "pinned", "WARN_count": 1, ... }

**Trace-Daten:**
- Format: JSON
- Hinweis: Fehlende Felder werden automatisch als Unknown‑Klasse klassifiziert.

### Analyse-Ausgaben

**Pro Gruppe / pro Governor:**
- WARN/FAIL‑Rate pro Stratum
- Unknown‑Klassifikation nach Ursache
- Overrides pro Run

**Vergleichsausgaben:**
- pinned vs unpinned
  - Δ: Differenz der kombinierten WARN+FAIL‑Rate

- Trace-Muster: Stabilitätsprüfung über 30 Runs oder 7 Tage bezogen auf policy_hash

## Workflow / Nutzung

**Analyse-Workflow:**
- Laden der letzten Drift‑Reports
- Erzeugen der rollout_metrics.json mit Aggregaten
- Härten der policy_eval.py gegen Feldfehler
- Sortierte JSON‑Ausgabe für CI‑Diff
- Einfügen des policy_hash in CI‑Kommentar

### Trace-Template-Anforderungen

**Ziel:** Sicherstellen, dass alle Drift‑Report‑Datensätze vollständig oder ersetzbar sind

**Erforderliche Tags & Metadaten:**
- policy_hash
- schema_version
- policy_state

**trace-cmd-Setup:**
- Log‑Extraktion über CI‑Pipeline nach jedem Run

**Run-Design für Contributors:**
- Mindestens 30 Runs, gemischte Policy‑Strata (pinned/unpinned)

## Interpretation & erwartete Ergebnisse

**Kernbefunde:**
- System verhält sich stabil trotz unvollständiger Felder.
- Diff‑freundliche Ausgaben reduzieren CI‑Rauschen signifikant.
- Go/No‑Go‑Regel operationalisiert Policy‑Freigaben mit klaren numerischen Grenzen.

**Implikationen für Experimente:**
- Frühzeitige Aktivierung des WARN‑Gates möglich, wenn Schwellen vor Tag 7 erfüllt sind.

**Planungsziel:**
- Ziel: Stabile Policy‑Überwachung ohne Betriebsabbrüche
- Vorgehen:
  - Schwellenwerte definieren
  - Metriken automatisiert zählen
  - Fehler tolerant klassifizieren

## Limitationen & Fallstricke

**Datenbezogene Limitationen:**
- Fehlende Felder können semantische Lücken verdecken, wenn Unknown‑Klassifikation zu grob bleibt.

**Kausalität & Generalisierbarkeit:**
- Metrikschwellen basieren nur auf beobachteten Runs und sind nicht kausal verallgemeinerbar.

**Praktische Fallstricke:**
- Manuelle Overrides können unbemerkt den Go/No‑Go‑Status verzerren.

## Nächste Schritte & Erweiterungen

**Geplante Experimente:**
- Schema‑Check mit Defaultwerten vor Policy‑Evaluation

**Analyseziele:**
- Vereinheitlichung der Unknown‑Labels
- Automatische Erkennung fehlerhafter Reports

**Community-Beiträge:**
- Definition eines offenen Schemas für rollout_metrics.json