# Rollout-Kriterien für Gate‑V1 im CI‑System

## Purpose

Festlegung der Rollout-Kriterien und Entscheidungslogik für den Gate‑V1‑Step im Continuous Integration (CI).

**Problemstellung:** Fehlende standardisierte Entscheidungskriterien bei der Integration von Gate‑V1 in automatisierte CI‑Pipelines.

**Ziele:**
- Operationelle Einführung von Gate‑V1 als CI‑Step
- Definition von Bewertungs- und Eskalationslogik (PASS, WARN, REVIEW)
- Dokumentation der stabilen Rollout-Phasen und Schwellenwerte

## Kontext & Hintergrund

Die Gate‑V1‑Komponente wertet Metriken aus den Policy-Berechnungen aus und erzeugt daraus ein `gate_result.json`.

**Gruppierung:**
- pro CI‑Run
- pro Policy‑Set

**Trace-Metadaten / zusätzliche Tags:**
- policy_hash zur Nachverfolgbarkeit der Policy-Konfiguration

**Domänenkontext:**
- CI‑Workflows
- kontinuierliche Qualitätssicherung
- automatisierte Policy‑Validierung

**Outlier-Definition:**
- Methode: Schwellenwertbasiert
- Beschreibung: Runs mit Unknown‑Rate > 1 % werden als Ausreißer und REVIEW‑Fälle markiert.
- Metrik: Unknown‑Rate

**Motivation:**
- Transparente, nachvollziehbare Entscheidungen in CI‑Pipelines
- Konsistentes Evaluationsverhalten über mehrere Runs hinweg
- Reduktion des log‑basierten manuellen Prüfaufwands

## Methode / Spezifikation

**Übersicht:**
- Der Gate‑V1‑Step erhält `policy_constants.json` und den daraus berechneten `policy_hash`.
- Er erzeugt ein `gate_result.json` mit Outcome, Hash, Count‑Metriken und Top‑Reasons.
- Er ergänzt den CI‑Lauf um einen kompakten PR‑Kommentar mit diesen Daten.

**Algorithmen / Verfahren:**
- Ermitteln der Unknown‑, WARN‑ und Sichtbarkeitsraten aus Policy‑Ergebnissen.
- Zuweisung eines Outcomes (PASS, WARN, REVIEW) anhand fester Schwellen.
- Speichern der Resultate in `gate_result.json`.
- Posten eines standardisierten CI‑Kommentars mit Hash, Outcome und Begründung.

## Input / Output

### Input-Anforderungen

**Hardware:**
**Software:**
- CI‑Umgebung mit JSON‑Support
- Zugriff auf Policy‑Auswertungsartefakte

**Konfiguration:**
- Bereitstellung von `policy_constants.json`
- Berechnung eines stabilen `policy_hash`

### Erwartete Rohdaten

**Felder pro Run:**
- policy_hash
- outcome
- unknown_rate
- visibility
- top_reasons

**Formatbeispiele:**
- {"policy_hash": "abcd1234", "outcome": "PASS", "unknown_rate": 0.009, "visibility": 0.995, "top_reasons": ["Sichtbarkeit ≥99%", "Unknown ≤1%"]}

**Trace-Daten:**
- Format: JSON
- Hinweis: Keine Zusatzfelder oder Telemetrie; minimalistische Struktur für diff‑basierte Vergleiche.

### Analyse-Ausgaben

**Pro Gruppe / pro Governor:**
- Unknown‑Rate
- Visibility‑Wert
- Warn‑Rate

- Trace-Muster: Stabilität des `policy_hash` über wiederholte Runs prüfen.

## Workflow / Nutzung

**Analyse-Workflow:**
- Ausführen des Gate‑V1‑Steps in der CI‑Pipeline.
- Erzeugen des `gate_result.json`.
- Kommentieren des PRs mit kompaktem Ergebnisblock.
- Bewerten der Resultate über mehrere Runs.

### Trace-Template-Anforderungen

**Ziel:** Stabilität und Nachvollziehbarkeit der CI‑Ergebnisse.

**Erforderliche Tags & Metadaten:**
- policy_hash
- outcome
- Counts‑Metriken (Unknown, Visibility, etc.)

**trace-cmd-Setup:**
- Keine zusätzlichen Tracepunkte im comment‑only‑Modus.

**Run-Design für Contributors:**
- Mindestens zwei Run‑Kategorien (Baseline, Degradiert).
- Kein Parameter‑Tuning während der Validierung.

## Interpretation & erwartete Ergebnisse

**Kernbefunde:**
- PASS bei stabiler Unknown‑Rate ≤1 % und Sichtbarkeit ≥99 %.
- REVIEW bei erhöhter Unknown‑Rate.
- Byte‑stabile Resultate zwischen Runs sind Indikator funktionaler Stabilität.

**Implikationen für Experimente:**
- Gate‑V1 kann reproduzierbare und erklärbare CI‑Entscheidungen liefern.
- Die Unknown‑Kategorie dient als Trigger für manuelle Prüfung.

**Planungsziel:**
- Ziel: Schrittweiser Rollout des Gate‑Mechanismus mit sicherer Eskalationslogik.
- Vorgehen:
  - Phase 1: comment‑only
  - Phase 2: WARN‑Gate bei definierten Kriterien
  - Option 3: blockend mit harten Bedingungen

## Limitationen & Fallstricke

**Datenbezogene Limitationen:**
- Abhängigkeit von Genauigkeit der Policy‑Metriken.
- Keine Datenvalidierung außerhalb der definierten Counts.

**Kausalität & Generalisierbarkeit:**
- Bewertungen gelten nur für getestete Policy‑Konfigurationen.

**Praktische Fallstricke:**
- Falsche Unknown‑Klassifizierung kann zu unnötigen REVIEWs führen.
- Hash‑Änderungen ohne sichtbare Policy‑Differenz erschweren Vergleichbarkeit.

## Nächste Schritte & Erweiterungen

**Geplante Experimente:**
- Einführung des WARN‑Gates nach stabilen 40 Runs.

**Analyseziele:**
- Quantifizierung der Unknown‑Rate‑Verteilung über längere Zeiträume.

**Regression & Modellierung:**
- Beobachtung der Outcome‑Verteilung über Policy‑Versionen hinweg.

**Community-Beiträge:**
- Best Practices für comment‑only Gates in CI‑Umgebungen dokumentieren.