Deploymentcenter/docs/SUPERVISOR_INTEGRATION_GUIDE.md

# Supervisor — Befunde und Rückbau

Der Supervisor sieht nach, ob etwas ungewöhnlich ist, und legt Befunde ab.

Er beantwortet die Frage **„ist das ungewöhnlich?"** — nicht „ist das
schlimm?". Die zweite Frage beantwortet ein Mensch oder ein Agent bei der
Sichtung, mit Verlauf, Flotte und Quelltext vor Augen.

Gültiger Stand aller Vorhaben: **[ROADMAP.md](ROADMAP.md)**<br>
Ausführliche Begründung (archiviert): [archiv/SUPERVISOR_MCP_DESIGN.md](archiv/SUPERVISOR_MCP_DESIGN.md)

---

## Wichtig: es gibt nichts einzubauen

> **Ein Supervisor im ausgelieferten Programm ist verworfen.** Er hätte in
> jeder Anwendung Einbau, Rückbau, eigenen Zustand auf Kundenhardware, ein
> weiteres Token im Binary und eine zweite Fassungspflege gebraucht — und dabei
> überwiegend gemeldet, was Error-Reporting und Bugtracker ohnehin abdecken.
>
> **Für Anwendungen ändert sich damit nichts.** Wer Fehler an den Bugtracker
> meldet, ist fertig. Die Detektoren laufen im Deploymentcenter auf den Daten,
> die dadurch ohnehin hereinkommen.

Diese Anleitung beschreibt deshalb zweierlei: **was der Supervisor findet und
wie man es ansieht** — und **wie begonnene Vorbereitungen zurückgebaut werden.**

---

## Woher Befunde kommen

**Serverseitig, von selbst.** Fünf Detektoren laufen im minütlichen Tick
(gedrosselt auf zehn Minuten) und brauchen keine Änderung an irgendeiner
Anwendung:

| Detektor | Findet |
|---|---|
| `novel.error_signature` | Fehlersignatur, die es in dieser Fassung noch nie gab |
| `silence.heartbeat` | Instanz meldet sich nicht mehr |
| `deviation.self` | Abweichung vom eigenen Verlauf der letzten Tage |
| `deviation.fleet` | Ausreißer gegenüber anderen Installationen derselben Fassung |
| `regression.build` | Kennzahl verschiebt sich nach einem Update |

Keiner davon muss den gesuchten Fehler vorher kennen. Der Maßstab kommt nicht
aus einem Kopf, sondern aus dem eigenen Verlauf, aus der Vorversion oder aus
den anderen Installationen — deshalb finden sie Dinge, an die niemand gedacht
hat.

**Von außen eingeliefert**, über `POST /api/supervisor/v1/observe` mit dem
Scope `supervisor:report`. Heute nutzen das Prüfwerkzeuge und Testläufe. Der
[Katalog](../src/Modules/Supervisor/Catalog.php) legt die Namen fest, unter
denen gemeldet wird — abrufbar über `GET /api/supervisor/v1/catalog`.

Dass die Namen stabil sind, ist der ganze Zweck: Befunde aus verschiedenen
Projekten müssen vergleichbar bleiben. Ein umbenannter Detektor zerreißt jede
Auswertung, die über den Zeitpunkt der Umbenennung hinausgeht.

---

## Befunde ansehen

Über MCP in Claude Code:

```
dc_finding_summary                      → Zählung je Detektor
dc_findings detector: "deviation"       → die Einzelbefunde
dc_metrics source: "app-01" metric: …   → der Verlauf dahinter
```

Ohne MCP:

```
GET /api/supervisor/v1/summary
GET /api/supervisor/v1/findings?detector=deviation&status=active
GET /api/supervisor/v1/catalog
```

Befunde tragen ihre Umgebung. Was außerhalb von `production` auffällt, ist eine
Stufe niedriger eingestuft — nicht weil es unwichtig wäre, sondern weil auf
Testmaschinen systematisch mehr Rauschen entsteht.

**Ob ein Befund aus einem Testlauf ein Artefakt des Prüfstands ist oder auch
beim Kunden aufträte, ist die schwierige Frage.** Sie ist offen; die Ansätze
stehen in der [Roadmap unter G8](ROADMAP.md). Der brauchbarste Gedanke daraus:
Fehlende Zugangsdaten sind ein Artefakt — *wie die Software darauf reagiert*,
ist keines. Ein Wiederholungssturm, ausgelöst durch fehlende Zugangsdaten, ist
ein echter Befund, denn auch beim Kunden laufen Zugangsdaten ab.

---

## Vorbereitungen in den Projekten zurückbauen

In mehreren Projekten wurde bereits von Hand etwas in Richtung Supervisor
begonnen — UI-Steuerelemente, teilweise ein lokaler KI-Agent. Das fällt
**ersatzlos** weg; es tritt nichts an seine Stelle.

### Erkennen

```bash
grep -rniE "supervisor|healthcheck|selfcheck|anomal" --include=*.cs --include=*.php .
```

