nixos-config/docs/review/reviewer-systemaudit-2026-09-01.md

Volltext-Systemaudit: NixOS-Plattform und Agent-/Herdr-Pipeline

Stand: 01.09.2026

Scope und Ausgangszustand

Geprüft wurde der committete Branch dev (HEAD 2d7e13d, identisch zu origin/dev), ohne Vergleich gegen main und ohne offenen PR als Grundlage. Der Scope umfasste tnix, blunix, pinix, globale und lokale Dienste, Flake-/Variablenstruktur sowie die Agent-/Herdr-Pipeline mit Rollendateien, Katalog, Claude-Settings, Self-Close-Wrapper, agents/tests/roles.sh und Eskalations-/Rückfrage-Dokumentation.

Secrets und private Inhalte wurden nicht gelesen oder entschlüsselt. Es wurde nichts aktiviert, deployed, committed, gepusht oder veröffentlicht.

Methode und tatsächlich ausgeführte Prüfungen

• AGENTS.md, agents/reviewer.md und die Auftragsspezifikation vollständig gelesen.
• Relevante Plattform-, Pipeline-, Architektur-, Rollen-, Katalog-, Settings-, Self-Close- und README-Dateien vollständig bzw. anhand aller einschlägigen Abschnitte gelesen und querverglichen.
• git status --short --branch, git log -1 und Dateiinventur ausgeführt.
• bash agents/tests/roles.sh: grün (OK: Rollenkatalog und Sicherheitsgrenzen).
• nix-instantiate --parse auf Flake, Variablen, Host-Konfigurationen, globalen Modulen und lokalen Service-Importlisten: ohne Parsefehler.
• nix flake check --no-build: nicht erfolgreich. Zuerst war der Nix-Fetcher-Cache im Home nicht beschreibbar; mit temporärem Cache war der Daemon-Socket in der Review-Sandbox nicht erreichbar. Das ist kein belegter Flake-Fehler.
• Python-Unittests: nicht ausgeführt, da kein python3/python im PATH verfügbar war.
• Graphify wurde gemäß lokalem Skill in einer temporären git archive-Kopie versucht. Der vollständige Lauf stoppte wegen fehlender Modellkonfiguration; der --code-only-AST-Lauf scheiterte zusätzlich mit Operation not permitted. Vorhandene ignorierte Graphify-Artefakte wurden nur als abgeleitete Navigationshilfe, nicht als Source of Truth, gelesen.

Befunde

widerlegt — Ursprünglich als „high" gemeldetes Kalender-Routing-Problem

Ursprüngliche Behauptung: Die generische externe Route erzeuge einen Router calendar mit Host(cal.${domain}), der mit cal.nixs Router calendar-web (ebenfalls cal.${domain}) um dieselbe öffentliche Anfrage konkurriere.

Korrektur (Orchestrator, nach Gegenprüfung von hosts/blunix/localServices/traefik/routes-external.nix:4-18): Die mkRoute-Hilfsfunktion baut die Traefik-Regel als Host(${name}.${host}). Für den Listeneintrag { name = "calendar"; host = "${config.domain}"; ... } ergibt das Host(calendar.${domain}) — nicht cal.${domain}. Der Router heißt zwar calendar, das ist aber nur der interne Traefik-Router-/Service-Name, nicht der Hostname. Es gibt keine Namenskollision mit cal.nixs calendar-web-Router (Host(cal.${domain})); beide Hostnamen (calendar.${domain} vs. cal.${domain}) sind verschieden und zeigen bewusst auf unterschiedliche Backends (Radicale/CalDAV auf Port 5002 bzw. das Web-Frontend auf Port 5001). Der Befund beruhte auf einer Verwechslung von Router-/Service-Name und tatsächlichem Host()-Hostnamen der Templating-Funktion. Kein Fix nötig.

high — XMPP-TCP-Backend verwendet einen inkonsistenten Key

Fundstelle: hosts/blunix/localServices/traefik/default.nix:81-94.

Beleg: Das Forgejo-TCP-Backend verwendet loadBalancer, das XMPP-Backend jedoch loadbalancer (kleines B). Traefik-Dynamic-Configuration-Keys sind case-sensitive.

Auswirkung: Das XMPP-Backend kann als unbekannt/ungültig verworfen werden; der dokumentierte XMPP-TCP-Passthrough wäre dann nicht belastbar verfügbar.

Empfehlung: Auf loadBalancer vereinheitlichen und eine Evaluierung plus zielgerichtete Traefik-Konfigurations-/Liveprüfung ergänzen. Der Nix-Parsertest allein prüft die semantische Traefik-Struktur nicht.

medium — Netzwerkdokumentation verweist auf nicht existierende Pfade

Fundstelle: docs/networking.md:8-9,28-31,40-42.

Beleg: Dokumentiert werden .../localServices/traefik.nix, traefik-routes-external.nix, traefik-routes-internal.nix und traefik-forgejo.nix. Tatsächlich liegen die Dateien unter .../localServices/traefik/default.nix sowie traefik/routes-{external,internal}.nix und traefik/forgejo.nix.

