From b24ce1cddc48c9534eb1c6ccc9f6bd7a695e2e88 Mon Sep 17 00:00:00 2001 From: Mika Date: Fri, 20 Feb 2026 11:16:32 +0000 Subject: [PATCH] Add rollout_series_report/README.md --- rollout_series_report/README.md | 187 ++++++++++++++++++++++++++++++++ 1 file changed, 187 insertions(+) create mode 100644 rollout_series_report/README.md diff --git a/rollout_series_report/README.md b/rollout_series_report/README.md new file mode 100644 index 0000000..2765797 --- /dev/null +++ b/rollout_series_report/README.md @@ -0,0 +1,187 @@ +# 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