gate_v1_rollout/rollout_series_report/README.md

# Rollout-Serie und Stabilitätsanalyse für Gate‑V1

## Purpose

Erstellung einer reproduzierbaren Rollout-Analyse aus CI-Artefakten zur Stabilisierung und Vorbereitung des Gate‑V1‑Systems auf produktive Nutzung.

**Problemstellung:** Gate‑V1 generiert CI‑Feedback, aber ohne belastbare Zeitreihen oder Kontrollwerte. Der Rollout erfordert quantifizierbare Stabilität, nicht nur Funktionsfähigkeit.

**Ziele:**
- Aggregierte Metriken über CI‑Runs erfassen
- Unknown‑Raten analysieren und klassifizieren
- Deterministische CSV‑Basis für Rollout‑Entscheidungen erzeugen
- Whitelist‑Mechanismus für Unknown‑Klassen implementieren

## Kontext & Hintergrund

Sammlung von CI‑Artefakten im JSON‑Format (gate_result.json) pro Run.

**Gruppierung:**
- policy_hash
- outcome
- unknown_rate
- top_reasons

**Trace-Metadaten / zusätzliche Tags:**
- policy_hash zur Versionsidentifikation
- unknown_rate als Qualitätskennzahl pro Run

**Domänenkontext:**
- CI/CD‑Systemintegration
- Gating‑Mechanismen für Software‑Deployments

**Outlier-Definition:**
- Methode: Identifikation wiederkehrender Unknown‑Klassen
- Beschreibung: Spitzenwerte (Spikes) in Unknown‑Raten werden nach Top‑Reason gruppiert und korreliert mit Fail‑Signalen überprüft.
- Metrik: unknown_rate

**Motivation:**
- Übergang von subjektivem CI‑Monitoring zu messbarer Rollout‑Kontrolle
- Reduktion von False‑Positives durch Unknown‑Klassifikation
- Erhöhung der Policy‑Stabilität durch deterministische Aggregation

## Methode / Spezifikation

**Übersicht:**
- Script rollup_rollout.py verarbeitet gate_result.json‑Dateien zu rollout_series.csv.
- Jeder Datensatz repräsentiert einen CI‑Run mit Policy‑Version und Ergebnissen.
- Unknown‑Klassen werden durch zusätzlichen Whitelist‑Mechanismus getrennt beobachtet.

**Algorithmen / Verfahren:**
- Einlesen aller gate_result.json aus definiertem Artefakt‑Verzeichnis
- Extraktion der Felder policy_hash, outcome, unknown_rate, top_reasons
- Deterministisches Aggregieren zu rollout_series.csv
- Optionales Mapping von Unknowns gegen unknown_whitelist.json

### Bootstrap-Übersicht

Kein numerisches Resampling; Serie dient als deterministische Beobachtung über Läufe.

**Zielgrößen:**
- unknown_rate_min
- unknown_rate_median
- unknown_rate_max
- Häufigkeiten von Unknown‑Klassen

### Abgeleitete Effektgrößen

**Risk Difference (Differenz der Raten):**
- Definition: Vergleich der Unknown‑Raten zwischen Whitelist‑ und Non‑Whitelist‑Klassen.
- Bootstrap: Keine Bootstrap‑Anwendung; feste Häufigkeitszählung.

**Risk Ratio:**
- Definition: Optionaler Indikator bei Übergang zu WARN‑Phase zur Beobachtung von Signal‑vs‑Unknown‑Verhalten.
- Bootstrap: Nicht implementiert.

## Input / Output

### Input-Anforderungen

**Hardware:**
**Software:**
- Python ≥ 3.9
- JSON‑fähiges Dateisystem
- Zugriff auf CI‑Artefakte

**Konfiguration:**
- Path zur Sammlung der gate_result.json‑Dateien
- optional: unknown_whitelist.json im Root‑Verzeichnis

### Erwartete Rohdaten

