nixos-config/docs/intent/board-intent-operator-orchestration.md

# Intent: Automatisierte Intent-Operator- und Builder-Orchestrierung

## Ziel

Zwischen Planung und Umsetzung einen neuen Agenten namens **Operator**
einführen. Wird ein geplanter Parent-Intent in die Operator-Spalte
verschoben, beginnt seine Analyse sofort und ohne weitere Freigabe. Der
Operator entscheidet, ob der Intent direkt in eine Builder-Pipeline gehen
kann oder vorher in kleinere, eigenständig umsetzbare Builder-Unter-Intents
zerlegt werden muss.

Eine erfolgreiche Operator-Entscheidung startet die empfohlenen Builder-
Läufe automatisch. Eine deterministische Scheduling-Schicht setzt dabei
Abhängigkeiten und die begrenzte VPS-Kapazität durch. So bleibt die
inhaltlich anspruchsvolle Zerlegung bei einem dafür geeigneten Modell,
während kleinere, klar begrenzte Unter-Intents mit günstigeren Profilen
bearbeitet werden können.

## Umfang

### Operator-Rolle und Vertrauensgrenze

- Eine neue, eigenständige Rolle `operator` mit eigener Rollendatei,
  Runtime-Konfiguration und eigenem Katalogeintrag einführen.
- Der Operator liest den vollständigen Parent-Intent sowie den für seine
  Entscheidung nötigen Repository-Kontext read-only.
- Der Operator schreibt keine Dateien, verändert keinen Board-State, queued
  keine Jobs, committet und deployt nicht.
- Der Operator liefert ausschließlich eine streng strukturierte Antwort.
  Ein vertrauenswürdiger Board-Wrapper validiert sie vollständig und führt
  erst danach die vorgesehenen Datei-, State- und Queue-Änderungen aus.

### Board-Phasen und Entscheidungen

- Neue, eindeutig sichtbare Phasen einführen:
  - `operator_angefordert`
  - `operator_laeuft`
  - `wartet_auf_kinder`
  - `durch_kinder_blockiert`
- Das Verschieben einer Karte von `geplant` nach
  `operator_angefordert` queued unmittelbar den Operator-Job. Es gibt
  danach kein zusätzliches Bestätigungs- oder Freigabe-Gate.
- Der Operator liefert genau eine der folgenden Entscheidungen:
  - `direct_builder`: Der Parent-Intent ist klein und präzise genug für
    einen direkten Builder-Lauf.
  - `split`: Der Parent-Intent wird in mehrere Builder-Unter-Intents
    zerlegt.
  - `needs_human`: Eine sichere automatische Entscheidung ist wegen
    Unklarheit, notwendiger Recherche, zu starker Kopplung oder eines nicht
    unterstützten Falls nicht möglich.
- Bei `direct_builder` wählt der Operator eine empfohlene Builder-Lane und
  ein Modell-/Reasoning-Profil. Der Wrapper queued den ursprünglichen
  Parent-Intent danach automatisch in der empfohlenen Builder-Pipeline.
- Bei `split` erzeugt der Wrapper atomar höchstens zehn vollständige,
  eigenständig umsetzbare Builder-Intent-Dateien. Entweder werden alle
  Kinder und ihre Beziehungen angelegt oder keine davon.
- Bei `needs_human` oder einer ungültigen Operator-Antwort entstehen keine
  Kinder und kein Builder-Job. Die Parent-Karte zeigt den Grund und einen
  klaren manuellen Recovery-Pfad.
- In dieser ersten Version erzeugt der Operator ausschließlich Builder-
  Kinder. Benötigt der Auftrag zuerst Research, muss er `needs_human`
  wählen.

### Ausführungsplan und Parent-/Child-Modell

- Das vorhandene Parent-/Child-Modell aus `fanout.py` wiederverwenden und
  für jedes Kind mindestens folgende Metadaten speichern:
  - `parent_id`
  - `blocked_by`
  - `wave`
  - `recommended_lane`
  - empfohlenes Runtime-/Modell-/Reasoning-Profil
  - erwarteter Schreibumfang beziehungsweise Zielpfade
  - kindspezifische Akzeptanzkriterien
