# Intent: Git-natives Intent-Board mit Reviewer-Feedback ## Ziel Ein Git-natives Intent-Board ersetzt Vikunja für den Lebenszyklus `Idee/Backlog → Geplant → In Umsetzung → Review → bereit für Deployment → Deployed` mit kontrolliertem Rückfluss `Review → Planung mit Feedback`. Ein Web-UI auf blunix visualisiert den Zustand und löst zwei Übergänge aktiv aus. Löst und ersetzt `docs/intent/kanban-board-admin-trigger.md`. **Konsolidierung (2026-09-06):** dieses Dokument ist jetzt auch die alleinige Fortsetzung von `docs/intent/builder-pipeline-git-intent-board-feedback.md`, das dieselbe Ausbaustufe in einer früheren, allgemeineren Fassung beschrieben hatte, ohne sie explizit abzulösen. Beide Dokumente entstanden im selben Planungsschritt (Commit `3909cbf`); die Iterationslimit-Hälfte davon wurde als eigener, engerer Intent ausgekoppelt (`docs/intent/builder-iterationslimit.md`, umgesetzt und deployed 2026-09-06, Commit `e8983e4`) und ist damit erledigt, nicht mehr offen. Die verbleibende Board-Hälfte lebt ab jetzt ausschließlich hier; `builder-pipeline-git-intent-board-feedback.md` bleibt als historisches Dokument liegen, wird aber nicht mehr separat umgesetzt (gleiches Muster wie bei `kanban-board-admin-trigger.md` oben). Inhalte aus dem abgelösten Dokument, die hier noch fehlten, sind unten eingearbeitet (Modellwahl-Abschnitt, zwei zusätzliche offene Risiken). **Status: Phase 1 umgesetzt und deployed (2026-09-06).** Kern des Job-getypten Queue-/Watcher-Mechanismus, Builder-Wiederverwendung über `agent-codex`s bestehende `builder-inbox/`, headless Reviewer-Runner und automatische Phasenübergänge stehen (`hosts/blunix/localServices/agent-codex/builder.py` Completion-Hook, `hosts/blunix/localServices/board-agent/worker.py` + `completion_watcher.py`). Zwei Annahmen unten stimmten nicht mit der Realität überein und wurden dabei bewusst geändert statt umgesetzt wie ursprünglich spezifiziert: - **Auth bleibt vorerst Traefik-BasicAuth**, nicht OIDC/Dex — es gibt im Repo keinen wiederverwendbaren `oauth2-proxy`/Dex-Mechanismus für interne Routen (verifiziert 06.09.2026: `oauth2-proxy` ist eine Singleton-Instanz vor einem einzigen, aktuell deaktivierten Backend). OIDC-Self-Check (wie Forgejo/GoToSocial/Headscale) bleibt ein eigenständiger Folge-Intent. - **Builder-Artefakt: bestehendes Stash-Modell wiederverwendet, keine isolierten Worktrees.** Board-Jobs laufen über den bereits gebauten, getesteten `agent-codex`-Builder (Lock + `git stash` im geteilten Checkout) statt über neue Worktree-Infrastruktur — bewusste Entscheidung, siehe "Offene Risiken" unten. - Zusätzlicher Fund: Reviewer läuft `--sandbox read-only`, nicht `workspace-write --add-dir docs/review` — Letzteres scoped Schreibrechte in diesem `codex-cli`-Build nachweislich NICHT pfadgenau (live getestet). Reviewer liefert seinen Bericht stattdessen als `===REVIEW-REPORT===`-Marker-Block, den der Wrapper außerhalb der Sandbox schreibt. **Weiterhin nicht Teil dieser Phase** (unverändert offen): `docs/board/.yaml` mit automatischen lokalen Git-Commits (Board bleibt bei `state.json`) und die Planner-Modellwahl-Eskalation aus dem Umfang-Abschnitt unten (kein Planner-Handoff-Mechanismus für Board-Karten vorhanden, der strukturierte Metadaten liefern könnte). ## Umfang - `docs/intent/.md` bleibt der fachliche Auftrag; pro Intent eine versionierte `docs/board/.yaml` mit Phase, Job-ID, Modellprofil + Begründung, Iterationslimit/verbrauchte Iterationen (aus `docs/intent/builder-iterationslimit.md`), Worktree-/Branch-Referenz, Prüf-Commit, Reviewer-Bericht(e), Review-Entscheidung, Zeitpunkte, Fehlerstatus. - **Modellwahl** (aus `builder-pipeline-git-intent-board-feedback.md` übernommen, dort wie in `builder-iterationslimit.md` bereits spezifiziert): Standard ist ein günstiges Modellprofil. Der Planner darf pro Auftrag ein stärkeres, individuell begründetes Profil anfordern — ausschließlich aus den bekannten, konfigurierten Profilen, niemals aus Freitext innerhalb eines Intent- oder Reviewer-Textes heraus. Modellprofil und Begründung werden als strukturierte Auftragsmetadaten übergeben und landen als eigene Felder in der Board-Metadatei (siehe oben). Das Iterationslimit gilt unabhängig vom gewählten Modell. Der Planner darf zusätzlich ein aufgabenspezifisches Iterationsbudget vorschlagen; die Plattform validiert es gegen die globale Obergrenze (20, siehe `builder-iterationslimit.md`) — der genaue Validierungsmechanismus ist Sache der Umsetzung. - Web-UI (Tailnet-only, ausschließlich blunix) hinter der **bestehenden** `oauth2-proxy`/Dex-Grenze für interne Dienste — keine eigene Auth-Implementierung. Nur du (lukas) erfüllst den geforderten OIDC-Gruppenclaim/Identität für die auslösende Aktion. - **Ein generischer, parametrisierter Queue-/Watcher-Mechanismus**: ein `systemd.paths`-Unit beobachtet ein Queue-Verzeichnis, Jobs tragen ein Feld „Job-Art" (`builder` oder `review`) und werden davon abhängig an die passende Rolle headless übergeben. Der zugehörige Dienst verarbeitet Jobs mit **Concurrency=1** streng seriell — dadurch strukturell keine parallelen Schreiber auf dieselbe Board-Datei, kein separates Git-Lock-Konzept nötig. - Aktiv steuerbar sind genau zwei Übergänge über denselben Mechanismus: 1. **Geplant → In Umsetzung**: durch dich im Web-UI ausgelöst, legt einen `builder`-Job in die Queue. Dieser ruft die **bestehende Builder-Rolle** headless auf (ihr bereits vorgesehener Start `xmpp-worker` deckt das ab) — nicht den Administrator. Das entspricht dem bestehenden Builder-Vertrag (Schreibzugriff, Commit/Push erlaubt, kein Deploy) und weicht nicht von der „Orchestrator ist einzige Dialogschnittstelle"-Regel für sichtbare Spezialisten ab, weil der Builder ohnehin schon headless/direkt ansprechbar ist. 2. **Erfolgreicher Builder-Prüf-Commit → Review**: vollautomatisch, legt einen `review`-Job in dieselbe Queue. - Builder-Artefakt: isolierter lokaler Git-Worktree/Job-Branch, bei Erfolg ein lokaler Prüf-Commit, Board referenziert Commit-Hash/Branch/ Diff-Basis; Haupt-Checkout bleibt frei von halbfertigen Änderungen; bei Limitüberschreitung (siehe `builder-iterationslimit.md`) bleibt Zwischenstand im Worktree, gilt nicht als fertiger Prüfstand. - Reviewer: **keine neue Aufgabenart** — die bestehende freie Diff-Review in `reviewer.md` bekommt einen zusätzlichen, klar markierten Absatz: bei Auslösung durch den Board-Trigger mit festem Commit-Scope schreibt sie zusätzlich einen Bericht nach `docs/review/.md` (Intent-Slug, geprüfter Commit, Scope/Prüfmethoden, priorisierte Befunde, Unsicherheiten, Entscheidung, Empfehlungen) und trifft eine der zwei Entscheidungen unten. Dieser Lauf darf headless statt `herdr-visible` laufen (Abweichung vom sonstigen Start-Modus der Reviewer-Rolle, nur für diesen Trigger). - Review-Entscheidungen: `bereit für Deployment` (Board → Wartephase, Mensch entscheidet über Push/Merge/Deployment) oder `zurück zur Planung` (Board → Feedback-/Planungsphase, Bericht bleibt dauerhaft, **keine** automatische neue Planner-Session — du startest sie bewusst mit Intent+Bericht als Kontext). Nach manuellem Deployment setzt du die Karte selbst auf `Deployed`. ## Explizit ausgeschlossen - Ersetzt `docs/intent/kanban-board-admin-trigger.md` und `docs/intent/builder-pipeline-git-intent-board-feedback.md` fachlich; beide Dateien bleiben als historische Dokumente liegen, werden aber nicht mehr separat umgesetzt. - Kein automatischer Git-Push, kein automatisches Merge/Deployment/ Aktivierung. - Keine automatische Planner-Session, keine automatische Builder-Korrektur direkt aus dem Reviewer. - Keine Verwendung/Integration von Vikunja, keine neue externe Datenbank/SaaS-Abhängigkeit. - Keine Änderung an `tnix`/`pinix`, keine Änderung am bestehenden Dashboard-Stack. - Kein öffentlicher Zugriff auf das Web-UI, kein roher API-Key für Agentenläufe. - Keine eigene Identitätsprüfung außerhalb des bestehenden Dex/oauth2-proxy-Musters. - Kein separates Git-Level-Lock-Konzept (ersetzt durch Concurrency-1-Queue). - Keine neue, eigenständig dokumentierte Reviewer-Aufgabenart. - Kein neuer Rollenkatalog-Eintrag für die reine Plattforminfrastruktur (Web-UI-Dienst, Queue-Verzeichnis, `systemd.paths`-Watcher, `oauth2-proxy`-Route) — analog zu `agent-codex` reine NixOS-Dienste ohne eigenen Agent-Rolleneintrag. ## Annahmen - Primärer Ausführungspunkt bleibt `blunix`; Git ist der dauerhafte Audit-Trail. - `docs/intent/builder-iterationslimit.md` ist umgesetzt und deployed (2026-09-06, Commit `e8983e4`) — dieses Dokument definiert das Limit nicht neu, referenziert dessen Daten (Limit 20, verbrauchte Iterationen) nur im Board. - Reviewer bleibt read-only gegenüber Code/Konfiguration; einzige neue Schreibausnahme ist der Bericht unter `docs/review/`. - „Builder" umfasst auch den Administrator bei technischen Plattformänderungen; der `builder`-Job-Typ aus der Queue ruft aber konkret die Builder-Rolle auf, nicht den Administrator. - Der bestehende `oauth2-proxy`/Dex-Mechanismus lässt sich analog zu anderen internen Diensten auf dieses Web-UI anwenden. - Die Umsetzung ändert `agents/reviewer.md` (neuer Absatz für board-getriggerten Review), `agents/catalog.json` und `agents/claude-settings/reviewer.json` (Versionsbump, Klarstellung des headless-Starts für diesen Trigger). ## Offene Risiken - **Entschieden und umgesetzt (2026-09-06):** Board-Jobs verwenden den bestehenden, geteilten Builder-Checkout (Lock + `git stash`, `locked_repos()`/`stash_foreign_changes()`) statt eines isolierten Worktrees/Job-Branches — die "Builder-Artefakt"-Formulierung oben gilt fachlich als entsprechend abgeschwächt für diese Phase. Wiedervorlage, falls echte Parallelität mehrerer gleichzeitiger Board-Jobs mal gebraucht wird. - **Neu, aus der Konsolidierung:** ein lokaler Commit ohne Push kann auf einem anderen Checkout (z. B. dem Recovery-Checkout auf pinix) unsichtbar bleiben. Der manuelle Veröffentlichungsweg (wer pusht wann, von welchem Checkout aus) muss dokumentiert sein, bevor das Board produktiv genutzt wird. - **Bereits gelöst, nicht mehr offen:** zuverlässiges Zählen der Codex-JSON-Ereignisse für das Iterationslimit — erledigt in `common.run_streaming()`/`builder.py` (`item.completed`-Events, live gegen `codex-cli` verifiziert). Ebenso bereits gelöst: der board-getriggerte Reviewer-Absatz existiert schon in `agents/reviewer.md` (Commit `3909cbf`), muss also bei der Umsetzung nur noch tatsächlich aufgerufen werden, nicht neu entworfen. - Selbst-Trigger-Vermeidung: auch mit Concurrency-1-Queue muss der Watcher-Mechanismus so gebaut sein, dass er nicht auf eigene Status-Update-Schreibvorgänge in der Board-Datei reagiert (Trigger sollte an neue Job-Dateien in der Queue gebunden sein, nicht an jede Änderung der YAML-Datei selbst) — Detailkonstruktion ist Sache der Umsetzung. - Abgebrochener Worktree braucht Aufräum-, Wiederaufnahme- und Verwerfungsregeln. - Exaktes Job-/Queue-Schema für beide Job-Arten, Fehlerbehandlung bei abstürzendem/unterbrochenem Lauf (z. B. durch einen Deploy, der den Worker-Dienst neu lädt). - Automatische lokale Board-Commits brauchen eine technische Git-Identität. - **Vertagt (2026-09-06):** genaue OIDC-Gruppen-/Claim-Anforderung für den Trigger-Endpunkt — Auth bleibt für diese Phase BasicAuth (siehe Status-Notiz oben), wird also erst mit dem OIDC-Folge-Intent relevant. ## Erfolgskriterien - Board aktualisiert Zustand ausschließlich über versionierte Metadateien und lokale Git-Commits, kein automatischer Push/Deploy. - Eine fertige Intent-Karte lässt sich im Web-UI nur von dir (verifiziert über die bestehende OIDC-Grenze) von „Geplant" nach „In Umsetzung" bewegen und löst nachweisbar einen echten headless Builder-Lauf aus. - Jeder erfolgreiche Builder-Commit startet automatisch genau einen Reviewer-Lauf über denselben generischen Mechanismus, der einen Bericht unter `docs/review/` erzeugt. - Zu keinem Zeitpunkt schreiben zwei Prozesse gleichzeitig dieselbe Board-Datei (verifiziert durch Concurrency-1-Queue-Verhalten). - Positiver Review → `bereit für Deployment`; negativer Review → `zurück zur Planung` mit Bericht im Planner-Kontext verfügbar. - Web-UI läuft ausschließlich Tailnet-erreichbar hinter bestehender OIDC-Grenze, kein öffentlicher Zugriff, kein roher API-Key. - Ablauf funktioniert ohne Vikunja, ohne neue externe Datenbank, ohne Änderungen an `tnix`/`pinix`/Dashboard-Stack. - `docs/intent/kanban-board-admin-trigger.md` und `docs/intent/builder-pipeline-git-intent-board-feedback.md` gelten als durch diesen Intent abgelöst.