werkrevisor/docs/anleitung-dev.hostsharing.net.md

# Anleitung: KI-Review für hsadmin-ng auf dev.hostsharing.net

Stand: 2026-10-07, werkrevisor 0.21.1,
nach dem Versuch auf git.javagil.de (siehe [betrieb-git.javagil.de.md](betrieb-git.javagil.de.md)).
Diese Anleitung ist noch nicht ausgeführt; von der Erprobung in Schritt 6 liefen schon die Dry runs, siehe dort.
Was vor Ort zu prüfen ist, steht als „prüfen“ dabei.
Die Anleitung setzt Werkator auf vm4006 voraus: Build-Definition, Neustart des Review-Builds und Status-Namen.
Läuft dort noch die GitTally-Implementierung, kommt zuerst der Wechsel auf Werkator.

## Ziel

Die Repositories `hostsharing/hs.hsadmin.ng` und das Frontend-Repository (Name prüfen) bekommen denselben KI-Review wie `mi/werkprobe`.
Unterschiede zum Versuch:

- Ein Frontier-Modell und höchstens 1 USD pro Review, weil es nur 2–3 PRs pro Tag gibt.
- Werkator läuft auf vm4006 mit rootless Docker statt Werkdock.
- Eigene Regeln für automatisch freigebbare Änderungen; Migrationen und RBAC bleiben YELLOW, bis das Team anders entscheidet.

## Zusammenspiel

So arbeiten die Systeme zusammen:

```mermaid
flowchart LR
    dev["Entwickler"] -- "push, PR ohne WIP" --> gitea
    human["Mensch, z. B. mi"] -- "Approval bei YELLOW oder ORANGE" --> gitea
    subgraph gitea["Gitea"]
        pr["Pull Request"]
        bp{"Branch Protection"}
    end
    subgraph host["vm4006"]
        werkator["Werkator"]
        subgraph sandbox["Docker-Container, frisches Home"]
            werkrevisor["werkrevisor"] --> pragent["PR-Agent"]
        end
        mcfg[("Maschinen-Konfiguration:<br/>Build ai-review, Secrets,<br/>WERKREVISOR_CONFIG_TOML")]
    end
    subgraph internet["Dienste im Internet"]
        openrouter["OpenRouter"] --> llm["Sprachmodelle"]
        typesafe["TypeSafe: Jev"]
    end

    werkator -- "pollt neue Heads und offene PRs" --> pr
    mcfg -. "Befehl, Umgebung" .-> werkator
    werkator -- "CI-Build" --> ci["normaler Build"]
    werkator -- "PR-Target-Build" --> werkrevisor
    werkrevisor -- "liest PR, Diff, Dateien" --> pr
    pragent -- "Review-Prompt" --> openrouter
    werkrevisor -- "Auswahl von Ausschnitten" --> openrouter
    werkrevisor -- "Fragen zu Dateien, PR-Dokument,<br/>Findings und Kategorien" --> typesafe
    werkrevisor -- "Ergebniskommentar, Zeilenkommentare, Approval,<br/>Review-Anfrage, ai-review/assessment" --> pr
    werkator -- "Status werkator und ai-review/gate" --> pr
    pr --> bp
    bp -- "Merge erlaubt oder gesperrt" --> dev
```

## Voraussetzungen

| Was                     | Soll                                       | prüfen                                                             |
| ----------------------- | ------------------------------------------ | ------------------------------------------------------------------ |
| Gitea                   | 1.27.3                                     | erledigt: `GET https://dev.hostsharing.net/api/v1/version`          |
| Werkator auf vm4006     | mindestens 1.36.0                          | Fußzeile der Oberfläche; prüfen, ob dort Werkator oder noch die GitTally-Implementierung läuft |
| Docker auf vm4006       | rootless, für den Werkator-Benutzer        | `docker info` als dieser Benutzer                                  |
| Gitea-Administrator     | darf Konten anlegen                        | Menü „Site Administration“                                         |
| Werkator-Gitea-Token    | in `.git/werkator/.werkator.yml` (`git.token`) | nötig, damit Werkator offene PRs liest                          |

