ingest: raw/notes/Conversation Transcript - Version Part Nomenclature and Breaking Change Gate Session 2026-09-02.md

Files changed:
- kb/concepts/INDEX.md
- kb/concepts/KB Stack Versioning.md
- kb/entities/INDEX.md
- kb/entities/projects/Chemenu.md
- kb/entities/tools/wikitool.md
- kb/index.md
- kb/log.md
- kb/sources/INDEX.md
- kb/sources/Source - Version Part Nomenclature and Breaking Change Gate Session 2026-09-02.md
- raw/notes/Conversation Transcript - Version Part Nomenclature and Breaking Change Gate Session 2026-09-02.md

kb/concepts/INDEX.md

@@ -44,7 +44,7 @@
 | [[Issue Label Scheme]] | decision | Zweiachsiges Pflicht-Labelschema fuer das Gitea-Board: prio/1..3 und size/XS..L, bewusst keine dritte Achse; die Regel liegt in instructions/dev/, weil sie keine ausgelieferte Instanz erreichen darf | 2026-08-31 |
 | [[Iteration and Cost Limits]] | workflow | Im Code durchgesetzte Obergrenze von 60 wikitool-Aufrufen je Session, Loop-Breaker bei 3 identischen Wiederholungen, Slot-Erstattung, ein gemessenes Kalibrierungsband, und Retrieval sowie der MCP-Leseserver bleiben ausgenommen | 2026-09-02 |
 | [[KB Migration]] | workflow | Migration des KB-Inhalts entlang einer geordneten Versionskette; abgegrenzt gegen offene Instanz-Aktionen, die in den doctor-Check gehoeren statt in die Kette | 2026-08-31 |
-| [[KB Stack Versioning]] | decision | Semantische Versionierung des Wiki-Stacks: VERSION beschreibt die Maschinerie, Kompatibilitaet ist die linkeste Nicht-Null-Komponente, und drei getrennte Dateien trennen Maschinerie, Herkunft und Content-Form | 2026-08-30 |
+| [[KB Stack Versioning]] | decision | Semantische Versionierung des Wiki-Stacks: VERSION beschreibt die Maschinerie, Kompatibilitaet (Drop-in-Ersatz) und Inhaltsmigration sind seit 2.5.0 getrennte, unabhaengig geprueft Fragen | 2026-09-02 |
 | [[Knowledge Compounding]] | workflow | Effekt, bei dem Wissen im Wiki an Wert gewinnt, weil jede neue Quelle an bestehende, untereinander verwiesene Seiten anknüpft und sie ergänzt. | 2026-08-29 |
 | [[Knowledge Graph]] | architecture | Typisierte Schicht aus Entities und Beziehungen über den Wiki-Seiten, die eine reichere Wissensdarstellung und graphbasierte Abfragen ermöglicht. | 2026-08-29 |
 | [[Lint Workflow]] | workflow | Deterministischer Health-Check rund um wikitool lint; seit 1.7.2 maskiert es Code vor dem Notation-Match und zaehlt Zitat-Bloecke statt Zeilen | 2026-09-01 |

kb/concepts/KB Stack Versioning.md

@@ -3,13 +3,13 @@ type: types/concept.md
 concept_type: decision
 tags: [versioning, semver, release, stack]
 created: 2026-08-30
-modified: 2026-08-30
+modified: 2026-09-02
 related: [wikitool, Issue Label Scheme]
-sources: [Source - Conversation - Versioning CI-CD and Content Migration Session 2026-08-30, Source - Conversation - Issue Triage Labels and TODO Retirement Session 2026-08-31]
+sources: [Source - Conversation - Versioning CI-CD and Content Migration Session 2026-08-30, Source - Conversation - Issue Triage Labels and TODO Retirement Session 2026-08-31, Source - Version Part Nomenclature and Breaking Change Gate Session 2026-09-02]
 confidence: 0.70
 confidence_base: 0.70
 provenance: sourced
-summary: 'Semantische Versionierung des Wiki-Stacks: VERSION beschreibt die Maschinerie, Kompatibilitaet ist die linkeste Nicht-Null-Komponente, und drei getrennte Dateien trennen Maschinerie, Herkunft und Content-Form'
+summary: 'Semantische Versionierung des Wiki-Stacks: VERSION beschreibt die Maschinerie, Kompatibilitaet (Drop-in-Ersatz) und Inhaltsmigration sind seit 2.5.0 getrennte, unabhaengig geprueft Fragen'
 ---
 # KB Stack Versioning
 
@@ -42,9 +42,18 @@ deshalb eine ausdrückliche Handlung.
   Caret-Ranges
   verwenden[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30]. Sie gilt
   einheitlich für `0.x` und `1.x`, sodass unter `0.x` der Schritt `0.1.x` -> `0.2.0` dasselbe
-  Migrationssignal trägt wie `MAJOR` ab `1.0.0`. Der Code für den `compat_key` ist deshalb
+  Signal trägt wie `MAJOR` ab `1.0.0`. Der Code für den `compat_key` ist deshalb einheitlich
-  einheitlich formuliert und musste beim Wechsel auf `1.0.0` nicht angefasst
+  formuliert und musste beim Wechsel auf `1.0.0` nicht angefasst
   werden[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30].
+- **Kompatibilität und Inhaltsmigration sind zwei unabhängige Fragen, seit `2.5.0` auch zwei
+  getrennte Marker.** Kompatibilität fragt, ob die neue Version ein Drop-in-Ersatz ist -
+  vorwärts ohne Handarbeit, rückwärts noch downgradebar; Inhaltsmigration fragt, ob `kb/` sich
+  bewegen muss. Ein Grenzübertritt kann `kb/` unangetastet lassen und trotzdem MAJOR sein - der
+  `2.0.0`-Rebranding-Bump ist das Beispiel: Update-Pfad, Release-Artefaktname und
+  Paket-Import-Name brachen, keine Seite tat es. `version bump` verlangt deshalb bei jedem
+  Grenzübertritt `--breaking "<was aufhört zu funktionieren>"`, unabhängig von
+  `--no-migration`/einem Migrationsdokument; beide Zeilen landen getrennt im
+  `CHANGES.md`-Eintrag[^s-version-part-nomenclature-and-breaking-change-gate-session-2026-09-02].
 - **`x.y.z` ist die maximale Granularität. Keine Pre-Release-Suffixe.** Eine zweite
   Ordnungsregel müsste vom Release-Feed, von der Migrationskette und von der
   Kompatibilitätsprüfung gleichermaßen befolgt
