Task bearbeiten

Titel *

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

Typ

Abbrechen