# Intent: Iterationslimit für atomare Builder-Aufträge

## Ziel

Builder-Aufträge laufen atomar (neue Session je Auftrag) mit einem
konfigurierbaren Iterationslimit, damit sie nicht unbegrenzt weiterlaufen.
Das bestehende Wall-Clock-Timeout bleibt unverändert als zusätzliche
Notbremse.

## Umfang

- Jeder Builder-Auftrag startet eine neue Session, keine automatische
  Fortsetzung über Aufträge hinweg.
- Iterationslimit: **20** (ein vollständiger Modellschritt inkl. aller
  ausgelösten Tools = eine Iteration). Startwert, später ohne neue
  Intent-Klärung justierbar.
- Bei Limit-Erreichen: Zwischenstand bleibt erhalten, strukturierter
  Zwischenstandsbericht mit offenen Punkten und nächstem sinnvollen
  Schritt, **kein** Prüf-Commit, **kein** Reviewer-Lauf, **kein**
  Push/Deployment.
- Ein Folgeauftrag startet später eine neue Session mit dem bisherigen
  Zwischenstand ausdrücklich als Kontext.
- Modellwahl: günstiges Profil als Standard; der Planner darf pro Auftrag
  ein stärkeres, individuell begründetes Profil anfordern; nur bekannte
  konfigurierte Profile; Freitext aus Intent-/Reviewer-Inhalten darf die
  Wahl nicht verändern; das Iterationslimit gilt unabhängig vom Modell;
  der Planner darf optional ein aufgabenspezifisches Iterationsbudget
  vorschlagen, gegen eine globale Obergrenze validiert.

## Explizit ausgeschlossen

- Kein Board, kein Web-UI, kein automatischer Reviewer-Trigger (Teil des
  separaten Intents `docs/intent/git-intent-board-feedback.md`).
- Keine Änderung am Wert des bestehenden Wall-Clock-Timeouts.
- Kein automatischer Push, kein automatisches Merge/Deployment/
  Aktivierung.
- Keine Änderung an `tnix`/`pinix`.

## Annahmen

- Primärer Ausführungspunkt bleibt `blunix`.
- „Builder" umfasst die historische Builder-Rolle sowie andere Rollen mit
  tatsächlicher Implementierungsarbeit im Auftrag, insbesondere den
  Administrator bei technischen Plattformänderungen.
- Die bestehende XMPP-Builder-Implementierung muss von wiederaufgenommenen
  auf atomare Sitzungen umgestellt werden.
- Die Umsetzung ändert `agents/builder.md` (Vertragsänderung: atomare
  Sessions, Iterationslimit-Verhalten, Zwischenstandsbericht-Format) sowie
  `agents/catalog.json` (Versionsbump für `builder`, aktuell 1.0.0) und
  `agents/tests/roles.sh` (Regressionstest-Anpassung analog zu bisherigen
  Versionsbumps). Keine neuen Schreibrechte, keine Sandbox-Änderung
  (`workspace-write` bleibt) — reine Verhaltensänderung.

## Offene Risiken

- Codex-JSON-Ereignisse müssen zuverlässig gezählt werden, damit das
  Iterationslimit auch bei langen Tool-Aufrufen greift — unterschiedliches
  Event-Format je Runtime (Codex/Claude) ist eine bekannte Fehlerquelle.
- Genauer Mechanismus, wie ein vom Planner vorgeschlagenes
  aufgabenspezifisches Budget gegen die globale Obergrenze validiert wird,
  ist Sache der Umsetzung.
- Format und Ablageort des Zwischenstandsberichts bei Limit-Erreichen sind
  noch nicht festgelegt.

## Erfolgskriterien

- Jeder Builder-Auftrag startet nachweislich eine neue Session.
- Ein Builder-Auftrag kann sein Iterationslimit (20) nicht überschreiten.
- Ein Limitabbruch hinterlässt einen nutzbaren Zwischenstand ohne
  fertigen Prüf-Commit, ohne Reviewer-Lauf, ohne Push.
- Ein Folgeauftrag erhält den Zwischenstand nachweislich als Kontext.