Add policy_metadata/README.md

policy_metadata/README.md

@@ -0,0 +1,157 @@
+# 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