docs: Migrationsdokument haelt das Vorher fest und verweist auf die .template-Form, Rest-Abschnitt aus types/source.md entfernt (#107)

Files changed:
- CHANGES.md
- VERSION
- instructions/migrate-corpus.md
- instructions/migrations/6.0.0-type-guidance-split.md
- types/source.md

CHANGES.md

@@ -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

VERSION

@@ -1 +1 @@
-6.1.0-beta.1
+6.1.0-beta.2

instructions/migrate-corpus.md

@@ -120,6 +120,16 @@ Write it for a reader who has the new machinery and the old content, and who is
 changed, which pages are affected, how to tell a migrated page from an unmigrated one, and what
 `migrate verify` should report when it is done.
 
+**A verification step names its own baseline, and does it in an earlier step.** Where the
+document asks that something "read the same as before" - a composed `types describe` answer, a
+rendered index, any command's output - it says what to capture, where to put it, and at which
+point, so the check is a `diff` rather than a memory. Step 4's `migrate verify` needs none of
+that: its baseline is the last commit, which git holds whether or not anyone thought to keep it.
+A migration that changes machinery rather than `kb/` pages has no such baseline, and that is
+exactly where the unfalsifiable version has already slipped through - the 6.0.0 type-guidance
+split asked for output that "must read the same", named nothing to compare it against, and a
+stray section in the middle of one type-spec survived a check made in good faith.
+
 **Baseline: 1.0.0.** Migrations that predate it - the type-system move, the `confidence_base`
 backfill, the German section headings, the translation itself - have no documents and will not
 get any. An instance older than that is re-exported, not migrated.

instructions/migrations/6.0.0-type-guidance-split.md

@@ -56,7 +56,7 @@ upgrade(s) available"; taking it is not gated on anything else being current.
    shipped default.** Compare the type-spec's current prose (everything outside `## Frontmatter`
    and `## Template`) against the corresponding `types/<name>.guidance.md`:
 
-   - **Unchanged, or changed only in ways this instance is happy to lose:** proceed to step 3
+   - **Unchanged, or changed only in ways this instance is happy to lose:** proceed to step 4
      directly - the new guidance file already carries the improved version.
    - **Locally edited in a way worth keeping** (a house style note, an extra rule specific to
      this corpus): that edit has to move somewhere before the old prose is dropped. Either fold
@@ -65,28 +65,69 @@ upgrade(s) available"; taking it is not gated on anything else being current.
      instead of adding `guidance:` at all - both are legitimate; declining the stack default for
      one type is not an error.
 
-3. **Add `guidance: types/<name>.guidance.md` to the type-spec's frontmatter** - by hand, the same
+3. **Write down what `types describe` answers today, before changing anything.** Step 6 checks
+   that the composed answer still reads the same, and that is only a check if the "before" was
+   recorded somewhere other than your memory:
+
+   ```bash
+   tools/wikitool types describe <name> > /tmp/<name>-before.txt
+   ```
+
+   The whole output, per type-spec you are about to touch. Reading it through `head` or `tail`
+   instead is how a difference in the middle of a 150-line answer survives the check - and a
+   stray section in the middle of one type-spec is exactly what this step exists to catch.
+
+4. **Add `guidance: types/<name>.guidance.md` to the type-spec's frontmatter** - by hand, the same
    way any other type-spec frontmatter field is written (a type-spec is machinery, not a `kb/`
    page, so this is not a `wikitool touch` call). Do not remove `## Frontmatter` or `## Template`;
    only the generic prose around them is what the guidance file now carries.
 
-4. **Delete the now-duplicated prose from the type-spec**, keeping the H1, a short pointer to the
+5. **Delete the now-duplicated prose from the type-spec**, keeping the H1, a short pointer to the
-   guidance file (`types/entity.md`'s own current text is the worked example), `## Frontmatter`
+   guidance file, `## Frontmatter` and `## Template`. Where step 2 found a local edit worth
-   and `## Template`. Where step 2 found a local edit worth keeping and it lives in the
+   keeping and it lives in the type-spec's own body rather than a private guidance file, leave
-   type-spec's own body rather than a private guidance file, leave that part exactly where it is.
+   that part exactly where it is.
 
-5. **Verify:**
+   **The worked example is `types/<name>.md.template`, not `types/<name>.md`.** The latter is the
+   copy this instance adopted at setup - it is the file you are editing, so it still shows the
+   before-state. The `.template` beside it ships verbatim with every release and already carries
+   the after-state: H1, pointer paragraph, and `guidance:` in the frontmatter. Read it for the
+   shape; do not copy it wholesale, because its `## Frontmatter` and `## Template` are the
+   stack's defaults and yours are yours.
+
+   **The pointer paragraph is written in English**, like the H1 above it. It is authoring prose
+   addressed to an agent, so it belongs to the control plane whether or not this instance owns
+   the file it sits in - and so does any prose you keep beside it. A local note written in this
+   instance's KB language before that rule existed is therefore translated, not relabelled:
+   an English heading over a body in another language is the half-done version of this step.
+   [types/type-spec.md](../../types/type-spec.md#who-owns-a-type-spec) has the part-by-part
+   table; `## Frontmatter` and `## Template` are untouched by this migration either way.
+
+   **Do not head a kept note `## Authoring guidance`.** `types describe` sets that heading itself
+   and inlines the guidance file beneath it, which brings its own - so a third one out of the
+   type-spec's body reads as a duplicated section in the composed answer. Give a local note a
+   name of its own.
+
+6. **Verify against the file from step 3:**
 
    ```bash
-   tools/wikitool types describe <name>
+   tools/wikitool types describe <name> > /tmp/<name>-after.txt
+   diff /tmp/<name>-before.txt /tmp/<name>-after.txt
    ```
 
-   The output must read the same as it did before this migration - the guidance prose composed
+   The two must read the same - the guidance prose composed ahead of the type-spec's own body,
-   ahead of the type-spec's own body, in one answer. A diff against the pre-migration output of
+   in one answer. Wording differences are expected only where step 2 found something to drop or
-   the same command, restricted to wording, is expected only where step 2 found something to
+   fold in; the structure (frontmatter fields, template block) must be byte-identical, and a
-   drop or fold in; the structure (frontmatter fields, template block) must be byte-identical.
+   heading that stands in the "after" but not in the "before" means prose was renamed where it
+   should have been removed. One number catches the most likely version of that:
 
-6. **Record it:**
+   ```bash
+   grep -c '^## Authoring guidance' /tmp/<name>-after.txt
+   ```
+
+   Two is correct - the one `types describe` sets, and the one the guidance file brings. Three
+   means the type-spec's own body still carries a section of that name (step 5).
+
+7. **Record it:**
 
    ```bash
    tools/wikitool migrate done 6.0.0 --pages 0

types/source.md

@@ -44,10 +44,6 @@ how to write a conforming page is [types/source.guidance.md](source.guidance.md)
 | `concepts` | No | Titles of the concepts mentioned in this source |
 | `summary` | Yes | One-liner for `kb/index.md` |
 
-## Authoring guidance
-
-- The title starts with "Source - ", followed by the name of the source
-
 ## Template
 
 The block below is page material, so it is written in this instance's KB language