gate_v1_in_ci/rollout_criteria/README.md

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.