diff --git a/kb/concepts/INDEX.md b/kb/concepts/INDEX.md index 437700b..398980d 100644 --- a/kb/concepts/INDEX.md +++ b/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 | diff --git a/kb/concepts/KB Stack Versioning.md b/kb/concepts/KB Stack Versioning.md index 12bb38f..69a1881 100644 --- a/kb/concepts/KB Stack Versioning.md +++ b/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 - einheitlich formuliert und musste beim Wechsel auf `1.0.0` nicht angefasst + Signal trägt wie `MAJOR` ab `1.0.0`. Der Code für den `compat_key` ist deshalb einheitlich + 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 ""`, 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]] diff --git a/kb/entities/INDEX.md b/kb/entities/INDEX.md index efca298..7314fe1 100644 --- a/kb/entities/INDEX.md +++ b/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 | diff --git a/kb/entities/projects/Chemenu.md b/kb/entities/projects/Chemenu.md index 6b7560e..caf3dcb 100644 --- a/kb/entities/projects/Chemenu.md +++ b/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 diff --git a/kb/entities/tools/wikitool.md b/kb/entities/tools/wikitool.md index 5004a40..98a888e 100644 --- a/kb/entities/tools/wikitool.md +++ b/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 - nicht ausdrücklich mit `--no-migration ""` gesetzt wird; `check` ist der einzige + Wurzeldatei `VERSION`. Kompatibilität (ist die neue Version ein Drop-in-Ersatz - vorwärts ohne + Handarbeit, rückwärts noch downgradebar) und Inhaltsmigration sind seit `2.5.0` zwei getrennte + Fragen: ein Grenzübertritt verlangt zwingend `--breaking ""`, + verweigert auf jedem anderen Bump, und *zusätzlich* entweder ein Migrationsdokument oder + `--no-migration ""`, 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 ""`, 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]] diff --git a/kb/index.md b/kb/index.md index 335abe1..ff23052 100644 --- a/kb/index.md +++ b/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/ diff --git a/kb/log.md b/kb/log.md index cc01fea..5ecce6d 100644 --- a/kb/log.md +++ b/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). + +--- diff --git a/kb/sources/INDEX.md b/kb/sources/INDEX.md index ea0cbc0..efb6a70 100644 --- a/kb/sources/INDEX.md +++ b/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 | diff --git a/kb/sources/Source - Version Part Nomenclature and Breaking Change Gate Session 2026-09-02.md b/kb/sources/Source - Version Part Nomenclature and Breaking Change Gate Session 2026-09-02.md new file mode 100644 index 0000000..32f1d7e --- /dev/null +++ b/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]] diff --git a/raw/notes/Conversation Transcript - Version Part Nomenclature and Breaking Change Gate Session 2026-09-02.md b/raw/notes/Conversation Transcript - Version Part Nomenclature and Breaking Change Gate Session 2026-09-02.md new file mode 100644 index 0000000..d37b824 --- /dev/null +++ b/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 +block if it belongs only to this dev instance. +``` + +**Rejected approach:** wrapping the reference in `` 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 "". +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 ` 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 |