- `blocked_by` bildet echte Ausführungsabhängigkeiten ab. Die bereits
  vorhandene Parent-Liste `depends_on` bleibt die kanonische Liste aller
  Kinder und wird nicht gleichzeitig als Kind-zu-Kind-Abhängigkeitsgraph
  überladen.
- Ausführungsnummern stellen Wellen dar: Mehrere unabhängige Kinder dürfen
  dieselbe Welle `W1` besitzen und parallel laufen. Eine spätere Welle darf
  erst starten, wenn ihre explizit genannten Voraussetzungen erfolgreich
  abgeschlossen sind.
- Der Operator muss konkurrierende Schreibumfänge erkennen und betroffene
  Kinder entweder über `blocked_by` serialisieren oder `needs_human`
  wählen. Die Angabe von Zielpfaden ist eine Planungs- und
  Scheduling-Hilfe, keine vollständige technische Garantie semantischer
  Unabhängigkeit.
- Rekursives automatisches Zerlegen von Operator-Kindern ist in der ersten
  Version nicht zulässig.

### Deterministischer Scheduler und Kapazität

- Eine deterministische Scheduling-Schicht entscheidet, **wann** ein vom
  Operator geplanter Builder-Job starten darf. Das LLM entscheidet nicht
  über Locks, aktive Slots oder Queue-Kapazität.
- Der Scheduler berücksichtigt nicht nur die Board-Agent-Inbox, sondern
  auch nachgelagerte Builder-Inboxen, Processing-Verzeichnisse und aktive
  Jobs, damit bereits übergebene Arbeit weiterhin gegen das Limit zählt.
- Der Scheduler startet ausschließlich Kinder, deren `blocked_by`-
  Abhängigkeiten erfolgreich abgeschlossen sind.
- Kinder mit überlappendem deklariertem Schreibumfang dürfen nicht
  gleichzeitig gestartet werden.
- Eine konfigurierbare globale Obergrenze begrenzt alle gleichzeitig
  laufenden Operator-veranlassten Builder-Jobs. Der Anfangswert ist `2`.
- Lane-spezifische Limits dürfen zusätzlich gelten, aber niemals die
  globale Obergrenze umgehen.
- Derselbe Intent darf weder durch konkurrierende Scheduler-Läufe noch nach
  einem Service-Neustart doppelt gequeued werden.
- Nach Builder-Abschluss, Fehlerbehebung oder Service-Neustart bewertet der
  Scheduler wartende Parents erneut und startet neu freigewordene Kinder.
- Kinder starten nach einer vollständig validierten `split`-Entscheidung
  automatisch. Es gibt keine Einzelbestätigung pro Kind.

### Modellprofile und Eskalation

- Die Zerlegung selbst läuft mit einem für Planungsqualität geeigneten
  Profil, weil Fehler an dieser Stelle alle nachgelagerten Jobs betreffen.
- Kleine, klar begrenzte Kinder dürfen mit günstigeren, vom Operator
  empfohlenen Builder-Profilen starten.
- Modellwahl ist eine Empfehlung innerhalb einer serverseitig erlaubten
  Konfiguration; frei erfundene Runtime-, Modell- oder Reasoning-Werte aus
  der Modellausgabe werden abgelehnt.
- Bereits vorhandene, begrenzte Retry- oder Korrekturmechanismen dürfen für
  ein Kind genutzt werden. Dieser Intent führt keinen unbegrenzten Retry-
  oder automatischen Rekursionsloop ein.
- Ein günstigeres Profil gilt erst dann als erfolgreich, wenn sein Ergebnis
  den normalen Reviewpfad bestanden hat. Die bloße Fertigmeldung des
  Builder-Prozesses reicht nicht aus.

### Synthese, Fehler und Parent-Abschluss

- Ausschließlich erfolgreich reviewte Builder-Kinder zählen als
  erfolgreich abgeschlossen.