**Felder pro Run:**
- policy_hash
- outcome
- unknown_rate
- top_reasons

**Formatbeispiele:**
- { "policy_hash": "a6f53e", "outcome": "COMMENT", "unknown_rate": 0.08, "top_reasons": ["flaky_test"] }

**Trace-Daten:**
- Format: CSV-Ausgabe rollout_series.csv
- Hinweis: Alle Einträge deterministisch sortiert nach Run‑ID oder Timestamp

### Analyse-Ausgaben

**Pro Gruppe / pro Governor:**
- unknown_rate_min
- unknown_rate_median
- unknown_rate_max
- class_frequency_table

**Vergleichsausgaben:**

- Trace-Muster: Identifikation wiederkehrender Unknown‑Muster je policy_hash

## Workflow / Nutzung

**Analyse-Workflow:**
- CI‑Runs durchführen und gate_result.json erzeugen
- Script rollup_rollout.py ausführen
- Output in rollout_series.csv prüfen
- Optional: unknown_whitelist.json ergänzen und erneut aggregieren
- Statistische Metriken (min/median/max) in rollout_series_v1.md dokumentieren

### Trace-Template-Anforderungen

**Ziel:** Einheitliche Sammlung von Gate‑Ergebnissen über viele Runs zur Aufdeckung systematischer Muster.

**Erforderliche Tags & Metadaten:**
- policy_hash
- unknown_rate
- top_reasons

**trace-cmd-Setup:**
- CI muss Artefakte mit gate_result.json generieren
- rollup_rollout.py benötigt Pfadvariable CI_ARTIFACT_PATH

**Run-Design für Contributors:**
- Mindestens 40 Runs zur Ableitung stabiler Schwellenwerte sammeln

## Interpretation & erwartete Ergebnisse

**Kernbefunde:**
- Unknown‑Spitzen korrelieren überwiegend mit wiederkehrenden spezifischen Top‑Reasons.
- Echte FAIL‑Signale treten unabhängig von diesen Unknown‑Mustern auf.
- Unknown‑Klasse kann strukturiert reduziert werden.

**Implikationen für Experimente:**
- Whitelist‑Definition dient als Instrument zur kontrollierten Reduktion von Pseudo‑Anomalien.
- Gate‑Kommentare werden kompakter und klarer, was Akzeptanz im CI‑Prozess erhöht.

**Planungsziel:**
- Ziel: Beginn der WARN‑Phase mit definierten Schwellen für Unknown‑Rate und Outcome‑Mapping.
- Vorgehen:
  - Rollout‑Serie bis N≈40 erweitern
  - Median‑basierten Threshold bestimmen
  - False‑Positive‑Rate vor Phase‑Wechsel bewerten

## Limitationen & Fallstricke

**Datenbezogene Limitationen:**
- Ungleichmäßige Run‑Verteilung kann Median verzerren
- Fehlende oder fehlerhafte JSON‑Felder führen zu unvollständiger CSV

**Kausalität & Generalisierbarkeit:**
- Korrelation zwischen Unknown‑Rate und Fail‑Signalen ist nicht notwendigerweise kausal

**Praktische Fallstricke:**
- Whitelist‑Pflege erfordert Disziplin und regelmäßige Revision
- Fehlende Konsistenz in policy_hash‑Versionierung erschwert Langzeitvergleiche

## Nächste Schritte & Erweiterungen

**Geplante Experimente:**
- Rollout‑Serie mit ≥40 Runs erweitern
- Threshold‑Tuning für WARN‑Schwelle testen

**Analyseziele:**
- Quantitative Bestimmung der False‑Positive‑Reduktion
- Messung der Unknown‑Ratenstabilität über Policy‑Versionen hinweg

**Regression & Modellierung:**
- Optionale Risikomodellierung Unknown_vs_Fail‑Ratio

**Community-Beiträge:**
- Struktur und CSV‑Format für andere Gate‑Rollouts freigeben