Archived

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.

pijukka 36bab940aa board-agent: parent-/child fan-out with automatic synthesis-intent generation

Implements docs/intent/board-subintent-fanout-synthesis.md. Any two known
cards can be linked as parent/child via a new board-UI-free endpoint
(PATCH /api/board/cards/<child>/parent, body {"parent_id": "..."}), which
sets parent_id on the child and appends it to depends_on on the parent
(state.json overlay only, same pattern as every other per-card field this
board tracks). Once every child linked to a parent has reached a terminal
state (success or failure -- see fanout.child_terminal()'s per-source-type
definition), the board automatically writes a new
docs/intent/<parent>-synthese.md summarizing each child's outcome and
result link, and marks the parent so this only fires once. The synthesis
card starts in "Geplant" like any other new intent file -- no automatic
trigger, no automatic quality judgment.

fanout.py is shared by trigger.py, worker.py and completion_watcher.py
(same sibling-module import pattern as completion_watcher's existing
"import worker") and salvaged, reviewed, and wired up from an orphaned
draft an earlier automated attempt at this same intent had left behind
uncommitted after hitting its own iteration limit -- the draft's logic
checked out on review, only the integration (nix wiring, call sites,
board.html display, tests) was missing.

Also grants board-agent-trigger.service write access to docs/intent/: the
common case for a Builder-flow child (a human dragging a reviewed card to
bereit_fuer_deployment/planung_mit_feedback/deployed) only ever happens
through this always-on service, never through the oneshot worker, so it is
the only process that can run maybe_synthesize() for that transition.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01F51W1LEGuSvNroZNj7vXqC

2026-09-08 16:44:54 +02:00

4.9 KiB

Raw Permalink Blame History

Intent: Parent-/Child-Fan-out und automatische Synthese für das Board

Ziel

Ein Parent-/Child-Kompositionsmodell für Board-Karten einführen, das Fan-out in unabhängige Research- und/oder Builder-Unter-Intents erlaubt, sowie die automatische Erzeugung eines Synthese-Intents, sobald alle Kinder einen Endzustand erreicht haben — der im Bericht beschriebene Zyklus Parent-Intent → Unter-Intents → parallele Agenten → Resultate → Synthese → Evaluation → nächste Iteration wird damit technisch abgebildet.

Umfang

Erweiterung des Runtime-Overlays in state.json um parent_id (optional), depends_on/blocked_by (Liste von Kind-Slugs) und result_ref (Commit-Hash bei Builder-Kindern, Berichtspfad bei Research-Kindern).
Der Worker verfolgt für jede Parent-Karte, ob alle verknüpften Kinder einen Endzustand erreicht haben (geprüft/archiviert bzw. Fehlerzustand für Builder-Kinder; recherche_fertig/ recherche_fehlgeschlagen für Research-Kinder).
Sind alle Kinder fertig, erzeugt das Board automatisch eine neue Synthese-Intent-Datei (docs/intent/<slug>.md), die jedes Kind mit Ergebnis/Ergebnislink zusammenfasst, und legt die zugehörige Karte in Phase „Geplant" an — kein automatischer Start der Umsetzung.
Builder-Kinder nutzen die Worktree-Parallelität aus board-builder-worktree-parallelism.md. Research-Kinder laufen weiterhin unter dem bestehenden gemeinsamen Research-Lock (ggf. weiterhin seriell, auch wenn sie gemeinsam als Kinder eines Parents dispatcht werden).
Sowohl Research- als auch Builder-Unter-Intents zählen als gültige Kinder eines Parents.

Explizit ausgeschlossen

Keine neue Evaluator-Rolle und keine automatische Qualitätsbewertung — der Synthese-Intent wird zwar automatisch angelegt, seine eigentliche Umsetzung (und jede inhaltliche Bewertung, ob das Parent-Ziel erreicht wurde) bleibt ein normaler, manuell angestoßener Intent-Durchlauf.
Keine Board-UI-Änderung (Parent-/Child-Anzeige, Baumdarstellung) — das ist Teil der bereits vorgeschlagenen UX-Folgeintents.
Keine Konfliktbehandlung/Merge-Logik zwischen überlappenden Kind-Intents — Fan-out gilt weiterhin nur für unabhängige Kinder, wie beim Worktree-Intent.
Keine Änderung am Locking-/Serialisierungsmodell von Research selbst.
Keine neue geführte Planner-Rolle/Ablaufänderung, um ein Parent-mit-Kindern-Set in einem Schritt anzulegen — das würde selbst die Rollen-/Katalog-Grenze für planner.md berühren und ist nicht Teil dieses Intents.

Annahmen

Kinder werden ganz normal als eigene Intent-/Research-Intent-Dateien vom Nutzer/Planner erstellt; die Verknüpfung zu einem parent_id erfolgt über einen leichtgewichtigen Mechanismus (z. B. eine kleine API-Ergänzung oder einen manuellen State-Eintrag), ohne dass dafür Board-UI-Arbeit nötig ist.
„Alle Kinder fertig" bedeutet: jedes Kind hat irgendeinen Endzustand erreicht — erfolgreich oder fehlgeschlagen; die Synthese soll auch über Teilfehlschläge berichten können, statt auf eine manuelle Wiederholung zu warten.
board-builder-worktree-parallelism.md ist umgesetzt, bevor Builder-Kinder in der Praxis genutzt werden.

Offene Risiken

Der genaue Mechanismus zum initialen Verlinken von Kindern mit einem parent_id ist noch nicht festgelegt (kleine API vs. manueller State-Eintrag) — muss in der Umsetzung konkretisiert werden.
Unklar, ob die Synthese bei einem fehlgeschlagenen Kind sofort auslösen soll (mit dokumentiertem Teilfehlschlag) oder auf eine manuelle Wiederholung warten sollte — diese Rohfassung geht von „sofort, auch bei Fehlschlag" aus, das sollte beim Bauen noch einmal bestätigt werden.
Ein automatisch erzeugter Intent umgeht den normalen Planner-Dialog (Rückfragen, Nutzerbestätigung) — sein Inhalt ist zwangsläufig weniger durchdacht als ein von Hand erarbeiteter Intent; ein Review-/Bearbeitungsschritt vor dem eigenen „In Umsetzung" ist essenziell und darf nicht übersprungen werden.
Gemischte Research- und Builder-Kinder unter einem Parent bringen zwei unterschiedliche Lock-/Nebenläufigkeitsmodelle zusammen — vor produktivem Mischbetrieb lohnt sich ein Pilot mit nur einer Kind-Art.

Erfolgskriterien

Eine Parent-Karte kann N Kinder (Research und/oder Builder) über parent_id/depends_on in state.json referenzieren.
Sobald alle Kinder eines Parents einen Endzustand erreicht haben, erzeugt das Board automatisch einen Synthese-Intent mit Zusammenfassung und Ergebnislinks je Kind, in Phase „Geplant".
Der Synthese-Intent braucht den normalen manuellen „Geplant → In Umsetzung"-Trigger — keine automatische Weiterverkettung über seine Erzeugung hinaus.
Builder-Kinder laufen über die Worktree-Parallelität, Research-Kinder über das bestehende Research-Lock.
Bestehende Einzelkarten ohne parent_id funktionieren unverändert weiter.

4.9 KiB Raw Permalink Blame History