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.