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.mds 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.