## 1. Bot-Konto

1. In dev.hostsharing.net als Administrator das Konto `ai-reviewer` anlegen:
   - lokal;
   - Passwort im Passwort-Manager;
   - „Max. Anzahl an Repositorys“ `0`;
   - nicht Administrator, keine Organisationen.
2. In beiden Repositories `ai-reviewer` mit Recht „Schreiben“ eintragen.
   Bei Organisations-Repositories geht das als Mitarbeiter oder über ein eigenes Team nur für diese beiden Repositories.
   Ohne Schreibrecht zählt das Approval des Bots nicht als offiziell.
3. Als `ai-reviewer` den Token `pr-agent-bot` erzeugen:
   - repository: Lesen und Schreiben;
   - issue: Lesen und Schreiben;
   - user: Lesen.
   Ohne „user: Lesen“ kann werkrevisor seine eigenen Kommentare nicht erkennen.

## 2. OpenRouter-Key

Einen eigenen Key für Hostsharing anlegen, damit die Kosten getrennt bleiben, z. B. `hostsharing-review`.
Vorschlag für das Limit: 60 USD, monatlich zurückgesetzt; das reicht für etwa 60–90 Reviews bis 1 USD.

Für den Classifier Jev kommt ein TypeSafe-Key hinzu, als `TYPESAFE_API_KEY` neben `OPENROUTER_API_KEY`.
`config/hsadmin-ng.toml` nutzt `[engine] mode = "combined"` und `[db_schema] judge = "jev"`, braucht ihn also.
Jev kostet je Review weniger als 0,001 USD.

## 3. Modell und Betreiber-Konfiguration

Die Konfiguration steht in werkrevisor unter `config/hsadmin-ng.toml` und kommt ins Image; ein PR kann sie nicht ändern.

Ab werkrevisor 0.8.0 kann hsadmin-ng eine eigene Datei `.werkrevisor.toml` im Wurzelverzeichnis bekommen.
Sie liegt über der Host-Konfiguration und gewinnt je Schlüssel.

werkrevisor liest sie ab 0.21.0 über die Gitea-API am Head des Default-Branchs, also `master`, nie aus dem PR selbst;
so ändert auch ein gestapelter PR nicht die Regeln seines eigenen Reviews.
Dorthin gehören Größe, Kategorien, PR-Dokumente, Review-Anweisungen und die Fragen an Jev.
Ab 0.21.0 ersetzt sie die harten Pfade, die von Jev bewerteten Pfade und die DB-Schema-Pfade der Host-Konfiguration;
hart bleiben sollten nur die wenigen Pfade, die das Review oder die agentische Entwicklung selbst steuern.

Modell, Preise, Budget, Gate und Engine bleiben in der Host-Konfiguration;
setzt die Datei einen dieser Schlüssel, endet der Review mit ERROR.
Eine Änderung an `.werkrevisor.toml` braucht immer ein menschliches Approval und wirkt erst nach dem Merge.
Bis dahin bleibt `config/hsadmin-ng.toml` vollständig.

Vor der Aktivierung festzulegen:

- **Modell:** Kandidaten mit Preisen vom 2026-10-05 in USD pro 1 Mio. Tokens (Input / Output):
  - `anthropic/claude-sonnet-5.5`: 2 / 10;
  - `openai/gpt-6-astra`: 10 / 50.
  Auswahl nach einem Offline-Vergleich (Schritt 6), nicht nach Gefühl.
- **Preise und Grenzen:**
  - Die Preise des gewählten Modells gehören in `[model]`.
  - `max_context_tokens = 150000` begrenzt die Eingabe, weil lange Prompts den Review auch innerhalb des Kontextfensters verschlechtern.
  - werkrevisor leitet aus `max_usd_per_review` und `max_output_tokens` eine zweite Grenze ab:
    die größte Eingabe, für die `2 × (Input × Preis + Output × Preis)` höchstens 1 USD ergibt, hier 200.000 Tokens.
    Es gilt die kleinere der beiden Grenzen; ein PR darüber bekommt keinen KI-Review und wird YELLOW.
