# CI-Policy v0.1 – Definition und Evaluierung für PASS/WARN/FAIL Entscheidungen

## Purpose

Formale Definition einer Continuous-Integration-Policy, die Gate-Entscheidungen aus Debug-Daten automatisiert und nachvollziehbar trifft.

**Problemstellung:** Bisherige Entscheidungslogik in CI-Gates war inkonsistent und interpretierbar. Ziel ist eine deterministische, testbare Policy, die WARN- und FAIL-Bereiche formal abgrenzt.

**Ziele:**
- Reduktion subjektiver Entscheidungen in CI-Ergebnissen
- Standardisierung der Kategorien PASS, WARN und FAIL
- Einführung maschinenlesbarer Regeldefinition für Gate-Entscheidungen

## Kontext & Hintergrund

Backtest-CSV-Daten (#20–#29) mit Debug-JSON-Ausgaben je Run

**Gruppierung:**
- pinned
- unpinned

**Trace-Metadaten / zusätzliche Tags:**
- margin
- decision
- flaky_flag
- subset_flipcount
- mischfenster_p95

**Domänenkontext:**
- Continuous Integration
- Automatisiertes Testen
- Qualitätssicherung von CI-Gates

**Motivation:**
- Formalisierung bisher intuitiver Gate-Entscheidungen
- Stabilisierung der Bewertung von knappen Testergebnissen (Margin-Zone)
- Reduzierung von Flip-Flops zwischen Runs durch konsistente Regeln

## Methode / Spezifikation

**Übersicht:**
- Die Policy nutzt Metriken aus Debug-JSON zur Festlegung deterministischer Entscheidungen in CI-Läufen.
- Regeln sind in YAML definiert, maschinenlesbar und unit-testbar.

**Algorithmen / Verfahren:**
- PASS → allow
- WARN → allow + label + Auto-Rerun
- FAIL → block
- WARN wird getriggert, wenn Margin-Zone oder flaky_flag zutrifft

### Bootstrap-Übersicht

Nicht anwendbar – deterministische Regelbewertung, kein Resampling.

**Zielgrößen:**
## Input / Output

### Input-Anforderungen

**Hardware:**
**Software:**
- Python >=3.8
- YAML Parser
- CI-System (z. B. GitHub Actions, Jenkins)

**Konfiguration:**
- Integration der YAML-Policy in CI-Pipeline als Validierungsstufe

### Erwartete Rohdaten

**Felder pro Run:**
- timestamp
- run_id
- decision
- margin
- flaky_flag
- subset_flipcount
- mischfenster_p95

**Formatbeispiele:**
- 2024-02-10T08:33:20Z, run_020, WARN, 0.04, true, 1, 0.87

**Trace-Daten:**
- Format: JSON
- Hinweis: Debug-JSON pro Run liefert Basisdaten für Policy-Entscheidung

### Analyse-Ausgaben

**Pro Gruppe / pro Governor:**
**Vergleichsausgaben:**

- Trace-Muster: Analyse von WARN-Raten im Zeitverlauf als Indikator für Policy-Drift

## Workflow / Nutzung

**Analyse-Workflow:**
- Debug-JSONs aus CI-Runs sammeln.
- Policy auf Debug-JSON anwenden, Entscheidung ableiten.
- Per Run eine Zeile als Report-Artefakt schreiben.
- Mittlere WARN-Rate überwachen, Threshold-basierte Alarme setzen (z. B. >30% über 20 Runs).

### Trace-Template-Anforderungen

**Ziel:** Einheitliche Auswertungskriterien für alle CI-Runs.

**Erforderliche Tags & Metadaten:**
- margin
- flaky_flag
- decision

**trace-cmd-Setup:**
- Policy automatisch im Post-Test-Step ausführen
- Ergebnis als CSV-Zeile im Artefaktordner speichern

**Run-Design für Contributors:**
- Jeder Commit löst einen CI-Run aus
- Policy bewertet Run-Ergebnisse deterministisch
- WARN-Runs werden automatisch rerunnt

## Interpretation & erwartete Ergebnisse

**Kernbefunde:**
- pinned-Runs bleiben stabil im PASS/WARN-Bereich
- unpinned-Runs tragen Hauptanteil der WARN-Entscheidungen
- keine Fehlklassifikation durch Margin-Anpassung
- kritische Flip-Flops werden formal eliminiert

**Implikationen für Experimente:**
- Policy-Design verbessert Konsistenz und Nachvollziehbarkeit von Gate-Entscheidungen
- Automatische Reruns reduzieren unnötige FAIL-Blöcke
- Drift-Monitoring erlaubt langfristige Quantifizierung der Policy-Stabilität

**Planungsziel:**
- Ziel: Evaluiere Stabilität und Drift der Policy durch fortlaufende CI-Metrikerfassung.
- Vorgehen:
  - Messung der WARN-Rate über sequenzielle Runs
  - Schwellwert-Alarmierung bei Policy-Drift

## Limitationen & Fallstricke

**Datenbezogene Limitationen:**
- Backtest-Datensatz ist statisch; neue Laufdaten können abweichende WARN-Verteilungen zeigen

**Kausalität & Generalisierbarkeit:**
- Policy-Validität hängt von Stabilität der zugrundeliegenden Metriken ab

**Praktische Fallstricke:**
- Zu enge Margins können unnötige WARNs erzeugen
- Fehlerhafte flaky_flag-Erkennung beeinflusst Ergebnisqualität

## Nächste Schritte & Erweiterungen

**Geplante Experimente:**
- Implementierung eines Policy-Drift-Monitors zur Überwachung von WARN-Raten

**Analyseziele:**
- Langzeitstatistik von PASS/WARN/FAIL
- Analyse saisonaler Schwankungen in flaky_flag-Raten

**Regression & Modellierung:**
- Evaluierung einer adaptiven Margin-Zone basierend auf historischen Stable-Runs

**Community-Beiträge:**
- Open-Source-Veröffentlichung der YAML-Policy und CI-Runner-Integration
- Feedback-Sammlung zu WARN-Interpretation (soft fail vs. block with rerun)