- Ein fehlgeschlagenes, am Limit beendetes oder negativ reviewtes Kind
  blockiert die Synthese. Das heutige Fan-out-Verhalten, auch nach
  terminalen Fehlschlägen sofort eine Synthese zu erzeugen, wird für
  Operator-Parents bewusst nicht verwendet.
- Bei einem solchen Kind wechselt der Parent nach
  `durch_kinder_blockiert` und zeigt die blockierenden Kinder sowie deren
  Fehler- oder Feedbackstatus an.
- Der Parent bleibt blockiert, bis jedes fehlgeschlagene Kind über die
  vorhandenen Recovery-/Retry-Wege erfolgreich abgeschlossen wurde. Danach
  wird die Orchestrierung automatisch fortgesetzt.
- Erst wenn alle Kinder erfolgreich sind, erzeugt das Board genau einen
  Synthese-Intent. Die vorhandene idempotente Parent-/Child-Fan-in-Logik
  soll dafür wiederverwendet und um die strengere Erfolgsbedingung ergänzt
  werden.
- Der Synthese-Intent wird ohne zusätzliche Freigabe automatisch gestartet
  und durchläuft Builder und Review.
- Die Synthese bewertet und vervollständigt das kombinierte Ergebnis gegen
  Ziel und Akzeptanzkriterien des ursprünglichen Parent-Intents. Sie darf
  nicht lediglich Kindberichte zusammenfassen.
- Der Parent gilt erst nach einem erfolgreichen Review des
  Synthese-Ergebnisses als abgeschlossen. Ein fehlgeschlagenes oder
  abgelehntes Synthese-Ergebnis führt in einen sichtbaren Blockierungs-
  beziehungsweise Feedbackzustand und niemals stillschweigend zum
  Abschluss.

### Board-Darstellung

- Parent und Kinder erhalten eine deterministisch aus der Parent-ID
  abgeleitete, gemeinsame und ausreichend kontrastreiche visuelle
  Gruppierung.
- Farbe kennzeichnet nur die Familie. Agententyp, Builder-Lane,
  Ausführungswelle und Status werden als getrennte Text-Badges dargestellt
  und dürfen nicht ausschließlich über Farbe vermittelt werden.
- Parent-Karten zeigen Fortschritt, beispielsweise `2/5 Kinder
  erfolgreich`, aktuell laufende Wellen und blockierende Kinder.
- Kind-Karten zeigen Parent, Welle, `blocked_by`, empfohlenes Profil und
  tatsächlichen Laufstatus.
- Die Darstellung bleibt auch für bestehende Einzelkarten ohne
  Parent-Beziehung kompatibel.

## Explizit ausgeschlossen

- Keine Research-Kinder und keine gemischten Research-/Builder-Graphen in
  der ersten Version.
- Kein menschliches Approval zwischen Operator-Analyse, Kind-Erzeugung und
  automatischem Dispatch.
- Kein neuer Security- oder Risikoklassifikations-Gate; bestehende
  Sandbox-, Builder-, Review-, Deployment- und Systemgrenzen bleiben
  unverändert bestehen.
- Kein rekursives automatisches Splitten von Kindern.
- Keine unbegrenzten automatischen Retries oder Korrekturschleifen.
- Keine dynamische CPU-/RAM-Messung oder lastabhängige automatische
  Veränderung der Parallelitätsgrenze.
- Keine neue Merge-Engine für semantisch überlappende Änderungen.
- Kein automatisches Training oder selbstständiges Umschreiben von Rollen
  und Modellprofilen aufgrund einzelner Ergebnisse.

## Annahmen

- Die in Arbeit befindlichen Builder-Lanes und isolierten Worktrees werden
  stabilisiert und verifiziert, bevor die produktive Parallelitätsgrenze
  über `1` erhöht wird.
- Builder-Kinder bleiben normale `docs/intent/*.md`-Artefakte und
  durchlaufen dieselben Builder-/Review-Grundregeln wie manuell angelegte
  Intents.
- Orchestrierungsmetadaten und der strukturierte Operator-Bericht werden im
  Board-State gespeichert; die Intent-Dokumente bleiben die Quelle der
  Wahrheit für den fachlichen Auftragsinhalt.
