lukas/nixos-config
Archived
1
0
Fork 1
Code Issues Pull requests Releases Wiki Activity
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.
nixos-config/docs/intent/researcher-live-eval-tooling.md
pijukka 05575df408 docs: commit backlog of already-resolved intent/review corpus files 
board-agent's own README documents docs/intent/ and docs/research-intent/
as tracked corpus directories, and docs/review/<slug>.md as the reviewer's
persisted report per card - but the pipeline only writes these files to
the checkout, it never commits them itself. This had built up a backlog
of intent/review docs for cards already marked deployed or archiviert in
the live board state, which were sitting uncommitted in the working tree.

Adds that backlog as-is: the originating intents, their reviewer reports,
the research-intent/research pair for the board UX evaluation, and one
standalone process-retrospective report (board-review-pipeline-context-
overhead.md, same genre as the two already-tracked audit reports in
docs/review/). No code changes.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T7UVrKsttMP9a6FiGFna9b
2026-09-10 12:06:53 +02:00

5.2 KiB
Raw Permalink Blame History

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.