gate_v0_1_patch/ci_policy_documentation/README.md

# CI-Policy Dokumentation für Gate v0.1

## Purpose

Definition der CI-Policy-Regeln und Entscheidungslogik für Gate v0.1 auf Basis der k-of-n Aggregation und Decision-Margin-Mechanismen.

**Problemstellung:** Vor Gate v0.1 führten unstabile Aggregationsentscheidungen (z. B. k=3-of-6) zu häufigen Flip-Flops. Ziel ist eine belastbare, überprüfbare Regelung der Entscheidungslogik.

**Ziele:**
- Standardisierte Entscheidung über PASS/WARN/FAIL in CI-Prozessen
- Nachvollziehbare Aggregationslogik mit reproduzierbarem Backtest
- Etablierung robuster Schwellenwerte zur Reduktion von Fehlalarmen

## Kontext & Hintergrund

Frozen-Runs #20–#29 mit Ausgabedaten wie mischfenster_p95, margin, flaky_flag und subset_flip_count.

**Gruppierung:**
- run_id
- pinned

**Trace-Metadaten / zusätzliche Tags:**
- pinned Zustand
- Metrik mischfenster_p95
- Subset-Stabilität (subset_flip_count)

**Domänenkontext:**
- CI-Gate-Entscheidungssystem
- Performance- und Stabilitätstests

**Outlier-Definition:**
- Methode: Decision-Margin-Threshold
- Beschreibung: Definiert eine Zone um den Schwellenwert, in der FAIL in WARN umgewandelt wird.
- Metrik: mischfenster_p95

**Motivation:**
- Reduktion von Fehlalarmen in automatisierten Evaluationsläufen
- Transparente Entscheidungsfindung basierend auf Backtest-Daten
- Klare Trennung zwischen Warn- und Fehlerzuständen

## Methode / Spezifikation

**Übersicht:**
- Verwendet k-of-n Aggregation für n=6 Subentscheidungen.
- Standardkonfiguration: k=5-of-6 gilt als stabil.
- Decision-Margin-Zone konvertiert knappe FAILs zu WARNs.
- Flaky-Flag kennzeichnet instabile Subsets mit hoher Flip-Rate.

**Algorithmen / Verfahren:**
- Berechne mischfenster_p95 pro Run.
- Aggregiere n=6 Resultate per k-of-n-Logik.
- Ermittle Decision-Margin basierend auf Schwellwert.
- Setze flaky_flag auf TRUE, wenn subset_flip_count > 0.

### Bootstrap-Übersicht

Kein Bootstrap-Verfahren im eigentlichen Sinne – Backtest erfolgt über existierende Frozen-Runs.

**Zielgrößen:**
- Stabilität der Gate-Entscheidung
- Minimierung von Flip-Flops

### Abgeleitete Effektgrößen

**Risk Difference (Differenz der Raten):**
- Definition: Differenzanteil von FAIL-Entscheidungen zwischen Konfigurationen (z. B. k=3 und k=5).
- Bootstrap: Backtest-basierte Beobachtung über Runs #20–#29, keine Resampling-Verfahren verwendet.

**Risk Ratio:**
- Definition: Verhältnis des Fehl-Alarms zwischen alten und neuen Gate-Einstellungen.
- Bootstrap: Berechnet aus beobachteten CSV-Aggregaten.

## Input / Output

### Input-Anforderungen

**Hardware:**
- Standard CI-Runner Hardware, keine Spezialhardware erforderlich

**Software:**
- Python >= 3.9
- CSV-Auswertung in Pandas optional

**Konfiguration:**
- Gate-Parameter: k=5, n=6
- Decision-Margin-Threshold definieren (experimentabhängig)

### Erwartete Rohdaten

**Felder pro Run:**
- run_id
- pinned
- mischfenster_p95
- decision
- margin
- flaky_flag
- subset_flip_count

**Formatbeispiele:**
- 24, true, 0.935, WARN, 0.012, false, 1

**Trace-Daten:**
- Format: CSV
- Hinweis: Keine neuen Messungen, ausschließlich Reanalyse bestehender Frozen-Runs.