@@ -64,7 +73,11 @@ deshalb eine ausdrückliche Handlung.
   Instanz[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30].
 - **Die Grenze wird an zwei Stellen erzwungen:** in `version bump` und in `docs verify`, ergänzt
   um einen `kb-version`-Check in
-  `doctor`[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30].
+  `doctor`[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30]. Seit
+  `2.5.0` prüft `docs verify` dort zwei unabhängige Dinge - `check_migration_for_boundary` (hat
+  der Korpus sich bewegt) und `check_breaking_change_for_boundary` (wurde der Bruch benannt) -,
+  weil ein Grenzübertritt die eine Prüfung bestehen und an der anderen scheitern
+  kann[^s-version-part-nomenclature-and-breaking-change-gate-session-2026-09-02].
 
 ## Beispiele
 
@@ -105,7 +118,9 @@ kann.
 - [[wikitool]]
 - [[Issue Label Scheme]]
 - [[Source - Conversation - Issue Triage Labels and TODO Retirement Session 2026-08-31]]
+- [[Source - Version Part Nomenclature and Breaking Change Gate Session 2026-09-02]]
 
 ## 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]]
+[^s-version-part-nomenclature-and-breaking-change-gate-session-2026-09-02]: [[Source - Version Part Nomenclature and Breaking Change Gate Session 2026-09-02]]

kb/entities/INDEX.md

@@ -19,7 +19,7 @@
 |------|------|---------|----------------|
 | [[andybalholm-edl]] | project | Go-basierte EDL-Bibliothek für die Kommunikation mit eingebetteten Geräten. | 2026-08-29 |
 | [[BCDModule]] | project | Go-Modul, das die Entscheidungslogik für die Batterieladung umsetzt. | 2026-08-29 |
-| [[Chemenu]] | project | Deterministischer Wissenskompiler (raw/ -> kb/); seit 2.0.0 unter dem Namen Chemenu, seit 2026-09-01 oeffentlich, seit 2.4.0 mit einem MCP-Leseserver als zweitem Konsumenten | 2026-09-02 |
+| [[Chemenu]] | project | Deterministischer Wissenskompiler (raw/ -> kb/); seit 2.0.0 unter dem Namen Chemenu; Issue 26 zur Versionsstellen-Nomenklatur in 2.5.0 geschlossen | 2026-09-02 |
 | [[goresponsiveness]] | project | Go-Werkzeug zur Messung von Anwendungsleistung und Responsiveness. | 2026-08-29 |
 | [[ha-core]] | project | Kern-Integrationsbibliothek für Home-Assistant-E3DC-Systeme; stellt die E3DC-Kommunikationsprotokolle und den Home-Assistant-Integrationscode bereit. | 2026-08-29 |
 | [[hacs-e3dc]] | project | Home Assistant Custom Component zur Überwachung von E3DC-Energiesystemen. | 2026-08-29 |
@@ -98,6 +98,6 @@
 | [[Proton]] | tool | Wine-basierte Kompatibilitätsschicht von Valve; lässt Windows-Spiele über Steam unter Linux laufen, mit optimierter DirectX-Übersetzung. | 2026-08-29 |
 | [[qmd]] | tool | Lokale Suchmaschine fuer Markdown-Dateien: TypeScript/Node.js/Bun, SQLite-FTS5-BM25 plus sqlite-vec-Vektorsuche plus node-llama-cpp-LLM-Reranking. | 2026-09-02 |
 | [[Steam]] | tool | Valves Plattform für digitalen Spielevertrieb und Spielebibliothek auf dem PC. | 2026-08-29 |
-| [[wikitool]] | tool | Deterministisches CLI fuer alle mechanischen Wiki-Operationen; seit 2.0.0 im Paket chemenu, seit 2.4.0 zusaetzlich als MCP-Leseserver erreichbar | 2026-09-02 |
+| [[wikitool]] | tool | Deterministisches CLI fuer alle mechanischen Wiki-Operationen; seit 2.0.0 im Paket chemenu, seit 2.4.0 zusaetzlich als MCP-Leseserver erreichbar, seit 2.5.0 mit Breaking-Change-Pflichtmarker | 2026-09-02 |
 | [[Wine]] | tool | Kompatibilitätsschicht, die Windows-API-Aufrufe nach POSIX übersetzt und Windows-Anwendungen unter Linux, BSD und macOS ohne Virtualisierung oder Emulation ausführt. | 2026-08-29 |
 

kb/entities/projects/Chemenu.md

@@ -5,11 +5,11 @@ tags: [wiki, llm, knowledge-base]
 created: 2026-08-04
 modified: 2026-09-02
 related: [Personalization Plane, Issue Label Scheme, Optional Instance Context File, Delete Rather Than Anonymize, Dual Licensing by File Plan, Publish-Remote Gate, MCP-Leseserver]