Typisch: eine eigene Timer-Schleife, ein Verzeichnis mit Zählern, ein eigener
`HttpClient`-Aufruf gegen das Deploymentcenter, eine JSON-Datei mit Zustand,
eine Klasse namens `HealthCheck` oder ähnlich.

### Was verschwindet

- **Lokal laufender KI-Agent** samt API-Schlüssel. Der Schlüssel läge auf
  Kundenhardware, der Kontext im Speicher fremder Maschinen.
- **UI-Listen, -Tabellen und -Schaltflächen für Befunde.** Es gibt lokal keine
  Befundhistorie anzuzeigen, und Abhaken wäre `supervisor:manage` — ein Recht,
  das kein Laufzeit-Token trägt.
- **Eigene Warteschlangen** für nicht zugestellte Meldungen. Eine wachsende
  Warteschlange in einer ohnehin auffälligen Anwendung ist genau der Schaden,
  den man vermeiden wollte.
- **Eigene Alarmierung** je Auffälligkeit. Wer bei jeder Kleinigkeit alarmiert,
  hat nach einer Woche einen Kanal, den niemand mehr liest.
- **Feste Schwellwerte je Kennzahl.** Die tragenden Detektoren vergleichen
  gegen eigenen Verlauf, Vorversion oder Flotte. Ein Schwellwert findet nur,
  woran vorher jemand gedacht hat.
- **Timer-Schleifen, Zustandsdateien, eigene POSTs** an das Deploymentcenter.

Was bleiben darf, wenn es schon gebaut ist: eine **einzelne Statuszeile** im
Administrationsbereich — meldet die Anwendung Fehler, wann zuletzt. Das ist die
einzige lokal beantwortbare Frage.

### Was übrig bleibt und wertvoll ist

Wo in der Vorbereitung schon überlegt wurde, **worauf** zu achten wäre, ist
diese Überlegung das Wertvollste am ganzen Bestand. Sie wandert nicht ins
Nichts, sondern:

| Überlegung | Neuer Ort |
|---|---|
| „Hier darf nie ein negativer Saldo entstehen" | Prüfung im Testlauf |
| „Dieser `catch` verschluckt etwas Wichtiges" | Fehlermeldung an den Bugtracker, statt zu schlucken |
| „Diese Warteschlange kann volllaufen" | Kennzahl im Heartbeat — `deviation.self` sieht den Rest |
| „Dieser Job stirbt manchmal still" | Heartbeat-Monitor — `silence.heartbeat` sieht den Rest |

Die letzten beiden sind der Punkt: Was als Kennzahl im Heartbeat landet, wird
serverseitig ohnehin überwacht. Dafür braucht es keinen Beobachter im Programm,
nur einen Wert mehr im Ping.

### Auftrag für den Agenten im Projektverzeichnis

Zum Einfügen in eine frische Sitzung im jeweiligen Projekt:

```text
In diesem Projekt wurde eine Supervisor-Vorbereitung begonnen. Sie wird
ersatzlos zurückgebaut — ein Supervisor im ausgelieferten Programm ist
verworfen. Es tritt nichts an seine Stelle.

1. Bestandsaufnahme. Suche:
   grep -rniE "supervisor|healthcheck|selfcheck|anomal" .
   Berichte, was du findest, bevor du etwas änderst.

2. Ersatzlos entfernen:
   - lokal laufender KI-Agent samt API-Schlüssel
   - UI-Listen, -Tabellen und -Schaltflächen für Befunde
   - eigene Warteschlangen, eigene Alarmierung, feste Schwellwerte
   - eigener POST ans Deploymentcenter, eigene Zustandsdatei
   - eigene Timer-/Hintergrundschleife
   Behalten: höchstens eine Statuszeile im Administrationsbereich.

3. Die Überlegungen retten. Wo jemand notiert hat, WORAUF zu achten wäre,
   überführe das:
   - fachliche Zusicherung  -> Prüfung im Testlauf
   - verschluckter Fehler   -> Fehlermeldung an den Bugtracker statt Schlucken
   - Wert, der volllaufen kann -> Kennzahl im Heartbeat

4. Sicherstellen, dass Fehler gemeldet werden: globaler Exception-Handler an
   POST /api/errors/v1/report, mit build_version. Ohne diese Angabe kann der
   Tracker eine Regression nicht von einem veralteten Prüfstand unterscheiden.

5. Fassung festhalten: dc_link_project mit to_slug "deploymentcenter",
   integrated_version "2.6.1". Ohne MCP: POST /api/bugtracker/v1/projects.

Fällt dir dabei ein Fehler im Deploymentcenter selbst auf, melde ihn mit
dc_report gegen project_slug "deploymentcenter" samt evidence.
```

Schritt 4 ist der wichtigste. Er ersetzt den ganzen verworfenen Beobachter:
Kommen Fehler mit Fassungsangabe herein, arbeiten die serverseitigen Detektoren
darauf — ohne eine Zeile Beobachtercode in der Anwendung.