nixos-config/docs/intent/builder-pipeline-git-intent-board-feedback.md

# Intent: Atomare Builder-Pipeline mit Git-native Intent-Board-Rückkopplung

**Status (2026-09-06): abgelöst, nicht mehr separat umgesetzt.** Dieses
Dokument entstand im selben Planungsschritt wie
`docs/intent/builder-iterationslimit.md` und
`docs/intent/git-intent-board-feedback.md` (Commit `3909cbf`) und
beschreibt dieselbe Ausbaustufe nur allgemeiner/redundant. Die
Iterationslimit-Hälfte ist als `builder-iterationslimit.md` umgesetzt und
deployed (Commit `e8983e4`); die Board-Hälfte lebt ausschließlich in
`git-intent-board-feedback.md` weiter (dort seit der Konsolidierung um
den hier stehenden Modellwahl-Abschnitt sowie zwei zusätzliche offene
Risiken ergänzt). Bleibt als historisches Dokument liegen, gleiches
Muster wie `docs/intent/kanban-board-admin-trigger.md`.

## Ziel

Die Agent-Pipeline soll einen nachvollziehbaren, Git-nativen Lebenszyklus für Implementierungsaufträge erhalten:

`Planung → Umsetzung → Review → bereit für Deployment → Deployed`

Bei Review-Befunden soll der Auftrag kontrolliert in die Planung zurückfließen:

`Review → Planung mit Feedback`

Builder-Aufträge sollen atomar, begrenzt und reproduzierbar laufen. Planung erfolgt mit einem leistungsfähigeren Modell; die eigentliche Umsetzung standardmäßig mit einem kostengünstigeren Builder-Modell.

## Umfang

### Atomare Builder-Aufträge

- Jeder Builder-Auftrag startet eine neue Session.
- Sitzungen werden nicht automatisch über mehrere Aufträge hinweg fortgesetzt.
- Jede Session erhält ein konfigurierbares Iterationslimit.
- Eine Iteration ist ein vollständiger Modellschritt einschließlich aller von diesem Schritt ausgelösten Werkzeuge.
- Das bestehende Wall-Clock-Timeout bleibt als zusätzliche Notbremse bestehen.
- Bei Erreichen des Iterationslimits:
  - bleibt der Zwischenstand erhalten,
  - wird ein strukturierter Zwischenstandsbericht erzeugt,
  - werden offene Punkte und der nächste sinnvolle Schritt benannt,
  - wird kein fertiger Prüf-Commit erzeugt,
  - wird kein Reviewer-Lauf gestartet,
  - erfolgt kein Push und kein Deployment.
- Ein Folgeauftrag startet später eine neue Session und erhält den bisherigen Zwischenstand ausdrücklich als Kontext.

### Modellwahl

- Für Builder-Aufträge gilt ein günstiges Modellprofil als Standard.
- Der Planner darf für einen konkreten Auftrag ein stärkeres Modell anfordern.
- Diese Anforderung muss individuell begründet werden; es gibt keine starre Liste vorgegebener Begründungskategorien.
- Das Modellprofil und die Begründung werden als strukturierte Auftragsmetadaten übergeben.
- Nur bekannte, konfigurierte Modellprofile dürfen verwendet werden.
- Freitext aus Intent- oder Reviewer-Inhalten darf die Modellwahl nicht eigenmächtig verändern.
- Das Iterationslimit gilt unabhängig vom gewählten Modell.
- Optional darf der Planner zusätzlich ein aufgabenspezifisches Iterationsbudget vorschlagen; die Plattform validiert es gegen globale Obergrenzen.

### Git-native Board-Darstellung