- **Größe:** `[size] max_changed_lines = 1000` und `max_files = 40`; Dateien der Kategorie `docs` zählen nicht.
  Ein größerer PR wird YELLOW: Ein Entwickler gibt ihn bewusst frei, das Modell prüft ihn trotzdem.
  1000 Zeilen trifft etwa jeden vierten hsadmin-ng-PR und liegt knapp unter der harten Grenze von `tools/pr-quick-check`.
- **Kategorien:** `docs` = `doc/**`, `**/*.md`; `tests` = `src/test/**`; `main` = `src/main/**`; `api_spec` = `src/main/resources/api-definition/**`.
  Ab werkrevisor 0.10.0 ist auch Hauptcode mit nur hinzugefügten Tests automatisch freigebbar (`feature_with_tests`).
  Ein verlorener oder abgeschalteter Test ergibt YELLOW; andere geänderte Testzeilen prüft das Modell.
  Ab werkrevisor 0.15.0 ist auch `mixed` freigebbar, z. B. Hauptcode mit API-Spezifikation.
  `[categories] harmless` nennt weitere harmlose Dateien, z. B. `.editorconfig`; der Standard ist leer.
- **Harte YELLOW-Regeln, Vorschlag** (Dateien der Kategorie `docs` zählen nie dazu, z. B. `doc/PR/…-rbac-….md`):
  - Liquibase-Changelogs `src/main/resources/db/**`;
    ab werkrevisor 0.10.0 sind DB-Schema-Pfade eingebaut, z. B. `**/*.sql`, `**/db/changelog/**` und `**/migrations/**`;
    keine Konfigurationsebene kann sie entfernen;
    ab werkrevisor 0.16.0 bewertet Jev mit `[db_schema] judge = "jev"` jedes geänderte Changeset,
    und nur ein riskantes ergibt YELLOW;
  - RBAC und Security (`**/rbac/**`, `**/*Security*`, `**/*ApiKey*`);
  - Build und Abhängigkeiten (`build.gradle.kts`, `buildSrc/**`, `gradle/**`);
  - CI und Deployment (`.werkator*`, `tools/remote`, `Dockerfile*`);
  - Profile (`src/main/resources/application*.yml`).
  Die endgültige Liste legt das Team fest.
- **Secret-Scan:** `secret_scan_exclude = ["src/test/**"]`, weil Testdaten erfundene Passwörter enthalten;
  private Schlüssel, AWS-Schlüssel und vollständige `hsak_`- und `sk-or-v1-`-Schlüssel zählen auch dort.
- **Offene Fragen:** `[pr_doc] globs = ["doc/PR/*.md"]`;
  ein offener Punkt im Abschnitt „Open Questions“ oder „Offene Fragen“ eines geänderten PR-Dokuments ergibt RED ohne Modellaufruf.
  Erlaubt sind nur Punkte, die mit `[x]` als erledigt markiert sind.
- **Projektwissen:**
  - `repo_context_files = ["AGENTS.md"]` gibt dem Modell die Review-Regeln des Projekts mit.
  - PR-Agent liest die Datei über die Gitea-API aus der Basis des PRs, nie aus dem PR selbst; ein PR kann seine eigenen Review-Regeln also nicht ändern.
- **Gate:** `config/hsadmin-ng.toml` hat `yellow_gate = "block"` und keine `human_reviewers`:
  werkrevisor schreibt nur Kommentare und den Status, gibt aber nie frei;
  GREEN ist dort nur ein grüner Status `ai-review/gate`, ohne Approval und ohne automatischen Merge.
  Für die Aktivierung: `yellow_gate = "approval"`, `human_reviewers` = die drei Entwickler-Konten.
  Ab werkrevisor 0.19.3 gibt RED nur einen Kommentar und einen roten Status, nie „Änderungen angefordert“,
  weil der Bot eine solche Ablehnung nicht zurücknehmen kann und sie jeden späteren Commit sperren würde.
  Ab werkrevisor 0.20.2 zieht ein GREEN-Review, der den Merge einplant, die Review-Anfrage einer früheren YELLOW-Runde zurück.
