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 <noreply@anthropic.com>
This commit is contained in:
Thore Cimbal
2026-08-18 12:00:00 +00:00
co-authored by Claude Opus 5
parent 84e87238f6
commit 8e653082b6
3 changed files with 92 additions and 1 deletions
+2 -1
View File
@@ -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)
@@ -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).
@@ -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