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.