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.