nixos-config/docs/herdr-eskalation-review-entwurf.md

# Entwurf: Reviewer-Einbindung, Blocker-Eskalation, Token-Reduktion

**Status: Am 01.09.2026 freigegeben.** Die Entscheidungen stehen jetzt in
`docs/herdr-orchestration.md`, Abschnitt „Reviewer-Einbindung, Eskalationskette
und Rückfrage-Kanal" — dort maßgeblich für den laufenden Betrieb. Diese Datei
bleibt als Herkunfts- und Begründungsdokument bestehen. Entgegen der
ursprünglichen Annahme unten brauchten weder `agents/reviewer.md` noch
`agents/admin.md` eine Vertragsänderung: beide Verträge erlaubten das neue
Verhalten bereits (Reviewer definiert nicht, wer ihn wann beauftragt;
Administrator war schon Empfänger eng begrenzter Korrekturaufträge). Geändert
wurden stattdessen `agents/agent-manager.md` (neuer Abschnitt
„Eskalationsannahme", 2.0.0 → 2.1.0) und `agents/orga.md` (neuer Abschnitt
„Rückfrage-Kanal (Pilot)", 2.0.0 → 2.1.0), jeweils mit Versionsbump in
`agents/catalog.json`.

## 1. Reviewer als Standardschritt, nicht als Zusatzoption

Bisher ist der Reviewer ein eigenständiger, nur bei Bedarf angefragter
Spezialist. Vorschlag: Der Orchestrator zieht ihn standardmäßig in jede
Übergabekette ein, die eine Aktivierungsfreigabe vom Nutzer verlangt
(Administrator-Diffs, neue oder geänderte Rollen vom Agent-Manager, neue
Herdr-Automatisierung). Ablauf:

1. Spezialist (z. B. Administrator) meldet fertige Änderung samt Diff und
   Aktivierungswirkung an den Orchestrator — wie bisher, ohne
   Aktivierungsfreigabe.
2. Der Orchestrator startet **vor** der Nutzerfreigabe den Reviewer mit genau
   diesem Diff als Auftrag (kein erneutes Durchsuchen des ganzen Repos nötig
   — Diff-Scope steht bereits fest, siehe Token-Reduktion unten).
3. Reviewer liefert Befunde nach dem bestehenden Format aus `reviewer.md`
   (`blocker`/`high`/`medium`/`low`, `Keine Befunde` falls zutreffend).
4. Der Orchestrator synthetisiert Spezialist-Ergebnis und Review-Befund in
   einer Nachricht an den Nutzer. Bei `blocker`-Befunden geht die
   Aktivierungsfrage nicht an den Nutzer, sondern zurück an den
   ursprünglichen Spezialisten zur Korrektur — der Reviewer selbst ändert
   nichts (bleibt read-only, wie bisher).
5. Ausnahme: trivialer, vom Nutzer selbst als unkritisch markierter Auftrag
   kann das Reviewer-Hop überspringen, wenn der Nutzer das im Auftrag explizit
   sagt ("ohne Review", "trivial"). Standard bleibt: Review vor Freigabe.

Das ändert nichts an `reviewer.md`s Grenzen (weiterhin keine
Aktivierungs-/Deploymentfreigabe, weiterhin read-only) — es ändert nur, *wann*
er im Ablauf startet: regelhaft statt optional.

## 2. Eskalationsprotokoll bei Blockern

Aktuell: Ein Spezialist, der an eine Grenze stößt, "hält an und meldet" —
aber es gibt keinen definierten nächsten Schritt. Vorschlag für eine feste
Eskalationskette, die zur bestehenden Architektur passt (kein
Spezialist-zu-Spezialist-Kanal, der Orchestrator bleibt einzige
Dialogschnittstelle):

1. **Blockierter Spezialist → Orchestrator.** Meldung enthält: was fehlt oder
   nicht funktioniert (konkreter Befund, nicht nur "geht nicht"), vermutete
   Ursache falls erkennbar, und was zur Fortsetzung nötig wäre (z. B. fehlendes
   Paket, fehlende Berechtigung, fehlender Secret-Pfad, kaputte Konfiguration).
2. **Orchestrator entscheidet**, ob es sich um ein plattformseitig behebbares
   Problem handelt. Trifft das zu, delegiert er einen eng begrenzten
   Korrekturauftrag an den Administrator — mit der Meldung aus Schritt 1
   wörtlich als Kontext, nicht paraphrasiert (reduziert Rückfragen und
   Tokenverbrauch durch verlorene Details).
3. **Administrator behebt** nach seinem bestehenden Vertrag (deklarativ
   ändern, prüfen, Diff berichten, auf Aktivierungsfreigabe warten — siehe
   Abschnitt 1 zur Reviewer-Einbindung, die hier ebenfalls greift, wenn die
   Korrektur eine Aktivierungsfreigabe braucht).
4. **Administrator → Orchestrator**: bestätigt Behebung samt Status
   ("aktiv" nach Freigabe, oder "bereit, wartet auf Freigabe"). Kein
   automatischer Restart des blockierten Spezialisten vor dieser Bestätigung.
5. **Orchestrator → ursprünglich blockierter Spezialist**: setzt ihn erst
   nach bestätigter Behebung mit demselben Auftrag fort und nennt knapp, was
   sich geändert hat (z. B. "orga-calendar-write ist jetzt verfügbar"). Der
   Spezialist muss nicht selbst nachfragen oder pollen, ob es weitergeht.
6. Ist das Problem *nicht* plattformseitig behebbar (z. B. fehlende
   Nutzerentscheidung, fehlende externe Zugangsdaten, fachliche Unklarheit),
   geht die Meldung direkt an den Nutzer statt an den Administrator — der
   Administrator ist Fixer für technische Hürden, nicht für alles.

Das beantwortet die beiden offenen Fragen aus dem Diktat: *wer* das Problem
üblicherweise beheben kann (Administrator, für technische Hürden), und *wie*
der ursprüngliche Agent erfährt, dass und wann es weitergeht (Schritt 5,
Orchestrator-vermittelt, kein eigenständiges Warten oder Nachfragen).

## 3. Token-Reduktion

Konkrete Hebel, keine Kürzung der Sicherheitsregeln:

- **Reviewer-Scope auf den Diff begrenzen** (siehe Abschnitt 1, Schritt 2):
  kein erneutes volles Repo-Einlesen, wenn der Diff und die betroffenen
  Dateien schon feststehen.
- **Eskalationsmeldung wörtlich weiterreichen** (Abschnitt 2, Schritt 2)
  statt sie vom Orchestrator zusammenfassen und den Administrator dann
  nachfragen zu lassen.
- **Reasoning-Effort nach Aufgabentyp**, nicht pauschal hoch: Ein
  Korrekturauftrag mit klar benanntem, engem Fix (z. B. fehlendes Paket
  ergänzen) braucht nicht denselben Effort wie eine offene Diagnose. Die
  bestehende `model_profiles`-Tabelle in `catalog.json` erlaubt das schon
  pro Start; zu ergänzen wäre eine Faustregel im Orchestrator-Auftrag: eng
  spezifizierte Korrektur → Standardprofil, offene Fehlersuche →
  Eskalation auf `sol`/`high` nur bei tatsächlichem Bedarf (bestehende Regel
  aus `herdr-orchestration.md` gilt unverändert weiter).
- **Panes wiederverwenden statt neu spawnen** innerhalb einer
  zusammenhängenden Auftragskette: Wenn ein Spezialist für Folgeaufträge
  im selben Kontext ohnehin wieder gebraucht wird (z. B. Administrator prüft
  nach eigenem Fix direkt noch einen zweiten, verwandten Punkt), spart die
  Fortsetzung im selben Pane das erneute volle Einlesen von `AGENTS.md` und
  der Rollendatei gegenüber einem frischen Prozess.

## 4. Rückfrage-Kanal: Spezialist → Orchestrator, ohne Turn-Ende

**Anlass:** Live beobachtet am 31.08.2026. Der Orchestrator wollte für Orgas
offenen Capability-Handoff (`orga-cal-20260901-hdm-online-plenum-v1`) den
Administrator um eine formale Herdr-Antwort bitten. Es gibt aktuell keinen
Weg für einen Spezialisten, dem Orchestrator *während* eines laufenden Turns
gezielt eine Frage zu stellen und auf eine Antwort zu warten -- nur "anhalten
und im Ergebnisformat melden" (Turn endet, Pane wird `idle`) oder eben gar
nicht fragen. Der Orchestrator musste stattdessen den gesamten Kontext in
einer einzigen langen Nachricht vorwegnehmen und danach auf volle
Turn-Fertigstellung pollen -- langsam und je nach Formulierung selbst wieder
Anlass für einen Fehlalarm (siehe unten).

**Vorschlag:** Ein dritter Zustand zusätzlich zu "anhalten und Turn beenden"
und "einfach weiterarbeiten": *blockiert mit Rückfrage, Turn bleibt offen*.

1. Der Spezialist meldet über `herdr pane report-agent <pane_id> --source
   <id> --agent <label> --state blocked --message "<konkrete Frage>"` und
   wartet, statt den Turn zu beenden.
2. Der Orchestrator bekommt das zeitnah über `herdr agent wait <target>
   --status blocked --timeout <ms>` mit, statt in festen Intervallen auf
   volle Fertigstellung zu pollen.
3. Der Orchestrator liest die Frage, holt bei Bedarf die Nutzerentscheidung
   ein und schickt die Antwort in **dieselbe** Pane (`herdr pane run
   <pane_id> "<Antwort>"` + `herdr pane send-keys <pane_id> Enter`) --
   Session, Kontext und Prompt-Cache bleiben erhalten, kein neuer Prozess.
4. Der Spezialist arbeitet im selben Turn weiter.

**Grenze, nicht verhandelbar:** Dieser Kanal ist ausschließlich für fehlende
fachliche Angaben oder Nutzerentscheidungen gedacht (Datum, Zielkalender,
Formulierung, "welche der beiden Optionen"). Er ersetzt **nicht** die
Capability-Handoff-Kette aus `agents/orga.md` und ist kein Weg, eine
Berechtigungs- oder Scope-Ausweitung "einfach schnell" vom Orchestrator
bestätigen zu lassen. Genau das ist am 31.08.2026 live schiefgegangen: eine
Orchestrator-Nachricht, die dem Administrator eine bereits als
sicherheitsrelevant dokumentierte Scope-Frage (breiter Admin-Zugriff vs.
angefordertes One-Shot-Recht) zur Bewertung vorlegte, wurde von Orga *und*
unabhängig davon vom Administrator als mögliches
Social-Engineering-/Prompt-Injection-Muster erkannt und abgelehnt -- zu
Recht, unabhängig davon, dass die Nachricht tatsächlich vom legitimen
Orchestrator kam. Ein Rückfrage-Kanal hätte das nicht anders gelöst, weil
das eigentliche Problem keine fehlende Angabe, sondern eine
Sicherheits-/Scope-Entscheidung war, die ohnehin nicht über einen relayten
Chat-Text an einen anderen Agenten delegierbar ist. Diese Trennung -- fachliche
Rückfrage über den neuen Kanal, Capability-/Scope-Fragen ausschließlich über
die bestehende Handoff-Kette mit echter, direkter Nutzerbestätigung -- muss
im Rollenvertrag jeder betroffenen Rolle explizit stehen, sonst verwischt sie
in der Praxis.

## Entscheidungen (01.09.2026)

- **Reviewer-Pflicht:** nur ab Risikoschwelle, nicht für jeden
  Administrator-Diff (konkrete Kriterien in `docs/herdr-orchestration.md`).
- **Eskalationskette:** Agent-Manager gilt zusätzlich zum Administrator als
  Fixer, für Rollenvertrags-Probleme statt technischer Infrastrukturhürden.
- **Rückfrage-Kanal:** zunächst nur an einer Rolle pilotieren, nicht sofort
  für alle. Gewählt: `orga`, weil der auslösende Vorfall vom 31.08.2026 dort
  entstand. Eine zusätzliche technische Durchsetzung der Grenze zur
  Capability-Handoff-Kette (automatische Ablehnung erkennbarer
  Scope-Schlüsselwörter) wird bewusst noch nicht gebaut — der Pilot läuft
  erst promptbasiert bei einer einzigen Rolle, bevor sich der Zusatzaufwand
  rechtfertigt.
- ~~Wie soll die eigentliche Policy-Frage aus dem 31.08.2026-Vorfall geklärt
  werden~~ -- **entschieden, 31.08.2026:** bewusst einfach, keine engere
  Radicale-Identität. Der blockierte Kalendereintrag ("HdM Plenum") wurde
  direkt vom Nutzer über die Orchestrator-Sitzung angelegt, nicht über Orgas
  eigenen Handoff -- siehe `agents/orga.md`, Abschnitt "Referenzhandoff,
  abgeschlossen ohne formale `available`-Antwort". Orgas Regel 3 (keine
  pauschalen Schreibrechte) bleibt unverändert; das ist keine Blanko-Freigabe
  für künftige automatische Orga-Schreibzugriffe auf private Ziele.