- `docs/intent/<slug>.md` bleibt der stabile fachliche Auftrag.
- Pro Intent wird eine versionierte Board-Metadatei unter `docs/board/<slug>.yaml` geführt.
- Diese Metadatei enthält mindestens:
  - Intent-Slug und Titel,
  - aktuelle Phase,
  - Builder-Job-ID,
  - verwendetes Modellprofil,
  - Begründung für ein stärkeres Modell,
  - Iterationslimit und verbrauchte Iterationen,
  - Worktree-/Branch-Referenz,
  - Prüf-Commit,
  - Reviewer-Bericht(e),
  - Review-Entscheidung,
  - Zeitpunkte und Fehlerstatus.
- Das Board rendert seine Spalten aus diesen versionierten Metadateien.
- Board-Bewegungen aktualisieren die Metadatei und erzeugen automatisch einen kleinen lokalen Git-Commit.
- Diese Commits werden nicht automatisch gepusht.
- Vor parallelen Zustandsänderungen und Builder-/Reviewer-Läufen schützt ein Git-Lock.

### Builder-Artefakt

- Ein fertiger Builder-Lauf arbeitet in einem isolierten lokalen Git-Worktree beziehungsweise Job-Branch.
- Bei erfolgreichem Abschluss wird dort ein lokaler Prüf-Commit erzeugt.
- Der Board-Eintrag referenziert Commit-Hash, Branch/Worktree und Diff-Basis.
- Der Haupt-Checkout bleibt frei von halbfertigen Builder-Änderungen.
- Bei Limitüberschreitung bleibt der Zwischenstand im zugehörigen Worktree erhalten, wird aber nicht als fertiger Prüfstand behandelt.
- Push, Merge, Aktivierung und Deployment sind nicht Teil des automatischen Builder-Abschlusses.

### Automatischer Review

- Jeder erfolgreiche Builder-Prüf-Commit wechselt automatisch in die Review-Phase.
- Für jeden solchen Commit wird automatisch ein read-only Reviewer-Lauf gestartet.
- Der Reviewer prüft genau den referenzierten Commit beziehungsweise dessen Diff.
- Der Reviewer schreibt einen versionierten Bericht unter `docs/review/`.
- Der Bericht enthält mindestens:
  - Intent-Slug,
  - geprüften Commit-Hash,
  - Scope und Prüfmethoden,
  - priorisierte Befunde,
  - offene Unsicherheiten,
  - Entscheidung,
  - konkrete Empfehlungen.
- Die Board-Metadatei referenziert den Bericht; der Bericht selbst wird nicht verschoben.

### Review-Entscheidungen

Der Reviewer liefert genau einen der beiden fachlichen Ausgänge:

- `bereit für Deployment`
  - Der geprüfte Stand gilt als technisch reviewt.
  - Das Board führt ihn in eine entsprechende Wartephase.
  - Ein Mensch entscheidet über Push, Merge und Deployment.
- `zurück zur Planung`
  - Das Board führt den Auftrag in eine Feedback-/Planungsphase.
  - Der Reviewer-Bericht bleibt dauerhaft unter `docs/review/`.
  - Eine neue Planner-Session wird nicht automatisch gestartet.
  - Du startest die Planner-Session bewusst und stellst Intent sowie Reviewer-Bericht als Kontext bereit.
  - Der Planner überarbeitet dasselbe Intent-Dokument; die Revisionhistorie bleibt in Git erhalten.

Nach einem manuellen Deployment setzt du die Karte selbst auf `Deployed`.

## Explizit ausgeschlossen

- Kein automatischer Git-Push.
- Kein automatisches Merge oder Deployment.
- Keine automatische Aktivierung von NixOS- oder anderen Änderungen.
- Keine automatische Planner-Session ohne bewussten Nutzerstart.
- Keine automatische Builder-Korrektur direkt aus dem Reviewer.
- Keine Verwendung oder Integration von Vikunja.
- Keine neue externe Datenbank oder SaaS-Abhängigkeit.
- Keine Änderung an `tnix` oder `pinix`.
- Keine Änderung am bestehenden Dashboard-Stack.
- Keine Verschiebung der fachlichen Intent- oder Reviewer-Dateien zwischen Lifecycle-Ordnern.
- Kein Vertrauen in Modellwahl- oder Freigabeanweisungen aus unstrukturiertem Intent-/Reviewer-Freitext.

