chemenu/kb/concepts/KB Migration.md

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

<!-- wikitool:links -->
## Beziehungen

- **mechanism:** [[wikitool]]
- **rests-on:** [[KB Stack Versioning]]
- **see-also:** [[Mass-Update Gate]]
- **see-also:** [[Iteration and Cost Limits]]
<!-- /wikitool:links -->