Protokoll #6583

{
    "event": "PreToolUse",
    "tool_name": "Write",
    "tool_input": {
        "file_path": "\/var\/www\/dev.campus.systemische-tools.de\/docs\/report-architecture-gate-implementation.md",
        "content": "# Report: Architecture Gate Implementation\n\n**Datum:** 2025-12-23\n**Status:** Phase 1 abgeschlossen, aktiv\n**Contract:** architecture-gate-contract v1.1 (ID 11)\n\n---\n\n## Zusammenfassung\n\nNach Supervision-Review wurde der Architecture Gate Contract technisch durchgesetzt. Der Pre-Hook `architecture_guard.py` ist aktiv und blockiert Architektur-Verletzungen **bevor** Code geschrieben wird.\n\n---\n\n## Supervision-Feedback: Umgesetzte Korrekturen\n\n### 1. Regelreferenzierung korrigiert\n\n**Problem:** Ursprünglicher Plan referenzierte B-Regeln (Post-Creation) im Pre-Hook.\n\n**Lösung:** Neuer `hard_constraints`-Abschnitt im Contract mit eigener H-Nummerierung:\n\n```yaml\nhard_constraints:\n  applies_pre_creation: true\n  rules:\n    - id: H1  # statt B10\n    - id: H2  # statt B5\n    - id: H3  # statt B4\n    - id: H4  # statt B4\/B12\n    - id: H5  # statt B4\/B12\n```\n\n### 2. Controller-Erkennung präzisiert\n\n**Problem:** Unklare Definition, was ein Controller ist.\n\n**Lösung:** Ausschließlich Pfad-basiert, keine Heuristiken:\n\n```python\ndef is_controller(file_path: str) -> bool:\n    return \"\/Controller\/\" in file_path\n```\n\n### 3. Service-Verbot eingeschränkt\n\n**Problem:** `new \\w+Service\\(` war zu grob, Application Services sind legitim.\n\n**Lösung:** Nur Infrastructure-Services blockieren:\n\n```python\n# Gestrichen: new \\w+Service\\(\n# Neu: new Infrastructure\\\\\n```\n\n### 4. Unscharfe Regeln gestrichen\n\n| Gestrichen | Grund |\n|------------|-------|\n| Duplizierte Methodensignaturen | Ohne AST nicht prüfbar |\n| Business Logic Pattern | Nicht formal definierbar |\n| new Service (generisch) | Zu grob |\n\n### 5. Allowlist definiert\n\n```python\nALLOWED_PATHS = [\n    \"\/Factory\/\",      # Factory darf new verwenden\n    \"\/Bootstrap\/\",    # Bootstrap darf new verwenden\n    \"\/tests\/\",        # Tests dürfen alles\n    \"\/Test\/\",         # PHPUnit Tests\n    \"\/vendor\/\",       # Third-party Code\n]\n```\n\n### 6. Rollback-Entscheidung\n\n**Supervision-Vorgabe:** Kein Rollback. Blockiere vorher oder warne nachher.\n\n**Umsetzung:** Pre-Hook blockiert mit `{\"allowed\": false}`, kein implizites Zurückdrehen.\n\n### 7. Statisch vs. Dynamisch\n\n**Supervision-Vorgabe:** Phase 1 niemals dynamisch.\n\n**Umsetzung:** Regeln in Python hardcoded, kein YAML-Parsing zur Laufzeit.\n\n---\n\n## Implementierte Regeln\n\n### BLOCK (Pre-Hook, nicht verhandelbar)\n\n| ID | Regel | Pattern | Scope |\n|----|-------|---------|-------|\n| H1 | strict_types erforderlich | `declare(strict_types=1)` muss vorhanden sein | Alle PHP-Dateien |\n| H2 | Domain ohne Infrastructure | `use Infrastructure\\` verboten | `\/Domain\/` |\n| H3 | DatabaseFactory nur in Factory | `DatabaseFactory::` verboten | Außerhalb `\/Factory\/` |\n| H4 | Kein new Repository in Controller | `new \\w+Repository(` verboten | `\/Controller\/` |\n| H5 | Kein new Infrastructure in Controller | `new Infrastructure\\` verboten | `\/Controller\/` |\n\n### WARN (Post-Hook, Phase 2)\n\n| ID | Regel | Check | Schwellwert |\n|----|-------|-------|-------------|\n| W1 | Klassengröße | Zeilenanzahl | > 300 |\n| W2 | Constructor-Komplexität | Parameter | > 5 |\n| W3 | SQL im Controller | Keywords | SELECT\/INSERT\/UPDATE\/DELETE |\n| W4 | Fehlende PHPDoc | Public Methods | Ohne Doc |\n\n---\n\n## Technische Umsetzung\n\n### Hook-Script\n\n**Datei:** `\/var\/www\/tools\/ki-protokoll\/claude-hook\/architecture_guard.py`\n\n**Trigger:** PreToolUse → Write → *.php\n\n**Verhalten:**\n1. Prüft ob PHP-Datei\n2. Prüft Allowlist\n3. Iteriert über 5 harte Regeln\n4. Bei Violation: `{\"allowed\": false, \"message\": \"...\"}`\n5. Bei OK: `{\"allowed\": true}`\n\n### Hook-Registrierung\n\n**Datei:** `\/root\/.claude\/settings.json`\n\n```json\n{\n  \"hooks\": {\n    \"PreToolUse\": [\n      {\n        \"matcher\": \"Write\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"\/var\/www\/tools\/ki-protokoll\/claude-hook\/architecture_guard.py\",\n            \"timeout\": 5\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n### Contract-Update\n\n**Version:** 1.0 → 1.1\n\n**Änderungen:**\n- `hard_constraints`-Abschnitt hinzugefügt (H1-H5)\n- `warning_indicators`-Abschnitt hinzugefügt (W1-W4)\n- Allowlist dokumentiert\n\n---\n\n## Testergebnisse\n\nAlle 5 Regeln wurden mit absichtlichen Verstößen getestet:\n\n```\n=== Test H1: Missing strict_types ===\n{\"allowed\": false, \"message\": \"ARCHITECTURE VIOLATION [H1]: Missing declare(strict_types=1)...\"}\n\n=== Test H1: With strict_types (should pass) ===\n{\"allowed\": true}\n\n=== Test H2: Domain uses Infrastructure ===\n{\"allowed\": false, \"message\": \"ARCHITECTURE VIOLATION [H2]: Domain must not use Infrastructure...\"}\n\n=== Test H3: DatabaseFactory outside Factory ===\n{\"allowed\": false, \"message\": \"ARCHITECTURE VIOLATION [H3]: DatabaseFactory only allowed in Factory...\"}\n\n=== Test H3: DatabaseFactory in Factory (should pass) ===\n{\"allowed\": true}\n\n=== Test H4: new Repository in Controller ===\n{\"allowed\": false, \"message\": \"ARCHITECTURE VIOLATION [H4]: new Repository in Controller not allowed...\"}\n\n=== Test H5: new Infrastructure in Controller ===\n{\"allowed\": false, \"message\": \"ARCHITECTURE VIOLATION [H5]: new Infrastructure in Controller not allowed...\"}\n\n=== Test Allowlist: Test path (should pass) ===\n{\"allowed\": true}\n```\n\n---\n\n## Status der Implementierung\n\n| Schritt | Status |\n|---------|--------|\n| Supervision-Review | ✓ Abgeschlossen |\n| Regelmatrix bereinigt | ✓ 5 Block + 4 Warn |\n| Contract v1.1 | ✓ Aktiv |\n| architecture_guard.py | ✓ Implementiert |\n| Tests | ✓ Alle bestanden |\n| Hook registriert | ✓ In settings.json |\n| Beobachtungsphase | ○ Läuft (1 Woche) |\n| Post-Hook (Warnungen) | ○ Phase 2 |\n\n---\n\n## Nächste Schritte\n\n1. **Beobachtungsphase (1 Woche)**\n   - False Positives identifizieren\n   - Allowlist bei Bedarf erweitern\n   - Violation-Häufigkeit monitoren\n\n2. **Phase 2: Post-Hook**\n   - `architecture_validator.py` implementieren\n   - Warnungen für W1-W4\n   - Kein Block, nur Info\n\n3. **Dokumentation**\n   - Integration in `\/docs\/prozesse\/`\n   - Entwickler-Anleitung\n\n---\n\n## Dateien\n\n| Datei | Zweck |\n|-------|-------|\n| `\/var\/www\/tools\/ki-protokoll\/claude-hook\/architecture_guard.py` | Pre-Hook (Blocking) |\n| `\/root\/.claude\/settings.json` | Hook-Konfiguration |\n| `\/var\/www\/dev.campus.systemische-tools.de\/docs\/plan-architecture-gate-enforcement.md` | Plan-Dokument |\n| Contract ID 11 (ki_protokoll.contracts) | architecture-gate-contract v1.1 |\n\n---\n\n## Fazit\n\nDer Architecture Gate ist jetzt ein **echtes Code Gate**, nicht nur Dokumentation. Jede neue PHP-Datei muss die 5 harten Regeln passieren. Die Supervision-Korrekturen wurden vollständig umgesetzt:\n\n- Klare Trennung Block vs. Warn\n- Deterministische Pfad-basierte Erkennung\n- Explizite Allowlist\n- Keine unscharfen Heuristiken\n- Statische Regeln (kein Runtime-YAML)\n"
    }
}