- **Vollständige Dateien:** Das Modell sieht nach dem Diff auch den vollständigen neuen Inhalt jeder geänderten Datei
  (`full_files = true`).
  Doku erreicht das Modell nur als Diff und zählt nicht gegen die Grenzen.
  `config/hsadmin-ng.toml` erlaubt 100.000 Zeichen je Datei und 300.000 Zeichen insgesamt.
  Ab werkrevisor 0.19.2 bekommt eine größere Datei einen Ausschnitt: jede geänderte Zeile mit 40 Zeilen davor und danach.
  Ab 0.20.0 kann ein Economy-Modell den Ausschnitt wählen (`[excerpt] select = "model"`);
  hsadmin-ng behält den festen Ausschnitt, weil die Auswahl Code an einen weiteren Anbieter schickt.
  Passt der Prompt nicht in die Eingabegrenze, fallen zuerst die vollständigen Dateien und dann die Ausschnitte weg.
- **Build-Dateien:** Ab werkrevisor 0.20.4 sieht das Modell auch `*.gradle`-Dateien wie `settings.gradle`.
  Ab 0.19.0 kann ein Pfad als „von Jev bewertet“ gelten (`[hard_yellow] judged_paths`):
  nur eine riskante Änderung ergibt YELLOW.
  `config/hsadmin-ng.toml` verbietet das dem Repository (`[path_judge] repository_may_enable = false`):
  für hsadmin-ng bleiben alle harten Pfade hart.
- **Bewertung aller Dateien:** Ab werkrevisor 0.21.0 bewertet Jev mit `[path_judge] scope = "all"` jede geänderte Datei:
  eine Änderung, die Sicherheit berührt, ergibt YELLOW, eine, die Prüfungen abschwächt, ORANGE.
  `[engine] model_role` legt fest, ob das Modell dabei entscheidet oder nur berät:
  `"decides"`, der Standard, behält das Modell als Gate, z. B. ein Frontier-Modell wie GPT-6 Astra, das Hostsharing bezahlt;
  `"advises"` macht seine Zweifel zu Hinweisen, dann genügt ein Economy-Modell.
  Auf git.javagil.de wären so 20 von 37 gemergten PRs GREEN geworden, vorher 6.
  `config/hsadmin-ng.toml` bleibt vorerst bei `scope = "judged_paths"` und `"decides"`; das Team entscheidet.
- **Engine:** `config/hsadmin-ng.toml` nutzt `[engine] mode = "combined"`:
  Jev bewertet zuerst die Abschnitte und Gherkin-Szenarien der PR-Dokumente unter `doc/PR/`;
  ein klar schlechtes Szenario ergibt ORANGE, auch ohne Befund des LLM.
  Die Fragen und Schwellwerte in `[classifier]` vorher mit `tools/jev-eval` an den vorhandenen PR-Dokumenten prüfen.

## 4. Image auf vm4006

Auf vm4006 als Werkator-Benutzer:

```bash
git clone https://git.javagil.de/mi/werkrevisor.git && cd werkrevisor
docker pull pragent/pr-agent:0.47.0@sha256:7d98954c29289846a08faf00aaea0f1f1375b1676cd8a2ed303e0af07010af7a
docker build --pull=false -t werkrevisor:$(sed -n 's/^__version__ = "\(.*\)"$/\1/p' werkrevisor/__init__.py) .
```

Jede neue werkrevisor-Version bekommt ein eigenes Tag; die Build-Definition nennt das Tag ausdrücklich.

## 5. Werkator-Build-Definition

Je Repository in der Maschinen-Konfiguration `.git/werkator/.werkator.yml` auf vm4006 (nie in eine eingecheckte Datei):

