--- type: types/concept.md concept_type: workflow tags: [migration, versioning, corpus-diff, workflow] created: 2026-08-30 modified: 2026-08-31 related: - mechanism: wikitool - rests-on: KB Stack Versioning - see-also: Mass-Update Gate - see-also: Iteration and Cost Limits sources: [Source - Conversation - Versioning CI-CD and Content Migration Session 2026-08-30] confidence: 0.70 confidence_base: 0.70 provenance: sourced summary: Migration des KB-Inhalts entlang einer geordneten Versionskette; abgegrenzt gegen offene Instanz-Aktionen, die in den doctor-Check gehoeren statt in die Kette --- # KB Migration **Typ:** Workflow ## Definition KB Migration ist der Ablauf, mit dem der **Inhalt** einer Wissensbasis auf die Form gebracht wird, die eine neuere Stack-Version erwartet. Die Form des Inhalts hat eine eigene Version in `.wikitool-kb.json`, unabhängig von der Stack-Version in `VERSION` ([[KB Stack Versioning]])[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30]. Eine Instanz kann Maschinerie `1.4.0` tragen, während ihr Inhalt noch in `1.2.0`-Form vorliegt; genau diesen Zustand durchläuft jedes Upgrade, und er ist der Grund für die Trennung. Migrationen selbst sind `manual: true`-Anweisungen unter `instructions/migrations/`. Damit werden sie von `dist export` ohne zweiten Exportpfad mitgeliefert[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30]. ## Kernpunkte - **Die Kette ist ein Intervall, keine Fallunterscheidung.** `migrate status` bildet `(kb_version, VERSION]` aus den vorhandenen Migrationsdokumenten und ordnet aufsteigend. Von `1.3.1` nach `2.0.0` laufen `1.4.0`, dann `1.7.0`, dann `2.0.0`. Dass keine Migration auf `1.3.x` zielt, ist kein Sonderfall, sondern schlicht nicht im Intervall[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30]. - **`migrate done` verweigert jede Version, die nicht das nächste Glied ist.** Ein Sprung wird dadurch unmöglich, und ein unterbrochenes mehrstufiges Upgrade ist an der Stelle fortsetzbar, an der es abbrach[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30]. - **`1.0.0` ist die Basis.** Alles Ältere wird neu exportiert, nicht migriert[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30]. Eine bestehende Instanz ohne `.wikitool-kb.json` erhält ihren Startwert über `migrate baseline`; der Entwicklungsbaum selbst war der erste Fall und bekam `1.0.0`, weil sein Inhalt seiner Maschinerie nie hinterherhing[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30]. - **Zählen, nie Mengen vergleichen.** `kb_scan.extract_wikilinks()` liefert ein Set. Für `lint` ist das richtig - die Frage lautet, ob ein Verweis auflöst. Für eine Migrationsprüfung ist es falsch, denn dort lautet die Frage, ob einer verschwunden ist. Drei der vier Defekte, die die frühere Übersetzung des Korpus fand, hatten unveränderte Link-Mengen und nur veränderte Zählungen[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30]. - **`lint` kann eine Migration nicht absichern.** Die Negativkontrolle: eines von zwei `[[Docker]]`-Vorkommen aus `kb/entities/tools/Act Runner.md` entfernt, die Link-*Menge* damit unverändert. `migrate verify --from HEAD --fail-on-error` meldet `'Docker' 2->1`, `lint --fail-on-error` endet mit Exit 0 und schweigt über alle 21 Checks[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30]. `lint` liest eine einzige Revision; ein verschwundener Verweis hinterlässt ein Korpus, das in sich vollkommen stimmig ist. Darauf ruht die gesamte Strategie. - **„Seite" muss überall dasselbe heißen.** Der erste Lauf von `migrate verify` über 248 Seiten meldete 13 „entfernte Seiten", die keine sind: Die historische Seite listete jede `.md` unter `kb/`, die Arbeitsbaum-Seite benutzte `iter_kb_pages`, das `COLLECTION.md`, `INDEX.md` und die Meta-Dateien der kb-Wurzel überspringt. Behoben durch ein gemeinsames `kb_scan.is_page_path`, festgehalten durch einen Regressionstest[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30]. - **Kanonischer Name plus Aliase ist das Migrationsmuster.** `sections.py` dokumentiert es im eigenen Docstring: Es ist das, was ein Korpus Seite für Seite statt auf einen Schlag migrieren lässt - und das Entfernen eines Alias ist eine Breaking Change, keine Aufräumarbeit[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30]. - **Zwei Größen, zwei Regeln.** Einheiten werden nach dem Iterationsbudget geschnitten, Batches getrennt davon nach dem [[Mass-Update Gate]]. Beides zu verwechseln kostete im ersten Schnitt des Plans elf unnötige Freigaben[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30]. - **Pro Einheit zuerst die Struktur:** Frontmatter, H1, Wikilink-Ziele und Cite-IDs gegen `HEAD` vergleichen, bevor irgendetwas anderes geprüft wird. `lint` wird über jede Einheit vollständig gelesen, nicht nur über die vermeintlich betroffenen Abschnitte - der Frontmatter-Fehler der ersten Einheit tauchte als Schema-Fehler in einem Feld auf, das niemand bearbeitet hatte[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30]. - **Zusammenfassungen schreibt die orchestrierende Sitzung**, nie aus einem Subagenten übernommen: Sie schmücken aus, etwa „measuring application performance and responsiveness" zu „Latenz und Durchsatz unter Lastbedingungen"[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30]. ## Beispiele - [[wikitool]] - stellt `migrate list`/`status`/`verify`/`done`/`baseline` bereit und trägt die Prüfung `corpus diff`. - [[Chemenu]] - erster Fall für `migrate baseline`; `1.0.0` wurde ohne Migrationsdokument gesetzt, mit ausdrücklicher Begründung. ## Wann zu verwenden Sobald eine semantische Änderung am Inhalt ansteht, die eine bestehende Instanz nicht durch ein bloßes Stack-Update mitbekommt - eine geänderte Abschnittsbenennung, ein umbenanntes Frontmatter-Feld, ein umgezogenes Verzeichnis. Der `MAJOR`-Bump ohne Migrationsdokument wird von `version bump` verweigert[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30]. ## Wann NICHT zu verwenden - Nicht für Änderungen, die nur die Maschinerie betreffen. Ein neuer Befehl ohne Wirkung auf die Form des Inhalts braucht kein Migrationsdokument. - Nicht mit einem mechanischen Runner für Null-Migrationen. Eine DSL dafür wurde bewusst nicht gebaut, solange es nichts zu automatisieren gibt[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30]. - Nicht mit `lint` als Absicherung - siehe die Negativkontrolle oben. - **Nicht für eine offene Instanz-Aktion.** Die Maschinerie ist durchgehend auf Korpus-Form verdrahtet: `kb_version` beschreibt die Form des Inhalts, `migrate done` nimmt `--pages`, `migrate verify` vergleicht `kb/`. Eine Anforderung, die eine Instanz erfüllen muss, ohne dass sich eine Seite ändert - etwa das Anlegen von `USER.md`/`SOUL.md` aus der [[Personalization Plane]] - ist deshalb keine Migration, sondern ein Fall für einen `doctor`-Check. Ein Migrationsdokument dafür hätte zwei Kosten: `migrate done` würde `kb_version` heben und damit über den Inhalt etwas behaupten, das nicht über ihn gilt, und eine frische Instanz bekäme die Migration nie zu sehen, weil `dist export` ihr `kb_version = VERSION` mitgibt. Der Health-Check ist hier zudem das schärfere Werkzeug, weil er selbstprüfend ist: er meldet `FAIL`, bis die Sache erledigt ist, während `migrate done` eine Behauptung ist, die man ohne die Arbeit aufstellen kann. ## Fußnoten [^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30]: [[Source - Conversation - Versioning CI-CD and Content Migration Session 2026-08-30]] ## Beziehungen - **mechanism:** [[wikitool]] - **rests-on:** [[KB Stack Versioning]] - **see-also:** [[Mass-Update Gate]] - **see-also:** [[Iteration and Cost Limits]]