Compare commits
16 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 torben
|
c8c238523a | ||
|
torben
|
3f99d6715f | ||
|
torben
|
807094deae | ||
|
torben
|
8b711f4860 | ||
|
torben
|
a35c94e2d9 | ||
|
torben
|
9e2f9bf98d | ||
|
torben
|
7e15035001 | ||
|
torben
|
b137359b90 | ||
|
torben
|
177c7e9ce8 | ||
|
torben
|
502971d147 | ||
|
torben
|
9843df99d3 | ||
|
torben
|
31662dc3ff | ||
|
torben
|
7fbb9a99df | ||
|
torben
|
778764de4d | ||
|
torben
|
f7597b209c | ||
|
torben
|
83018fcc7d |
@@ -221,6 +221,16 @@ jobs:
|
||||
for personal in USER SOUL; do
|
||||
grep -v 'wikitool:template-unfilled' "$personal.md.template" > "$personal.md"
|
||||
done
|
||||
# The authoring conventions ride the same split one directory down,
|
||||
# and are stubbed the same way: what is under test is that the export
|
||||
# carries the templates and that `doctor`/`docs verify` accept an
|
||||
# adopted one, not what a person would write into them. The collection
|
||||
# contracts are adopted verbatim - the shipped text is a working
|
||||
# default, unlike a personalization file.
|
||||
grep -v 'wikitool:template-unfilled' kb/CONVENTIONS.md.template > kb/CONVENTIONS.md
|
||||
for template in kb/*/COLLECTION.md.template types/*.template; do
|
||||
cp "$template" "${template%.template}"
|
||||
done
|
||||
python3 -m venv tools/.venv
|
||||
tools/.venv/bin/pip install --quiet -r tools/requirements.txt
|
||||
tools/wikitool instructions sync
|
||||
|
||||
+13
-2
@@ -1,5 +1,16 @@
|
||||
{
|
||||
"schema": 1,
|
||||
"kb_version": "1.0.0",
|
||||
"applied": []
|
||||
"kb_version": "4.0.0",
|
||||
"applied": [
|
||||
{
|
||||
"migration": "3.0.0-authoring-conventions",
|
||||
"at": "2026-09-02",
|
||||
"pages": 0
|
||||
},
|
||||
{
|
||||
"migration": "4.0.0-link-taxonomy",
|
||||
"at": "2026-09-02",
|
||||
"pages": 153
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -77,10 +77,11 @@ What a file is called says who it is for and how it is loaded. This is a rule, n
|
||||
| `SOUL.md` | Agents | Always, every session |
|
||||
| `ENVIRONMENT.md` | Agents | Every session, **if it exists** - the one optional file in this table. Not committed: it describes one checkout, not the repo |
|
||||
| `<stage>/CONTRACT.md` | Agents | When writing in that stage |
|
||||
| `kb/<collection>/COLLECTION.md` | Agents | When writing in that collection |
|
||||
| `kb/CONVENTIONS.md` | Agents | When writing any page - it holds what *this* instance decided about authoring (language, section headings, naming, tone, relationship labels, confidence rubric), where `kb/CONTRACT.md` holds what the stack enforces. Instance-owned: a distribution ships only the `.template` |
|
||||
| `kb/<collection>/COLLECTION.md` | Agents | When writing in that collection. Instance-owned in the same way, and declares in frontmatter which profile it adopted |
|
||||
| `instructions/<name>.md` | Agents | By link, or on explicit request |
|
||||
| `instructions/<name>/SKILL.md` | Agents | By the harness, once published |
|
||||
| `types/<name>.md` | Agents + validator | Via `tools/wikitool types describe` |
|
||||
| `types/<name>.md` | Agents + validator | Via `tools/wikitool types describe`. Split by `root:`: a page type-spec (`root: kb`) belongs to the instance and ships as `.template`; one describing a stack artifact ships verbatim |
|
||||
| `INDEX.md` | Both | Generated - never hand-edited |
|
||||
|
||||
A stage may carry both a `README.md` and a `CONTRACT.md`: different readers, different
|
||||
@@ -104,6 +105,16 @@ and `SOUL.md.template`; the Personalization step of
|
||||
writes the real files. `tools/wikitool doctor` FAILs on a missing one, and on one still
|
||||
carrying the template's sentinel.
|
||||
|
||||
The same `.template` split runs one directory down, for authoring rather than for voice.
|
||||
`kb/CONVENTIONS.md` and each `kb/<name>/COLLECTION.md` bind every page and belong to the
|
||||
instance, so a distribution ships them as templates and the KB-language step of
|
||||
[instructions/setup-instance.md](instructions/setup-instance.md) fills them in, out of a
|
||||
catalogue of ready-made profiles it routes to; `doctor` FAILs on a missing or unfilled
|
||||
`kb/CONVENTIONS.md` the same way.
|
||||
|
||||
Unlike `USER.md`, these two *are* a source of rules: they are as binding as `kb/CONTRACT.md`.
|
||||
What differs is ownership, not authority.
|
||||
|
||||
## Environment
|
||||
|
||||
`ENVIRONMENT.md` records what *this checkout* works through - harness, published skills,
|
||||
@@ -142,15 +153,17 @@ Alongside it, not part of it: `instructions/` (what agents are told to do) and t
|
||||
|-------|----------|--------|
|
||||
| `raw/` | [raw/CONTRACT.md](raw/CONTRACT.md) | Immutability, directory routing, untrusted-content rule |
|
||||
| `types/` | [types/type-spec.md](types/type-spec.md) | Type-spec anatomy, placement, adding a type, template variables |
|
||||
| `kb/` | [kb/CONTRACT.md](kb/CONTRACT.md) | Collections, naming, tone, linking, provenance, confidence |
|
||||
| `kb/` | [kb/CONTRACT.md](kb/CONTRACT.md) + `kb/CONVENTIONS.md` | What the stack enforces about a page (collections, linking, provenance, confidence machinery), and beside it what this instance decided (language, naming, tone, labels, rubric) |
|
||||
| `reports/` | [reports/CONTRACT.md](reports/CONTRACT.md) | Why reports and traces are generated, gitignored, and carried into `kb/log.md` |
|
||||
| `work/` | [work/CONTRACT.md](work/CONTRACT.md) | Workshop runs: run keys, required files, why they are tracked, how a run closes |
|
||||
| `tools/` | [tools/CONTRACT.md](tools/CONTRACT.md) | Full command reference, per-command error contracts, maintenance schedule |
|
||||
| `instructions/` | [instructions/CONTRACT.md](instructions/CONTRACT.md) | Instruction vs. skill, publishing, writing standard |
|
||||
|
||||
**By collection** - then read the contract for the collection you are writing in.
|
||||
[kb/CONTRACT.md](kb/CONTRACT.md) routes between `kb/entities/`, `kb/concepts/`, `kb/sources/`
|
||||
and `kb/comparisons/`, and holds the rules they share.
|
||||
[kb/CONTRACT.md](kb/CONTRACT.md) routes between this instance's collections and holds the rules
|
||||
the stack enforces across all of them; `kb/CONVENTIONS.md` holds the ones this instance chose.
|
||||
Both bind. The difference is who may change the sentence - which is also why a distribution
|
||||
ships the first verbatim and the second only as a `.template`.
|
||||
|
||||
**By task** - skills hold the step-by-step procedures. Sources live in `instructions/<name>/`:
|
||||
|
||||
|
||||
+269
@@ -20,6 +20,275 @@ their date-only headings.
|
||||
|
||||
---
|
||||
|
||||
## 4.0.1 - 2026-09-02 - Issue-Board: vier Pflicht-Label-Familien und Body-als-Wahrheit
|
||||
|
||||
**Author:** Torben Nehmer
|
||||
|
||||
Das Issue-Schema aus 1.2.1 hatte zwei Pflichtachsen und einen ausdrücklich begründeten Verzicht
|
||||
auf eine dritte: eine Taxonomie mit mehr Achsen brauche eigene Pflege, und das Board habe einen
|
||||
einzigen Betreuer. Diese Begründung ist entfallen, weil die Pflege inzwischen maschinell
|
||||
passiert - Body-Rewrites und Kommentare laufen über eine LLM-Sitzung, Menschen fassen in der
|
||||
Regel nur Labels an. Damit sind vier Achsen bezahlbar (Issue #41).
|
||||
|
||||
**Pflicht auf jedem offenen Issue sind jetzt vier Label:** `area/` (`kb`, `distribution`,
|
||||
`corpus`, `workflow`, `process` - kein `area/tools`, Tooling wird nach der bedienten Domäne
|
||||
einsortiert, nicht nach Codeort), `kind/` (`decision`, `build`, `defect`), `prio/`
|
||||
(`blocking`, `planned`, `waiting` - reine Umbenennung von `1`/`2`/`3`) und `size/` (`S`, `M`,
|
||||
`L`; `XS` entfällt). Dazu zwei optionale Flags: `status/blocked` für Abhängigkeit von einem
|
||||
anderen offenen Issue, `status/unconfirmed` für einen ungeprüften Verdacht, unter dem `size`
|
||||
und `prio` vorläufig sind. Ein `unconfirmed`-Issue endet in der Triage entweder ohne Flag und
|
||||
mit verbindlichen Werten oder geschlossen mit Begründung - die Prozessentsprechung zu
|
||||
Invariante 3.
|
||||
|
||||
**Der Issue-Body ist ab jetzt aktuelle Wahrheit, nicht Ursprungstext.** Die Umsetzung eines
|
||||
Issues zieht sich über mehrere, zeitlich getrennte Sitzungen, und der Body ist das einzige, was
|
||||
sie verbindet: eine Sitzung muss aus ihm allein rekonstruieren können, was entschieden und was
|
||||
offen ist. Er wird deshalb umgeschrieben statt ergänzt. Jeder Rewrite bekommt einen Kommentar,
|
||||
der ausschließlich benennt, was sich geändert hat - keine Vollkopie des alten Stands, weil ein
|
||||
Mensch zwei Fließtexte nicht diffen kann und eine Kopie pro Revision damit keine Historie ist,
|
||||
sondern nur eine weitere Kopie.
|
||||
|
||||
Geändert: [instructions/dev/issue-tracking.md](instructions/dev/issue-tracking.md) (Schritte 2,
|
||||
3, 5 neu; Schritt 4 um `area/` und `kind/` erweitert; der Entscheidungspunkt „Two labels feel
|
||||
too coarse?" entfällt) und die Beschreibungszeile in `instructions/dev/stack-dev/SKILL.md`. Für
|
||||
eine ausgelieferte Instanz ändert sich nichts: `dist export` schließt `instructions/dev/`
|
||||
vollständig aus, weshalb dies ein PATCH ist und kein MINOR - dieselbe Begründung wie bei
|
||||
`1.2.1`. Noch offen aus #41: `kb/concepts/Issue Label Scheme.md` beschreibt weiterhin das
|
||||
zweiachsige Schema und braucht eine eigene `wiki-manage`-Sitzung.
|
||||
|
||||
---
|
||||
|
||||
## 4.0.0 - 2026-09-02 - Prosa ist kein Identifier: Link-Taxonomie als Enum, generierte Regionen mit Markern
|
||||
|
||||
**Author:** Torben Nehmer
|
||||
|
||||
**Breaking Change:** Beziehungslabel sind Enum-Werte in related: statt Freitext im Body-Bullet, toolgefuehrte Abschnitte liegen zwischen Marker-Paaren statt hinter ihrer Ueberschrift, und xref add schreibt nur noch eine Kante statt beider Richtungen. tools/chemenu/sections.py ist geloescht. Eine bestehende Instanz muss sections: in kb/CONVENTIONS.md auf links/footnotes umstellen, outbound: in jede COLLECTION.md eintragen, die {section.*}-Variablen aus ihren Page-Type-Templates entfernen und den Korpus umstellen - sonst scaffoldet new die Variablen woertlich in neue Seiten. Ablauf: instructions/migrations/4.0.0-link-taxonomy.md
|
||||
|
||||
Der Stack benutzte an drei Stellen **Prosa als Identifier**, und jede hat messbar etwas
|
||||
gekostet. Die Überschrift eines Abschnitts war seine Adresse (`^## Beziehungen$`), was die
|
||||
KB-Sprache zu einer Compiler-Konstante machte *und* das Ende der Region zur Schätzung - sie lief
|
||||
bis zur nächsten Überschrift, davor bis zum Dateiende, und hat auf acht Seiten still Inhalt
|
||||
gelöscht. Das Beziehungslabel stand nur im Body-Bullet, also konnte nichts das Vokabular prüfen:
|
||||
gemessen am Korpus **152 distinkte Label in 337 Bullets** gegen dreizehn dokumentierte, 102 davon
|
||||
genau einmal vorkommend. Und `xref add` spiegelte jede Kante, was `## Siehe auch` mit 555
|
||||
Bullets ohne Label füllte - 353 davon beweisbar redundant.
|
||||
|
||||
**Was jetzt Identifier ist.** Eine Region liegt zwischen `<!-- wikitool:links -->` bzw.
|
||||
`<!-- wikitool:footnotes -->` und wird vollständig aus dem Frontmatter gerendert, Überschrift
|
||||
eingeschlossen. Ein Label ist ein Maschinenwert in `related:` (`- depends-on: Hermes`), gezogen
|
||||
aus `instructions/link-taxonomy.md` und **pro Ziel autorisiert von der Quell-Collection**
|
||||
(`outbound:` im `COLLECTION.md`, Commonplaces ADR-019). Der Body-Bullet ist eine Darstellung
|
||||
dieser Daten, nicht ihr zweiter Aufbewahrungsort.
|
||||
|
||||
**Gelöscht, ersatzlos:** `tools/chemenu/sections.py` komplett, `heading_re`, der
|
||||
Alias-Mechanismus, `PRE_CONVENTIONS_NAMES`, `cite_block_heading`, `provenance.__getattr__`, die
|
||||
`{section.*}`-Template-Variablen, `xref`s Abschnittssuche. Kein Überschriftentext liegt mehr in
|
||||
Python - bis auf zwei kosmetische Fallbacks, und die sind harmlos geworden: der Marker trägt die
|
||||
Identität, also rendert ein falscher Default falsche Wörter statt Struktur zu zerlegen, und der
|
||||
nächste Write repariert es.
|
||||
|
||||
**Kanten sind direktional, und das war keine Geschmacksfrage.** Die per-Collection-Autorisierung
|
||||
ist mit einer automatisch gespiegelten Gegenkante logisch unverträglich: die Spiegelhälfte
|
||||
entsteht in einer Collection, deren Regeln der Autor nie gelesen hat. Entweder schriebe das
|
||||
Werkzeug unautorisierte Kanten, oder die Regel "die Quellcollection entscheidet" löst sich auf.
|
||||
Der Navigationseinwand wird dabei *besser* beantwortet als vorher: `wikitool links show --page`
|
||||
berechnet die Eingangssicht über den Korpus, vollständig und ohne Pflege, und das gerenderte
|
||||
Bullet ist ein gewöhnlicher `[[wikilink]]` - ein Backlink-Panel zeigt es ohnehin. Die erzwungene
|
||||
Gegenkante garantierte nie Vollständigkeit, nur dass jemand daran gedacht hat.
|
||||
|
||||
**Der Orphan-Check meldet dadurch mehr,** und das ist die Prüfung bei der Arbeit: sie misst jetzt
|
||||
Erreichbarkeit statt "ist `xref` gelaufen".
|
||||
|
||||
**`obligation:` trennt zwei Achsen, die vorher eine waren.** `migration_kind:` sagt *wie*
|
||||
gearbeitet wird, neu `obligation: required|offered` *ob* überhaupt. Eine `offered`-Migration ist
|
||||
ein Angebot für eine Datei, die der Instanz gehört - sie blockiert nie, steht nicht in der Kette,
|
||||
und `migrate done` verbucht sie im Ledger, **ohne** `kb_version` zu bewegen. Genau daran hing ein
|
||||
Entwurfsfehler, den erst der Test gezeigt hat: Offers gegen `kb_version` zu filtern hätte jede
|
||||
Offer verschwinden lassen, sobald irgendein unbeteiligter Pflichtschritt lief. Dazu ist die
|
||||
Erkennungshälfte aktiviert, die seit ihrer Einführung ungelesen dalag - die sha256 pro Datei in
|
||||
`.wikitool-release.json` beantwortet jetzt "editiert oder nur empfangen", also ob eine Offer
|
||||
kopiert werden darf oder von Hand abgeglichen werden muss.
|
||||
|
||||
**`types/` teilt sich entlang `root:`.** `root: kb` heißt Wissensseite heißt Instanz: die vier
|
||||
Page-Type-Specs samt Schemas gehen als `.template`, `instruction`/`lint-report`/`type-spec`
|
||||
verbatim. Damit ist die deutsche Prosa in jenen vier Dateien **korrekt statt Migrationsschuld** -
|
||||
es war die richtige Sprache an einem Ort mit falsch deklariertem Eigentümer. Was der Stack von
|
||||
der Type-Schicht noch verlangt, ist eine Zeile: ein Type-Spec `name: source`, dessen Schema
|
||||
`raw_files` fordert. `STACK_REQUIRED_COLLECTIONS` entfällt als separate Liste - die pflichtige
|
||||
Collection wird aus dem `base_dir` dieses Typs abgeleitet.
|
||||
|
||||
**Warum das MAJOR ist.** Vorwärts: `sections:` hat eine andere Form, `outbound:` fehlt, und die
|
||||
in 3.0.0 übernommenen Page-Type-Templates enthalten `{section.*}`-Variablen, die es nicht mehr
|
||||
gibt - `new` schriebe sie wörtlich in neue Seiten. Rückwärts: 4.0.0 schreibt gelabelte Kanten,
|
||||
die 3.0.0s Schema als `type: string` ablehnt. Beide Hälften des Drop-in-Tests fallen.
|
||||
|
||||
**Der Korpus dieser Instanz ist noch nicht umgestellt.** Diese Version liefert die Maschinerie;
|
||||
`lint` meldet die 480 noch ungelabelten Kanten als Findings, nicht als Fehler, weil das genau das
|
||||
Fenster ist, für das `.wikitool-kb.json` existiert. `malformed_edges` und `unbalanced_markers`
|
||||
sind dagegen sofort hart - keines beschreibt eine unkonvertierte Seite, nur eine kaputte. Die
|
||||
Beförderung der beiden anderen kommt, wenn der Korpus sie bestehen kann.
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 3.0.0 - 2026-09-02 - Autorenkonventionen nach Eigentum geschnitten: kb/CONVENTIONS.md, deklarierte Collections
|
||||
|
||||
**Author:** Torben Nehmer
|
||||
|
||||
**Breaking Change:** kb/CONTRACT.md ist um alles gekuerzt, was eine Instanz selbst entscheidet; das steht jetzt in einer neuen, instanzeigenen kb/CONVENTIONS.md, aus der der Compiler die drei toolgefuehrten Abschnittsnamen liest. Eine bestehende Instanz muss diese Datei anlegen, auf jedem kb/*/COLLECTION.md profile: und required_by_stack: deklarieren und kb/CONTRACT.md aus dem Release nachziehen - sonst FAILt doctor und docs verify bricht. Ablauf: instructions/migrations/3.0.0-authoring-conventions.md
|
||||
|
||||
`kb/CONTRACT.md` war eine Datei mit zwei Autoritäten. Der eine Teil ist code-erzwungen und in
|
||||
jeder Instanz gleich; der andere - **§ Language komplett**, das Beziehungslabel-Vokabular, die
|
||||
Tonfall-Beispiele samt deutscher Buzzword-Liste, die Confidence-Rubrik, das ADR-Präfix - ist
|
||||
Konvention, die jede Instanz für sich entscheidet, und wurde trotzdem als bindender Contract
|
||||
verbatim ausgeliefert. Wer bei Schritt 5 von `setup-instance.md` "Englisch" antwortete, hatte
|
||||
danach `kb/CONTRACT.md`, vier Type-Specs **und `tools/chemenu/sections.py`** lokal geändert -
|
||||
und `private-instance.md`s Decision Point sagt für so einen Merge-Konflikt: Upstream-Seite
|
||||
nehmen. Für diese Instanz hieß das: KB-Sprache zurück auf Deutsch.
|
||||
|
||||
**Der Schnitt läuft jetzt danach, wer den Satz ändern darf.** `kb/CONTRACT.md` behält, was
|
||||
`wikitool` erzwingt; neu daneben liegt `kb/CONVENTIONS.md`, die **genauso bindet** und der
|
||||
Instanz gehört. Unterschied ist Eigentum, nicht Autorität - deshalb liefert die Distribution nur
|
||||
`kb/CONVENTIONS.md.template`, exakt der `USER.md`/`SOUL.md`-Split ein Verzeichnis tiefer. Dazu
|
||||
`instructions/kb-profiles.md`: der Katalog erprobter Profile, ausdrücklich **Palette und kein
|
||||
Enum**. Übernommen wird der *Text* in die Instanzdatei, nie ein Verweis auf den Katalog - ein
|
||||
Verweis wäre wieder genau die Konstruktion, die dieser Release beendet.
|
||||
|
||||
**`sections.py` hält keine Überschrift mehr.** `RELATIONSHIPS = "Beziehungen"` war die Stelle,
|
||||
an der die Konvention in Code übergelaufen war: solange sie dort stand, konnte kein Template die
|
||||
Sprache umstellen. Neu ist `tools/chemenu/conventions.py`, das die drei Namen aus
|
||||
`kb/CONVENTIONS.md` liest; `sections.py` löst sie per PEP 562 bei jedem Zugriff auf, wie
|
||||
`config` seine Pfade - ein Modulkonstante hätte den Wert an den Baum gebunden, in dem der Prozess
|
||||
gestartet ist. Aus demselben Grund ist `provenance.CITE_BLOCK_HEADING` ein `__getattr__` und
|
||||
`render_cite_block(heading=None)` löst innerhalb des Aufrufs auf. Der Alias-Mechanismus, den das
|
||||
Modul schon hatte, **ist** der Migrationspfad: erkannt wird die kanonische Form plus die
|
||||
deklarierten `section_aliases:` plus das, was dieser Stack vor der Konventionsdatei geschrieben
|
||||
hat. Ohne Datei antwortet dieser Fallback - richtig für jeden Korpus, der ihn erreichen kann,
|
||||
denn der wurde unter genau diesen Namen geschrieben; `doctor` ist die laute Hälfte davon.
|
||||
|
||||
**Die vier Page-Type-Specs schreiben `## {section.relationships}`** statt einer Überschrift.
|
||||
Neue Template-Variablen `{section.relationships}` / `{section.see_also}` / `{section.footnotes}`,
|
||||
gefüllt aus der Instanzdeklaration. Damit ändert eine anderssprachige Instanz **keine Datei unter
|
||||
`tools/` oder `types/`** mehr - was Schritt 5 von `setup-instance.md` von fünf Editierstellen
|
||||
über drei Schichten auf eine Entscheidung reduziert.
|
||||
|
||||
**`COLLECTION.md` bekommt Frontmatter.** Bisher wurde eine Collection rein an der Dateipräsenz
|
||||
erkannt; die Deklaration brauchte einen Träger, sonst wäre der Ortsschnitt nur durch einen
|
||||
Prosaschnitt ersetzt worden. `profile:` nennt den übernommenen Katalogeintrag (Freitext - eine
|
||||
selbst angelegte Collection hat dort keinen), `required_by_stack:` sagt, ob `wikitool` die
|
||||
Collection *namentlich* auflöst. Das zweite ist **nicht** die Wahl der Instanz: `docs verify`
|
||||
prüft es beidseitig gegen `kb_collections.STACK_REQUIRED_COLLECTIONS`. Heute steht dort genau
|
||||
`sources` - `sources coverage`, die `[^cite-id]`-Auflösung und `kb/provenance.md` hängen an dem
|
||||
Namen, `entities` an keinem.
|
||||
|
||||
**Das zweite Leck der Merge-Prozedur ist zu.** `git checkout HEAD -- kb raw` holte *alles* unter
|
||||
beiden Stages auf den Vor-Merge-Stand - auch `kb/CONTRACT.md` und `raw/CONTRACT.md`. Änderte der
|
||||
Upstream einen davon, warf die Prozedur das Update still weg, und die Kontrollzeile meldete dabei
|
||||
*leer*, bestätigte den Fehler also, statt ihn zu fangen. `private-instance.md` nimmt die
|
||||
Upstream-Seite jetzt für die drei Maschinerie-Pfade unter den Content-Stages zurück
|
||||
(`kb/CONTRACT.md`, `kb/CONVENTIONS.md.template`, `raw/CONTRACT.md`) und schließt sie aus der
|
||||
Kontrollzeile aus. Dieselbe Altlast in der Tarball-Richtung: `INSTALL.md` Schritt 3 fasste `kb/`
|
||||
gar nicht an und zog `kb/CONTRACT.md` damit nie nach - jetzt ausdrücklich benannt.
|
||||
|
||||
**Verworfen, gemessen: `sources/` aus `kb/` herausziehen.** Der Graph ist einwurzelig
|
||||
(`kb_scan.iter_kb_pages` macht ein `rglob` über `kb/`, darauf sitzen Link-Graph, Orphan-Check,
|
||||
`index rebuild` und `search`), und Source-Seiten sind darin der dichteste Knotentyp. Ein Hoist
|
||||
machte jede Graph-Operation dauerhaft zweiwurzelig, um ein Verzeichnis umzubenennen. Vor allem
|
||||
aber kann der *Ort* Eigentum ohnehin nicht kodieren, sobald Collections offen sind: eine selbst
|
||||
angelegte liegt im selben `kb/` wie die Defaults. Eigentum ist eine deklarierte Eigenschaft -
|
||||
daher das Frontmatter oben. Gitea #39 trägt die Ablehnung im Volltext.
|
||||
|
||||
**Warum das MAJOR ist.** Die Rückwärtshälfte des Drop-in-Tests hält - 2.5.0 ignoriert beide neuen
|
||||
Deklarationen folgenlos. Die Vorwärtshälfte nicht: nach dem Kopieren der Maschinerie FAILt
|
||||
`doctor` auf der fehlenden `kb/CONVENTIONS.md`, `docs verify` bricht auf den undeklarierten
|
||||
Collections, und `kb/CONTRACT.md` muss aus dem Release nachgezogen werden. Ein Shim war die
|
||||
Alternative (`doctor` nur WARN, Pflichtfelder tolerant) und wurde verworfen: er hätte genau den
|
||||
Zustand normalisiert, in dem eine Instanz glaubt, sie habe entschieden, während in Wahrheit der
|
||||
Fallback antwortet - für eine englische Instanz hieße das `## Beziehungen` in englischen Seiten.
|
||||
Die Handarbeit ist eine Datei und zwei Frontmatter-Zeilen je Collection; keine einzige `kb/`-Seite
|
||||
ändert sich, weshalb `migrate done 3.0.0 --pages 0` ehrlich und kein Platzhalter ist.
|
||||
|
||||
---
|
||||
|
||||
## 2.5.0 - 2026-09-02 - Versionsstelle: Kompatibilitaet statt Inhaltsmigration, Breaking-Change-Vermerk erzwungen
|
||||
|
||||
**Author:** Torben Nehmer
|
||||
|
||||
Die Doku des Stacks führte für die Wahl der Versionsstelle zwei Fragen zusammen, die nicht
|
||||
dieselbe sind: *muss der Korpus migriert werden?* und *ist die neue Version ein
|
||||
Drop-in-Ersatz?* An allen drei Stellen, die einer Session vor dem Bump begegnen - die Tabelle
|
||||
in `stack-dev`, der Modul-Docstring in `version.py`, `INSTALL.md` § Version und Updates -
|
||||
stand nur die erste. Nur `version bump --help` formulierte es richtig, also ausgerechnet die
|
||||
Stelle, die man erst liest, wenn die Entscheidung gefallen ist. Bei `2.0.0` hat genau diese
|
||||
Lücke zu `1.9.0` geführt (Gitea #26; der Eintrag zu `2.0.0` trägt den Fall im Volltext).
|
||||
|
||||
**Die Regel, jetzt an einer Stelle.** Neu ist
|
||||
`instructions/dev/version-parts.md`: der Drop-in-Test in zwei Hälften - vorwärts (kopieren,
|
||||
fertig, keine Handarbeit durch Nutzer oder Migrationsskript) und rückwärts (die alte Version
|
||||
lässt sich noch zurückinstallieren) -, der Katalog der Brüche, die die Grenze bei völlig
|
||||
unangetastetem `kb/` überschreiten (Update-Pfad, Artefaktname, Import-Name, Flags, Envvars,
|
||||
Shape maschinengelesener Dateien), und der Fall `2.0.0` als Fallbeispiel. `instructions/dev/`,
|
||||
also nicht in einer ausgelieferten Instanz - die Datei entscheidet, wer den Stack entwickelt.
|
||||
Die ausgelieferten Artefakte tragen deshalb die Kurzform der Regel, aber keinen Verweis auf
|
||||
sie: `instructions verify` meldet einen solchen Verweis, weil er nach `dist export` ins Leere
|
||||
zeigen würde.
|
||||
|
||||
**Breaking Changes sind teuer, also genehmigungspflichtig.** `stack-dev` hat einen
|
||||
Entscheidungspunkt bekommen: stellt sich eine Änderung als nicht drop-in heraus, wird nicht
|
||||
aus eigener Initiative über die Grenze gebumpt. Vorgelegt werden der konkrete Bruch, was jede
|
||||
bestehende Instanz von Hand tun muss, und die Alternativen - Bruch per Shim vermeiden,
|
||||
aufschieben und mit dem nächsten bündeln, oder in einen kompatiblen und einen brechenden Teil
|
||||
mit Deprecation-Fenster spalten -, dazu eine Empfehlung. Dann Freigabe abwarten.
|
||||
|
||||
**`--breaking` ist neu und bei jedem Grenzübertritt Pflicht.** Es schreibt eine
|
||||
`**Breaking Change:**`-Zeile in den Eintrag, vor die Migrationszeile: das ist, was der Operator
|
||||
einer bestehenden Instanz beim Lesen der Release-Notes zuerst braucht. `docs verify` prüft den
|
||||
neuesten grenzüberschreitenden Eintrag darauf, analog zu `**Migration:** none required` und aus
|
||||
demselben Grund - eine Prosa-Regel driftet, ein Marker nicht. Auf einem kompatiblen Bump wird
|
||||
`--breaking` verweigert, damit es keine Gewohnheit wird. Beide Prüfungen bleiben getrennt:
|
||||
`check_migration_for_boundary` fragt, ob der Inhalt sich bewegt, `check_breaking_change_for_boundary`,
|
||||
ob dem Operator gesagt wurde, dass der Tausch keiner zum Drüberkopieren ist. Ein Rebranding
|
||||
besteht die erste und fällt durch die zweite.
|
||||
|
||||
**Was ausdrücklich nicht passiert:** `docs verify` prüft weiterhin nicht, *ob die Stelle
|
||||
richtig gewählt* wurde. Kein Validator unterscheidet ein umbenanntes Flag von einem neuen; das
|
||||
bleibt Urteil, und dieser Eintrag existiert, weil das Urteil eine Anleitung braucht, keinen
|
||||
Automaten.
|
||||
|
||||
Berührt: `instructions/dev/version-parts.md` (neu), `instructions/dev/stack-dev/SKILL.md`,
|
||||
`tools/chemenu/version.py`, `tools/chemenu/commands/version_cmd.py`,
|
||||
`tools/chemenu/commands/docs_verify.py`, `tools/CONTRACT.md`, `INSTALL.md`. Sechs neue Tests.
|
||||
|
||||
---
|
||||
|
||||
## 2.4.1 - 2026-09-02 - INSTALL-MCP.md: Menschendoku fuer den Leseserver, und sie wird mit ausgeliefert
|
||||
|
||||
**Author:** Torben Nehmer
|
||||
|
||||
Nachtrag zu 2.4.0. Der Server war ausgeliefert und für Menschen nur über `tools/CONTRACT.md` und
|
||||
eine Instruktion beschrieben — beide für Agenten geschrieben. `INSTALL-MCP.md` schließt das,
|
||||
neben `INSTALL.md` und in derselben Form: Voraussetzungen, sechs Schritte, Verifikation,
|
||||
Troubleshooting.
|
||||
|
||||
**Was drinsteht, das sonst nirgends zusammen stand:** die Client-Konfiguration als JSON-Block;
|
||||
dass `WIKI_TRACE=0` nicht optional ist und wie die Startverweigerung aussieht; dass
|
||||
`--host 0.0.0.0` bewusst nicht der Default ist; und der Verweis auf die
|
||||
Traefik-ForwardAuth-Middleware unter <https://gitea.nehmer.net/torben/gitea-mcp-forward-auth>
|
||||
samt dem, was sie erwartet (Bearer-Token gegen SHA-256-Hashes, `AUTH_PROXY_TOKEN_HASHES_DIR`).
|
||||
Der Verifikationsabschnitt ist ein lauffähiges Skript — wörtlich so ausgeführt, bevor es hier
|
||||
landete.
|
||||
|
||||
**`dist export` liefert die Datei mit.** `ROOT_FILES` ist eine Allowlist, also hätte sie sonst
|
||||
keine Instanz erreicht: ein ausgelieferter Server, dessen Bedienungsanleitung im Ursprungs-Repo
|
||||
zurückbleibt, ist einer, den der Empfänger durch Quelltextlesen findet. `INSTALL.md` bekommt
|
||||
zusätzlich `CHEMENU_ROOT` und `WIKI_TRACE`/`WIKI_TRACE_DIR` in seine Konfigurationstabelle —
|
||||
beide waren seit 2.3.0 bzw. seit jeher wirksam und dort nicht aufgeführt.
|
||||
|
||||
**Dateien:** `INSTALL-MCP.md` (neu), `INSTALL.md`, `README.md`,
|
||||
`tools/chemenu/commands/dist_cmd.py`.
|
||||
|
||||
---
|
||||
|
||||
## 2.4.0 - 2026-09-02 - MCP-Leseserver: zweiter Konsument auf demselben Kern
|
||||
|
||||
**Author:** Torben Nehmer
|
||||
|
||||
+239
@@ -0,0 +1,239 @@
|
||||
# MCP-Leseserver installieren
|
||||
|
||||
Dieses Dokument richtet sich an Menschen. Es beschreibt, wie der MCP-Leseserver eines Chemenu-
|
||||
Wikis lokal läuft, wie ein Client ihn einbindet, und wie er hinter einer Authentifizierung
|
||||
erreichbar wird. Der agent-seitige Betriebsablauf steht in
|
||||
[instructions/mcp-read-server.md](instructions/mcp-read-server.md); die vollständige
|
||||
Kommandoreferenz in [tools/CONTRACT.md](tools/CONTRACT.md).
|
||||
|
||||
**Was der Server ist.** Ein zweiter Konsument desselben Kerns, nicht ein zweites Programm. CLI
|
||||
und Server rufen dieselben Funktionen auf; ein Golden-Test hält ihre Ausgaben gegeneinander.
|
||||
Was `tools/wikitool search --json` liefert, liefert das MCP-Tool `search` auch — plus den
|
||||
Commit, aus dem die Antwort berechnet wurde.
|
||||
|
||||
**Was er nicht ist.** Kein Schreibpfad. Es gibt kein Tool, das eine Seite anlegt, ändert oder
|
||||
publiziert — nicht weil eine Liste gefiltert wird, sondern weil der Server nichts unter
|
||||
`tools/chemenu/commands/` importiert. Die Funktionen sind aus diesem Prozess heraus nicht
|
||||
erreichbar.
|
||||
|
||||
## Voraussetzungen
|
||||
|
||||
- Eine funktionierende Instanz nach [INSTALL.md](INSTALL.md) — inklusive `tools/.venv` und
|
||||
`ripgrep`
|
||||
- Python 3.11 oder neuer (wie die CLI)
|
||||
|
||||
## Schritt 1: Abhängigkeit installieren
|
||||
|
||||
Sie liegt bewusst nicht in `tools/requirements.txt`. Eine Instanz, die nur die CLI benutzt, soll
|
||||
dafür nicht pydantic, starlette, uvicorn und cryptography mitinstallieren müssen.
|
||||
|
||||
```bash
|
||||
tools/.venv/bin/pip install -r tools/requirements-mcp.txt
|
||||
```
|
||||
|
||||
## Schritt 2: Lokal starten (stdio)
|
||||
|
||||
`stdio` ist der Weg zum Ausprobieren und für einen Client auf derselben Maschine: ein Prozess
|
||||
pro Konsument, lokal gestartet, kein Netzwerk.
|
||||
|
||||
```bash
|
||||
WIKI_TRACE=0 tools/.venv/bin/python -m chemenu.mcp
|
||||
```
|
||||
|
||||
Der Prozess spricht MCP über stdin/stdout und gibt für sich genommen nichts aus — das ist
|
||||
richtig so. Gestartet wird er normalerweise nicht von Hand, sondern vom Client (Schritt 3).
|
||||
|
||||
**`WIKI_TRACE=0` ist nicht optional.** Telemetrie ist per Default an und schreibt nach
|
||||
`reports/telemetry/` im Repo. Der Server **verweigert den Start**, solange das so ist, statt
|
||||
still umzuleiten:
|
||||
|
||||
```
|
||||
ERROR Telemetry is on and would write into the served checkout (...). Set WIKI_TRACE=0,
|
||||
or point WIKI_TRACE_DIR outside the corpus.
|
||||
```
|
||||
|
||||
Beide Auswege sind gleichwertig: `WIKI_TRACE=0` schaltet ab, `WIKI_TRACE_DIR=/var/log/chemenu`
|
||||
lenkt um. Der Grund steht in Schritt 6 — der Sync darf `reports/` wegräumen.
|
||||
|
||||
## Schritt 3: Einen Client einbinden
|
||||
|
||||
Die Konfiguration folgt der üblichen MCP-Client-Form. Absolute Pfade, weil der Client kein
|
||||
Arbeitsverzeichnis erbt:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"chemenu": {
|
||||
"command": "/pfad/zur/instanz/tools/.venv/bin/python",
|
||||
"args": ["-m", "chemenu.mcp"],
|
||||
"cwd": "/pfad/zur/instanz/tools",
|
||||
"env": {
|
||||
"WIKI_TRACE": "0",
|
||||
"CHEMENU_ROOT": "/pfad/zur/instanz"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`CHEMENU_ROOT` sagt, **welches** Wiki bedient wird. Ohne die Variable nimmt der Server den
|
||||
Checkout, in dem das Paket selbst liegt — für eine einzelne Instanz reicht das, aber wer mehrere
|
||||
Korpora hat, setzt sie besser immer.
|
||||
|
||||
Danach kennt der Client fünf Werkzeuge:
|
||||
|
||||
| Tool | Was es beantwortet |
|
||||
|---|---|
|
||||
| `search` | Seiten in `kb/` nach Text, nach Frontmatter (`confidence<0.6`, `tags~k8s`) oder beidem |
|
||||
| `types` | Welche Seitentypen dieses Wiki kennt |
|
||||
| `describe_type` | Der vollständige Vertrag eines Typs: Felder, Pflichtangaben, Enums |
|
||||
| `lint` | Strukturelle Befunde: kaputte Wikilinks, Waisen, Index-Drift, Schema-Lücken |
|
||||
| `status` | Momentaufnahme: Seitenzahl, Verteilung auf Collections, Befundzahlen |
|
||||
|
||||
## Schritt 4: Ausgeliefert starten (streamable HTTP)
|
||||
|
||||
Der Transport für den Betrieb, und der einzige, vor den sich ein Reverse Proxy setzen kann.
|
||||
|
||||
```bash
|
||||
WIKI_TRACE=0 CHEMENU_ROOT=/srv/chemenu \
|
||||
tools/.venv/bin/python -m chemenu.mcp \
|
||||
--transport streamable-http --host 0.0.0.0 --port 8000
|
||||
```
|
||||
|
||||
Der Endpunkt ist dann `http://<host>:8000/mcp`.
|
||||
|
||||
`--host 0.0.0.0` ist bewusst nicht der Default. Ohne die Angabe bindet der Server auf Loopback,
|
||||
was lokal richtig und im Container falsch ist — dort muss der Proxy ihn erreichen können. Wer
|
||||
`0.0.0.0` setzt, muss also auch dafür sorgen, dass davor etwas steht (Schritt 5).
|
||||
|
||||
`sse` wird nicht angeboten. Es ist der abgelöste Remote-Transport; jetzt darauf zu bauen
|
||||
verschiebt den Wechsel nur.
|
||||
|
||||
## Schritt 5: Authentifizierung davor
|
||||
|
||||
**Der Server authentifiziert nicht selbst, und das ist Absicht.** Nicht sauber
|
||||
authentifizierte Zugriffe sollen den Python-Prozess gar nicht erst erreichen. Die
|
||||
Authentifizierung ist eine Traefik-ForwardAuth-Middleware:
|
||||
|
||||
> **<https://gitea.nehmer.net/torben/gitea-mcp-forward-auth>**
|
||||
|
||||
Kurz, was sie tut: sie prüft `Authorization: Bearer <token>` gegen SHA-256-Hashes erlaubter
|
||||
Tokens, antwortet `200` bei gültigem und `401` bei fehlendem oder falschem Token, und hält
|
||||
`GET /healthz` immer offen. Klartext-Tokens liegen weder in der Konfiguration noch im Log — nur
|
||||
Hashes und ein kurzer Fingerprint. Konfiguriert wird sie über
|
||||
`AUTH_PROXY_TOKEN_HASHES_DIR` (ein Verzeichnis, eine Datei je Token-Hash — passend für ein
|
||||
Kubernetes-Secret-Volume) oder `AUTH_PROXY_TOKEN_HASHES` (kommagetrennte Liste). Einzelheiten,
|
||||
Referenzmanifeste und ein Testskript stehen im README dort.
|
||||
|
||||
Einen Token-Hash erzeugen:
|
||||
|
||||
```bash
|
||||
echo -n "mein-token" | sha256sum | awk '{print $1}'
|
||||
```
|
||||
|
||||
**Rate Limiting gehört an dieselbe Stelle** — vor den Prozess, neben die Authentifizierung.
|
||||
Nicht in den Iteration Budget Gate: der begrenzt eine *Agenten-Session* am unbemerkten Iterieren
|
||||
über den Wiki-Zustand, weshalb Retrieval von ihm ausgenommen ist. Ihn als Rate Limiter zu
|
||||
benutzen würde ihn dazu verwässern.
|
||||
|
||||
## Schritt 6: Den Korpus aktuell halten
|
||||
|
||||
Der Server liest den Arbeitsbaum. Ein veralteter Checkout antwortet selbstbewusst falsch —
|
||||
deshalb trägt **jede Antwort den Commit**, aus dem sie berechnet wurde:
|
||||
|
||||
```json
|
||||
{ "commit": "<40-stelliger SHA>", "as_of": "<ISO-8601, UTC>", "count": 3, "...": "..." }
|
||||
```
|
||||
|
||||
Aktuell gehalten wird der Baum durch Polling, aus einem Timer neben dem Server:
|
||||
|
||||
```bash
|
||||
git -C "$CHEMENU_ROOT" fetch --quiet origin && \
|
||||
git -C "$CHEMENU_ROOT" reset --hard --quiet origin/main
|
||||
```
|
||||
|
||||
Polling statt Webhook, weil es keinen eingehenden Endpunkt und keine Signaturprüfung braucht —
|
||||
eine kleinere Angriffsfläche als das, was es optimieren würde.
|
||||
|
||||
`reset --hard` ist dabei tragend und keine Bequemlichkeit: der Korpus-Cache verwendet einen
|
||||
Parse wieder, solange der Commit gleich bleibt, und cacht einen **schmutzigen Baum überhaupt
|
||||
nicht**. Ein abgedrifteter Checkout antwortet also zwar richtig, parst aber bei jeder Anfrage
|
||||
neu — und stempelt jede Antwort mit `"commit": null`, weil sie keiner Revision entspricht.
|
||||
|
||||
## Verifikation
|
||||
|
||||
Läuft es? Der schnellste Test ohne Client — startet den Server über stdio, listet die Tools und
|
||||
stellt eine Frage:
|
||||
|
||||
```bash
|
||||
cd tools && WIKI_TRACE=0 .venv/bin/python - <<'EOF'
|
||||
import asyncio, os
|
||||
from mcp import ClientSession, StdioServerParameters
|
||||
from mcp.client.stdio import stdio_client
|
||||
|
||||
async def main():
|
||||
params = StdioServerParameters(
|
||||
command=".venv/bin/python", args=["-m", "chemenu.mcp"],
|
||||
env={"WIKI_TRACE": "0", "PATH": os.environ["PATH"]},
|
||||
)
|
||||
async with stdio_client(params) as (r, w):
|
||||
async with ClientSession(r, w) as s:
|
||||
await s.initialize()
|
||||
print("Tools:", [t.name for t in (await s.list_tools()).tools])
|
||||
out = await s.call_tool("status", {})
|
||||
d = getattr(out, "structuredContent", None) or out.structured_content
|
||||
print("Seiten:", d["pages"], "| Commit:", d["commit"])
|
||||
|
||||
asyncio.run(main())
|
||||
EOF
|
||||
```
|
||||
|
||||
Erwartete Ausgabe, sinngemäß:
|
||||
|
||||
```
|
||||
Tools: ['search', 'types', 'describe_type', 'lint', 'status']
|
||||
Seiten: 176 | Commit: 576df2cdddc96614a7e6641e562022d52112d411
|
||||
```
|
||||
|
||||
Gegen die CLI gegenprüfen — beide müssen dieselbe Antwort geben:
|
||||
|
||||
```bash
|
||||
tools/wikitool search "<begriff>" --json
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**`ERROR Telemetry is on and would write into the served checkout`** — erwartetes Verhalten,
|
||||
kein Fehler in der Installation. `WIKI_TRACE=0` setzen oder `WIKI_TRACE_DIR` aus dem Korpus
|
||||
heraus zeigen lassen (Schritt 2).
|
||||
|
||||
**`ModuleNotFoundError: No module named 'mcp'`** — Schritt 1 fehlt, oder der Client startet ein
|
||||
anderes Python als das der Instanz. Im Client den absoluten Pfad auf `tools/.venv/bin/python`
|
||||
setzen.
|
||||
|
||||
**`"commit": null` in jeder Antwort** — der bediente Baum hat uncommittete Änderungen. Entweder
|
||||
läuft der Sync nicht, oder etwas schreibt in den Korpus, das dort nichts zu suchen hat. Der
|
||||
Server selbst schreibt nie; ein Test prüft das, indem er alle fünf Tools aufruft und Dateibaum,
|
||||
`HEAD` und `git status --porcelain` vorher/nachher vergleicht.
|
||||
|
||||
**`commit` nennt eine alte Revision** — der Sync aus Schritt 6 läuft nicht.
|
||||
|
||||
**Der Server antwortet anders als `wikitool`** — das ist ein Defekt, keine
|
||||
Konfigurationsdifferenz: beide gehen durch dieselben Funktionen, und ein Golden-Test hält sie
|
||||
zusammen. Zuerst prüfen, ob beide auf denselben Root zeigen; `CHEMENU_ROOT` ist leicht für einen
|
||||
von beiden gesetzt und für den anderen nicht.
|
||||
|
||||
**Von außen nicht erreichbar** — ohne `--host 0.0.0.0` bindet der Server auf Loopback
|
||||
(Schritt 4). Wenn er dann erreichbar ist, aber jeder Aufruf `401` bekommt, arbeitet die
|
||||
Middleware aus Schritt 5 korrekt und das Token stimmt nicht.
|
||||
|
||||
## Was hier bewusst nicht steht
|
||||
|
||||
Deployment — Cluster, Ingress-Hosts, Secret-Store, FluxCD-Quelle. Das ist private Infrastruktur
|
||||
und dieses Repo ist öffentlich.
|
||||
|
||||
Ein **Container-Image** für den Betrieb gibt es noch nicht; es ist als eigenes Vorhaben erfasst,
|
||||
mitsamt den Entscheidungen, die dafür noch offen sind (Korpus im Image oder als Volume, wer den
|
||||
Sync ausführt, Basis-Image, Healthcheck):
|
||||
<https://gitea.nehmer.net/torben/chemenu/issues/37>. Bis dahin ist der Weg oben — venv,
|
||||
`python -m chemenu.mcp`, Proxy davor — der vollständige.
|
||||
+40
-14
@@ -7,6 +7,10 @@ Repo als Upstream** aufsetzen. Der agent-seitige Ablauf steckt in `instructions/
|
||||
nur die menschlichen Teile - für die vollständige Kommandoreferenz siehe
|
||||
[tools/CONTRACT.md](tools/CONTRACT.md).
|
||||
|
||||
Den optionalen **MCP-Leseserver** installiert und betreibt
|
||||
[INSTALL-MCP.md](INSTALL-MCP.md): derselbe Korpus, lesend, für einen Konsumenten, der kein
|
||||
Terminal auf dieser Maschine ist.
|
||||
|
||||
## Voraussetzungen
|
||||
|
||||
- Python 3.11 oder neuer
|
||||
@@ -64,11 +68,14 @@ Zwei Schritte, von denen nur der erste rein menschlich ist:
|
||||
Wiki-Seite (`$WIKI_AUTHOR` überschreibt dies bei Bedarf).
|
||||
- **Remote** (optional) - eine URL, wenn du das Repo auf einen Server pushen willst; sonst
|
||||
bleibt die Instanz lokal, und jedes `publish` läuft mit `--no-push`.
|
||||
- **KB-Sprache** - die exportierte Distribution bringt **Deutsch** mit: die Regel in
|
||||
`kb/CONTRACT.md`, das Vokabular in `instructions/german-terminology.md` und deutsche
|
||||
Abschnittsnamen in den Seitenvorlagen. Das ist eine Entscheidung dieser Ursprungsinstanz,
|
||||
keine Eigenschaft des Musters. Willst du eine andere Sprache, sag es **vor dem ersten
|
||||
Ingest** - danach ist es eine Migration jeder bereits angelegten Seite.
|
||||
- **Autorenkonventionen** - Sprache, Abschnittsnamen, Namensformen, Ton, Beziehungslabels
|
||||
und Confidence-Rubrik stehen in `kb/CONVENTIONS.md`, dazu je Collection die Regeln in
|
||||
`kb/<name>/COLLECTION.md`. Die Distribution bringt davon nur die `.template`-Dateien mit:
|
||||
das sind Entscheidungen *dieser* Instanz, keine Eigenschaft des Musters, und nichts davon
|
||||
liegt unter `tools/` oder `types/`. Fertige Profile - darunter ein vollständiges deutsches -
|
||||
hält `instructions/kb-profiles.md` bereit; es ist eine Palette, kein Enum. Sag die Sprache
|
||||
**vor dem ersten Ingest** - danach ist ein Wechsel der Abschnittsnamen eine Migration jeder
|
||||
bereits angelegten Seite.
|
||||
- **Personalization** - wer diese Instanz bedient (`USER.md`) und wie sie klingt
|
||||
(`SOUL.md`). Die Distribution bringt nur `USER.md.template` und `SOUL.md.template` mit:
|
||||
persönlicher Inhalt gehört nicht in jede exportierte Kopie, aber beide Dateien werden in
|
||||
@@ -142,8 +149,21 @@ nicht erreichbarer Feed wird als Fehler gemeldet - **nie** als „aktuell".
|
||||
|
||||
**Was die Versionsnummer aussagt:** kompatibel ist, was in der *linkesten von Null
|
||||
verschiedenen Stelle* übereinstimmt. `0.1.3 → 0.1.4` ist ein sicheres Update, `0.1.3 → 0.2.0`
|
||||
verlangt eine Migration, und ab `1.0.0` liest sich dieselbe Regel als das gewohnte „MAJOR heißt
|
||||
Migration". `version check` sagt das direkt (`state: update` vs. `state: migration`).
|
||||
nicht, und ab `1.0.0` liest sich dieselbe Regel als das gewohnte „MAJOR bricht". `version check`
|
||||
sagt das direkt (`state: update` vs. `state: migration`).
|
||||
|
||||
Was diese Stelle beantwortet, ist **ob die neue Version ein Drop-in-Ersatz ist** - ob sich die
|
||||
Maschinerie einfach darüberkopieren lässt und ob die alte danach noch zurückkann. Ob *Inhalt*
|
||||
migriert werden muss, ist eine **zweite, unabhängige Frage**. Ein MAJOR-Sprung kann eine leere
|
||||
Migrationskette haben und trotzdem Handarbeit verlangen: umbenannter Release-Feed, umbenanntes
|
||||
Artefakt, umbenannter Import- oder Kommandoname, geänderte Envvar - `kb/` bleibt dabei
|
||||
unangetastet, das Update ist trotzdem keins zum Drüberkopieren. Der Abschnitt „Sonderfall:
|
||||
Update von 1.x auf 2.0.0" unten ist genau dieser Fall.
|
||||
|
||||
Deshalb stehen in den Release-Notes eines MAJOR zwei getrennte Zeilen, und beide sind vor dem
|
||||
Update zu lesen: **Breaking Change:** sagt, was aufhört zu funktionieren und was diese Instanz
|
||||
dagegen tun muss; **Migration:** sagt, ob und wie der Korpus umgeschrieben wird (`none required`,
|
||||
wenn nicht). `tools/wikitool version notes` druckt den Eintrag.
|
||||
|
||||
### Eine Instanz aktualisieren
|
||||
|
||||
@@ -160,13 +180,17 @@ dieser Unterschied ist der Zustand, in dem sich jede Instanz mitten im Upgrade b
|
||||
|
||||
2. Release-Tarball herunterladen und entpacken (Weg A), die Release-Notes lesen.
|
||||
3. Die **Maschinerie** aus dem Tarball über die Instanz kopieren: `tools/`, `types/`,
|
||||
`instructions/`, `AGENTS.md`, `VERSION`, `.wikitool-release.json`. Nicht anfassen: `kb/`,
|
||||
`raw/`, `work/`, `.wikitool-kb.json` und `.git/` - das ist die Instanz selbst.
|
||||
4. Achtung bei lokal angepassten Contract-Dateien: wer z. B. die KB-Sprache umgestellt hat
|
||||
(Schritt 5 in `setup-instance.md`), hat `kb/CONTRACT.md` und die Templates unter `types/`
|
||||
verändert. Diese Änderungen vorher sichern und danach wieder einspielen. Welche Dateien das
|
||||
sind, verrät ein Vergleich gegen die sha256-Summen im `files`-Block der alten
|
||||
`.wikitool-release.json`.
|
||||
`instructions/`, `AGENTS.md`, `VERSION`, `.wikitool-release.json` - **und `kb/CONTRACT.md`**.
|
||||
Die letzte Datei liegt unter einem Content-Verzeichnis, ist aber Stack-Eigentum: sie hält,
|
||||
was `wikitool` erzwingt, und ist in jeder Instanz gleich. Nicht anfassen: alles andere unter
|
||||
`kb/` und `raw/`, `work/`, `.wikitool-kb.json` und `.git/` - das ist die Instanz selbst,
|
||||
`kb/CONVENTIONS.md` und die `kb/*/COLLECTION.md` eingeschlossen.
|
||||
4. Achtung bei lokal angepassten Stack-Dateien. Die Autorenkonventionen gehören **nicht** dazu:
|
||||
`kb/CONVENTIONS.md` und die `kb/*/COLLECTION.md` liegen unter `kb/`, werden in Schritt 3
|
||||
also ohnehin nicht angefasst - genau dafür ist der Schnitt da. Wer darüber hinaus etwas
|
||||
unter `tools/`, `types/` oder `instructions/` verändert hat, sichert das vorher und spielt
|
||||
es danach wieder ein. Welche Dateien das sind, verrät ein Vergleich gegen die sha256-Summen
|
||||
im `files`-Block der alten `.wikitool-release.json`.
|
||||
5. **Die Migrationskette abarbeiten.** `tools/wikitool migrate status` listet jetzt alle
|
||||
offenen Migrationen in der Reihenfolge, in der sie laufen müssen - bei einem Sprung über
|
||||
mehrere Versionen sind das mehrere. Für jede: das genannte Dokument unter
|
||||
@@ -223,6 +247,8 @@ behält Schema und Shape.
|
||||
| `WIKITOOL_SESSION_ID` | Scopt das Iteration-Budget-Gate auf eine Aufgabe statt auf ein Terminal | Parent-Process-ID (siehe [instructions/session-setup.md](instructions/session-setup.md)) |
|
||||
| `WIKITOOL_UPDATE_URL` | Release-Feed, den `version check` abfragt | Wert aus `.wikitool-release.json`, sonst der Feed der Ursprungs-Instanz |
|
||||
| `WIKITOOL_UPDATE_TOKEN` | Gitea-Token für den Release-Feed | keiner - gegen `torben/chemenu` nicht nötig, nur für einen privaten Fork (siehe unten) |
|
||||
| `CHEMENU_ROOT` | Auf welchen Korpus das Paket zeigt - für einen Aufrufer, der nicht im Checkout selbst liegt | der Checkout, in dem das Paket liegt (`tools/wikitool` verhält sich ohne die Variable unverändert) |
|
||||
| `WIKI_TRACE` / `WIKI_TRACE_DIR` | Telemetrie abschalten bzw. aus dem Arbeitsbaum heraus umlenken | an, nach `reports/telemetry/` - der MCP-Server verweigert damit den Start, siehe [INSTALL-MCP.md](INSTALL-MCP.md) |
|
||||
|
||||
**Gegen das Ursprungs-Repo braucht es kein Token.** `torben/chemenu` ist öffentlich lesbar;
|
||||
`version check` und der Download in Weg A funktionieren ohne Konfiguration.
|
||||
|
||||
@@ -14,12 +14,15 @@ and maintains a persistent wiki** that compounds over time.
|
||||
English; the compiled pages under `kb/` are not. What stays English inside them is everything that
|
||||
is an *identifier* rather than prose - page titles, section headings, wikilink targets, citation
|
||||
ids, schema enum values, tags, commands, paths and code - so `GitOps Ownership Model` and
|
||||
`## Beziehungen` sit in the same page without contradiction. The rule is
|
||||
[kb/CONTRACT.md § Language](kb/CONTRACT.md#language); the vocabulary behind it is
|
||||
`## Beziehungen` sit in the same page without contradiction. Which lines are identifiers is
|
||||
[kb/CONTRACT.md § Language and identifiers](kb/CONTRACT.md#language-and-identifiers); *which
|
||||
language* the prose is in, and what the tool-owned headings are called, is this instance's own
|
||||
[kb/CONVENTIONS.md](kb/CONVENTIONS.md), and the vocabulary behind it is
|
||||
[instructions/german-terminology.md](instructions/german-terminology.md).
|
||||
|
||||
This is a per-instance decision, not a property of the pattern. A new instance built with
|
||||
`dist export` starts empty and can pick any language by editing that one contract section before
|
||||
This is a per-instance decision, not a property of the pattern - which is why it lives in a file
|
||||
the instance owns rather than in one the stack ships. A new instance built with
|
||||
`dist export` starts empty and picks any language by filling in `kb/CONVENTIONS.md` before
|
||||
the first ingest.
|
||||
|
||||
## Getting started
|
||||
@@ -51,6 +54,7 @@ chemenu/
|
||||
├── CLAUDE.md # Claude Code only: imports AGENTS.md/USER.md/SOUL.md/ENVIRONMENT.md + its Claude-Code-only instructions. No rules of its own
|
||||
├── README.md # This file: human-readable overview of the whole repo
|
||||
├── INSTALL.md # Human-readable setup: new instance vs. cloning this one
|
||||
├── INSTALL-MCP.md # Human-readable setup for the optional MCP read server
|
||||
├── EVALS.md # Human-readable overview of telemetry and evaluation
|
||||
├── CHANGES.md # Changelog for the stack itself
|
||||
├── USER.md # Who operates this instance - context, never instructions
|
||||
@@ -363,8 +367,11 @@ WIKI_TRACE=0 tools/.venv/bin/python -m chemenu.mcp \
|
||||
```
|
||||
|
||||
The dependency is deliberately not in `requirements.txt`: an instance that only uses the CLI
|
||||
should not have to install a web stack to do it. Running it, keeping its checkout current, and
|
||||
where authentication belongs (in front of the process, not in it) are in
|
||||
should not have to install a web stack to do it.
|
||||
|
||||
Installing it, wiring a client to it, and putting authentication in front of it:
|
||||
[`INSTALL-MCP.md`](INSTALL-MCP.md), for humans. The agent-side operating procedure - keeping the
|
||||
checkout current, and what a stale answer looks like - is
|
||||
[`instructions/mcp-read-server.md`](instructions/mcp-read-server.md).
|
||||
|
||||
### Obsidian
|
||||
@@ -397,7 +404,7 @@ This wiki is tailored for IT work with:
|
||||
|
||||
- **Entity types** specific to software development and systems
|
||||
- **Relationship types** like `hängt ab von`, `verwendet`, `implementiert` - the vocabulary is in
|
||||
[kb/CONTRACT.md § Linking](kb/CONTRACT.md#linking)
|
||||
[kb/CONVENTIONS.md](kb/CONVENTIONS.md), because it is this instance's rather than the stack's
|
||||
- **Templates** for projects, systems, tools, technologies, ADRs
|
||||
- **Guidelines** for documenting technical decisions
|
||||
- **Cross-reference patterns** for code and architecture
|
||||
|
||||
@@ -58,16 +58,38 @@ whether an instruction is still reachable, which is exactly why the answer means
|
||||
`instructions/dev/` boundary check below asks the opposite question - what would *dangle* in a
|
||||
distributed instance - and does scan README.md, because `dist export` ships it verbatim.
|
||||
|
||||
Two kinds of file use the Manual tier today: [german-terminology.md](german-terminology.md), a
|
||||
vocabulary consulted on demand rather than a procedure, and every migration document (below).
|
||||
Three kinds of file use the Manual tier today: [german-terminology.md](german-terminology.md), a
|
||||
vocabulary consulted on demand rather than a procedure; [kb-profiles.md](kb-profiles.md), the
|
||||
catalogue of authoring profiles an instance may adopt into its own `kb/CONVENTIONS.md` and
|
||||
`COLLECTION.md` files; and every migration document (below).
|
||||
|
||||
## `instructions/migrations/`
|
||||
|
||||
A content migration is a Manual instruction with two extra frontmatter fields
|
||||
A content migration is a Manual instruction with three extra frontmatter fields
|
||||
(`types/instruction.schema.yaml`): `migrates_to:`, the stack version whose content shape it
|
||||
produces, and `migration_kind:` (`mechanical` | `assisted`). It lives at
|
||||
produces; `migration_kind:` (`mechanical` | `assisted`); and `obligation:`
|
||||
(`required` | `offered`, default `required`). It lives at
|
||||
`instructions/migrations/<version>-<slug>.md`.
|
||||
|
||||
`migration_kind:` and `obligation:` are **two axes, not one**. The first says how the work is
|
||||
carried out, the second whether it has to happen at all:
|
||||
|
||||
| `obligation:` | Means | `migrate status` |
|
||||
|---|---|---|
|
||||
| `required` | The content must reach the new shape or it no longer fits the machinery | Counted as outstanding; `migrate done` advances `kb_version` through it, in chain order |
|
||||
| `offered` | A file the instance owns still works as it is, and the stack proposes a better default | Listed separately, never blocks, no ordering rule. `migrate done` records it in the applied ledger and leaves `kb_version` where it is |
|
||||
|
||||
Keeping them apart is what stops `migrate status` crying wolf: an instance nagged about an
|
||||
improvement it declined stops reading the nag that means its content no longer fits its
|
||||
machinery. And because taking an offer deliberately does not move the version, the **applied
|
||||
ledger** - not `kb_version` - is what makes an offer stop being offered; without that record
|
||||
there is no way to tell a taken offer from an ignored one.
|
||||
|
||||
An `offered` migration is what makes an instance-owned file upgradeable at all. `dist export`
|
||||
records a sha256 per shipped file in `.wikitool-release.json`, so `migrate status` can say which
|
||||
of those files the instance edited and which it merely received - the first have to be
|
||||
reconciled by a person, the second can simply be copied over.
|
||||
|
||||
The tier fits exactly: a migration must never be picked up implicitly - it rewrites the corpus -
|
||||
and it is referenced by nothing, because `tools/wikitool migrate status` finds it by reading the
|
||||
directory and comparing `migrates_to:` against this instance's `kb_version`. That is also why
|
||||
@@ -153,7 +175,8 @@ What lives where:
|
||||
|-------|------|
|
||||
| [AGENTS.md](../AGENTS.md) | Invariants and routing - what must always hold |
|
||||
| `instructions/` | How the tooling is *operated* |
|
||||
| [kb/CONTRACT.md](../kb/CONTRACT.md) + each `COLLECTION.md` | How a page is *authored* |
|
||||
| [kb/CONTRACT.md](../kb/CONTRACT.md) | What the stack enforces about a page, in every instance |
|
||||
| `kb/CONVENTIONS.md` + each `COLLECTION.md` | What *this* instance decided about authoring - owned by the instance, shipped only as a `.template` |
|
||||
| [types/](../types/type-spec.md) | What a page structurally *is* |
|
||||
| [tools/CONTRACT.md](../tools/CONTRACT.md) | What each command does and how it fails |
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
type: types/instruction.md
|
||||
name: issue-tracking
|
||||
description: Where open work on this stack is tracked, and what the prio/ and size/ labels on a Gitea issue mean.
|
||||
description: Where open work on this stack is tracked, what the four mandatory area/kind/prio/size labels and the two status flags on a Gitea issue mean, and how to keep an issue body current across sessions.
|
||||
---
|
||||
# Track open work as Gitea issues, not as prose in the repo
|
||||
|
||||
@@ -26,6 +26,8 @@ issues at that URL, which is exactly why `dist export` excludes
|
||||
the repo.
|
||||
- A session's findings outgrow the change it was making - a gap in the tooling,
|
||||
an assumption nobody has checked, a decision that needs the user.
|
||||
- Picking an issue up: before doing anything else, read the body as the current
|
||||
spec, and re-label it if the ground has moved since.
|
||||
- Prioritising: deciding what to pick up next, or re-labelling after the ground
|
||||
moved.
|
||||
|
||||
@@ -36,35 +38,96 @@ issues at that URL, which is exactly why `dist export` excludes
|
||||
specific files or commands involved. An issue that only makes sense to
|
||||
whoever wrote it is a note, and notes were the problem.
|
||||
|
||||
2. **Give it exactly two labels: one `prio/`, one `size/`.** Both, always -
|
||||
a priority without a cost is half a decision. Neither is a promise about
|
||||
*when*; together they answer "what should I pick up in the time I have".
|
||||
2. **Treat the body as the current truth, not as a historical first post.**
|
||||
Work on one issue spans several sessions, often weeks apart, and the body is
|
||||
the only thing that connects them: a session opening the issue must be able
|
||||
to reconstruct what is decided and what is still open from the body alone,
|
||||
without a human re-explaining it. So when the state changes, **rewrite the
|
||||
body** - do not append to a text that has become wrong. An additively grown
|
||||
log forces every later reader to reconstruct the current state by filtering
|
||||
the whole history.
|
||||
|
||||
| Priority | Means |
|
||||
Body rewrites and comments are an LLM session's job. A human normally
|
||||
touches only labels and metadata directly.
|
||||
|
||||
3. **Comment a changelog, never a copy.** Every body rewrite gets one short
|
||||
comment naming only what changed against the previous state - what is new,
|
||||
what is gone, what was corrected. Do not snapshot the old body into a
|
||||
comment: a full copy per revision forces a human to diff two prose texts,
|
||||
which is not a readable history, only another copy.
|
||||
|
||||
```
|
||||
**Changelog:** Decision 2 tightened - `kind/` may now change over an
|
||||
issue's life. Old acceptance criterion 3 dropped (covered by #42).
|
||||
```
|
||||
|
||||
4. **Give it all four mandatory labels: one `area/`, one `kind/`, one `prio/`,
|
||||
one `size/`.** All four, always. Machine maintenance by an LLM session is
|
||||
what makes four axes affordable - the original objection to a third and
|
||||
fourth axis was the upkeep cost for a single human maintainer, and that
|
||||
objection no longer holds.
|
||||
|
||||
| `area/` | Means |
|
||||
|---|---|
|
||||
| `prio/1` | Blocks or damages work in progress. Next. |
|
||||
| `prio/2` | Accrues interest. Planned. |
|
||||
| `prio/3` | Worth doing, waiting on a trigger. |
|
||||
| `area/kb` | The `kb/` schema, contract, confidence machinery, lint - the knowledge base as a system. |
|
||||
| `area/distribution` | Shipping, upgrading and versioning an instance. |
|
||||
| `area/corpus` | The content and scope of `kb/` in this instance, and the demo/testbed question. |
|
||||
| `area/workflow` | Git, merging, branching, publish, PRs. |
|
||||
| `area/process` | The development process itself, rather than the stack as an artefact. |
|
||||
|
||||
`prio/3` is not a graveyard. It means the issue's value is real but gated on
|
||||
something outside it - a decision, another issue, a second instance
|
||||
There is deliberately no `area/tools`: tooling is filed under the domain it
|
||||
serves, not under where its code sits. The axis follows the stage split in
|
||||
[AGENTS.md](../../AGENTS.md).
|
||||
|
||||
| `kind/` | Means |
|
||||
|---|---|
|
||||
| `kind/decision` | Waiting on an operator decision. |
|
||||
| `kind/build` | Specified; waiting only on implementation time. |
|
||||
| `kind/defect` | A finding: documentation and reality, or two documents, contradict each other. |
|
||||
|
||||
`kind/` is expected to change over an issue's life - `decision` becomes
|
||||
`build` once the decision is made. That is session memory working, not a
|
||||
labelling failure.
|
||||
|
||||
| `prio/` | Means |
|
||||
|---|---|
|
||||
| `prio/blocking` | Blocks or damages work in progress. Next. |
|
||||
| `prio/planned` | Accrues interest. Planned. |
|
||||
| `prio/waiting` | Worth doing, waiting on a trigger. |
|
||||
|
||||
`prio/waiting` is not a graveyard. It means the issue's value is real but
|
||||
gated on something outside it - a decision, another issue, a second instance
|
||||
existing. Name that trigger in the issue, or the label is a polite no.
|
||||
|
||||
| Size | Means |
|
||||
| `size/` | Means |
|
||||
|---|---|
|
||||
| `size/XS` | Minutes. Often just a decision or an observation to record. |
|
||||
| `size/S` | One session, one publish, a clear cut. |
|
||||
| `size/M` | Several files; a contract or instruction change; its own test effort. |
|
||||
| `size/L` | Several sessions, or open design questions before the first commit. |
|
||||
|
||||
Size is effort, not importance. A `prio/1 size/XS` is the best thing on the
|
||||
board; a `prio/3 size/L` is a thing to talk about before anyone starts.
|
||||
Size is effort, not importance. A `prio/blocking size/S` is the best thing
|
||||
on the board; a `prio/waiting size/L` is a thing to talk about before anyone
|
||||
starts.
|
||||
|
||||
3. **Re-label when the ground moves, and say why in a comment.** A trigger that
|
||||
fired turns `prio/3` into `prio/2`. A design question that got answered can
|
||||
drop a size. Silent re-labelling is how a board stops meaning anything.
|
||||
5. **Add a `status/` flag only when it applies.** Both are optional, because
|
||||
each describes a temporary condition rather than a property every issue has.
|
||||
|
||||
4. **Close with what actually happened**, not with a commit hash alone: which
|
||||
| `status/` | Means |
|
||||
|---|---|
|
||||
| `status/blocked` | Waiting on another, still-open issue - not workable on its own, whatever its `prio/` says. Name the blocking issue in the body. |
|
||||
| `status/unconfirmed` | A reported suspicion, not yet checked against actual behaviour. Applies to any `kind/`, not just `kind/defect`. |
|
||||
|
||||
While `status/unconfirmed` is set, `size/` and `prio/` are provisional. Triage
|
||||
ends it one of two ways: the flag comes off and `size`/`prio` are set for
|
||||
real, or the issue is closed with the reason. An unverified suspicion does not
|
||||
stay open indefinitely - the process-level analogue of AGENTS.md invariant 3.
|
||||
|
||||
6. **Re-label when the ground moves, and say why in a comment.** A trigger that
|
||||
fired turns `prio/waiting` into `prio/planned`. A design question that got
|
||||
answered can drop a size and move `kind/decision` to `kind/build`. Silent
|
||||
re-labelling is how a board stops meaning anything.
|
||||
|
||||
7. **Close with what actually happened**, not with a commit hash alone: which
|
||||
proposals were implemented, which were deliberately left out and why, and
|
||||
what was verified. The issue is the only place that record survives - a
|
||||
changelog entry says what changed, not what was decided against.
|
||||
@@ -75,8 +138,13 @@ issues at that URL, which is exactly why `dist export` excludes
|
||||
what shipped. A finished change needs both: the entry, and the issue closed
|
||||
with the reasoning.
|
||||
- **Issue or `kb/` page?** An issue is about *this stack* and is ephemeral - it
|
||||
closes. A `kb/` page is compiled knowledge that stays true. Never put wiki
|
||||
content findings in an issue, and never file a work item as a page.
|
||||
- **Two labels feel too coarse?** They are meant to. A third axis - kind, area,
|
||||
status - is the point at which a taxonomy starts needing maintenance of its
|
||||
own, and this board has one maintainer.
|
||||
closes, and it records a wish. A `kb/` page is verified knowledge that stays
|
||||
true. Never put wiki content findings in an issue, and never file a work item
|
||||
as a page.
|
||||
- **Rewrite the body, or add a comment?** Rewrite whenever a reader of the body
|
||||
alone would otherwise be misled - a changed decision, a dropped criterion, a
|
||||
new constraint. A comment carries the changelog line for that rewrite, and
|
||||
nothing else that a future session needs in order to act.
|
||||
- **An old issue carries only `prio/` and `size/`?** Complete it to all four
|
||||
when you touch it, rather than in a sweep. The board reaches the new scheme
|
||||
issue by issue, as each is picked up.
|
||||
|
||||
@@ -43,11 +43,15 @@ stack development happens in the origin repo instead (see AGENTS.md's routing li
|
||||
engineering, memory and deploy-time learning; consult before a design decision in those
|
||||
areas.
|
||||
[issue-tracking.md](../issue-tracking.md) - open work lives in Gitea issues, one per work
|
||||
package, labelled `prio/1..3` and `size/XS..L`. There is no `TODO.md`. Read it before
|
||||
filing something for later, or before deciding what to pick up next.
|
||||
package, labelled `area/`, `kind/`, `prio/` and `size/`, with the body kept as the current
|
||||
truth rather than as a first post. There is no `TODO.md`. Read it before filing something
|
||||
for later, before editing an issue, or before deciding what to pick up next.
|
||||
[testing-conventions.md](../testing-conventions.md) - the suite runs against a deliberately
|
||||
empty machine; what the autouse fixture already neutralizes, and what a test still has to
|
||||
establish itself. Read it before adding or changing a test.
|
||||
[version-parts.md](../version-parts.md) - which part a change bumps: the drop-in test, the
|
||||
catalogue of breaks that cross the compatibility boundary with `kb/` untouched, and what to
|
||||
put in front of the user before a breaking bump. Read it before step 3.
|
||||
More instructions are added here incrementally as stack-development needs come up - this
|
||||
list grows without needing this skill file to change shape.
|
||||
3. **Raise the version, if the change ships.** A change under `tools/`, `types/`,
|
||||
@@ -59,18 +63,27 @@ stack development happens in the origin repo instead (see AGENTS.md's routing li
|
||||
```
|
||||
|
||||
Never edit `VERSION` or the entry's heading by hand - `bump` writes both, and `docs verify`
|
||||
fails a tree where they disagree. Pick the part by what an existing instance would have to do:
|
||||
fails a tree where they disagree. Pick the part by whether the new version is a **drop-in
|
||||
replacement** for the old one - not by whether content has to be migrated:
|
||||
|
||||
| Change | Part |
|
||||
|--------|------|
|
||||
| Fix, no interface change | `--patch` |
|
||||
| New capability, backwards compatible | `--minor` |
|
||||
| **Existing content must be migrated** | `--major` |
|
||||
| New capability, still drop-in in both directions | `--minor` |
|
||||
| **Not a drop-in replacement** - any hand-work by the user or a migration script, or a downgrade that no longer works | `--major` |
|
||||
|
||||
A `--major` bump additionally needs a migration document for the new version - written per
|
||||
[migrate-corpus.md](../../migrate-corpus.md) - or `--no-migration "<reason>"` when no content
|
||||
actually has to change. `bump` refuses otherwise, and so does `docs verify`: an instance
|
||||
learning that it must migrate, with nothing telling it how, is a dead end.
|
||||
Content migration is one way to land in the last row, not the definition of it: a rename of
|
||||
the update path, the artefact, an import name, a flag or an envvar breaks a swap with `kb/`
|
||||
entirely untouched. The full test, the catalogue of such breaks, and what to put in front of
|
||||
the user first are in [version-parts.md](../version-parts.md) - **read it before choosing
|
||||
`--major`.**
|
||||
|
||||
A `--major` bump therefore needs two things recorded. `--breaking "<what stops working>"`
|
||||
is required on every boundary-crossing bump; on top of it, a migration document for the new
|
||||
version - written per [migrate-corpus.md](../../migrate-corpus.md) - or
|
||||
`--no-migration "<reason>"` when no content actually has to change. `bump` refuses without
|
||||
either, and so does `docs verify`: an instance learning that it must migrate, with nothing
|
||||
telling it how, is a dead end.
|
||||
|
||||
Then write the entry's body - `bump` deliberately leaves it empty, the same way `new` leaves
|
||||
the prose.
|
||||
@@ -90,6 +103,12 @@ stack development happens in the origin repo instead (see AGENTS.md's routing li
|
||||
- **Touches both stack code and wiki content in one session?** Apply this skill's rules to the
|
||||
code changes and the normal content skills' rules to the content changes - they are not
|
||||
mutually exclusive within a session, only per change.
|
||||
- **The change turns out not to be a drop-in replacement?** Do not bump across the boundary on
|
||||
your own initiative. Every existing instance pays for a breaking change once, by hand, so the
|
||||
user decides whether it is worth that: show them what breaks, what an instance has to do about
|
||||
it, and the alternatives (avoid the break with a shim, defer and batch it with the next one,
|
||||
or split it behind a deprecation window), then recommend one and wait for a go-ahead.
|
||||
[version-parts.md](../version-parts.md) step 4 has the full shape.
|
||||
|
||||
## Scope
|
||||
|
||||
|
||||
@@ -35,6 +35,11 @@ Do not re-do any of this per test; it is done for you, per test, via `monkeypatc
|
||||
fixture redirects it into `tmp_path`. Tracing is never disabled suite-wide, because two
|
||||
telemetry tests assert that a trace gets written.
|
||||
|
||||
Two in-process caches are cleared alongside the environment, for the same reason: `config`'s
|
||||
resolved paths and `conventions`' parsed `kb/CONVENTIONS.md`. A test that *rewrites* the
|
||||
conventions file mid-test calls `conventions.reset_cache()` itself - the fixture answers for the
|
||||
boundary between tests, not for one inside a test.
|
||||
|
||||
## When to run
|
||||
|
||||
Whenever you add or change a test under `tools/chemenu/tests/`.
|
||||
|
||||
@@ -0,0 +1,149 @@
|
||||
---
|
||||
type: types/instruction.md
|
||||
name: version-parts
|
||||
description: Which part of the stack version a change bumps - the compatibility question (is the new version a drop-in replacement?) separated from the migration question (must existing content change?), plus what to do before a breaking bump.
|
||||
---
|
||||
# Pick the version part for a stack change
|
||||
|
||||
Two questions decide a version bump, and they are **not the same question**:
|
||||
|
||||
1. **Is the new version a drop-in replacement for the old one?** This is what the version
|
||||
number itself says. Compatibility is read off the **leftmost non-zero component** - on this
|
||||
stack (`2.x`) that is MAJOR, on a `0.x` stack it is MINOR. A bump that changes it is called
|
||||
*boundary-crossing* below, because that is the term `version bump` and `docs verify` use in
|
||||
their own messages.
|
||||
2. **Must existing content be migrated?** This is a *consequence* a boundary crossing may or
|
||||
may not have. `kb/` staying untouched does not make a change compatible, and
|
||||
`version bump --no-migration` exists precisely because boundary-crossing bumps with an
|
||||
untouched corpus are a real case.
|
||||
|
||||
Getting these backwards is how a genuinely breaking change ships as a MINOR. It happened once
|
||||
already (see the case study at the end), which is why this file exists.
|
||||
|
||||
## When to run
|
||||
|
||||
Before every `tools/wikitool version bump` - the `stack-dev` skill's step 3 sends you here.
|
||||
Read it in full the first time a change looks like it might be boundary-crossing; afterwards
|
||||
the three-line test below is usually enough.
|
||||
|
||||
## Steps
|
||||
|
||||
1. **Apply the drop-in test.** The bump is boundary-crossing if **either** half fails:
|
||||
|
||||
- **Forward:** an existing instance can install the new machinery by copying `tools/`,
|
||||
`types/`, `instructions/`, `AGENTS.md`, `VERSION` and `.wikitool-release.json` over itself,
|
||||
and everything that worked before still works - with **no** hand-work by the user and **no**
|
||||
migration script. Any step beyond the copy, however small, fails this half.
|
||||
- **Backward:** having installed the new version, the user can put the old one back and be
|
||||
where they started. A state file the old version cannot read, a rewritten corpus, a
|
||||
renamed stamp - anything that makes the downgrade fail or leave a broken instance - fails
|
||||
this half.
|
||||
|
||||
Content migration is one way to fail the forward half, not the definition of it.
|
||||
|
||||
2. **Check the catalogue** when the answer still feels like a judgment call. Each of these
|
||||
crosses the boundary with `kb/` entirely untouched:
|
||||
|
||||
| What changed | Why the swap is not drop-in |
|
||||
|---|---|
|
||||
| The update path - `update_url`, the release feed, the repo it points at | The instance cannot repair its own `.wikitool-release.json`: it is machine-written, and invariant 1 forbids the hand-edit. The channel that would have told it to update is the channel that broke |
|
||||
| The release artefact's name | Every download script and every pin against it breaks |
|
||||
| The Python package's import name | `from <old> import ...` outside the shipped tree breaks |
|
||||
| A command, subcommand, or flag that was removed or renamed | Scripts, CI workflows and instruction files calling the old spelling break |
|
||||
| An environment variable's name | An instance configured through it silently loses the configuration |
|
||||
| The shape of a machine-read file - `.wikitool-kb.json`, `.wikitool-release.json`, a generated index | The old version cannot read what the new one wrote, so the downgrade half fails even if the upgrade half passed |
|
||||
| A type-spec's required fields | Existing pages stop validating - this one crosses *and* needs a content migration |
|
||||
|
||||
The catalogue is illustrative, not exhaustive. When something is not on it, go back to step 1.
|
||||
|
||||
3. **Otherwise pick the compatible part:**
|
||||
|
||||
| Change | Part |
|
||||
|---|---|
|
||||
| Fix, no interface change | `--patch` |
|
||||
| New capability, drop-in in both directions | `--minor` |
|
||||
|
||||
4. **Stop and talk to the user before a boundary-crossing bump.** It is expensive in a way the
|
||||
other two parts are not: every existing instance pays for it, once, by hand. Put in front of
|
||||
them, in this order:
|
||||
|
||||
- **What breaks**, concretely - which file, which name, which call site.
|
||||
- **What each existing instance must do**, as the steps they would actually run.
|
||||
- **The alternatives**, so the break is a choice and not a side effect:
|
||||
- *Avoid it* - keep the old name as an alias, read both file shapes, accept both flag
|
||||
spellings. A compatibility shim carried for one release is usually cheaper than a
|
||||
migration everyone runs.
|
||||
- *Defer and batch it* - hold the break until the next boundary crossing, so instances pay
|
||||
once instead of twice.
|
||||
- *Split it* - ship the compatible half now, the breaking half later behind a deprecation
|
||||
window that the changelog announces in advance.
|
||||
- **Your recommendation**, with the trade-off named.
|
||||
|
||||
Then wait for an explicit go-ahead. Do not bump across the boundary on your own initiative.
|
||||
|
||||
5. **Record the break in the bump itself.** A boundary-crossing bump requires
|
||||
`--breaking "<what breaks>"`, which writes a `**Breaking Change:**` line into the entry:
|
||||
|
||||
```bash
|
||||
tools/wikitool version bump --major \
|
||||
--title "<what changed>" \
|
||||
--breaking "<what stops working, and what an instance must do about it>" \
|
||||
--no-migration "<why no page has to change>" # only if that is true
|
||||
```
|
||||
|
||||
`--breaking` is refused on a bump that crosses nothing, and required on one that does;
|
||||
`docs verify` checks the newest boundary-crossing entry still carries the line. Write it for
|
||||
the operator of an instance that has not read this repository: what stops working, and what
|
||||
they do about it.
|
||||
|
||||
6. **Then answer the migration question separately.** Boundary-crossing and
|
||||
content-migrating are independent:
|
||||
|
||||
- Content must change → write the migration document under `instructions/migrations/` per
|
||||
[migrate-corpus.md](../migrate-corpus.md). `bump` finds it by its `migrates_to:` field.
|
||||
- Content need not change → `--no-migration "<reason>"`, which records that in the entry.
|
||||
|
||||
Both are also needed by `docs verify`, for the same reason: an instance that learns it must
|
||||
migrate, with nothing telling it how, is a dead end.
|
||||
|
||||
7. **Write the entry's body.** `bump` leaves it empty on purpose. A boundary-crossing entry
|
||||
earns a paragraph that says *why this is breaking* - it is the one thing a future reader
|
||||
cannot reconstruct from the diff, and it is what the next session in this position will read
|
||||
instead of guessing.
|
||||
|
||||
## Decision points
|
||||
|
||||
- **The change ships no code - only `README.md`, `INSTALL.md`, `EVALS.md`, or `.gitea/`?** No
|
||||
bump at all; CI's version gate is scoped to what changes behaviour.
|
||||
- **A break you can see coming but are not making yet?** File it as an issue and let it
|
||||
accumulate. Boundary crossings are cheaper in batches, and step 4's "defer" alternative is
|
||||
only real if someone wrote the break down.
|
||||
- **Unsure between MINOR and boundary-crossing?** It is boundary-crossing. The cost of an
|
||||
unnecessary MAJOR is one extra release note; the cost of a MINOR that actually breaks is an
|
||||
instance whose update path fails while its version number promised it would not.
|
||||
- **The break only affects this repository, not a distributed instance** - something under
|
||||
`instructions/dev/`, say? Then it is not a stack break at all: `dist export` never shipped it.
|
||||
Judge by what an *exported* instance sees.
|
||||
|
||||
## Scope
|
||||
|
||||
Applies to the stack version in `VERSION` - `tools/`, `types/`, `instructions/`, `AGENTS.md`
|
||||
and the contracts. It says nothing about the content shape in `.wikitool-kb.json`, which is
|
||||
advanced by `wikitool migrate done` and described by [migrate-corpus.md](../migrate-corpus.md),
|
||||
and nothing about wiki content operations, which are logged in `kb/log.md` and carry no version
|
||||
at all.
|
||||
|
||||
Choosing the part remains a judgment call, deliberately: `docs verify` checks that a
|
||||
boundary-crossing entry *documents* its break and its migration, never that the part was chosen
|
||||
correctly. No validator can tell a renamed flag from a new one.
|
||||
|
||||
## Case study: 2.0.0
|
||||
|
||||
The Chemenu rebranding renamed the repo, the release artefact and the Python package. No page
|
||||
in `kb/` changed, so the first attempt was `1.9.0` - the migration question, answered correctly,
|
||||
substituted for the compatibility question, which was never asked. Three things broke: every
|
||||
existing instance's `update_url` pointed at a repo path that no longer existed and could not be
|
||||
hand-repaired; the artefact name changed; the import name changed. The correct bump was
|
||||
`--major --no-migration`, and the `CHANGES.md` entry for `2.0.0` carries the reasoning in full
|
||||
under "Warum das trotzdem MAJOR ist". The error was caught by the user, not by the
|
||||
documentation - which is what step 4 is for.
|
||||
@@ -7,9 +7,13 @@ manual: true
|
||||
|
||||
# German terminology for `kb/`
|
||||
|
||||
Reference vocabulary for [kb/CONTRACT.md](../kb/CONTRACT.md#language)'s rule that pages are
|
||||
written in German. The rule lives there; the word list lives here, because it is lookup material
|
||||
rather than a norm and would otherwise be loaded on every write.
|
||||
Reference vocabulary for [kb/CONVENTIONS.md](../kb/CONVENTIONS.md#language)'s rule that this
|
||||
instance's pages are written in German. The rule lives there; the word list lives here, because
|
||||
it is lookup material rather than a norm and would otherwise be loaded on every write.
|
||||
|
||||
**This file belongs to the `german` language profile, not to the stack.** An instance writing in
|
||||
another language deletes or replaces it - see
|
||||
[kb-profiles.md](kb-profiles.md).
|
||||
|
||||
Derived from translating all 248 pages on 2026-08-29. Every entry below is a decision that was
|
||||
made wrong at least once first - each cost a correction pass across published pages, which is why
|
||||
@@ -98,8 +102,8 @@ none of them structural, so no check found them. It is the one thing to watch fo
|
||||
instructional prose.
|
||||
|
||||
- **Quotations are never reworded**, neither translated nor moved into the impersonal register.
|
||||
- Buzzwords and AI filler are banned by [kb/CONTRACT.md](../kb/CONTRACT.md#tone); the German list
|
||||
is there.
|
||||
- Buzzwords and AI filler are banned by [kb/CONVENTIONS.md](../kb/CONVENTIONS.md#tone); the
|
||||
German list is there.
|
||||
- Dash as ` - `, not `—`.
|
||||
- German number formatting only in prose („10.000 Punkte"). Never inside code, version numbers or
|
||||
measurements (`75-85 px`, `10m`, `0.90`).
|
||||
@@ -108,4 +112,4 @@ instructional prose.
|
||||
|
||||
This is about prose in `kb/`. What is prose and what is an identifier - titles, headings, wikilink
|
||||
targets, cite-ids, enum values, tags, code - is decided by
|
||||
[kb/CONTRACT.md](../kb/CONTRACT.md#language), not here.
|
||||
[kb/CONTRACT.md](../kb/CONTRACT.md#language-and-identifiers), not here.
|
||||
|
||||
@@ -0,0 +1,191 @@
|
||||
---
|
||||
type: types/instruction.md
|
||||
name: kb-profiles
|
||||
description: Ready-made answers for kb/CONVENTIONS.md and each COLLECTION.md - the proven collection contracts and language profiles this stack has shipped, offered as a palette to adopt or adapt, never as a binding source.
|
||||
manual: true
|
||||
---
|
||||
# Pick a profile for a collection or for this instance's conventions
|
||||
|
||||
**This page is a palette, not an enum.** Each `kb/<name>/COLLECTION.md` stays authoritative for
|
||||
its own collection and `kb/CONVENTIONS.md` for the instance as a whole; an entry here is a
|
||||
proven starting point, nothing more. Adopting one means *copying its text into* that file - not
|
||||
pointing at this page and inheriting whatever it says later. Nothing in the stack reads this
|
||||
document, and `profile:` in a contract's frontmatter records where the text came from, not where
|
||||
it lives.
|
||||
|
||||
That direction is deliberate and it is the opposite of how this repo used to work. Language,
|
||||
tone, naming and the relationship vocabulary sat in `kb/CONTRACT.md`, a file `dist export` ships
|
||||
verbatim - so every instance that wanted something else edited a stack file, and an upstream
|
||||
merge handed the stack's answer back. What binds is now the instance's; what ships is this
|
||||
catalogue, and it binds nothing.
|
||||
|
||||
## When to run
|
||||
|
||||
- Setting up a new instance: the KB-language step of
|
||||
[setup-instance.md](setup-instance.md) sends you here to fill `kb/CONVENTIONS.md`.
|
||||
- Adding a collection to an existing instance, and wanting a contract that already works rather
|
||||
than a blank one.
|
||||
- Rewriting an existing `COLLECTION.md` or `kb/CONVENTIONS.md` and wanting to see what the
|
||||
alternatives were.
|
||||
|
||||
Not for changing what the *stack* enforces. That is [kb/CONTRACT.md](../kb/CONTRACT.md), and it
|
||||
is not a profile.
|
||||
|
||||
## Steps
|
||||
|
||||
1. **Decide what you are filling.** Two different files, and they are not interchangeable:
|
||||
|
||||
| File | Holds | Profiles below |
|
||||
|---|---|---|
|
||||
| `kb/CONVENTIONS.md` | Language, section headings, naming forms, tone, relationship labels, confidence rubric - once per instance | [Language profiles](#language-profiles) |
|
||||
| `kb/<name>/COLLECTION.md` | What one collection holds, its quality goal, its local linking and naming rules | [Collection profiles](#collection-profiles) |
|
||||
|
||||
2. **Copy the entry's text into the file**, then edit it until it is true of this instance.
|
||||
A profile you adopted and then changed is still that profile's `profile:` value - the field
|
||||
records the starting point, not a promise of fidelity.
|
||||
|
||||
3. **Record it.** `profile: <name>` in the file's frontmatter, or `profile: none` for a
|
||||
collection written from scratch. `wikitool docs verify` checks the field is there; it does
|
||||
not check the value against this page, because a collection an instance invented has no
|
||||
entry here to name.
|
||||
|
||||
4. **Set `required_by_stack:` on a collection - and set it correctly.** This one is *not* a
|
||||
choice: it says whether `wikitool` resolves against the collection by name, and
|
||||
`docs verify` checks it against the stack's own list. `sources` is `true`, everything else
|
||||
is `false`. See [kb/CONTRACT.md § Collections](../kb/CONTRACT.md#collections).
|
||||
|
||||
## Language profiles
|
||||
|
||||
A language profile answers all of `kb/CONVENTIONS.md` at once. There is one today, because one
|
||||
is what this repo has actually run.
|
||||
|
||||
### `german`
|
||||
|
||||
The profile this repo's own instance uses, and the reason this catalogue exists: it was the
|
||||
stack's hardcoded behaviour until the conventions file existed.
|
||||
|
||||
| Decides | Value |
|
||||
|---|---|
|
||||
| `language:` | `de` |
|
||||
| `sections:` | `Beziehungen` / `Siehe auch` / `Fußnoten` |
|
||||
| Naming | Human-readable titles with spaces; singular for entities; `adr-NNN-` for decisions; `X vs Y` for comparisons |
|
||||
| Tone | Wikipedia register, with a German buzzword and filler list |
|
||||
| Relationship labels | `hängt ab von` · `verwendet` · `implementiert` · `erweitert` · `ersetzt` · `steht in Konflikt mit` · `benötigt` · `erzeugt` · `konsumiert` · `besitzt` · `pflegt` · `läuft auf` · `verwandt mit` |
|
||||
| Confidence rubric | 0.5 base, +0.2 per supporting source (max +0.6), recency and source-quality bonuses; hedge with "möglicherweise"/"kann" below 0.6, "unsicher"/"unbestätigt" below 0.4 |
|
||||
| Terminology | [german-terminology.md](german-terminology.md) - which English terms stay English, and which have a settled German form |
|
||||
|
||||
**The full text to copy** is this repo's own [kb/CONVENTIONS.md](../kb/CONVENTIONS.md). An
|
||||
instance adopting it takes that file, not this table; the table is what the profile *decides*,
|
||||
so you can tell at a glance whether it is the one you want.
|
||||
|
||||
Adopting it also means keeping `german-terminology.md`. An instance on any other language
|
||||
deletes or replaces that file - it is the profile's lookup material, not the stack's.
|
||||
|
||||
### `english`
|
||||
|
||||
What `kb/CONVENTIONS.md.template` ships as its default, so "adopt `english`" means "fill in the
|
||||
template and change nothing structural". `sections:` are `Relationships` / `See Also` /
|
||||
`Footnotes`, which are also the names this stack wrote before it had a conventions file - so a
|
||||
corpus that predates the split needs no translation pass to adopt this profile.
|
||||
|
||||
There is no worked text for the rest of it. The template's placeholders are the questions;
|
||||
`german` above is what a filled answer looks like.
|
||||
|
||||
### Writing a third one
|
||||
|
||||
A language profile is not a translation of `german`. Two of its sections are judgment about a
|
||||
language rather than vocabulary in it - which foreign technical terms stay untranslated, and how
|
||||
to hedge a low-confidence claim - and those are exactly the two that read as awkward when
|
||||
translated mechanically. Write them, do not convert them.
|
||||
|
||||
The one part that is mechanical: `section_aliases:`. Whatever the corpus used before goes in
|
||||
that list, and the pages then migrate one at a time instead of all at once.
|
||||
|
||||
## Collection profiles
|
||||
|
||||
The four collections this repo runs. Each is a whole `COLLECTION.md`, and **the text to copy is
|
||||
the file itself** - `dist export` ships each one as `kb/<name>/COLLECTION.md.template`, which a
|
||||
new instance adopts by renaming. What follows is what each decides, so you can tell whether you
|
||||
want it.
|
||||
|
||||
### `entities`
|
||||
|
||||
Concrete, pointable things: projects, deployed systems, tools, technologies, people.
|
||||
|
||||
- **Quality goal:** pointability plus currency - what the thing is, where it actually is, and
|
||||
whether that is still true.
|
||||
- **Areas** driven by the `entity_type:` field: `projects/`, `systems/`, `tools/`,
|
||||
`technologies/`, `people/`. Areas, not collections - they inherit the contract and carry no
|
||||
`COLLECTION.md`.
|
||||
- **Per-area emphasis** spelled out, so a system page is not written like a technology page.
|
||||
- `required_by_stack: false`.
|
||||
|
||||
Take it when the wiki is about things that exist. Adapt the area list first: it is the part most
|
||||
likely to be wrong for another domain.
|
||||
|
||||
### `concepts`
|
||||
|
||||
Ideas rather than things: architectures, patterns, protocols, workflows, recurring problems,
|
||||
and the decisions taken about them.
|
||||
|
||||
- **Quality goal:** explanatory sufficiency - the page answers *why it is done this way* without
|
||||
the reader opening the entity pages that use it.
|
||||
- Carries the **ADR shape**: context, decision, consequences, status, and the rule that a
|
||||
superseded decision is never rewritten.
|
||||
- Routes head-to-head arguments out to `comparisons/` rather than hosting them.
|
||||
- `required_by_stack: false`.
|
||||
|
||||
Take it whenever `entities` is taken - the split between the two is what keeps either from
|
||||
becoming an essay.
|
||||
|
||||
### `sources`
|
||||
|
||||
One page per ingested source, carrying the `raw_files:` provenance every citation resolves
|
||||
against.
|
||||
|
||||
- **Quality goal:** faithful compression - what *this source* said, not what was concluded from
|
||||
it. A source page improved beyond its source is no longer evidence.
|
||||
- Titles carry the `Source - ` prefix, applied by `wikitool new source`.
|
||||
- `required_by_stack: **true**`. `sources coverage`, `[^cite-id]` resolution and
|
||||
`kb/provenance.md` resolve against the name `sources`.
|
||||
|
||||
Not optional in the way the others are. An instance may rewrite its authoring rules and may not
|
||||
rename or drop it.
|
||||
|
||||
### `comparisons`
|
||||
|
||||
Structured head-to-head evaluations of two or more things that already have pages.
|
||||
|
||||
- **Quality goal:** decidability - named, checkable dimensions and a stated trade-off, so a
|
||||
reader with a concrete situation can choose.
|
||||
- Every subject must already have a page; a comparison is a view over existing knowledge.
|
||||
- **Exempt from the orphan check** - comparisons are reached through the catalog, not through
|
||||
inbound prose links.
|
||||
- `required_by_stack: false`.
|
||||
|
||||
Skip it in a wiki that records rather than decides. It is the one of the four that is genuinely
|
||||
optional.
|
||||
|
||||
## Decision points
|
||||
|
||||
- **A profile is almost right?** Copy and edit. There is no partial adoption and no override
|
||||
file - the copy *is* the mechanism, and `profile:` still records where it started.
|
||||
- **Two collections want the same profile?** Fine. `profile:` is not unique, and two
|
||||
collections holding different subject matter under the same authoring rules is an ordinary
|
||||
outcome.
|
||||
- **Changing `sections:` after pages exist?** That is a corpus migration, not an edit. Put the
|
||||
old names in `section_aliases:` first, then translate page by page - the tool keeps finding
|
||||
the old headings for as long as the alias stands. See
|
||||
[migrate-corpus.md](migrate-corpus.md).
|
||||
- **Tempted to make this page binding** - to have `COLLECTION.md` say `profile: entities` and
|
||||
nothing else? Do not. That is the arrangement this split was written to end: the instance
|
||||
would be bound by a file the stack ships and upgrades, which is how an upstream merge changes
|
||||
an instance's authoring rules without anyone deciding to.
|
||||
|
||||
## Scope
|
||||
|
||||
Covers what an instance authors under `kb/`. It says nothing about what the stack enforces
|
||||
([kb/CONTRACT.md](../kb/CONTRACT.md)), what a page structurally is
|
||||
([types/type-spec.md](../types/type-spec.md)), or how a command behaves
|
||||
([tools/CONTRACT.md](../tools/CONTRACT.md)). None of those are profiles, and none of them are
|
||||
the instance's to change.
|
||||
@@ -0,0 +1,199 @@
|
||||
---
|
||||
type: types/instruction.md
|
||||
name: link-taxonomy
|
||||
description: The link-label catalogue - every relationship label a page may declare in related:, grouped by register, with the reader need each one names. A palette to authorise from in a COLLECTION.md, never binding on its own.
|
||||
manual: true
|
||||
---
|
||||
# Pick a link label
|
||||
|
||||
**This page is a palette, not an enum.** It lists every label this stack ships with and what
|
||||
each one asserts. What a page may actually *use* is decided by its own collection: each
|
||||
`kb/<name>/COLLECTION.md` authorises a subset per destination, and `wikitool lint` checks
|
||||
`related:` against that authorisation rather than against this file. A collection that
|
||||
authorises six labels has six, however long this list gets.
|
||||
|
||||
A label is an **identifier, not prose**. It is written into `related:` as a machine value and
|
||||
rendered verbatim into the page body, so it is never translated - not in a German wiki, not in
|
||||
any other. Which words a page is *written* in stays [kb/CONVENTIONS.md](../kb/CONVENTIONS.md)'s;
|
||||
this is not one of them.
|
||||
|
||||
## The invariant every label obeys
|
||||
|
||||
Every label completes, with the page carrying the link as the grammatical subject:
|
||||
|
||||
> `[source] <label> [target]`
|
||||
|
||||
The page containing the link asserts something **about** the target. `Hermes depends-on
|
||||
PostgreSQL` reads correctly on Hermes' page; the same fact written on PostgreSQL's page is a
|
||||
different label (`required-by`), not the same one pointing back. Omitted helper verbs ("is",
|
||||
"a") are fine where they do not reverse the endpoints.
|
||||
|
||||
This is Commonplace's ADR-058, adopted wholesale, and it is what makes a label checkable rather
|
||||
than a matter of taste: read the sentence out loud, and if it says the opposite of what you
|
||||
meant, the label is wrong.
|
||||
|
||||
## Direction is authored, never mirrored
|
||||
|
||||
Each direction is a separate decision. A link back from the target is welcome when it
|
||||
independently helps a reader *there* - and unnecessary when it does not. **Do not add a reverse
|
||||
edge merely to mirror the first one.** The inbound view is rendered from the graph by
|
||||
`index rebuild` and `search`, so a reader landing on the target sees what points at it whether
|
||||
or not anyone wrote a second edge.
|
||||
|
||||
That is why most labels below have no inverse. Only two pairs do, because in each the reverse
|
||||
direction is a genuine primary statement someone would write on its own: `depends-on` /
|
||||
`required-by` and `runs-on` / `hosts`.
|
||||
|
||||
## When to run
|
||||
|
||||
Adding or changing a `related:` entry, authorising labels in a `COLLECTION.md`, or judging
|
||||
whether a relationship is worth naming as a formal edge at all.
|
||||
|
||||
## Steps
|
||||
|
||||
1. **Decide whether this is an edge.** Not every mention is one. An edge is a reader aid: it
|
||||
says *follow this if you need X*. A subject mentioned once in passing is prose with a
|
||||
`[[wikilink]]`, not a declared relationship. Over-declaring is how a graph becomes a list of
|
||||
everything adjacent to everything.
|
||||
|
||||
2. **Say the sentence.** `[this page] <label> [that page]`. If it reads backwards, you want the
|
||||
other page to carry the edge, or a different label.
|
||||
|
||||
3. **Pick from the register that fits the pair**, below. Prefer the most specific label that is
|
||||
true; fall back outward only when nothing fits.
|
||||
|
||||
4. **Check the collection authorises it** for that destination -
|
||||
`kb/<name>/COLLECTION.md`'s `outbound:` block. If the label you want is not authorised and
|
||||
should be, that is a collection-contract change, made deliberately, not a lint error to
|
||||
route around.
|
||||
|
||||
5. **Write it with the tool**, never by hand:
|
||||
|
||||
```bash
|
||||
tools/wikitool xref add --a "<This Page>" --b "<That Page>" --rel <label>
|
||||
```
|
||||
|
||||
## The catalogue
|
||||
|
||||
### Operational
|
||||
|
||||
Concrete things and how they stand to one another - the register this instance runs on. Mostly
|
||||
entity to entity.
|
||||
|
||||
| label | inverse | asserts |
|
||||
|---|---|---|
|
||||
| `depends-on` | `required-by` | cannot function without the target |
|
||||
| `required-by` | `depends-on` | the target cannot function without this |
|
||||
| `runs-on` | `hosts` | executes on the target as its substrate |
|
||||
| `hosts` | `runs-on` | provides the substrate the target executes on |
|
||||
| `uses` | — | employs the target at runtime, but survives without it |
|
||||
| `produces` | — | emits the target as an artifact or data |
|
||||
| `consumes` | — | reads the target as an artifact or data |
|
||||
| `maintains` | — | carries the upkeep of the target |
|
||||
| `owns` | — | is accountable for the target's existence and decisions |
|
||||
|
||||
`uses` versus `depends-on` is the distinction worth keeping sharp: if removing the target breaks
|
||||
this thing, it is `depends-on`. `owns` versus `maintains`: accountability versus labour, and
|
||||
they are often different people.
|
||||
|
||||
### Realization
|
||||
|
||||
How an idea becomes a running thing. Usually concept to entity or the reverse.
|
||||
|
||||
| label | asserts |
|
||||
|---|---|
|
||||
| `implements` | is a concrete realization of the target |
|
||||
| `operationalized-from` | is the prescriptive form of the target's theory |
|
||||
| `mechanism` | is the mechanism by which the target works |
|
||||
| `procedure` | is the procedure for carrying out the target |
|
||||
| `applies-when` | applies under the condition the target describes |
|
||||
| `operates-on` | acts upon the target as its subject matter |
|
||||
| `invokes` | calls the target as a step within itself |
|
||||
|
||||
### Conceptual
|
||||
|
||||
Inference and comparison between ideas.
|
||||
|
||||
| label | asserts |
|
||||
|---|---|
|
||||
| `extends` | develops the target's argument further |
|
||||
| `grounds` | provides the basis the target rests on |
|
||||
| `rests-on` | takes the target as its premise |
|
||||
| `enables` | is the operational prerequisite that makes the target possible |
|
||||
| `precondition` | must hold before the target applies |
|
||||
| `exemplifies` | is an instance of the general claim the target makes |
|
||||
| `abstracted-from` | generalizes from the target |
|
||||
| `contrasts` | differs from the target in a way worth reading both for |
|
||||
| `compares-with` | is weighed against the target on shared dimensions |
|
||||
| `contradicts` | asserts something the target denies |
|
||||
| `composition` | is composed of the target |
|
||||
| `part-of` | is a component of the target |
|
||||
|
||||
`grounds` / `rests-on` is a genuine pair and both directions are primary statements; they are
|
||||
listed separately rather than as inverses because either page may legitimately carry only its
|
||||
own side.
|
||||
|
||||
### Lineage
|
||||
|
||||
Where something came from, and what replaced it.
|
||||
|
||||
| label | asserts |
|
||||
|---|---|
|
||||
| `supersedes` | replaces the target, which is now historical |
|
||||
| `derived-from` | was produced from the target |
|
||||
| `adapted-from` | was reworked from the target for a different purpose |
|
||||
| `defined-in` | takes its definition from the target |
|
||||
|
||||
A superseded page is never deleted or rewritten - see the collection contract for
|
||||
`kb/concepts/`.
|
||||
|
||||
### Evidence
|
||||
|
||||
The provenance register. Distinct from `sources:` and `[^cite-id]`, which are the *mechanical*
|
||||
provenance path: these two are authored claims about how strongly something is backed.
|
||||
|
||||
| label | asserts |
|
||||
|---|---|
|
||||
| `evidenced-by` | is supported by the target as evidence |
|
||||
| `is-evidence-for` | serves as evidence for the target's claim |
|
||||
|
||||
### Universal
|
||||
|
||||
| label | asserts |
|
||||
|---|---|
|
||||
| `see-also` | nothing more specific applies, and a reader here would still want the target |
|
||||
|
||||
**`see-also` is the last resort and should stay rare.** A collection where it is the commonest
|
||||
label has a vocabulary problem, not a lot of loosely related pages. The previous vocabulary's
|
||||
`verwandt mit` was exactly that, and it is the reason this catalogue exists.
|
||||
|
||||
## Extending it
|
||||
|
||||
Adding a label is a line of data, never a code change:
|
||||
|
||||
1. Add a row here, in the register it belongs to, with the sentence it completes.
|
||||
2. Authorise it in the `COLLECTION.md` of every collection that may use it.
|
||||
|
||||
The registers are advisory groupings for readers, not a schema - nothing checks that a label is
|
||||
used only within its register. Invent an intra-collection label the work needs and propose it
|
||||
here afterwards; the architecture is deliberately loose, because the link theory is still
|
||||
developing.
|
||||
|
||||
## Decision points
|
||||
|
||||
- **Two labels both fit?** Take the more specific one. If they are equally specific and mean
|
||||
different things, the relationship is probably two edges.
|
||||
- **The relationship reads better from the other page?** Write it there. Nothing is lost - the
|
||||
inbound view renders it here.
|
||||
- **You want a reverse edge for navigation?** You do not need one. That is what the rendered
|
||||
inbound view is for, and it is complete in a way an authored mirror never was.
|
||||
- **Nothing fits at all?** Use `see-also` and say so in the commit, or propose a label. Do not
|
||||
stretch a label whose sentence reads false - a wrong edge is worse than a weak one, because
|
||||
it is machine-readable and will be believed.
|
||||
|
||||
## Scope
|
||||
|
||||
Covers labels on `related:` edges between pages. Says nothing about `sources:` (the provenance
|
||||
field, unlabelled by construction), `[^cite-id]` footnotes
|
||||
([kb/CONTRACT.md](../kb/CONTRACT.md#provenance-and-citation)), or `tags:` (search keys, not
|
||||
relationships).
|
||||
@@ -0,0 +1,150 @@
|
||||
---
|
||||
type: types/instruction.md
|
||||
name: 3.0.0-authoring-conventions
|
||||
description: 'Adopt the instance-owned authoring conventions introduced in 3.0.0 - write kb/CONVENTIONS.md, declare profile:/required_by_stack: on every COLLECTION.md, and replace kb/CONTRACT.md with the shipped one.'
|
||||
manual: true
|
||||
migrates_to: 3.0.0
|
||||
migration_kind: mechanical
|
||||
---
|
||||
# Adopt this instance's own authoring conventions (3.0.0)
|
||||
|
||||
Until 3.0.0, the rules for writing a page were split by *location*: everything about `kb/` sat
|
||||
in `kb/CONTRACT.md`, a file every distribution ships verbatim. Half of it was never the stack's
|
||||
to decide - the language pages are written in, the three tool-owned section headings, the naming
|
||||
forms, the tone, the relationship labels, the confidence rubric - so an instance that wanted
|
||||
something else edited a file the stack also ships, and an upstream merge handed the stack's
|
||||
answer back.
|
||||
|
||||
3.0.0 splits it by *ownership* instead. `kb/CONTRACT.md` keeps only what `wikitool` enforces;
|
||||
everything else moves into a new `kb/CONVENTIONS.md` that belongs to this instance, and each
|
||||
`kb/<name>/COLLECTION.md` now declares what it is. The compiler reads its section headings from
|
||||
that file rather than from `tools/chemenu/sections.py`.
|
||||
|
||||
**No page changes.** Not one line under `kb/entities/`, `kb/concepts/`, `kb/sources/` or
|
||||
`kb/comparisons/` is touched. What changes are the contracts beside them, which is why this is
|
||||
`mechanical` and takes minutes rather than a workshop.
|
||||
|
||||
## When to run
|
||||
|
||||
After installing 3.0.0 machinery over an instance that was on 2.x, when `tools/wikitool doctor`
|
||||
reports `FAIL conventions` or `tools/wikitool docs verify` reports a `COLLECTION.md` with no
|
||||
frontmatter. `tools/wikitool migrate status` names this document.
|
||||
|
||||
**Until it has run, the compiler answers out of a fallback.** `xref add` and `cite add` write
|
||||
`## Beziehungen` / `## Siehe auch` / `## Fußnoten` - what this stack hardcoded before the
|
||||
conventions file existed. That is correct for a corpus written under them and wrong for any
|
||||
other, so run this before the next `wiki-ingest` or `wiki-manage`, not afterwards.
|
||||
|
||||
## Steps
|
||||
|
||||
1. **Replace `kb/CONTRACT.md` from the release.** It is machinery that happens to live under a
|
||||
content directory, and the tarball update path used to skip it (see `INSTALL.md`, which now
|
||||
names it explicitly). The 3.0.0 version is roughly half the length of the 2.x one - the
|
||||
removed half is what step 2 is about to write into a file of yours.
|
||||
|
||||
```bash
|
||||
cp <unpacked-release>/kb/CONTRACT.md kb/CONTRACT.md
|
||||
```
|
||||
|
||||
A private instance cloned from an upstream takes it with the merge instead - see
|
||||
[private-instance.md](../private-instance.md), whose update procedure now re-takes the
|
||||
upstream side for exactly this path.
|
||||
|
||||
2. **Write `kb/CONVENTIONS.md`.** Two ways in, and the first is almost always right:
|
||||
|
||||
- **This instance writes German pages** (it did, unless you changed it): copy the release's
|
||||
`kb/CONVENTIONS.md.template` and fill it from the `german` profile in
|
||||
[kb-profiles.md](../kb-profiles.md) - whose worked full text is the origin repo's own
|
||||
`kb/CONVENTIONS.md`. Everything in it was already true of your corpus; it was simply
|
||||
written down somewhere you did not own.
|
||||
- **You had changed the language**, and therefore hold local edits to `kb/CONTRACT.md`,
|
||||
`types/*.md` and `tools/chemenu/sections.py`: those edits are what this file replaces. Copy
|
||||
the canonical heading names out of your old `sections.py` into `sections:`, the labels and
|
||||
tone rules out of your old `kb/CONTRACT.md`, then **discard the local edits under `tools/`
|
||||
and `types/`** and take the shipped versions. That is the whole point of the change: there
|
||||
is nothing left to patch there.
|
||||
|
||||
The minimum the tool needs is the frontmatter:
|
||||
|
||||
```yaml
|
||||
---
|
||||
language: de
|
||||
profile: german
|
||||
sections:
|
||||
relationships: Beziehungen
|
||||
see_also: Siehe auch
|
||||
footnotes: Fußnoten
|
||||
---
|
||||
```
|
||||
|
||||
Set `sections:` to the names **your existing pages already carry**, not to what you would
|
||||
prefer. Changing them is a separate, real corpus migration; `section_aliases:` is how it is
|
||||
done page by page ([migrate-corpus.md](../migrate-corpus.md)).
|
||||
|
||||
Drop the `wikitool:template-unfilled` sentinel line while filling it in - `doctor` FAILs on a
|
||||
renamed-but-unanswered template exactly as it does for `USER.md`.
|
||||
|
||||
3. **Declare each collection.** Two frontmatter lines at the top of every
|
||||
`kb/<name>/COLLECTION.md`:
|
||||
|
||||
```yaml
|
||||
---
|
||||
profile: <the entry in instructions/kb-profiles.md this contract came from, or none>
|
||||
required_by_stack: false
|
||||
---
|
||||
```
|
||||
|
||||
`required_by_stack: true` on `kb/sources/` and **nowhere else**. It is not a preference:
|
||||
`sources coverage`, `[^cite-id]` resolution and `kb/provenance.md` resolve against that name,
|
||||
and `docs verify` checks the field against the stack's own list in both directions.
|
||||
|
||||
For the four default collections, the shipped `kb/<name>/COLLECTION.md.template` files carry
|
||||
the right values already.
|
||||
|
||||
4. **Verify.** All three must pass:
|
||||
|
||||
```bash
|
||||
tools/wikitool doctor # `conventions` must be OK
|
||||
tools/wikitool docs verify
|
||||
tools/wikitool lint
|
||||
```
|
||||
|
||||
`migrate verify` is deliberately not in that list: it compares pages, and no page changed.
|
||||
Running it would report nothing and prove nothing.
|
||||
|
||||
5. **Record it.**
|
||||
|
||||
```bash
|
||||
tools/wikitool migrate done 3.0.0 --pages 0
|
||||
```
|
||||
|
||||
`--pages 0` is honest, not a placeholder - see the note under step 1.
|
||||
|
||||
## How to tell a migrated instance from an unmigrated one
|
||||
|
||||
`kb/CONVENTIONS.md` exists, carries no `wikitool:template-unfilled` line, and names all three
|
||||
slots under `sections:`; every `kb/*/COLLECTION.md` opens with a frontmatter block; and
|
||||
`kb/CONTRACT.md` has a `## Language and identifiers` heading rather than a `## Language` one.
|
||||
`doctor` answers all of that in one call.
|
||||
|
||||
## Decision points
|
||||
|
||||
- **`doctor` says `conventions: FAIL` after step 2?** It prints which slot is missing. The three
|
||||
keys are `relationships`, `see_also` and `footnotes` - the *slot* names are fixed, only their
|
||||
values are yours.
|
||||
- **A collection this instance invented, with no profile behind it?** `profile: none`. The field
|
||||
records where the text came from; it is free text and `docs verify` does not check it against
|
||||
the catalogue, because an invented collection has no entry there to name.
|
||||
- **Tempted to point `profile:` at the catalogue instead of copying the text?** Do not. An
|
||||
adopted profile is a copy; a reference would put your binding authoring rules in a file the
|
||||
stack ships and upgrades, which is the arrangement 3.0.0 exists to end.
|
||||
- **Your old `kb/CONTRACT.md` had local edits you still want?** They belong in
|
||||
`kb/CONVENTIONS.md` now. If something you edited has no home there, it was a stack rule you
|
||||
overrode - file it as an issue against the origin repo rather than re-applying it.
|
||||
|
||||
## Scope
|
||||
|
||||
One instance's contracts, once. It changes no page, no frontmatter on a page, and nothing under
|
||||
`raw/`. The machinery half of the 3.0.0 upgrade - copying `tools/`, `types/`, `instructions/`,
|
||||
`AGENTS.md`, `VERSION` and `.wikitool-release.json` - is `INSTALL.md`'s, and has to have
|
||||
happened before step 1.
|
||||
@@ -0,0 +1,146 @@
|
||||
---
|
||||
type: types/instruction.md
|
||||
name: 4.0.0-link-taxonomy
|
||||
description: Move every relationship from free-text prose in a body bullet to a labelled edge in related:, and every tool-owned body region from heading-matching to a marker pair.
|
||||
manual: true
|
||||
migrates_to: 4.0.0
|
||||
migration_kind: assisted
|
||||
obligation: required
|
||||
---
|
||||
# Move relationships into the data, and generated regions behind markers (4.0.0)
|
||||
|
||||
Until 4.0.0 the stack used **prose as an identifier** in three places, and each one cost
|
||||
something measurable:
|
||||
|
||||
| Was the identifier | Cost |
|
||||
|---|---|
|
||||
| A section's heading text (`## Beziehungen`) | The KB language was a compiler constant, and the region's *end* was a guess. Content sitting after it was silently deleted on eight pages |
|
||||
| A relationship label in a body bullet (`- **hängt ab von:**`) | Nothing could check the vocabulary, so it drifted to **152 distinct labels** across 337 bullets against thirteen that were documented |
|
||||
| The reciprocal half of every edge | `xref add` mirrored every link, which made per-collection label authorisation impossible and filled `## Siehe auch` with 555 unlabelled bullets, 353 of them provably redundant |
|
||||
|
||||
4.0.0 replaces all three. A region is delimited by a marker pair and rendered from frontmatter;
|
||||
a label is a machine value in `related:`, drawn from a catalogue and authorised per destination
|
||||
by the source collection; an edge is authored in one direction and the inbound view is computed.
|
||||
|
||||
**This one touches pages.** Unlike 3.0.0 it is not a contract reshuffle: every `related:` entry
|
||||
and every tool-owned body region changes. It is `assisted` because there is no mapping table -
|
||||
mapping free-text German onto a 35-label catalogue is a judgment call per edge, and a large
|
||||
minority of the old labels are reverse directions that under the new model are not stored at all.
|
||||
|
||||
## When to run
|
||||
|
||||
After installing 4.0.0 over an instance on 3.x. `tools/wikitool migrate status` names it, and
|
||||
`lint` reports `unlabelled_edges` for every unconverted edge - that count reaching zero is how
|
||||
you know the run is finished.
|
||||
|
||||
**Nothing breaks while it is outstanding.** Unlabelled edges and undelimited regions are read,
|
||||
not rejected: `links.py` treats a bare title as an edge whose label is not declared yet, and
|
||||
`provenance.split_cite_block` falls back to the pre-marker layout. That is deliberate - a corpus
|
||||
has to stay readable while it is being converted - and it is why the two lint findings are
|
||||
advisory until step 6 promotes them.
|
||||
|
||||
## Steps
|
||||
|
||||
1. **Rewrite `kb/CONVENTIONS.md`'s `sections:` block.** Three slots become two, because the
|
||||
See Also region is gone:
|
||||
|
||||
```yaml
|
||||
sections:
|
||||
links: <your heading for declared relationships>
|
||||
footnotes: <your heading for citation definitions>
|
||||
```
|
||||
|
||||
Delete `section_aliases:` if you have one - nothing matches on heading text any more, so
|
||||
there is nothing to alias. The heading is now a *rendering* value: changing it re-renders
|
||||
the words above each region on the next write and can no longer split a page.
|
||||
|
||||
2. **Add an `outbound:` block to every `kb/<name>/COLLECTION.md`.** Which labels a page may use,
|
||||
per destination collection, with `any` as a wildcard:
|
||||
|
||||
```yaml
|
||||
outbound:
|
||||
entities: [depends-on, runs-on, uses, see-also]
|
||||
concepts: [implements, see-also]
|
||||
```
|
||||
|
||||
The catalogue to draw from is [link-taxonomy.md](../link-taxonomy.md); the four contracts in
|
||||
the origin repo are worked examples. **The source collection decides** - that is what makes a
|
||||
35-label palette usable, and it is why the reverse edge can no longer be written
|
||||
automatically. A destination you do not list authorises nothing, which is a real answer.
|
||||
|
||||
3. **Fix your page type-spec templates.** If you adopted the 3.0.0 templates, they contain
|
||||
`## {section.relationships}` and `## {section.see_also}`. Those variables no longer exist and
|
||||
would be written into new pages literally. **Delete both sections from the `## Template`
|
||||
block** - a template must not scaffold a tool-owned region at all: it is generated between
|
||||
markers on the first `xref add` / `cite add` and re-rendered on every write.
|
||||
|
||||
4. **Convert the corpus**, following [migrate-corpus.md](../migrate-corpus.md). Cut it into
|
||||
units sized against the iteration budget; the origin repo used four, ~45 pages each. Per page:
|
||||
|
||||
- For each labelled bullet under the old relationships heading: say the sentence
|
||||
`[this page] <label> [target]` and pick the catalogue label that makes it true. If it only
|
||||
reads true **backwards**, the edge belongs on the other page - move it there rather than
|
||||
inventing an inverse label the catalogue does not have.
|
||||
- For each bare `- [[X]]` bullet under the old See Also heading: drop it if a labelled edge
|
||||
already connects the pair. Otherwise decide - a real label, or dropped with the reason
|
||||
recorded. **Do not convert them to `see-also` in bulk.** That is the one shortcut this
|
||||
migration explicitly refuses: it would start the new taxonomy with most of its edges on its
|
||||
weakest label, which is the sediment the change exists to remove.
|
||||
- Write edges with `tools/wikitool xref add --a "<A>" --b "<B>" --rel <label>`, never by
|
||||
hand. The body region is rendered from `related:`; editing inside a marker pair is
|
||||
overwritten without warning.
|
||||
- `cite sync` converts a page's old footnote block into a marked region in passing.
|
||||
|
||||
5. **Check each unit mechanically before anything else:**
|
||||
|
||||
```bash
|
||||
tools/wikitool migrate verify --from <pre-migration rev> --path kb/<area> --fail-on-error
|
||||
```
|
||||
|
||||
It compares wikilink and citation **counts**, footnote definitions, H1, structural
|
||||
frontmatter, and - new in 4.0.0 - the **count of marker pairs per region**. A dropped marker
|
||||
is otherwise silent: the region becomes ordinary prose and the next write appends a second
|
||||
one beside it.
|
||||
|
||||
6. **Record it, then tighten the checks:**
|
||||
|
||||
```bash
|
||||
tools/wikitool lint # unlabelled_edges and unauthorised_labels must be 0
|
||||
tools/wikitool migrate done 4.0.0 --pages <N>
|
||||
```
|
||||
|
||||
Only once `lint` reports zero of both is the run finished. The two findings are advisory
|
||||
during the window and become hard errors afterwards - the same path
|
||||
`legacy_citation_markers` took after the citation migration.
|
||||
|
||||
## How to tell a migrated page from an unmigrated one
|
||||
|
||||
Its `related:` entries are `- <label>: <title>` rather than bare titles, and its relationship
|
||||
and footnote sections sit between `<!-- wikitool:links -->` / `<!-- wikitool:footnotes -->`
|
||||
marker pairs. `tools/wikitool links show --page "<Title>"` prints `unlabelled` for every edge
|
||||
still waiting, and `lint`'s `unlabelled_edges` count is the corpus-wide version of the same
|
||||
question.
|
||||
|
||||
## Decision points
|
||||
|
||||
- **A label you want is not in the catalogue?** Add it - a row in `link-taxonomy.md` and an
|
||||
entry in the authorising `COLLECTION.md`. No code change is involved, and the registers are
|
||||
advisory groupings rather than a schema. Do not stretch a label whose sentence reads false: a
|
||||
wrong edge is worse than a weak one, because it is machine-readable and will be believed.
|
||||
- **`related:` holds an entry with no body bullet to derive a label from?** Expected - the
|
||||
origin repo found 480 edges against 337 bullets, because frontmatter and body had already
|
||||
drifted apart while the label lived only in prose. Read the page and decide; that drift is
|
||||
itself part of what this migration repairs.
|
||||
- **A page loses its last inbound edge?** The orphan check will now report it, and that is the
|
||||
check working: directional edges mean a page nothing points at is genuinely unreachable, where
|
||||
the old mirrored model always manufactured a back-link. Either something should point at it,
|
||||
or it is reached through the catalog and that is fine.
|
||||
- **Tempted to keep writing reverse edges for navigation?** Do not. `links show` computes the
|
||||
inbound view, and the rendered bullet on the asserting page is an ordinary `[[wikilink]]`, so
|
||||
a backlink panel in an editor already shows it.
|
||||
|
||||
## Scope
|
||||
|
||||
The corpus under `kb/`, plus the three instance-owned declarations in steps 1-3. It does not
|
||||
touch `raw/`, and it learns nothing new: the same knowledge is restated in a form that can be
|
||||
checked. Installing the 4.0.0 machinery itself is `INSTALL.md`'s and must have happened first.
|
||||
@@ -100,17 +100,36 @@ So the merge has to be scoped. That is the procedure below, and it is not option
|
||||
[setup-instance.md](setup-instance.md), then [bootstrap.md](bootstrap.md) for the venv and
|
||||
the skills.
|
||||
|
||||
A clone inherits the upstream's `kb/CONVENTIONS.md` and `kb/*/COLLECTION.md` rather than
|
||||
templates, because it inherits the upstream's whole tree. They are yours from this point on:
|
||||
rewrite them if this instance writes its pages differently - the update procedure below
|
||||
restores them on every merge, so the change sticks. [kb-profiles.md](kb-profiles.md) has the
|
||||
alternatives.
|
||||
|
||||
## Taking a stack update
|
||||
|
||||
Take the machinery, never the content. The merge is held open, the content stages are forced
|
||||
back to your own state, and only then does it close:
|
||||
back to your own state, and only then does it close.
|
||||
|
||||
**Three files under those stages are machinery, not content**, and forcing them back is how an
|
||||
upstream contract change gets silently discarded:
|
||||
|
||||
| Path | Why it must take the upstream side |
|
||||
|---|---|
|
||||
| `kb/CONTRACT.md` | The stack's own knowledge-layer contract. Every rule in it is enforced by `wikitool`; an instance never edits it |
|
||||
| `kb/CONVENTIONS.md.template` | The template your `kb/CONVENTIONS.md` was filled from. The filled file is yours; the template is the stack's |
|
||||
| `raw/CONTRACT.md` | The raw stage's contract, for the same reason as the first row |
|
||||
|
||||
Everything else under `kb/` and `raw/` is yours, `kb/CONVENTIONS.md` and each
|
||||
`kb/<name>/COLLECTION.md` included - they bind your corpus, and they are exactly what the
|
||||
restore below is protecting.
|
||||
|
||||
```bash
|
||||
BEFORE=$(git rev-parse HEAD)
|
||||
git fetch upstream
|
||||
|
||||
# --no-commit holds the merge open; it may report conflicts under kb/ or raw/,
|
||||
# which the next three lines are about to make irrelevant.
|
||||
# which the next four lines are about to make irrelevant.
|
||||
git merge --no-commit --no-ff upstream/main || true
|
||||
|
||||
# Whatever the merge did to the content stages, undo it. HEAD is still your
|
||||
@@ -119,18 +138,32 @@ git rm -rq --cached --ignore-unmatch kb raw
|
||||
rm -rf kb raw
|
||||
git checkout HEAD -- kb raw
|
||||
|
||||
# ...then take the upstream side back for the machinery that lives among it.
|
||||
# MERGE_HEAD is still resolvable while the merge is open.
|
||||
git checkout MERGE_HEAD -- kb/CONTRACT.md kb/CONVENTIONS.md.template raw/CONTRACT.md
|
||||
|
||||
git commit --no-edit
|
||||
```
|
||||
|
||||
Then **check that it worked**, rather than trusting that it did:
|
||||
Then **check that it worked**, rather than trusting that it did. The same three paths are
|
||||
excluded here, spelled out rather than held in a variable so that the check can be read on its
|
||||
own and copied on its own:
|
||||
|
||||
```bash
|
||||
git diff --name-only $BEFORE HEAD -- kb raw # must print nothing
|
||||
git diff --name-only "$BEFORE" HEAD -- kb raw \
|
||||
| grep -vE '^(kb/CONTRACT\.md|kb/CONVENTIONS\.md\.template|raw/CONTRACT\.md)$'
|
||||
```
|
||||
|
||||
Must print nothing.
|
||||
|
||||
An empty result is the proof that the update touched machinery only. A non-empty one means a
|
||||
path slipped through - inspect it before going further.
|
||||
|
||||
**The exclusion is not cosmetic.** Without it the check reports *empty* for an update that just
|
||||
ate a `kb/CONTRACT.md` change - it would be confirming the failure it exists to catch. If one of
|
||||
the three paths does not appear in the diff at all, that is fine: it means upstream did not
|
||||
touch it.
|
||||
|
||||
Then, as after any stack change: `doctor`, `docs verify`, `instructions verify`, `migrate status`,
|
||||
`lint`. A `migrate status` with outstanding links means the update crossed a compatibility
|
||||
boundary - follow [migrate-corpus.md](migrate-corpus.md) before doing anything else.
|
||||
@@ -157,11 +190,20 @@ merge above. Nothing is lost by the detour: the fix has to pass that CI either w
|
||||
above overwrites those stages with your own afterwards, so the conflict resolves itself.
|
||||
Never resolve one by hand with `git add -A` - that is exactly how the upstream version, which
|
||||
git left sitting in your working tree, gets committed into your instance.
|
||||
- **`git diff` after the merge shows something under `kb/` or `raw/`?** Stop. The scoping step
|
||||
did not take. Do not publish; find out which path came through and where from.
|
||||
- **`git diff` after the merge shows something under `kb/` or `raw/`?** Stop - unless it is one
|
||||
of the three machinery paths the check excludes, which is the update working as intended. For
|
||||
anything else the scoping step did not take: do not publish; find out which path came through
|
||||
and where from.
|
||||
- **Conflict in `tools/`, `types/` or `instructions/`?** You changed the stack locally, which
|
||||
step "Where stack development happens" says not to do. Take the upstream side and re-file the
|
||||
change as an issue there.
|
||||
- **...but you changed how *your pages* are written?** That is not a stack change and the rule
|
||||
above does not apply to it. Language, section headings, naming forms, tone, relationship
|
||||
labels and the confidence rubric live in `kb/CONVENTIONS.md`, and each collection's authoring
|
||||
rules in `kb/<name>/COLLECTION.md` - all under `kb/`, all yours, all restored by the merge
|
||||
procedure rather than overwritten by it. If you find yourself editing `tools/` or `types/` to
|
||||
change an authoring convention, that is a stack bug: file it, because the split exists
|
||||
precisely so you do not have to.
|
||||
|
||||
## Scope
|
||||
|
||||
|
||||
@@ -60,24 +60,71 @@ bereit für den ersten `Ingest`.
|
||||
- Nicht genannt: lokal bleiben - dann braucht **jeder** spätere `tools/wikitool publish`
|
||||
ein `--no-push` (dessen Branch-Prüfung dabei ohnehin entfällt, siehe Schritt 2).
|
||||
|
||||
5. **Entscheidungspunkt - KB-Sprache.** Frage den Nutzer, in welcher Sprache die Seiten unter
|
||||
`kb/` geschrieben werden sollen. Diese Instanz erbt aus dem Quell-Repo **Deutsch** - sowohl die
|
||||
Regel in [kb/CONTRACT.md](../kb/CONTRACT.md#language) als auch das Vokabular in
|
||||
[german-terminology.md](german-terminology.md) und die deutschen Abschnittsnamen in
|
||||
`tools/chemenu/sections.py`. Das ist eine Entscheidung der Ursprungsinstanz, keine
|
||||
Eigenschaft des Musters, und sie wird hier nicht stillschweigend weitergereicht.
|
||||
5. **Entscheidungspunkt - Autorenkonventionen.** Die Distribution bringt keine ausgefüllten
|
||||
Konventionen mit, sondern `kb/CONVENTIONS.md.template` und je Collection ein
|
||||
`kb/<name>/COLLECTION.md.template`. Beide **binden**, sobald sie übernommen sind, und beide
|
||||
gehören dieser Instanz - deshalb liefert der Stack nur die Vorlage. Die eine Entscheidung
|
||||
dahinter ist: **in welcher Sprache und in welchem Ton schreibt diese Instanz ihre Seiten?**
|
||||
|
||||
- **Deutsch bestätigt:** nichts zu tun.
|
||||
- **Andere Sprache:** *vor dem ersten Ingest* umstellen, denn danach ist es eine Migration
|
||||
jeder vorhandenen Seite. Zu ändern sind der Abschnitt "Language" in `kb/CONTRACT.md`, die
|
||||
Tonfall-Beispiele und Hedge-Wörter darunter, die vier Page-Type-Templates in `types/`, die
|
||||
kanonischen Namen in `sections.py` (die bisherigen als Alias behalten) und die
|
||||
Beziehungslabels in `kb/CONTRACT.md` § Linking. `german-terminology.md` wird dann ersetzt
|
||||
oder gelöscht.
|
||||
Ablauf:
|
||||
|
||||
Unverändert bleibt in jedem Fall die eigentliche Regel: **jede Zeile einer Seite ist Prosa
|
||||
oder Identifier, und nur Prosa wird übersetzt.** Titel, Wikilink-Ziele, Cite-IDs, Enum-Werte,
|
||||
Tags, Befehle und Pfade folgen keiner KB-Sprache.
|
||||
1. Die Collection-Contracts **und die Page-Type-Specs** übernehmen - Kopien, keine Frage an
|
||||
den Nutzer, denn was dort steht ist als Ausgangspunkt unabhängig von der Sprache brauchbar:
|
||||
|
||||
```bash
|
||||
for template in kb/*/COLLECTION.md.template types/*.template; do
|
||||
cp "$template" "${template%.template}"
|
||||
done
|
||||
```
|
||||
|
||||
Die `.template`-Dateien bleiben liegen; sie sind die Vorlage für den nächsten Export.
|
||||
|
||||
Unter `types/` betrifft das genau die Type-Specs mit `root: kb` - `entity`, `concept`,
|
||||
`source`, `comparison` - samt ihrer `.schema.yaml`. Sie beschreiben Seiten, die *diese*
|
||||
Instanz schreibt, also gehören sie ihr: Prosa, Template und Sprache dürfen umgeschrieben
|
||||
werden. `instruction`, `lint-report` und `type-spec` beschreiben Stack-Artefakte und
|
||||
kommen unverändert.
|
||||
|
||||
2. Den Nutzer nach der KB-Sprache fragen. `kb/CONVENTIONS.md.template` ist auf **Englisch**
|
||||
voreingestellt; [kb-profiles.md](kb-profiles.md) hält daneben ein vollständiges
|
||||
deutsches Profil bereit, und dessen Volltext ist die `kb/CONVENTIONS.md` des Quell-Repos.
|
||||
Der Profilkatalog ist eine **Palette, kein Enum**: übernommen wird der Text *in* die
|
||||
Instanzdatei, nicht ein Verweis auf den Katalog.
|
||||
|
||||
3. `kb/CONVENTIONS.md.template` nach `kb/CONVENTIONS.md` kopieren, entlang des gewählten
|
||||
Profils ausfüllen - Sprache, Abschnittsnamen, Namensformen, Ton, Beziehungslabels,
|
||||
Confidence-Rubrik - und dabei die Sentinel-Zeile (`wikitool:template-unfilled`) entfernen.
|
||||
Die Platzhalter in geschweiften Klammern **sind** der Fragenkatalog.
|
||||
|
||||
4. Bei einer anderen Sprache als der des Quell-Repos: `german-terminology.md` löschen oder
|
||||
durch das eigene Vokabular ersetzen - sie ist Material des deutschen Profils, nicht des
|
||||
Stacks.
|
||||
|
||||
**Vor dem ersten Ingest entscheiden.** Die `sections:`-Namen in `kb/CONVENTIONS.md` sind die
|
||||
Überschriften, die `xref` und `cite` in jede Seite schreiben; sie danach zu ändern ist eine
|
||||
Migration jeder vorhandenen Seite (`section_aliases:` trägt die alten Namen, siehe
|
||||
[migrate-corpus.md](migrate-corpus.md)).
|
||||
|
||||
**Nichts davon liegt in einer Stack-Datei.** Der Compiler liest die Abschnittsnamen aus
|
||||
`kb/CONVENTIONS.md`; die vier Page-Type-Specs gehören ab Schritt 1 dieser Instanz. Eine
|
||||
anderssprachige Instanz übersetzt sie einfach - das ist kein lokaler Patch an etwas
|
||||
Ausgeliefertem mehr, sondern Arbeit an den eigenen Dateien, und ein Upgrade nimmt sie ihr
|
||||
nicht wieder weg.
|
||||
|
||||
Was der Stack von `types/` überhaupt noch verlangt, ist eine Zeile: es muss einen Type-Spec
|
||||
mit `name: source` geben, dessen Schema `raw_files` fordert. Daran hängt der gesamte
|
||||
`raw/`→`kb/`-Provenance-Pfad (`sources coverage`, `[^cite-id]`-Auflösung, `kb/provenance.md`),
|
||||
und `docs verify` prüft genau das - nicht mehr.
|
||||
|
||||
Unverändert bleibt in jedem Fall die Regel, die dem Stack gehört: **jede Zeile einer Seite
|
||||
ist Prosa oder Identifier, und nur Prosa wird übersetzt** ([kb/CONTRACT.md § Language and
|
||||
identifiers](../kb/CONTRACT.md#language-and-identifiers)). Titel, Wikilink-Ziele, Cite-IDs,
|
||||
Enum-Werte, Tags, Befehle und Pfade folgen keiner KB-Sprache.
|
||||
|
||||
`tools/wikitool doctor` prüft das Ergebnis in Schritt 12 (`conventions`): eine fehlende
|
||||
Datei ist ein `FAIL`, eine mit Sentinel oder ohne vollständigen `sections:`-Block ebenso.
|
||||
`docs verify` prüft zusätzlich `profile:` und `required_by_stack:` auf jedem
|
||||
`COLLECTION.md`.
|
||||
|
||||
6. **Entscheidungspunkt - Personalization.** Die Distribution bringt
|
||||
`USER.md.template` und `SOUL.md.template` mit, aber keine ausgefüllten Fassungen: wer diese
|
||||
|
||||
@@ -61,8 +61,9 @@ pages should never have cost the concept contract. Field-level requirements alwa
|
||||
article also pass `--set source_url=<upstream URL>`; `raw_files:` must still point at the
|
||||
local copy. Then write the Summary / Key Takeaways / Action Items prose from step 4 - in the
|
||||
KB language, whatever the source's own language is, quoting verbatim passages in the
|
||||
original. The rule and what is exempt from it:
|
||||
[kb/CONTRACT.md](../../kb/CONTRACT.md#language).
|
||||
original. Which language that is: [kb/CONVENTIONS.md](../../kb/CONVENTIONS.md#language).
|
||||
What is exempt from it, in any language:
|
||||
[kb/CONTRACT.md](../../kb/CONTRACT.md#language-and-identifiers).
|
||||
|
||||
Fill `## Not Extracted` in the same pass: what you read and deliberately did not promote,
|
||||
with the reason. Nothing in the repository can re-derive that judgment, and without it the
|
||||
@@ -70,8 +71,9 @@ pages should never have cost the concept contract. Field-level requirements alwa
|
||||
|
||||
6. **Create or update entity pages.** Read
|
||||
[kb/entities/COLLECTION.md](../../kb/entities/COLLECTION.md) and
|
||||
[kb/CONTRACT.md](../../kb/CONTRACT.md) first - the second is where tone, naming, provenance
|
||||
and citation are defined.
|
||||
[kb/CONTRACT.md](../../kb/CONTRACT.md) plus
|
||||
[kb/CONVENTIONS.md](../../kb/CONVENTIONS.md) first - the second is where provenance and
|
||||
citation are defined, the third where this instance's tone and naming forms are.
|
||||
|
||||
New:
|
||||
|
||||
|
||||
@@ -13,10 +13,12 @@ integrating into an existing one.
|
||||
|
||||
**Before the first `wikitool` call:** [session-setup.md](../session-setup.md).
|
||||
|
||||
**Read before drafting:** [kb/CONTRACT.md](../../kb/CONTRACT.md) - naming, tone, linking,
|
||||
provenance and confidence - together with the target collection's own `COLLECTION.md`, which
|
||||
carries its quality goal and what is local to that subtree. Field-level requirements come from
|
||||
`tools/wikitool types describe <type>`.
|
||||
**Read before drafting:** [kb/CONTRACT.md](../../kb/CONTRACT.md) - linking, provenance and the
|
||||
confidence machinery, all of which the tool enforces - and
|
||||
[kb/CONVENTIONS.md](../../kb/CONVENTIONS.md), which is where this instance's language, naming
|
||||
forms, tone and relationship labels are, together with the target collection's own
|
||||
`COLLECTION.md`, which carries its quality goal and what is local to that subtree. Field-level
|
||||
requirements come from `tools/wikitool types describe <type>`.
|
||||
|
||||
## Creating a page
|
||||
|
||||
@@ -46,7 +48,7 @@ carries its quality goal and what is local to that subtree. Field-level requirem
|
||||
subjects - so the prose connects to existing pages instead of restating them.
|
||||
|
||||
5. **Draft.** Fill in the generated skeleton's TODO sections, following the tone rules in
|
||||
[kb/CONTRACT.md](../../kb/CONTRACT.md#tone). If `provenance:` is `sourced` or `mixed`, cite
|
||||
[kb/CONVENTIONS.md](../../kb/CONVENTIONS.md#tone). If `provenance:` is `sourced` or `mixed`, cite
|
||||
hard facts as you write them with `tools/wikitool cite add --page "<Title>" --source
|
||||
"Source - X"`, which also adds `X` to `sources:` - paste the `[^cite-id]` marker it prints.
|
||||
|
||||
|
||||
+110
-82
@@ -7,12 +7,24 @@ material in `raw/`, and is expected to stay correct without being re-derived.
|
||||
**Quality goal:** a page should answer a future question *without* re-reading the source it
|
||||
came from. If answering still requires the raw file, the page is incomplete.
|
||||
|
||||
This file holds the rules that apply in **every** collection. Each `kb/<name>/COLLECTION.md`
|
||||
declares that it inherits them and adds only what is local to its own subtree - read this file
|
||||
together with the target collection's contract before writing or editing a page.
|
||||
This file holds the rules that apply in **every** collection **and in every instance**. That
|
||||
second half is the cut: what is written here is enforced by `tools/wikitool` or follows from
|
||||
how it works, so it is identical everywhere and `dist export` ships it verbatim.
|
||||
|
||||
**What an instance decides for itself is next door, in
|
||||
[kb/CONVENTIONS.md](CONVENTIONS.md)** - the language pages are written in, the headings its two
|
||||
generated regions render under, the naming forms, the tone, the confidence rubric. That file binds exactly as this one does; it is simply owned by the instance
|
||||
rather than by the stack, so the distribution ships only its `.template` and the instance writes
|
||||
the real one. Read both, plus the target collection's `kb/<name>/COLLECTION.md` (also
|
||||
instance-owned), before writing or editing a page.
|
||||
|
||||
The split is by **who may change the sentence**, not by what it is about. Language, tone and
|
||||
naming used to sit here, which meant every instance that answered "not German" to
|
||||
`setup-instance.md` was locally editing a file the stack also ships - and a merge from upstream
|
||||
would quietly hand it back.
|
||||
|
||||
Structural facts (which frontmatter fields exist, which are required, what the body skeleton
|
||||
looks like) are *not* here - they belong to the type-specs and are printed by
|
||||
looks like) are in neither - they belong to the type-specs and are printed by
|
||||
`tools/wikitool types describe <type>`. Never hand-write frontmatter; scaffold with
|
||||
`tools/wikitool new <type> --name "<Name>" --set field=value ...`.
|
||||
|
||||
@@ -21,7 +33,15 @@ looks like) are *not* here - they belong to the type-specs and are printed by
|
||||
`kb/` is a **namespace, not a collection**. It carries no `COLLECTION.md` of its own.
|
||||
|
||||
A directory under `kb/` is a **collection** exactly when it contains a `COLLECTION.md`. That
|
||||
file is the local authoring contract for every page in the subtree.
|
||||
file is the local authoring contract for every page in the subtree, and it belongs to the
|
||||
instance: it declares in its frontmatter which profile from
|
||||
[instructions/kb-profiles.md](../instructions/kb-profiles.md) it adopted, and whether the stack
|
||||
resolves against it by name.
|
||||
|
||||
| Field | Means |
|
||||
|---|---|
|
||||
| `profile:` | Which catalogue entry this contract started from, or `none`. Free text - the catalogue is a palette, not an enum, and a collection an instance invented has no entry to name |
|
||||
| `required_by_stack:` | Whether `wikitool` itself depends on this collection *by name*. Not the instance's to choose: `docs verify` checks it against the stack's own list. `kb/sources/` is `true` - `sources coverage`, `[^cite-id]` resolution and `kb/provenance.md` all resolve against that name - and everything else is `false` |
|
||||
|
||||
- A subdirectory *inside* a collection is an **area**. It inherits the enclosing contract and
|
||||
must not carry a `COLLECTION.md` of its own - `kb/entities/systems/` is an area of
|
||||
@@ -40,9 +60,11 @@ file is the local authoring contract for every page in the subtree.
|
||||
| `kb/sources/` | One summary page per ingested source, carrying its `raw_files:` provenance | [sources/COLLECTION.md](sources/COLLECTION.md) |
|
||||
| `kb/comparisons/` | Structured comparisons of two or more existing pages | [comparisons/COLLECTION.md](comparisons/COLLECTION.md) |
|
||||
|
||||
**Adding a collection:** `mkdir kb/<name>` and write a `kb/<name>/COLLECTION.md`. Collections
|
||||
The four rows above are this instance's collections, not a fixed set. **Adding one:**
|
||||
`mkdir kb/<name>` and write a `kb/<name>/COLLECTION.md` with the two fields above. Collections
|
||||
are discovered by contract presence, so no code change is needed. A collection only becomes
|
||||
*writable* once some type-spec declares a matching `base_dir:`.
|
||||
*writable* once some type-spec declares a matching `base_dir:`. Renaming or dropping one is the
|
||||
instance's call too - except where `required_by_stack: true` says otherwise.
|
||||
|
||||
**Where a page goes** is decided by its type-spec, never by hand - see
|
||||
[types/type-spec.md](../types/type-spec.md).
|
||||
@@ -61,53 +83,41 @@ Never hand-edit these; they are produced by `tools/wikitool`:
|
||||
To *find* a page, search rather than read the catalog: `tools/wikitool search "<text>"`, or
|
||||
`tools/wikitool search --field <predicate>` for a structured query over frontmatter.
|
||||
|
||||
## Naming
|
||||
## Titles are identifiers
|
||||
|
||||
- Human-readable titles with spaces: `Hybrid Search.md`, `Gitea Actions.md` - not kebab-case.
|
||||
- Singular for entities: `ha-core.md`, not `ha-cores.md`.
|
||||
- Comparison pages read as a comparison: `Go vs Rust.md`.
|
||||
- ADRs are prefixed: `adr-001-use-go-modules.md`.
|
||||
- The filename stem *is* the page title, and `[[wikilinks]]` must match it exactly.
|
||||
- Prefer readability over convention when the two conflict.
|
||||
**The filename stem *is* the page title, and `[[wikilinks]]` must match it exactly.** That is
|
||||
not a naming preference; it is the wiki's only way to address a page. `wikitool lint` reports an
|
||||
H1 that stops matching its title, `rename`/`rm` rewrite every reference to a stem, and a
|
||||
`[^cite-id]` resolves through one.
|
||||
|
||||
What to name a thing: projects use their repository or common name; systems a descriptive
|
||||
name; tools the tool's own name; technologies their standard spelling and capitalization;
|
||||
people a full name or common handle.
|
||||
Which *form* those titles take - spaces or kebab-case, singular or plural, what prefixes a
|
||||
decision record - is the instance's, in
|
||||
[kb/CONVENTIONS.md § Naming](CONVENTIONS.md#naming).
|
||||
|
||||
## Every page should
|
||||
|
||||
- [ ] Carry a clear, descriptive title and a summary near the top
|
||||
- [ ] Use consistent terminology with the rest of the wiki
|
||||
- [ ] Link to every entity and concept it mentions, and be linked to in return
|
||||
- [ ] Link to the entities and concepts it mentions, and declare an edge where the relationship
|
||||
is worth naming - in the direction this page asserts it, not in both
|
||||
- [ ] Cite its hard facts (see [Provenance and citation](#provenance-and-citation))
|
||||
- [ ] Duplicate no existing page
|
||||
- [ ] Appear in the catalog (guaranteed by `wikitool index rebuild`)
|
||||
|
||||
## Tone
|
||||
## Quotation cap
|
||||
|
||||
Wikipedia style: factual, neutral, specific.
|
||||
At most 2 blockquoted lines per page. `wikitool lint` reports overages as advisory, since
|
||||
exceeding the cap can be a legitimate judgment call - but the page should carry the knowledge
|
||||
itself, not delegate it to quotations. The cap is about how much of the page you let quotes
|
||||
carry; it does not apply to text you are citing verbatim from a source.
|
||||
|
||||
- No buzzwords ("bahnbrechend", "hochmodern", "leistungsstark", "revolutioniert").
|
||||
- No AI filler ("es sei angemerkt", "es ist wichtig zu betonen", "in der heutigen Zeit").
|
||||
- No em-dash asides carrying parenthetical reasoning.
|
||||
- At most 2 blockquoted lines per page. `wikitool lint` reports overages as advisory, since
|
||||
exceeding the cap can be a legitimate judgment call - but the page should carry the
|
||||
knowledge itself, not delegate it to quotations. The cap is about how much of the page you
|
||||
let quotes carry; it does not apply to text you are citing verbatim from a source.
|
||||
The register those lines are written in - what counts as a buzzword, what filler is refused -
|
||||
is the instance's, in [kb/CONVENTIONS.md § Tone](CONVENTIONS.md#tone).
|
||||
|
||||
Good: "MQTT ist ein leichtgewichtiges Publish-Subscribe-Protokoll für Geräte mit knappen
|
||||
Ressourcen."
|
||||
## Language and identifiers
|
||||
|
||||
Bad: "MQTT ist ein bahnbrechendes, hochmodernes Protokoll, das die IoT-Kommunikation
|
||||
revolutioniert - und es sei angemerkt, dass es ein Publish-Subscribe-Muster verwendet."
|
||||
|
||||
## Language
|
||||
|
||||
Pages are written in **German**. This binds `kb/` and the authoring surface that shapes it -
|
||||
the page type-specs `types/entity.md`, `types/concept.md`, `types/source.md` and
|
||||
`types/comparison.md`. `raw/` is untouched ([raw/CONTRACT.md](../raw/CONTRACT.md)), and the
|
||||
control plane stays English: AGENTS.md, the stage contracts including this one, `instructions/`,
|
||||
and the type-specs for non-page artifacts.
|
||||
*Which* language pages are written in is [kb/CONVENTIONS.md](CONVENTIONS.md)'s to say. What
|
||||
follows here is the part that is not a choice, because the tool resolves against it.
|
||||
|
||||
Every line of a page is either **prose** or an **identifier**. Only prose is translated.
|
||||
|
||||
@@ -118,55 +128,75 @@ source page's Summary / Key Takeaways / Action Items / Not Extracted, and `summa
|
||||
|
||||
| Identifier | Why |
|
||||
|---|---|
|
||||
| Page titles, and the H1 that repeats one | A title is the wiki's only identifier for a page and follows the subject's own established name - see [Naming](#naming). `wikitool lint` reports an H1 that stops matching its title |
|
||||
| Page titles, and the H1 that repeats one | A title is the wiki's only identifier for a page and follows the subject's own established name - see [Titles are identifiers](#titles-are-identifiers). `wikitool lint` reports an H1 that stops matching its title |
|
||||
| The subtype value on the generated `**Typ:**` line | It renders a schema enum value (`technology`, `workflow`), which `search --field` filters on. The label is prose; the value is not |
|
||||
| `tags:` | Search keys, not prose |
|
||||
| Commands, paths, config keys, hostnames, code | They are what they are |
|
||||
| Quotations | Quoted verbatim in the source's own language |
|
||||
|
||||
Established English technical terms stay English inside German prose - "GitOps", "Ownership
|
||||
Model", "Reverse Proxy", "Pull Request". Translate a term only where the German one is genuinely
|
||||
the more common usage. A coined German equivalent nobody else writes makes the page harder to
|
||||
find, not more idiomatic.
|
||||
|
||||
Which terms those are, which have a settled German form, and the register the prose is written in:
|
||||
[instructions/german-terminology.md](../instructions/german-terminology.md). It is lookup material,
|
||||
not a second rule - every entry in it is a decision that was made wrong once first.
|
||||
Which foreign technical terms stay untranslated inside that prose is a judgment call the
|
||||
instance records - see [kb/CONVENTIONS.md § Language](CONVENTIONS.md#language).
|
||||
|
||||
**A source in another language** is still summarized in the KB language: a source page is
|
||||
evidence *about* a source, not a substitute for it. Quote verbatim in the original language and
|
||||
record the raw file's language in `source_language:`.
|
||||
|
||||
### Section headings
|
||||
### Generated regions
|
||||
|
||||
Three headings are a vocabulary the tool owns rather than prose an author picks: `xref add`
|
||||
writes into Relationships and See Also, and `cite add` owns the trailing Footnotes block. They
|
||||
follow the KB language like everything else - `## Beziehungen`, `## Siehe auch`, `## Fußnoten` -
|
||||
and `tools/chemenu/sections.py` is the single place naming them.
|
||||
Two regions of a page body are **generated**, not authored: the links region `xref` owns and the
|
||||
footnotes region `cite` owns. Each sits between a marker pair:
|
||||
|
||||
Each has aliases the tool still *recognizes* but no longer writes, which is what lets the corpus
|
||||
be translated page by page: a page still carrying `## Relationships` is found and appended to
|
||||
correctly, and `cite sync` leaves an untranslated `## Footnotes` heading alone rather than
|
||||
retitling it. Renaming a heading is the translation pass's job, never a side effect of another
|
||||
command. Any *other* heading an author adds is ordinary prose and is translated with the rest.
|
||||
```markdown
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **depends-on:** [[Hermes]]
|
||||
<!-- /wikitool:links -->
|
||||
```
|
||||
|
||||
The marker is what the tool locates the region by, and everything between the markers -
|
||||
**heading included** - is replaced wholesale on the next write. An author never edits inside
|
||||
them; anything left there is overwritten without warning, exactly as in `kb/index.md`. A region
|
||||
with nothing to show is absent rather than empty.
|
||||
|
||||
The heading is therefore a *rendering* value, taken from `kb/CONVENTIONS.md`'s `sections:`. No
|
||||
heading text exists in the compiler, and nothing matches on it: changing the declaration
|
||||
re-renders the words on the next write and cannot split a page.
|
||||
|
||||
That is not how it used to work. The tool located these regions by matching their heading text,
|
||||
which made a translated heading a structural fact - and made the region's *end* a guess. It ran
|
||||
to the next heading, and before that to the end of the file, which silently deleted whatever sat
|
||||
after it on eight pages. Any *other* heading a page carries is ordinary prose.
|
||||
|
||||
## Linking
|
||||
|
||||
Every page links to what it mentions, in both directions. Cross-references are created with
|
||||
`tools/wikitool xref add --a "<A>" --b "<B>" --rel-a "<label>" --rel-b "<label>"`, never by
|
||||
hand-editing the `related:` array or the Relationships/See Also bullets.
|
||||
**An edge is authored in one direction**, on the page that asserts it, and carries a label that
|
||||
is a machine value rather than prose:
|
||||
|
||||
Use a typed relationship label rather than a generic one:
|
||||
```yaml
|
||||
related:
|
||||
- depends-on: Hermes
|
||||
```
|
||||
|
||||
`hängt ab von` · `verwendet` · `implementiert` · `erweitert` · `ersetzt` · `steht in Konflikt mit`
|
||||
· `benötigt` · `erzeugt` · `konsumiert` · `besitzt` · `pflegt` · `läuft auf` · `verwandt mit`
|
||||
(last resort)
|
||||
Created with `tools/wikitool xref add --a "<A>" --b "<B>" --rel <label>`, never by hand-editing
|
||||
`related:` or the rendered bullet. Say the sentence before choosing the label - `[A] <label>
|
||||
[B]` - and if it only reads true backwards, the edge belongs on the other page.
|
||||
|
||||
The labels are prose written into a `- **label:** [[Title]]` bullet; no code matches on them, so
|
||||
an untranslated page's English label is stale wording, not a broken reference.
|
||||
**A reverse edge is a separate decision, not a mirror.** Write one when it independently helps a
|
||||
reader at the other end; do not write one to make the graph symmetric. Navigation does not
|
||||
depend on it either way: `index rebuild` renders the inbound view from the graph, completely and
|
||||
without maintenance.
|
||||
|
||||
A page is expected to have at least one inbound link; `wikitool lint` reports orphans.
|
||||
Comparison pages are exempt - they are reached through the catalog.
|
||||
Which labels exist is [instructions/link-taxonomy.md](../instructions/link-taxonomy.md), a
|
||||
palette that binds nothing. Which of them a page may *use* is its own collection's `outbound:`
|
||||
block, per destination - the **source** collection decides, because the rules that govern an
|
||||
edge are the rules of the collection asserting it. `xref add` refuses an unauthorised label and
|
||||
`lint` reports one.
|
||||
|
||||
A page is expected to have at least one inbound edge; `wikitool lint` reports orphans.
|
||||
Comparison pages are exempt - they are reached through the catalog. Directional edges mean more
|
||||
pages qualify than under the old mirrored model, and that is the check measuring reachability
|
||||
rather than measuring whether `xref` ran.
|
||||
|
||||
Renaming a page, deleting one, or dropping a single reference are tool operations with their
|
||||
own procedure: see [instructions/page-lifecycle.md](../instructions/page-lifecycle.md).
|
||||
@@ -187,15 +217,16 @@ Every claim is either traceable to a raw file or explicitly marked as not.
|
||||
command, or config value. `tools/wikitool cite add --page "<Title>" --source "Source - X"
|
||||
[--file <qualifier>]` mints the id, upserts its `[[Source - X]]` (or
|
||||
`[[Source - X|storage-model.md]]` for a multi-file source) definition in the page's trailing
|
||||
`## Footnotes` block, and adds `Source - X` to `sources:` - it prints the marker to paste at
|
||||
Footnotes block (named per [Section headings](#section-headings)), and adds `Source - X` to
|
||||
`sources:` - it prints the marker to paste at
|
||||
the fact; placing it is still manual. Never hand-type a cite-id (AGENTS.md invariant 1). This
|
||||
differs from a plain `[[Source - X]]` link, which only means "related to".
|
||||
- **Notation inside code is notation, not a reference.** A `[^cite-id]` or a `[[wikilink]]`
|
||||
written in backticks or a fenced block is read as an example: the citation does not count and
|
||||
the link does not exist. That is what lets a page document this stack's own syntax. It also
|
||||
means a marker appended to a line *inside* a fence cites nothing - put it on a
|
||||
`Quelle: [^cite-id]` line under the block, where it renders as a footnote instead of
|
||||
travelling with the command when someone copies it.
|
||||
means a marker appended to a line *inside* a fence cites nothing - put it on a source line
|
||||
under the block (`<source-word>: [^cite-id]`, in the KB language), where it renders as a
|
||||
footnote instead of travelling with the command when someone copies it.
|
||||
- A source cited inline must also appear in the page's frontmatter `sources:` list;
|
||||
`wikitool lint` checks this in both directions, and hard-errors on a leftover pre-migration
|
||||
`^[[...]]` marker, an undefined `[^cite-id]` reference, or an orphaned Footnotes definition.
|
||||
@@ -215,23 +246,20 @@ one - and never file the synthesized version back into the wiki.
|
||||
`confidence` is *derived* from it by `tools/wikitool confidence decay` and must never be
|
||||
edited directly.
|
||||
|
||||
Base score for a single source is 0.5, adjusted by:
|
||||
|
||||
- **+0.2 per supporting source** (max +0.6)
|
||||
- **+0.2** if confirmed <30 days ago, **+0.1** if <90 days
|
||||
- **+0.1** for official documentation, **+0.05** for a reputable secondary source
|
||||
- **+0.1** if multiple independent sources agree
|
||||
|
||||
Re-assess a page with `tools/wikitool touch --page "<Title>" --confidence-base <value>`.
|
||||
|
||||
In prose, hedge according to the score: below 0.6 write "möglicherweise"/"kann"; below 0.4
|
||||
write "unsicher"/"unbestätigt".
|
||||
What the number *means* - the base score, what raises it and by how much, and how to hedge in
|
||||
prose below a threshold - is a rubric rather than a mechanism, so it is
|
||||
[kb/CONVENTIONS.md § Confidence rubric](CONVENTIONS.md#confidence-rubric)'s.
|
||||
|
||||
## What does not belong here
|
||||
|
||||
- Raw source material - it stays immutable under `raw/`.
|
||||
- Type definitions, frontmatter contracts, or templates - those live in `types/`.
|
||||
- Procedures for operating the tooling - those live in `instructions/`.
|
||||
- **Anything an instance would have to rewrite for itself** - language, naming forms, tone,
|
||||
relationship labels, the confidence rubric. Those are `kb/CONVENTIONS.md`'s, and a sentence
|
||||
of that kind here is a sentence the stack ships over the instance's own answer.
|
||||
- Rules that apply to only one collection - those belong in that collection's
|
||||
`COLLECTION.md`.
|
||||
- Hand-edited generated files - see [Generated files](#generated-files).
|
||||
|
||||
@@ -0,0 +1,119 @@
|
||||
---
|
||||
language: de
|
||||
profile: german
|
||||
sections:
|
||||
links: Beziehungen
|
||||
footnotes: Fußnoten
|
||||
---
|
||||
|
||||
# kb/ - Authoring Conventions of This Instance
|
||||
|
||||
The decisions [kb/CONTRACT.md](CONTRACT.md) deliberately does not make. The contract holds what
|
||||
the code enforces and is identical in every instance; this file holds what *this* instance
|
||||
chose, and no other instance has to agree with a word of it.
|
||||
|
||||
**It binds all the same.** Everything below applies to every page under `kb/`, exactly as the
|
||||
contract does. The difference is ownership, not authority: a rule here is changed by editing
|
||||
this file, a rule there by changing the stack.
|
||||
|
||||
Adopted from the `german` profile in
|
||||
[instructions/kb-profiles.md](../instructions/kb-profiles.md). That catalogue is a palette, not
|
||||
an enum - what is written here is what holds, whether or not a profile says the same thing.
|
||||
|
||||
The frontmatter above is the one machine-read part. `sections:` names the headings the two
|
||||
**generated regions** render under - the links region `wikitool xref` owns and the footnotes
|
||||
region `wikitool cite` owns. Each sits between a marker pair, and the marker is what the tool
|
||||
locates it by, so the heading here is a display value: changing it re-renders the words above
|
||||
those regions and nothing else. Nothing matches on this text.
|
||||
|
||||
## Language
|
||||
|
||||
Pages are written in **German**. This binds `kb/` and the authoring surface that shapes it -
|
||||
the page type-specs `types/entity.md`, `types/concept.md`, `types/source.md` and
|
||||
`types/comparison.md`. `raw/` is untouched ([raw/CONTRACT.md](../raw/CONTRACT.md)), and the
|
||||
control plane stays English: `AGENTS.md`, the stage contracts, this file, `instructions/`, and
|
||||
the type-specs for non-page artifacts.
|
||||
|
||||
Which line is prose and which is an identifier - and therefore what is translated at all - is
|
||||
the contract's rule, not this file's: see
|
||||
[kb/CONTRACT.md § Language and identifiers](CONTRACT.md#language-and-identifiers).
|
||||
|
||||
Established English technical terms stay English inside German prose - "GitOps", "Ownership
|
||||
Model", "Reverse Proxy", "Pull Request". Translate a term only where the German one is genuinely
|
||||
the more common usage. A coined German equivalent nobody else writes makes the page harder to
|
||||
find, not more idiomatic.
|
||||
|
||||
Which terms those are, which have a settled German form, and the register the prose is written
|
||||
in: [instructions/german-terminology.md](../instructions/german-terminology.md). It is lookup
|
||||
material, not a second rule - every entry in it is a decision that was made wrong once first.
|
||||
|
||||
### Section headings
|
||||
|
||||
The two generated regions render under `## Beziehungen` and `## Fußnoten`. An author never
|
||||
writes inside them - they are rebuilt from frontmatter on every write, exactly like
|
||||
`kb/index.md` - and never has to write the heading either. Any *other* heading on a page is
|
||||
ordinary prose and is translated with the rest.
|
||||
|
||||
There is no `## Siehe auch` region any more. It was the reciprocal half of a bidirectional
|
||||
`xref add`; under authored directional edges, `see-also` is a *label* inside the links region.
|
||||
|
||||
## Naming
|
||||
|
||||
- Human-readable titles with spaces: `Hybrid Search.md`, `Gitea Actions.md` - not kebab-case.
|
||||
- Singular for entities: `ha-core.md`, not `ha-cores.md`.
|
||||
- Comparison pages read as a comparison: `Go vs Rust.md`.
|
||||
- ADRs are prefixed: `adr-001-use-go-modules.md`.
|
||||
- Prefer readability over convention when the two conflict.
|
||||
|
||||
What to name a thing: projects use their repository or common name; systems a descriptive
|
||||
name; tools the tool's own name; technologies their standard spelling and capitalization;
|
||||
people a full name or common handle.
|
||||
|
||||
The one naming fact that is *not* a choice, and therefore lives in the contract: the filename
|
||||
stem is the page title, and `[[wikilinks]]` must match it exactly.
|
||||
|
||||
## Tone
|
||||
|
||||
Wikipedia style: factual, neutral, specific.
|
||||
|
||||
- No buzzwords ("bahnbrechend", "hochmodern", "leistungsstark", "revolutioniert").
|
||||
- No AI filler ("es sei angemerkt", "es ist wichtig zu betonen", "in der heutigen Zeit").
|
||||
- No em-dash asides carrying parenthetical reasoning.
|
||||
|
||||
Good: "MQTT ist ein leichtgewichtiges Publish-Subscribe-Protokoll für Geräte mit knappen
|
||||
Ressourcen."
|
||||
|
||||
Bad: "MQTT ist ein bahnbrechendes, hochmodernes Protokoll, das die IoT-Kommunikation
|
||||
revolutioniert - und es sei angemerkt, dass es ein Publish-Subscribe-Muster verwendet."
|
||||
|
||||
The blockquote cap is not here: `wikitool lint` reports it, so it is the contract's.
|
||||
|
||||
## Relationship labels
|
||||
|
||||
**Not this file's to list, and not localized.** A label is a machine value in `related:`, drawn
|
||||
from [instructions/link-taxonomy.md](../instructions/link-taxonomy.md) and authorised per
|
||||
destination in each `kb/<name>/COLLECTION.md`'s `outbound:` block. `- **depends-on:** [[Hermes]]`
|
||||
is what a German page carries, and that is deliberate: the label is an identifier, so translating
|
||||
it would make the graph's semantics depend on the prose again.
|
||||
|
||||
## Confidence rubric
|
||||
|
||||
`confidence_base` is set by hand and `confidence` is derived from it - that mechanism is the
|
||||
contract's. What the number *means* is this instance's:
|
||||
|
||||
Base score for a single source is 0.5, adjusted by:
|
||||
|
||||
- **+0.2 per supporting source** (max +0.6)
|
||||
- **+0.2** if confirmed <30 days ago, **+0.1** if <90 days
|
||||
- **+0.1** for official documentation, **+0.05** for a reputable secondary source
|
||||
- **+0.1** if multiple independent sources agree
|
||||
|
||||
In prose, hedge according to the score: below 0.6 write "möglicherweise"/"kann"; below 0.4
|
||||
write "unsicher"/"unbestätigt".
|
||||
|
||||
## Keeping this file honest
|
||||
|
||||
Change it when a convention actually changes. `sections:` is safe to change at any time - the
|
||||
regions are located by their markers and re-rendered under the new words on the next write.
|
||||
`wikitool doctor` FAILs on a missing or unfilled file, and `wikitool docs verify` refuses a
|
||||
`sections:` block that does not name both regions.
|
||||
@@ -0,0 +1,89 @@
|
||||
---
|
||||
# wikitool:template-unfilled - delete this line once the file is answered.
|
||||
language: en
|
||||
profile: none
|
||||
sections:
|
||||
links: Relationships
|
||||
footnotes: Footnotes
|
||||
---
|
||||
|
||||
# kb/ - Authoring Conventions of This Instance
|
||||
|
||||
The decisions [kb/CONTRACT.md](CONTRACT.md) deliberately does not make. The contract holds what
|
||||
the code enforces and is identical in every instance; this file holds what *this* instance
|
||||
chooses, and no other instance has to agree with a word of it.
|
||||
|
||||
**It binds all the same.** Everything below applies to every page under `kb/`, exactly as the
|
||||
contract does. The difference is ownership, not authority: a rule here is changed by editing
|
||||
this file, a rule there by changing the stack.
|
||||
|
||||
Ready-made answers to every section below - including a complete German profile - are in
|
||||
[instructions/kb-profiles.md](../instructions/kb-profiles.md). That catalogue is a palette, not
|
||||
an enum: adopt an entry, adapt it, or write your own. What is written *here* is what holds.
|
||||
|
||||
The frontmatter above is the one machine-read part. `sections:` names the headings the two
|
||||
generated regions render under. Safe to change at any time - each region is located by its
|
||||
marker pair, so a rename re-renders words and nothing else.
|
||||
|
||||
## Language
|
||||
|
||||
Pages are written in **{language}**. This binds `kb/` and the authoring surface that shapes it -
|
||||
the page type-specs `types/entity.md`, `types/concept.md`, `types/source.md` and
|
||||
`types/comparison.md`, whose `## Template` blocks are the body skeleton every new page starts
|
||||
from. `raw/` is untouched ([raw/CONTRACT.md](../raw/CONTRACT.md)), and the control plane stays
|
||||
English: `AGENTS.md`, the stage contracts, this file, `instructions/`, and the type-specs for
|
||||
non-page artifacts.
|
||||
|
||||
Which line is prose and which is an identifier - and therefore what is translated at all - is
|
||||
the contract's rule, not this file's: see
|
||||
[kb/CONTRACT.md § Language and identifiers](CONTRACT.md#language-and-identifiers).
|
||||
|
||||
{Which established foreign-language technical terms stay untranslated inside this instance's
|
||||
prose, and where the vocabulary for that is looked up. Delete this paragraph if the KB language
|
||||
is the one those terms are already in.}
|
||||
|
||||
### Section headings
|
||||
|
||||
The two generated regions render under the frontmatter's headings. An author never writes inside
|
||||
them - they are rebuilt from frontmatter on every write. Any *other* heading is ordinary prose.
|
||||
|
||||
## Naming
|
||||
|
||||
- {Title form - words and spaces, or kebab-case, or the subject's own spelling.}
|
||||
- {Singular or plural for entities.}
|
||||
- {How a comparison page's title reads.}
|
||||
- {The ADR prefix, if this instance files decisions as pages.}
|
||||
- {What to name a thing: projects, systems, tools, technologies, people.}
|
||||
|
||||
The one naming fact that is *not* a choice, and therefore lives in the contract: the filename
|
||||
stem is the page title, and `[[wikilinks]]` must match it exactly.
|
||||
|
||||
## Tone
|
||||
|
||||
{The register pages are written in, in one line.}
|
||||
|
||||
- {Words and constructions this instance refuses, with examples in the KB language.}
|
||||
|
||||
Good: {one sentence that is what this instance wants.}
|
||||
|
||||
Bad: {the same sentence written the way it must not be.}
|
||||
|
||||
## Relationship labels
|
||||
|
||||
**Not this file's to list, and not localized.** A label is a machine value in `related:`, drawn
|
||||
from [instructions/link-taxonomy.md](../instructions/link-taxonomy.md) and authorised per
|
||||
destination in each `kb/<name>/COLLECTION.md`'s `outbound:` block.
|
||||
|
||||
## Confidence rubric
|
||||
|
||||
`confidence_base` is set by hand and `confidence` is derived from it - that mechanism is the
|
||||
contract's. What the number *means* is this instance's:
|
||||
|
||||
{the base score, what raises it, and by how much}
|
||||
|
||||
{How to hedge in prose at a low score, in the KB language.}
|
||||
|
||||
## Keeping this file honest
|
||||
|
||||
Change it when a convention actually changes. `wikitool doctor` FAILs on a missing or unfilled
|
||||
file, and `wikitool docs verify` refuses a `sections:` block that does not name both regions.
|
||||
@@ -1,3 +1,10 @@
|
||||
---
|
||||
profile: comparisons
|
||||
outbound:
|
||||
any: [compares-with, contrasts, see-also]
|
||||
required_by_stack: false
|
||||
---
|
||||
|
||||
# kb/comparisons/ - Collection Contract
|
||||
|
||||
Structured head-to-head evaluations of two or more things that already have pages here. A
|
||||
@@ -7,8 +14,10 @@ comparison exists so that neither subject's own page has to argue against the ot
|
||||
That needs named, checkable dimensions and a stated trade-off; a page that lists differences
|
||||
without saying what they cost has described, not compared.
|
||||
|
||||
Inherits [kb/CONTRACT.md](../CONTRACT.md) - naming, tone, linking, provenance and confidence
|
||||
are defined there and are not restated here.
|
||||
Inherits [kb/CONTRACT.md](../CONTRACT.md) for the rules the stack enforces - linking mechanics,
|
||||
provenance, citation, the confidence machinery - and
|
||||
[kb/CONVENTIONS.md](../CONVENTIONS.md) for what this instance decided: language, naming forms,
|
||||
tone, relationship labels, the confidence rubric. Neither is restated here.
|
||||
|
||||
## Types offered
|
||||
|
||||
@@ -16,8 +25,9 @@ are defined there and are not restated here.
|
||||
|
||||
## Naming
|
||||
|
||||
The title reads as a comparison: `Go vs Rust.md`, `Traefik vs nginx.md`. Order the subjects as
|
||||
they are most commonly spoken, not alphabetically.
|
||||
The title form is [kb/CONVENTIONS.md § Naming](../CONVENTIONS.md#naming)'s. What is local here
|
||||
is the ordering: name the subjects as they are most commonly spoken together, not
|
||||
alphabetically.
|
||||
|
||||
## Requirements
|
||||
|
||||
@@ -29,11 +39,22 @@ they are most commonly spoken, not alphabetically.
|
||||
- State the trade-off, not a winner. Where a recommendation is genuinely warranted, scope it:
|
||||
"for X workload", not "better".
|
||||
|
||||
## Authorised labels
|
||||
|
||||
The `outbound:` block above is what `wikitool lint` and `xref add` check: which labels a page in
|
||||
this collection may use, per destination. The catalogue they are drawn from - and what each one
|
||||
asserts - is [instructions/link-taxonomy.md](../../instructions/link-taxonomy.md), which binds
|
||||
nothing on its own.
|
||||
|
||||
Narrow for the opposite reason: a comparison's substance is its table, and its links to the compared subjects are the one relationship it asserts.
|
||||
|
||||
Adding a label here is a deliberate contract change, not a way around a refusal.
|
||||
|
||||
## Outbound linking
|
||||
|
||||
A comparison links to every subject with `related to`, and each subject links back. Comparison
|
||||
pages are **exempt from the orphan check** - they are reached through `index.md` rather than
|
||||
through inbound prose links.
|
||||
A comparison links to every subject with `compares-with`. The subjects do not have to link back:
|
||||
a comparison is reached through the catalog, and each subject's inbound view renders the edge
|
||||
anyway. Comparison pages are **exempt from the orphan check** for the same reason.
|
||||
|
||||
## What does not belong here
|
||||
|
||||
|
||||
@@ -133,11 +133,6 @@ ls /sys/devices/system/cpu/cpu0/cpufreq/cppc_*
|
||||
|
||||
## Beziehungen
|
||||
|
||||
- **compares:** [[amd-pstate]]
|
||||
- **compares:** [[acpi-cpufreq]]
|
||||
|
||||
## Siehe auch
|
||||
|
||||
- [[amd-pstate]]
|
||||
- [[acpi-cpufreq]]
|
||||
- **compares-with:** [[amd-pstate]]
|
||||
- **compares-with:** [[acpi-cpufreq]]
|
||||
|
||||
|
||||
@@ -4,7 +4,11 @@ concept_type: problem
|
||||
tags: [tests, ci, tooling, quality]
|
||||
created: 2026-08-31
|
||||
modified: 2026-08-31
|
||||
related: [Structural Enforcement over Documented Rule, Green Suite Blind Spot, wikitool, Gitea Actions]
|
||||
related:
|
||||
- exemplifies: Structural Enforcement over Documented Rule
|
||||
- contrasts: Green Suite Blind Spot
|
||||
- exemplifies: wikitool
|
||||
- exemplifies: Gitea Actions
|
||||
sources: [Source - Conversation - Hardening the Test Suite Against Silent Environment Dependencies Session 2026-08-31]
|
||||
confidence: 0.50
|
||||
confidence_base: 0.50
|
||||
@@ -101,26 +105,21 @@ wird sie erst auf einer fremden Maschine - und wenn niemand die Suite je woander
|
||||
- Als Argument gegen Integrationstests gegen echte Systeme. Die stützen sich bewusst auf eine
|
||||
Umgebung, und das ist deklariert - nicht still.
|
||||
|
||||
## Verwandte Concepts
|
||||
|
||||
- [[Green Suite Blind Spot]]
|
||||
- [[Structural Enforcement over Documented Rule]]
|
||||
|
||||
## Beziehungen
|
||||
|
||||
- **abzugrenzen von:** [[Green Suite Blind Spot]]
|
||||
- **behoben durch:** [[Structural Enforcement over Documented Rule]]
|
||||
- **trat auf in:** [[wikitool]]
|
||||
- **beobachtet an:** [[Gitea Actions]]
|
||||
|
||||
## Siehe auch
|
||||
|
||||
- [[Source - Conversation - Hardening the Test Suite Against Silent Environment Dependencies Session 2026-08-31]]
|
||||
- [[Structural Enforcement over Documented Rule]]
|
||||
- [[Green Suite Blind Spot]]
|
||||
- [[wikitool]]
|
||||
- [[Gitea Actions]]
|
||||
|
||||
## Fußnoten
|
||||
|
||||
[^s-conversation-hardening-the-test-suite-against-silent-environment-dependencies-session-2026-08-31]: [[Source - Conversation - Hardening the Test Suite Against Silent Environment Dependencies Session 2026-08-31]]
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **exemplifies:** [[Structural Enforcement over Documented Rule]]
|
||||
- **contrasts:** [[Green Suite Blind Spot]]
|
||||
- **exemplifies:** [[wikitool]]
|
||||
- **exemplifies:** [[Gitea Actions]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,9 @@ concept_type: workflow
|
||||
tags: [cramming, heuristic, pages, creation]
|
||||
created: 2026-08-03
|
||||
modified: 2026-08-29
|
||||
related: [Content Quality Control, Iteration and Cost Limits]
|
||||
related:
|
||||
- part-of: Content Quality Control
|
||||
- see-also: Iteration and Cost Limits
|
||||
sources: [Source - LLM Improvements Sonnet Analysis, Source - LLM Improvements Production Agent Gaps 2026]
|
||||
confidence: 0.80
|
||||
confidence_base: 0.80
|
||||
@@ -46,21 +48,20 @@ Die Anti-Cramming-Heuristik ist eine Entscheidungsregel, die hilft zu bestimmen,
|
||||
- Wenn das Unterthema inhärent Teil des Hauptthemas ist und eine Aufteilung künstlich wäre
|
||||
- Wenn der Inhalt kurz ist und die Seite gut organisiert bleibt
|
||||
|
||||
## Verwandte Concepts
|
||||
|
||||
- [[Content Quality Control]] - Breitere Qualitätsrichtlinie
|
||||
- [[Split Threshold]] - Größenbasierte Aufteilungsregel
|
||||
|
||||
## Beziehungen
|
||||
|
||||
- **protected by:** [[Iteration and Cost Limits]]
|
||||
|
||||
## Siehe auch
|
||||
|
||||
- [[Source - LLM Improvements Sonnet Analysis]]
|
||||
- [[Iteration and Cost Limits]]
|
||||
- [[Source - LLM Improvements Production Agent Gaps 2026]]
|
||||
|
||||
## Fußnoten
|
||||
|
||||
[^s-llm-improvements-sonnet-analysis]: [[Source - LLM Improvements Sonnet Analysis]]
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **part-of:** [[Content Quality Control]]
|
||||
- **see-also:** [[Iteration and Cost Limits]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,13 @@ concept_type: pattern
|
||||
tags: []
|
||||
created: 2026-08-02
|
||||
modified: 2026-08-29
|
||||
related: [Implementation Spectrum, Multi-Agent Collaboration, Privacy and Governance, Quality and Self-Correction, Source - LLM Wiki v2, Supersession]
|
||||
related:
|
||||
- exemplifies: Implementation Spectrum
|
||||
- enables: Multi-Agent Collaboration
|
||||
- part-of: Privacy and Governance
|
||||
- enables: Quality and Self-Correction
|
||||
- evidenced-by: Source - LLM Wiki v2
|
||||
- enables: Supersession
|
||||
sources: []
|
||||
confidence: 0.50
|
||||
confidence_base: 0.50
|
||||
@@ -38,3 +44,14 @@ TODO
|
||||
## Verwandte Concepts
|
||||
|
||||
- TODO
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **exemplifies:** [[Implementation Spectrum]]
|
||||
- **enables:** [[Multi-Agent Collaboration]]
|
||||
- **part-of:** [[Privacy and Governance]]
|
||||
- **enables:** [[Quality and Self-Correction]]
|
||||
- **evidenced-by:** [[Source - LLM Wiki v2]]
|
||||
- **enables:** [[Supersession]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
+12
-1
@@ -4,7 +4,10 @@ concept_type: pattern
|
||||
tags: []
|
||||
created: 2026-08-02
|
||||
modified: 2026-08-29
|
||||
related: [Hybrid Search, LLM Wiki Pattern, Source - LLM Wiki v2]
|
||||
related:
|
||||
- part-of: Hybrid Search
|
||||
- see-also: LLM Wiki Pattern
|
||||
- evidenced-by: Source - LLM Wiki v2
|
||||
sources: []
|
||||
confidence: 0.50
|
||||
confidence_base: 0.50
|
||||
@@ -38,3 +41,11 @@ TODO
|
||||
## Verwandte Concepts
|
||||
|
||||
- TODO
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **part-of:** [[Hybrid Search]]
|
||||
- **see-also:** [[LLM Wiki Pattern]]
|
||||
- **evidenced-by:** [[Source - LLM Wiki v2]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,10 @@ concept_type: workflow
|
||||
tags: []
|
||||
created: 2026-08-02
|
||||
modified: 2026-08-29
|
||||
related: [Privacy and Governance, Implementation Spectrum, Mass-Update Gate]
|
||||
related:
|
||||
- part-of: Privacy and Governance
|
||||
- exemplifies: Implementation Spectrum
|
||||
- see-also: Mass-Update Gate
|
||||
sources: []
|
||||
confidence: 0.50
|
||||
confidence_base: 0.50
|
||||
@@ -41,9 +44,12 @@ TODO
|
||||
|
||||
## Beziehungen
|
||||
|
||||
- **ergaenzt:** [[Mass-Update Gate]]
|
||||
|
||||
## Siehe auch
|
||||
|
||||
- [[Mass-Update Gate]]
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **part-of:** [[Privacy and Governance]]
|
||||
- **exemplifies:** [[Implementation Spectrum]]
|
||||
- **see-also:** [[Mass-Update Gate]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,9 @@ concept_type: workflow
|
||||
tags: [pre-commit, hooks, automation, quality-control]
|
||||
created: 2026-08-03
|
||||
modified: 2026-09-01
|
||||
related: [wikitool, Gitea Actions]
|
||||
related:
|
||||
- invokes: wikitool
|
||||
- operates-on: Gitea Actions
|
||||
sources: [Source - LLM Improvements Codex Analysis, Source - Conversation - Nightly Drift-Check Workflow and doctor's Bootstrap Gap Session 2026-08-31]
|
||||
confidence: 0.80
|
||||
confidence_base: 0.80
|
||||
@@ -82,24 +84,23 @@ Bootstrap-Anspruch an eine Instanz statt an einen bloßen Checkout).
|
||||
|
||||
## Verwandte Concepts
|
||||
|
||||
- [[wikitool]] (stellt Lint- und andere Befehle für CI bereit)
|
||||
(die Reihenfolge hinter dem Coverage-Reporting)
|
||||
(CI-Gates ergänzen Runtime-Gates)
|
||||
- [[Lint Workflow]] (Lint ist eine Schlüssel-CI-Prüfung)
|
||||
- [[Source - LLM Improvements Codex Analysis]][^s-llm-improvements-codex-analysis]
|
||||
|
||||
## Beziehungen
|
||||
|
||||
- **verwendet:** [[wikitool]]
|
||||
- **implementiert über:** [[Gitea Actions]]
|
||||
|
||||
## Siehe auch
|
||||
|
||||
- [[Source - LLM Improvements Codex Analysis]]
|
||||
- [[wikitool]]
|
||||
- [[Gitea Actions]]
|
||||
|
||||
## Fußnoten
|
||||
|
||||
[^s-conversation-nightly-drift-check-workflow-and-doctor-s-bootstrap-gap-session-2026-08-31]: [[Source - Conversation - Nightly Drift-Check Workflow and doctor's Bootstrap Gap Session 2026-08-31]]
|
||||
[^s-llm-improvements-codex-analysis]: [[Source - LLM Improvements Codex Analysis]]
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **invokes:** [[wikitool]]
|
||||
- **operates-on:** [[Gitea Actions]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -1,3 +1,13 @@
|
||||
---
|
||||
profile: concepts
|
||||
outbound:
|
||||
concepts: [extends, grounds, rests-on, enables, precondition, exemplifies, abstracted-from, contrasts, compares-with, contradicts, composition, part-of, supersedes, derived-from, adapted-from, see-also]
|
||||
entities: [operationalized-from, mechanism, procedure, applies-when, operates-on, invokes, exemplifies, see-also]
|
||||
sources: [evidenced-by, derived-from, adapted-from, defined-in, see-also]
|
||||
comparisons: [compares-with, see-also]
|
||||
required_by_stack: false
|
||||
---
|
||||
|
||||
# kb/concepts/ - Collection Contract
|
||||
|
||||
Ideas rather than things: architectures, patterns, protocols, workflows, recurring problems,
|
||||
@@ -8,8 +18,10 @@ records *what*.
|
||||
without the reader having to open the entity pages that use it. If the explanation only makes
|
||||
sense once you already know the system, it is on the wrong page.
|
||||
|
||||
Inherits [kb/CONTRACT.md](../CONTRACT.md) - naming, tone, linking, provenance and confidence
|
||||
are defined there and are not restated here.
|
||||
Inherits [kb/CONTRACT.md](../CONTRACT.md) for the rules the stack enforces - linking mechanics,
|
||||
provenance, citation, the confidence machinery - and
|
||||
[kb/CONVENTIONS.md](../CONVENTIONS.md) for what this instance decided: language, naming forms,
|
||||
tone, relationship labels, the confidence rubric. Neither is restated here.
|
||||
|
||||
## Types offered
|
||||
|
||||
@@ -17,8 +29,8 @@ are defined there and are not restated here.
|
||||
|
||||
## Decisions and ADRs
|
||||
|
||||
An architectural decision is a concept page prefixed `adr-NNN-`, e.g.
|
||||
`adr-001-use-go-modules.md`. It records:
|
||||
An architectural decision is a concept page, prefixed as
|
||||
[kb/CONVENTIONS.md § Naming](../CONVENTIONS.md#naming) says. It records:
|
||||
|
||||
- **Context** - what forced a decision.
|
||||
- **Decision** - what was chosen.
|
||||
@@ -26,8 +38,19 @@ An architectural decision is a concept page prefixed `adr-NNN-`, e.g.
|
||||
- **Status** - proposed / accepted / deprecated / superseded.
|
||||
- Links to every entity the decision affects.
|
||||
|
||||
A superseded ADR is never deleted or rewritten; a new one supersedes it and both link to the
|
||||
other with `replaces` / `replaced by`.
|
||||
A superseded ADR is never deleted or rewritten. The new one declares `supersedes` pointing at
|
||||
it; the old one needs no edge back, because its inbound view renders the replacement.
|
||||
|
||||
## Authorised labels
|
||||
|
||||
The `outbound:` block above is what `wikitool lint` and `xref add` check: which labels a page in
|
||||
this collection may use, per destination. The catalogue they are drawn from - and what each one
|
||||
asserts - is [instructions/link-taxonomy.md](../../instructions/link-taxonomy.md), which binds
|
||||
nothing on its own.
|
||||
|
||||
The widest authorisation in this instance, because argumentation is what concept pages do. Note that the operational labels are absent: a concept does not `depend-on` anything - the entity implementing it does.
|
||||
|
||||
Adding a label here is a deliberate contract change, not a way around a refusal.
|
||||
|
||||
## Outbound linking
|
||||
|
||||
|
||||
+11
-5
@@ -4,7 +4,10 @@ concept_type: protocol
|
||||
tags: [power-management, cpu, amd, hardware]
|
||||
created: 2026-07-31
|
||||
modified: 2026-08-29
|
||||
related: [Linux Kernel, amd-pstate, Kernel PM Governors]
|
||||
related:
|
||||
- see-also: Linux Kernel
|
||||
- mechanism: amd-pstate
|
||||
- see-also: Kernel PM Governors
|
||||
sources: [Source - AMD Powermanagement CPU]
|
||||
confidence: 0.95
|
||||
confidence_base: 0.95
|
||||
@@ -75,7 +78,10 @@ CPPC bietet mehrere Schlüsselmöglichkeiten:
|
||||
|
||||
## Siehe auch
|
||||
|
||||
- [[amd-pstate]]
|
||||
- [[acpi-cpufreq]]
|
||||
- [[Kernel PM Governors]]
|
||||
- [[Linux Kernel]]
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **see-also:** [[Linux Kernel]]
|
||||
- **mechanism:** [[amd-pstate]]
|
||||
- **see-also:** [[Kernel PM Governors]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,9 @@ concept_type: workflow
|
||||
tags: [audit, checkpoint, rhythm, quality]
|
||||
created: 2026-08-03
|
||||
modified: 2026-08-29
|
||||
related: [Semantic Lint Automation, Content Quality Control]
|
||||
related:
|
||||
- see-also: Semantic Lint Automation
|
||||
- part-of: Content Quality Control
|
||||
sources: [Source - LLM Improvements Sonnet Analysis]
|
||||
confidence: 0.80
|
||||
confidence_base: 0.80
|
||||
@@ -64,3 +66,10 @@ Das Checkpoint Audit definiert einen regelmäßigen Rhythmus für Qualitätssich
|
||||
## Fußnoten
|
||||
|
||||
[^s-llm-improvements-sonnet-analysis]: [[Source - LLM Improvements Sonnet Analysis]]
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **see-also:** [[Semantic Lint Automation]]
|
||||
- **part-of:** [[Content Quality Control]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,9 @@ concept_type: workflow
|
||||
tags: [claude-code, permissions, auto-mode, harness, classifier]
|
||||
created: 2026-08-31
|
||||
modified: 2026-08-31
|
||||
related: [Claude Code, Diff-Reviewable Agent Edits]
|
||||
related:
|
||||
- mechanism: Claude Code
|
||||
- contradicts: Diff-Reviewable Agent Edits
|
||||
sources: [Source - Conversation - Auto Mode and Tool Choice Session 2026-08-31]
|
||||
confidence: 0.50
|
||||
confidence_base: 0.50
|
||||
@@ -96,15 +98,17 @@ ist hier also die eingebaute Voreinstellung, keine getroffene Wahl.
|
||||
|
||||
## Beziehungen
|
||||
|
||||
- **wird umgesetzt von:** [[Claude Code]]
|
||||
- **steht in Konflikt mit:** [[Diff-Reviewable Agent Edits]]
|
||||
|
||||
## Siehe auch
|
||||
|
||||
- [[Claude Code]]
|
||||
- [[Diff-Reviewable Agent Edits]]
|
||||
- [[Source - Conversation - Auto Mode and Tool Choice Session 2026-08-31]]
|
||||
|
||||
## Fußnoten
|
||||
|
||||
[^s-conversation-auto-mode-and-tool-choice-session-2026-08-31]: [[Source - Conversation - Auto Mode and Tool Choice Session 2026-08-31]]
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **mechanism:** [[Claude Code]]
|
||||
- **contradicts:** [[Diff-Reviewable Agent Edits]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,12 @@ concept_type: pattern
|
||||
tags: [wikitool, cli, idempotenz, tooling, datenintegritaet]
|
||||
created: 2026-08-31
|
||||
modified: 2026-08-31
|
||||
related: [wikitool, Self-Healing, Detect-Repair Asymmetry, Green Suite Blind Spot, Write-Once Frontmatter Fields]
|
||||
related:
|
||||
- exemplifies: wikitool
|
||||
- enables: Self-Healing
|
||||
- contrasts: Detect-Repair Asymmetry
|
||||
- see-also: Green Suite Blind Spot
|
||||
- contrasts: Write-Once Frontmatter Fields
|
||||
sources: [Source - Conversation - Two Round-Trip Defects Found by an Ingest Session 2026-08-31]
|
||||
confidence: 0.70
|
||||
confidence_base: 0.70
|
||||
@@ -93,29 +98,24 @@ Seite, die kein Befehl mehr reparieren kann, ist eine Sackgasse.
|
||||
- Als Argument gegen anhängende Schreibvorgänge überhaupt. Das Problem war nicht das Anhängen
|
||||
am Dateiende, sondern ein Leser, der alles dahinter als seinen Bereich betrachtete.
|
||||
|
||||
## Verwandte Concepts
|
||||
|
||||
- [[Detect-Repair Asymmetry]]
|
||||
- [[Self-Healing]]
|
||||
- [[Green Suite Blind Spot]]
|
||||
|
||||
## Beziehungen
|
||||
|
||||
- **tritt auf in:** [[wikitool]]
|
||||
- **erzeugt:** [[Self-Healing]]
|
||||
- **abgegrenzt gegen:** [[Detect-Repair Asymmetry]]
|
||||
- **wird begünstigt durch:** [[Green Suite Blind Spot]]
|
||||
- **abgegrenzt gegen:** [[Write-Once Frontmatter Fields]]
|
||||
|
||||
## Siehe auch
|
||||
|
||||
- [[Source - Conversation - Two Round-Trip Defects Found by an Ingest Session 2026-08-31]]
|
||||
- [[wikitool]]
|
||||
- [[Self-Healing]]
|
||||
- [[Detect-Repair Asymmetry]]
|
||||
- [[Green Suite Blind Spot]]
|
||||
- [[Write-Once Frontmatter Fields]]
|
||||
|
||||
## Fußnoten
|
||||
|
||||
[^s-conversation-two-round-trip-defects-found-by-an-ingest-session-2026-08-31]: [[Source - Conversation - Two Round-Trip Defects Found by an Ingest Session 2026-08-31]]
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **exemplifies:** [[wikitool]]
|
||||
- **enables:** [[Self-Healing]]
|
||||
- **contrasts:** [[Detect-Repair Asymmetry]]
|
||||
- **see-also:** [[Green Suite Blind Spot]]
|
||||
- **contrasts:** [[Write-Once Frontmatter Fields]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,9 @@ concept_type: pattern
|
||||
tags: [confidence, scoring, reliability, knowledge-management]
|
||||
created: 2026-07-26
|
||||
modified: 2026-08-29
|
||||
related: [Memory Lifecycle, LLM Wiki Pattern]
|
||||
related:
|
||||
- part-of: Memory Lifecycle
|
||||
- exemplifies: LLM Wiki Pattern
|
||||
sources: [Source - LLM Wiki v2]
|
||||
confidence: 0.95
|
||||
confidence_base: 0.95
|
||||
@@ -128,3 +130,10 @@ Aussage: „Das CI-System verwendet BuildKit auf Port 1234." (als Tatsache angeg
|
||||
- [[Event-Driven Automation]] (für automatisierte Konfidenz-Updates)
|
||||
- [[Contradiction Resolution]] (für Konfliktbehandlung)
|
||||
- [[Self-Healing]] (für automatisierte Konfidenz-Reparatur)
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **part-of:** [[Memory Lifecycle]]
|
||||
- **exemplifies:** [[LLM Wiki Pattern]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,13 @@ concept_type: architecture
|
||||
tags: [memory, tiers, consolidation, knowledge-management]
|
||||
created: 2026-07-26
|
||||
modified: 2026-08-29
|
||||
related: [Memory Lifecycle, Working Memory, Episodic Memory, Semantic Memory, Procedural Memory, LLM Wiki Pattern]
|
||||
related:
|
||||
- part-of: Memory Lifecycle
|
||||
- composition: Working Memory
|
||||
- composition: Episodic Memory
|
||||
- composition: Semantic Memory
|
||||
- composition: Procedural Memory
|
||||
- exemplifies: LLM Wiki Pattern
|
||||
sources: [Source - LLM Wiki v2]
|
||||
confidence: 0.95
|
||||
confidence_base: 0.95
|
||||
@@ -189,12 +195,6 @@ Basierend auf [[Agent Memory]]-Erfahrung:
|
||||
|
||||
## Verwandte Konzepte
|
||||
|
||||
- [[Memory Lifecycle]] - Übergeordnetes Konzept
|
||||
- [[Working Memory]] - Ebene 1
|
||||
- [[Episodic Memory]] - Ebene 2
|
||||
- [[Semantic Memory]] - Ebene 3
|
||||
- [[Procedural Memory]] - Ebene 4
|
||||
- [[LLM Wiki Pattern]] - Gesamtmuster
|
||||
- [[Agent Memory]] - Produktive Implementierung
|
||||
- [[Forgetting]] - Ergänzender Aufbewahrungsmechanismus
|
||||
|
||||
@@ -203,3 +203,14 @@ Basierend auf [[Agent Memory]]-Erfahrung:
|
||||
- [[Confidence Scoring]] (für ebenenspezifische Konfidenz)
|
||||
- [[Event-Driven Automation]] (für Förderungstrigger)
|
||||
- [[Knowledge Graph]] (für ebenenübergreifende Beziehungen)
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **part-of:** [[Memory Lifecycle]]
|
||||
- **composition:** [[Working Memory]]
|
||||
- **composition:** [[Episodic Memory]]
|
||||
- **composition:** [[Semantic Memory]]
|
||||
- **composition:** [[Procedural Memory]]
|
||||
- **exemplifies:** [[LLM Wiki Pattern]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,10 @@ concept_type: workflow
|
||||
tags: [quality, lint, thresholds, pages]
|
||||
created: 2026-08-03
|
||||
modified: 2026-08-29
|
||||
related: [Semantic Lint Automation, Stub Threshold, Split Threshold]
|
||||
related:
|
||||
- composition: Semantic Lint Automation
|
||||
- composition: Stub Threshold
|
||||
- composition: Split Threshold
|
||||
sources: [Source - LLM Improvements Sonnet Analysis]
|
||||
confidence: 0.80
|
||||
confidence_base: 0.80
|
||||
@@ -45,9 +48,6 @@ Content Quality Control bezieht sich auf die Menge der Regeln, Schwellwerte und
|
||||
|
||||
## Verwandte Konzepte
|
||||
|
||||
- [[Semantic Lint Automation]] - Automatisierte semantische Überprüfungen, die Qualitätsschwellwerte beinhalten könnten
|
||||
- [[Stub Threshold]] - Spezifische Mindestanforderung an Inhalte
|
||||
- [[Split Threshold]] - Spezifische maximale Größe vor dem Aufteilen
|
||||
- [[Index Scaling]] - Verwandte Skalierungsüberlegungen für die Index-Seite
|
||||
|
||||
## Siehe auch
|
||||
@@ -57,3 +57,11 @@ Content Quality Control bezieht sich auf die Menge der Regeln, Schwellwerte und
|
||||
## Fußnoten
|
||||
|
||||
[^s-llm-improvements-sonnet-analysis]: [[Source - LLM Improvements Sonnet Analysis]]
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **composition:** [[Semantic Lint Automation]]
|
||||
- **composition:** [[Stub Threshold]]
|
||||
- **composition:** [[Split Threshold]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,10 @@ concept_type: architecture
|
||||
tags: [context, isolation, efficiency]
|
||||
created: 2026-08-04
|
||||
modified: 2026-08-29
|
||||
related: []
|
||||
related:
|
||||
- see-also: Token Economics
|
||||
- see-also: Scale Ceiling
|
||||
- see-also: Workflow Extraction
|
||||
sources: [Source - Copilot Skill Restructure Instructions, Source - Conversation - AGENTS.md Skill Restructuring Session 2026-08-04]
|
||||
confidence: 0.80
|
||||
confidence_base: 0.80
|
||||
@@ -50,9 +53,6 @@ Context Isolation ist weniger wirksam, wenn:
|
||||
## Verwandte Konzepte
|
||||
|
||||
- [[Cross-platform Agent Skills]]
|
||||
- [[Token Economics]]
|
||||
- [[Scale Ceiling]]
|
||||
- [[Workflow Extraction]]
|
||||
|
||||
## Siehe auch
|
||||
|
||||
@@ -61,3 +61,11 @@ Context Isolation ist weniger wirksam, wenn:
|
||||
## Fußnoten
|
||||
|
||||
[^s-copilot-skill-restructure-instructions]: [[Source - Copilot Skill Restructure Instructions]]
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **see-also:** [[Token Economics]]
|
||||
- **see-also:** [[Scale Ceiling]]
|
||||
- **see-also:** [[Workflow Extraction]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,13 @@ concept_type: pattern
|
||||
tags: []
|
||||
created: 2026-08-02
|
||||
modified: 2026-08-29
|
||||
related: [Confidence Scoring, Event-Driven Automation, Multi-Agent Collaboration, Quality and Self-Correction, Source - LLM Wiki v2, Supersession]
|
||||
related:
|
||||
- rests-on: Confidence Scoring
|
||||
- see-also: Event-Driven Automation
|
||||
- see-also: Multi-Agent Collaboration
|
||||
- part-of: Quality and Self-Correction
|
||||
- evidenced-by: Source - LLM Wiki v2
|
||||
- enables: Supersession
|
||||
sources: []
|
||||
confidence: 0.50
|
||||
confidence_base: 0.50
|
||||
@@ -38,3 +44,14 @@ TODO
|
||||
## Verwandte Konzepte
|
||||
|
||||
- TODO
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **rests-on:** [[Confidence Scoring]]
|
||||
- **see-also:** [[Event-Driven Automation]]
|
||||
- **see-also:** [[Multi-Agent Collaboration]]
|
||||
- **part-of:** [[Quality and Self-Correction]]
|
||||
- **evidenced-by:** [[Source - LLM Wiki v2]]
|
||||
- **enables:** [[Supersession]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,11 @@ concept_type: architecture
|
||||
tags: [skills, agents, cross-platform]
|
||||
created: 2026-08-04
|
||||
modified: 2026-09-01
|
||||
related: []
|
||||
related:
|
||||
- rests-on: Context Isolation
|
||||
- rests-on: Token Economics
|
||||
- see-also: Scale Ceiling
|
||||
- see-also: Workflow Extraction
|
||||
sources: [Source - Copilot Skill Restructure Instructions, Source - Conversation - AGENTS.md Skill Restructuring Session 2026-08-04]
|
||||
confidence: 0.90
|
||||
confidence_base: 0.90
|
||||
@@ -66,13 +70,6 @@ Dieses Muster vermeiden, wenn:
|
||||
- Workflows so eng gekoppelt sind, dass sie nicht sauber unterteilt werden können
|
||||
- der Overhead für die Verwaltung der Skill-Struktur die Vorteile überwiegt
|
||||
|
||||
## Verwandte Konzepte
|
||||
|
||||
- [[Token Economics]]
|
||||
- [[Scale Ceiling]]
|
||||
- [[Context Isolation]]
|
||||
- [[Workflow Extraction]]
|
||||
|
||||
## Siehe auch
|
||||
|
||||
- [[Source - Copilot Skill Restructure Instructions]]
|
||||
@@ -82,3 +79,12 @@ Dieses Muster vermeiden, wenn:
|
||||
|
||||
[^s-copilot-skill-restructure-instructions]: [[Source - Copilot Skill Restructure Instructions]]
|
||||
[^s-conversation-agents-md-skill-restructuring-session-2026-08-04]: [[Source - Conversation - AGENTS.md Skill Restructuring Session 2026-08-04]]
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **rests-on:** [[Context Isolation]]
|
||||
- **rests-on:** [[Token Economics]]
|
||||
- **see-also:** [[Scale Ceiling]]
|
||||
- **see-also:** [[Workflow Extraction]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,10 @@ concept_type: workflow
|
||||
tags: [crystallization, knowledge, distillation, workflow]
|
||||
created: 2026-07-26
|
||||
modified: 2026-08-29
|
||||
related: [LLM Wiki Pattern, Memory Lifecycle, Event-Driven Automation]
|
||||
related:
|
||||
- exemplifies: LLM Wiki Pattern
|
||||
- part-of: Memory Lifecycle
|
||||
- rests-on: Event-Driven Automation
|
||||
sources: [Source - LLM Wiki v2]
|
||||
confidence: 0.85
|
||||
confidence_base: 0.85
|
||||
@@ -138,9 +141,6 @@ Mit [[Event-Driven Automation]] integrieren:
|
||||
|
||||
## Verwandte Konzepte
|
||||
|
||||
- [[LLM Wiki Pattern]] - Gesamtmuster
|
||||
- [[Memory Lifecycle]] - Wie kristallisiertes Wissen verwaltet wird
|
||||
- [[Event-Driven Automation]] - Für automatische Crystallization
|
||||
- [[Consolidation Tiers]] - Wo kristallisiertes Wissen befördert wird
|
||||
- [[Knowledge Compounding]] - Der Gesamteffekt
|
||||
|
||||
@@ -148,3 +148,11 @@ Mit [[Event-Driven Automation]] integrieren:
|
||||
|
||||
- [[Implementation Spectrum]] (Crystallization als erweiterte Funktion)
|
||||
- [[Quality and Self-Correction]] (Sicherung der Qualität kristallisierten Inhalts)
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **exemplifies:** [[LLM Wiki Pattern]]
|
||||
- **part-of:** [[Memory Lifecycle]]
|
||||
- **rests-on:** [[Event-Driven Automation]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,9 +4,10 @@ concept_type: decision
|
||||
tags: []
|
||||
created: 2026-09-01
|
||||
modified: 2026-09-01
|
||||
related: [Chemenu]
|
||||
related:
|
||||
- operates-on: Chemenu
|
||||
sources: ['Source - Public Release, Corpus Purge and History Squash Session 2026-09-01', Source - Private-Instance Merge Correction and Issue 30 Session 2026-09-01]
|
||||
confidence: 0.90
|
||||
confidence: 0.70
|
||||
confidence_base: 0.70
|
||||
provenance: sourced
|
||||
summary: 'Private Korpusinhalte per Loeschung entfernen statt zu anonymisieren: ein Seitentitel ist der einzige Identifier eines Wikis, Umbenennen ist die volle page-lifecycle-Prozedur je Seite, Loeschen ist ein unterstuetztes Kommando.'
|
||||
@@ -63,11 +64,13 @@ sonst unverändertem Inhalt) vorzuziehen - wenn ein unterstütztes Löschkommand
|
||||
|
||||
## Beziehungen
|
||||
|
||||
- **gilt fuer:** [[Chemenu]]
|
||||
|
||||
## Siehe auch
|
||||
|
||||
- [[Source - Public Release, Corpus Purge and History Squash Session 2026-09-01]]
|
||||
- [[Chemenu]]
|
||||
- [[Source - Private-Instance Merge Correction and Issue 30 Session 2026-09-01]]
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **operates-on:** [[Chemenu]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,10 @@ concept_type: decision
|
||||
tags: [schema, tooling, cli, design-rule]
|
||||
created: 2026-08-31
|
||||
modified: 2026-08-31
|
||||
related: [wikitool, Write-Once Frontmatter Fields, AGENTS.md, Green Suite Blind Spot]
|
||||
related:
|
||||
- mechanism: wikitool
|
||||
- grounds: Write-Once Frontmatter Fields
|
||||
- see-also: Green Suite Blind Spot
|
||||
sources: [Source - Conversation - Write-Once Frontmatter Fields and touch --set Session 2026-08-31, Source - Conversation - Two Round-Trip Defects Found by an Ingest Session 2026-08-31]
|
||||
confidence: 0.70
|
||||
confidence_base: 0.70
|
||||
@@ -83,21 +86,20 @@ Angenommen (2026-08-31) mit Stack-Version `1.4.0`, Commit
|
||||
|
||||
## Beziehungen
|
||||
|
||||
- **umgesetzt in:** [[wikitool]]
|
||||
- **begründet die Lösung von:** [[Write-Once Frontmatter Fields]]
|
||||
- **beruft sich auf:** [[AGENTS.md]]
|
||||
- **verwandt mit:** [[Green Suite Blind Spot]]
|
||||
|
||||
## Siehe auch
|
||||
|
||||
- [[wikitool]]
|
||||
- [[Write-Once Frontmatter Fields]]
|
||||
- [[AGENTS.md]]
|
||||
- [[Source - Conversation - Write-Once Frontmatter Fields and touch --set Session 2026-08-31]]
|
||||
- [[Source - Conversation - Two Round-Trip Defects Found by an Ingest Session 2026-08-31]]
|
||||
- [[Green Suite Blind Spot]]
|
||||
|
||||
## Fußnoten
|
||||
|
||||
[^s-conversation-write-once-frontmatter-fields-and-touch-set-session-2026-08-31]: [[Source - Conversation - Write-Once Frontmatter Fields and touch --set Session 2026-08-31]]
|
||||
[^s-conversation-two-round-trip-defects-found-by-an-ingest-session-2026-08-31]: [[Source - Conversation - Two Round-Trip Defects Found by an Ingest Session 2026-08-31]]
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **mechanism:** [[wikitool]]
|
||||
- **grounds:** [[Write-Once Frontmatter Fields]]
|
||||
- **see-also:** [[Green Suite Blind Spot]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,13 @@ concept_type: problem
|
||||
tags: [tooling, lint, provenance, hand-edit, gap]
|
||||
created: 2026-08-31
|
||||
modified: 2026-08-31
|
||||
related: [wikitool, Lint Workflow, Self-Healing, Issue Label Scheme, Write-Once Frontmatter Fields, Command Round-Trip Integrity]
|
||||
related:
|
||||
- exemplifies: wikitool
|
||||
- rests-on: Lint Workflow
|
||||
- contrasts: Self-Healing
|
||||
- see-also: Issue Label Scheme
|
||||
- contrasts: Write-Once Frontmatter Fields
|
||||
- contrasts: Command Round-Trip Integrity
|
||||
sources: [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 - Two Round-Trip Defects Found by an Ingest Session 2026-08-31]
|
||||
confidence: 0.50
|
||||
confidence_base: 0.50
|
||||
@@ -102,34 +108,27 @@ auftritt.
|
||||
- Als Begründung, einen Check wegzulassen, bis die Reparatur fertig ist. Ein gemeldeter Defekt
|
||||
ohne Reparatur ist immer noch besser als ein unbemerkter.
|
||||
|
||||
## Verwandte Concepts
|
||||
|
||||
- [[Self-Healing]]
|
||||
- [[Lint Workflow]]
|
||||
|
||||
## Beziehungen
|
||||
|
||||
- **abgegrenzt gegen:** [[Write-Once Frontmatter Fields]]
|
||||
- **tritt auf in:** [[wikitool]]
|
||||
- **wird sichtbar durch:** [[Lint Workflow]]
|
||||
- **abgegrenzt gegen:** [[Self-Healing]]
|
||||
- **verwandt mit:** [[Issue Label Scheme]]
|
||||
- **abgegrenzt gegen:** [[Command Round-Trip Integrity]]
|
||||
|
||||
## Siehe auch
|
||||
|
||||
- [[Write-Once Frontmatter Fields]]
|
||||
- [[wikitool]]
|
||||
- [[Lint Workflow]]
|
||||
- [[Self-Healing]]
|
||||
- [[Issue Label Scheme]]
|
||||
- [[Source - Conversation - Write-Once Frontmatter Fields and touch --set Session 2026-08-31]]
|
||||
- [[Source - Conversation - Issue Triage Labels and TODO Retirement Session 2026-08-31]]
|
||||
- [[Source - Conversation - Two Round-Trip Defects Found by an Ingest Session 2026-08-31]]
|
||||
- [[Command Round-Trip Integrity]]
|
||||
|
||||
## Fußnoten
|
||||
|
||||
[^s-conversation-comma-bug-budget-refund-and-lint-report-path-session-2026-08-31]: [[Source - Conversation - Comma Bug Budget Refund and Lint Report Path Session 2026-08-31]]
|
||||
[^s-conversation-write-once-frontmatter-fields-and-touch-set-session-2026-08-31]: [[Source - Conversation - Write-Once Frontmatter Fields and touch --set Session 2026-08-31]]
|
||||
[^s-conversation-two-round-trip-defects-found-by-an-ingest-session-2026-08-31]: [[Source - Conversation - Two Round-Trip Defects Found by an Ingest Session 2026-08-31]]
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **exemplifies:** [[wikitool]]
|
||||
- **rests-on:** [[Lint Workflow]]
|
||||
- **contrasts:** [[Self-Healing]]
|
||||
- **see-also:** [[Issue Label Scheme]]
|
||||
- **contrasts:** [[Write-Once Frontmatter Fields]]
|
||||
- **contrasts:** [[Command Round-Trip Integrity]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,10 @@ concept_type: decision
|
||||
tags: [agent-workflow, context-engineering, tooling]
|
||||
created: 2026-08-31
|
||||
modified: 2026-08-31
|
||||
related: [Claude Code Auto Mode, Claude Code, Write-Once Frontmatter Fields]
|
||||
related:
|
||||
- see-also: Claude Code Auto Mode
|
||||
- operates-on: Claude Code
|
||||
- derived-from: Write-Once Frontmatter Fields
|
||||
sources: [Source - Conversation - Auto Mode and Tool Choice Session 2026-08-31]
|
||||
confidence: 0.70
|
||||
confidence_base: 0.70
|
||||
@@ -75,17 +78,18 @@ Angenommen (2026-08-31), auf Anweisung des Nutzers, für Sitzungen an diesem Rep
|
||||
|
||||
## Beziehungen
|
||||
|
||||
- **korrigiert:** [[Claude Code Auto Mode]]
|
||||
- **gilt für:** [[Claude Code]]
|
||||
- **war betroffen von:** [[Write-Once Frontmatter Fields]]
|
||||
|
||||
## Siehe auch
|
||||
|
||||
- [[Claude Code Auto Mode]]
|
||||
- [[Claude Code]]
|
||||
- [[Source - Conversation - Auto Mode and Tool Choice Session 2026-08-31]]
|
||||
- [[Write-Once Frontmatter Fields]]
|
||||
|
||||
## Fußnoten
|
||||
|
||||
[^s-conversation-auto-mode-and-tool-choice-session-2026-08-31]: [[Source - Conversation - Auto Mode and Tool Choice Session 2026-08-31]]
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **see-also:** [[Claude Code Auto Mode]]
|
||||
- **operates-on:** [[Claude Code]]
|
||||
- **derived-from:** [[Write-Once Frontmatter Fields]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,9 +4,10 @@ concept_type: decision
|
||||
tags: []
|
||||
created: 2026-09-01
|
||||
modified: 2026-09-01
|
||||
related: [Chemenu]
|
||||
related:
|
||||
- operates-on: Chemenu
|
||||
sources: ['Source - Public Release, Corpus Purge and History Squash Session 2026-09-01']
|
||||
confidence: 0.50
|
||||
confidence: 0.70
|
||||
confidence_base: 0.70
|
||||
provenance: sourced
|
||||
summary: Ein Repo mit Code- und Inhaltsanteil erhaelt zwei Lizenzen; die Grenze zwischen ihnen ist kein zweiter, gepflegter Pfadkatalog, sondern der ohnehin vorhandene Dateiplan des Distributionswerkzeugs.
|
||||
@@ -56,16 +57,14 @@ Distributions-/Build-Werkzeug ohnehin pflegt.
|
||||
separate, maschinell nachvollziehbare Grenze existiert - dort wäre die Lizenz-Zuordnung selbst
|
||||
wieder eine unabhängige, drift-anfällige Liste.
|
||||
|
||||
## Verwandte Concepts
|
||||
|
||||
- [[Chemenu]]
|
||||
|
||||
## Beziehungen
|
||||
|
||||
- **gilt fuer:** [[Chemenu]]
|
||||
|
||||
## Siehe auch
|
||||
|
||||
- [[Source - Public Release, Corpus Purge and History Squash Session 2026-09-01]]
|
||||
- [[Chemenu]]
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **operates-on:** [[Chemenu]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,10 @@ concept_type: pattern
|
||||
tags: []
|
||||
created: 2026-08-02
|
||||
modified: 2026-08-29
|
||||
related: [Implementation Spectrum, Knowledge Graph, Source - LLM Wiki v2]
|
||||
related:
|
||||
- exemplifies: Implementation Spectrum
|
||||
- enables: Knowledge Graph
|
||||
- evidenced-by: Source - LLM Wiki v2
|
||||
sources: []
|
||||
confidence: 0.50
|
||||
confidence_base: 0.50
|
||||
@@ -37,4 +40,10 @@ TODO
|
||||
|
||||
## Verwandte Concepts
|
||||
|
||||
- TODO
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **exemplifies:** [[Implementation Spectrum]]
|
||||
- **enables:** [[Knowledge Graph]]
|
||||
- **evidenced-by:** [[Source - LLM Wiki v2]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,8 @@ concept_type: architecture
|
||||
tags: []
|
||||
created: 2026-08-02
|
||||
modified: 2026-08-29
|
||||
related: [Consolidation Tiers]
|
||||
related:
|
||||
- see-also: Consolidation Tiers
|
||||
sources: []
|
||||
confidence: 0.50
|
||||
confidence_base: 0.50
|
||||
@@ -37,4 +38,8 @@ TODO
|
||||
|
||||
## Verwandte Concepts
|
||||
|
||||
- TODO
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **see-also:** [[Consolidation Tiers]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,10 @@ concept_type: workflow
|
||||
tags: [automation, hooks, events, workflow]
|
||||
created: 2026-07-26
|
||||
modified: 2026-08-29
|
||||
related: [LLM Wiki Pattern, Memory Lifecycle, Hooks]
|
||||
related:
|
||||
- exemplifies: LLM Wiki Pattern
|
||||
- enables: Memory Lifecycle
|
||||
- rests-on: Hooks
|
||||
sources: [Source - LLM Wiki v2]
|
||||
confidence: 0.95
|
||||
confidence_base: 0.95
|
||||
@@ -169,9 +172,6 @@ Mit **Stufe 2 (Basis)** beginnen und Ereignisse nach Bedarf hinzufügen:
|
||||
|
||||
## Verwandte Concepts
|
||||
|
||||
- [[LLM Wiki Pattern]] - Gesamtmuster
|
||||
- [[Memory Lifecycle]] - Was Automatisierung verwaltet
|
||||
- [[Hooks]] - Der Implementierungsmechanismus
|
||||
- [[Agent Memory]] - Produktionsimplementierung
|
||||
- [[Quality and Self-Correction]] - Ergänzende Qualitätsmechanismen
|
||||
|
||||
@@ -183,3 +183,11 @@ Mit **Stufe 2 (Basis)** beginnen und Ereignisse nach Bedarf hinzufügen:
|
||||
- [[Forgetting]] (angewandt durch Automatisierung)
|
||||
- [[Hybrid Search]] (verwendet in Query-Automatisierung)
|
||||
- [[Contradiction Resolution]] (ausgelöst durch Automatisierung)
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **exemplifies:** [[LLM Wiki Pattern]]
|
||||
- **enables:** [[Memory Lifecycle]]
|
||||
- **rests-on:** [[Hooks]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,9 @@ concept_type: pattern
|
||||
tags: []
|
||||
created: 2026-08-02
|
||||
modified: 2026-08-29
|
||||
related: [Implementation Spectrum, Privacy and Governance]
|
||||
related:
|
||||
- exemplifies: Implementation Spectrum
|
||||
- part-of: Privacy and Governance
|
||||
sources: []
|
||||
confidence: 0.50
|
||||
confidence_base: 0.50
|
||||
@@ -37,4 +39,9 @@ TODO
|
||||
|
||||
## Verwandte Concepts
|
||||
|
||||
- TODO
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **exemplifies:** [[Implementation Spectrum]]
|
||||
- **part-of:** [[Privacy and Governance]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,10 @@ concept_type: pattern
|
||||
tags: [memory, retention, decay, ebbinghaus]
|
||||
created: 2026-07-26
|
||||
modified: 2026-08-29
|
||||
related: [Memory Lifecycle, Confidence Scoring, Consolidation Tiers]
|
||||
related:
|
||||
- part-of: Memory Lifecycle
|
||||
- see-also: Confidence Scoring
|
||||
- rests-on: Consolidation Tiers
|
||||
sources: [Source - LLM Wiki v2]
|
||||
confidence: 0.90
|
||||
confidence_base: 0.90
|
||||
@@ -149,9 +152,6 @@ Fakten mit niedrigerer Priorität:
|
||||
|
||||
## Verwandte Concepts
|
||||
|
||||
- [[Memory Lifecycle]] - Übergeordnetes Concept
|
||||
- [[Confidence Scoring]] - Ergänzender Zuverlässigkeitsmechanismus
|
||||
- [[Consolidation Tiers]] - Tier-spezifische Verfallsraten
|
||||
- [[Supersession]] - Umgang mit veralteten Informationen
|
||||
- [[LLM Wiki Pattern]] - Gesamtmuster
|
||||
|
||||
@@ -159,3 +159,11 @@ Fakten mit niedrigerer Priorität:
|
||||
|
||||
- [[Event-Driven Automation]] (für automatisiertes Verstärkungstracking)
|
||||
- [[Quality and Self-Correction]] (für verwandte Qualitätsmechanismen)
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **part-of:** [[Memory Lifecycle]]
|
||||
- **see-also:** [[Confidence Scoring]]
|
||||
- **rests-on:** [[Consolidation Tiers]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,11 @@ concept_type: pattern
|
||||
tags: []
|
||||
created: 2026-08-02
|
||||
modified: 2026-08-29
|
||||
related: [Hybrid Search, Knowledge Graph, LLM Wiki Pattern, Source - LLM Wiki v2]
|
||||
related:
|
||||
- part-of: Hybrid Search
|
||||
- rests-on: Knowledge Graph
|
||||
- exemplifies: LLM Wiki Pattern
|
||||
- evidenced-by: Source - LLM Wiki v2
|
||||
sources: []
|
||||
confidence: 0.50
|
||||
confidence_base: 0.50
|
||||
@@ -37,4 +41,11 @@ TODO
|
||||
|
||||
## Verwandte Concepts
|
||||
|
||||
- TODO
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **part-of:** [[Hybrid Search]]
|
||||
- **rests-on:** [[Knowledge Graph]]
|
||||
- **exemplifies:** [[LLM Wiki Pattern]]
|
||||
- **evidenced-by:** [[Source - LLM Wiki v2]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,12 @@ concept_type: problem
|
||||
tags: [tests, regression, tooling, quality]
|
||||
created: 2026-08-31
|
||||
modified: 2026-08-31
|
||||
related: [Command Round-Trip Integrity, wikitool, Denylist over Allowlist, Ambient Environment Dependency, Lint Workflow]
|
||||
related:
|
||||
- see-also: Command Round-Trip Integrity
|
||||
- exemplifies: wikitool
|
||||
- see-also: Denylist over Allowlist
|
||||
- see-also: Ambient Environment Dependency
|
||||
- rests-on: Lint Workflow
|
||||
sources: [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]
|
||||
confidence: 0.70
|
||||
confidence_base: 0.70
|
||||
@@ -110,30 +115,26 @@ widersprechen: jede für sich ist getestet, das Zusammenspiel hat nie jemand auf
|
||||
|
||||
## Verwandte Concepts
|
||||
|
||||
- [[Command Round-Trip Integrity]]
|
||||
- [[Denylist over Allowlist]]
|
||||
- [[Ambient Environment Dependency]]
|
||||
- [[Structural Enforcement over Documented Rule]]
|
||||
|
||||
## Beziehungen
|
||||
|
||||
- **begünstigt:** [[Command Round-Trip Integrity]]
|
||||
- **trat auf in:** [[wikitool]]
|
||||
- **belegt an:** [[Denylist over Allowlist]]
|
||||
- **abzugrenzen von:** [[Ambient Environment Dependency]]
|
||||
- **belegt an:** [[Lint Workflow]]
|
||||
|
||||
## Siehe auch
|
||||
|
||||
- [[Source - Conversation - Two Round-Trip Defects Found by an Ingest Session 2026-08-31]]
|
||||
- [[Command Round-Trip Integrity]]
|
||||
- [[wikitool]]
|
||||
- [[Denylist over Allowlist]]
|
||||
- [[Source - Conversation - Hardening the Test Suite Against Silent Environment Dependencies Session 2026-08-31]]
|
||||
- [[Ambient Environment Dependency]]
|
||||
- [[Lint Workflow]]
|
||||
|
||||
## Fußnoten
|
||||
|
||||
[^s-conversation-two-round-trip-defects-found-by-an-ingest-session-2026-08-31]: [[Source - Conversation - Two Round-Trip Defects Found by an Ingest Session 2026-08-31]]
|
||||
[^s-conversation-hardening-the-test-suite-against-silent-environment-dependencies-session-2026-08-31]: [[Source - Conversation - Hardening the Test Suite Against Silent Environment Dependencies Session 2026-08-31]]
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **see-also:** [[Command Round-Trip Integrity]]
|
||||
- **exemplifies:** [[wikitool]]
|
||||
- **see-also:** [[Denylist over Allowlist]]
|
||||
- **see-also:** [[Ambient Environment Dependency]]
|
||||
- **rests-on:** [[Lint Workflow]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
+10
-3
@@ -4,7 +4,9 @@ concept_type: workflow
|
||||
tags: [automation, events, triggers, workflow]
|
||||
created: 2026-07-26
|
||||
modified: 2026-08-29
|
||||
related: [Event-Driven Automation, LLM Wiki Pattern]
|
||||
related:
|
||||
- grounds: Event-Driven Automation
|
||||
- exemplifies: LLM Wiki Pattern
|
||||
sources: [Source - LLM Wiki v2]
|
||||
confidence: 0.85
|
||||
confidence_base: 0.85
|
||||
@@ -129,8 +131,6 @@ Hooks sollten **robust** sein:
|
||||
|
||||
## Verwandte Concepts
|
||||
|
||||
- [[Event-Driven Automation]] - Das Gesamtautomatisierungs-Framework
|
||||
- [[LLM Wiki Pattern]] - Das übergeordnete Muster
|
||||
- [[Memory Lifecycle]] - Was Hooks helfen zu verwalten
|
||||
- [[Quality and Self-Correction]] - Qualitätsbezogene Hooks
|
||||
|
||||
@@ -140,3 +140,10 @@ Hooks sollten **robust** sein:
|
||||
- [[Consolidation Tiers]] (hochgestuft durch Hooks)
|
||||
- [[Forgetting]] (angewandt durch Hooks)
|
||||
- [[Confidence Scoring]] (aktualisiert durch Hooks)
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **grounds:** [[Event-Driven Automation]]
|
||||
- **exemplifies:** [[LLM Wiki Pattern]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,13 @@ concept_type: architecture
|
||||
tags: [search, bm25, vector, graph, scalability]
|
||||
created: 2026-07-26
|
||||
modified: 2026-08-29
|
||||
related: [LLM Wiki Pattern, BM25, Vector Search, Reciprocal Rank Fusion, Knowledge Graph, Graph Traversal]
|
||||
related:
|
||||
- exemplifies: LLM Wiki Pattern
|
||||
- see-also: BM25
|
||||
- composition: Vector Search
|
||||
- composition: Reciprocal Rank Fusion
|
||||
- rests-on: Knowledge Graph
|
||||
- see-also: Graph Traversal
|
||||
sources: [Source - LLM Wiki v2]
|
||||
confidence: 0.90
|
||||
confidence_base: 0.90
|
||||
@@ -115,15 +121,20 @@ Abfrage: "Wie funktioniert das Auth-System?"
|
||||
|
||||
## Verwandte Concepts
|
||||
|
||||
- [[LLM Wiki Pattern]] - Gesamtmuster
|
||||
- [[BM25]] - Schlüsselwortabgleich-Komponente
|
||||
- [[Vector Search]] - Semantische Ähnlichkeits-Komponente
|
||||
- [[Reciprocal Rank Fusion]] - Fusionsalgorithmus
|
||||
- [[Knowledge Graph]] - Graph-Traversal-Komponente
|
||||
- [[Graph Traversal]] - Der Graph-Suchmechanismus
|
||||
- [[Agent Memory]] - Produktionsimplementierung
|
||||
|
||||
## Siehe auch
|
||||
|
||||
- [[Event-Driven Automation]] (für automatisierte Indizierung)
|
||||
- Scalable Search (verwandtes Concept)
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **exemplifies:** [[LLM Wiki Pattern]]
|
||||
- **see-also:** [[BM25]]
|
||||
- **composition:** [[Vector Search]]
|
||||
- **composition:** [[Reciprocal Rank Fusion]]
|
||||
- **rests-on:** [[Knowledge Graph]]
|
||||
- **see-also:** [[Graph Traversal]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
# kb/concepts/ - Index
|
||||
|
||||
79 page(s). Regenerated by `wikitool index rebuild`.
|
||||
80 page(s). Regenerated by `wikitool index rebuild`.
|
||||
|
||||
## All
|
||||
|
||||
@@ -42,14 +42,15 @@
|
||||
| [[Implementation Spectrum]] | architecture | Modularer Einführungspfad für die Funktionen von LLM Wiki v2, vom minimal tragfähigen Wiki bis zur vollen Umsetzung mit Automatisierung und Governance. | 2026-08-29 |
|
||||
| [[Index Scaling]] | workflow | Skalierungsregeln für Indexseiten: Tabellenabschnitte ab 50 Einträgen teilen, ab 200 Seiten _meta/topic-map.md anlegen | 2026-08-29 |
|
||||
| [[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 bei abgelehntem Aufruf und ein seit 1.5.0 gemessenes Kalibrierungsband von 5-15 (einfach) bzw. 20-35 (komplex) Aufrufen | 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 |
|
||||
| [[LLM Wiki Pattern]] | architecture | Methodik für persönliches Wissensmanagement, bei der ein LLM aus Rohquellen ein dauerhaftes Wiki aufbaut - Wissen wird kompiliert statt per RAG neu hergeleitet. | 2026-08-29 |
|
||||
| [[Mass-Update Gate]] | workflow | Mass-Update Gate: publish endet mit 42 (Freigabe durch den Menschen noetig) ab 10 gezaehlten Dateien; generierte Dateien und work/ werden committet\, aber seit 1.5.0 nicht gezaehlt; freigegeben per --confirm <token> | 2026-09-01 |
|
||||
| [[MCP-Leseserver]] | architecture | Zweiter Konsument von chemenu ueber MCP: search/types/describe_type/lint/status auf chemenu.api.Corpus, strukturell ohne Schreibpfad, jede Antwort trage einen Commit-Stempel. | 2026-09-02 |
|
||||
| [[Memory Lifecycle]] | architecture | Architektur des Wissenslebenszyklus mit Confidence Scoring, Supersession, Forgetting und Consolidation Tiers zur Pflege von Fakten über die Zeit. | 2026-08-29 |
|
||||
| [[Mesh Sync]] | pattern | Abgleichsmechanismus, der Beobachtungen paralleler Agenten in ein gemeinsames Wiki überführt; Last-Write-Wins mit Konflikterkennung und manuellem Eingriff. | 2026-08-29 |
|
||||
| [[Modbus]] | protocol | Industrielles Kommunikationsprotokoll von 1979 zur Anbindung speicherprogrammierbarer Steuerungen und Geräte über serielle oder TCP-Netze. | 2026-08-29 |
|
||||
@@ -60,7 +61,7 @@
|
||||
| [[Personalization Plane]] | architecture | Schicht fuer Instanz-Identitaet: USER.md/SOUL.md werden als Template ausgeliefert, im Setup-Interview woertlich befuellt und vom doctor-Check auf fehlend wie unbefuellt geprueft | 2026-08-31 |
|
||||
| [[Privacy and Governance]] | workflow | Rahmenwerk zur Absicherung von Wiki-Inhalten über Datenfilterung beim Ingest, Audit-Trail-Protokollierung und umkehrbare Massenoperationen. | 2026-08-29 |
|
||||
| [[Procedural Memory]] | architecture | Langlebigste Speicherschicht für Abläufe, Muster, bewährte Vorgehensweisen und Rezepte, gewonnen aus wiederholten semantischen Beobachtungen. | 2026-08-29 |
|
||||
| [[Publish-Remote Gate]] | workflow | Drittes, im Code durchgesetztes Gate: publish bricht mit Exit 42 ab, wenn die aufgeloeste Push-URL nicht in einer optionalen, gitignoreten Allowlist steht; anders als die anderen Gates gibt es keinen Freigabe-Token. | 2026-09-01 |
|
||||
| [[Publish-Remote Gate]] | workflow | Drittes, im Code durchgesetztes Gate: publish bricht mit Exit 42 ab, wenn die aufgeloeste Push-URL nicht in einer optionalen, gitignoreten Allowlist steht; doctor benennt seit 2026-09-02 den Gate-Zustand statt nur die Dateiexistenz | 2026-09-02 |
|
||||
| [[Quality and Self-Correction]] | workflow | Automatische Qualitätssicherung für Wikis mit Inhaltsbewertung, Selbstheilung und Widerspruchserkennung. | 2026-08-29 |
|
||||
| [[Quality Scoring]] | pattern | Quantitative Bewertung aller vom LLM geschriebenen Inhalte nach struktureller Qualität, Vollständigkeit der Quellenangaben, Konsistenz mit dem Wiki und Themenabdeckung. | 2026-08-29 |
|
||||
| [[RAG]] | architecture | Architekturmuster, bei dem LLMs die Generierung um Dokumente aus einer Wissensbasis anreichern. | 2026-08-29 |
|
||||
|
||||
@@ -4,7 +4,14 @@ concept_type: architecture
|
||||
tags: [implementation, modular, levels, adoption]
|
||||
created: 2026-07-26
|
||||
modified: 2026-08-29
|
||||
related: [LLM Wiki Pattern, Memory Lifecycle, Knowledge Graph, Event-Driven Automation, Multi-Agent Collaboration, Privacy and Governance, Crystallization]
|
||||
related:
|
||||
- rests-on: LLM Wiki Pattern
|
||||
- composition: Memory Lifecycle
|
||||
- composition: Knowledge Graph
|
||||
- composition: Event-Driven Automation
|
||||
- composition: Multi-Agent Collaboration
|
||||
- composition: Privacy and Governance
|
||||
- composition: Crystallization
|
||||
sources: [Source - LLM Wiki v2]
|
||||
confidence: 0.90
|
||||
confidence_base: 0.90
|
||||
@@ -224,16 +231,21 @@ Level 0 → Level 1 → Level 2 → Level 3 → Level 4 → Level 5 → Level 6
|
||||
|
||||
## Verwandte Concepts
|
||||
|
||||
- [[LLM Wiki Pattern]] - Gesamtmuster
|
||||
- [[Memory Lifecycle]] - Level-1-Erweiterung
|
||||
- [[Knowledge Graph]] - Level-2-Erweiterung
|
||||
- [[Event-Driven Automation]] - Level-3-Erweiterung
|
||||
- [[Hybrid Search]] - Level-4-Erweiterung
|
||||
- [[Multi-Agent Collaboration]] - Level-5-Erweiterung
|
||||
- [[Privacy and Governance]] - Level-6-Erweiterung
|
||||
- [[Crystallization]] - Level-7-Erweiterung
|
||||
|
||||
## Siehe auch
|
||||
|
||||
- [[Three-Layer Architecture]] (Grundlage für alle Ebenen)
|
||||
- [[Agent Memory]] (Implementierung höherer Ebenen)
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **rests-on:** [[LLM Wiki Pattern]]
|
||||
- **composition:** [[Memory Lifecycle]]
|
||||
- **composition:** [[Knowledge Graph]]
|
||||
- **composition:** [[Event-Driven Automation]]
|
||||
- **composition:** [[Multi-Agent Collaboration]]
|
||||
- **composition:** [[Privacy and Governance]]
|
||||
- **composition:** [[Crystallization]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,11 @@ concept_type: workflow
|
||||
tags: [index, scaling, thresholds, pages]
|
||||
created: 2026-08-03
|
||||
modified: 2026-08-29
|
||||
related: [Content Quality Control, Split Threshold, pascalandy schema, Iteration and Cost Limits]
|
||||
related:
|
||||
- part-of: Content Quality Control
|
||||
- see-also: Split Threshold
|
||||
- operationalized-from: pascalandy schema
|
||||
- see-also: Iteration and Cost Limits
|
||||
sources: [Source - LLM Improvements Sonnet Analysis, Source - LLM Improvements Production Agent Gaps 2026]
|
||||
confidence: 0.80
|
||||
confidence_base: 0.80
|
||||
@@ -56,21 +60,24 @@ Index Scaling definiert Regeln und Schwellenwerte für den Zeitpunkt und die Art
|
||||
|
||||
## Verwandte Concepts
|
||||
|
||||
- [[Content Quality Control]] - Umfassenderes Qualitätssystem
|
||||
- [[Split Threshold]] - Ähnliches Konzept für einzelne Seiten
|
||||
- [[pascalandy schema]] - Quelle der Skalierungsempfehlungen
|
||||
- [[Three-Layer Architecture]] - Index ist Teil der Wiki-Ebene
|
||||
|
||||
## Beziehungen
|
||||
|
||||
- **geschützt durch:** [[Iteration and Cost Limits]]
|
||||
|
||||
## Siehe auch
|
||||
|
||||
- [[Source - LLM Improvements Sonnet Analysis]]
|
||||
- [[Iteration and Cost Limits]]
|
||||
- [[Source - LLM Improvements Production Agent Gaps 2026]]
|
||||
|
||||
## Fußnoten
|
||||
|
||||
[^s-llm-improvements-sonnet-analysis]: [[Source - LLM Improvements Sonnet Analysis]]
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **part-of:** [[Content Quality Control]]
|
||||
- **see-also:** [[Split Threshold]]
|
||||
- **operationalized-from:** [[pascalandy schema]]
|
||||
- **see-also:** [[Iteration and Cost Limits]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,11 @@ concept_type: decision
|
||||
tags: [issues, gitea, triage, labels, backlog]
|
||||
created: 2026-08-31
|
||||
modified: 2026-08-31
|
||||
related: [Chemenu, Gitea MCP Server, KB Stack Versioning, Detect-Repair Asymmetry]
|
||||
related:
|
||||
- operates-on: Chemenu
|
||||
- mechanism: Gitea MCP Server
|
||||
- see-also: KB Stack Versioning
|
||||
- see-also: Detect-Repair Asymmetry
|
||||
sources: [Source - Conversation - Issue Triage Labels and TODO Retirement Session 2026-08-31]
|
||||
confidence: 0.70
|
||||
confidence_base: 0.70
|
||||
@@ -101,26 +105,21 @@ auf `instructions/` passt und `instructions/dev/` darunter liegt[^s-conversation
|
||||
- Nicht in einer ausgelieferten Instanz. Das Schema beschreibt das Entwicklungs-Repository und
|
||||
hat außerhalb davon keinen Gegenstand.
|
||||
|
||||
## Verwandte Concepts
|
||||
|
||||
- [[KB Stack Versioning]]
|
||||
- [[Detect-Repair Asymmetry]]
|
||||
|
||||
## Beziehungen
|
||||
|
||||
- **gilt für:** [[Chemenu]]
|
||||
- **umgesetzt über:** [[Gitea MCP Server]]
|
||||
- **verwandt mit:** [[KB Stack Versioning]]
|
||||
- **verwandt mit:** [[Detect-Repair Asymmetry]]
|
||||
|
||||
## Siehe auch
|
||||
|
||||
- [[Chemenu]]
|
||||
- [[Gitea MCP Server]]
|
||||
- [[KB Stack Versioning]]
|
||||
- [[Detect-Repair Asymmetry]]
|
||||
- [[Source - Conversation - Issue Triage Labels and TODO Retirement Session 2026-08-31]]
|
||||
|
||||
## Fußnoten
|
||||
|
||||
[^s-conversation-issue-triage-labels-and-todo-retirement-session-2026-08-31]: [[Source - Conversation - Issue Triage Labels and TODO Retirement Session 2026-08-31]]
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **operates-on:** [[Chemenu]]
|
||||
- **mechanism:** [[Gitea MCP Server]]
|
||||
- **see-also:** [[KB Stack Versioning]]
|
||||
- **see-also:** [[Detect-Repair Asymmetry]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -3,13 +3,19 @@ type: types/concept.md
|
||||
concept_type: workflow
|
||||
tags: [gate, safety, iteration-budget, loop-breaker]
|
||||
created: 2026-08-07
|
||||
modified: 2026-08-31
|
||||
related: [Mass-Update Gate, Anti-Cramming Heuristic, Index Scaling, wikitool, Structural Enforcement over Documented Rule]
|
||||
sources: [Source - LLM Improvements Production Agent Gaps 2026, Source - Conversation - Comma Bug Budget Refund and Lint Report Path Session 2026-08-31, Source - Conversation - Gate Counting and Measured Calibration Session 2026-08-31]
|
||||
modified: 2026-09-02
|
||||
related:
|
||||
- compares-with: Mass-Update Gate
|
||||
- see-also: Anti-Cramming Heuristic
|
||||
- see-also: Index Scaling
|
||||
- mechanism: wikitool
|
||||
- exemplifies: Structural Enforcement over Documented Rule
|
||||
- see-also: MCP-Leseserver
|
||||
sources: [Source - LLM Improvements Production Agent Gaps 2026, Source - Conversation - Comma Bug Budget Refund and Lint Report Path Session 2026-08-31, Source - Conversation - Gate Counting and Measured Calibration Session 2026-08-31, Source - MCP Read Server Implementation Session 2026-09-02]
|
||||
confidence: 0.88
|
||||
confidence_base: 0.88
|
||||
provenance: sourced
|
||||
summary: Im Code durchgesetzte Obergrenze von 60 wikitool-Aufrufen je Session\, Loop-Breaker bei 3 identischen Wiederholungen\, Slot-Erstattung bei abgelehntem Aufruf und ein seit 1.5.0 gemessenes Kalibrierungsband von 5-15 (einfach) bzw. 20-35 (komplex) Aufrufen
|
||||
summary: 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
|
||||
---
|
||||
# Iteration and Cost Limits
|
||||
|
||||
@@ -48,34 +54,33 @@ Eine hart in Code durchgesetzte Obergrenze für die Anzahl der Tool-Aufrufe, die
|
||||
|
||||
- Einzelne, begrenzte Einmalvorgänge, bei denen die Aufrufen-Anzahl inhärent festgelegt ist (z. B. ein einzelner `new entity`-Aufruf) - das Gate wird dort immer noch gleichmäßig angewendet, wird aber im Wesentlichen nie ausgelöst.
|
||||
- Als Ersatz für das [[Mass-Update Gate]], das auf den *Schadensradius* eines `publish` (Dateien, die von einem einzelnen Push betroffen sind) begrenzt ist, nicht auf die *Iterationsmenge* über eine Sitzung - die beiden Gates beheben unterschiedliche Ausfallmodi und beide bleiben notwendig.
|
||||
|
||||
## Verwandte Concepts
|
||||
|
||||
- [[Mass-Update Gate]] - das verwandte Sicherheitsgate, das dieses Muster spiegelt, begrenzt auf Veröffentlichungsgröße statt Sitzungsiterationsvolumen
|
||||
- [[Anti-Cramming Heuristic]] - eines der Wiki-Qualitätsprobleme, die ein unbegrenzter Ingest-Lauf sonst verletzen könnte
|
||||
- [[Index Scaling]] - das andere Wiki-Qualitätsproblem, das durch unkontrolliertes Seitenwachstum gefährdet ist
|
||||
- [[wikitool]] - die CLI, die dieses Gate implementiert
|
||||
- Im [[MCP-Leseserver]]. Das Gate begrenzt eine Agenten-Session am unbemerkten Iterieren über den
|
||||
Wiki-Zustand - deshalb ist Retrieval bereits generell ausgenommen (`SKIP_COMMANDS`) -, nicht
|
||||
einen Nutzer, der oft sucht. Ein zu häufig suchender Nutzer ist ein Ressourcenproblem, das vor
|
||||
den Serverprozess gehört (Rate Limiting), nicht in dieses Gate - beide zu vermischen würde es
|
||||
zu einem Rate Limiter verwässern.[^s-mcp-read-server-implementation-session-2026-09-02]
|
||||
|
||||
## Beziehungen
|
||||
|
||||
- **spiegelt das gleiche Muster wie:** [[Mass-Update Gate]]
|
||||
- **schützt:** [[Anti-Cramming Heuristic]]
|
||||
- **schützt:** [[Index Scaling]]
|
||||
- **implementiert durch:** [[wikitool]]
|
||||
- **wendet an:** [[Structural Enforcement over Documented Rule]]
|
||||
|
||||
## Siehe auch
|
||||
|
||||
- [[Mass-Update Gate]]
|
||||
- [[Anti-Cramming Heuristic]]
|
||||
- [[Index Scaling]]
|
||||
- [[wikitool]]
|
||||
- [[Source - LLM Improvements Production Agent Gaps 2026]]
|
||||
- [[Source - Conversation - Gate Counting and Measured Calibration Session 2026-08-31]]
|
||||
- [[Structural Enforcement over Documented Rule]]
|
||||
|
||||
## Fußnoten
|
||||
|
||||
[^s-llm-improvements-production-agent-gaps-2026]: [[Source - LLM Improvements Production Agent Gaps 2026]]
|
||||
[^s-conversation-gate-counting-and-measured-calibration-session-2026-08-31]: [[Source - Conversation - Gate Counting and Measured Calibration Session 2026-08-31]]
|
||||
[^s-conversation-comma-bug-budget-refund-and-lint-report-path-session-2026-08-31]: [[Source - Conversation - Comma Bug Budget Refund and Lint Report Path Session 2026-08-31]]
|
||||
[^s-mcp-read-server-implementation-session-2026-09-02]: [[Source - MCP Read Server Implementation Session 2026-09-02]]
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **compares-with:** [[Mass-Update Gate]]
|
||||
- **see-also:** [[Anti-Cramming Heuristic]]
|
||||
- **see-also:** [[Index Scaling]]
|
||||
- **mechanism:** [[wikitool]]
|
||||
- **exemplifies:** [[Structural Enforcement over Documented Rule]]
|
||||
- **see-also:** [[MCP-Leseserver]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,11 @@ concept_type: workflow
|
||||
tags: [migration, versioning, corpus-diff, workflow]
|
||||
created: 2026-08-30
|
||||
modified: 2026-08-31
|
||||
related: [wikitool]
|
||||
related:
|
||||
- mechanism: wikitool
|
||||
- rests-on: KB Stack Versioning
|
||||
- see-also: Mass-Update Gate
|
||||
- see-also: Iteration and Cost Limits
|
||||
sources: [Source - Conversation - Versioning CI-CD and Content Migration Session 2026-08-30]
|
||||
confidence: 0.70
|
||||
confidence_base: 0.70
|
||||
@@ -116,12 +120,15 @@ verweigert[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-0
|
||||
Werkzeug, weil er selbstprüfend ist: er meldet `FAIL`, bis die Sache erledigt ist, während
|
||||
`migrate done` eine Behauptung ist, die man ohne die Arbeit aufstellen kann.
|
||||
|
||||
## Verwandte Concepts
|
||||
|
||||
- [[KB Stack Versioning]]
|
||||
- [[Mass-Update Gate]]
|
||||
- [[Iteration and Cost Limits]]
|
||||
|
||||
## Fußnoten
|
||||
|
||||
[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30]: [[Source - Conversation - Versioning CI-CD and Content Migration Session 2026-08-30]]
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **mechanism:** [[wikitool]]
|
||||
- **rests-on:** [[KB Stack Versioning]]
|
||||
- **see-also:** [[Mass-Update Gate]]
|
||||
- **see-also:** [[Iteration and Cost Limits]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -3,13 +3,16 @@ type: types/concept.md
|
||||
concept_type: decision
|
||||
tags: [versioning, semver, release, stack]
|
||||
created: 2026-08-30
|
||||
modified: 2026-08-30
|
||||
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]
|
||||
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 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 +45,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 "<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 +76,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
|
||||
|
||||
@@ -90,22 +106,22 @@ kann.
|
||||
- Nicht als automatischer Bump aus Commit-Nachrichten, solange Content-Commits und
|
||||
Stack-Commits im selben Repository liegen.
|
||||
|
||||
## Verwandte Concepts
|
||||
|
||||
- [[KB Migration]]
|
||||
- [[CI Integration]]
|
||||
|
||||
## Beziehungen
|
||||
|
||||
- **umgesetzt von:** [[wikitool]]
|
||||
- **verwandt mit:** [[Issue Label Scheme]]
|
||||
|
||||
## Siehe auch
|
||||
|
||||
- [[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]]
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **mechanism:** [[wikitool]]
|
||||
- **see-also:** [[Issue Label Scheme]]
|
||||
- **see-also:** [[CI Integration]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,10 @@ concept_type: workflow
|
||||
tags: [knowledge-management, growth, learning]
|
||||
created: 2026-07-26
|
||||
modified: 2026-08-29
|
||||
related: [LLM Wiki Pattern, Memex, Tolkien Gateway]
|
||||
related:
|
||||
- part-of: LLM Wiki Pattern
|
||||
- see-also: Memex
|
||||
- see-also: Tolkien Gateway
|
||||
sources: [Source - LLM Wiki Pattern]
|
||||
confidence: 0.90
|
||||
confidence_base: 0.90
|
||||
@@ -118,7 +121,12 @@ Mit LLM Wiki Pattern:
|
||||
|
||||
## Siehe auch
|
||||
|
||||
- [[LLM Wiki Pattern]]
|
||||
- [[Memex]]
|
||||
- [[Tolkien Gateway]]
|
||||
- [[Three-Layer Architecture]]
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **part-of:** [[LLM Wiki Pattern]]
|
||||
- **see-also:** [[Memex]]
|
||||
- **see-also:** [[Tolkien Gateway]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,12 @@ concept_type: architecture
|
||||
tags: [graph, entities, relationships, knowledge-management]
|
||||
created: 2026-07-26
|
||||
modified: 2026-08-29
|
||||
related: [LLM Wiki Pattern, Memory Lifecycle, Entity Extraction, Typed Relationships, Graph Traversal]
|
||||
related:
|
||||
- exemplifies: LLM Wiki Pattern
|
||||
- see-also: Memory Lifecycle
|
||||
- see-also: Entity Extraction
|
||||
- composition: Typed Relationships
|
||||
- see-also: Graph Traversal
|
||||
sources: [Source - LLM Wiki v2]
|
||||
confidence: 0.90
|
||||
confidence_base: 0.90
|
||||
@@ -130,11 +135,6 @@ Basierend auf [[Agent Memory]] und [[iii Engine]]:
|
||||
|
||||
## Verwandte Concepts
|
||||
|
||||
- [[LLM Wiki Pattern]] - Gesamtes Muster
|
||||
- [[Entity Extraction]] - Füllung des Graphen
|
||||
- [[Typed Relationships]] - Die Beziehungstypen
|
||||
- [[Graph Traversal]] - Abfragemechanismus
|
||||
- [[Memory Lifecycle]] - Komplementäres Wissensmanagement
|
||||
- [[Agent Memory]] - Produktionsimplementierung
|
||||
|
||||
## Siehe auch
|
||||
@@ -142,3 +142,13 @@ Basierend auf [[Agent Memory]] und [[iii Engine]]:
|
||||
- [[Hybrid Search]] (nutzt Graph-Traversal als einen Stream)
|
||||
- [[Event-Driven Automation]] (für automatische Graph-Updates)
|
||||
- [[Supersession]] (als Graph-Beziehung verfolgt)
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **exemplifies:** [[LLM Wiki Pattern]]
|
||||
- **see-also:** [[Memory Lifecycle]]
|
||||
- **see-also:** [[Entity Extraction]]
|
||||
- **composition:** [[Typed Relationships]]
|
||||
- **see-also:** [[Graph Traversal]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,13 @@ concept_type: architecture
|
||||
tags: [knowledge-management, llm, wiki, pattern]
|
||||
created: 2026-07-26
|
||||
modified: 2026-08-29
|
||||
related: [Three-Layer Architecture, Knowledge Compounding, RAG, Memex, Vannevar Bush, Memory Lifecycle]
|
||||
related:
|
||||
- rests-on: Three-Layer Architecture
|
||||
- see-also: Knowledge Compounding
|
||||
- contrasts: RAG
|
||||
- see-also: Vannevar Bush
|
||||
- composition: Memory Lifecycle
|
||||
- see-also: Memex
|
||||
sources: [Source - LLM Wiki Pattern, Source - LLM Wiki v2]
|
||||
confidence: 0.95
|
||||
confidence_base: 0.95
|
||||
@@ -201,11 +207,6 @@ Periodische Gesundheitsprüfung zu:
|
||||
|
||||
## Verwandte Concepts
|
||||
|
||||
- [[RAG]]: Der traditionelle Ansatz, den dieses Muster verbessert
|
||||
- [[Knowledge Compounding]]: Die Auswirkung des Aufbaus von Wissen auf sich selbst
|
||||
- [[Three-Layer Architecture]]: Die architektonische Grundlage
|
||||
- [[Memex]]: Vannevar Bushs 1945er Vision, die dieses Muster inspirierte
|
||||
|
||||
## Beispiele
|
||||
|
||||
- **Persönlich**: Ziele, Gesundheit, Psychologie, Selbstverbesserung verfolgen
|
||||
@@ -230,10 +231,15 @@ Periodische Gesundheitsprüfung zu:
|
||||
|
||||
## Siehe auch
|
||||
|
||||
- [[Three-Layer Architecture]]
|
||||
- [[Knowledge Compounding]]
|
||||
- [[RAG]]
|
||||
- [[Memex]]
|
||||
- [[Vannevar Bush]]
|
||||
- [[Obsidian]]
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **rests-on:** [[Three-Layer Architecture]]
|
||||
- **see-also:** [[Knowledge Compounding]]
|
||||
- **contrasts:** [[RAG]]
|
||||
- **see-also:** [[Vannevar Bush]]
|
||||
- **composition:** [[Memory Lifecycle]]
|
||||
- **see-also:** [[Memex]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,11 @@ concept_type: workflow
|
||||
tags: []
|
||||
created: 2026-08-02
|
||||
modified: 2026-09-01
|
||||
related: [Event-Driven Automation, Quality and Self-Correction, Detect-Repair Asymmetry, Green Suite Blind Spot]
|
||||
related:
|
||||
- see-also: Event-Driven Automation
|
||||
- part-of: Quality and Self-Correction
|
||||
- grounds: Detect-Repair Asymmetry
|
||||
- grounds: Green Suite Blind Spot
|
||||
sources: [Source - Conversation - Comma Bug Budget Refund and Lint Report Path Session 2026-08-31]
|
||||
confidence: 0.50
|
||||
confidence_base: 0.50
|
||||
@@ -48,21 +52,22 @@ Läuft nach Zeitplan (täglich/wöchentlich) ab und kann durch Memory-Write-Erei
|
||||
|
||||
## Verwandte Concepts
|
||||
|
||||
- [[Quality and Self-Correction]]
|
||||
- [[Confidence Scoring]]
|
||||
- [[Event-Driven Automation]]
|
||||
- [[LLM Wiki Pattern]]
|
||||
|
||||
## Beziehungen
|
||||
|
||||
- **macht sichtbar:** [[Detect-Repair Asymmetry]]
|
||||
- **abgesichert von:** [[Green Suite Blind Spot]]
|
||||
|
||||
## Siehe auch
|
||||
|
||||
- [[Detect-Repair Asymmetry]]
|
||||
- [[Green Suite Blind Spot]]
|
||||
|
||||
## Fußnoten
|
||||
|
||||
[^s-conversation-comma-bug-budget-refund-and-lint-report-path-session-2026-08-31]: [[Source - Conversation - Comma Bug Budget Refund and Lint Report Path Session 2026-08-31]]
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **see-also:** [[Event-Driven Automation]]
|
||||
- **part-of:** [[Quality and Self-Correction]]
|
||||
- **grounds:** [[Detect-Repair Asymmetry]]
|
||||
- **grounds:** [[Green Suite Blind Spot]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -0,0 +1,105 @@
|
||||
---
|
||||
type: types/concept.md
|
||||
concept_type: architecture
|
||||
tags: [mcp, library-boundary, search, server]
|
||||
created: 2026-09-02
|
||||
modified: 2026-09-02
|
||||
related:
|
||||
- operates-on: wikitool
|
||||
- see-also: Publish-Remote Gate
|
||||
- see-also: Mass-Update Gate
|
||||
- see-also: Iteration and Cost Limits
|
||||
- see-also: Chemenu
|
||||
sources: [Source - MCP Read Server Implementation Session 2026-09-02]
|
||||
confidence: 0.50
|
||||
confidence_base: 0.50
|
||||
provenance: sourced
|
||||
summary: 'Zweiter Konsument von chemenu ueber MCP: search/types/describe_type/lint/status auf chemenu.api.Corpus, strukturell ohne Schreibpfad, jede Antwort trage einen Commit-Stempel.'
|
||||
---
|
||||
# MCP-Leseserver
|
||||
|
||||
**Typ:** Architecture
|
||||
|
||||
## Definition
|
||||
|
||||
Ein zweiter Konsument desselben Kerns, nicht ein zweites Programm: `tools/chemenu/mcp/` exponiert
|
||||
`search`, `types`, `describe_type`, `lint` und `status` über MCP, indem es dieselben Funktionen
|
||||
aufruft, die `wikitool` auch aufruft - vermittelt durch `chemenu.api.Corpus`, den In-Process-
|
||||
Einstiegspunkt. Ein Golden-Test hält die Ausgaben beider Wege gegeneinander, statt darauf zu
|
||||
vertrauen, dass sie übereinstimmen.
|
||||
|
||||
## Kernpunkte
|
||||
|
||||
- **Kein Schreibpfad, strukturell.** Weder der Server noch `chemenu.api` importiert etwas unter
|
||||
`chemenu.commands` - `new`, `touch`, `xref`, `publish`, `migrate` sind aus diesem Prozess
|
||||
heraus nicht erreichbar, statt aus einer Liste gefiltert zu werden. Ein Test importiert das
|
||||
Servermodul in einem frischen Interpreter und prüft
|
||||
`sys.modules`.[^s-mcp-read-server-implementation-session-2026-09-02]
|
||||
- **Zwei Transports.** `stdio` zum Entwickeln und Testen ohne Netz; `streamable-http` für die
|
||||
Auslieferung, der einzige, vor den sich ein HTTP-Reverse-Proxy setzen kann. `sse` ist über das
|
||||
SDK erreichbar und wird bewusst nicht angeboten - der abgelöste Remote-Transport, jetzt darauf
|
||||
zu bauen verschiebt den Wechsel nur.
|
||||
- **Jede Antwort trägt den Commit, aus dem sie berechnet wurde** (`commit`, `as_of`). Ein
|
||||
veralteter Checkout antwortet sonst selbstbewusst falsch. `null` heißt: der bediente Baum hat
|
||||
uncommittete Änderungen, die Antwort entspricht keiner Revision. Der Stempel ist die Revision,
|
||||
aus der die Seiten *tatsächlich* gelesen wurden, nicht die zum Zeitpunkt des Stempelns aktuelle
|
||||
- ein Bug, der genau diesen Unterschied überging, wurde beim Schreiben des Golden-Tests selbst
|
||||
gefunden und behoben.[^s-mcp-read-server-implementation-session-2026-09-02]
|
||||
- **Telemetrie in den bedienten Baum wird beim Start verweigert**, nicht still umgeleitet. Der
|
||||
Sync, der den Checkout aktuell hält (`git fetch && git reset --hard`), darf `reports/telemetry/`
|
||||
wegräumen; ein Trace, der dort landet, wäre ein Verlust und eine stille Möglichkeit, den Baum
|
||||
zu beschmutzen, dessen Sauberkeit der Korpus-Cache prüft.
|
||||
- **Kein Iteration Budget Gate im Server.** Das Gate begrenzt eine Agenten-Session am unbemerkten
|
||||
Iterieren über den Wiki-Zustand, nicht einen Nutzer, der oft sucht - Retrieval ist deshalb
|
||||
bereits generell davon ausgenommen (siehe [[Iteration and Cost Limits]]). Rate Limiting gehört
|
||||
stattdessen vor den Prozess, neben die Authentifizierung.
|
||||
- **Authentifizierung ist Middleware, nicht Servercode.** Eine Traefik-ForwardAuth-Instanz
|
||||
(Bearer-Token gegen SHA-256-Hashes) sitzt vor dem Prozess; nicht sauber authentifizierte
|
||||
Zugriffe erreichen Python gar nicht erst.
|
||||
- **Gemessen:** Korpus-Parse für 176 Seiten 265 ms → 54 ms (`CSafeLoader`),
|
||||
`wikitool search` end-to-end 593 ms → 347 ms; die verbleibenden ~262 ms sind Modulimport und
|
||||
entfallen im residenten Serverprozess, weil er ihn einmal pro Start statt pro Aufruf
|
||||
zahlt.[^s-mcp-read-server-implementation-session-2026-09-02]
|
||||
|
||||
## Beispiele
|
||||
|
||||
- `search`/`types`/`describe_type`/`lint`/`status` als die fünf Tools - siehe
|
||||
`tools/chemenu/mcp/server.py`.
|
||||
- Der Korpus-Cache (`chemenu/corpus_cache.py`) hält einen Parse pro Commit und cacht nie einen
|
||||
schmutzigen Arbeitsbaum - dieselbe Eigenschaft, die den Antwort-Stempel korrekt hält.
|
||||
- `chemenu.api.Corpus`: nimmt einen Root, liefert exakt die `--json`-Formen der CLI, raised statt
|
||||
zu exitieren.
|
||||
|
||||
## Wann zu verwenden
|
||||
|
||||
- Ein Konsument, der keine Shell auf der bedienenden Maschine ist, soll dieselben Fragen stellen
|
||||
können wie ein Agent, der `wikitool` direkt aufruft.
|
||||
- Mehrere gleichzeitige Leser eines Korpus, für die ein Prozess pro CLI-Aufruf (Modulimport,
|
||||
Korpus-Parse) unnötigen Overhead bedeutet.
|
||||
|
||||
## Wann NICHT zu verwenden
|
||||
|
||||
- Als Ort für einen Schreibpfad - die Ingest-Queue (geplant, Issue #32) ist ein anderes Design
|
||||
mit einer Quarantäne davor, nicht eine Erweiterung dieses Servers.
|
||||
- Als Ersatz für den Iteration Budget Gate oder das Traefik-Rate-Limiting - beide bleiben
|
||||
notwendig und leben an anderer Stelle.
|
||||
|
||||
## Fußnoten
|
||||
|
||||
[^s-mcp-read-server-implementation-session-2026-09-02]: [[Source - MCP Read Server Implementation Session 2026-09-02]]
|
||||
|
||||
## Beziehungen
|
||||
|
||||
## Siehe auch
|
||||
|
||||
- [[Source - MCP Read Server Implementation Session 2026-09-02]]
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **operates-on:** [[wikitool]]
|
||||
- **see-also:** [[Publish-Remote Gate]]
|
||||
- **see-also:** [[Mass-Update Gate]]
|
||||
- **see-also:** [[Iteration and Cost Limits]]
|
||||
- **see-also:** [[Chemenu]]
|
||||
<!-- /wikitool:links -->
|
||||
@@ -4,7 +4,14 @@ concept_type: workflow
|
||||
tags: [gate, safety, mass-update, confirmation]
|
||||
created: 2026-08-03
|
||||
modified: 2026-09-01
|
||||
related: [Content Quality Control, wikitool, Iteration and Cost Limits, Structural Enforcement over Documented Rule, Bulk Operations, Publish-Remote Gate]
|
||||
related:
|
||||
- enables: Content Quality Control
|
||||
- mechanism: wikitool
|
||||
- see-also: Iteration and Cost Limits
|
||||
- exemplifies: Structural Enforcement over Documented Rule
|
||||
- contrasts: Bulk Operations
|
||||
- see-also: Publish-Remote Gate
|
||||
- see-also: MCP-Leseserver
|
||||
sources: [Source - LLM Improvements Sonnet Analysis, Source - LLM Improvements Production Agent Gaps 2026, Source - Conversation - Comma Bug Budget Refund and Lint Report Path Session 2026-08-31, Source - Conversation - Gate Counting and Measured Calibration Session 2026-08-31, Source - LLM Improvements Codex Analysis]
|
||||
confidence: 0.88
|
||||
confidence_base: 0.88
|
||||
@@ -68,26 +75,15 @@ Das Mass-Update Gate ist ein Sicherheitsmechanismus, der die Ausführung pausier
|
||||
|
||||
## Verwandte Concepts
|
||||
|
||||
- [[Content Quality Control]] - Qualitätsrahmen, den Massenaktualisierungen bewahren sollten
|
||||
- [[wikitool]] - Das CLI-Tool, das dieses Gate implementieren könnte
|
||||
- [[Workflow Orchestration]] - Koordinierte Vorgänge, die Gates benötigen könnten
|
||||
|
||||
## Beziehungen
|
||||
|
||||
- **wird gespiegelt durch:** [[Iteration and Cost Limits]]
|
||||
- **wendet an:** [[Structural Enforcement over Documented Rule]]
|
||||
- **grenzt ab gegen:** [[Bulk Operations]]
|
||||
- **verwandtes Gate:** [[Publish-Remote Gate]]
|
||||
|
||||
## Siehe auch
|
||||
|
||||
- [[Source - LLM Improvements Sonnet Analysis]]
|
||||
- [[Iteration and Cost Limits]]
|
||||
- [[Source - LLM Improvements Production Agent Gaps 2026]]
|
||||
- [[Source - Conversation - Gate Counting and Measured Calibration Session 2026-08-31]]
|
||||
- [[Structural Enforcement over Documented Rule]]
|
||||
- [[Bulk Operations]]
|
||||
- [[Publish-Remote Gate]]
|
||||
|
||||
## Fußnoten
|
||||
|
||||
@@ -95,3 +91,15 @@ Das Mass-Update Gate ist ein Sicherheitsmechanismus, der die Ausführung pausier
|
||||
[^s-conversation-gate-counting-and-measured-calibration-session-2026-08-31]: [[Source - Conversation - Gate Counting and Measured Calibration Session 2026-08-31]]
|
||||
[^s-llm-improvements-codex-analysis]: [[Source - LLM Improvements Codex Analysis]]
|
||||
[^s-conversation-comma-bug-budget-refund-and-lint-report-path-session-2026-08-31]: [[Source - Conversation - Comma Bug Budget Refund and Lint Report Path Session 2026-08-31]]
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **enables:** [[Content Quality Control]]
|
||||
- **mechanism:** [[wikitool]]
|
||||
- **see-also:** [[Iteration and Cost Limits]]
|
||||
- **exemplifies:** [[Structural Enforcement over Documented Rule]]
|
||||
- **contrasts:** [[Bulk Operations]]
|
||||
- **see-also:** [[Publish-Remote Gate]]
|
||||
- **see-also:** [[MCP-Leseserver]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,13 @@ concept_type: architecture
|
||||
tags: [memory, lifecycle, confidence, knowledge-management]
|
||||
created: 2026-07-26
|
||||
modified: 2026-08-29
|
||||
related: [LLM Wiki Pattern, Confidence Scoring, Supersession, Consolidation Tiers, Forgetting, Knowledge Compounding]
|
||||
related:
|
||||
- see-also: LLM Wiki Pattern
|
||||
- see-also: Confidence Scoring
|
||||
- composition: Supersession
|
||||
- see-also: Consolidation Tiers
|
||||
- see-also: Forgetting
|
||||
- enables: Knowledge Compounding
|
||||
sources: [Source - LLM Wiki v2]
|
||||
confidence: 0.95
|
||||
confidence_base: 0.95
|
||||
@@ -109,12 +115,6 @@ Basierend auf [[Agent Memory]]-Erfahrung:
|
||||
|
||||
## Verwandte Concepts
|
||||
|
||||
- [[Confidence Scoring]] - Der Scoring-Mechanismus
|
||||
- [[Supersession]] - Der Versionskontroll-Mechanismus
|
||||
- [[Forgetting]] - Der Retention-Curve-Mechanismus
|
||||
- [[Consolidation Tiers]] - Die Promotions-Pipeline
|
||||
- [[Knowledge Compounding]] - Die Gesamtauswirkung
|
||||
- [[LLM Wiki Pattern]] - Das übergeordnete Muster
|
||||
- [[Agent Memory]] - Produktionsimplementierung
|
||||
|
||||
## Siehe auch
|
||||
@@ -122,3 +122,14 @@ Basierend auf [[Agent Memory]]-Erfahrung:
|
||||
- [[Event-Driven Automation]] (Trigger für Lebenszyklus-Management)
|
||||
- [[Quality Scoring]] (komplementäre Qualitätsmetriken)
|
||||
- [[Knowledge Graph]] (Struktur zur Verfolgung von Beziehungen)
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **see-also:** [[LLM Wiki Pattern]]
|
||||
- **see-also:** [[Confidence Scoring]]
|
||||
- **composition:** [[Supersession]]
|
||||
- **see-also:** [[Consolidation Tiers]]
|
||||
- **see-also:** [[Forgetting]]
|
||||
- **enables:** [[Knowledge Compounding]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,10 @@ concept_type: pattern
|
||||
tags: []
|
||||
created: 2026-08-02
|
||||
modified: 2026-08-29
|
||||
related: [Implementation Spectrum, Multi-Agent Collaboration, Source - LLM Wiki v2]
|
||||
related:
|
||||
- exemplifies: Implementation Spectrum
|
||||
- see-also: Multi-Agent Collaboration
|
||||
- evidenced-by: Source - LLM Wiki v2
|
||||
sources: []
|
||||
confidence: 0.50
|
||||
confidence_base: 0.50
|
||||
@@ -38,3 +41,11 @@ TODO
|
||||
## Verwandte Concepts
|
||||
|
||||
- TODO
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **exemplifies:** [[Implementation Spectrum]]
|
||||
- **see-also:** [[Multi-Agent Collaboration]]
|
||||
- **evidenced-by:** [[Source - LLM Wiki v2]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
+12
-4
@@ -4,7 +4,10 @@ concept_type: protocol
|
||||
tags: [industrial, automation, communication, serial]
|
||||
created: 2026-07-25
|
||||
modified: 2026-08-29
|
||||
related: [E3DC, ha-core, Home Assistant]
|
||||
related:
|
||||
- see-also: E3DC
|
||||
- see-also: ha-core
|
||||
- see-also: Home Assistant
|
||||
sources: []
|
||||
confidence: 0.90
|
||||
confidence_base: 0.90
|
||||
@@ -243,7 +246,6 @@ func main() {
|
||||
- [[MQTT]] - Alternatives Protokoll für IoT/Industrie
|
||||
- [[OPC UA]] - Modernes Industrieprotokoll mit Sicherheit
|
||||
- Industrial-Automation-Konzept
|
||||
- [[E3DC]] - Verwendet Modbus zur Kommunikation
|
||||
|
||||
## Historie
|
||||
|
||||
@@ -257,5 +259,11 @@ func main() {
|
||||
|
||||
- [Modbus Organization](https://modbus.org/)
|
||||
- [Modbus Specifications](https://modbus.org/specifications/)
|
||||
- [[E3DC]] - Verwendet Modbus TCP
|
||||
- [[ha-core]] - Kann Modbus verwenden
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **see-also:** [[E3DC]]
|
||||
- **see-also:** [[ha-core]]
|
||||
- **see-also:** [[Home Assistant]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,12 @@ concept_type: workflow
|
||||
tags: [multi-agent, collaboration, sync, coordination]
|
||||
created: 2026-07-26
|
||||
modified: 2026-08-29
|
||||
related: [LLM Wiki Pattern, Memory Lifecycle, Mesh Sync, Shared vs Private, Work Coordination]
|
||||
related:
|
||||
- exemplifies: LLM Wiki Pattern
|
||||
- see-also: Memory Lifecycle
|
||||
- composition: Mesh Sync
|
||||
- composition: Shared vs Private
|
||||
- composition: Work Coordination
|
||||
sources: [Source - LLM Wiki v2]
|
||||
confidence: 0.85
|
||||
confidence_base: 0.85
|
||||
@@ -116,10 +121,6 @@ Basierend auf [[Agent Memory]]-Erfahrung:
|
||||
|
||||
## Verwandte Concepts
|
||||
|
||||
- [[LLM Wiki Pattern]] - Gesamtmuster
|
||||
- [[Mesh Sync]] - Der Synchronisationsmechanismus
|
||||
- [[Shared vs Private]] - Der Scoping-Mechanismus
|
||||
- [[Work Coordination]] - Der Koordinationsmechanismus
|
||||
- [[Event-Driven Automation]] - Für Sync-Trigger
|
||||
- [[Audit Trail]] - Zur Verfolgung von Multi-Agent-Operationen
|
||||
|
||||
@@ -127,3 +128,13 @@ Basierend auf [[Agent Memory]]-Erfahrung:
|
||||
|
||||
- [[Privacy and Governance]] (für Zugriffskontrolle)
|
||||
- [[Quality and Self-Correction]] (zur Aufrechterhaltung der Qualität in kollaborativen Einstellungen)
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **exemplifies:** [[LLM Wiki Pattern]]
|
||||
- **see-also:** [[Memory Lifecycle]]
|
||||
- **composition:** [[Mesh Sync]]
|
||||
- **composition:** [[Shared vs Private]]
|
||||
- **composition:** [[Work Coordination]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,8 @@ concept_type: problem
|
||||
tags: [bug, drifts, kebab-case, human-readable]
|
||||
created: 2026-08-03
|
||||
modified: 2026-08-29
|
||||
related: [AGENTS.md]
|
||||
related:
|
||||
- operates-on: AGENTS.md
|
||||
sources: [Source - LLM Improvements Codex Analysis]
|
||||
confidence: 0.80
|
||||
confidence_base: 0.80
|
||||
@@ -45,19 +46,21 @@ Naming Convention Conflict ist ein spezifischer Drift/Bug, bei dem README.md und
|
||||
|
||||
## Verwandte Concepts
|
||||
|
||||
- [[AGENTS.md]] (gibt benutzerfreundliche Titel mit Leerzeichen an)
|
||||
- README.md (gibt kebab-case an)
|
||||
- [[Source - LLM Improvements Codex Analysis]][^s-llm-improvements-codex-analysis]
|
||||
|
||||
## Beziehungen
|
||||
|
||||
- **beeinflusst:** [[AGENTS.md]]
|
||||
|
||||
## Siehe auch
|
||||
|
||||
- [[Source - LLM Improvements Codex Analysis]]
|
||||
- [[AGENTS.md]]
|
||||
|
||||
## Fußnoten
|
||||
|
||||
[^s-llm-improvements-codex-analysis]: [[Source - LLM Improvements Codex Analysis]]
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **operates-on:** [[AGENTS.md]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,8 @@ concept_type: architecture
|
||||
tags: [interoperability, export, validate, okf-profile]
|
||||
created: 2026-08-03
|
||||
modified: 2026-08-29
|
||||
related: [awesome-llm-wiki]
|
||||
related:
|
||||
- see-also: awesome-llm-wiki
|
||||
sources: [Source - LLM Improvements Codex Analysis]
|
||||
confidence: 0.80
|
||||
confidence_base: 0.80
|
||||
@@ -45,19 +46,21 @@ OKF (Open Knowledge Framework) Compatibility ist das Konzept, einen Export-/Vali
|
||||
|
||||
## Verwandte Concepts
|
||||
|
||||
- [[awesome-llm-wiki]] (OKF ist ein großes Thema in diesem Repository)
|
||||
- [[Three-Layer Architecture]] (OKF-Export würde eine zusätzliche Ebene oder einen Modus darstellen)
|
||||
- [[Source - LLM Improvements Codex Analysis]][^s-llm-improvements-codex-analysis]
|
||||
|
||||
## Beziehungen
|
||||
|
||||
- **vorgestellt in:** [[awesome-llm-wiki]]
|
||||
|
||||
## Siehe auch
|
||||
|
||||
- [[Source - LLM Improvements Codex Analysis]]
|
||||
- [[awesome-llm-wiki]]
|
||||
|
||||
## Fußnoten
|
||||
|
||||
[^s-llm-improvements-codex-analysis]: [[Source - LLM Improvements Codex Analysis]]
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **see-also:** [[awesome-llm-wiki]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,11 @@ concept_type: architecture
|
||||
tags: []
|
||||
created: 2026-08-31
|
||||
modified: 2026-08-31
|
||||
related: [ENVIRONMENT.md, Personalization Plane, wikitool, Chemenu]
|
||||
related:
|
||||
- mechanism: ENVIRONMENT.md
|
||||
- contrasts: Personalization Plane
|
||||
- mechanism: wikitool
|
||||
- operates-on: Chemenu
|
||||
sources: [Source - Conversation - ENVIRONMENT.md as an Optional Third Session-Level File Session 2026-08-31]
|
||||
confidence: 0.50
|
||||
confidence_base: 0.50
|
||||
@@ -92,25 +96,23 @@ in das Repo aller anderen.
|
||||
|
||||
## Verwandte Concepts
|
||||
|
||||
- [[Personalization Plane]] — dasselbe Muster als Pflicht: dort `FAIL` bei fehlender Datei, hier
|
||||
nie
|
||||
- [[KB Stack Versioning]] — das Muster kam mit `1.8.0`, ohne Kompatibilitätsbruch
|
||||
|
||||
## Beziehungen
|
||||
|
||||
- **umgesetzt von:** [[wikitool]]
|
||||
- **verwendet von:** [[Chemenu]]
|
||||
- **umgesetzt von:** [[ENVIRONMENT.md]]
|
||||
- **verwandt mit:** [[Personalization Plane]]
|
||||
|
||||
## Siehe auch
|
||||
|
||||
- [[ENVIRONMENT.md]]
|
||||
- [[Personalization Plane]]
|
||||
- [[wikitool]]
|
||||
- [[Chemenu]]
|
||||
- [[Source - Conversation - ENVIRONMENT.md as an Optional Third Session-Level File Session 2026-08-31]]
|
||||
|
||||
## Fußnoten
|
||||
|
||||
[^s-conversation-environment-md-as-an-optional-third-session-level-file-session-2026-08-31]: [[Source - Conversation - ENVIRONMENT.md as an Optional Third Session-Level File Session 2026-08-31]]
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **mechanism:** [[ENVIRONMENT.md]]
|
||||
- **contrasts:** [[Personalization Plane]]
|
||||
- **mechanism:** [[wikitool]]
|
||||
- **operates-on:** [[Chemenu]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,10 @@ concept_type: architecture
|
||||
tags: []
|
||||
created: 2026-08-31
|
||||
modified: 2026-08-31
|
||||
related: [wikitool, Chemenu, Optional Instance Context File]
|
||||
related:
|
||||
- mechanism: wikitool
|
||||
- operates-on: Chemenu
|
||||
- see-also: Optional Instance Context File
|
||||
sources: [Source - Conversation - ENVIRONMENT.md as an Optional Third Session-Level File Session 2026-08-31]
|
||||
confidence: 0.50
|
||||
confidence_base: 0.50
|
||||
@@ -85,23 +88,24 @@ sondern in den Health-Check.
|
||||
## Verwandte Concepts
|
||||
|
||||
- [[KB Migration]] - Abgrenzung: dort Korpus-Form, hier Instanz-Zustand
|
||||
- [[Optional Instance Context File]] - dasselbe Muster ohne Pflicht: dort meldet der
|
||||
- Optional Instance Context File - dasselbe Muster ohne Pflicht: dort meldet der
|
||||
Health-Check nur, hier scheitert er[^s-conversation-environment-md-as-an-optional-third-session-level-file-session-2026-08-31]
|
||||
- [[KB Stack Versioning]] - die Plane kam mit `1.1.0`, ohne Kompatibilitätsbruch
|
||||
|
||||
## Beziehungen
|
||||
|
||||
- **umgesetzt von:** [[wikitool]]
|
||||
- **verwendet von:** [[Chemenu]]
|
||||
- **verwandt mit:** [[Optional Instance Context File]]
|
||||
|
||||
## Siehe auch
|
||||
|
||||
- [[wikitool]]
|
||||
- [[Chemenu]]
|
||||
- [[Optional Instance Context File]]
|
||||
- [[Source - Conversation - ENVIRONMENT.md as an Optional Third Session-Level File Session 2026-08-31]]
|
||||
|
||||
## Fußnoten
|
||||
|
||||
[^s-conversation-environment-md-as-an-optional-third-session-level-file-session-2026-08-31]: [[Source - Conversation - ENVIRONMENT.md as an Optional Third Session-Level File Session 2026-08-31]]
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **mechanism:** [[wikitool]]
|
||||
- **operates-on:** [[Chemenu]]
|
||||
- **see-also:** [[Optional Instance Context File]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,11 @@ concept_type: workflow
|
||||
tags: [privacy, security, governance, audit]
|
||||
created: 2026-07-26
|
||||
modified: 2026-08-29
|
||||
related: [LLM Wiki Pattern, Filter on Ingest, Audit Trail, Bulk Operations]
|
||||
related:
|
||||
- exemplifies: LLM Wiki Pattern
|
||||
- see-also: Filter on Ingest
|
||||
- see-also: Audit Trail
|
||||
- see-also: Bulk Operations
|
||||
sources: [Source - LLM Wiki v2]
|
||||
confidence: 0.90
|
||||
confidence_base: 0.90
|
||||
@@ -132,10 +136,6 @@ Basierend auf [[Agent Memory]] und Produktionserfahrung:
|
||||
|
||||
## Verwandte Concepts
|
||||
|
||||
- [[LLM Wiki Pattern]] - Gesamtmuster
|
||||
- [[Filter on Ingest]] - Der Filtermechanismus
|
||||
- [[Audit Trail]] - Der Protokollierungsmechanismus
|
||||
- [[Bulk Operations]] - Gouvernanzoperationen
|
||||
- [[Event-Driven Automation]] - Für automatisierte Governance
|
||||
|
||||
## Siehe auch
|
||||
@@ -143,3 +143,12 @@ Basierend auf [[Agent Memory]] und Produktionserfahrung:
|
||||
- [[Privacy and Governance]] (diese Seite)
|
||||
- [[Multi-Agent Collaboration]] (für Multi-Agent-Sicherheit)
|
||||
- [[Quality and Self-Correction]] (für Qualitätsaspekte)
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **exemplifies:** [[LLM Wiki Pattern]]
|
||||
- **see-also:** [[Filter on Ingest]]
|
||||
- **see-also:** [[Audit Trail]]
|
||||
- **see-also:** [[Bulk Operations]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,8 @@ concept_type: architecture
|
||||
tags: []
|
||||
created: 2026-08-02
|
||||
modified: 2026-08-29
|
||||
related: [Consolidation Tiers]
|
||||
related:
|
||||
- see-also: Consolidation Tiers
|
||||
sources: []
|
||||
confidence: 0.50
|
||||
confidence_base: 0.50
|
||||
@@ -38,3 +39,9 @@ TODO
|
||||
## Verwandte Concepts
|
||||
|
||||
- TODO
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **see-also:** [[Consolidation Tiers]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -3,13 +3,16 @@ type: types/concept.md
|
||||
concept_type: workflow
|
||||
tags: []
|
||||
created: 2026-09-01
|
||||
modified: 2026-09-01
|
||||
related: [Mass-Update Gate, Chemenu]
|
||||
sources: [Source - Publish-Remote Gate and Issue Triage Session 2026-09-01, Source - Private-Instance Merge Correction and Issue 30 Session 2026-09-01]
|
||||
confidence: 0.50
|
||||
modified: 2026-09-02
|
||||
related:
|
||||
- see-also: Mass-Update Gate
|
||||
- operates-on: Chemenu
|
||||
- see-also: MCP-Leseserver
|
||||
sources: [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]
|
||||
confidence: 0.70
|
||||
confidence_base: 0.70
|
||||
provenance: sourced
|
||||
summary: 'Drittes, im Code durchgesetztes Gate: publish bricht mit Exit 42 ab, wenn die aufgeloeste Push-URL nicht in einer optionalen, gitignoreten Allowlist steht; anders als die anderen Gates gibt es keinen Freigabe-Token.'
|
||||
summary: 'Drittes, im Code durchgesetztes Gate: publish bricht mit Exit 42 ab, wenn die aufgeloeste Push-URL nicht in einer optionalen, gitignoreten Allowlist steht; doctor benennt seit 2026-09-02 den Gate-Zustand statt nur die Dateiexistenz'
|
||||
---
|
||||
# Publish-Remote Gate
|
||||
|
||||
@@ -40,6 +43,12 @@ Remote lokal konfiguriert ist.
|
||||
ist wichtig: Ein Checkout ohne Beschränkungsbedarf soll nicht gezwungen sein, eine leere
|
||||
Konfigurationsdatei zu pflegen; eine beschädigte Datei darf aber nicht wie eine abwesende
|
||||
behandelt werden, sonst wird eine defekte Sicherung zu einer stillschweigend abgeschalteten.
|
||||
- **`doctor` benennt seit 2026-09-02 den Gate-*Zustand*, nicht nur, ob die Datei existiert.**
|
||||
Vorher meldete der Check nur die Anwesenheit von `.wikitool-remotes.json`; ob das
|
||||
gleichbedeutend mit "scharf" ist, musste der Leser selbst schließen. Alle drei Ausgaben
|
||||
beginnen jetzt mit `Gate armed:` bzw. `Gate not armed:` - der Ein-Remote-Fall ohne Allowlist
|
||||
bleibt `OK` (er hat nichts zu schützen), sagt aber ausdrücklich, dass jedes Push-Ziel
|
||||
durchkommt.[^s-mcp-read-server-implementation-session-2026-09-02]
|
||||
|
||||
## Wann zu verwenden
|
||||
|
||||
@@ -85,22 +94,22 @@ getestetes Skript und zwei Architekturvorschläge (das Verfahren als `wikitool`-
|
||||
oder den Demo-Korpus grundsätzlich von dem Branch fernhalten, von dem private Instanzen ihre
|
||||
Maschinerie ziehen) stehen in Gitea-Issue #30.
|
||||
|
||||
## Verwandte Concepts
|
||||
|
||||
- [[Mass-Update Gate]]
|
||||
|
||||
## Beziehungen
|
||||
|
||||
- **gilt fuer:** [[Chemenu]]
|
||||
- **verwandtes Gate:** [[Mass-Update Gate]]
|
||||
|
||||
## Siehe auch
|
||||
|
||||
- [[Source - Publish-Remote Gate and Issue Triage Session 2026-09-01]]
|
||||
- [[Chemenu]]
|
||||
- [[Mass-Update Gate]]
|
||||
- [[Source - Private-Instance Merge Correction and Issue 30 Session 2026-09-01]]
|
||||
|
||||
## Fußnoten
|
||||
|
||||
[^s-private-instance-merge-correction-and-issue-30-session-2026-09-01]: [[Source - Private-Instance Merge Correction and Issue 30 Session 2026-09-01]]
|
||||
[^s-mcp-read-server-implementation-session-2026-09-02]: [[Source - MCP Read Server Implementation Session 2026-09-02]]
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **see-also:** [[Mass-Update Gate]]
|
||||
- **operates-on:** [[Chemenu]]
|
||||
- **see-also:** [[MCP-Leseserver]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,11 @@ concept_type: pattern
|
||||
tags: []
|
||||
created: 2026-08-02
|
||||
modified: 2026-08-29
|
||||
related: [Confidence Scoring, Implementation Spectrum, Memory Lifecycle, Source - LLM Wiki v2]
|
||||
related:
|
||||
- see-also: Confidence Scoring
|
||||
- exemplifies: Implementation Spectrum
|
||||
- see-also: Memory Lifecycle
|
||||
- evidenced-by: Source - LLM Wiki v2
|
||||
sources: []
|
||||
confidence: 0.50
|
||||
confidence_base: 0.50
|
||||
@@ -38,3 +42,12 @@ TODO
|
||||
## Verwandte Concepts
|
||||
|
||||
- TODO
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **see-also:** [[Confidence Scoring]]
|
||||
- **exemplifies:** [[Implementation Spectrum]]
|
||||
- **see-also:** [[Memory Lifecycle]]
|
||||
- **evidenced-by:** [[Source - LLM Wiki v2]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,11 @@ concept_type: workflow
|
||||
tags: [quality, scoring, self-healing, contradiction, knowledge-management]
|
||||
created: 2026-07-26
|
||||
modified: 2026-08-29
|
||||
related: [LLM Wiki Pattern, Memory Lifecycle, Event-Driven Automation, Confidence Scoring]
|
||||
related:
|
||||
- exemplifies: LLM Wiki Pattern
|
||||
- see-also: Memory Lifecycle
|
||||
- rests-on: Event-Driven Automation
|
||||
- rests-on: Confidence Scoring
|
||||
sources: [Source - LLM Wiki v2]
|
||||
confidence: 0.90
|
||||
confidence_base: 0.90
|
||||
@@ -111,10 +115,6 @@ Basierend auf [[Agent Memory]] und [[Event-Driven Automation]]:
|
||||
|
||||
## Verwandte Concepts
|
||||
|
||||
- [[LLM Wiki Pattern]] - Gesamtmuster
|
||||
- [[Memory Lifecycle]] - Ergänzende Knowledge Management
|
||||
- [[Confidence Scoring]] - Für Aussage-Level-Konfidenz
|
||||
- [[Event-Driven Automation]] - Für Auslösen von Qualitätsprüfungen
|
||||
- [[Lint Workflow]] - Die Gesundheitsprüfungsoperation
|
||||
- [[Agent Memory]] - Produktionsimplementierung
|
||||
|
||||
@@ -125,3 +125,11 @@ Basierend auf [[Agent Memory]] und [[Event-Driven Automation]]:
|
||||
- [[Self-Healing]] (der automatische Reparaturmechanismus)
|
||||
- [[Contradiction Resolution]] (der Entscheidungsprozess)
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **exemplifies:** [[LLM Wiki Pattern]]
|
||||
- **see-also:** [[Memory Lifecycle]]
|
||||
- **rests-on:** [[Event-Driven Automation]]
|
||||
- **rests-on:** [[Confidence Scoring]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
+12
-4
@@ -4,7 +4,10 @@ concept_type: architecture
|
||||
tags: [ai, retrieval, generation, knowledge-management]
|
||||
created: 2026-07-26
|
||||
modified: 2026-08-29
|
||||
related: [LLM Wiki Pattern, NotebookLM, ChatGPT]
|
||||
related:
|
||||
- see-also: LLM Wiki Pattern
|
||||
- see-also: NotebookLM
|
||||
- see-also: ChatGPT
|
||||
sources: [Source - LLM Wiki Pattern]
|
||||
confidence: 0.90
|
||||
confidence_base: 0.90
|
||||
@@ -107,7 +110,12 @@ Das [[LLM Wiki Pattern]] kann als eine Verbesserung zu RAG angesehen werden, die
|
||||
|
||||
## Siehe auch
|
||||
|
||||
- [[LLM Wiki Pattern]]
|
||||
- [[Knowledge Compounding]]
|
||||
- [[NotebookLM]]
|
||||
- [[ChatGPT]]
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **see-also:** [[LLM Wiki Pattern]]
|
||||
- **see-also:** [[NotebookLM]]
|
||||
- **see-also:** [[ChatGPT]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,10 @@ concept_type: pattern
|
||||
tags: []
|
||||
created: 2026-08-02
|
||||
modified: 2026-08-29
|
||||
related: [Hybrid Search, LLM Wiki Pattern, Source - LLM Wiki v2]
|
||||
related:
|
||||
- see-also: Hybrid Search
|
||||
- exemplifies: LLM Wiki Pattern
|
||||
- evidenced-by: Source - LLM Wiki v2
|
||||
sources: []
|
||||
confidence: 0.50
|
||||
confidence_base: 0.50
|
||||
@@ -38,3 +41,11 @@ TODO
|
||||
## Verwandte Concepts
|
||||
|
||||
- TODO
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **see-also:** [[Hybrid Search]]
|
||||
- **exemplifies:** [[LLM Wiki Pattern]]
|
||||
- **evidenced-by:** [[Source - LLM Wiki v2]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
+11
-7
@@ -4,7 +4,9 @@ concept_type: protocol
|
||||
tags: [storage, ssd, performance, optimization, linux]
|
||||
created: 2026-07-31
|
||||
modified: 2026-08-29
|
||||
related: [Disk Encryption, LVM, Arch Linux]
|
||||
related:
|
||||
- see-also: LVM
|
||||
- see-also: Arch Linux
|
||||
sources: [Source - Arch Linux Cheat Sheet]
|
||||
confidence: 0.90
|
||||
confidence_base: 0.90
|
||||
@@ -175,16 +177,18 @@ lsblk -o NAME,FSTYPE,DISC-GRAN,DISC-MAX
|
||||
|
||||
## Beziehungen
|
||||
|
||||
- **Verwendet mit:** [[Disk Encryption]] (dm-crypt/LUKS)
|
||||
- **Ergänzt:** [[LVM]] (Logical Volume Manager)
|
||||
- **Läuft auf:** [[Arch Linux]] und anderen Distributionen
|
||||
(dm-crypt/LUKS)
|
||||
- **Wirkt sich aus auf:** Speicherleistung SSD-gestützter Systeme
|
||||
|
||||
## Siehe auch
|
||||
|
||||
- [[Disk Encryption]]
|
||||
- [[LVM]]
|
||||
- [[Arch Linux]]
|
||||
- [[Source - Arch Linux Cheat Sheet]]
|
||||
- https://wiki.archlinux.org/title/Solid_State_Drives
|
||||
- https://wiki.archlinux.org/title/Dm-crypt/Specialties#Discard/TRIM_support_for_solid_state_drives_(SSD)
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **see-also:** [[LVM]]
|
||||
- **see-also:** [[Arch Linux]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,10 @@ concept_type: architecture
|
||||
tags: [scale, limitations]
|
||||
created: 2026-08-04
|
||||
modified: 2026-09-01
|
||||
related: []
|
||||
related:
|
||||
- see-also: Token Economics
|
||||
- see-also: Cross-platform Agent Skills
|
||||
- see-also: Context Isolation
|
||||
sources: [Source - Copilot Skill Restructure Instructions]
|
||||
confidence: 0.80
|
||||
confidence_base: 0.80
|
||||
@@ -46,12 +49,14 @@ Scale Ceiling ist kein Problem wenn:
|
||||
- Retrieval-Augmented-Ansätze genutzt werden, die alles in den Kontext laden vermeiden
|
||||
- Die Workflows kein Verständnis von Verbindungen über das gesamte Wiki erfordern
|
||||
|
||||
## Verwandte Concepts
|
||||
|
||||
- [[Token Economics]]
|
||||
- [[Cross-platform Agent Skills]]
|
||||
- [[Context Isolation]]
|
||||
|
||||
## Fußnoten
|
||||
|
||||
[^s-copilot-skill-restructure-instructions]: [[Source - Copilot Skill Restructure Instructions]]
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **see-also:** [[Token Economics]]
|
||||
- **see-also:** [[Cross-platform Agent Skills]]
|
||||
- **see-also:** [[Context Isolation]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,13 @@ concept_type: pattern
|
||||
tags: []
|
||||
created: 2026-08-02
|
||||
modified: 2026-08-29
|
||||
related: [Confidence Scoring, Quality and Self-Correction, Source - LLM Wiki v2, Supersession, Detect-Repair Asymmetry, Command Round-Trip Integrity]
|
||||
related:
|
||||
- see-also: Confidence Scoring
|
||||
- part-of: Quality and Self-Correction
|
||||
- evidenced-by: Source - LLM Wiki v2
|
||||
- see-also: Supersession
|
||||
- see-also: Detect-Repair Asymmetry
|
||||
- see-also: Command Round-Trip Integrity
|
||||
sources: []
|
||||
confidence: 0.50
|
||||
confidence_base: 0.50
|
||||
@@ -41,11 +47,15 @@ TODO
|
||||
|
||||
## Beziehungen
|
||||
|
||||
- **abgegrenzt gegen:** [[Detect-Repair Asymmetry]]
|
||||
- **folgt aus:** [[Command Round-Trip Integrity]]
|
||||
|
||||
## Siehe auch
|
||||
|
||||
- [[Detect-Repair Asymmetry]]
|
||||
- [[Command Round-Trip Integrity]]
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **see-also:** [[Confidence Scoring]]
|
||||
- **part-of:** [[Quality and Self-Correction]]
|
||||
- **evidenced-by:** [[Source - LLM Wiki v2]]
|
||||
- **see-also:** [[Supersession]]
|
||||
- **see-also:** [[Detect-Repair Asymmetry]]
|
||||
- **see-also:** [[Command Round-Trip Integrity]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,8 @@ concept_type: workflow
|
||||
tags: [heuristics, stale-claims, change-density, weak-linking]
|
||||
created: 2026-08-03
|
||||
modified: 2026-08-29
|
||||
related: [wikitool]
|
||||
related:
|
||||
- mechanism: wikitool
|
||||
sources: [Source - LLM Improvements Codex Analysis, Source - LLM Improvements Sonnet Analysis]
|
||||
confidence: 0.80
|
||||
confidence_base: 0.80
|
||||
@@ -55,20 +56,22 @@ Semantic Lint Automation bezieht sich auf Maschinen-Heuristiken, die potenzielle
|
||||
|
||||
- [[Lint Workflow]] (vorhandenes Konzept für strukturelles Linting)
|
||||
- [[Confidence Scoring]] (wird verwendet, um Aussagen mit niedrigem Vertrauen zu identifizieren)
|
||||
- [[wikitool]] (implementiert strukturelles Linting, könnte semantische Heuristiken hinzufügen)
|
||||
- [[Source - LLM Improvements Codex Analysis]][^s-llm-improvements-codex-analysis]
|
||||
|
||||
## Beziehungen
|
||||
|
||||
- **implementiert von:** [[wikitool]]
|
||||
|
||||
## Siehe auch
|
||||
|
||||
- [[Source - LLM Improvements Codex Analysis]]
|
||||
- [[wikitool]]
|
||||
- [[Source - LLM Improvements Sonnet Analysis]]
|
||||
|
||||
## Fußnoten
|
||||
|
||||
[^s-llm-improvements-sonnet-analysis]: [[Source - LLM Improvements Sonnet Analysis]]
|
||||
[^s-llm-improvements-codex-analysis]: [[Source - LLM Improvements Codex Analysis]]
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **mechanism:** [[wikitool]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,8 @@ concept_type: architecture
|
||||
tags: []
|
||||
created: 2026-08-02
|
||||
modified: 2026-08-29
|
||||
related: [Consolidation Tiers]
|
||||
related:
|
||||
- see-also: Consolidation Tiers
|
||||
sources: []
|
||||
confidence: 0.50
|
||||
confidence_base: 0.50
|
||||
@@ -38,3 +39,9 @@ TODO
|
||||
## Verwandte Concepts
|
||||
|
||||
- TODO
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **see-also:** [[Consolidation Tiers]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,8 @@ concept_type: workflow
|
||||
tags: [preflight, context, query, update]
|
||||
created: 2026-08-03
|
||||
modified: 2026-08-29
|
||||
related: [wikitool]
|
||||
related:
|
||||
- mechanism: wikitool
|
||||
sources: [Source - LLM Improvements Codex Analysis, Source - LLM Improvements Sonnet Analysis]
|
||||
confidence: 0.80
|
||||
confidence_base: 0.80
|
||||
@@ -55,15 +56,18 @@ Session Orientation ist eine obligatorische Preflight-Prüfung, die einen Kontex
|
||||
|
||||
## Beziehungen
|
||||
|
||||
- **würde implementiert von:** [[wikitool]]
|
||||
|
||||
## Siehe auch
|
||||
|
||||
- [[Source - LLM Improvements Codex Analysis]]
|
||||
- [[wikitool]]
|
||||
- [[Source - LLM Improvements Sonnet Analysis]]
|
||||
|
||||
## Fußnoten
|
||||
|
||||
[^s-llm-improvements-sonnet-analysis]: [[Source - LLM Improvements Sonnet Analysis]]
|
||||
[^s-llm-improvements-codex-analysis]: [[Source - LLM Improvements Codex Analysis]]
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **mechanism:** [[wikitool]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,8 @@ concept_type: pattern
|
||||
tags: []
|
||||
created: 2026-08-02
|
||||
modified: 2026-08-29
|
||||
related: [Multi-Agent Collaboration]
|
||||
related:
|
||||
- see-also: Multi-Agent Collaboration
|
||||
sources: []
|
||||
confidence: 0.50
|
||||
confidence_base: 0.50
|
||||
@@ -38,3 +39,9 @@ TODO
|
||||
## Verwandte Concepts
|
||||
|
||||
- TODO
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **see-also:** [[Multi-Agent Collaboration]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,8 @@ concept_type: workflow
|
||||
tags: [page-management, refactoring, link-correction, frontmatter]
|
||||
created: 2026-08-03
|
||||
modified: 2026-08-29
|
||||
related: [wikitool]
|
||||
related:
|
||||
- mechanism: wikitool
|
||||
sources: [Source - LLM Improvements Codex Analysis]
|
||||
confidence: 0.80
|
||||
confidence_base: 0.80
|
||||
@@ -46,20 +47,22 @@ Split Merge Reclassify bezieht sich auf dedizierte Befehle für strukturelle Sei
|
||||
|
||||
## Verwandte Concepts
|
||||
|
||||
- [[wikitool]] (Werkzeug, das diese Befehle implementieren würde)
|
||||
- [[Bulk Operations]] (vorhandenes Concept für geprüfte Massenvorgänge)
|
||||
- [[Entity Extraction]] (bezüglich Umklassifizierungsentscheidungen)
|
||||
- [[Source - LLM Improvements Codex Analysis]][^s-llm-improvements-codex-analysis]
|
||||
|
||||
## Beziehungen
|
||||
|
||||
- **würde implementiert durch:** [[wikitool]]
|
||||
|
||||
## Siehe auch
|
||||
|
||||
- [[Source - LLM Improvements Codex Analysis]]
|
||||
- [[wikitool]]
|
||||
|
||||
## Fußnoten
|
||||
|
||||
[^s-llm-improvements-codex-analysis]: [[Source - LLM Improvements Codex Analysis]]
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **mechanism:** [[wikitool]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,10 @@ concept_type: workflow
|
||||
tags: [split, threshold, lines, pages]
|
||||
created: 2026-08-03
|
||||
modified: 2026-08-29
|
||||
related: [Content Quality Control, Stub Threshold, Index Scaling]
|
||||
related:
|
||||
- see-also: Content Quality Control
|
||||
- see-also: Stub Threshold
|
||||
- see-also: Index Scaling
|
||||
sources: [Source - LLM Improvements Sonnet Analysis]
|
||||
confidence: 0.80
|
||||
confidence_base: 0.80
|
||||
@@ -53,9 +56,6 @@ Split Threshold definiert die maximale Größe, die eine Wiki-Seite erreichen so
|
||||
|
||||
## Verwandte Concepts
|
||||
|
||||
- [[Content Quality Control]] - Breiteres Framework
|
||||
- [[Stub Threshold]] - Mindestgröße-Ergänzung
|
||||
- [[Index Scaling]] - Verwandte Skalierung für Index-Seiten
|
||||
- [[Anti-Cramming Heuristic]] - Regel für wann neue Seiten zu erstellen sind
|
||||
|
||||
## Siehe auch
|
||||
@@ -65,3 +65,11 @@ Split Threshold definiert die maximale Größe, die eine Wiki-Seite erreichen so
|
||||
## Fußnoten
|
||||
|
||||
[^s-llm-improvements-sonnet-analysis]: [[Source - LLM Improvements Sonnet Analysis]]
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **see-also:** [[Content Quality Control]]
|
||||
- **see-also:** [[Stub Threshold]]
|
||||
- **see-also:** [[Index Scaling]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,11 @@ concept_type: decision
|
||||
tags: [quality, tooling, tests, governance]
|
||||
created: 2026-08-31
|
||||
modified: 2026-08-31
|
||||
related: [Ambient Environment Dependency, wikitool, Iteration and Cost Limits, Mass-Update Gate]
|
||||
related:
|
||||
- see-also: Ambient Environment Dependency
|
||||
- mechanism: wikitool
|
||||
- see-also: Iteration and Cost Limits
|
||||
- see-also: Mass-Update Gate
|
||||
sources: [Source - Conversation - Hardening the Test Suite Against Silent Environment Dependencies Session 2026-08-31]
|
||||
confidence: 0.50
|
||||
confidence_base: 0.50
|
||||
@@ -92,26 +96,23 @@ Dokumentation erklärt die Regel und ihre Ausnahmen; sie trägt aber nicht die D
|
||||
|
||||
## Verwandte Concepts
|
||||
|
||||
- [[Ambient Environment Dependency]]
|
||||
- [[Iteration and Cost Limits]]
|
||||
- [[Mass-Update Gate]]
|
||||
- [[Green Suite Blind Spot]]
|
||||
|
||||
## Beziehungen
|
||||
|
||||
- **Gegenmittel zu:** [[Ambient Environment Dependency]]
|
||||
- **angewandt in:** [[Iteration and Cost Limits]]
|
||||
- **angewandt in:** [[Mass-Update Gate]]
|
||||
- **umgesetzt in:** [[wikitool]]
|
||||
|
||||
## Siehe auch
|
||||
|
||||
- [[Source - Conversation - Hardening the Test Suite Against Silent Environment Dependencies Session 2026-08-31]]
|
||||
- [[Ambient Environment Dependency]]
|
||||
- [[wikitool]]
|
||||
- [[Iteration and Cost Limits]]
|
||||
- [[Mass-Update Gate]]
|
||||
|
||||
## Fußnoten
|
||||
|
||||
[^s-conversation-hardening-the-test-suite-against-silent-environment-dependencies-session-2026-08-31]: [[Source - Conversation - Hardening the Test Suite Against Silent Environment Dependencies Session 2026-08-31]]
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **see-also:** [[Ambient Environment Dependency]]
|
||||
- **mechanism:** [[wikitool]]
|
||||
- **see-also:** [[Iteration and Cost Limits]]
|
||||
- **see-also:** [[Mass-Update Gate]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,10 @@ concept_type: workflow
|
||||
tags: [stub, minimum, quality, lines]
|
||||
created: 2026-08-03
|
||||
modified: 2026-08-29
|
||||
related: [Content Quality Control, Split Threshold, Semantic Lint Automation]
|
||||
related:
|
||||
- see-also: Content Quality Control
|
||||
- see-also: Split Threshold
|
||||
- see-also: Semantic Lint Automation
|
||||
sources: [Source - LLM Improvements Sonnet Analysis, Source - LLM Wiki v2]
|
||||
confidence: 0.80
|
||||
confidence_base: 0.80
|
||||
@@ -64,12 +67,6 @@ It provides comprehensive information about the topic. It clearly exceeds the st
|
||||
- Für Seiten, die absichtlich minimal sind (z. B. Redirect-Seiten)
|
||||
- Wenn der Inhalt natürlicherweise kurz aber vollständig ist
|
||||
|
||||
## Verwandte Concepts
|
||||
|
||||
- [[Content Quality Control]] - Das breitere Framework, das Stub-Schwellenwerte enthält
|
||||
- [[Split Threshold]] - Die obere Grenze-Ergänzung zu Stub-Schwellenwert
|
||||
- [[Semantic Lint Automation]] - Könnte Stub-Erkennung einbinden
|
||||
|
||||
## Siehe auch
|
||||
|
||||
- [[Source - LLM Improvements Sonnet Analysis]]
|
||||
@@ -79,3 +76,11 @@ It provides comprehensive information about the topic. It clearly exceeds the st
|
||||
|
||||
[^s-llm-improvements-sonnet-analysis]: [[Source - LLM Improvements Sonnet Analysis]]
|
||||
[^s-llm-wiki-v2]: [[Source - LLM Wiki v2]]
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **see-also:** [[Content Quality Control]]
|
||||
- **see-also:** [[Split Threshold]]
|
||||
- **see-also:** [[Semantic Lint Automation]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,11 @@ concept_type: workflow
|
||||
tags: [versioning, knowledge, updates, lifecycle]
|
||||
created: 2026-07-26
|
||||
modified: 2026-08-29
|
||||
related: [Memory Lifecycle, Confidence Scoring, Knowledge Graph, LLM Wiki Pattern]
|
||||
related:
|
||||
- see-also: Memory Lifecycle
|
||||
- rests-on: Confidence Scoring
|
||||
- see-also: Knowledge Graph
|
||||
- exemplifies: LLM Wiki Pattern
|
||||
sources: [Source - LLM Wiki v2]
|
||||
confidence: 0.95
|
||||
confidence_base: 0.95
|
||||
@@ -122,11 +126,7 @@ Wenn Aussage B Aussage A ersetzt:
|
||||
|
||||
## Verwandte Concepts
|
||||
|
||||
- [[Memory Lifecycle]] - Übergeordnetes Concept
|
||||
- [[Confidence Scoring]] - Bestimmt welche Aussage in Widerspruch gewinnt
|
||||
- [[Contradiction Resolution]] - Der Entscheidungsprozess für Supersession
|
||||
- [[Knowledge Graph]] - Struktur zur Verfolgung von Supersession-Beziehungen
|
||||
- [[LLM Wiki Pattern]] - Gesamtes Pattern
|
||||
|
||||
## Siehe auch
|
||||
|
||||
@@ -134,3 +134,12 @@ Wenn Aussage B Aussage A ersetzt:
|
||||
- [[Forgetting]] (komplementärer Mechanismus)
|
||||
- [[Self-Healing]] (für automatisierte Supersession-Erkennung)
|
||||
- [[Audit Trail]] (zum Nachverfolgen von Supersession-Historie)
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **see-also:** [[Memory Lifecycle]]
|
||||
- **rests-on:** [[Confidence Scoring]]
|
||||
- **see-also:** [[Knowledge Graph]]
|
||||
- **exemplifies:** [[LLM Wiki Pattern]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
@@ -4,7 +4,11 @@ concept_type: architecture
|
||||
tags: [llm-wiki, layers, structure]
|
||||
created: 2026-07-26
|
||||
modified: 2026-08-29
|
||||
related: [LLM Wiki Pattern, RAG, Memory Lifecycle, Knowledge Graph]
|
||||
related:
|
||||
- see-also: LLM Wiki Pattern
|
||||
- contrasts: RAG
|
||||
- composition: Memory Lifecycle
|
||||
- composition: Knowledge Graph
|
||||
sources: [Source - LLM Wiki Pattern, Source - LLM Wiki v2]
|
||||
confidence: 0.95
|
||||
confidence_base: 0.95
|
||||
@@ -256,11 +260,15 @@ Die Three-Layer Architecture bleibt gültig und ausreichend für viele Anwendung
|
||||
|
||||
## Siehe auch
|
||||
|
||||
- [[LLM Wiki Pattern]]
|
||||
- AGENTS.md
|
||||
- [[RAG]]
|
||||
- [[Knowledge Compounding]]
|
||||
- [[Memory Lifecycle]]
|
||||
- [[Knowledge Graph]]
|
||||
- [[Implementation Spectrum]]
|
||||
|
||||
<!-- wikitool:links -->
|
||||
## Beziehungen
|
||||
|
||||
- **see-also:** [[LLM Wiki Pattern]]
|
||||
- **contrasts:** [[RAG]]
|
||||
- **composition:** [[Memory Lifecycle]]
|
||||
- **composition:** [[Knowledge Graph]]
|
||||
<!-- /wikitool:links -->
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user