-sources: [Source - Copilot Skill Restructure Instructions, Source - Conversation - AGENTS.md Skill Restructuring Session 2026-08-04, Source - Conversation - Versioning CI-CD and Content Migration Session 2026-08-30, Source - Conversation - Comma Bug Budget Refund and Lint Report Path Session 2026-08-31, Source - Conversation - Issue Triage Labels and TODO Retirement Session 2026-08-31, Source - Conversation - Write-Once Frontmatter Fields and touch --set Session 2026-08-31, Source - Conversation - Gate Counting and Measured Calibration Session 2026-08-31, Source - Conversation - Two Round-Trip Defects Found by an Ingest Session 2026-08-31, Source - Conversation - Hardening the Test Suite Against Silent Environment Dependencies Session 2026-08-31, 'Source - Public Release, Corpus Purge and History Squash Session 2026-09-01', Source - Publish-Remote Gate and Issue Triage Session 2026-09-01, Source - Private-Instance Merge Correction and Issue 30 Session 2026-09-01, Source - MCP Read Server Implementation Session 2026-09-02]
+sources: [Source - Copilot Skill Restructure Instructions, Source - Conversation - AGENTS.md Skill Restructuring Session 2026-08-04, Source - Conversation - Versioning CI-CD and Content Migration Session 2026-08-30, Source - Conversation - Comma Bug Budget Refund and Lint Report Path Session 2026-08-31, Source - Conversation - Issue Triage Labels and TODO Retirement Session 2026-08-31, Source - Conversation - Write-Once Frontmatter Fields and touch --set Session 2026-08-31, Source - Conversation - Gate Counting and Measured Calibration Session 2026-08-31, Source - Conversation - Two Round-Trip Defects Found by an Ingest Session 2026-08-31, Source - Conversation - Hardening the Test Suite Against Silent Environment Dependencies Session 2026-08-31, 'Source - Public Release, Corpus Purge and History Squash Session 2026-09-01', Source - Publish-Remote Gate and Issue Triage Session 2026-09-01, Source - Private-Instance Merge Correction and Issue 30 Session 2026-09-01, Source - MCP Read Server Implementation Session 2026-09-02, Source - Version Part Nomenclature and Breaking Change Gate Session 2026-09-02]
 confidence: 0.90
 confidence_base: 0.90
 provenance: mixed
-summary: Deterministischer Wissenskompiler (raw/ -> kb/); seit 2.0.0 unter dem Namen Chemenu, seit 2026-09-01 oeffentlich, seit 2.4.0 mit einem MCP-Leseserver als zweitem Konsumenten
+summary: Deterministischer Wissenskompiler (raw/ -> kb/); seit 2.0.0 unter dem Namen Chemenu; Issue 26 zur Versionsstellen-Nomenklatur in 2.5.0 geschlossen
 ---
 # Chemenu
 
@@ -159,7 +159,8 @@ Repositorys selbst und keine Aussagen aus einer Rohdatenquelle; der Änderungsda
   auf den alten Repo-Pfad und lässt sich per Invariante 1 nicht von Hand reparieren. Die
   erste Einschätzung lautete `1.9.0` und wurde von Torben korrigiert; die Lücke in der Doku,
   die dazu führte - MAJOR ist dort als Inhaltsmigration statt als Kompatibilitätsbruch
-  beschrieben - liegt als Issue #26. Verzeichnet in `CHANGES.md` (`2.0.0`).
+  beschrieben - war Issue #26 und wurde in `2.5.0` geschlossen (siehe [[KB Stack Versioning]]).
+  Verzeichnet in `CHANGES.md` (`2.0.0`).
 - 2026-08-31 - `1.8.1` (Commit `a243a4a`, Korrektur `2b7b3cb`): Test-Coverage wird in CI
   gemessen und als Artefakt ausgewiesen, ohne `--cov-fail-under` - siehe
   Messen vor Schwelle. Die Messung deckte einen `dist export`-Fehler auf: Coverage-Ausgabe
@@ -228,6 +229,7 @@ Repositorys selbst und keine Aussagen aus einer Rohdatenquelle; der Änderungsda
 - [[Publish-Remote Gate]]
 - [[Source - Private-Instance Merge Correction and Issue 30 Session 2026-09-01]]
 - [[MCP-Leseserver]]
+- [[Source - Version Part Nomenclature and Breaking Change Gate Session 2026-09-02]]
 
 ## Fußnoten
 

kb/entities/tools/wikitool.md

@@ -5,11 +5,11 @@ tags: [cli, automation, deterministic, wiki-management]
 created: 2026-08-03
 modified: 2026-09-02
 related: [Semantic Lint Automation, Session Orientation, Iteration and Cost Limits, KB Stack Versioning, KB Migration, Personalization Plane, Detect-Repair Asymmetry, Write-Once Frontmatter Fields, Denylist over Allowlist, Command Round-Trip Integrity, Green Suite Blind Spot, Ambient Environment Dependency, Structural Enforcement over Documented Rule, Optional Instance Context File, MCP-Leseserver]
-sources: [Source - LLM Improvements Codex Analysis, Source - LLM Improvements Sonnet Analysis, Source - Copilot Skill Restructure Instructions, Source - Conversation - AGENTS.md Skill Restructuring Session 2026-08-04, Source - LLM Improvements Production Agent Gaps 2026, Source - Conversation - Versioning CI-CD and Content Migration Session 2026-08-30, Source - Conversation - Comma Bug Budget Refund and Lint Report Path Session 2026-08-31, Source - Conversation - Issue Triage Labels and TODO Retirement Session 2026-08-31, Source - Conversation - Auto Mode and Tool Choice Session 2026-08-31, Source - Conversation - Write-Once Frontmatter Fields and touch --set Session 2026-08-31, Source - Conversation - Gate Counting and Measured Calibration Session 2026-08-31, Source - Conversation - Two Round-Trip Defects Found by an Ingest Session 2026-08-31, Source - Conversation - Hardening the Test Suite Against Silent Environment Dependencies Session 2026-08-31, Source - Conversation - ENVIRONMENT.md as an Optional Third Session-Level File Session 2026-08-31, 'Source - Public Release, Corpus Purge and History Squash Session 2026-09-01', Source - Publish-Remote Gate and Issue Triage Session 2026-09-01, Source - Private-Instance Merge Correction and Issue 30 Session 2026-09-01, Source - MCP Read Server Implementation Session 2026-09-02]
+sources: [Source - LLM Improvements Codex Analysis, Source - LLM Improvements Sonnet Analysis, Source - Copilot Skill Restructure Instructions, Source - Conversation - AGENTS.md Skill Restructuring Session 2026-08-04, Source - LLM Improvements Production Agent Gaps 2026, Source - Conversation - Versioning CI-CD and Content Migration Session 2026-08-30, Source - Conversation - Comma Bug Budget Refund and Lint Report Path Session 2026-08-31, Source - Conversation - Issue Triage Labels and TODO Retirement Session 2026-08-31, Source - Conversation - Auto Mode and Tool Choice Session 2026-08-31, Source - Conversation - Write-Once Frontmatter Fields and touch --set Session 2026-08-31, Source - Conversation - Gate Counting and Measured Calibration Session 2026-08-31, Source - Conversation - Two Round-Trip Defects Found by an Ingest Session 2026-08-31, Source - Conversation - Hardening the Test Suite Against Silent Environment Dependencies Session 2026-08-31, Source - Conversation - ENVIRONMENT.md as an Optional Third Session-Level File Session 2026-08-31, 'Source - Public Release, Corpus Purge and History Squash Session 2026-09-01', Source - Publish-Remote Gate and Issue Triage Session 2026-09-01, Source - Private-Instance Merge Correction and Issue 30 Session 2026-09-01, Source - MCP Read Server Implementation Session 2026-09-02, Source - Version Part Nomenclature and Breaking Change Gate Session 2026-09-02]
 confidence: 0.90
 confidence_base: 0.90
 provenance: sourced
