chemenu/kb/concepts/workflows/KB Migration.md

type, concept_type, tags, created, modified, related, sources, provenance, summary

type	concept_type	tags	created	modified	related	sources	provenance	summary
types/concept.md	workflow	migration versioning corpus-diff workflow	2026-08-30	2026-08-31	mechanism wikitool rests-on KB Stack Versioning see-also Mass-Update Gate see-also Iteration and Cost Limits	Source - Conversation - Versioning CI-CD and Content Migration Session 2026-08-30	sourced	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)¹ . 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¹ .

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¹ .
• 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¹ .
• 1.0.0 ist die Basis. Alles Ältere wird neu exportiert, nicht migriert¹ . 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¹ .
• 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¹ .
• 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¹ . 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¹ .
• 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¹ .
• 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¹ .
• 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¹ .
• 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"¹ .

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¹ .

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¹ .
• 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

Beziehungen

• mechanism: wikitool
• rests-on: KB Stack Versioning
• see-also: Mass-Update Gate
• see-also: Iteration and Cost Limits

---

1. Source - Conversation - Versioning CI-CD and Content Migration Session 2026-08-30 ↩︎