management/FRAMEWORK-BEFUNDE.md

Framework-Befunde

Wofür diese Datei da ist: Stellen, an denen das Verfahren nicht getragen hat — weil ihm etwas fehlt, weil niemand widersprochen hat, oder weil derselbe Fehler wiederkam. Sie ist die Eingangsliste für die Framework-Ernte: Was hier steht, soll in der nächsten neckbeard-Iteration nicht erneut passieren müssen.

Was hierher gehört: wiederkehrende Fehlerklassen, Abweichungen vom Verfahren, Regeln, die sich ohne Werkzeug nicht durchsetzen, und Prüfungen, die etwas melden, das niemand beheben kann.

Was nicht: normale Issues (die gehören nach docs/issues/) und einzelne Vorfälle (die gehören als AAR nach docs/aar/). Hier steht, was aus mehreren davon als Muster hervorgeht.

Pflege: Ein Befund wird geerntet, wenn die nächste Iteration ihn abdeckt — nicht schon, wenn er einmal behoben wurde. Das Refinement geht die offenen durch.

Wie eine Ernte hier herausgeht: verallgemeinert zu Fehlerklasse, Wirkung und Ursache — nie mit unseren Namen, Hosts, Stack-Komponenten oder Kennungen. Das ist die bindende Regel des Frameworks (ADR-0008 dort), und sie hat einen Grund: Am 2026-08-13 sind unsere Namen und eine offene Schutzlücke bereits in einen gepushten Commit geraten; dass sie nicht weiterwanderten, lag an einem abgelaufenen Token, nicht an einer Vorkehrung. Die Gegenprobe dazu ist scripts/harvest-terms.txt — unsere Liste, die das Framework bewusst nicht kennt. ⚠️ Ein grüner Lauf ist kein Beweis der Abwesenheit: Eine Sperrliste findet nur, woran jemand gedacht hat.

Stand der Ernte

Am 2026-08-20 sind alle elf Befunde übergeben worden — anonymisiert, als neun Issues der nächsten Framework-Iteration, samt einem Übergabe-Dokument und der Regel, nach der künftige Ernten zu erfolgen haben. Zwei Paare fielen zusammen, weil ihre Abhilfe dieselbe ist; die vollständige Zuordnung steht im Übergabe-Dokument.

⚠️ Sie bleiben hier trotzdem offen. Übergeben ist nicht geerntet: Nach der Regel oben zählt ein Befund erst, wenn die nächste Iteration ihn tatsächlich abdeckt. Das Refinement prüft das gegen die Dispositionen, die jedes Issue trägt.

Übersicht

#	Befund	Klasse	Stand
FB-01	Die AAR-Pflicht setzt sich ohne Werkzeug nicht durch	Durchsetzung	offen
FB-02	„Meldet Erfolg, ist aber blind" — sieben Vorkommen in fünf Werkzeugen	Fehlerklasse	offen
FB-03	Prüfungen erzeugen Befunde, die niemand beheben kann	Verfahrenslücke	teilweise
FB-04	Issues behaupten Zustände, die längst überholt sind	Verfahrenslücke	offen
FB-05	Dashboards und Prüfungen ohne Datenbeleg	Fehlerklasse	offen
FB-06	Dokumente werden ergänzt, aber nicht revidiert	Fehlerklasse	offen
FB-07	Werkzeuge messen unbemerkt die falsche Instanz	Fehlerklasse	offen
FB-08	Dokumente werden angelesen, nicht durchgelesen	Arbeitsweise	offen
FB-09	Gelesene Anweisungen werden nicht befolgt	Arbeitsweise	offen
FB-10	Gesperrte Dateien werden bearbeitet	Arbeitsweise	Werkzeug steht
FB-11	Regeln ohne maschinellen Widerspruch werden nicht befolgt	Durchsetzung	offen

---

FB-01 — Die AAR-Pflicht setzt sich ohne Werkzeug nicht durch

Beschreibung. roadmap.md verlangt einen AAR nach jedem Deploy mit Übergabe und nach Incidents. Zwischen dem 17. und 20.08.2026 gab es sechs solche Ereignisse. Geschrieben wurde zunächst keiner; alle sechs entstanden nachträglich auf Nachfrage von sorb.

