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