- Der konfigurierte Anfangswert von zwei parallelen Jobs ist eine
  vorsichtige Startannahme und muss anhand realer VPS-Beobachtung bestätigt
  werden.
- Kleinere Intents ermöglichen den Einsatz günstigerer Modelle, garantieren
  aber für sich allein weder geringere Gesamtkosten noch dieselbe Qualität
  wie ein einzelner großer Lauf.

## Offene Risiken

- Eine fachlich schlechte Zerlegung kann versteckte Kopplungen erzeugen,
  obwohl deklarierte Zielpfade nicht überlappen.
- Automatisch bis zu zehn Kinder zu erzeugen und zu starten kann bei
  mittelgroßen Intents teurer sein als ein einzelner stärkerer Builder-
  Lauf.
- Im privaten Board-State gespeicherte Operator-Entscheidungen besitzen
  eine schwächere Git-Historie als versionierte Intent-Dokumente.
- Ein nicht erfolgreich repariertes Kind kann seinen Parent dauerhaft
  blockieren; dieser Zustand muss im Board deutlich sichtbar bleiben.
- Zwei parallele Nix-Evaluierungen oder Builds können den VPS bereits
  überlasten. Die Softwaregrenze ersetzt keinen realen Belastungstest.
- Modell- und Lane-Empfehlungen sind heuristisch. Ohne einen kleinen
  repräsentativen Eval-Korpus kann nicht belegt werden, dass die
  günstigeren Pipelines dieselbe Ergebnisqualität wie ein großer
  Modelllauf erreichen.
- Automatischer Start ohne Freigabe erhöht den möglichen Ressourcenverbrauch
  und die Wirkung einer Fehlentscheidung des Operators. Diese bewusste
  Entscheidung muss in UI und Dokumentation sichtbar sein, auch wenn ein
  zusätzlicher Security-Gate erst später ergänzt wird.

## Erfolgskriterien

- Das Verschieben eines geplanten Intents in die Operator-Spalte startet
  den Operator unmittelbar und ohne weitere Bestätigung.
- Der Operator ist eine neue, eigenständige read-only Rolle namens
  `operator`.
- Eine vollständig validierte `direct_builder`-Entscheidung queued den
  ursprünglichen Intent automatisch mit einem erlaubten empfohlenen
  Builder-Profil.
- Eine vollständig validierte `split`-Entscheidung erzeugt atomar höchstens
  zehn vollständige, miteinander verknüpfte Builder-Karten und startet alle
  aktuell ausführbaren Kinder automatisch.
- Ungültige oder unvollständige Operator-Ausgaben erzeugen weder Teilmengen
  von Kind-Dateien noch Builder-Jobs.
- Standardmäßig laufen höchstens zwei Operator-veranlasste Builder-Jobs
  gleichzeitig; nachgelagerte Queues und aktive Jobs werden korrekt
  mitgezählt.
- Abhängigkeiten, überlappende deklarierte Schreibumfänge und
  Ausführungswellen werden vor jedem Start berücksichtigt.
- Parent-/Child-Familie, Welle, Lane, Fortschritt und Blockierungsgrund sind
  auf dem Board sichtbar und nicht allein farblich codiert.
- Ein Service-Neustart verliert keine wartende Arbeit und erzeugt keine
  doppelten Builder-Jobs.
- Jeder fehlgeschlagene oder negativ reviewte Kind-Lauf verhindert die
  Synthese zuverlässig.
- Wird das letzte blockierende Kind später erfolgreich abgeschlossen,
  setzt der Scheduler die Orchestrierung ohne erneute Freigabe fort.
- Die Synthese wird genau einmal und erst nach erfolgreichem Review aller
  Kinder erzeugt und automatisch gestartet.
- Der Parent wird erst nach erfolgreichem Review des Synthese-Ergebnisses
  abgeschlossen.
- Bestehende Intents ohne Operator- oder Parent-/Child-Metadaten
  funktionieren unverändert weiter.