Add rollout_criteria/README.md

rollout_criteria/README.md

@@ -0,0 +1,158 @@
+# Rollout-Kriterien für Gate‑V1 im CI‑System
+
+## Purpose
+
+Festlegung der Rollout-Kriterien und Entscheidungslogik für den Gate‑V1‑Step im Continuous Integration (CI).
+
+**Problemstellung:** Fehlende standardisierte Entscheidungskriterien bei der Integration von Gate‑V1 in automatisierte CI‑Pipelines.
+
+**Ziele:**
+- Operationelle Einführung von Gate‑V1 als CI‑Step
+- Definition von Bewertungs- und Eskalationslogik (PASS, WARN, REVIEW)
+- Dokumentation der stabilen Rollout-Phasen und Schwellenwerte
+
+## Kontext & Hintergrund
+
+Die Gate‑V1‑Komponente wertet Metriken aus den Policy-Berechnungen aus und erzeugt daraus ein `gate_result.json`.
+
+**Gruppierung:**
+- pro CI‑Run
+- pro Policy‑Set
+
+**Trace-Metadaten / zusätzliche Tags:**
+- policy_hash zur Nachverfolgbarkeit der Policy-Konfiguration
+
+**Domänenkontext:**
+- CI‑Workflows
+- kontinuierliche Qualitätssicherung
+- automatisierte Policy‑Validierung
+
+**Outlier-Definition:**
+- Methode: Schwellenwertbasiert
+- Beschreibung: Runs mit Unknown‑Rate > 1 % werden als Ausreißer und REVIEW‑Fälle markiert.
+- Metrik: Unknown‑Rate
+
+**Motivation:**
+- Transparente, nachvollziehbare Entscheidungen in CI‑Pipelines
+- Konsistentes Evaluationsverhalten über mehrere Runs hinweg
+- Reduktion des log‑basierten manuellen Prüfaufwands
+
+## Methode / Spezifikation
+
+**Übersicht:**
+- Der Gate‑V1‑Step erhält `policy_constants.json` und den daraus berechneten `policy_hash`.
+- Er erzeugt ein `gate_result.json` mit Outcome, Hash, Count‑Metriken und Top‑Reasons.
+- Er ergänzt den CI‑Lauf um einen kompakten PR‑Kommentar mit diesen Daten.
+
+**Algorithmen / Verfahren:**
+- Ermitteln der Unknown‑, WARN‑ und Sichtbarkeitsraten aus Policy‑Ergebnissen.
+- Zuweisung eines Outcomes (PASS, WARN, REVIEW) anhand fester Schwellen.
+- Speichern der Resultate in `gate_result.json`.
+- Posten eines standardisierten CI‑Kommentars mit Hash, Outcome und Begründung.
+
+## Input / Output
+
+### Input-Anforderungen
+
+**Hardware:**
+**Software:**
+- CI‑Umgebung mit JSON‑Support
+- Zugriff auf Policy‑Auswertungsartefakte
+
+**Konfiguration:**
+- Bereitstellung von `policy_constants.json`
+- Berechnung eines stabilen `policy_hash`
+
+### Erwartete Rohdaten
+
+**Felder pro Run:**
+- policy_hash
+- outcome
+- unknown_rate
+- visibility
+- top_reasons
+
+**Formatbeispiele:**
+- {"policy_hash": "abcd1234", "outcome": "PASS", "unknown_rate": 0.009, "visibility": 0.995, "top_reasons": ["Sichtbarkeit ≥99%", "Unknown ≤1%"]}
+
+**Trace-Daten:**
+- Format: JSON
+- Hinweis: Keine Zusatzfelder oder Telemetrie; minimalistische Struktur für diff‑basierte Vergleiche.
+
+### Analyse-Ausgaben
+
+**Pro Gruppe / pro Governor:**
+- Unknown‑Rate
+- Visibility‑Wert
+- Warn‑Rate
+
+- Trace-Muster: Stabilität des `policy_hash` über wiederholte Runs prüfen.
+
+## Workflow / Nutzung
+
+**Analyse-Workflow:**
+- Ausführen des Gate‑V1‑Steps in der CI‑Pipeline.
+- Erzeugen des `gate_result.json`.
+- Kommentieren des PRs mit kompaktem Ergebnisblock.
+- Bewerten der Resultate über mehrere Runs.
+
+### Trace-Template-Anforderungen
+
+**Ziel:** Stabilität und Nachvollziehbarkeit der CI‑Ergebnisse.
+
+**Erforderliche Tags & Metadaten:**
+- policy_hash
+- outcome
+- Counts‑Metriken (Unknown, Visibility, etc.)
+
+**trace-cmd-Setup:**
+- Keine zusätzlichen Tracepunkte im comment‑only‑Modus.
+
+**Run-Design für Contributors:**
+- Mindestens zwei Run‑Kategorien (Baseline, Degradiert).
+- Kein Parameter‑Tuning während der Validierung.
+
+## Interpretation & erwartete Ergebnisse
+
+**Kernbefunde:**
+- PASS bei stabiler Unknown‑Rate ≤1 % und Sichtbarkeit ≥99 %.
+- REVIEW bei erhöhter Unknown‑Rate.
+- Byte‑stabile Resultate zwischen Runs sind Indikator funktionaler Stabilität.
+
+**Implikationen für Experimente:**
+- Gate‑V1 kann reproduzierbare und erklärbare CI‑Entscheidungen liefern.
+- Die Unknown‑Kategorie dient als Trigger für manuelle Prüfung.
+
+**Planungsziel:**
+- Ziel: Schrittweiser Rollout des Gate‑Mechanismus mit sicherer Eskalationslogik.
+- Vorgehen:
+  - Phase 1: comment‑only
+  - Phase 2: WARN‑Gate bei definierten Kriterien
+  - Option 3: blockend mit harten Bedingungen
+
+## Limitationen & Fallstricke
+
+**Datenbezogene Limitationen:**
+- Abhängigkeit von Genauigkeit der Policy‑Metriken.
+- Keine Datenvalidierung außerhalb der definierten Counts.
+
+**Kausalität & Generalisierbarkeit:**
+- Bewertungen gelten nur für getestete Policy‑Konfigurationen.
+
+**Praktische Fallstricke:**
+- Falsche Unknown‑Klassifizierung kann zu unnötigen REVIEWs führen.
+- Hash‑Änderungen ohne sichtbare Policy‑Differenz erschweren Vergleichbarkeit.
+
+## Nächste Schritte & Erweiterungen
+
+**Geplante Experimente:**
+- Einführung des WARN‑Gates nach stabilen 40 Runs.
+
+**Analyseziele:**
+- Quantifizierung der Unknown‑Rate‑Verteilung über längere Zeiträume.
+
+**Regression & Modellierung:**
+- Beobachtung der Outcome‑Verteilung über Policy‑Versionen hinweg.
+
+**Community-Beiträge:**
+- Best Practices für comment‑only Gates in CI‑Umgebungen dokumentieren.