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:
co-authored by
Claude Opus 5
parent
84e87238f6
commit
8e653082b6
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user