Contract-Enforcement-System

Erstellt: 2025-12-22 | Aktualisiert: 2025-12-27

Das Enforcement-System stellt sicher, dass alle Code-Qualitätsstandards und Architektur-Regeln automatisch durchgesetzt werden.

Architektur-Übersicht


┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Contracts     │────▶│    Validator    │────▶│     Hooks       │
│  (YAML in DB)   │     │ (contract-check)│     │ (Python Scripts)│
└─────────────────┘     └─────────────────┘     └─────────────────┘
        │                       │                       │
        ▼                       ▼                       ▼
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  MCP-Contracts  │     │  sync-dev-prod  │     │   Claude Code   │
│    (API)        │     │    (Workflow)   │     │  (PreToolUse)   │
└─────────────────┘     └─────────────────┘     └─────────────────┘

Komponenten

1. Contracts (Datenbank)

Contracts sind in ki_protokoll.contracts gespeichert und definieren Regeln im YAML-Format.

Contract	Zweck	Severity
code-quality-standards	LOC-Limits, PDO-Verbot in Controllern	critical/major
layered-architecture	Schichtenarchitektur (MVC/MVP)	critical
db-access-security	Keine direkten DB-Befehle	critical
python-pipeline	Python-Qualitätsstandards	critical/major
view-structure	CRUD-View-Standards	critical/major
css-standards	Accessibility (WCAG 2.1)	critical/major
critic-workflow	Review-Prozess Definition	critical

2. Validator (contract-check.sh)

Führt Contract-Validierungen aus:

/opt/scripts/contract-check.sh /var/www/dev.campus.systemische-tools.de

3. Hooks (PreToolUse)

Blockieren Architektur-Verletzungen BEVOR Code geschrieben wird:

Hook	Trigger	Prüfung
block_direct_db.py	Bash	mysql/mariadb-Befehle
architecture_guard.py	Write/Edit	Controller LOC > 500, PDO in Controller

Workflow

Pre-Sync Validierung

Contract-Check: Alle Contracts werden validiert
PHP Quality: PHPStan, PHP-CS-Fixer, Semgrep
Unit Tests: PHPUnit ausführen
Entscheidung: Critical=Block, Major=Warn, Minor=Log

PreToolUse Hooks

Claude Code ruft Write/Edit/Bash auf
Hook prüft Content/Command
Bei Violation: Exit 2 → Block + Fehlermeldung
Bei OK: Exit 0 → Durchlassen

MCP-Tools

contracts_list

contracts_list(compact=True)

Listet alle Contracts auf.

contracts_validate

contracts_validate(name="code-quality-standards")

Validiert einen Contract gegen die Codebase.

contracts_create/update

contracts_create(name="...", yaml_content="...", version="1.0")

Erstellt oder aktualisiert einen Contract.

Troubleshooting

"Mein Code wird blockiert"

Prüfe welcher Hook blockiert (Fehlermeldung)
Prüfe welche Regel verletzt wird
Behebe das Problem (z.B. Service extrahieren statt PDO in Controller)

"Contract-Validierung findet nichts"

Prüfe ob Contract aktiv ist: contracts_get(name="...")
Prüfe Scope-Pfade im Contract
Prüfe ob Dateien existieren

"Sync wird blockiert"

Führe /opt/scripts/contract-check.sh aus
Prüfe Critical/Major Violations
Behebe alle Critical-Violations
Major-Violations können als Baseline akzeptiert werden

Baseline für Legacy-Code

Aktuell akzeptierte Legacy-Violations (nicht für neue Code):

SemanticExplorerRepository.php: 797 LOC
SystemExplorerRepository.php: 709 LOC
ChunkSyncService.php: 551 LOC

Neue Violations in diesen Dateien werden trotzdem blockiert.