diff --git a/STATUS.md b/STATUS.md index a63871c..7f3c9b8 100644 --- a/STATUS.md +++ b/STATUS.md @@ -87,9 +87,11 @@ Bedeutung der Meilensteine: siehe [roadmap.md](roadmap.md). | [0090](docs/issues/0090-gitops-59-kein-kubernetes-audit-log-zugriffe-an-der-api.md) | low | open | Kein Kubernetes-Audit-Log — Zugriffe an der API werden nicht protokolliert | -## Active design docs (0) +## Active design docs (1) -_none active_ +| Design | Gate | Title | +|---|---|---| +| [2026-08-21-v031-adoption-stage-2](docs/design/2026-08-21-v031-adoption-stage-2.md) | gate-1 | Design: Die Übernahme von v0.3.1 zu Ende bringen — Etappe 2 | ## ADRs (24) diff --git a/docs/design/2026-08-21-v031-adoption-stage-2.md b/docs/design/2026-08-21-v031-adoption-stage-2.md new file mode 100644 index 0000000..d6b6369 --- /dev/null +++ b/docs/design/2026-08-21-v031-adoption-stage-2.md @@ -0,0 +1,101 @@ +--- +type: design +status: gate-1 +date: 2026-08-21 +size: L +related: + - "FRAMEWORK-BEFUNDE.md" + - "docs/ledger/2026-08-21-neckbeard-v0-3-1-upgrade.md" + - "docs/adr/0024-drei-framework-dateien-erklaert-erweitert.md" +--- + +# Design: Die Übernahme von v0.3.1 zu Ende bringen — Etappe 2 + +## Gate 1 — Product + +**Ausgangslage, gemessen statt angenommen.** Dieses Vorhaben wurde als +zweistufige Übernahme von neckbeard `v0.3.1` aufgesetzt. Beim Aufsetzen +zeigte sich, dass **Etappe 1 bereits gelaufen ist** — ein paralleler +Durchlauf am selben Tag hat sie erledigt und in +[docs/ledger/2026-08-21-neckbeard-v0-3-1-upgrade.md](../ledger/2026-08-21-neckbeard-v0-3-1-upgrade.md) +protokolliert. Dieses Dokument beschreibt deshalb **nur den Rest**, nicht +das Ganze; alles andere wäre die Klasse „Dokument behauptet einen Zustand, +den die Messung längst überholt hat" (FB-04) im eigenen Plan. + +Erledigt und nachgeprüft: + +| | Stand | +|---|---| +| Baseline `neckbeard-v0.3.1/` vendoriert, `v0.1.1/` daneben stehen geblieben | ✅ | +| `pruefe_upstream_drift.py` gegen die neue Baseline: **0 Fehler** | ✅ | +| `schema.yaml` zusammengeführt — `ledger` und `verdict` vorhanden, unsere Erweiterungen (`component`, Meilenstein, Priorität) unangetastet | ✅ | +| `check_harvest.py` und `judge.py` übernommen, `validate.py` um die Portabilitätsprüfung ergänzt | ✅ | +| Ledger-Pflicht in Kraft, erstes Ledger geschrieben | ✅ | +| [ADR-0024](../adr/0024-drei-framework-dateien-erklaert-erweitert.md): drei Dateien sind **erklärte Erweiterungen** statt byte-treuer Kopien | ✅ | +| **FB-12** aufgenommen: der Upgrade-Pfad war beschrieben, nie begangen | ✅ | + +⚠️ **Eine Festlegung wurde dabei bewusst umgedreht**, mit Freigabe und +Begründung im Ledger: `check_locked.py` wurde **nicht** übernommen. Unsere +`pruefe_sperrliste.py` erfüllt dieselbe Aufgabe und hatte nur einen Defekt — +sie hielt jeden *Zugang* unter `docs/sources/` für eine *Änderung* und +verbot damit das Upgrade selbst. Der Defekt wurde behoben (`--name-status` +statt `--name-only`). Erste Sprosse der Leiter: zwei Werkzeuge für eine +Regel sind Pflege ohne Gewinn. Das wird hier **nicht neu aufgerollt**. + +**Problem.** Was aussteht, ist der inhaltliche Teil — und es ist der, an dem +die Übernahme scheitern würde, wenn man sie für erledigt hält: + +1. **Die elf Befunde liegen noch als handgepflegtes Register vor.** + **ADR-0009 des Rahmenwerks** hat die Frage anders entschieden als von uns vorgeschlagen: + keine eigene Artefaktart, sondern je eine `stolpersteine`-Wiki-Seite mit + `status: open | partly | harvested` und `harvested_in`. Genau der Ort, + den wir schon haben — drei Seiten liegen dort bereits. +2. **Der Ernte-Stand ist unbestimmt.** Vier Rahmenwerks-Versionen sind + erschienen, seit die elf übergeben wurden. Damit ist die Bedingung „eine + **veröffentlichte** Version deckt das Muster ab" zum ersten Mal prüfbar — + und ungeprüft. Solange das so bleibt, sagt kein einziger der elf Stände + etwas aus. +3. **`judge.py` ist übernommen, aber nirgends verdrahtet**, und es existiert + kein einziges Verdikt. Ein Werkzeug, das nie läuft, ist Deko. + +**Acceptance criterion.** + +1. Jeder der zwölf Befunde ist entweder eine `stolpersteine`-Seite mit + gesetztem `status`, oder er ist begründet **keiner** — die Zahl der + Befunde ohne Zuordnung ist **0**, per Skript gezeigt, nicht gelesen. +2. Jede Seite mit `status: harvested` nennt in `harvested_in` eine + **veröffentlichte** Version, und der Beleg dafür ist prüfbar: die Regel + oder das Werkzeug, das sie abdeckt, existiert in der genannten Version. + Übergeben ist nicht geerntet. +3. `FRAMEWORK-BEFUNDE.md` wird **erzeugt** und trägt einen `--check`-Modus + wie `STATUS.md`; eine Änderung von Hand färbt die Pipeline rot. +4. Der doppelte Regeltext im Projektabschnitt von `AGENTS.md` ist entfernt + (die ADR-Pflicht für dauerhafte Ausnahmen steht seit v0.1.2 upstream) — + Entscheidung sorb vom 2026-08-21. +5. `judge.py` läuft mindestens einmal gegen einen echten Durchlauf und + erzeugt ein `verdict`-Artefakt. Dass es rot werden **kann**, ist gezeigt. +6. Alle Tore grün, Pipeline grün. + +**Non-goals.** + +- **Etappe 1 wird nicht wiederholt** und die Entscheidung zu + `check_locked.py` nicht revidiert. +- **Kein Umschreiben der Befundtexte.** Sie ziehen um und bekommen einen + Stand; ihr Inhalt bleibt, was er ist. +- **Keine Ernte.** Was hier an neuen Mustern auffällt, wird notiert, nicht + übergeben — die nächste Übergabe ist ein eigenes Vorhaben. +- **Kein rückwirkendes Urteil** über vergangene Sitzungen. +- **Kein Push nach Gitea.** + +**Announcement.** Das Rahmenwerk hat unsere Fehlerklassen einen Platz +bekommen lassen — und einen Stand, der zwischen „gemeldet", „teilweise +gedeckt" und „geerntet" unterscheidet, wobei geerntet nur zählt, wenn eine +veröffentlichte Version es wirklich abdeckt. Diese Etappe zieht die zwölf +Befunde dorthin um, prüft zum ersten Mal nach, welche davon inzwischen +tatsächlich gedeckt sind, und macht aus dem handgepflegten Register eine +erzeugte Übersicht, die nicht mehr veralten kann. Damit hört der Bestand +auf, eine Behauptung zu sein. + +**Mockups.** Keine Oberfläche beteiligt. + +> **STOP — Freigabe für Gate 1.** diff --git a/docs/ledger/2026-08-21-v031-adoption-stage-2.md b/docs/ledger/2026-08-21-v031-adoption-stage-2.md new file mode 100644 index 0000000..2b6e05c --- /dev/null +++ b/docs/ledger/2026-08-21-v031-adoption-stage-2.md @@ -0,0 +1,41 @@ +--- +type: ledger +date: 2026-08-21 +size: L +status: open +related: + - "docs/design/2026-08-21-v031-adoption-stage-2.md" +--- + +# Ledger: Die Übernahme von v0.3.1 zu Ende bringen + +## Gates + +| gate | commit | approval | status | note | +|---|---|---|---|---| +| 1 | | | NEEDS_CONTEXT | Gate 1 geschrieben; Freigabe steht aus. Zuschnitt einmal komplett neu gefasst, weil die Messung ergab, dass Etappe 1 schon lief. | + +## Ladder + +| searched | found | outcome | commit | +|---|---|---|---| +| `docs/design/`, ob für die v0.3.1-Übernahme schon ein Vorhaben läuft | kein Design-Dokument — aber `docs/ledger/2026-08-21-neckbeard-v0-3-1-upgrade.md` mit vollständig protokollierter Etappe 1 | reused: Etappe 1 nicht wiederholt; dieses Dokument auf den Rest umgeschrieben statt danebengestellt | | +| neckbeards `check_locked.py` gegen unsere `pruefe_sperrliste.py`, wie am 2026-08-20 vorgeschlagen | im Ledger des Parallellaufs bereits abgewogen und mit Freigabe entschieden: unsere behalten, Defekt behoben | reused: die Entscheidung übernommen, nicht neu aufgerollt | | +| `docs/wiki/stolpersteine/`, bevor für die Befunde ein Ort gebaut wird | drei Seiten liegen schon dort; `schema.yaml` trägt `status` und `harvested_in` seit v0.3.1 | reused: der Ort existiert, es wird keiner gebaut — nur umgezogen | | +| `scripts/gen_status.py`, als Vorbild für die erzeugte Befundübersicht | erzeugt aus Frontmatter, trägt `--check`, in der CI verdrahtet | reused: dasselbe Muster, statt einen zweiten Erzeugungsweg zu erfinden | | + +## Notes + +**Der Zuschnitt hat sich beim Messen geändert, nicht beim Planen.** Das +Vorhaben war als vollständige Übernahme aufgesetzt und wurde beim ersten +Push abgelehnt — auf `main` lagen acht Commits eines parallelen Laufs, der +Etappe 1 bereits erledigt hatte. Gate 1 ist daraufhin **vollständig neu +geschrieben** worden statt ergänzt: ein Plan, der bereits erledigte Arbeit +ankündigt, ist derselbe Fehler wie ein Issue, dessen Kopf eine überholte +Diagnose behauptet. + +⚠️ **Eine Verunreinigung des Arbeitsbaums beim Sichten.** Um den fremden +Stand anzusehen, wurde `git checkout origin/main -- .` benutzt — das legt +fremde Inhalte über den eigenen Stand, statt sie nur zu lesen. Mit +`git reset --hard` zurückgenommen, danach sauber rebast. Zum Lesen eines +fremden Standes gehört `git show`, nicht `git checkout`.