Add policy_definition/README.md

policy_definition/README.md

@@ -0,0 +1,165 @@
+# CI-Policy v0.1 – Definition und Evaluierung für PASS/WARN/FAIL Entscheidungen
+
+## Purpose
+
+Formale Definition einer Continuous-Integration-Policy, die Gate-Entscheidungen aus Debug-Daten automatisiert und nachvollziehbar trifft.
+
+**Problemstellung:** Bisherige Entscheidungslogik in CI-Gates war inkonsistent und interpretierbar. Ziel ist eine deterministische, testbare Policy, die WARN- und FAIL-Bereiche formal abgrenzt.
+
+**Ziele:**
+- Reduktion subjektiver Entscheidungen in CI-Ergebnissen
+- Standardisierung der Kategorien PASS, WARN und FAIL
+- Einführung maschinenlesbarer Regeldefinition für Gate-Entscheidungen
+
+## Kontext & Hintergrund
+
+Backtest-CSV-Daten (#20–#29) mit Debug-JSON-Ausgaben je Run
+
+**Gruppierung:**
+- pinned
+- unpinned
+
+**Trace-Metadaten / zusätzliche Tags:**
+- margin
+- decision
+- flaky_flag
+- subset_flipcount
+- mischfenster_p95
+
+**Domänenkontext:**
+- Continuous Integration
+- Automatisiertes Testen
+- Qualitätssicherung von CI-Gates
+
+**Motivation:**
+- Formalisierung bisher intuitiver Gate-Entscheidungen
+- Stabilisierung der Bewertung von knappen Testergebnissen (Margin-Zone)
+- Reduzierung von Flip-Flops zwischen Runs durch konsistente Regeln
+
+## Methode / Spezifikation
+
+**Übersicht:**
+- Die Policy nutzt Metriken aus Debug-JSON zur Festlegung deterministischer Entscheidungen in CI-Läufen.
+- Regeln sind in YAML definiert, maschinenlesbar und unit-testbar.
+
+**Algorithmen / Verfahren:**
+- PASS → allow
+- WARN → allow + label + Auto-Rerun
+- FAIL → block
+- WARN wird getriggert, wenn Margin-Zone oder flaky_flag zutrifft
+
+### Bootstrap-Übersicht
+
+Nicht anwendbar – deterministische Regelbewertung, kein Resampling.
+
+**Zielgrößen:**
+## Input / Output
+
+### Input-Anforderungen
+
+**Hardware:**
+**Software:**
+- Python >=3.8
+- YAML Parser
+- CI-System (z. B. GitHub Actions, Jenkins)
+
+**Konfiguration:**
+- Integration der YAML-Policy in CI-Pipeline als Validierungsstufe
+
+### Erwartete Rohdaten
+
+**Felder pro Run:**
+- timestamp
+- run_id
+- decision
+- margin
+- flaky_flag
+- subset_flipcount
+- mischfenster_p95
+
+**Formatbeispiele:**
+- 2024-02-10T08:33:20Z, run_020, WARN, 0.04, true, 1, 0.87
+
+**Trace-Daten:**
+- Format: JSON
+- Hinweis: Debug-JSON pro Run liefert Basisdaten für Policy-Entscheidung
+
+### Analyse-Ausgaben
+
+**Pro Gruppe / pro Governor:**
+**Vergleichsausgaben:**
+
+- Trace-Muster: Analyse von WARN-Raten im Zeitverlauf als Indikator für Policy-Drift
+
+## Workflow / Nutzung
+
+**Analyse-Workflow:**
+- Debug-JSONs aus CI-Runs sammeln.
+- Policy auf Debug-JSON anwenden, Entscheidung ableiten.
+- Per Run eine Zeile als Report-Artefakt schreiben.
+- Mittlere WARN-Rate überwachen, Threshold-basierte Alarme setzen (z. B. >30% über 20 Runs).
+
+### Trace-Template-Anforderungen
+
+**Ziel:** Einheitliche Auswertungskriterien für alle CI-Runs.
+
+**Erforderliche Tags & Metadaten:**
+- margin
+- flaky_flag
+- decision
+
+**trace-cmd-Setup:**
+- Policy automatisch im Post-Test-Step ausführen
+- Ergebnis als CSV-Zeile im Artefaktordner speichern
+
+**Run-Design für Contributors:**
+- Jeder Commit löst einen CI-Run aus
+- Policy bewertet Run-Ergebnisse deterministisch
+- WARN-Runs werden automatisch rerunnt
+
+## Interpretation & erwartete Ergebnisse
+
+**Kernbefunde:**
+- pinned-Runs bleiben stabil im PASS/WARN-Bereich
+- unpinned-Runs tragen Hauptanteil der WARN-Entscheidungen
+- keine Fehlklassifikation durch Margin-Anpassung
+- kritische Flip-Flops werden formal eliminiert
+
+**Implikationen für Experimente:**
+- Policy-Design verbessert Konsistenz und Nachvollziehbarkeit von Gate-Entscheidungen
+- Automatische Reruns reduzieren unnötige FAIL-Blöcke
+- Drift-Monitoring erlaubt langfristige Quantifizierung der Policy-Stabilität
+
+**Planungsziel:**
+- Ziel: Evaluiere Stabilität und Drift der Policy durch fortlaufende CI-Metrikerfassung.
+- Vorgehen:
+  - Messung der WARN-Rate über sequenzielle Runs
+  - Schwellwert-Alarmierung bei Policy-Drift
+
+## Limitationen & Fallstricke
+
+**Datenbezogene Limitationen:**
+- Backtest-Datensatz ist statisch; neue Laufdaten können abweichende WARN-Verteilungen zeigen
+
+**Kausalität & Generalisierbarkeit:**
+- Policy-Validität hängt von Stabilität der zugrundeliegenden Metriken ab
+
+**Praktische Fallstricke:**
+- Zu enge Margins können unnötige WARNs erzeugen
+- Fehlerhafte flaky_flag-Erkennung beeinflusst Ergebnisqualität
+
+## Nächste Schritte & Erweiterungen
+
+**Geplante Experimente:**
+- Implementierung eines Policy-Drift-Monitors zur Überwachung von WARN-Raten
+
+**Analyseziele:**
+- Langzeitstatistik von PASS/WARN/FAIL
+- Analyse saisonaler Schwankungen in flaky_flag-Raten
+
+**Regression & Modellierung:**
+- Evaluierung einer adaptiven Margin-Zone basierend auf historischen Stable-Runs
+
+**Community-Beiträge:**
+- Open-Source-Veröffentlichung der YAML-Policy und CI-Runner-Integration
+- Feedback-Sammlung zu WARN-Interpretation (soft fail vs. block with rerun)