05575df408
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
101 lines
5.2 KiB
Markdown
101 lines
5.2 KiB
Markdown
# 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.
|