-summary: Deterministisches CLI fuer alle mechanischen Wiki-Operationen; seit 2.0.0 im Paket chemenu, seit 2.4.0 zusaetzlich als MCP-Leseserver erreichbar
+summary: Deterministisches CLI fuer alle mechanischen Wiki-Operationen; seit 2.0.0 im Paket chemenu, seit 2.4.0 zusaetzlich als MCP-Leseserver erreichbar, seit 2.5.0 mit Breaking-Change-Pflichtmarker
 ---
 # wikitool
 
@@ -86,8 +86,15 @@ wikitool bietet die folgenden Befehlskategorien:
 - **Veröffentlichung:** `publish` - zählt seit `1.5.0` nur noch Dateien, die eine Entscheidung tragen: Pfade unter `work/` und generierte Dateien (`kb/index.md`, `kb/log.md`, `kb/provenance.md`, jede `INDEX.md`) werden committet und gepusht, aber nicht gegen die Schwelle gezählt; die Weigerungszeile weist beide Gründe getrennt aus[^s-conversation-gate-counting-and-measured-calibration-session-2026-08-31]. Siehe [[Mass-Update Gate]]
 - **Budget:** `budget status`, `budget reset` - Obergrenze seit `1.2.0` 60 Aufrufe je Sitzung; ein Aufruf, der über `_util.fail()` abgelehnt wurde, bekommt seinen Slot zurück und bleibt trotzdem in `recent`, damit der Loop-Breaker ihn sieht[^s-conversation-comma-bug-budget-refund-and-lint-report-path-session-2026-08-31]. Siehe [[Iteration and Cost Limits]]
 - **Versionierung:** `version bump`, `version check` - `bump` schreibt die Stack-Version in die
-  Wurzeldatei `VERSION` und verweigert einen `MAJOR`-Sprung ohne Migrationsdokument, sofern er
+  Wurzeldatei `VERSION`. Kompatibilität (ist die neue Version ein Drop-in-Ersatz - vorwärts ohne
-  nicht ausdrücklich mit `--no-migration "<Begründung>"` gesetzt wird; `check` ist der einzige
+  Handarbeit, rückwärts noch downgradebar) und Inhaltsmigration sind seit `2.5.0` zwei getrennte
+  Fragen: ein Grenzübertritt verlangt zwingend `--breaking "<was aufhört zu funktionieren>"`,
+  verweigert auf jedem anderen Bump, und *zusätzlich* entweder ein Migrationsdokument oder
+  `--no-migration "<Begründung>"`, wenn `kb/` unangetastet bleibt. Beide Marker landen als
+  eigene Zeile im `CHANGES.md`-Eintrag (`**Breaking Change:**` vor `**Migration:**`) und werden
+  von `docs verify` unabhängig
+  voneinander geprüft[^s-version-part-nomenclature-and-breaking-change-gate-session-2026-09-02].
+  Siehe [[KB Stack Versioning]]. `check` ist der einzige
   Befehl, der einen Netzaufruf machen darf - ohne Schlüssel, mit Timeout und injizierbarem
   Fetch, damit Tests nie ein Netz
   berühren[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30]
@@ -151,6 +158,19 @@ ist[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30].
 
 ## Historie
 
+- 2026-09-02 - `2.5.0` (Commit `31662dc`, 806 Tests grün, 6 neu): Gitea-Issue #26 geschlossen.
+  `instructions/dev/version-parts.md` (neu, `instructions/dev/` - kein Verweis aus einem
+  ausgelieferten Artefakt, `instructions verify` hätte einen dangelnden Verweis nach
+  `dist export` gemeldet) trennt die Kompatibilitäts- von der Migrationsfrage: Drop-in-Test in
+  beiden Richtungen, Katalog der Brüche mit unangetastetem `kb/` (Update-Pfad, Artefaktname,
+  Import-Name, Flag/Envvar, Shape einer maschinengelesenen Datei), `2.0.0` als Fallbeispiel.
+  `version bump` bekommt `--breaking "<was aufhört zu funktionieren>"`, bei jedem
+  Grenzübertritt Pflicht und auf jedem anderen Bump verweigert; `docs verify` prüft das über
+  eine zweite, von der Migrationsprüfung unabhängige Regel. `stack-dev` bekommt einen
+  Entscheidungspunkt: kein Grenzübertritt aus eigener Initiative, erst Bruch, Handarbeit je
+  Instanz und Alternativen (Shim, aufschieben/bündeln, kompatibel/brechend mit
+  Deprecation-Fenster aufspalten) vorlegen, dann
+  Freigabe[^s-version-part-nomenclature-and-breaking-change-gate-session-2026-09-02].
 - 2026-09-02 - `2.2.3`-`2.4.1`: die vierstufige Sequenz aus Issue #36 (Publish-Remote-Gate
   scharf, Lesepfad gehärtet, Root-Auflösung und Bibliotheksgrenze, [[MCP-Leseserver]]) plus
   Menschendoku. `.wikitool-remotes.json` war trotz gegenteiliger Dokumentation nicht gesetzt -