```yaml
builds:
  ai-review:
    trigger:
      onPullRequestTarget: true
    statusContext: ai-review/gate
    cleanCommand: ""
    buildCommand: python -s -m werkrevisor
    timeout: 15m
    artifactDirs: [build/werkrevisor]
    docker:
      enabled: true
      image: werkrevisor:0.21.1
      env:
        PYTHONNOUSERSITE: "1"
        GITEA_BOT_TOKEN: "…"
        OPENROUTER_API_KEY: "…"
        TYPESAFE_API_KEY: "…"
        # optional, für die Statistik auf werkrevisor.javagil.de; der Token kommt vom Betreiber des Dienstes:
        # WERKREVISOR_STATS_URL: "https://werkrevisor.javagil.de"
        # WERKREVISOR_STATS_TOKEN: "…"
        # Die vollständige Betreiber-Konfiguration, Ausgangspunkt ist config/hsadmin-ng.toml.
        WERKREVISOR_CONFIG_TOML: |
          [model]
          id = "openrouter/anthropic/claude-sonnet-5.5"
          input_price_usd_per_mtok = 2.00
          output_price_usd_per_mtok = 10.00
          max_context_tokens = 150000
          max_output_tokens = 10000
          reasoning_effort = "medium"
          # … alle weiteren Abschnitte aus config/hsadmin-ng.toml …
```

Modell und Reasoning-Stufe wechselt man in `WERKREVISOR_CONFIG_TOML` (`id`, beide Preise, `reasoning_effort`, bei Bedarf `max_context_tokens`); der nächste Review nutzt sie, ein neues Image ist nicht nötig.
Der eingebettete TOML-Text ersetzt die Datei vollständig, deshalb immer die ganze Konfiguration einfügen; fehlt ein Abschnitt, bricht werkrevisor mit ERROR ab.
`python -s` und `PYTHONNOUSERSITE=1` verhindern, dass Python Code aus dem Home-Verzeichnis lädt; ohne sie bricht werkrevisor mit Exit 30 ab.

Die Datei muss die Rechte `600` haben.
Zuerst eine Sicherung der bisherigen Datei anlegen.
Das Timeout muss über `timeout_seconds × (max_retries + 1) + 120` Sekunden liegen.

## 6. Erprobung vor der Aktivierung

1. **Nur Regeln, kostenlos:** `tools/dry-run <PR-URL> config/hsadmin-ng.toml` für die letzten etwa 25 gemergten PRs.
   Ergebnis: Welche PRs würden die Regeln automatisch freigeben, welche würden sie sperren?
2. **Mit Modell:** dieselben PRs mit `--llm` und je Kandidatenmodell; zuerst PRs, deren Befunde aus menschlichen Reviews bekannt sind.
   Ergebnis: gefundene und übersehene Befunde sowie die Kosten je Modell.
3. Mit dem Team die Regeln und das Modell festlegen.

`tools/dry-run` schreibt nichts nach Gitea; es braucht `GITEA_BOT_TOKEN` (Lesen genügt) und für `--llm` den OpenRouter-Key.
Bis das Konto `ai-reviewer` besteht, genügt ein persönlicher Token
mit den Rechten `read:issue`, `read:repository` und `read:user`.

### Ergebnis vom 2026-10-06

Geprüft wurden die letzten 25 gemergten PRs von hs.hsadmin.ng mit `config/hsadmin-ng.toml` und werkrevisor 0.20.6.
Ein Dry run prüft den letzten Head eines PRs, also den Stand nach allen menschlichen Reviews.

**Nur Regeln, 24 PRs:**
#283 bricht mit „base commit unknown“ ab, obwohl Gitea seine Merge-Basis kennt:
sein Ziel-Branch wurde nach dem Merge gelöscht, deshalb meldet Gitea keinen Basis-Commit.
Seit 0.21.0 bricht werkrevisor dort nicht mehr ab, seit 0.32.11 nennt es die Merge-Basis als Basis-Commit.

| Regel | PRs | Folge |
|---|---|---|
| harter Pfad | 12 | YELLOW, auch bei einem fehlerfreien Review des Modells |
| mehr als 1000 geänderte Zeilen | 5 | YELLOW |
| Test entfernt | 3 | YELLOW; bei #310 gewollt, weil das Merkmal wegfiel |
| keine sperrende Regel | 8 | GREEN möglich, wenn das Modell nichts Schweres findet |