## Annahmen

- Der primäre technische Ausführungspunkt bleibt `blunix`.
- Git ist der dauerhafte Audit-Trail.
- Board-Metadateien und Übergangscommits liegen im selben Repository wie die Intents.
- Der Planner bleibt die direkte Nutzerschnittstelle für neue Anforderungen und Review-Rückläufe.
- Der Reviewer bleibt read-only gegenüber Code und Konfiguration; seine einzige neue Schreibausnahme ist der zugeordnete Bericht unter `docs/review/`.
- Die bestehenden Freigabegrenzen für Commit, Push, Aktivierung und Deployment bleiben erhalten.
- Der Begriff „Builder“ umfasst die historische Builder-Rolle sowie andere Rollen, die im Auftrag tatsächlich Implementierungsarbeit ausführen, insbesondere den Administrator bei technischen Änderungen.

## Offene Risiken

- Die bestehende XMPP-Builder-Implementierung verwendet derzeit wiederaufgenommene Sitzungen und muss auf atomare Aufträge umgestellt werden.
- Die aktuelle Builder-Implementierung committen und pusht Änderungen teilweise außerhalb der Codex-Sandbox; dieser Ablauf muss vom neuen lokalen Worktree-/Prüf-Commit-Vertrag abgegrenzt werden.
- Die Codex-JSON-Ereignisse müssen zuverlässig gezählt werden, damit ein Iterationslimit auch bei langen Tool-Aufrufen greift.
- Ein abgebrochener Worktree braucht Aufräum-, Wiederaufnahme- und Verwerfungsregeln.
- Automatische lokale Git-Commits des Boards benötigen eine technische Identität, Locking und Konfliktbehandlung.
- Reviewer-Berichte für normale Diff-Reviews sind heute nicht durchgehend als Datei-Artefakte vorgesehen; Rollenvertrag, Katalog, Settings und Tests müssen konsistent erweitert werden.
- Ein fehlerhafter Board-Commit darf keinen falschen Phasenübergang oder doppelten Builder-/Reviewer-Lauf auslösen.
- Ein lokaler Commit ohne Push kann auf anderen Checkouts unsichtbar bleiben; der manuelle Veröffentlichungsweg muss deshalb klar dokumentiert werden.
- Die konkreten Standardwerte für Iterationslimit, Wall-Clock-Timeout und globale Obergrenzen sind noch festzulegen.

## Erfolgskriterien

- Jeder Builder-Auftrag startet nachweislich eine neue Session.
- Ein Builder-Auftrag kann sein Iterationslimit nicht überschreiten.
- Ein Limitabbruch hinterlässt einen nutzbaren Zwischenstand ohne fertigen Prüf-Commit.
- Ein erfolgreicher Lauf erzeugt einen isolierten lokalen Prüf-Commit mit eindeutiger Intent-Referenz.
- Das Board aktualisiert seinen Zustand ausschließlich über versionierte Metadateien und lokale Git-Commits.
- Kein Board-Übergang pusht oder deployed automatisch.
- Jeder erfolgreiche Builder-Commit startet automatisch genau einen Reviewer-Lauf.
- Jeder Reviewer-Lauf erzeugt einen Bericht unter `docs/review/`, der Intent und Commit eindeutig referenziert.
- Ein positiver Review führt zu `bereit für Deployment`.
- Ein negativer Review führt zu `zurück zur Planung` und macht den Bericht im Planner-Kontext verfügbar.
- Eine neue Planner-Session wird nur durch deinen bewussten Start ausgelöst.
- Ein manueller Deployment-Schritt kann anschließend auf `Deployed` setzen.
- Der Ablauf funktioniert ohne Vikunja, ohne neue externe Datenbank und ohne Änderungen an `tnix` oder `pinix`.
- Rollenverträge, Katalog, Settings und Regressionstests beschreiben denselben Ablauf konsistent.