{
    "tool_response": {
        "type": "create",
        "filePath": "\/var\/www\/dev.campus.systemische-tools.de\/docs\/report-architecture-gate-implementation.md",
        "content": "# Report: Architecture Gate Implementation\n\n**Datum:** 2025-12-23\n**Status:** Phase 1 abgeschlossen, aktiv\n**Contract:** architecture-gate-contract v1.1 (ID 11)\n\n---\n\n## Zusammenfassung\n\nNach Supervision-Review wurde der Architecture Gate Contract technisch durchgesetzt. Der Pre-Hook `architecture_guard.py` ist aktiv und blockiert Architektur-Verletzungen **bevor** Code geschrieben wird.\n\n---\n\n## Supervision-Feedback: Umgesetzte Korrekturen\n\n### 1. Regelreferenzierung korrigiert\n\n**Problem:** Ursprünglicher Plan referenzierte B-Regeln (Post-Creation) im Pre-Hook.\n\n**Lösung:** Neuer `hard_constraints`-Abschnitt im Contract mit eigener H-Nummerierung:\n\n```yaml\nhard_constraints:\n  applies_pre_creation: true\n  rules:\n    - id: H1  # statt B10\n    - id: H2  # statt B5\n    - id: H3  # statt B4\n    - id: H4  # statt B4\/B12\n    - id: H5  # statt B4\/B12\n```\n\n### 2. Controller-Erkennung präzisiert\n\n**Problem:** Unklare Definition, was ein Controller ist.\n\n**Lösung:** Ausschließlich Pfad-basiert, keine Heuristiken:\n\n```python\ndef is_controller(file_path: str) -> bool:\n    return \"\/Controller\/\" in file_path\n```\n\n### 3. Service-Verbot eingeschränkt\n\n**Problem:** `new \\w+Service\\(` war zu grob, Application Services sind legitim.\n\n**Lösung:** Nur Infrastructure-Services blockieren:\n\n```python\n# Gestrichen: new \\w+Service\\(\n# Neu: new Infrastructure\\\\\n```\n\n### 4. Unscharfe Regeln gestrichen\n\n| Gestrichen | Grund |\n|------------|-------|\n| Duplizierte Methodensignaturen | Ohne AST nicht prüfbar |\n| Business Logic Pattern | Nicht formal definierbar |\n| new Service (generisch) | Zu grob |\n\n### 5. Allowlist definiert\n\n```python\nALLOWED_PATHS = [\n    \"\/Factory\/\",      # Factory darf new verwenden\n    \"\/Bootstrap\/\",    # Bootstrap darf new verwenden\n    \"\/tests\/\",        # Tests dürfen alles\n    \"\/Test\/\",         # PHPUnit Tests\n    \"\/vendor\/\",       # Third-party Code\n]\n```\n\n### 6. Rollback-Entscheidung\n\n**Supervision-Vorgabe:** Kein Rollback. Blockiere vorher oder warne nachher.\n\n**Umsetzung:** Pre-Hook blockiert mit `{\"allowed\": false}`, kein implizites Zurückdrehen.\n\n### 7. Statisch vs. Dynamisch\n\n**Supervision-Vorgabe:** Phase 1 niemals dynamisch.\n\n**Umsetzung:** Regeln in Python hardcoded, kein YAML-Parsing zur Laufzeit.\n\n---\n\n## Implementierte Regeln\n\n### BLOCK (Pre-Hook, nicht verhandelbar)\n\n| ID | Regel | Pattern | Scope |\n|----|-------|---------|-------|\n| H1 | strict_types erforderlich | `declare(strict_types=1)` muss vorhanden sein | Alle PHP-Dateien |\n| H2 | Domain ohne Infrastructure | `use Infrastructure\\` verboten | `\/Domain\/` |\n| H3 | DatabaseFactory nur in Factory | `DatabaseFactory::` verboten | Außerhalb `\/Factory\/` |\n| H4 | Kein new Repository in Controller | `new \\w+Repository(` verboten | `\/Controller\/` |\n| H5 | Kein new Infrastructure in Controller | `new Infrastructure\\` verboten | `\/Controller\/` |\n\n### WARN (Post-Hook, Phase 2)\n\n| ID | Regel | Check | Schwellwert |\n|----|-------|-------|-------------|\n| W1 | Klassengröße | Zeilenanzahl | > 300 |\n| W2 | Constructor-Komplexität | Parameter | > 5 |\n| W3 | SQL im Controller | Keywords | SELECT\/INSERT\/UPDATE\/DELETE |\n| W4 | Fehlende PHPDoc | Public Methods | Ohne Doc |\n\n---\n\n## Technische Umsetzung\n\n### Hook-Script\n\n**Datei:** `\/var\/www\/tools\/ki-protokoll\/claude-hook\/architecture_guard.py`\n\n**Trigger:** PreToolUse → Write → *.php\n\n**Verhalten:**\n1. Prüft ob PHP-Datei\n2. Prüft Allowlist\n3. Iteriert über 5 harte Regeln\n4. Bei Violation: `{\"allowed\": false, \"message\": \"...\"}`\n5. Bei OK: `{\"allowed\": true}`\n\n### Hook-Registrierung\n\n**Datei:** `\/root\/.claude\/settings.json`\n\n```json\n{\n  \"hooks\": {\n    \"PreToolUse\": [\n      {\n        \"matcher\": \"Write\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"\/var\/www\/tools\/ki-protokoll\/claude-hook\/architecture_guard.py\",\n            \"timeout\": 5\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n### Contract-Update\n\n**Version:** 1.0 → 1.1\n\n**Änderungen:**\n- `hard_constraints`-Abschnitt hinzugefügt (H1-H5)\n- `warning_indicators`-Abschnitt hinzugefügt (W1-W4)\n- Allowlist dokumentiert\n\n---\n\n## Testergebnisse\n\nAlle 5 Regeln wurden mit absichtlichen Verstößen getestet:\n\n```\n=== Test H1: Missing strict_types ===\n{\"allowed\": false, \"message\": \"ARCHITECTURE VIOLATION [H1]: Missing declare(strict_types=1)...\"}\n\n=== Test H1: With strict_types (should pass) ===\n{\"allowed\": true}\n\n=== Test H2: Domain uses Infrastructure ===\n{\"allowed\": false, \"message\": \"ARCHITECTURE VIOLATION [H2]: Domain must not use Infrastructure...\"}\n\n=== Test H3: DatabaseFactory outside Factory ===\n{\"allowed\": false, \"message\": \"ARCHITECTURE VIOLATION [H3]: DatabaseFactory only allowed in Factory...\"}\n\n=== Test H3: DatabaseFactory in Factory (should pass) ===\n{\"allowed\": true}\n\n=== Test H4: new Repository in Controller ===\n{\"allowed\": false, \"message\": \"ARCHITECTURE VIOLATION [H4]: new Repository in Controller not allowed...\"}\n\n=== Test H5: new Infrastructure in Controller ===\n{\"allowed\": false, \"message\": \"ARCHITECTURE VIOLATION [H5]: new Infrastructure in Controller not allowed...\"}\n\n=== Test Allowlist: Test path (should pass) ===\n{\"allowed\": true}\n```\n\n---\n\n## Status der Implementierung\n\n| Schritt | Status |\n|---------|--------|\n| Supervision-Review | ✓ Abgeschlossen |\n| Regelmatrix bereinigt | ✓ 5 Block + 4 Warn |\n| Contract v1.1 | ✓ Aktiv |\n| architecture_guard.py | ✓ Implementiert |\n| Tests | ✓ Alle bestanden |\n| Hook registriert | ✓ In settings.json |\n| Beobachtungsphase | ○ Läuft (1 Woche) |\n| Post-Hook (Warnungen) | ○ Phase 2 |\n\n---\n\n## Nächste Schritte\n\n1. **Beobachtungsphase (1 Woche)**\n   - False Positives identifizieren\n   - Allowlist bei Bedarf erweitern\n   - Violation-Häufigkeit monitoren\n\n2. **Phase 2: Post-Hook**\n   - `architecture_validator.py` implementieren\n   - Warnungen für W1-W4\n   - Kein Block, nur Info\n\n3. **Dokumentation**\n   - Integration in `\/docs\/prozesse\/`\n   - Entwickler-Anleitung\n\n---\n\n## Dateien\n\n| Datei | Zweck |\n|-------|-------|\n| `\/var\/www\/tools\/ki-protokoll\/claude-hook\/architecture_guard.py` | Pre-Hook (Blocking) |\n| `\/root\/.claude\/settings.json` | Hook-Konfiguration |\n| `\/var\/www\/dev.campus.systemische-tools.de\/docs\/plan-architecture-gate-enforcement.md` | Plan-Dokument |\n| Contract ID 11 (ki_protokoll.contracts) | architecture-gate-contract v1.1 |\n\n---\n\n## Fazit\n\nDer Architecture Gate ist jetzt ein **echtes Code Gate**, nicht nur Dokumentation. Jede neue PHP-Datei muss die 5 harten Regeln passieren. Die Supervision-Korrekturen wurden vollständig umgesetzt:\n\n- Klare Trennung Block vs. Warn\n- Deterministische Pfad-basierte Erkennung\n- Explizite Allowlist\n- Keine unscharfen Heuristiken\n- Statische Regeln (kein Runtime-YAML)\n",
        "structuredPatch": [],
        "originalFile": null
    }
}