From 8e653082b63e053d50e228e88c71e227a743fdc2 Mon Sep 17 00:00:00 2001 From: Thore Cimbal Date: Tue, 18 Aug 2026 12:00:00 +0000 Subject: [PATCH] docs(adr): ADR-0020 for the acknowledgement mechanism The framework audit found this missing. Acknowledging known findings is a process decision about how the alarm system treats exceptions, and AGENTS.md is explicit that documenting an exception instead of deciding it is itself the error. It lived only inside #0104 and #0105, which are issues, not decision records. The ADR carries the reasoning the issues could not: why option C beat working the backlog down first or tolerating red, and why the obvious objection - an exception list is a candidate for the next blind spot - is answered by the three rules rather than waved away. It also records what is deliberately not acknowledged, the transient mirror divergence, because that message is the only signal if a mirror truly stops. One consequence is stated plainly rather than discovered later: acknowledgements bind to substrings of the finding text, so fixing or moving a cause can change the wording and require the entry to follow. Stable finding IDs would avoid that and would make the file unreadable without special knowledge; the trade is taken knowingly. Co-Authored-By: Claude Opus 5 --- STATUS.md | 3 +- docs/adr/0020-bekannte-befunde-quittieren.md | 89 +++++++++++++++++++ .../0104-daueralarme-melden-nichts-mehr.md | 1 + 3 files changed, 92 insertions(+), 1 deletion(-) create mode 100644 docs/adr/0020-bekannte-befunde-quittieren.md diff --git a/STATUS.md b/STATUS.md index 5758529..5b894d6 100644 --- a/STATUS.md +++ b/STATUS.md @@ -78,7 +78,7 @@ Verteilung: M1 18 · M2 17 · M3 4 · M4 11 · M5 15 _none active_ -## ADRs (19) +## ADRs (20) | ADR | Status | Title | |---|---|---| @@ -101,6 +101,7 @@ _none active_ | [0017](docs/adr/0017-split-dns-cfgmon-vier-zonen.md) | accepted | 0017 — Split-DNS auf CFGMON: vier Zonen statt einer, je Zone begründet | | [0018](docs/adr/0018-ki-geraeuschunterdrueckung-clientseitig-opt-in.md) | accepted | 0018 — KI-Geräuschunterdrückung in threadnet-call: client-seitig, opt-in, selbst ausgeliefert | | [0019](docs/adr/0019-komponenten-issues-adoptiert.md) | accepted | ADR-0019: Komponenten-Issues in docs/issues/ adoptiert — eine Nummernwelt für die Gruppe | +| [0020](docs/adr/0020-bekannte-befunde-quittieren.md) | accepted | ADR-0020: Bekannte Befunde werden quittiert, damit Rot wieder etwas bedeutet | ## Open AARs (0) diff --git a/docs/adr/0020-bekannte-befunde-quittieren.md b/docs/adr/0020-bekannte-befunde-quittieren.md new file mode 100644 index 0000000..a66aebc --- /dev/null +++ b/docs/adr/0020-bekannte-befunde-quittieren.md @@ -0,0 +1,89 @@ +--- +type: adr +id: "0020" +status: accepted +date: 2026-08-18 +supersedes: null +superseded_by: null +related: + - "docs/issues/0104-daueralarme-melden-nichts-mehr.md" + - "docs/adr/0013-gruppenregeln-kanonisch-mit-pruefung.md" +--- + +# ADR-0020: Bekannte Befunde werden quittiert, damit Rot wieder etwas bedeutet + +## Kontext + +Das Alarmprinzip der Gruppe steht in AGENTS.md: *„Seine rote Pipeline **ist** der +Alarm — es gibt bewusst keinen zweiten Meldeweg."* Am 2026-08-18 zeigte die +Messung, dass **alle drei** geplanten Prüfungen dauerhaft rot standen: +`gruppenpruefung` mit 20 Befunden (17 davon von sorb bewusst vertagt, #0053), +`stillstandspruefung` mit fehlendem `GITEA_TOKEN`, und `canonize_rotation` seit +neun Tagen an einem liegengebliebenen Rotationszweig. + +Der `canonize`-Fall ist der Beleg, nicht die Anekdote: Neun Tage lang scheiterte +der Job an einem Konflikt, der `coturn-secret.yaml`, `synapse-turn-secret.yaml` +und `element-server-suite.yaml` betraf — und niemand bemerkte es, weil ein rotes +Kreuz mehr zwischen roten Kreuzen unsichtbar ist. Gefunden wurde es nur, weil +jemand aus anderem Anlass hinsah. + +Damit war die Regel faktisch außer Kraft: Eine Prüfung, die nur noch rot sein +kann, meldet nichts. Gleichzeitig ist das Vertagen selbst legitim — #0053 ist eine +bewusste Entscheidung, kein Versäumnis, und sie soll die Alarmfähigkeit nicht als +Geisel nehmen. + +## Optionen + +**A: Vertagtes abarbeiten, bis alles grün ist.** Ehrlich, aber es macht die +Alarmfähigkeit von Aufräumarbeit abhängig, die bewusst niedrige Priorität trägt — +und liefert für die Zwischenzeit keinen funktionierenden Meldeweg. + +**B: Rot tolerieren und die Läufe von Hand lesen.** Der Ist-Zustand. Er hat neun +Tage lang einen echten Ausfall verdeckt; genau diese Klasse soll die +Stillstandsprüfungs-Familie ja finden. + +**C: Bekannte Befunde quittieren.** Eine gepflegte Liste nimmt Bekanntes aus der +Rot-Wertung, ohne es zu verstecken. Rot bleibt dem Neuen vorbehalten. +Einwand — und er wiegt: Eine Ausnahmeliste ist selbst ein Kandidat für die nächste +Blindstelle, dieselbe Klasse wie der `mrtc`-Record. + +## Entscheidung + +**Option C**, mit drei Regeln, die den Einwand konstruktiv beantworten +(`scripts/quittungen.py`, `scripts/befund_quittungen.tsv`): + +- **Quittiertes verschwindet nicht.** Es erscheint weiterhin in der Ausgabe, mit + Grund und Frist. Quittieren heißt „bekannt", nicht „weg". +- **Jede Zeile trägt eine Frist.** Läuft sie ab, quittiert die Zeile nicht mehr + und meldet sich selbst; der Befund zählt wieder. Es gibt keine stille Ewigkeit. +- **„Dauerhaft" ist ausschließlich als ADR-Verweis formulierbar.** Eine dauerhafte + Ausnahme ohne Entscheidungs-Record ist nach AGENTS.md ohnehin ein Fehler — hier + lässt sie sich technisch nicht einmal hinschreiben. Wer Dauer will, muss + entscheiden. +- **Wirkungslose Zeilen melden sich.** Eine Quittung, auf die kein Befund mehr + passt, wird ausgegeben, damit die Datei nicht Zeilen für längst gelöste Probleme + sammelt. + +Quittiert wird pro Befund, **nicht per Sammelmuster**: Die 17 Commit-Hygiene-Funde +aus #0053 stehen einzeln mit ihrer SHA, weil ein Muster wie `: Echtzeit-Stempel` +jeden künftigen Verstoß mitverschluckt hätte. + +**Nicht quittiert werden flüchtige Befunde**, deren Meldung anderswo gebraucht +wird. Beispiel: „Mirror auseinander" erscheint bei jedem Lauf kurz nach einem Push, +ist aber der einzige Hinweis, wenn ein Spiegel wirklich stehenbleibt (#0028). Ein +kurzfristig roter Lauf ist der geringere Preis. + +## Konsequenzen + +- Grün ist wieder erreichbar und bedeutet „nichts Neues". Nachgewiesen am + 2026-08-18: beide Prüfungen von 25 offenen Befunden auf 0, während ein + absichtlich eingefügter neuer Befund weiterhin rot färbt. +- Die Quittungsdatei wird Teil der Refinement-Pflege: abgelaufene und wirkungslose + Zeilen sind Arbeitsvorrat, kein Rauschen. +- Quittungen binden an **Teilzeichenketten des Befundtextes**. Wer eine Ursache + behebt oder verschiebt, ändert damit unter Umständen den Text und muss die + Quittung nachziehen. Das ist bewusst in Kauf genommen: Die Alternative wären + stabile Befund-IDs, die die Datei ohne Spezialwissen unlesbar machen würden. +- Die Bedingung, unter der „rote Pipeline = Alarm" trägt, gehört neben die Regel + selbst in AGENTS.md. Diese Änderung ist mit sorb abzustimmen und daher hier nur + vermerkt, nicht vollzogen (#0104). diff --git a/docs/issues/0104-daueralarme-melden-nichts-mehr.md b/docs/issues/0104-daueralarme-melden-nichts-mehr.md index b8d7269..a6080b0 100644 --- a/docs/issues/0104-daueralarme-melden-nichts-mehr.md +++ b/docs/issues/0104-daueralarme-melden-nichts-mehr.md @@ -129,6 +129,7 @@ Spalte `pruefung`. | Ein *neu* eingeführter Befund färbt nachweislich rot | ✅ am Beispiel gezeigt, nicht abgeleitet | | Quittiertes bleibt sichtbar, mit Grund und Datum | ✅ | | Bedingung in AGENTS.md ergänzen | ⏳ **offen — braucht sorbs Zustimmung** | +| Prozessentscheidung als ADR festgehalten | ✅ [ADR-0020](../adr/0020-bekannte-befunde-quittieren.md) | Der letzte Punkt bleibt bewusst liegen: Änderungen an AGENTS.md werden nur mit sorb abgestimmt. Vorschlag für die Ergänzung neben „die rote Pipeline ist der