werkrevisor/docs/konzept-jev-classifier.md

# Konzept: Classifier Jev und LLM-Review kombinieren

Stand: 2026-10-05, Entwurf aus der Diskussion nach dem Versuch auf git.javagil.de.

## Stand der Umsetzung

Stufe 1 ist in werkrevisor 0.5.0 umgesetzt: Jev bewertet die Abschnitte und Gherkin-Szenarien der PR-Dokumente.

- `[engine] mode` wählt `llm` (wie bisher, Standard), `classifier` oder `combined`.
- Jede Frage fragt nach einem Problem; ein hoher Wert bedeutet immer „schlecht“.
  Ein Score läuft von „kein Problem“ bis „schlimmstes Problem“; sein Wert ist die erwartete Stufe geteilt durch die höchste Stufe.
  Eine Auswahl nennt ihre schlechten Optionen in `problem_options`; ihr Wert ist deren Wahrscheinlichkeit.
- Statt `max_state_tokens` begrenzt `max_state_chars` die Einheit; eine zu große Einheit geht nicht an Jev und ergibt YELLOW.
  `max_units` begrenzt die Zahl der Aufrufe je Review.
- Ein Ja/Nein hat keine Konfidenz; `min_confidence` gilt nur für Auswahl und Score.
- Im Modus `combined` bekommt das LLM die markierten Einheiten als Liste nach den vollständigen Dateien im User-Prompt:
  Datei, Zeile, Szenario-Nummer, Frage und Wert, aber kein Text aus dem PR.
- `tools/jev-eval` misst die Fragen offline an vorhandenen PR-Dokumenten, ohne Gitea.
- Ab werkrevisor 0.6.0 ergibt ein Wert über `red_above` ORANGE statt RED, auch bei den Spezifikationsfragen.
  Ein Classifier kann irren; deshalb sperrt er nie hart, sondern ein Entwickler prüft den Befund und gibt mit seinem Approval frei.
  RED kommt nur noch aus festen Regeln; der Name `red_above` bleibt, damit bestehende Konfigurationen gültig bleiben.

Ab werkrevisor 0.9.0 fragt keine Beispiel-Konfiguration Jev mehr nach den Schreibregeln.
Bei der Messung mit `tools/jev-eval` lag die Frage `writing_rules_violated` für alle 34 Abschnitte über `red_above`,
sie trennte also gute nicht von schlechten Abschnitten.
Die zählbaren Regeln (ein Satz je Zeile, Zeilenlänge, Sätze je Absatz) prüft nun `[writing]` deterministisch;
die übrigen Stilregeln bleiben beim LLM.
`tools/jev-eval` nutzt ab 0.9.0 dieselben Konfigurationsebenen wie der Review, mit `--repo-config` für `.werkrevisor.toml`.

Die Fragen und Schwellwerte in `config/hsadmin-ng.toml` sind mit `tools/jev-eval` an der Historie von hsadmin-ng geprüft.
Die Messung lief je Dokument über die 69 PR-Dokumente von 2026: 281 Einheiten, 682 Antworten, Kosten 0,023 USD.
74 Antworten waren YELLOW, keine erreichte `red_above`.
58 davon waren nur wegen niedriger Konfidenz YELLOW (`min_confidence = 0.3`), meist bei kurzen Abschnitten wie „Release Note“.
Die 16 Antworten über `yellow_above` verteilten sich auf 8 der 69 Dokumente; Stichproben bestätigten sie.
Ab werkrevisor 0.12.0 zählt deshalb eine Antwort unter `min_confidence` nicht mehr für das Ergebnis;
im Modus `combined` bekommt das LLM sie als unsicheren Hinweis.
Die Schwellwerte bleiben unverändert.

Von Stufe 2 (Risiko je Datei) ist der deterministische Teil in werkrevisor 0.13.0 umgesetzt, siehe `[mechanical]` im README:
Dateien, deren geänderte Zeilen nur Imports, Leerraum oder eine Umbenennung sind, gehen nicht an das LLM.
Der Jev-Filter für die übrigen Dateien bleibt offen, ebenso Stufe 3 (Build-Laufzeit).

## Ausgangslage

Der heutige Review ist ein einzelner LLM-Aufruf über PR-Agent und OpenRouter.
Er liefert Befunde mit Problem, Auswirkung und Fundstelle, ist aber für jede Einzelfrage teuer und langsam.

Jev von TypeSafe ist ein „System One“-Modell, also ein Classifier.
Jev erzeugt keinen Text, sondern beantwortet getypte Fragen mit kalibrierten Wahrscheinlichkeiten:

- Fragetypen: Ja/Nein (`noul`), Auswahl (`choice`, bis 255 Optionen), Score (`score`, 2–10 Stufen);
- Eingabe („state“) bis etwa 32.000 Tokens, state und Fragen zusammen bis etwa 64.000 Tokens;
- Antwortzeit etwa 100 ms;
- Preis 0,042 USD pro 1 Mio. Input-Tokens, Output kostenlos;
- keine Begründung, keine Fundstelle, kein verlässliches Rechnen oder Vergleichen von Zahlen.

Quelle: [flaviocopes.com/jev](https://flaviocopes.com/jev/), [LiteLLM-Doku](https://docs.litellm.ai/docs/pass_through/typesafe).

## Anbindung

Jev ist über OpenRouter nicht als Classifier verfügbar.
Dort gibt es nur `typesafe/jev-router`; der wählt für Chat-Anfragen ein passendes LLM aus.
litellm und damit PR-Agent kennen Jev nur als Pass-Through im Proxy-Betrieb.

werkrevisor spricht Jev deshalb direkt an: `POST https://api.typesafe.ai/v1/systemone` mit `model: "jev-latest"`.
Dazu kommt ein kleiner Client nur mit der Standardbibliothek, mit denselben Regeln wie der Gitea-Client (TLS, keine Weiterleitungen).
Neues Secret auf dem Host: `TYPESAFE_API_KEY` in `werkdock.env` bzw. `docker.env`.
Werkator und die Gitea-Seite bleiben unverändert.

Offen: TypeSafe hat neue Registrierungen pausiert; alternativ ist Jev über das Vercel AI Gateway erreichbar.

## Ablauf in vier Stufen

### 1. Aufbereiten

Ohne Modell und deterministisch wird der PR in Einheiten zerlegt:

- je geänderte Datei: Diff plus vollständige neue Fassung;
  passt sie nicht in das Limit von Jev, nur ein Ausschnitt um die Änderungen, und die Einheit gilt als unvollständig;
- das PR-Dokument nach Abschnitten (Markdown-Überschriften);
- jedes Gherkin-Szenario einzeln.

Ein LLM zum Aufbereiten ist vorerst nicht nötig, höchstens für Zusammenfassungen sehr großer Dateien.

### 2. Viele Jev-Aufrufe parallel

| Einheit                    | Fragen                                                                                         |
| -------------------------- | ---------------------------------------------------------------------------------------------- |
| je Datei                   | Risiko (Score 1–5); ändert sich Verhalten (Ja/Nein); werden Tests abgeschwächt (Ja/Nein); sicherheitsrelevant (Ja/Nein) |
| je Abschnitt des PR-Dokuments | verständlich für Menschen (Score); Slop-Faktor: Füllwörter, gestelzte Prosa, Erzählung statt Begründung (Score) |
| je Gherkin-Szenario        | gut lesbar (Score); genau ein Aspekt (Ja/Nein); frei von Implementierungsdetails (Ja/Nein); Given/When/Then sauber (Ja/Nein) |

Die zählbaren Schreibregeln aus `AGENTS.md` prüft werkrevisor ohne Jev, siehe oben.
Die Fragen, Optionen und Schwellwerte stehen in der Betreiber-Konfiguration, nie im PR.

#### Risiko je Änderung auf Dateiebene

Das Risiko hängt an der Art der Änderung, nicht an ihrer Größe.
Jev ordnet jede geänderte Datei einer Änderungsklasse zu (`choice`), mit Wahrscheinlichkeit und Konfidenz:

| Änderungsklasse                                                               | Risiko                 |
| ----------------------------------------------------------------------------- | ---------------------- |
| nur Imports oder Paketnamen geändert, z. B. weil eine Klasse verschoben wurde | gering                 |
| Datei umbenannt oder verschoben, Inhalt unverändert                           | gering                 |
| neue Testmethoden oder neue Assertions                                        | gering                 |
| Assertions oder Testmethoden gelöscht oder abgeschwächt, Tests deaktiviert    | hoch                   |
| Verhalten im Produktivcode geändert                                           | je nach Inhalt (Score) |

Ein Paket-Umzug, der Imports in 200 Dateien ändert, ist damit fast risikofrei:
Ein falscher Import fällt bei der guten Testabdeckung in der verpflichtenden CI auf.
Die geringe Einstufung gilt deshalb nur zusammen mit einer grünen CI.

Mechanische Änderungen lassen sich oft auch deterministisch erkennen, z. B. wenn ein Datei-Diff nur `import`- und `package`-Zeilen enthält.
Diese Erkennung ist sicher und kostet nichts; Jev entscheidet nur die Fälle, die sie nicht eindeutig zuordnet.
Die deterministische Erkennung gibt es ab werkrevisor 0.13.0 (`[mechanical]`);
ob Jev die übrigen Fälle verlässlich einordnet, ist vor einer Umsetzung an echten PRs zu messen.
Als mechanisch erkannte Dateien gehen nicht in den LLM-Review und belasten dessen Token-Budget nicht.
So wird ein großer, aber mechanischer PR nicht mehr allein wegen seiner Größe ORANGE oder YELLOW.

### 3. Zusammenführen

- Ein schlecht lesbares Gherkin-Szenario oder ein PR-Dokument mit hohem Slop-Faktor ergibt früh ORANGE, bevor ein Mensch Zeit investiert.
  Für hsadmin-ng ist das besonders wichtig, weil die Gherkin-Szenarien dort eine von Menschen freigegebene Spezifikation sind.
  RED wäre zu hart: Der Administrator auf dev.hostsharing.net ist Betreiber, kein Entwickler, und hebt ein falsches RED nicht auf.
- Hohe Risiko-Scores oder unvollständige Einheiten ergeben YELLOW.
  Unsichere Antworten (niedrige Konfidenz) zählen ab 0.12.0 nicht für das Ergebnis.
- Sind alle Einheiten unauffällig, ist der PR ein Kandidat für GREEN.
- Die festen Regeln (Kategorien, riskante Pfade, Secret-Scan, offene Fragen im PR-Dokument) gelten unverändert und gehen vor.

### 4. Gezielter LLM-Review

Das LLM bekommt die Jev-Ergebnisse als Hinweise, z. B. „Datei X Risiko 4, Szenario 3 nicht lesbar“.
Es prüft vor allem die markierten Stellen und schreibt die Befunde mit Problem, Auswirkung und Fundstelle.
Ein klar schlechter Wert aus Jev ergibt auch ohne Befund des LLM ORANGE, ebenso bei Spezifikationsfragen (Gherkin, PR-Dokument).
Ein Entwickler prüft den Befund; sein Approval gibt den PR frei.

Der Kommentar zeigt zusätzlich eine kleine Tabelle mit den Jev-Werten je Datei, Abschnitt und Szenario.

## Konfiguration

```toml
[engine]
# "llm" ist der heutige Review, "classifier" nur Jev, "combined" die vier Stufen.
mode = "combined"

[classifier]
endpoint = "https://api.typesafe.ai/v1/systemone"
model = "jev-latest"
input_price_usd_per_mtok = 0.042
max_state_chars = 60000
max_units = 80
timeout_seconds = 20
pr_doc_globs = ["doc/PR/*.md"]
min_confidence = 0.3
# Dazu die Fragen in [[classifier.scenario_questions]] und [[classifier.section_questions]], siehe config/hsadmin-ng.toml.
```

Gewechselt wird wie bisher über `WERKREVISOR_CONFIG_TOML` auf dem Host, ohne neues Image.

## Build-Laufzeit als Kriterium

Ein PR, der nur Tests hinzufügt, ist an sich risikofrei; er kann aber die Build-Laufzeit stark erhöhen.
Das gehört nicht zu Jev, weil Jev Zahlen schlecht vergleicht; es wird deterministisch geprüft.

- Werkator kennt die Build-Dauer je Definition mit Median (`BuildDurationTrends`).
- Den Test-Anteil getrennt vom PIT-Anteil liefert der `--profile`-Bericht von hsadmin-ng;
  ein unzureichender PIT-Cache darf nicht als langsamer Test zählen.
- Dafür muss der Review das Ende der CI des gleichen Heads abwarten und die Zahlen von Werkator bekommen.
  Das ist eine eigene, spätere Ausbaustufe mit einer Werkator-Erweiterung.

## Vorbehalte

- Wie gut Jev Code-Risiko, Slop und Lesbarkeit bewertet, ist unbekannt.
  Vor dem Einsatz wird Jev offline an der Historie von hsadmin-ng gemessen: bekannte gute und schlechte Szenarien und PR-Dokumente.
- Ohne Enterprise-Vertrag garantiert TypeSafe keine Löschung der Anfragen, trainiert aber nicht darauf.
  Für öffentlich gespiegelten Code ist das vermutlich unkritisch; die Entscheidung trifft der Betreiber.

## Reihenfolge

1. Jev für Gherkin-Szenarien und PR-Dokument: größter Nutzen, ORANGE vor dem menschlichen Review.
2. Risiko je Datei als Vorfilter und Hinweisgeber für den LLM-Review;
   der deterministische Teil ist umgesetzt, der Jev-Teil folgt nach einer Messung.
3. Build-Laufzeit über Werkator.

Voraussetzung für 1 und 2 ist ein Jev-Zugang.