Ursachen-Einschätzung. Nicht Nachlässigkeit, sondern eine strukturelle Asymmetrie: Im selben Zeitraum wurde kein einziges Mal vergessen, was ein Werkzeug prüft — Frontmatter (validate.py), STATUS.md (gen_status --check), Spiegel (spiegel_issues.py), Commit-Konvention (gruppenpruefung.py). Der Unterschied ist, wer widerspricht. Der AAR-Pflicht widerspricht niemand.

Verschärfend war: Die Regel stand nur in roadmap.md, nicht in AGENTS.md — und auf AGENTS.md verweist jedes CLAUDE.md. Wer nur der Zeigerkette folgte, fand die Pflicht nicht.

Teilweise behoben 2026-08-20 (Entscheidung sorb): AGENTS.md trägt im Projektabschnitt jetzt den Abschnitt „Nach Deploys und Vorfällen" mit der AAR-Pflicht und dem Verweis auf diese Datei. ⚠️ Das schließt die Wissenslücke, nicht die Durchsetzungslücke — kein Werkzeug erzwingt die Pflicht, und genau das steht dort auch ausdrücklich.

Belege. docs/issues/0040-* (Rückmeldung), sechs AARs vom 17.–20.08.

Vorschlag für die nächste Iteration. Entweder eine Prüfung, die geschlossene Vorfälle und Deploy-Übergaben ohne zugehörigen AAR meldet — dafür bräuchte es ein maschinell lesbares Merkmal „war ein Vorfall" am Issue. Oder die ehrliche Alternative: Wenn eine Regel dauerhaft nur auf Nachfrage befolgt wird, ist zu prüfen, ob die Schwelle stimmt. Sechs AARs in vier Tagen sind viel.

➡️ Die hier vermutete Asymmetrie ist am 2026-08-20 über den gesamten Regelsatz nachgemessen worden und hat sich bestätigt: FB-11. Dieser Befund bleibt als Einzelfall gültig; FB-11 trägt die Regelmäßigkeit.

---

FB-02 — „Meldet Erfolg, ist aber blind"

Beschreibung. Ein Schritt läuft durch, meldet Erfolg und hat nichts getan. Sieben belegte Vorkommen in fünf verschiedenen Werkzeugen — ausführlich in docs/wiki/stolpersteine/meldet-erfolg-ist-aber-blind.md.

Ursachen-Einschätzung. Das Verfahren verlangt verifizierbare Abnahmekriterien, aber nichts verlangt, dass eine selbstgebaute Prüfung einmal absichtlich rot war. Ein Tor, das nur grün gesehen wurde, ist eine Vermutung — genau so entstanden vier der sieben Vorkommen.

