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
98 lines
4.7 KiB
Markdown
98 lines
4.7 KiB
Markdown
# Intent: Research-Intent-Verzeichnis ohne Worker-Startfehler bereitstellen
|
|
|
|
## Ziel
|
|
|
|
`board-agent-worker.service` und damit der nach einem Builder-Commit
|
|
eingeplante Reviewer müssen auch dann starten, wenn noch kein echter
|
|
Research-Intent unter `docs/research-intent/` existiert. Die Vorbereitung
|
|
des privaten Codex-Homes darf niemals versuchen, in den durch systemd
|
|
schreibgeschützten Repository-Checkout zu schreiben.
|
|
|
|
## Beobachteter Fehler
|
|
|
|
Der Builder der Karte `research-pipeline-board-datamodel` hat Commit
|
|
`c5dd811` erfolgreich erzeugt. Der anschließend eingeplante Review-Job
|
|
`research-pipeline-board-datamodel-1788795685` blieb jedoch in
|
|
`/var/lib/board-agent/inbox/`, weil `board-agent-worker.service` bereits in
|
|
`ExecStartPre` scheiterte:
|
|
|
|
```text
|
|
install: cannot create directory
|
|
'/home/drone/nixos-config/docs/research-intent': Read-only file system
|
|
```
|
|
|
|
Nach mehreren path-getriggerten Startversuchen erreichte die Unit zusätzlich
|
|
`start-limit-hit`. Der Reviewer-Prozess selbst wurde nicht gestartet.
|
|
|
|
## Belegte Ursache
|
|
|
|
- `researchIntentDir` zeigt auf `${repoDir}/docs/research-intent`.
|
|
- `prepareCodexHome` führt aktuell `install -d` gleichzeitig für die beiden
|
|
privaten Verzeichnisse unter `/var/lib/board-agent/` und für dieses
|
|
Repository-Verzeichnis aus.
|
|
- `board-agent-worker.service` läuft mit `ProtectSystem="strict"`; der
|
|
Checkout ist für die Unit absichtlich nicht schreibbar.
|
|
- Das Verzeichnis `docs/research-intent/` ist im Commit nicht vorhanden.
|
|
Git versioniert leere Verzeichnisse nicht.
|
|
- `trigger.py:list_research_cards()` behandelt ein fehlendes Verzeichnis
|
|
bereits sicher als leere Kartenmenge. Ein Laufzeit-`mkdir` im Worker ist
|
|
daher weder für den Trigger noch für den Reviewer erforderlich.
|
|
|
|
## Umfang / Auftrag an den Builder
|
|
|
|
- `docs/research-intent/` durch einen getrackten, nicht als Research-Intent
|
|
interpretierbaren Platzhalter dauerhaft im Checkout anlegen, zum Beispiel
|
|
`docs/research-intent/.gitkeep`. Kein zusätzliches `*.md`, das durch
|
|
`list_research_cards()` versehentlich als Karte erscheinen könnte.
|
|
- `${researchIntentDir}` aus `prepareCodexHome` entfernen. Dieses Skript darf
|
|
ausschließlich seine privaten Laufzeitverzeichnisse unter
|
|
`/var/lib/board-agent/` vorbereiten und bei Bedarf `auth.json` kopieren.
|
|
- `BOARD_RESEARCH_INTENT_DIR` unverändert auf den Repository-Pfad zeigen
|
|
lassen. Trigger und Worker benötigen dort nur Lesezugriff; spätere
|
|
Research-Intent-Dateien werden durch den normalen Git-/Builder-Workflow
|
|
angelegt.
|
|
- Die bestehende Härtung (`ProtectSystem="strict"`,
|
|
`ProtectHome="read-only"`) beibehalten. Den Fehler ausdrücklich **nicht**
|
|
durch einen pauschalen Schreibpfad für das Repository oder für
|
|
`docs/research-intent/` umgehen.
|
|
- Sicherstellen, dass eine Aktivierung der korrigierten Unit den vorhandenen
|
|
`start-limit-hit` auflöst und der bereits wartende Review-Job anschließend
|
|
genau einmal verarbeitet werden kann. Falls dafür eine deklarative
|
|
systemd-Anpassung nötig ist, diese eng auf die Board-Worker-Unit begrenzen.
|
|
- Den Architekturhinweis in `board-agent/README.md` ergänzen: Corpus-
|
|
Verzeichnisse im Repository sind getrackte Eingaben; `ExecStartPre` erzeugt
|
|
ausschließlich privaten Runtime-State.
|
|
|
|
## Tests
|
|
|
|
- Nix-Auswertung beziehungsweise Unit-Prüfung: `ExecStartPre` enthält keinen
|
|
Schreibzugriff auf `${repoDir}` oder `docs/research-intent`.
|
|
- Das getrackte Platzhalter-Artefakt erzeugt in `GET /api/board` keine
|
|
Research-Karte.
|
|
- Mit leerem `docs/research-intent/` starten
|
|
`board-agent-trigger.service` und ein manueller Testlauf von
|
|
`board-agent-worker.service` unter der bestehenden Sandbox erfolgreich.
|
|
- Ein bereits in `BOARD_INBOX_DIR` liegender Review-Job wird nach der
|
|
Aktivierung genau einmal übernommen; es entsteht weder ein Duplikat noch
|
|
ein Verlust des vorhandenen Queue-Eintrags.
|
|
- Bestehende Board-Agent-Tests bleiben grün.
|
|
|
|
## Ausgeschlossen
|
|
|
|
- Keine Umsetzung des eigentlichen Research-Worker-Dispatchs.
|
|
- Keine Änderung an Codex-/Claude-Modellen oder Runtime-Snapshots.
|
|
- Kein Abschwächen der systemd-Sandbox.
|
|
- Kein Löschen oder manuelles Umschreiben des wartenden Review-Jobs.
|
|
- Keine generische Fehleranzeige im Board; diese folgt in der separaten Karte
|
|
`board-worker-startup-failures-on-card`.
|
|
|
|
## Erfolgskriterien
|
|
|
|
- `board-agent-worker.service` startet ohne Schreibversuch im Repository.
|
|
- Die Worker- und Path-Unit sind nach Aktivierung nicht mehr im Zustand
|
|
`failed` beziehungsweise `start-limit-hit`.
|
|
- Der Review von Commit `c5dd811` kann mit dem unveränderten Queue-Eintrag
|
|
anlaufen.
|
|
- `docs/research-intent/` existiert in einem frischen Checkout, ohne eine
|
|
Phantomkarte im Board zu erzeugen.
|
|
- Die bisherigen Härtungsgrenzen der Unit bleiben vollständig erhalten.
|