Die harten Pfade trafen `buildSrc/**` und `build.gradle*` je 6-mal, `**/rbac/**` 6-mal,
`.werkator*` 3-mal und `tools/remote` 2-mal.
`**/rbac/**` trifft auch Szenario-Tests unter `src/test/…/rbac/`; das Team kann den Pfad auf `src/main/**` begrenzen.

**Mit Modell, Claude Sonnet 5.5, 11 PRs, zusammen 2,08 USD:**
die 8 PRs ohne sperrende Regel und die 3 PRs mit Zeilenkommentaren von Menschen.

| PR | Urteil | Kosten in USD |
|---|---|---|
| #311, #299, #292, #290 | GREEN | 0,26, 0,08, 0,09, 0,05 |
| #300 | YELLOW, ein Befund, an dem Jev zweifelt | 0,22 |
| #315, #304, #286 | ORANGE | 0,06, 0,19, 0,32 |
| #302, #307, #306 | ORANGE, dazu harte Regeln | 0,30, 0,27, 0,25 |

Von den 8 PRs ohne sperrende Regel wären 4 GREEN geworden;
mit `yellow_gate = "block"` aus `config/hsadmin-ng.toml` heißt das nur ein grüner Status;
ein Approval gibt der Bot erst mit `"approval"`.
Die ORANGE-Befunde betreffen gemergten Code, z. B. den Index der Szenario-Berichte in #304
und sich überschneidende Importläufe in #307; geprüft ist noch nicht, ob sie echte Fehler sind.
Mehrmals las das Modell Diff-Zeilen als „verirrte Zeilen“ im Code; Jev stufte diese Befunde meist als Hinweis herab.
Die menschlichen Zeilenkommentare zu #302, #307 und #306 sind Fragen an die Spezifikation;
das Modell fand dort andere Punkte, weil der geprüfte Head die Fragen schon beantwortet.

## 7. Branch Protection

Erst nach Schritt 6 und erst, wenn ein paar echte PRs ohne Pflicht gelaufen sind.

1. Ein Repository-Administrator führt `tools/branch-protection` aus werkrevisor aus, erst mit `--dry-run`:

   ```bash
   GITEA_TOKEN=… tools/branch-protection https://dev.hostsharing.net/hostsharing/hs.hsadmin.ng master \
       --contexts werkator,ai-review/gate --approvers ai-reviewer,<Reviewer> --block-admin-override --dry-run
   ```

   `werkator` ist der Status der CI unter Werkator; den Namen zeigt jeder Commit in Gitea.
   Das Werkzeug sichert die bestehende Regel als JSON-Datei und behält ihre Status-Kontexte.
2. Ohne `--dry-run` setzt es diese Felder:

   | Feld                                | Wert                                          |
   | ----------------------------------- | --------------------------------------------- |
   | `status_check_contexts`             | bisherige Kontexte und `ai-review/gate`        |
   | `required_approvals`                | `1`                                            |
   | `enable_approvals_whitelist`        | `true`                                         |
   | `approvals_whitelist_username`      | `ai-reviewer` und die menschlichen Reviewer    |
   | `block_on_rejected_reviews`         | `true`                                         |
   | `block_on_official_review_requests` | `true`; ab werkrevisor 0.20.2 zieht ein GREEN-Review seine Review-Anfrage zurück |
   | `dismiss_stale_approvals`           | `true`                                         |
   | `block_on_outdated_branch`          | `true`                                         |
   | `block_admin_merge_override`        | `true`, damit auch Administratoren die Sperre nicht übergehen |

3. Mit einem harmlosen PR prüfen: GREEN wird mergebar, YELLOW und ORANGE sperren bis zum Approval, RED bis zu einem neuen Commit.

