Contracts

Contracts sind normative YAML-Dokumente, die verbindliche Regeln für Code, Architektur und Dokumentation definieren. Sie ermöglichen automatisierte Validierung und stellen Qualitätsstandards sicher.

Was sind Contracts?

• Normativ: Verbindliche Regeln, keine Empfehlungen
• Maschinenlesbar: YAML-Format für automatisierte Prüfung
• Versioniert: Änderungen erfordern explizite Versionierung
• Validierbar: Klare Pass/Fail-Kriterien

Wann werden Contracts geprüft?

Contract-Management

Contracts werden in der Datenbank verwaltet und sind über Web-UI und MCP-API zugänglich.

Web-UI Features

• /contracts - Liste aller Contracts mit Filter
• /contracts/new - Neuen Contract erstellen
• /contracts/{id} - Contract-Details, YAML-Inhalt, Validierungshistorie
• /contracts/{id}/edit - Contract bearbeiten (erzeugt neue Version)
• Validierung direkt aus der UI auslösen
• Versionshistorie mit Diff-Ansicht

MCP-Tools (mcp-tasks)

Datenbankschema

-- Contracts mit YAML-Content und Versionierung
ki_protokoll.contracts
├── id, uuid, name, version, status
├── yaml_content, scope_description
└── created_at, created_by, updated_at

-- Änderungshistorie
ki_protokoll.contract_history
├── contract_id, previous_yaml, previous_version
└── change_description, changed_at, changed_by

-- Validierungsläufe
ki_protokoll.contract_validations
├── contract_id, result (passed/failed)
├── critical_count, major_count, minor_count
└── violations (JSON), triggered_by, duration_ms

Aktive Contracts

Betriebsdokumentation v1.1

Validiert Server- und Betriebsdokumentation:

• Dateipfade müssen existieren
• Befehle müssen syntaktisch korrekt sein
• Ports/Versionen müssen aktuell sein
• Struktur: Breadcrumb, h1, Intro, Tabelle, Commands

Layered Architecture v1.0

Validiert die Schichtenarchitektur:

• /src (MVC): Framework, Controller, Domain, UseCases, Infrastructure, View
• /app (MVP): Presenter, View
• Dependency Rules zwischen Layern
• Verbotene Imports und Platzierungen

HTML Tables Contract v1.0

Validiert HTML-Tabellen nach DRY/KISS/SRP-Prinzipien:

• Keine "Aktionen"-Spalte mit Details-Button - ID/Titel verlinken
• Keine Modals - echte URLs verwenden
• Alle Spalten sortierbar (data-sort Attribut)
• Suchfeld für jede Tabelle
• Wiederverwendbare DataTable-Komponente

CSS Contract v1.0

Validiert CSS nach WCAG 2.1 AA Accessibility-Standards:

• Farbkontrast min. 4.5:1 für Text (A11Y-001)
• Vordergrundfarbe immer mit Hintergrundfarbe definieren (COL-001)
• Focus-Styles niemals entfernen (A11Y-004)
• Mindestschriftgröße 16px für Fließtext (TYP-001)
• CSS-Variablen für Farben verwenden (COL-002)
• Kein !important außer für Utility-Klassen (FRB-001)

JS Browser Architecture v2

Validiert JavaScript für Browser-Anwendungen:

• ES Modules ohne Build-Tools (ECMAScript 2024)
• Strikte Gleichheit (===)
• const/let statt var
• Double Quotes, Semikolons, 2 Spaces
• Keine eval(), no-implied-eval (Security)

Python Pipeline Contract v1.0

Validiert Python-Code in der KI-Pipeline:

• Type Hints für alle Funktionen (Parameter + Return)
• Docstrings für Module, Klassen, Public Functions
• Keine bare except, keine silent failures
• Security: Keine hardcoded Credentials, kein eval()
• Imports sortiert, keine Wildcards

View Structure Contract v1.0

Validiert die Struktur von CRUD-Views (index, show, new, edit):

• RESTful URLs: /{resource}, /{resource}/new, /{resource}/{id}, /{resource}/{id}/edit
• Seitenaufbau: Breadcrumb → h1 → Tabelle/Content → Actions
• Keine page-container, Cards oder verschachtelte Strukturen
• Formulare: class="form", max-width: 600px, flache form-group
• Referenz: /src/View/tasks/* als Vorlage

Gilt nicht für: /docs (eigener Contract), /chat (interaktives Tool), /home (Landing Pages)

Neue CRUD-Ressource hinzufügen

1. Verzeichnis erstellen: /src/View/{resource}/
2. Views anlegen: index.php, show.php, new.php, edit.php
3. Contract-Scope erweitern: includes += "/src/View/{resource}/*.php"
4. Vorlage: /src/View/tasks/* kopieren und anpassen

Zukünftige Contracts

Geplante Contracts für zukünftige Erweiterungen:

• API Contract - OpenAPI/Swagger Validierung

Severity Levels

Pass-Schwelle

• 0 critical violations (sonst: rejected)
• max 2 major violations (sonst: revision required)
• max 5 minor violations (sonst: approved with notes)

Automatische Validierung

Alle Contracts werden automatisch vor dem Sync zu Produktion geprüft.

Pre-Sync Hook

Geprüfte Contracts

Manuell ausführen

# Alle Contracts prüfen
/opt/scripts/contract-check.sh

# Mit spezifischem Pfad
/opt/scripts/contract-check.sh /var/www/dev.campus.systemische-tools.de