nixos-config/docs/intent/board-column-config-backend-state.md

# Intent: Spaltenweite Modell-/Iterations-Konfiguration — Backend-Speicher und API

## Ziel

Ein neuer, additiver State-Bereich `column_config` in `state.json` sowie
zugehörige GET/POST-HTTP-Endpunkte in `board-agent/trigger.py`
speichern für jede der drei job-auslösenden Spalten (`in_umsetzung`,
`review`, `recherche_laeuft`) eine eigene Konfiguration aus Runtime,
Modell und Reasoning-Effort — bei `in_umsetzung` zusätzlich ein
Iterationslimit. Dies ist reine Speicher-/API-Infrastruktur; noch keine
UI und noch kein Verbraucher (Job-Trigger) liest diese Werte — das
bestehende Verhalten (globaler `board_runtime()`) bleibt unverändert
und unangetastet bestehen, bis Geschwister-Intents darauf umstellen.

## Umfang

- Festgelegtes Schema (verbindlicher Vertrag für alle Geschwister-
  Intents dieses Splits — Feldnamen exakt so übernehmen):
  ```
  column_config = {
    "in_umsetzung":     {"runtime": "codex", "model": "", "reasoning_effort": "", "iteration_limit": 20},
    "review":           {"runtime": "codex", "model": "", "reasoning_effort": ""},
    "recherche_laeuft": {"runtime": "codex", "model": "", "reasoning_effort": ""},
  }
  ```
  `model`/`reasoning_effort` = `""` bedeutet „kein Override, bestehender
  Env-Var-Default greift downstream weiter" — diese Semantik ist
  wichtig für die Geschwister-Intents, die daraus Job-Payloads bauen
  (dort muss `""` beim Zusammenbau des Payloads als *fehlendes* Feld
  behandelt werden, nicht als explizite leere Zeichenkette, damit
  `common.append_model_options()`/`append_claude_model_options()`
  weiterhin ihren `model=None`-Fallback auf die bestehenden Env-Vars
  nehmen).
- `board-agent/trigger.py`, neben dem bestehenden `board_runtime()`/
  `set_board_runtime()` (Zeile 93-103, bleibt unverändert):
  - `validate_column_config_value(column, payload)`: validiert
    `runtime` (wiederverwendet `validate_runtime()`, Zeile 86-90),
    `model` (Regex `[A-Za-z0-9][A-Za-z0-9._:+-]*`, max. 128 Zeichen,
    leer erlaubt), `reasoning_effort` (Regex `[A-Za-z0-9_-]{1,32}`,
    leer erlaubt), sowie bei `column == "in_umsetzung"` zusätzlich
    `iteration_limit` (Integer, gültiger Bereich 5–40 inklusive).
  - `load_column_config()`: liest `state.json["column_config"]`,
    füllt fehlende Spalten/Felder mit den Default-Werten aus dem
    Schema oben auf (Rückwärtskompatibilität für `state.json`-Dateien,
    die den Schlüssel noch nicht kennen).
  - `set_column_config(column, updates)`: merged validierte `updates`
    in die bestehende gespeicherte Konfiguration der genannten Spalte
    und persistiert via `save_state()` (Zeile 128) unter demselben
    `STATE_LOCK` (Zeile 83) wie `set_board_runtime()`.
  - `GET /api/board/column-config` → gibt das vollständige,
    default-aufgefüllte `column_config`-Objekt aller drei Spalten
    zurück.
  - `POST /api/board/column-config/<column>` (Pfad-Parameter `column`
    ∈ `{in_umsetzung, review, recherche_laeuft}`, sonst 404) → Body
    ist ein JSON-Objekt mit einer beliebigen Teilmenge der erlaubten
    Felder dieser Spalte; bei Validierungsfehler 400 mit
    `{"error": "..."}`; bei Erfolg 200 mit der aktualisierten
    Konfiguration dieser einen Spalte.
  - `GET /api/board` (bestehender Handler, Zeile 717) bekommt
    zusätzlich den Schlüssel `"column_config"` in der Antwort, additiv
    neben dem bestehenden `"runtime"`-Schlüssel — Letzterer bleibt
    unverändert bestehen (wird von keinem Geschwister-Intent dieses
    Kindes entfernt).
