Contracts

Erstellt: 2025-12-20 | Aktualisiert: 2025-12-31

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?

Zeitpunkt	Contract	Aktion bei Violation
Vor Sync zu Prod	Alle aktiven	Sync blockiert
Nach Dateiänderung	Betriebsdokumentation	Warnung
Bei neuem Modul	Layered Architecture	Ablehnung

Contract-Management

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

Web-UI	/contracts
Datenbank	`ki_dev.contracts`
MCP-Server	mcp-contracts (contracts_* Tools)

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-contracts)

Für Details siehe MCP-Contracts Tools.

Tool	Beschreibung
`contracts_list`	Alle Contracts auflisten
`contracts_get`	Contract nach ID/Name abrufen
`contracts_create`	Neuen Contract anlegen
`contracts_update`	Contract aktualisieren (neue Version)
`contracts_validate`	Validierung ausführen
`contracts_history`	Änderungshistorie abrufen
`contracts_violations`	Letzte Violations abrufen
`contracts_deprecate`	Contract als deprecated markieren

Aktive Contracts (15)

ID	Name	Version	Scope
1	betriebsdokumentation-pruefung	2.0	Docs-Struktur
2	CSS Contract	2.0	Stylelint-Regeln
3	HTML Tables Contract	2.0	Tabellen-Struktur
4	js-browser-architecture-contract	2.0	JavaScript ES Modules
5	layered-architecture-pruefung	3.2	Layer-Grenzen
6	python-pipeline-contract	2.0	Python Code Quality
7	View Structure Contract	2.0	CRUD-Views
8	db-access-security-protocol	2.0	DB Security
9	code-quality-standards	2.1	Code Quality
10	critic-workflow	1.0	Review-Workflow
11	architecture-gate-contract	1.1	PHP File Analysis
12	taxonomy-mapping-contract	1.0.0	Taxonomie-Mapping
13	text-quality-standards	1.0	Text-Qualität
14	htmx-patterns-contract	1.0	HTMX-Patterns
15	SemanticExplorerController	1.0	Semantic Explorer

Severity Levels

Level	Bedeutung	Aktion
critical	Faktisch falsch	Dokument abgelehnt
major	Unvollständig	Überarbeitung nötig
minor	Kosmetisch	Nur protokolliert

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

Script	`/var/www/scripts/contract-check.sh`
Aufruf	`/var/www/scripts/contract-check.sh [path]`
Integration	`/var/www/scripts/sync-dev-prod.sh`
Exit-Codes	0 = OK, 1 = Critical, 2 = Major

Manuell ausführen

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

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