### Analyse-Ausgaben

**Pro Gruppe / pro Governor:**
- Anteil von PASS/WARN/FAIL pro Run
- Stabilitätsindikator pro Aggregationsgruppe

**Vergleichsausgaben:**
- k=3-of-6 vs k=5-of-6
  - Δ: Reduktion der Flip-Flop-Rate um ~X Prozentpunkte
  - RR: Rückgang der Fehlalarme um Faktor Y

- Trace-Muster: Visualisierung von subset_flip_count vs. Decision-Margin zur Stabilitätsanalyse

## Workflow / Nutzung

**Analyse-Workflow:**
- Importiere Frozen-Run-Daten (#20–#29).
- Führe k-of-n Aggregation mit k=5, n=6 aus.
- Berechne Decision-Margin und flaky_flag.
- Erzeuge zusammenfassende CSV- und Debug-JSON-Dateien.
- Verifiziere Ergebnisse gegen bestehende Aggregationskonfigurationen (z. B. k=3).

### Trace-Template-Anforderungen

**Ziel:** Einheitlicher Vergleich über identische Run-Strukturen hinweg.

**Erforderliche Tags & Metadaten:**
- run_id
- pinned
- mischfenster_p95

**trace-cmd-Setup:**
- Nutze unveränderte Pipeline-Konfiguration.
- Keine zusätzlichen Measurement-Probes aktivieren.

**Run-Design für Contributors:**
- Ergänze Runs nur, wenn Freeze-Kriterien erfüllt sind.
- Dokumentiere Margin-Threshold-Werte im Git-Metadatenfeld.

## Interpretation & erwartete Ergebnisse

**Kernbefunde:**
- k=5-of-6 eliminiert instabile Flip-Flop-Verhalten fast vollständig.
- Decision-Margin verringert Fehlalarme ohne signifikante Sensitivitätseinbußen.
- Flakiness wird transparent markiert statt überdeckt.

**Implikationen für Experimente:**
- Standardisierung der k-of-n Aggregation im CI-System.
- Integration von WARN-Stufen zur kontrollierten Fehlertoleranz.

**Planungsziel:**
- Ziel: Reduktion fehlerhafter FAIL-Entscheidungen in der CI-Auswertung.
- Vorgehen:
  - Einführung von Decision-Margin-Grenzen.
  - Validierung über Backtest-Ergebnisse.
  - Anwendung konsistenter Aggregationsparameter in zukünftigen Versionen.

## Limitationen & Fallstricke

**Datenbezogene Limitationen:**
- Begrenzte Stichprobe (nur Runs #20–#29).
- Keine neuen Messproben; mögliche Datenverzerrungen bleiben bestehen.

**Bootstrap-spezifische Limitationen:**
- Keine echte Bootstrap-Stichprobenbildung; Ergebnisse basieren auf beobachteten Werten.

**Kausalität & Generalisierbarkeit:**
- Ergebnisse gelten nur für identische Metriken und Run-Strukturen.
- Keine Generalisierung auf andere Gate-Signale ohne Revalidierung.

**Praktische Fallstricke:**
- Fehlende Dynamik bei Änderungen der Metrik mischfenster_p95.
- Decision-Margin kann bei stark schwankenden Runs Fehlinterpretationen erzeugen.

## Nächste Schritte & Erweiterungen

**Geplante Experimente:**
- Evaluation anderer k-Werte zur Stabilitätsanalyse unter variierenden Bedingungen.

**Analyseziele:**
- Umfassende Gegenüberstellung k=3 vs. k=5 mit Flip-Flop-Tabelle.
- Integration der CI-Reaktionsregeln direkt in das Reporting.

**Regression & Modellierung:**
- Aufbau eines Regressionsmodells zur Vorhersage von Flakiness basierend auf margin- und subset-Metriken.

**Community-Beiträge:**
- Bereitstellung der Backtest-CSV und CI-Policy-Definition zur Reproduktion durch andere Teammitglieder.