- `board-agent/test_board_agent.py`: Tests für
  `validate_column_config_value()`/`load_column_config()`/
  `set_column_config()` sowie für die beiden neuen HTTP-Endpunkte
  (gültige/ungültige `runtime`/`model`/`reasoning_effort`/
  `iteration_limit`, unbekannte Spalte → 404, Default-Werte bei leerem
  `state.json`).
- `board-agent/README.md`: neuen Abschnitt für
  `GET/POST /api/board/column-config[/<column>]` ergänzen, analog zum
  bestehenden Eintrag für `POST /api/board/runtime` (Zeile 55).

## Explizit ausgeschlossen

- Keine UI-Änderung — `board.html` bleibt in diesem Kind unangetastet
  (eigenes Geschwister-Intent).
- Kein Umstellen der bestehenden Job-Trigger-Stellen
  (`in_umsetzung`-Trigger, Research-Trigger, Review-Completion) auf
  `column_config` — die lesen weiterhin `board_runtime()` wie bisher
  (eigene Geschwister-Intents).
- Kein Entfernen von `board_runtime()`/`set_board_runtime()` oder der
  bestehenden `GET/POST /api/board/runtime`-Endpunkte — die bleiben
  vollständig funktionsfähig, bis das Frontend-Geschwister-Intent sie
  ablöst.
- Keine dynamische Modell-Liste aus `agents/catalog.json` — Validierung
  bleibt reine Regex-/Bereichsprüfung, keine Whitelist-Abfrage gegen
  eine externe Quelle.
- Kein Pro-Karte-Override — Konfiguration ist ausschließlich
  spaltenweit.

## Annahmen

- Der oben dokumentierte `column_config`-Schema-Vertrag (Feldnamen,
  Default-Werte, Bedeutung von `""`) ist für alle Geschwister-Intents
  dieses Splits verbindlich und wird dort unverändert vorausgesetzt.
- `state.json` ohne den Schlüssel `column_config` ist ein gültiger,
  häufiger Zustand (frischer Rollout) und muss transparent auf die
  Default-Werte zurückfallen, ohne einen Fehler zu werfen.
- Spaltenweiter statt Pro-Karte-Scope ist die gewünschte Granularität.

## Offene Risiken / offene Fragen

- Modell-Whitelist im späteren Dropdown muss von Hand mit
  `agents/catalog.json` synchron gehalten werden (kein automatischer
  Sync) — Drift-Risiko, betrifft aber primär das Frontend-Geschwister.
- Das Iterationslimit-Feld hat hier bereits eine Obergrenze (5–40) als
  Ressourcenschutz — falls ein anderer Wertebereich gewünscht wird,
  muss das hier und im Frontend-Geschwister-Intent synchron geändert
  werden.
- `STATE_LOCK` schützt nur Schreiboperationen innerhalb dieses
  Prozesses; das bestehende Nebenläufigkeitsmodell (ThreadingHTTPServer)
  bleibt unverändert und war bereits vor diesem Intent so.

## Erfolgskriterien

- `state.json` ohne `column_config`-Schlüssel liefert bei
  `GET /api/board/column-config` die dokumentierten Default-Werte.
- `POST /api/board/column-config/in_umsetzung` mit gültigem Body
  persistiert `runtime`/`model`/`reasoning_effort`/`iteration_limit`
  und ein nachfolgendes GET liefert exakt diese Werte.
- `POST /api/board/column-config/review` mit `iteration_limit` im Body
  wird abgelehnt (400) oder das Feld wird ignoriert — Review kennt kein
  Iterationslimit.
- Ungültiger Spaltenname im Pfad → 404. Ungültiges `model`/
  `reasoning_effort`/`iteration_limit` → 400 mit Fehlermeldung.
- `GET /api/board` enthält weiterhin den bisherigen `"runtime"`-
  Schlüssel unverändert, zusätzlich den neuen `"column_config"`-
  Schlüssel.
- Bestehende `board_runtime()`/`set_board_runtime()`-Tests und die
  bestehenden `/api/board/runtime`-Endpunkte bleiben unverändert grün.
- Neue Tests für Validierung, Defaults und beide neuen Endpunkte sind
  grün.