@@ -303,3 +323,4 @@ ist[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30].
 [^s-public-release-corpus-purge-and-history-squash-session-2026-09-01]: [[Source - Public Release, Corpus Purge and History Squash Session 2026-09-01]]
 [^s-publish-remote-gate-and-issue-triage-session-2026-09-01]: [[Source - Publish-Remote Gate and Issue Triage Session 2026-09-01]]
 [^s-mcp-read-server-implementation-session-2026-09-02]: [[Source - MCP Read Server Implementation Session 2026-09-02]]
+[^s-version-part-nomenclature-and-breaking-change-gate-session-2026-09-02]: [[Source - Version Part Nomenclature and Breaking Change Gate Session 2026-09-02]]

kb/index.md

@@ -13,11 +13,11 @@ The page tables live in a generated `INDEX.md` inside each collection, linked be
 
 ## Statistics
 
-- **Total Pages:** 179
+- **Total Pages:** 180
 - **Comparisons:** 1
 - **Concepts:** 80
 - **Entities:** 72
-- **Sources:** 26
+- **Sources:** 27
 - **Last Updated:** 2026-09-02
 
 ---
@@ -29,7 +29,7 @@ The page tables live in a generated `INDEX.md` inside each collection, linked be
 | `comparisons/` | 1 | [comparisons/INDEX.md](comparisons/INDEX.md) |
 | `concepts/` | 80 | [concepts/INDEX.md](concepts/INDEX.md) |
 | `entities/` | 72 | [entities/INDEX.md](entities/INDEX.md) |
-| `sources/` | 26 | [sources/INDEX.md](sources/INDEX.md) |
+| `sources/` | 27 | [sources/INDEX.md](sources/INDEX.md) |
 
 ### entities/
 

kb/log.md

@@ -91,3 +91,9 @@ Direkt gegen tobi/qmd auf GitHub geprueft: TypeScript statt der geratenen 'Go od
 Aufgaben-Checkbox fuer die qmd.md-Korrektur nachgezogen (war [ ], ist erledigt) und ein Korrektur-Hinweis ergaenzt: der Fidelity-Block des Rohtranskripts kuendigte ein zweites Transkript fuer die qmd-Korrektur an, das nie geschrieben wurde - die Korrektur lief stattdessen als eigene Quellen-Verifikation. raw/ ist unveraenderlich, die Korrektur steht deshalb auf der Source-Seite.
 
 ---
