docs: Migrationsdokument haelt das Vorher fest und verweist auf die .template-Form, Rest-Abschnitt aus types/source.md entfernt (#107)
CI / verify (push) Successful in 46s
Release / release (push) Successful in 37s

Files changed:
- CHANGES.md
- VERSION
- instructions/migrate-corpus.md
- instructions/migrations/6.0.0-type-guidance-split.md
- types/source.md
This commit is contained in:
2026-09-16 15:44:11 +02:00
parent 504149c7c4
commit 0e09cf41ea
5 changed files with 118 additions and 19 deletions
+53 -1
View File
@@ -59,12 +59,13 @@ concern - readable here, never shipped as something to parse.
---
## 6.1.0-beta.1 - 2026-09-16 - Upgrade-Prozedur als eigene Instruktion statt als Prosa in INSTALL.md
## 6.1.0-beta.2 - 2026-09-16 - Migrationsdokument prueft gegen eine festgehaltene Vorher-Ausgabe, Beispielverweis auf die .template-Form
**Author:** Torben Nehmer
<!-- wikitool:bumps -->
- Upgrade-Prozedur als eigene Instruktion statt als Prosa in INSTALL.md
- Migrationsdokument prueft gegen eine festgehaltene Vorher-Ausgabe, Beispielverweis auf die .template-Form
<!-- /wikitool:bumps -->
### Upgrade-Prozedur als eigene Instruktion statt als Prosa in INSTALL.md
@@ -121,6 +122,57 @@ Kein Grenzuebertritt: eine neue Instruktionsdatei und ein geaenderter Meldungste
Richtungen ein Drop-in. Eine Instanz, die zurueckgeht, behaelt die Datei als ueberzaehlige Datei,
und nichts liest sie automatisch - `manual: true` heisst genau das.
### Migrationsdokument prueft gegen eine festgehaltene Vorher-Ausgabe, Beispielverweis auf die .template-Form
`instructions/migrations/6.0.0-type-guidance-split.md` verlangte in seinem Verifikationsschritt,
die Ausgabe von `types describe <name>` muesse *"read the same as it did before this migration"* -
ohne dass ein Schritt davor dieses Vorher festhielt. Eine Pruefung gegen einen Zustand, den
niemand aufgeschrieben hat, faellt auf das Gedaechtnis des Ausfuehrenden zurueck, und bei ueber
150 Zeilen Ausgabe je Typ ist das keins. Der getracete 6.0.0-Lauf hat entsprechend durch
`| head -250` und `| tail -80` geprueft und *"structurally identical to before"* geurteilt; was
das uebersah, lag in der Mitte der `source`-Ausgabe. Das Dokument schreibt die Ausgabe jetzt in
einem eigenen Schritt **vor** der Aenderung in eine Datei und diffed hinterher, mit
`grep -c '^## Authoring guidance'` als Ein-Zahl-Probe: zwei Koepfe sind richtig - einen setzt
`types describe` selbst, einen bringt die Guidance-Datei mit.
Als generisches Muster steht dasselbe jetzt in `instructions/migrate-corpus.md` § "Writing the
migration document", weil es nicht an diesem einen Dokument haengt: `migrate verify` traegt seine
Baseline im letzten Commit, ob jemand daran denkt oder nicht - eine Migration an der Maschinerie
statt an `kb/` hat gar keine, und genau dort entsteht die Behauptung, die sich nicht widerlegen
laesst.
Zweiter Fehler im selben Dokument: der Beispielverweis auf `types/entity.md` zeigt in einer
ausgelieferten Instanz auf die beim Setup adoptierte Kopie - also auf genau den Vorher-Zustand,
den der Schritt entfernen laesst. Der Nachher-Zustand liegt dort unter
`types/entity.md.template`, und im Ursprungs-Repo existiert diese Datei ueberhaupt nicht:
`dist export` re-keyt `types/<name>.md` erst beim Export. Der Satz konnte in einer Instanz also
nicht bloss unguenstig sein, er konnte dort nie stimmen. Dazu sagt der Schritt jetzt die Sprache
des Pointer-Absatzes - englisch, weil Anleitungsprosa an einen Agenten Control Plane ist,
unabhaengig davon, wem die Datei gehoert - und dass das auch fuer behaltene lokale Prosa gilt:
die wird uebersetzt, nicht umbenannt. Die Tabelle dazu wird verlinkt statt kopiert
(`types/type-spec.md` § "Who owns a type-spec"), und ein behaltener Abschnitt bekommt einen
eigenen Namen statt der Ueberschrift, die `types describe` schon selbst setzt.
Derselbe Defekt eine Ebene hoeher, gefunden beim Nachmessen: `types/source.md` trug hier im
Ursprungs-Repo noch einen Rest-Abschnitt `## Authoring guidance` mit einem einzigen Bullet, der
die `title_prefix`-Frontmatter wiederholte - `types describe source` gab drei Koepfe aus, die
anderen drei Typen zwei. Die Sprachzentralisierung hat den Abschnitt uebersetzt, der
Guidance-Split den Rest der Prosa ausgelagert und diesen Bullet stehenlassen. Die Datei wird beim
Export zu `types/source.md.template`, also haette ihn jede neu aufgesetzte Instanz mit adoptiert.
Entfernt, geprueft mit genau dem Muster, das der Schritt oben jetzt vorschreibt: Vorher-Datei,
Diff, vier entfernte Zeilen und sonst nichts, alle vier Typen komponieren jetzt mit zwei Koepfen.
Verifiziert: `docs verify` (73 ausgelieferte Dokumente, 58 Referenzdateien),
`instructions verify` (23 Instruktionen, 7 Skills) und 1276 Tests gruen. Kein neuer Test: die
Aenderung ist Prosa in zwei Instruktionen und ein entfernter Abschnitt aus einem Type-Spec -
was hier mechanisch pruefbar waere, prueft `docs verify` bereits als Type-Spec gegen sein Schema.
Kein Grenzuebertritt: in beide Richtungen ein Drop-in. Die Korrektur gilt denen, die noch
upgraden - eine Instanz, die das Angebot bereits genommen hat, liest das Dokument nicht noch
einmal. Fuer sie lohnt der eine Befehl, mit dem der Schaden hier gefunden wurde:
`grep -c '^## Authoring guidance'` ueber `types describe <name>` fuer alle vier Typen, drei
bedeutet einen Rest-Abschnitt im eigenen Type-Spec.
---
## 6.0.1 - 2026-09-16 - docs toc/verify erreichen die .template-Form einer Referenzdatei