kb/concepts/ bekommt Areas: layout: fuer concept, Area-Titel aus jedem Type-Spec, Schwellen-Empfehlung im lint (schliesst #59)

Files changed: - CHANGES.md - README.md - VERSION - kb/concepts/Ambient Environment Dependency.md - kb/concepts/Anti-Cramming Heuristic.md - kb/concepts/Audit Trail.md - kb/concepts/BM25.md - kb/concepts/Bulk Operations.md - kb/concepts/CI Integration.md - kb/concepts/COLLECTION.md - kb/concepts/CPPC.md - kb/concepts/Checkpoint Audit.md - kb/concepts/Claude Code Auto Mode.md - kb/concepts/Command Round-Trip Integrity.md - kb/concepts/Confidence Scoring.md - kb/concepts/Consolidation Tiers.md - kb/concepts/Content Quality Control.md - kb/concepts/Context Isolation.md - kb/concepts/Contradiction Resolution.md - kb/concepts/Cross-platform Agent Skills.md - kb/concepts/Crystallization.md - kb/concepts/Delete Rather Than Anonymize.md - kb/concepts/Denylist over Allowlist.md - kb/concepts/Detect-Repair Asymmetry.md - kb/concepts/Diff-Reviewable Agent Edits.md - kb/concepts/Dual Licensing by File Plan.md - kb/concepts/Entity Extraction.md - kb/concepts/Episodic Memory.md - kb/concepts/Event-Driven Automation.md - kb/concepts/Filter on Ingest.md - kb/concepts/Forgetting.md - kb/concepts/Graph Traversal.md - kb/concepts/Green Suite Blind Spot.md - kb/concepts/Hooks.md - kb/concepts/Hybrid Search.md - kb/concepts/INDEX.md - kb/concepts/Implementation Spectrum.md - kb/concepts/Index Scaling.md - kb/concepts/Issue Label Scheme.md - kb/concepts/Iteration and Cost Limits.md - kb/concepts/KB Migration.md - kb/concepts/KB Stack Versioning.md - kb/concepts/Knowledge Compounding.md - kb/concepts/Knowledge Graph.md - kb/concepts/LLM Wiki Pattern.md - kb/concepts/Lint Workflow.md - kb/concepts/MCP-Leseserver.md - kb/concepts/Mass-Update Gate.md - kb/concepts/Memory Lifecycle.md - kb/concepts/Mesh Sync.md - kb/concepts/Modbus.md - kb/concepts/Multi-Agent Collaboration.md - kb/concepts/Naming Convention Conflict.md - kb/concepts/OKF Compatibility.md - kb/concepts/Optional Instance Context File.md - kb/concepts/Personalization Plane.md - kb/concepts/Privacy and Governance.md - kb/concepts/Procedural Memory.md - kb/concepts/Publish-Remote Gate.md - kb/concepts/Quality Scoring.md - kb/concepts/Quality and Self-Correction.md - kb/concepts/RAG.md - kb/concepts/Reciprocal Rank Fusion.md - kb/concepts/SSD TRIM.md - kb/concepts/Scale Ceiling.md - kb/concepts/Self-Healing.md - kb/concepts/Semantic Lint Automation.md - kb/concepts/Semantic Memory.md - kb/concepts/Session Orientation.md - kb/concepts/Shared vs Private.md - kb/concepts/Split Merge Reclassify.md - kb/concepts/Split Threshold.md - kb/concepts/Structural Enforcement over Documented Rule.md - kb/concepts/Stub Threshold.md - kb/concepts/Supersession.md - kb/concepts/Three-Layer Architecture.md - kb/concepts/Token Economics.md - kb/concepts/Typed Relationships.md - kb/concepts/User Management.md - kb/concepts/Vector Search.md - kb/concepts/Work Coordination.md - kb/concepts/Workflow Extraction.md - kb/concepts/Workflow Orchestration.md - kb/concepts/Working Memory.md - kb/concepts/Write-Once Frontmatter Fields.md - kb/concepts/architectures/Consolidation Tiers.md - kb/concepts/architectures/Context Isolation.md - kb/concepts/architectures/Cross-platform Agent Skills.md - kb/concepts/architectures/Episodic Memory.md - kb/concepts/architectures/Hybrid Search.md - kb/concepts/architectures/Implementation Spectrum.md - kb/concepts/architectures/Knowledge Graph.md - kb/concepts/architectures/LLM Wiki Pattern.md - kb/concepts/architectures/MCP-Leseserver.md - kb/concepts/architectures/Memory Lifecycle.md - kb/concepts/architectures/OKF Compatibility.md - kb/concepts/architectures/Optional Instance Context File.md - kb/concepts/architectures/Personalization Plane.md - kb/concepts/architectures/Procedural Memory.md - kb/concepts/architectures/RAG.md - kb/concepts/architectures/Scale Ceiling.md - kb/concepts/architectures/Semantic Memory.md - kb/concepts/architectures/Three-Layer Architecture.md - kb/concepts/architectures/Token Economics.md - kb/concepts/architectures/Working Memory.md - kb/concepts/decisions/Delete Rather Than Anonymize.md - kb/concepts/decisions/Denylist over Allowlist.md - kb/concepts/decisions/Diff-Reviewable Agent Edits.md - kb/concepts/decisions/Dual Licensing by File Plan.md - kb/concepts/decisions/Issue Label Scheme.md - kb/concepts/decisions/KB Stack Versioning.md - kb/concepts/decisions/Structural Enforcement over Documented Rule.md - kb/concepts/patterns/Audit Trail.md - kb/concepts/patterns/BM25.md - kb/concepts/patterns/Command Round-Trip Integrity.md - kb/concepts/patterns/Confidence Scoring.md - kb/concepts/patterns/Contradiction Resolution.md - kb/concepts/patterns/Entity Extraction.md - kb/concepts/patterns/Filter on Ingest.md - kb/concepts/patterns/Forgetting.md - kb/concepts/patterns/Graph Traversal.md - kb/concepts/patterns/Mesh Sync.md - kb/concepts/patterns/Quality Scoring.md - kb/concepts/patterns/Reciprocal Rank Fusion.md - kb/concepts/patterns/Self-Healing.md - kb/concepts/patterns/Shared vs Private.md - kb/concepts/patterns/Typed Relationships.md - kb/concepts/patterns/Vector Search.md - kb/concepts/patterns/Work Coordination.md - kb/concepts/problems/Ambient Environment Dependency.md - kb/concepts/problems/Detect-Repair Asymmetry.md - kb/concepts/problems/Green Suite Blind Spot.md - kb/concepts/problems/Naming Convention Conflict.md - kb/concepts/problems/Write-Once Frontmatter Fields.md - kb/concepts/protocols/CPPC.md - kb/concepts/protocols/Modbus.md - kb/concepts/protocols/SSD TRIM.md - kb/concepts/workflows/Anti-Cramming Heuristic.md - kb/concepts/workflows/Bulk Operations.md - kb/concepts/workflows/CI Integration.md - kb/concepts/workflows/Checkpoint Audit.md - kb/concepts/workflows/Claude Code Auto Mode.md - kb/concepts/workflows/Content Quality Control.md - kb/concepts/workflows/Crystallization.md - kb/concepts/workflows/Event-Driven Automation.md - kb/concepts/workflows/Hooks.md - kb/concepts/workflows/Index Scaling.md - kb/concepts/workflows/Iteration and Cost Limits.md - kb/concepts/workflows/KB Migration.md - kb/concepts/workflows/Knowledge Compounding.md - kb/concepts/workflows/Lint Workflow.md - kb/concepts/workflows/Mass-Update Gate.md - kb/concepts/workflows/Multi-Agent Collaboration.md - kb/concepts/workflows/Privacy and Governance.md - kb/concepts/workflows/Publish-Remote Gate.md - kb/concepts/workflows/Quality and Self-Correction.md - kb/concepts/workflows/Semantic Lint Automation.md - kb/concepts/workflows/Session Orientation.md - kb/concepts/workflows/Split Merge Reclassify.md - kb/concepts/workflows/Split Threshold.md - kb/concepts/workflows/Stub Threshold.md - kb/concepts/workflows/Supersession.md - kb/concepts/workflows/User Management.md - kb/concepts/workflows/Workflow Extraction.md - kb/concepts/workflows/Workflow Orchestration.md - kb/index.md - kb/log.md - tools/CONTRACT.md - tools/README.md - tools/chemenu/catalog.py - tools/chemenu/commands/index_build.py - tools/chemenu/lint_core.py - tools/chemenu/tests/conftest.py - tools/chemenu/tests/test_cite_cmd.py - tools/chemenu/tests/test_git_publish.py - tools/chemenu/tests/test_index_build.py - tools/chemenu/tests/test_lint.py - tools/chemenu/tests/test_new_page.py - tools/chemenu/tests/test_provenance.py - tools/chemenu/tests/test_type_resolver.py - tools/chemenu/tests/test_xref.py - types/concept.md - types/type-spec.md
2026-09-08 10:07:46 +02:00
parent 63b4bb82d9
commit 7f74303a00
103 changed files with 703 additions and 180 deletions
@@ -0,0 +1,127 @@
+---
+type: types/concept.md
+concept_type: decision
+tags: [versioning, semver, release, stack]
+created: 2026-08-30
+modified: 2026-09-02
+related:
+  - mechanism: wikitool
+  - see-also: Issue Label Scheme
+  - see-also: CI Integration
+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 (Drop-in-Ersatz) und Inhaltsmigration sind seit 2.5.0 getrennte, unabhaengig geprueft Fragen'
+---
+# KB Stack Versioning
+
+**Typ:** Decision
+
+## Definition
+
+KB Stack Versioning ist die Entscheidung, den Wiki-**Stack** semantisch zu versionieren und
+diese Version strikt von der Form des Inhalts zu trennen. Die Stack-Version steht in der
+Wurzeldatei `VERSION` und wird ausschließlich von `wikitool version bump`
+geschrieben[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30]. Sie
+beantwortet genau eine Frage: welche Maschinerie installiert ist.
+
+Ein automatischer Bump aus Commit-Nachrichten wurde verworfen. `wikitool publish --message
+"ingest: ..."` schreibt Content-Commits in dasselbe Repository, sodass eine
+Conventional-Commit-Auswertung jeden Ingest zu einem Release
+machte[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30]. Der Bump ist
+deshalb eine ausdrückliche Handlung.
+
+## Kernpunkte
+
+- **Drei Fakten, drei Dateien.** `VERSION` trägt die Stack-Version und wird von `version bump`
+  geschrieben; `.wikitool-release.json` ist der Release-Stempel, den `dist export` in jeden
+  Export legt und der beantwortet, woher die Maschinerie stammt; `.wikitool-kb.json` trägt die
+  KB-Version und wird von `migrate done`
+  geschrieben[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30]. Die
+  Trennung ist keine Aufteilung aus Bequemlichkeit: Der Stempel ist erzeugt und darf nie von
+  Hand geändert werden, der KB-Zustand dagegen ist veränderlicher Instanzzustand.
+- **Kompatibilität ist die linkeste Nicht-Null-Komponente** - dieselbe Regel, die Cargos
+  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
+  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 "<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
+  werden[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30].
+- **Der Einstieg bei `1.0.0` statt `0.1.0`** beseitigte einen Selbstwiderspruch: Die Anleitung
+  in `stack-dev/SKILL.md` wies `--minor` sowohl „neue Fähigkeit" als auch „erfordert Migration"
+  zu, was unter `0.x` nicht beides zugleich stimmen
+  kann[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30].
+- **Aktualisierungserkennung über einen Stempel, nicht über eine Prüfsumme.**
+  `wikitool version check` darf als einziger Befehl einen Netzaufruf machen: eigener Befehl,
+  kein Schlüssel, Timeout, injizierbarer Fetch, damit Tests nie ein Netz
+  berühren[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30]. Der
+  Aktualisierungspfad selbst (`dist upgrade`) wurde bewusst zurückgestellt: erst Erkennung, dann
+  Ausführung.
+- **CI wird nicht mitgeliefert.** `runs-on: linux-docker` ist ein standortspezifisches
+  Runner-Label und gehört nicht in eine verteilte
+  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]. 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
+
+- [[Chemenu]] - erste Instanz; `1.0.0` ist die Migrationsbasis, `1.0.1` das erste über
+  die Pipeline veröffentlichte Release.
+- [[wikitool]] - trägt die Befehlsgruppen `version` und `migrate`, die die drei Dateien
+  schreiben und lesen.
+
+## Wann zu verwenden
+
+Sobald eine Wissensbasis als installierbares Artefakt an mehr als eine Stelle geht und
+Aktualisierungen erkennbar sein müssen. Die Trennung von Stack- und Content-Version lohnt sich
+ab dem Moment, in dem eine Instanz existiert, deren Inhalt hinter der Maschinerie zurückbleiben
+kann.
+
+## Wann NICHT zu verwenden
+
+- Nicht für den Inhalt. Eine Version, die Stack und Content zugleich beschreibt, macht den
+  Zustand „Maschinerie `1.4.0`, Inhalt in `1.2.0`-Form" unabbildbar - und das ist der Zustand,
+  den jedes Upgrade
+  durchläuft[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30]. Dafür
+  ist [[KB Migration]] zuständig.
+- Nicht als automatischer Bump aus Commit-Nachrichten, solange Content-Commits und
+  Stack-Commits im selben Repository liegen.
+
+## Beziehungen
+
+## Siehe auch
+
+- [[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]]
+
+<!-- wikitool:links -->
+## Beziehungen
+
+- **mechanism:** [[wikitool]]
+- **see-also:** [[Issue Label Scheme]]
+- **see-also:** [[CI Integration]]
+<!-- /wikitool:links -->