nixos-config/docs/intent/board-keep-cards-visible-during-builder-stash.md

Intent: Intent-Karten während des Builder-Stash sichtbar halten

Ziel

Eine manuell angelegte, noch ungetrackte docs/intent/<slug>.md muss im Intent Board sichtbar bleiben, nachdem sie von geplant nach in_umsetzung verschoben wurde. Das gilt auch während der Builder seine Arbeitskopie vorbereitet und fremde Änderungen vorübergehend per Git-Stash beiseitelegt.

Beobachteter Fehler

Nach dem Verschieben einer ungetrackten Intent-Karte nach in_umsetzung verschwindet sie aus dem Board. Nach Abschluss des Builder-Laufs und einem erfolgreichen git stash pop kann sie wieder erscheinen.

Der Fehler ist unabhängig von der ausgewählten Runtime (codex oder claude). Der Runtime-Umschalter fiel zeitlich nur mit dem ersten beobachteten Auftreten zusammen.

Belegte Ursache

• agent-codex/builder.py ruft vor dem Modelllauf für fremde Änderungen git stash push --include-untracked auf. Dadurch verschwindet auch die ungetrackte Datei, aus der die gerade gestartete Board-Karte stammt, vorübergehend aus dem Arbeitsbaum.
• board-agent/trigger.py:list_intent_cards() entdeckt Intent-Karten ausschließlich über aktuell vorhandene docs/intent/*.md.
• merged_board() rendert State-Einträge ohne zugehörige Datei nur dann, wenn deren source gleich idea ist. Ein bereits gespeicherter source=intent-Eintrag wird deshalb während des Stash nicht ausgegeben.
• board.html lädt das Board alle fünf Sekunden neu. Sobald der nächste Abruf in dieses Zeitfenster fällt, wird die Karte aus dem DOM entfernt.
• Das neu ergänzte runtime-Feld beeinflusst diese Filterung nicht.

Umfang / Auftrag an den Builder

• Den Board-State beim erfolgreichen Übergang geplant -> in_umsetzung um die für eine sichere Darstellung nötigen unveränderlichen Kartendaten ergänzen: mindestens validierter Slug, Titel und kanonischer intent_path unter docs/intent/.
• merged_board() so erweitern, dass ein gespeicherter Intent während einer laufenden oder wartenden Pipeline weiterhin als Karte ausgegeben wird, wenn seine Quelldatei vorübergehend fehlt.
• Einen fehlenden Intent nicht still wie eine normale Karte behandeln: Die API soll einen maschinenlesbaren Zustand wie source_missing: true liefern und das Frontend einen knappen Hinweis wie „Intent-Datei vorübergehend nicht verfügbar“ anzeigen.
• Der Fallback darf ausschließlich aus serverseitig gespeicherten und erneut validierten Werten aufgebaut werden. Weder beliebige Pfade aus state.json noch Pfade außerhalb von docs/intent/<slug>.md dürfen lesbar werden.
• Nach Rückkehr der Datei muss automatisch wieder die Datei als Source of Truth gelten; es darf keine zweite dauerhaft abweichende Kopie des Intent-Inhalts entstehen.
• Falls git stash pop fehlschlägt, muss die Karte sichtbar bleiben und der bestehende Fehlerstatus beziehungsweise ein klarer Hinweis auf die fehlende Quelldatei erkennbar sein.
• Tests in board-agent/test_board_agent.py ergänzen, die den kompletten Sichtbarkeitsfall abdecken: vorhandene ungetrackte Intent-Datei, Übergang nach in_umsetzung, vorübergehend fehlende Datei, weiterhin gelieferte Karte und Rückkehr zur dateibasierten Darstellung.
• Den vorhandenen Builder-Stash-Test um die Board-relevante Randbedingung ergänzen oder einen Integrationstest hinzufügen, der belegt, dass --include-untracked die Quelldatei tatsächlich vorübergehend entfernt und die Board-Fallback-Darstellung dieses Zeitfenster abfängt.

Ausgeschlossen

• Keine Abschaffung des Schutzes vor dem versehentlichen Commit fremder Arbeitsbaumänderungen.
• Intent-Dateien nicht pauschal vom Stash ausschließen: Sie könnten sonst zusammen mit der Builder-Änderung unbeabsichtigt committed werden.
• Kein automatischer Commit einer manuell angelegten Intent-Datei allein durch das Verschieben der Karte.
• Keine Änderung an der Provider-Auswahl oder an den Codex-/Claude- Modellparametern.
• Kein automatischer Dienstneustart oder Deployment durch diesen Intent.

Sicherheitsanforderungen

• Slug weiterhin mit der bestehenden SLUG_RE validieren.
• Ein gespeicherter Pfad muss exakt docs/intent/<slug>.md entsprechen; keine frei wählbaren oder zustandsbasierten Dateipfade öffnen.
• State-only-Fallbacks dürfen keine unbekannten Kartenquellen sichtbar machen.
• Gleichzeitige State-Updates müssen weiterhin unter STATE_LOCK atomar gespeichert werden.

Erfolgskriterien

• Eine ungetrackte Intent-Karte bleibt während des gesamten Builder-Laufs in in_umsetzung sichtbar.
• Während die Datei gestasht ist, zeigt die Karte einen verständlichen Hinweis statt zu verschwinden.
• Nach erfolgreichem Restore verschwindet der Hinweis ohne manuellen Reload spätestens beim nächsten regulären Board-Refresh.
• Ein fehlgeschlagener Restore lässt die Karte mit erkennbarem Fehler sichtbar.
• Getrackte Intent-Karten und reine Idea-Karten funktionieren unverändert.
• Der Runtime-Snapshot für Builder und Review bleibt unverändert erhalten.
• Alle bestehenden sowie die neuen Board- und Builder-Tests sind grün.

Manuelle End-to-End-Prüfung

1. Diese Datei uncommitted im Arbeitsbaum belassen.
2. Die daraus erzeugte Karte manuell von geplant nach in_umsetzung verschieben.
3. Während des Builder-Laufs mehrere automatische Board-Refreshes abwarten und prüfen, dass die Karte sichtbar bleibt.
4. Nach Abschluss prüfen, dass wieder der normale Intent-Inhalt geöffnet werden kann und kein fremdes Arbeitsbaum-Artefakt committed wurde.