# Intent: Live-Eval-Werkzeuge für die Researcher-Rolle

## Ziel

Der Researcher-Rolle (`agents/researcher.md`) die technischen Mittel geben, um
die im Bericht `docs/research/intent-board-architektur-ux-evaluation.md` als
„nicht ausgeführt" benannten Prüfungen künftig selbst durchzuführen:
Python-Testläufe der bestehenden Testsuiten, günstige Nix-Prüfungen (`flake
check`/`eval`), und rein lesende Beobachtung des echten Boards im Browser —
als dauerhafte Erweiterung der bestehenden Rolle, nicht als separate Rolle.

## Umfang

- `flake.nix`: neuer `devShells`-Output (mindestens für `x86_64-linux`) mit
  `python3` und den für die vorhandenen Testdateien (`test_board_agent.py`,
  `test_agent_codex.py`, `test_orga_agent.py`) nötigen Paketen (z. B.
  `pytest`) sowie einem Headless-Browser-Toolkit (z. B. Playwright) für rein
  lesende Board-Beobachtung.
- `agents/researcher.md`: Texterweiterung, die explizit erlaubt:
  - Ausführung der vorhandenen Python-Unit-Tests über die neue Dev-Shell
    (`nix develop`/`nix run`), ausschließlich auf dem Claude-Runtime-Pfad,
    ausschließlich auf blunix.
  - `nix flake check` und `nix eval` als Diagnosebefehle.
  - Rein lesende/beobachtende Browser-Interaktion mit dem echten Board auf
    blunix über die neue Dev-Shell (Seite laden, DOM/Text lesen,
    Tastaturfokus/ARIA-Eigenschaften prüfen, Screenshots) — ausdrücklich
    **ohne** Drag-and-Drop oder sonstige Aktionen, die eine echte
    Phasenänderung/einen Job auslösen.
  - Ausdrückliches Verbot von lokalem `nix build` eines Toplevel-Closures auf
    blunix (VPS-Überlastungsrisiko); stattdessen bei Bedarf Verweis auf den
    bestehenden `nixbuild.net`-Remote-Store-Pfad, aber kein automatischer
    Aufruf davon durch den Researcher selbst (das wäre bereits eine
    deployment-nahe Aktion).
- `agents/claude-settings/researcher.json`: Deny-Liste um
  `Bash(nix build *)` (bzw. eine treffende Einschränkung, die
  `nix flake check`/`nix eval` nicht blockiert) ergänzen, um das
  Build-Verbot strukturell abzusichern, nicht nur textlich in der
  Rollendatei.
- Alle neuen Fähigkeiten gelten weiterhin ausschließlich für den
  Claude-Runtime-Pfad und ausschließlich auf blunix (kein SSH/Zugriff auf
  pinix, tnix oder weitere Hosts) — deckungsgleich mit der bestehenden
  Shell-Einschränkung in `researcher.md`.

## Explizit ausgeschlossen

- Keine echten Schreibrechte auf das Live-Board, laufende Karten, den
  Runtime-Schalter oder sonstigen Systemzustand — Zustandsänderungen bleiben,
  wenn überhaupt später gebraucht, einer separaten isolierten Testinstanz
  vorbehalten (nicht Teil dieses Intents).
- Kein lokaler `nix build` von Toplevel-Closures auf blunix.
- Kein Deployment, keine Aktivierung, kein Service-Neustart (bleibt Aufgabe
  des Administrators).
- Keine tatsächliche Token-, Kosten-, Laufzeit- oder UX-Messung/
  Instrumentierung — das ist laut Bericht ein eigener, noch zu
  entscheidender Datenschutz-/Mess-Intent (`board-runtime-signal-measurement`)
  und wird hier bewusst ausgeklammert.
- Keine neue separate Rolle; die bestehende `researcher`-Rolle wird
  erweitert.
- Keine Änderung an anderen Rollen (`builder.md`, `reviewer.md`,
  `planner.md` etc.).

## Annahmen

- Die vorhandenen Python-Testdateien (`test_board_agent.py`,
  `test_agent_codex.py`, `test_orga_agent.py`) sind mit `pytest` lauffähig,
  sobald `python3`/`pytest` über eine Dev-Shell verfügbar sind.
- Ein Headless-Browser-Toolkit (z. B. Playwright) lässt sich über `nixpkgs`
  beziehen und rein lesend gegen das echte Board fahren, ohne dessen
  Polling/Zustand zu beeinträchtigen.
- Der Deny-Listen-Mechanismus in `agents/claude-settings/researcher.json`
  (Bash-Pattern-Matching) kann `nix build` gezielt blocken, ohne
  `nix flake check`/`nix eval` mit zu treffen.

## Offene Risiken

- Ein Muster wie `Bash(nix build *)` in der Deny-Liste könnte je nach
  Matching-Implementierung auch legitime Umgehungen zulassen (z. B.
  `nix --extra-experimental-features nix-command build ...`) oder zu
  breit/zu eng greifen — die genaue Deny-Regel muss beim Umsetzen gegen die
  tatsächliche Pattern-Syntax geprüft werden.
- Auch rein „lesende" Browser-Automatisierung erzeugt zusätzliche Poll-/
  Ladelast auf dem echten Board; bei wiederholten Testläufen sollte das
  nicht mit dem produktiven 5-Sekunden-Polling kollidieren (kein hartes
  Ausschlusskriterium, aber zu beobachten).
- Playwright (oder ein Äquivalent) als neue Abhängigkeit steht im
  Spannungsfeld mit dem Grundsatz „kleines, forkbares Grundsystem" — Umfang
  der Dev-Shell sollte beim Bauen bewusst minimal gehalten werden.

## Erfolgskriterien

- `flake.nix` bietet eine Dev-Shell, aus der heraus die drei vorhandenen
  Python-Testsuiten laufen.
- `agents/researcher.md` erlaubt explizit `nix flake check`/`nix eval`,
  Testläufe über die Dev-Shell und rein lesende Browser-Beobachtung des
  echten Boards — mit ausdrücklichem Verbot von `nix build`,
  Zustandsänderungen, Deployment und Aktivierung.
- `agents/claude-settings/researcher.json` blockt `nix build` strukturell
  über die Deny-Liste.
- Ein künftiger Research-Auftrag mit Runtime `claude` kann diese Prüfungen
  tatsächlich ausführen, ohne dass ein VPS-Überlastungsrisiko wie beim
  ersten Live-Smoke-Test entsteht.