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-intent-detail-and-transition-guardrails.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.5 KiB
Raw Permalink Blame History

Intent: Intent-Detail-Modal und Übergangs-Guardrails im Board

Ziel

Zwei zusammengehörige Verbesserungen am Board-Web-UI (hosts/blunix/localServices/board-agent/):

  1. Der Intent-Inhalt einer Karte (docs/intent/<slug>.md) soll beim Kartenklick lesbar sein, unabhängig davon, in welcher Spalte die Karte gerade steht.
  2. Vorwärts-Übergänge zwischen Spalten, die eine oder mehrere Pipeline-Stufen überspringen, sollen serverseitig abgelehnt werden statt unkommentiert durchzugehen.

Umfang / Auftrag an den Builder

  • In trigger.py: einen neuen Endpoint GET /api/board/cards/<id>/intent ergänzen, analog zum bestehenden Review-Endpoint (GET /api/board/cards/<id>/review). Er liest den Inhalt der Datei unter dem intent_path der Karte und liefert ihn als Text/Markdown zurück. 404, wenn die Karte keinen intent_path hat oder die Datei fehlt.
  • In board.html: einen Klick-Handler für jede Karte mit source === "intent" ergänzen (aktuell bekommen nur has-review-Karten einen Handler). Der Klick öffnet ein eigenes <dialog>-Modal, das den Inhalt von GET .../intent in einem <pre>-Block anzeigt — analog zum bestehenden showReview()-Mechanismus, aber ein eigenständiges Modal. Keine Vermischung mit dem Review-Dialog; der bleibt unverändert und zeigt weiterhin ausschließlich den Review-Inhalt.
  • In trigger.py's PATCH /api/board/cards/<id>-Handler: die erlaubte Vorwärtsfolge der Spalten ist idea → geplant → in_umsetzung → review → {bereit_fuer_deployment | planung_mit_feedback} → deployed. Ein Vorwärts-Sprung, der eine oder mehrere Stufen dieser Folge überspringt (z. B. geplant → deployed direkt), wird mit HTTP 409 abgelehnt — gleiches Muster wie der bereits bestehende geplant → in_umsetzung-Doppel-Trigger-Guard. Rückwärts-Bewegungen (in dieser Folge nach hinten, in beliebigem Abstand) bleiben uneingeschränkt erlaubt, ohne Guard. bereit_fuer_deployment → deployed und planung_mit_feedback → geplant bleiben wie bisher reine Buchhaltung ohne Seiteneffekt (kein Auto-Deploy, kein Auto-Re-Enqueue).
  • test_board_agent.py: Tests für den neuen Endpoint sowie für die neuen Guard-Fälle ergänzen (mindestens: ein erlaubter Vorwärtsschritt, ein abgelehnter übersprungener Vorwärtsschritt, ein erlaubter Rückwärtsschritt).

Ausgeschlossen

  • Kein gemeinsames Modal für Intent- und Review-Inhalt, kein Tab-Umbau des bestehenden Review-Dialogs.
  • Kein Markdown-Rendering zu HTML — reiner <pre>-Text wie beim bestehenden Review-Dialog.
  • Kein automatisches Re-Enqueue eines Builder-Jobs beim Rework-Loop; planung_mit_feedback → geplant → in_umsetzung bleibt zwei manuelle Schritte.
  • Kein Auto-Deploy-Trigger bei → deployed.
  • Keine Einführung von docs/board/<slug>.yaml — State bleibt in BOARD_STATE_FILE/state.json, wie im bestehenden Phase-1-Scope festgelegt.

Annahmen

  • Die erlaubte Vorwärtsfolge ist eindeutig aus der bestehenden COLUMNS- Reihenfolge in board.html ableitbar.
  • bereit_fuer_deployment und planung_mit_feedback gelten beide gleichermaßen als gültige Nachfolger von review und als gültige Vorgänger von deployed (nur bereit_fuer_deployment führt praktisch weiter zu deployed, planung_mit_feedback führt zurück).
  • Rückwärts-Bewegungen brauchen keinen Guard, weil sie schon heute uneingeschränkt funktionieren und keine Seiteneffekte auslösen.

Offene Risiken

  • Die Guard-Logik ist eine hartcodierte Reihenfolge, kein generisches State-Machine-Konfigurationsobjekt. Kommen künftig weitere Spalten/Phasen hinzu, muss diese Logik von Hand mitgepflegt werden — bewusster Trade-off gegen eine generischere, aber für den aktuellen Umfang überdimensionierte Lösung.

Erfolgskriterien

  • Klick auf eine beliebige Intent-Karte, in jeder Spalte, öffnet ein Modal mit dem aktuellen Inhalt ihrer docs/intent/<slug>.md.
  • Ein Drag, der eine Pipeline-Stufe überspringt, wird mit 409 abgelehnt, die Karte bleibt in ihrer bisherigen Spalte.
  • Bestehende und neue Tests in test_board_agent.py sind grün.
  • Dieser Intent dient zugleich als Pipeline-Test: Nach dem Schreiben dieser Datei wird die Karte manuell durch geplant → in_umsetzung gezogen, um den bestehenden, durch diese Änderung unberührten Builder-Übergang end-to-end zu validieren. Diese Karte wird als erste von drei zusammengehörigen Karten (siehe docs/intent/planner-precise-package-removal-scope.md und docs/intent/reviewer-scale-depth-to-risk.md) durch die Pipeline gezogen.