# 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 --source --agent