MCP-Tasks: Contracts & Quality-Tools Integration

Beschreibung

# Ergänzung zu Task #29: Contracts & Quality-Tools

Diese Spezifikation ERGÄNZT Task #29 um Prüfpflichten.

---

## Kontext: Normative Contracts

Der Server verwendet verbindliche Contracts zur Qualitätssicherung:

### 1. Betriebsdokumentation Contract
- **Pfad:** `/var/www/docs/contracts/betriebsdokumentation-pruefung_v1.1.yaml`
- **Scope:** `/app/Views/docs/**/*.php`
- **Status:** active

**Validierungsfaktoren (Priorität):**
| Faktor | Severity | Prüft |
|--------|----------|-------|
| path_existence | critical | Dateipfade müssen existieren |
| command_validity | critical | Befehle syntaktisch korrekt |
| service_accuracy | critical | Ports/Versionen aktuell |
| config_correctness | major | Konfig-Beispiele stimmen |
| structure_compliance | major | Breadcrumb, h1, Tabelle, Code |
| link_integrity | major | Interne Links funktionieren |
| terminology | minor | Einheitliche Begriffe |

**Pass-Schwelle:**
- 0 critical → sonst rejected
- max 2 major → sonst revision required
- max 5 minor

### 2. Layered Architecture Contract
- **Pfad:** `/var/www/docs/contracts/layered-architecture-pruefung_v1.0.yaml`
- **Scope:** `/src/**/*.php`, `/app/**/*.php` (außer Views/docs)
- **Status:** active

**Architektur:**
```
/src/ → MVC (Backend)
├── Domain/ → Fachlogik, Entities
├── UseCases/ → Anwendungsfälle
├── Infrastructure/ → DB, External Services
├── Controller/ → Request/Response
└── View/ → Templates

/app/ → MVP (Frontend)
├── Presenter/ → UI-Logik
└── View/ → Passive Views
```

**Validierungsfaktoren:**
| Faktor | Severity | Prüft |
|--------|----------|-------|
| directory_structure | critical | Erwartete Verzeichnisse |
| file_placement | critical | Dateien im richtigen Layer |
| import_compliance | critical | use-Statements regelkonform |
| layer_logic_compliance | major | Code passt zur Layer-Rolle |
| cycle_detection | critical | Keine zyklischen Abhängigkeiten |

**Forbidden Imports:**
- /src → /app (critical)
- /app → /src/Infrastructure (critical)
- /app/View → /app/Presenter (critical)
- /src/Domain → /src/Infrastructure (critical)

---

## Kontext: PHP Quality Tools

**Installation:** `/opt/php-tools/`
**Check-Script:** `/opt/scripts/php-check.sh`

| Tool | Zweck | Severity |
|------|-------|----------|
| PHPStan 2.1.33 | Statische Analyse Level 5 | critical |
| PHP-CS-Fixer 3.92.3 | PSR-12 Code Style | major |
| Semgrep 1.146.0 | OWASP Security (SQLi, XSS, etc.) | critical |
| Composer Audit | Dependency CVEs | critical |

---

## ZUSÄTZLICHE MCP-Tools (ergänzt #29)

### 11. contracts_list
**Zweck:** Verfügbare Contracts auflisten

**Parameter:** keine

**Rückgabe:**
```json
{
"contracts": [
{
"name": "betriebsdokumentation_validation",
"version": "1.1.0",
"status": "active",
"scope": "/app/Views/docs/**/*.php"
},
{
"name": "layered_architecture_validation",
"version": "1.0.0",
"status": "active",
"scope": "/src/**/*.php, /app/**/*.php"
}
]
}
```

---

### 12. contracts_validate
**Zweck:** Contract-Validierung ausführen

**Parameter:**
- contract (required): betriebsdokumentation | layered_architecture
- path (optional): Spezifischer Pfad, sonst gesamter Scope
- fix (optional, bool): Automatische Korrektur wo möglich

**Rückgabe:**
```json
{
"contract": "betriebsdokumentation",
"outcome": "revision_required",
"violations": {
"critical": 0,
"major": 3,
"minor": 2
},
"findings": [
{
"factor": "config_correctness",
"severity": "major",
"file": "/app/Views/docs/modul/apache.php",
"message": "Konfiguration veraltet",
"line": 45
}
]
}
```

---

### 13. quality_check
**Zweck:** PHP-Quality-Prüfung ausführen

**Parameter:**
- path (optional, default: /var/www/dev.campus.systemische-tools.de): Zu prüfender Pfad
- checks (optional, default: all): phpstan | cs-fixer | semgrep | composer-audit | all
- fix (optional, bool): Style-Probleme automatisch korrigieren

**Rückgabe:**
```json
{
"path": "/src/Controller/Api/TaskController.php",
"passed": false,
"results": {
"phpstan": {
"passed": true,
"errors": 0
},
"cs_fixer": {
"passed": false,
"issues": 3,
"fixed": 0
},
"semgrep": {
"passed": true,
"vulnerabilities": 0
},
"composer_audit": {
"passed": true,
"cves": 0
}
}
}
```

---

### 14. quality_report
**Zweck:** Qualitätsbericht für Codebase erstellen

**Parameter:**
- scope (optional): full | changes_only
- format (optional): json | markdown

**Rückgabe:** Vollständiger Report über alle Prüfungen

---

## WORKFLOW-INTEGRATION

### Bei Task-Erstellung mit Code-Änderungen:
```
1. tasks_create → Task erstellen
2. [KI arbeitet]
3. quality_check --path=<geänderte Dateien>
4. IF failed:
→ tasks_result --status=partial --error_message="Quality check failed"
→ Korrigieren und erneut prüfen
5. IF Code in /app/Views/docs:
→ contracts_validate --contract=betriebsdokumentation
6. IF Code in /src oder /app (nicht docs):
→ contracts_validate --contract=layered_architecture
7. IF all passed:
→ tasks_result --status=success
→ tasks_status --status=completed
```

### Vor Deployment (Sync zu Prod):
```
1. quality_check --checks=all
2. contracts_validate --contract=betriebsdokumentation
3. contracts_validate --contract=layered_architecture
4. IF any critical → BLOCK SYNC
5. IF major > threshold → WARNING
```

---

## ENFORCEMENT-REGELN für MCP-Server

Der MCP-Server MUSS diese Regeln durchsetzen:

1. **Nach jeder Code-Änderung (Edit/Write auf .php):**
- Automatisch `quality_check` ausführen
- Bei Security-Violations (Semgrep): Warnung an KI

2. **Vor Task-Completion:**
- `quality_check` auf alle geänderten Dateien
- Relevante `contracts_validate` ausführen
- Task darf nur bei 0 critical violations als "completed" markiert werden

3. **Kein Git auf diesem Server:**
- Deployment erfolgt via `/opt/scripts/sync-dev-prod.sh`
- MCP-Server sollte NIEMALS git-Befehle ausführen

---

## Deliverables (ergänzt zu #29)

6. Integration der Contract-Validierung
7. Integration der PHP-Quality-Checks
8. Automatische Enforcement-Logik
9. Fehlermeldungen mit konkreten Korrekturhinweisen

Aktionen

Ergebnisse

Quality-Tools (contracts_list, contracts_validate, quality_check, quality_report) in quality_tools.py implementiert

Kommentare

← Zurück zur Task-Liste