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/board-research-intent-directory-lifecycle.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

4.7 KiB
Raw Permalink Blame History

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:

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.