lukas/nixos-config
Archived
1
0
Fork 1
Code Issues Pull requests Releases Wiki Activity
This repository has been archived on 2026-09-17. You can view files and clone it, but you cannot make any changes to its state, such as pushing and creating new issues, pull requests or comments.
nixos-config/docs/intent/builder-iterationslimit.md
pijukka 3909cbf5f0 feat(agents): add builder iteration limit and board-triggered review contract 
Builder now runs atomic sessions with a configurable iteration limit (20)
on top of the unchanged wall-clock timeout; a follow-up job gets prior
progress passed in as context instead of resuming a session. Reviewer
gains a board-triggered review addendum (same free diff review, fixed
commit scope, docs/review/<slug>.md report, headless start only for this
trigger) for the upcoming git-native intent board. Orga gets
disableClaudeAiConnectors so it can't fall back to generic claude.ai
connectors instead of its own helper scripts.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ANg2L2xUmNJ45t9mcv6HVT
2026-09-06 16:17:47 +02:00

3.3 KiB
Raw Permalink Blame History

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.