Zweiter Anteil: Das Muster war seit dem 2026-08-18 als solches erkannt („viertes Vorkommen" in #0054) und stand trotzdem nur in einem Issue. Es lag nicht dort, wo AGENTS.md die Lehren sucht — und wurde deshalb dreimal neu entdeckt.

Vorschlag. Positivkontrolle als Pflichtbestandteil jeder neuen Prüfung: Wer ein Tor baut, weist nach, dass es mit eingebautem Fehler rot ist. Denkbar als Gate im Design-Doc oder als Zeile in der Abnahme.

---

FB-03 — Prüfungen erzeugen Befunde, die niemand beheben kann

Beschreibung. Am 2026-08-18 waren alle geplanten Prüfungen dauerhaft rot (25 Befunde), womit keine mehr etwas meldete. Behoben über den Quittungsmechanismus (ADR-0020). Zwei Tage später kam dieselbe Klasse zurück: Der Upstream-Merge brachte 70.265 fremde Commits, welche die Git-Hygiene-Prüfung bemängelte — Commits, die unserer Konvention nie folgen konnten (ADR-0023).

Ursachen-Einschätzung. Beim Bau einer Prüfung wird gefragt, was sie finden soll, nicht, welche Befunde sie erzeugen wird, die niemand beheben kann. Der Quittungsmechanismus behandelt das Symptom gut (mit Pflichtfrist), verhindert aber nicht, dass die nächste Prüfung dieselbe Lage erzeugt.

Vorschlag. Bei jeder neuen Prüfung im Voraus beantworten: Welche Befunde wird sie erzeugen, die strukturell nicht behebbar sind? Wenn es welche gibt, gehört die Ausnahme in dieselbe Änderung — nicht in eine spätere Aufräumrunde.

---

FB-04 — Issues behaupten Zustände, die längst überholt sind

Beschreibung. Mehrfach an einem Tag: #0083 nannte drei Dateien als Einzeldatei- Mounts, die längst Verzeichnis-Mounts waren. #0088 nannte Zahlen („13 Ingress-Regeln, ein Egress-Vorkommen"), die nicht mehr stimmten. #0002 führte die Firewall als Ursache, die es nie war. #0030 trägt im Titel „Der Restore ist nie geprobt", obwohl der Datenbank-Restore geprobt und überwacht ist.

Ursachen-Einschätzung. Issues sind append-only — richtig so, git ist die Historie. Aber Kopf und Titel bleiben stehen, während die Anhänge sie widerlegen. Wer ein Issue öffnet, liest zuerst die veraltete Fassung. Es gibt keine Pflicht, einen widerlegten Befund im Kopf zu markieren.

Praktische Folge, mehrfach beobachtet: Arbeit wird auf einer Prämisse begonnen, die inzwischen falsch ist — und muss nach dem Nachmessen umgeplant werden.

Vorschlag. Ein leichtgewichtiges Mittel, etwa eine ⚠️ überholt-Zeile direkt unter dem Titel, sobald ein Anhang die Ausgangsdiagnose widerlegt. Oder ein Feld letzte_messung, das sichtbar altert.

---

FB-05 — Dashboards und Prüfungen ohne Datenbeleg

Beschreibung. dashboards/gameserver/pterodactyl-server.json war drei Monate dauerhaft leer — es fragte Metriken eines Exporters ab, der nie funktioniert hat. Niemandem ist es aufgefallen. Dasselbe Muster beim ClamAV-Dashboard: Der Vorschlag im Issue nutzte ein Label, das in dieser Loki gar nicht existiert.

Ursachen-Einschätzung. Ein Dashboard gilt als fertig, wenn es angelegt ist. Es gibt keine Abnahme „liefert Daten". Ein leeres Panel sieht aus wie „gerade nichts los" und ist von „fragt Unsinn ab" nicht zu unterscheiden.

Vorschlag. Abnahmekriterium für jedes neue Dashboard: Jede Query wurde gegen die laufende Instanz geprüft und hat Daten geliefert — oder es steht dabei, warum sie berechtigt leer ist.

---

FB-06 — Dokumente werden ergänzt, aber nicht revidiert

Beschreibung. docs/axion1337-fork.md beschrieb nach dem Upstream-Merge weiterhin ein Repo ohne gemeinsamen Vorfahren. dns-soll.md nannte einen Absender, der so nie versandte. monitoring/README.md beschrieb Targets als „antworten aktuell nicht", ohne den Grund und nach der Umstellung mit falscher Adresse.

Ursachen-Einschätzung. Anhängen ist billig und fühlt sich vollständig an; das Widerlegen einer früheren Aussage kostet Mut und Aufmerksamkeit. Beim Abschluss einer Arbeit wird gefragt „ist es dokumentiert?", nicht „welche bestehende Aussage ist dadurch falsch geworden?".

Vorschlag. Beim Abschluss einer Arbeit ausdrücklich die Gegenfrage stellen und die Antwort in der Abnahme festhalten — auch wenn sie „keine" lautet.

---

FB-07 — Werkzeuge messen unbemerkt die falsche Instanz

Beschreibung. Über den Entwicklungstunnel zeigen cfgmon.lab:9090 und :3100 auf einen anderen Stack (host=dokploy-host); der operating-Stack ist nur aus dem matrix-Cluster über 10.0.0.3 erreichbar. Zusätzlich wird im Lab Port 53 abgefangen — eine dig-Anfrage an eine TEST-NET-Adresse liefert ein Ergebnis. Beides hat an einem Tag je zwei Diagnosen ins Leere laufen lassen.

Ursachen-Einschätzung. Die Umgebung beantwortet Fragen, die sie nicht beantworten kann, statt zu schweigen. Ein Werkzeug, das eine Adresse anspricht, kann nicht erkennen, dass jemand dazwischen sitzt. Dokumentiert war das teilweise (reference: Diagnose-Fallen) — aber nicht dort, wo die Werkzeuge laufen.

Vorschlag. Gegenprobe als Standardbestandteil von Diagnose-Skripten, vor der eigentlichen Messung. pruefe-dns.sh macht das seit dem 2026-08-20 vor; pruefe-ports.sh seit dem 2026-08-19. Das Muster gehört in die Werkzeug-Vorlage, nicht in jedes Skript neu.

---

FB-08 — Dokumente werden angelesen, nicht durchgelesen

Beschreibung. roadmap.md wurde am 2026-08-20 vollständig ausgegeben — alle 94 Zeilen — um den Aufbau für eine Ergänzung zu verstehen. Die AAR-Pflicht steht dort in Zeile 94 und war seit dem 2026-08-12 unverändert vorhanden. Sie wurde nicht gesehen. Anschließend wurde dieselbe Datei bearbeitet, ohne dass die Regel auffiel — und sechsmal verletzt.

Dasselbe Muster mehrfach am selben Tag: Der Kommentar in der .npmrc sagt den 404-Fehlschlag wörtlich voraus; gelesen wurde er nach dem Fehlschlag. Der Kommentar in docker-compose.yml erklärt, dass der Verzeichnis-Mount die Inode-Falle bereits beseitigt; trotzdem wurde --force-recreate in zwei Übergaben weitergetragen.

Ursachen-Einschätzung. Dokumente werden als Nachschlagewerk für die gerade anstehende Frage behandelt, nicht als bindender Rahmen, den man vor dem Handeln verinnerlicht. Gelesen wird, um zu finden — nicht, um sich zu binden. Deshalb bleibt eine Regel unsichtbar, die drei Zeilen unter der bearbeiteten Stelle steht.

Vorschlag. Vor einer Änderung an einer Datei: deren eigenen Kopf und die Regeln zu ihrer Gattung vollständig lesen und im Arbeitsergebnis benennen, welche davon einschlägig waren. Das kostet Zeilen und spart Wiederholungen.

FB-09 — Gelesene Anweisungen werden nicht befolgt

Beschreibung. AGENTS.md Zeile 81: „docs/adr/ — binding; never edited, only superseded." Die Datei war gelesen. Trotzdem wurde ADR-0022 um einen Nachtrag ergänzt, committet und gepusht.

Ursachen-Einschätzung. Zwischen „gelesen" und „angewandt" fehlt der Schritt, in dem die eigene geplante Handlung gegen die Regel gehalten wird. Die Regel war bekannt; die Frage „darf ich das?" wurde vor der Handlung nicht gestellt, sondern erst, als zufällig die Vorlage geöffnet wurde.

⚠️ Diese Klasse ist gefährlicher als FB-08: Bei FB-08 fehlt Wissen, hier ist es vorhanden und wird nicht abgerufen. Kein Werkzeug kann das auffangen, das nicht die Absicht kennt.

Vorschlag. Für die kleine Zahl harter Verbote (ADRs nicht editieren, nicht nach Gitea pushen, docs/sources/ unveränderlich, STATUS.md nicht von Hand) eine Prüfung, die den Verstoß im Commit findet statt im Nachhinein — etwa ein pre-commit-Hook oder eine CI-Regel, die geänderte Pfade gegen eine Sperrliste hält.

FB-10 — Gesperrte Dateien werden bearbeitet

Beschreibung. Commit 6652125 veränderte die angenommene ADR-0022. Der Verstoß wurde gepusht und erst mit 6731d2a zurückgenommen — nicht durch eine Prüfung, sondern durch Zufall.

Ursachen-Einschätzung. Es gibt keine technische Sperre. validate.py prüft Schema und Verweise, nicht Bearbeitbarkeit. Der Schutz einer bindenden Entscheidung besteht heute ausschließlich aus einem Satz in einer Kommentarzeile der Vorlage und einer Zeile in AGENTS.md.

Zum Vergleich: STATUS.md trägt dieselbe Art Verbot („nicht von Hand ändern") — und wurde kein einziges Mal verletzt, weil gen_status.py --check widerspricht. Derselbe Befund wie FB-01, an anderem Gegenstand.

Umgesetzt 2026-08-20. scripts/pruefe_sperrliste.py, im validate-Job bei jedem Push. Gesperrt sind docs/sources/** und jede ADR, die vor dem Push status: accepted trug; erlaubt bleibt genau die von der Vorlage vorgeschriebene Änderung — superseded_by und status setzen, wenn eine neue ADR ablöst.

Beide Sperren mit Positivkontrolle belegt, nicht nur gebaut:

Fall	Ergebnis
Commit 6652125 (mein realer Verstoß an ADR-0022)	rot, 23 beanstandete Zeilen
Wegwerf-Commit an docs/sources/…/AGENTS.md	rot
sauberer Commit	grün
ungültiger Vergleichsbereich	rot — „ungeprüft ist nicht bestanden"

⚠️ Beim Bau ist mir dieselbe Klasse prompt wieder unterlaufen: Der erste git-Helfer verwandelte einen Fehlschlag in einen leeren String — ein ungültiger Bereich wurde damit zu „keine Änderungen" und bestand stillschweigend. Aufgefallen nur, weil der Test gegen den Wurzel-Commit des Repos lief, der keinen Vorgänger hat. Das ist FB-02 im Werkzeug gegen FB-10; der Fall steht als vierte Zeile in der Tabelle oben, weil er jetzt geprüft wird.

Nicht abgedeckt: generierte Dateien. STATUS.md bleibt durch gen_status --check geschützt, andere Generate haben heute keine Entsprechung.

FB-11 — Regeln ohne maschinellen Widerspruch werden nicht befolgt

Anlass. sorb fragte am 2026-08-20: „was ist eigentlich mit ponytail? das sollte ja auch eigentlich im framework stehen und dir vorgegeben sein. es scheint nicht verwendet zu werden." Die Frage traf zu. Beim Nachmessen zeigte sich, dass ponytail nur der Punkt ist, an dem das Muster sichtbar wurde.

Was ponytail ist. Die Entscheidungsleiter in AGENTS.md §1, Zeile 26–29:

Before writing new code, stop at the first rung that holds: needed at all? → codebase already has it? → stdlib? → platform-native? → installed dependency? → one line? → only then: the minimum that works. (Ladder after ponytail, MIT.)

Sie steht in AGENTS.md und byte-gleich in der Baseline docs/sources/upstream/neckbeard-v0.1.1/AGENTS.md — also in der Datei, die in jede Session geladen wird. In den Sitzungen vom 17.–20.08.2026 wurde sie kein einziges Mal genannt und an keiner Stelle nachweislich bestiegen.

Die Messung. AGENTS.md §1/§3 zerfällt in zwei Sorten Regeln, und die Befolgung folgt nicht der Regel, sondern dem Werkzeug:

Regel	Widerspruch im Werkzeug	Befolgung
Frontmatter nach schema.yaml	validate.py	nie verletzt
STATUS.md nicht von Hand	gen_status.py --check	nie verletzt
Baseline byte-treu	pruefe_upstream_drift.py	nie verletzt
WIP-Limit 2, ein Meilenstein je Issue	validate.py / schema.yaml	nie verletzt
Tote Verweise, SHA-Zitate	pruefe_prosa.py	nie verletzt
Commit-Konvention, Identitäten	gruppenpruefung.py	nie verletzt
ponytail-Leiter (§1)	keiner	nie angewandt
Schlussstatus DONE/DONE_WITH_CONCERNS/NEEDS_CONTEXT/BLOCKED (§1)	keiner	nie benutzt
Größenklasse S/M/L am Aufgabenbeginn (§3)	keiner	nie vorgeschlagen
„Every changed line must trace directly to the request" (§3)	keiner	verletzt (Rüge sorb, 20.08.)
Angenommene ADRs nie editieren	keiner → seit 20.08. pruefe_sperrliste.py	verletzt (FB-09/FB-10)
AAR-Pflicht	keiner	6× verletzt (FB-01)

Belege für die drei „nie"-Zeilen.

• Die vier Pflicht-Status kommen im ganzen Repo ausschließlich in den Regeldateien selbst vor (AGENTS.md, WORKFLOW.md, docs/design/template.md) und in deren Baseline-Kopien — in keinem einzigen Arbeitsergebnis.
• Größenklassen: dasselbe Bild, nur Regeltext (AGENTS.md §3, WORKFLOW.md, README.md).
• WORKFLOW.md verlangt für L („new feature, multiple files or sessions, real decisions") ein Design-Dokument mit Gates 1–5. In docs/design/ liegt genau eines, vom 2026-08-11 — die neckbeard-Migration selbst. Seither ohne Design-Dokument gelaufen: der Upstream-Merge mit 70.265 Commits, Release v0.6.0, das typecheck-Tor, die Egress-Sperre über zehn Workloads, die Game-Host-Anbindung. PROJECT.md gewährt nur die S-Ausnahme; „M und L stoppen immer" steht dort wörtlich.

Ursachen-Einschätzung. Ausnahmslos jede Regel mit maschinellem Widerspruch wurde eingehalten. Ausnahmslos jede Regel ohne einen wurde gebrochen oder ignoriert. Das ist keine Sammlung von Einzelnachlässigkeiten, sondern ein Gefälle, dem die Arbeitsweise folgt. FB-01 hat den Mechanismus an einem Gegenstand vermutet; neu ist hier, dass er über den gesamten Regelsatz gilt — und dass er auch dort greift, wo Wissen und Absicht vorhanden sind (FB-09).

Er erklärt zugleich, warum FB-10 funktioniert hat: nicht weil die Regel neu formuliert wurde, sondern weil ihr seit dem 20.08. ein Skript widerspricht.

⚠️ Der strukturelle Zusatz — und der eigentliche Grund, warum das hierher gehört: Die unbewachten Regeln stehen sämtlich in §1–§5, dem byte-treuen Baseline-Teil. Dieses Projekt kann dort keine Durchsetzung nachrüsten, ohne pruefe_upstream_drift.py zu brechen. Was hier fehlt, kann das Projekt nicht selbst beheben — es muss aus der nächsten neckbeard-Iteration kommen.

Warum hier kein Skript vorgeschlagen wird. Die Leiter auf sich selbst angewandt, erste Sprosse „needed at all?": Die gebrochenen Regeln sind Urteilsregeln („ist das die einfachste Lösung?", „welche Größenklasse?"). Ein Skript kann Urteil nicht prüfen, nur Rituale zählen — und eine Prüfung, die Rituale zählt, erzeugt Befunde, die niemand beheben kann (FB-03).

Vorschlag für die nächste Iteration. Zwei Ansätze, die ohne Urteilsprüfung auskommen, beide berühren AGENTS.md/WORKFLOW.md und damit die Baseline — Entscheidung sorb im Refinement:

1. Größenklasse als Artefakt statt als Ansage. Wenn die Klasse irgendwo im Frontmatter landet, kann validate.py für L das Design-Dokument einfordern. Heute ist sie ein Satz im Chat und damit spurlos.
2. Die Schwelle prüfen statt die Disziplin. Wenn Gates über Monate nur auf Nachfrage durchlaufen werden, ist die zweite Erklärung, dass sie für diesen Betrieb zu eng geschnitten sind. Das ist ausdrücklich keine Entlastung — aber es zu messen ist ehrlicher, als die Regel ein weiteres Mal zu wiederholen.

Entschieden am 2026-08-20 (sorb): Größenklasse und Schlussstatus werden ab sofort mitgeführt — die Verhaltensseite ist damit geklärt. ⚠️ Der Befund bleibt trotzdem offen: Die Durchsetzungslücke besteht unverändert, denn genau das war schon vorher die Regel. Was sich geändert hat, ist die Aufmerksamkeit, nicht der Mechanismus — und FB-01 zeigt, wie lange das trägt.

Was nicht hilft: die Regel nochmals irgendwohin schreiben. Sie steht bereits an zwei Stellen, und beide wurden gelesen — siehe „Meldet Erfolg, ist aber blind" für die verwandte Klasse und FB-08.

---

Angelegt 2026-08-20 auf Wunsch von sorb, nach einer Sitzung, in der mehrere dieser Befunde gleichzeitig sichtbar wurden. Erstbefüllung stammt von der Seite, die die Abweichungen verursacht hat — das ist kein Argument gegen die Befunde, aber ein Grund, sie im Refinement gegenzulesen.