diff --git a/FRAMEWORK-BEFUNDE.md b/FRAMEWORK-BEFUNDE.md index 54986b8..cd58e38 100644 --- a/FRAMEWORK-BEFUNDE.md +++ b/FRAMEWORK-BEFUNDE.md @@ -450,8 +450,13 @@ Prüfungen macht. Löschung bleiben gesperrt, nur der Zugang ist erlaubt. Vier Kontrollen belegt. Upstream `check_locked.py` zieht dieselbe Grenze und sichert sie zu — unsere Fassung wusste es nur nicht. -- **Punkt 3 ist offen.** Der Abgleich ist gemacht und in `HERKUNFT.md` protokolliert, aber - beim nächsten Upgrade erinnert nichts daran. +- **Punkt 3 ist entschieden, aber nicht behoben.** Der Abgleich ist gemacht und in + `HERKUNFT.md` protokolliert; seit dem 2026-08-21 trägt + [ADR-0024](docs/adr/0024-drei-framework-dateien-erklaert-erweitert.md) die Ausnahme als + Entscheidung statt nur als Beschreibung und nimmt den Abgleich ausdrücklich in die + Upgrade-Pflicht auf. **Der maschinelle Widerspruch fehlt weiterhin** — beim nächsten + Upgrade erinnert nur noch diese ADR daran, und das ist genau die Sorte Gedächtnis, der + FB-11 nicht traut. **Vorschlag für die nächste Iteration.** Zwei Dinge, beide klein: diff --git a/STATUS.md b/STATUS.md index efbd19b..a63871c 100644 --- a/STATUS.md +++ b/STATUS.md @@ -91,7 +91,7 @@ Bedeutung der Meilensteine: siehe [roadmap.md](roadmap.md). _none active_ -## ADRs (23) +## ADRs (24) | ADR | Status | Title | |---|---|---| @@ -118,6 +118,7 @@ _none active_ | [0021](docs/adr/0021-foederation-geschlossen.md) | accepted | ADR-0021: Föderation wird geschlossen — leere Whitelist statt offener Tür | | [0022](docs/adr/0022-upstream-anschluss-durch-einmaligen-merge.md) | accepted | ADR-0022: Anschluss an Upstream durch einen einmaligen Merge, nicht durch einen geteilten Graft | | [0023](docs/adr/0023-fremdhistorie-von-der-git-hygiene-ausnehmen.md) | accepted | ADR-0023: Fremde Historie von der Git-Hygiene ausnehmen — erklärt, nicht global | +| [0024](docs/adr/0024-drei-framework-dateien-erklaert-erweitert.md) | accepted | ADR-0024: Drei Framework-Dateien sind erklärt erweitert — Diff-Referenz statt Byte-Vergleich | ## Open AARs (6) diff --git a/docs/adr/0024-drei-framework-dateien-erklaert-erweitert.md b/docs/adr/0024-drei-framework-dateien-erklaert-erweitert.md new file mode 100644 index 0000000..7804948 --- /dev/null +++ b/docs/adr/0024-drei-framework-dateien-erklaert-erweitert.md @@ -0,0 +1,115 @@ +--- +type: adr +id: "0024" +status: accepted +date: 2026-08-21 +supersedes: null +superseded_by: null +related: + - "docs/design/done/2026-08-11-neckbeard-migration.md" + - "docs/sources/upstream/neckbeard-v0.3.1/HERKUNFT.md" + - "FRAMEWORK-BEFUNDE.md" +--- + +# ADR-0024: Drei Framework-Dateien sind erklärt erweitert — Diff-Referenz statt Byte-Vergleich + +## Kontext + +Der Adoptionspfad des Rahmenwerks (`AGENTS.md` §5) verlangt, die +übernommenen Framework-Dateien byte-genau gegen eine vendorierte Baseline +zu halten. `scripts/pruefe_upstream_drift.py` tut das seit der Migration +vom 2026-08-11 — für neun der zwölf vendorierten Artefakte. + +Für drei geht es nicht, weil dieses Projekt Dinge braucht, die das +Rahmenwerk nicht kennt. Gemessen gegen die aktuelle Baseline v0.3.1: + +| Datei | Umfang | Was | +|---|---|---| +| `schema.yaml` | +51 / −9 Zeilen | Typ `component`; am Typ `issue` die Pflichtfelder `milestone` und `priority` sowie `area`, `due`, `gitlab_iid`, `host`, `projekt`, `wartegrund`; Status-Enum um `next`/`waiting` erweitert | +| `scripts/validate.py` | +20 / −1 Zeilen | Regeln `waiting_requires_reason` und `slug_matches_filename`, dazu das WIP-Limit von 2 | +| `scripts/gen_status.py` | +36 / −6 Zeilen | `STATUS.md` nach Meilenstein und Priorität gegliedert statt als flache Liste | + +Diese Abweichung ist seit dem 2026-08-11 gelebte Praxis und an zwei +Stellen beschrieben: in der Herkunftstabelle der Baseline als „erklärt +projekterweitert — nur Diff-Referenz", und im Kopf der `schema.yaml` +selbst. **Beschrieben, aber nie entschieden.** `AGENTS.md` §1 verlangt für +jede dauerhafte Ausnahme von einer Regel eine ADR — *„eine Ausnahme nur zu +dokumentieren statt sie zu entscheiden, ist ein Fehler."* Diese fehlte. +[FB-12](../../FRAMEWORK-BEFUNDE.md) hat die Lücke beim Upgrade auf v0.3.1 +benannt. + +## Optionen + +**A: Alles byte-treu halten, Erweiterungen nur upstream einbringen.** +Verworfen. Meilensteine und Prioritäten trugen 71 von 71 offenen Issues, +bevor das Rahmenwerk das Konzept überhaupt kannte; es steht dort bis heute +als offener Vorgang. Diese Option koppelt die Arbeitsfähigkeit dieses +Repos an die Freigabekadenz eines anderen Projekts. Das Rahmenwerk selbst +sieht das anders: Projektseitige Varianten sind dort ausdrücklich als +„gepinnte Basis plus erklärte, diffbare Erweiterungen" vorgesehen. + +**B: Still forken.** Verworfen ohne Diskussion — genau das ist der +Zustand, den `pruefe_upstream_drift.py` verhindern soll. Die Frage von +sorb, die zur Prüfung führte, lautete *„wird die AGENTS.md ggf. durch +Agenten umgeschrieben?"*; eine unerklärte Abweichung beantwortet sie mit +Ja. + +**C: Präfix-Vergleich wie bei `AGENTS.md`.** Verworfen, und zwar +nachgemessen: Bei `AGENTS.md` trägt der Upstream-Teil vorn und der +Projektabschnitt hängt hinten an — ein Präfix-Vergleich greift. Bei diesen +drei Dateien sind die Erweiterungen **eingewoben**: `component` steht +zwischen `issue` und `wiki-page`, die beiden Regeln stehen *innerhalb* von +`apply_rules`, und `gen_status.py` **ersetzt** die Issue-Tabelle, statt +etwas anzuhängen. Ein Präfix-Vergleich wäre ab der ersten abweichenden +Zeile rot und damit wertlos. + +**D: Erklärte Erweiterung mit Diff-Referenz.** Die Baseline behält die +unveränderten Originale, aber nicht als Byte-Maßstab, sondern als +Vergleichsstand: Was wir geändert haben, ist jederzeit als Diff sichtbar. +Die Herkunftstabelle sagt Datei für Datei, welche Prüfung gilt. + +## Entscheidung + +**Option D** (sorb, 2026-08-21, auf FB-12 hin). Damit ist die seit dem +2026-08-11 gelebte Praxis erstmals entschieden statt nur beschrieben. + +Verbindlich ist dabei: + +- Die Ausnahme gilt für **genau diese drei Dateien**. Jede weitere + Abweichung von der Baseline ist ein Fehler, bis sie eine eigene ADR hat. +- **Maßgeblich ist die Tabelle in `HERKUNFT.md`** der jeweils gültigen + Baseline. Sie und die Paarliste in `pruefe_upstream_drift.py` müssen + sich decken; weicht eine von der anderen ab, ist die Prüfung falsch + konfiguriert und nicht die Datei. +- **Jede Erweiterung wird an ihrem eigenen Ort begründet**, nicht nur + hier: `schema.yaml` trägt den Erweiterungsblock im Kopf, die beiden + Skripte nennen ihre Zusätze im Modulkopf. Eine Erweiterung ohne + Begründung gibt es nicht — dasselbe Muster wie bei den Quittungen. +- **Ein Framework-Upgrade schließt den Abgleich dieser drei ein.** Was + upstream zwischen alter und neuer Baseline an ihnen geändert hat, wird + von Hand nachgezogen und in der neuen `HERKUNFT.md` protokolliert. + +## Konsequenzen + +- Das Projekt bleibt arbeitsfähig, ohne auf fremde Freigaben zu warten, + und die Abweichung ist an drei Stellen nachlesbar statt an keiner. +- **Für die übrigen neun Dateien behält der Byte-Vergleich seine volle + Schärfe** — belegt beim Upgrade auf v0.3.1: `pruefe_upstream_drift: 0 + Fehler`, mit `WORKFLOW.md` byte-genau übernommen und zwei neu + hinzugekommenen Vorlagen im Vergleich. +- ⚠️ **Der Preis, ehrlich benannt: Der Abgleich beim Upgrade hat keinen + maschinellen Widerspruch.** Er hängt daran, dass jemand daran denkt. + Nachgemessen an genau diesem Fall: Zwischen v0.1.1 und v0.3.1 hat + upstream zwei der drei Dateien angefasst — `validate.py` +29, + `schema.yaml` +50 Zeilen, `gen_status.py` gar nicht. **Gemeldet hat das + nichts.** Sichtbar wurde es erst, weil beim Upgrade ausdrücklich ein + Diff über die Baselines gezogen wurde. Bis dafür eine Prüfung existiert, + ist diese ADR das einzige, was sich daran erinnert. Das ist FB-12, + Punkt 3, und dort steht auch der Vorschlag: eine Prüfung, die die + erklärt-erweiterten Dateien gegen die *vorige* Baseline hält und meldet, + dass etwas nachzuziehen war. Sie kann nicht beurteilen, ob wir richtig + nachgezogen haben — aber der Fehler ist Vergessen, nicht Falschmachen. +- Wird eine der drei Erweiterungen eines Tages upstream übernommen, fällt + sie hier ersatzlos weg und die Datei kehrt in den Byte-Vergleich zurück. + Für den Typ `component` und das Meilenstein-Konzept ist das der + erklärte Zielzustand, nicht bloß eine Möglichkeit.