+
+## [2026-09-02] ingest | raw/notes/Conversation Transcript - Version Part Nomenclature and Breaking Change Gate Session 2026-09-02.md
+
+Neue Source-Seite, Korrektur der veralteten MAJOR-als-Migration-Formulierung in wikitool.md und KB Stack Versioning.md, Nachtrag in Chemenu.md (Issue #26 geschlossen).
+
+---

kb/sources/INDEX.md

@@ -2,7 +2,7 @@
 
 # kb/sources/ - Index
 
-26 page(s). Regenerated by `wikitool index rebuild`.
+27 page(s). Regenerated by `wikitool index rebuild`.
 
 ## All
 
@@ -33,5 +33,6 @@
 | [[Source - Public Release, Corpus Purge and History Squash Session 2026-09-01]] | notes | Sitzung, die den Chemenu-Stack von einer privaten Testinstanz in ein oeffentliches Repo ueberfuehrt: Korpus geloescht statt anonymisiert, Git-History auf einen Commit gesquashed, AGPL-3.0/CC-BY-4.0-Dual-Lizenz gewaehlt, dist export um einen Leak-Canary gehaertet. | 2026-09-01 |
 | [[Source - Publish-Remote Gate and Issue Triage Session 2026-09-01]] | notes | Sitzung, die ein drittes, Token-loses Gate fuer publish baut, instructions/private-instance.md schreibt, sechs Gitea-Issues auf den Rename und die neue Architektur nachzieht und die Actions-Run-Historie entfernen laesst. | 2026-09-01 |
 | [[Source - qmd - GitHub Repository]] | document | GitHub-API-Metadaten, package.json und README-Auszuege von tobi/qmd: TypeScript/Node/Bun statt Go oder Rust, BM25 (SQLite FTS5) plus Vektor-Suche (sqlite-vec) plus LLM-Reranking ueber node-llama-cpp. | 2026-09-02 |
+| [[Source - Version Part Nomenclature and Breaking Change Gate Session 2026-09-02]] | notes | Sitzung, die die Versionsstelle als Kompatibilitaets- statt Migrationsfrage praezisiert und einen Freigabe-Ablauf fuer Breaking Changes in stack-dev einfuehrt | 2026-09-02 |
 | [[Source - Wine]] | notes | Wine-Konfiguration für Arch Linux: pacman-NoExtract-Einstellungen und Bottles-Runtime-Optionen einschließlich Proton- und Lutris-Varianten. | 2026-08-01 |
 

kb/sources/Source - Version Part Nomenclature and Breaking Change Gate Session 2026-09-02.md

@@ -0,0 +1,75 @@
+---
+type: types/source.md
+source_type: notes
+author: Torben Nehmer
+raw_files: [raw/notes/Conversation Transcript - Version Part Nomenclature and Breaking Change Gate Session 2026-09-02.md]
+source_language: de
+date: 2026-09-02
+tags: []
+entities: [wikitool, Chemenu]
+concepts: [KB Stack Versioning]
+summary: Sitzung, die die Versionsstelle als Kompatibilitaets- statt Migrationsfrage praezisiert und einen Freigabe-Ablauf fuer Breaking Changes in stack-dev einfuehrt
+---
+# Source: Version Part Nomenclature and Breaking Change Gate Session 2026-09-02
+
+**Autor:** Torben Nehmer  
+**Datum:** 2026-09-02  
+**Raw-Dateien:** raw/notes/Conversation Transcript - Version Part Nomenclature and Breaking Change Gate Session 2026-09-02.md  
+**Typ:** Notes
+
+## Zusammenfassung
+
+Umsetzung von Gitea-Issue #26: Die Doku des Stacks führte für die Wahl der Versionsstelle zwei
+Fragen zusammen, die nicht dieselbe sind - ob der Korpus migriert werden muss, und ob der
+Wechsel ein Drop-in-Ersatz ist. Nur `version bump --help` unterschied korrekt; die drei
+prosaischen Stellen (`stack-dev`, `version.py`-Docstring, `INSTALL.md`) beschrieben MAJOR als
+Migrationsfrage. Der `2.0.0`-Rebranding-Bump hatte genau daran zuerst `1.9.0` statt `--major`
+angesetzt.
+
+Der Nutzer schärfte die Regel während der Sitzung zu einem konkreten zweiseitigen Test nach:
+"die neue version ist kein drop-in replacement. Sobald irgendwie Hand angelegt werden muss, sei
+es durch den user oder durch ein Migrationsscript, ist es ein major version change. selbiges
+gilt, wenn ein update nicht rückgängig gemacht werden kann [...] in allen Fällen muss bei einem
+Major version change ein 'Breaking Change' vermerkt werden. breaking changes sind damit teuer.
+passe stack-dev so an, dass in diesen Fällen zwingend der user informiert, Alternativen
+aufgezeigt und eine freigabe eingeholt wird." Zwei Auswahlentscheidungen davor: Durchsetzung im
+Code statt reiner Prosa (weil Prosa bereits einmal gedriftet war), und die Freigabe als
+"Decision point" statt als Gate-Sprache, um die drei echten code-erzwungenen Gates nicht zu
+verwässern.
+
+## Kernaussagen
+
+- Kompatibilität (Drop-in-Ersatz, vorwärts wie rückwärts) und Inhaltsmigration sind zwei
+  unabhängige Fragen; MAJOR beantwortet die erste, `--no-migration`/ein Migrationsdokument die
+  zweite.
+- Ein Grenzübertritt kann `kb/` völlig unangetastet lassen und trotzdem MAJOR sein - Katalog:
+  Update-Pfad, Release-Artefaktname, Paket-Import-Name, ein umbenanntes Kommando/Flag/Envvar,
+  die Shape einer maschinengelesenen Datei.
+- Ein Breaking Change ist teuer (jede bestehende Instanz zahlt einmal, von Hand) und deshalb
+  genehmigungspflichtig: Bruch, Handarbeit je Instanz und Alternativen (Shim, aufschieben und
+  bündeln, aufspalten mit Deprecation-Fenster) vorlegen, dann Freigabe abwarten.
+- Reine Prosa-Regeln drifted - deshalb wurde `--breaking` als Pflichtflag samt zweiter, von der
+  Migrationsprüfung unabhängiger `docs verify`-Prüfung eingeführt, nicht nur eine Textänderung.
+
+## Aufgaben
+
+Keine offenen Aufgaben aus dieser Sitzung - Issue #26 wurde in derselben Sitzung geschlossen,
+mit Verweis auf Commit `31662dc` (`2.5.0`).
+
+## Nicht übernommen
+
+- Die vollständige Katalog-Tabelle und der `2.0.0`-Fallbeispiel-Text aus
+  `instructions/dev/version-parts.md` werden hier nicht wiederholt - die Datei ist die
+  autoritative Quelle (Instruktions-Layer, `manual`-artig durch die `instructions/dev/`-Grenze),
+  diese Source-Seite fasst nur zusammen, was zur Entscheidung führte.
+- Der genaue Wortlaut der Tool-Fehlermeldungen (`version bump`-Refusals) steht im Transkript
+  selbst; hier nur die Regel dahinter.
+
+## Verwandte Entities
+
+- [[wikitool]]
+- [[Chemenu]]
+
+## Verwandte Concepts
+
+- [[KB Stack Versioning]]

raw/notes/Conversation Transcript - Version Part Nomenclature and Breaking Change Gate Session 2026-09-02.md

@@ -0,0 +1,218 @@
+# Conversation Transcript - Version Part Nomenclature and Breaking Change Gate Session
+
+> Source: Claude Code session (`claude-sonnet-5`), chemenu workspace
+> Collected: 2026-09-02
+> Participant: Torben Nehmer
+> Fidelity: **faithful summary transcript, not a verbatim log.** The user's instructions and
+> clarifications are quoted verbatim; the agent's own reasoning and file-reading steps are
+> paraphrased; tool output blocks (`docs verify`, `pytest`, `version bump --dry-run`, the
+> Mass-Update Gate refusal) are real, copied from the actual run, not reconstructed.
+> No second-hand material - no subagent was used.
+> No credentials appeared.
+> Single topic, not cut.
+
+Closes Gitea issue #26 (already closed in-session) with `2.5.0`. Commit `31662dc` on `main`.
+Covers picking the version part for a stack change, and adding a user-approval gate for
+breaking changes to `stack-dev`.
+
+## Turn 1 - `/stack-dev kümmere dich um #26`
+
+The user invoked the `stack-dev` skill with the argument `kümmere dich um #26`. The agent read
+issue #26 via `gitea-mcp` (`torben/chemenu#26`, no comments yet).
+
+**The issue's own account** (quoted from its body, since it is the source of the whole
+session): the stack's documentation conflated two questions when choosing a version bump part -
+"Muss der Korpus migriert werden?" and "Ist der Wechsel rückwärtskompatibel?" - and every place
+an agent would consult before a bump stated only the first:
+
+| Ort | Wortlaut |
+|---|---|
+| `instructions/dev/stack-dev/SKILL.md`, Schritt 3 | `--major` ⇔ "Existing content must be migrated" |
+| `tools/chemenu/version.py`, module docstring | "from `1.0.0` on the same rule reads as the familiar 'MAJOR means migration'" |
+| `INSTALL.md` § Version und Updates | "ab `1.0.0` liest sich dieselbe Regel als das gewohnte 'MAJOR heißt Migration'" |
+
+Only `version bump --help` had it right ("A bump that crosses the compatibility boundary
+additionally requires a migration document ... or `--no-migration`") - the one place read only
+after the decision is already made.
+
+The issue's worked example was the `2.0.0` rebranding (`torben/llm-wiki-test1` →
+`torben/chemenu`): no page in `kb/` changed, so the first attempt at that bump was `1.9.0`. Three
+things broke anyway - the release-feed URL baked into every existing instance's
+`.wikitool-release.json` (unrepairable by hand, per invariant 1), the release artefact's
+filename, and the Python package's import name. The correct bump was `--major --no-migration`.
+The issue's "Was 'fertig' heißt" checklist asked for: rewording the three prose locations to
+lead with compatibility rather than migration, a decision aid enumerating which kinds of break
+force MAJOR even with `kb/` untouched, and a check that the three locations do not end up
+contradicting each other (invariant 8). It explicitly scoped out teaching `docs verify` to judge
+*whether* a bump chose the right part - "das ist eine Urteilsfrage und kein hartes Orakel."
+
+The agent read the three prose locations plus `tools/chemenu/commands/version_cmd.py` (the
+existing `--no-migration` enforcement) and `docs_verify.py` (`check_migration_for_boundary`), to
+scope the fix before writing anything.
+
+## Turn 2 - scope questions, then the user's clarification
+
+Before writing, the agent asked two `AskUserQuestion` questions:
+
+1. Whether the "Breaking Change" marker and approval requirement should be prose-only or also
+   enforced in the tool. Options offered: "Prosa + Marker im Code (Empfehlung)" vs. "Nur Prosa".
+   **User picked the enforced option** ("Prosa + Marker im Code (Empfehlung)") - a
+   `--breaking` flag on `version bump`, checked by `docs verify`, on the reasoning that a
+   pure-prose rule is exactly what drifted in the first place.
+2. Whether the pre-bump approval step should read like one of the codebase's actual gates
+   (`instructions/gates.md` language: "anhalten ... auf ausdrückliche Freigabe warten") or as a
+   softer "Decision points" entry. **User picked the softer framing** ("Als Entscheidungspunkt")
+   - explicitly *not* gate language, to avoid diluting the weight of the three real,
+   code-enforced gates (Mass-Update, Publish-Remote, Iteration Budget) by association.
+
+The user then added the clarification that drove the rest of the session, quoted in full:
+
+> "genaue nomenklatur für major version change: die neue version ist kein drop-in replacement.
+> Sobald irgendwie Hand angelegt werden muss, sei es durch den user oder durch ein
+> Migrationsscript, ist es ein major version change. selbiges gilt, wenn ein update nicht
+> rückgängig gemacht werden kann (Szenario: User aktualisiert den Stack von vA nach vB, vB hat
+> beim User ein Problem, kann jetzt vA nicht mehr einfach so als Downgrade installiert werden,
+> ist es ein breaking change)
+> in allen Fällen muss bei einem Major version change ein "Breaking Change" vermerkt werden.
+> breaking changes sind damit teuer. passe stack-dev so an, dass in diesen Fällen zwingend der
+> user informiert, Alternativen aufgezeigt und eine freigabe eingeholt wird."
+
+This sharpened the issue's "compatibility" question into a concrete two-sided test - **forward**
+(can the new version be copied over with zero hand-work, by user or script) and **backward** (can
+the old version still be reinstalled afterwards) - and made explicit that either half failing,
+independent of `kb/`, is what MAJOR actually means.
+
+## Turn 3 - what was written
+
+**`instructions/dev/version-parts.md` (new).** The single source for the rule. Structure:
+the two-sided drop-in test (step 1); a catalogue of breaks that cross the boundary with `kb/`
+untouched - update path, release-artefact name, package import name, a renamed
+command/flag/envvar, the shape of a machine-read file like `.wikitool-kb.json` (step 2); the
+plain compatible-part table for patch/minor (step 3); the mandatory stop-and-inform-the-user
+step before any boundary-crossing bump, with three named alternatives (avoid via a
+compatibility shim, defer and batch with the next crossing, split into a compatible half now
+and a deprecated-then-removed half later) plus a recommendation (step 4); `--breaking` usage
+(step 5); the pre-existing migration-document-or-`--no-migration` step, now explicitly
+independent of compatibility (step 6); writing the entry body (step 7). Closes with the `2.0.0`
+case study as the worked example, matching the issue's own account.
+
+Placed under `instructions/dev/` (not linked from any distributed artifact) because
+`tools/wikitool dist export` prunes that directory wholesale - the agent's first draft linked to
+it from `tools/CONTRACT.md` and the `version.py` docstring, which `tools/wikitool instructions
+verify` correctly rejected:
+
+```
+ERROR Instruction layer issues:
+  - version-parts.md: lives under instructions/dev/ but is referenced from
+outside it and outside a dist:strip block - `dist export` removes
+instructions/dev/ wholesale, so that reference would dangle in a distributed
+instance. Remove the reference, or wrap it in a <!-- dist:strip-start/end -->
+block if it belongs only to this dev instance.
+```
+
+**Rejected approach:** wrapping the reference in `<!-- dist:strip-start/end -->` markers so it
+would still resolve in this repo. Not used - the agent instead rewrote the three shipped
+locations (`tools/CONTRACT.md`, `version.py` docstring, `version_cmd.py` docstring) to state the
+short form of the rule standalone, with no pointer to the dev-only file, since a shipped
+instance never has it to point to.
+
+**`instructions/dev/stack-dev/SKILL.md`.** Step 3's table changed from "Existing content must
+be migrated → `--major`" to "Not a drop-in replacement ... → `--major`", with a pointer to
+`version-parts.md` for the full test and catalogue. A new "Decision points" entry: if a change
+turns out not to be a drop-in replacement, stop - do not bump across the boundary on the
+session's own initiative; show the user the concrete break, what each instance must do, and the
+three alternatives from `version-parts.md` step 4, then wait for a go-ahead. Written in the
+softer "Decision points" register per the user's second answer above, not gate language.
+
+**`tools/chemenu/version.py`.** Module docstring reworded: "MAJOR means migration" → "MAJOR
+breaks", with a new paragraph stating the two questions are independent and naming both markers.
+New constant `BREAKING_CHANGE_MARKER = "**Breaking Change:**"`, alongside the existing
+`MIGRATION_NONE_MARKER`. `insert_changes_entry()` gained a `breaking_reason` parameter, writing
+the `**Breaking Change:**` line *before* the migration line - the break is what an operator acts
+on first.
+
+**`tools/chemenu/commands/version_cmd.py`.** `bump` gained `--breaking TEXT`. Refused on a
+non-boundary-crossing bump; required on a boundary-crossing one, with a refusal message that
+also second-guesses the part choice itself: *"If that sentence is hard to write because nothing
+actually breaks - no hand-work on update, and the old version can still be put back - then the
+bump is probably not --major."* Verified live:
+
+```
+$ tools/wikitool version bump --major --title "smoke" --dry-run
+ERROR 2.4.1 -> 3.0.0 crosses the compatibility boundary, so it is not a drop-in
+replacement - re-run with --breaking "<what stops working, and what an instance
+must do about it>".
+If that sentence is hard to write because nothing actually breaks - no
+hand-work on update, and the old version can still be put back - then the
+bump is probably not --major.
+```
+
+```
+$ tools/wikitool version bump --minor --title "smoke" --breaking "x" --dry-run
+ERROR --breaking only applies to a bump that crosses the compatibility boundary;
+2.4.1 -> 2.5.0 does not.
+```
+
+**`tools/chemenu/commands/docs_verify.py`.** New `check_breaking_change_for_boundary()`,
+independent of the existing `check_migration_for_boundary()` on purpose - the two check
+different things (did the corpus move vs. was the operator told the swap isn't drop-in), and a
+crossing with `kb/` untouched can satisfy the first while failing the second. Wired into
+`verify()` alongside the existing check.
+
+**Tests.** `test_version_cmd.py`: nine existing calls updated for the new `breaking=` parameter,
+plus three new tests (`test_a_boundary_crossing_bump_without_breaking_is_refused`,
+`test_breaking_records_what_stops_working_in_the_changelog` - including the ordering assertion
+that `BREAKING_CHANGE_MARKER` precedes `MIGRATION_NONE_MARKER` in the rendered entry -
+`test_breaking_is_refused_on_a_compatible_bump`). `test_docs_verify.py`: four new tests mirroring
+the existing migration-boundary tests but for the breaking-change marker. Full suite: 806 passed.
+
+**`tools/CONTRACT.md` and `INSTALL.md`.** Both reworded to lead with the drop-in question and
+treat migration as the second, independent one; `INSTALL.md` additionally tells the reader which
+two lines to look for in release notes (`Breaking Change:` and `Migration:`) before applying an
+update.
+
+**`CHANGES.md`.** New `2.5.0` entry written after the bump, body filled in by the agent (the
+tool leaves it empty by design) - includes the "what deliberately did not change" note that
+`docs verify` still does not judge *whether* the chosen part was correct, matching the issue's
+explicit scope-out.
+
+## Turn 4 - publish, twice
+
+`tools/wikitool version bump --minor --title "..."` was run first (11 changed files, drop-in in
+both directions - the new requirement only binds the *next* boundary crossing, not
+retroactively). `tools/wikitool publish --message "..."` then hit the **Mass-Update Gate**
+(11 counted files ≥ threshold 10):
+
+```
+NEEDS USER CLEARANCE Mass-Update Gate: this publish would commit and push 11
+counted files (>= threshold 10) to origin/main. ...
+```
+
+Per the gate's own instructions, the agent reproduced the full file-by-area breakdown and the
+`--confirm <token>` line in its reply and ran nothing further that turn. The user replied
+"freigegeben" for both the earlier publish authorization ("publish ist freigegeben") and, in a
+separate turn, this specific token. The agent then ran `tools/wikitool publish --confirm
+95ae372d5677 --message '...'`, which pushed commit `31662dc` to `origin/main`, and verified
+`git rev-parse HEAD origin/main` matched afterward.
+
+## Turn 5 - issue closeout and this capture
+
+The user asked to update issue #26 "wie vorgeschlagen" (per the agent's own end-of-turn
+suggestion), run `instructions/capture-session.md`, and in the same pass correct
+`kb/entities/tools/wikitool.md`. The agent posted a comment on #26 summarizing what shipped
+(including the parts that went beyond the issue's own checklist - the `--breaking` flag and the
+second `docs verify` check, added because plain prose was judged likely to drift again) and
+closed the issue. This transcript and the `kb/` correction are the remaining two steps of that
+request.
+
+## Outcome
+
+| | |
+|---|---|
+| Version | `2.4.1` → `2.5.0` (`--minor`: new capability, still drop-in both directions) |
+| Commit | `31662dc` on `main`, pushed to `origin` |
+| Files changed | 11 (+432/-33): `instructions/dev/version-parts.md` (new), `instructions/dev/stack-dev/SKILL.md`, `tools/CONTRACT.md`, `tools/chemenu/version.py`, `tools/chemenu/commands/version_cmd.py`, `tools/chemenu/commands/docs_verify.py`, `tools/chemenu/tests/test_version_cmd.py`, `tools/chemenu/tests/test_docs_verify.py`, `CHANGES.md`, `INSTALL.md`, `VERSION` |
+| Tests | 806 passed (`tools/chemenu/tests/`), including 6 new |
+| Verification | `tools/wikitool docs verify` OK, `tools/wikitool instructions verify` OK (17 instructions, 6 skills, 12 published copies match), `tools/wikitool doctor` clean (only the expected `WIKITOOL_SESSION_ID` WARN) |
+| Issues | #26 closed, comment `torben/chemenu#26` (issuecomment-474) |
+| CI | Not yet observed in this session - a `VERSION` move on `main` triggers a tagged release per `.gitea/workflows/release.yml`; not polled |