Der Administrator der Repositories auf dev.hostsharing.net ist Betreiber, kein Entwickler.
Ein Merge über die Sperre hinweg ist deshalb kein Ausweg aus einem falschen RED.
Aus diesem Grund ergeben Befunde des Modells und des Classifiers höchstens ORANGE;
ab werkrevisor 0.15.0 bewertet Jev, ob ein Befund des Modells wahrscheinlich echt und schwer ist.
Ein Entwickler prüft die Befunde und gibt den PR mit seinem Approval frei.
RED kommt nur aus festen Regeln, die ein neuer Commit erfüllen muss.

## 8. PR-Ablauf und automatischer Merge

Agenten eröffnen ihre PRs als eigenes Gitea-Konto, auf git.javagil.de als `claude-code`, mit dem Titelpräfix „WIP: “.
Für einen WIP-PR startet Werkator keinen Review.
Erst wenn der PR fertig ist, entfernt der Autor das Präfix, in der Oberfläche oder per
`PATCH /api/v1/repos/<owner>/<repo>/pulls/<n>` mit dem neuen `title`.

Mit `[gate] require_wip_transition = true` prüft werkrevisor nur PRs, deren Titel Gitea als Wechsel von „WIP: “
zu ohne WIP protokolliert hat; ein PR ohne vorheriges „WIP: “ bekommt ERROR und kein Approval.
Mit `[gate] automerge = true` plant der Bot nach GREEN, YELLOW und ORANGE den Merge ein:
GREEN mergt sofort, YELLOW und ORANGE mit dem Approval eines Entwicklers.
Der Bot braucht dafür Schreibrecht im Repository.
Den Merge-Auftrag eines PRs löscht man in der Oberfläche oder per `DELETE /repos/<owner>/<repo>/pulls/<n>/merge`.

Ab werkrevisor 0.20.1 hält ein offener Hinweis den Merge eines GREEN-PRs zurück (`[gate] hints_hold_merge`, Standard `true`):
der Autor antwortet auf jeden Zeilenkommentar des Bots, löst ihn auf und startet den Review-Build neu oder pusht einen Commit.
Werkator startet den Review-Build über
`POST /api/repos/<repo>/builds/restart?branch=<branch>@ai-review&atOriginHead=true` neu;
ohne `@ai-review` startet es nur den normalen Build.
Ab werkrevisor 0.20.2 bekommt ein wiederverwendeter Zeilenkommentar den Text des neuen Befunds.
Für hsadmin-ng sind beide Schalter vorerst aus; das Team entscheidet, wann es sie einschaltet.

## Vertrauensmodell

Auf vm4006 laufen nur eng zusammengehörige Repositories (Backend und Frontend von hsadmin-ng).
Pushen können nur Entwickler, die ohnehin Schreibrecht auf allen diesen Repositories und vollen Zugriff auf vm4006 haben.
Ein CI-Build mit Docker-Socket (Testcontainers) könnte das Image `werkrevisor:<version>` umbenennen oder ersetzen;
dieses Restrisiko ist akzeptiert, weil ein PR niemandem mehr Zugriff verschafft, als er schon hat.
Sobald Fremde pushen dürfen, etwa bei einem öffentlichen Repository, muss die Build-Definition das Image über seine ID ansprechen (`docker image inspect --format '{{.Id}}' werkrevisor:<version>`).

## Rückbau

1. Die gesicherte Branch-Protection-Regel per `PATCH` zurückschreiben.
2. Den Block `builds.ai-review` aus der Maschinen-Konfiguration entfernen.
3. `ai-reviewer` aus den Repositories entfernen, Token löschen, Konto deaktivieren.
4. Den OpenRouter-Key löschen.
5. `docker image rm werkrevisor:<version>`.

## Offene Punkte vor dem Einsatz

- Review-Builds sollen nicht hinter der CI warten; dazu müssen sie das Limit `maxConcurrentPerRepository` umgehen können (Werkator).
- Ein menschliches Approval sollte `ai-review/assessment` aktualisieren (Werkator oder werkrevisor).
- Konfiguration für das Frontend-Repository; dessen Pfade kenne ich noch nicht.