Auswirkung: Die zentrale Betriebsdokumentation führt bei Diagnose und Änderung zu falschen Fundstellen und schwächt Forkbarkeit/Nachvollziehbarkeit.

Empfehlung: Pfade aktualisieren und einen kleinen Check ergänzen, der referenzierte lokale Pfade auf Existenz prüft.

medium — Self-Close-Rollenliste ist inkonsistent

Fundstelle: agents/researcher.md:65-99, agents/claude-settings/researcher.json, agents/tests/roles.sh:198-266 gegen docs/herdr-orchestration.md:242-245,282-285 und agents/design/herdr-self-close-entwurf.md:11-24.

Beleg: Researcher ist in Settings, Rollenvertrag und Rollentests mit dem Wrapper ausgestattet. Die Orchestrierungsdokumentation nennt dagegen nur fünf Rollen ohne researcher; der Entwurf lässt Researcher ebenfalls aus.

Auswirkung: Orchestrator und Fork-Betreiber erhalten widersprüchliche Angaben über die Self-Close-Fähigkeit. Lebenszyklus- und Eskalationssteuerung werden dadurch unnötig fehleranfällig.

Empfehlung: Eine kanonische Liste festlegen und in Doku, Entwurf und Tests identisch führen. Explizit beibehalten, dass reviewer ausgeschlossen ist.

medium — Planner-E2E-Status widerspricht Vertrag und Testharness

Fundstelle: docs/herdr-orchestration.md:306-317,319-323 gegen agents/planner.md:108-113 und agents/tests/roles.sh:264-266.

Beleg: Die Orchestrierungsdokumentation erklärt den Claude-Self-Close- Nachtest für Planner als erfolgreich und nennt nur die vier anderen Rollen als noch ungetestet. planner.md behauptet weiterhin, der Test stehe aus; der statische Test verlangt diese veraltete Formulierung für alle Self-Close-Rollen.

Auswirkung: Vertrag, Evidenz und Regressionstest bewerten denselben Zustand unterschiedlich. Die Testabdeckung wird nicht wahrheitsgetreu ausgewiesen.

Empfehlung: Planner-Vertrag und roles.sh an den dokumentierten Nachtest anpassen und den offenen E2E-Status nur für Administrator, Agent-Manager, Grafiker und Orga führen (oder die Erfolgsbehauptung zurücknehmen).

medium — Vollständige sichtbare Rollen fehlen in den Übersichten

Fundstelle: docs/herdr-orchestration.md:158-170 und docs/pipelines.md:37,64-72; Vergleich: agents/catalog.json.

Beleg: Der Katalog führt aktive Rollen reviewer und researcher; die Übersicht nennt sie nicht. docs/pipelines.md spricht von „alle vier Rollenverträge“ und nennt nur Administrator, Orga, Agent-Manager und Graphics, obwohl Planner, Researcher und Reviewer aktiv katalogisiert sind.

Auswirkung: Die Ablaufbeschreibung ist kein vollständiges Modell des aktuellen Systems. Review-, Bericht- und Intent-Pflichten können bei Weiterpflege übersehen werden.

Empfehlung: Übersicht und Pipeline vollständig aus dem Katalog ableiten oder klar als Teilansicht kennzeichnen; Reviewer, Researcher und Planner ergänzen und „vier Rollenverträge“ präzisieren.

Unsicherheiten und offene Prüfungen

• Die Traefik-Befunde sind statisch abgeleitet; vollständige Flake-Evaluierung und generierte Traefik-Prüfung waren wegen fehlendem Nix-Daemonzugriff nicht möglich.
• Python-Tests, NixOS-Builds, nixos-rebuild test/dry-activate und Live-Dienstprüfungen wurden nicht ausgeführt. Es lag keine Aktivierungs- oder Deploymentfreigabe vor.
• Sicherheitsbefunde waren nicht Schwerpunkt; offensichtliche Nebenbefunde wurden nur im Zusammenhang mit Routing oder Rollenverträgen berücksichtigt.

Fazit

Die statischen Rollengrenzen und Nix-Syntax sind nachvollziehbar, und die Rollentests laufen grün. Der Stand ist jedoch nicht vollständig konsistent dokumentiert; zusätzlich besteht ein bestätigter funktionaler Traefik-Fehler (XMPP-Backend-Key) mit Auswirkung auf die XMPP-Erreichbarkeit. Der ursprünglich als zweiter high-Befund gemeldete Kalender-Routing-Konflikt wurde bei Gegenprüfung widerlegt (siehe Korrektur oben) — kein Fix nötig. Vor einer Aktivierungsfreigabe sollte der verbleibende high-Befund (XMPP-Backend-Key) durch eine zielgerichtete Konfigurations-/Liveprüfung geklärt werden. Die Dokumentations- und Self-Close-Widersprüche sollten anschließend in einem separaten kleinen Fix bereinigt werden.

Keine Aktivierungs-, Deployment- oder Veröffentlichungsfreigabe erteilt.