Files

T

torben 00c2cf6ffe ingest: Public Release, Corpus Purge and History Squash Session 2026-09-01

Files changed:
- kb/concepts/Delete Rather Than Anonymize.md
- kb/concepts/Dual Licensing by File Plan.md
- kb/concepts/INDEX.md
- kb/entities/projects/Chemenu.md
- kb/entities/tools/wikitool.md
- kb/index.md
- kb/log.md
- kb/provenance.md
- kb/sources/INDEX.md
- kb/sources/Source - Public Release, Corpus Purge and History Squash Session 2026-09-01.md
- raw/notes/Conversation Transcript - Private-Instance Merge Correction and Issue 30 Session 2026-09-01.md
- raw/notes/Conversation Transcript - Public Release, Corpus Purge and History Squash Session 2026-09-01.md
- raw/notes/Conversation Transcript - Publish-Remote Gate and Issue Triage Session 2026-09-01.md

2026-09-01 20:32:05 +02:00

27 KiB

Raw Blame History

type, entity_type, tags, created, modified, related, sources, confidence, confidence_base, provenance, summary

type

entity_type

wikitool

Typ: tool

Beschreibung

wikitool ist ein deterministisches CLI-Tool, das alle mechanischen Operationen für Chemenu verwaltet. Es erzwingt Konsistenz über Gerüstbau, Cross-References, Index-Neuerstellung, Log-Einträge, Confidence-Decay-Berechnungen und Git-Publishing. Das Tool ist so ausgelegt, dass es manuelle Fehler verhindert und strukturelle Aspekte des Wikis (Frontmatter, Linking, Indizierung) immer korrekt sind, sodass sich das LLM auf semantische Inhalte konzentrieren kann.

Wie in der Codex-Analyse vermerkt, bietet wikitool die deterministische Grundlage, die vielen öffentlichen LLM-Wiki-Skills fehlt. Es implementiert die Trennung von "mechanisch vs. semantisch", die in AGENTS.md definiert ist, wobei wikitool alles handhabt, das präzise automatisiert werden kann, während das LLM Urteile und Prosa handhabt.

Kerndaten

Zweck: Deterministische mechanische Wiki-Operationen
Status: Aktiv, in aktiver Entwicklung
Version: Teil des tools/chemenu-Pakets
Sprache/Technik: Python 3, Typer CLI Framework
Repository: Lokal unter tools/chemenu/
Einstiegspunkt: tools/wikitool (Bash-Wrapper)

Beziehungen

Teil von: AGENTS.md-Workflow-Implementierung
Verwendet: Python
Verwandt mit: LLM Wiki Pattern, Three-Layer Architecture , Mass-Update Gate
implementiert: Semantic Lint Automation
würde implementieren: Session Orientation
Analyse: Source - LLM Improvements Codex Analysis, Source - LLM Improvements Sonnet Analysis
implementiert: Iteration and Cost Limits
implementiert: KB Stack Versioning
implementiert: KB Migration
implementiert: Personalization Plane
zeigt: Detect-Repair Asymmetry
behebt: Write-Once Frontmatter Fields
implementiert: Denylist over Allowlist
zeigt: Command Round-Trip Integrity
zeigt: Green Suite Blind Spot
zeigte: Ambient Environment Dependency
setzt um: Structural Enforcement over Documented Rule
setzt um: Optional Instance Context File

Befehle

wikitool bietet die folgenden Befehlskategorien:

Gerüstbau: new entity, new concept, new source, new comparison, new instruction. Ein --set-Wert für ein Array-Feld wird auf Kommas gesplittet; seit 1.2.0 ist ein literales Komma als \, ausdrückbar (Lookbehind (?<!\\), plus Unescape je Element), und ein für dasselbe Array-Feld wiederholtes --set hängt an statt zu ersetzen. Skalare behalten „last one wins". Derselbe Helper bedient auch xref add --entities¹
Seiten-Mutation: touch (eines Seiten-modified/summary/provenance/confidence_base, seit 1.4.0 zusätzlich --set/--add/--remove für jedes Feld, das das Schema des Seitentyps deklariert, abzüglich der Sperrliste type, confidence und der Referenz-Arrays; --add/--remove arbeiten auf einzelnen Elementen eines Listenfelds, --remove gelingt und meldet es, wenn das Element nicht vorhanden ist, und ein per touch geschriebenes raw_files: wird gegen das Dateisystem geprüft wie beim Anlegen². Siehe Write-Once Frontmatter Fields und Denylist over Allowlist), rename (Seite umtiteln und jeden Verweis neu ausrichten, oder Verweise auf eine bestehende Seite neu ausrichten), rm (Löschen und Entfernen von Verknüpfungen)
Cross-References: xref add, xref remove, xref link-source - seit 1.6.0 schreibt link-source beide Richtungen: das Ziel bekommt sources: und einen Siehe-auch-Eintrag, die Source-Seite trägt das Ziel in ihr eigenes entities: oder concepts: ein. Welches der beiden Felder es wird, folgt der Collection des Ziels (kb/entities/ → entities:), sodass eine neue Collection hier keine Codeänderung braucht. xref add lehnt eine Seite ab, deren Typ related: nicht deklariert, und prüft beide Seiten, bevor es eine schreibt; xref remove fegt auch ein undeklariertes Feld weg und löscht den Schlüssel, sobald er leer ist³. Siehe Command Round-Trip Integrity
Zitate: cite id, cite add, cite sync - der Fußnotenblock endet seit 1.5.1 an der nächsten Überschrift statt am Dateiende. Zuvor löschte cite add jeden Inhalt dahinter, weil split_cite_block() alles bis Dateiende als Block nahm und nur die Zitatdefinitionszeilen behielt; cite sync und rename benutzten denselben Pfad. Loser Text im Block wird auf den Seitenkopf zurückgefaltet statt abgelehnt, und weil der Block immer zuletzt gerendert wird, richtet die erste Zitatoperation eine verrutschte Seite von selbst wieder ein³
Abfrage: search - Textsuche über kb/ durch ein austauschbares Backend (rg heute), plus --field-Prädikate, die auf Frontmatter evaluiert werden (entity_type=system, confidence>=0.8, tags=k8s, !source_url). Ohne Text ist es eine reine strukturierte Abfrage. Schreibgeschützt und ausgenommen von der Iteration-Budget-Gate, da Abfrage das Lesen statt das Iterieren ist
Indizierung: index rebuild - regeneriert die kb/index.md-Map plus eine pro-Sammlung INDEX.md, wobei ein Bereich bei 50 Zeilen in seine eigene Shard aufgeteilt wird
Herkunft: sources coverage, sources trace, sources rebuild-index
Protokollierung: log append, log status
Linting: lint - schreibt den vollen Report seit 1.2.0 immer, standardmäßig nach reports/Lint Report <datum>.md, und gibt den Pfad aus; gedruckt werden nur Abschnitte mit Befunden, --full druckt alles, --json schreibt nichts¹
Typen: types list, types describe
Konfidenz: confidence decay, confidence init-base
Veröffentlichung: publish - zählt seit 1.5.0 nur noch Dateien, die eine Entscheidung tragen: Pfade unter work/ und generierte Dateien (kb/index.md, kb/log.md, kb/provenance.md, jede INDEX.md) werden committet und gepusht, aber nicht gegen die Schwelle gezählt; die Weigerungszeile weist beide Gründe getrennt aus⁴. Siehe Mass-Update Gate
Budget: budget status, budget reset - Obergrenze seit 1.2.0 60 Aufrufe je Sitzung; ein Aufruf, der über _util.fail() abgelehnt wurde, bekommt seinen Slot zurück und bleibt trotzdem in recent, damit der Loop-Breaker ihn sieht¹. Siehe Iteration and Cost Limits
Versionierung: version bump, version check - bump schreibt die Stack-Version in die Wurzeldatei VERSION und verweigert einen MAJOR-Sprung ohne Migrationsdokument, sofern er nicht ausdrücklich mit --no-migration "<Begründung>" gesetzt wird; check ist der einzige Befehl, der einen Netzaufruf machen darf - ohne Schlüssel, mit Timeout und injizierbarem Fetch, damit Tests nie ein Netz berühren⁵
Migration: migrate list, migrate status, migrate verify, migrate done, migrate baseline - status bildet das Intervall (kb_version, VERSION] aufsteigend, done verweigert jede Version, die nicht das nächste Glied ist, verify vergleicht zwei Revisionen des Korpus über corpus_diff mit Zählungen statt Mengen, baseline setzt einer Instanz ohne .wikitool-kb.json ihren Startwert⁵. Siehe KB Migration
Distribution: dist export - erzeugt das Release-Artefakt und legt den Stempel .wikitool-release.json hinein⁵
Diagnose: doctor - enthält einen kb-version-Check⁵ sowie seit 1.1.0 einen personalization-Check: FAIL, wenn USER.md oder SOUL.md fehlen, und ebenso, wenn eine der beiden noch die Sentinel-Zeile des Templates trägt - ein umbenanntes Template ist kein ausgefülltes. Siehe Personalization Plane sowie seit 1.8.0 einen environment-Check für ENVIRONMENT.md: OK bei fehlender wie bei ausgefüllter Datei, WARN allein bei einem umbenannten, nie ausgefüllten Template. Nie FAIL - die Datei ist optional, und ein FAIL machte sie durch die Hintertür verpflichtend⁶. Siehe Optional Instance Context File
Coverage: CI führt die Tests seit 1.8.1 mit pytest --cov aus (Konfiguration tools/.coveragerc, nicht pytest.ini - coverage.py liest Letzteres nicht) und lädt den Bericht als Artefakt hoch, ohne Abbruchschwelle - siehe Messen vor Schwelle
Dokumentation: docs verify - überprüft, dass jeder CLI-Befehl in tools/CONTRACT.md dokumentiert ist und umgekehrt, dass jedes Verzeichnis unter kb/ eine COLLECTION.md hat und kein Verzeichnis außerhalb hat, dass jeder Stage-Contract existiert, und dass keine Ignorierungsregel Inhalte unter raw/ oder kb/ stille ausschließen würde (oder stille generierte Ausgabe unter reports/ committen würde)
Anweisungen: instructions sync, instructions verify, instructions list - publiziert jede instructions/<name>/SKILL.md als Kopie in .agents/skills/ (nativ gelesen von GitHub Copilot, Codex CLI und Mistral Vibe) und .claude/skills/ (erforderlich für Claude Code, das nichts anderes liest), und überprüft die Schicht: Anweisungen gegen ihre Schema, Skill-Frontmatter gegen das, das der Harness liest, jede veröffentlichte Kopie Byte-für-Byte gegen ihre Quelle, und alle Anweisungen, auf die nichts verweist

Details

Das Tool verwendet eine Python-Paketstruktur mit einer Typer-basierten CLI. Wichtige Module sind:

cli.py - Haupteinstiegspunkt des Befehls
commands/new_page.py - Seiten-Gerüstbau
commands/xref.py - Cross-Reference-Verwaltung
commands/search.py + search/ - Abfrage, aufgeteilt in einen Backend-agnostischen Kern (SearchBackend-Protokoll, Frontmatter-Prädikate, Reciprocal Rank Fusion) und ein Backend (ripgrep.py), sodass ein Vektor-Backend ein neues Modul statt einer Umschrift ist
commands/index_build.py - Katalog-Map und Shard-Neuerstellung
commands/instructions_cmd.py - Anweisungs-Schicht: publish, verify, list
commands/provenance_cmd.py - Herkunfts-Verfolgung
commands/log_append.py - Log-Eintrag-Formatierung
commands/lint.py - Strukturvalidierung
commands/git_publish.py - Git-Operationen
commands/skills_sync.py - .agents/skills/ <-> .claude/skills/-Spiegelung und Verifikation⁷

Die Provenance-Remediation-Session fügte drei wichtige operative Verbesserungen hinzu:

Neue Provenance-Befehlsgruppe (sources coverage, sources trace, sources rebuild-index) für Raw-zu-Source- und Source-zu-Page-Nachverfolgbarkeit.
Erweiterte Lint-Überprüfungen für nicht abgedeckte Raw-Dateien, beschädigte Raw-Verweise, fehlende Provenance-Marker und Citation/Frontmatter-Drift.
Wrapper-Verhaltensbehebung, sodass relative Pfadargumente vom Arbeitsverzeichnis des Aufrufers (Repository-Root-Verwendung) statt von tools/ aufgelöst werden.

Der Bash-Wrapper unter tools/wikitool aktiviert die Python venv und exportiert PYTHONPATH, um chemenu importierbar zu halten, ohne cwd zu ändern.

Für die Migrationsprüfung kamen zwei Module dazu: corpus_diff.py vergleicht zwei Revisionen des Korpus und kb_state.py liest und schreibt .wikitool-kb.json. Beide Seiten des Vergleichs müssen dieselbe Vorstellung von „Seite" haben: Ein erster Lauf meldete 13 entfernte Seiten, die keine waren, weil die historische Seite jede .md unter kb/ zählte und die Arbeitsbaum-Seite iter_kb_pages benutzte. Ein gemeinsames kb_scan.is_page_path löst das auf⁵.

kb_scan.extract_wikilinks() liefert bewusst ein Set. Das ist die richtige Form für lint, das fragt, ob ein Verweis auflöst - und die falsche für eine Migrationsprüfung, die fragt, ob einer verschwunden ist⁵.

Historie

2026-09-01 - 2.1.0-2.2.2: Vorbereitung und Durchführung der Veröffentlichung. dist export bekommt REQUIRED_ROOT_FILES (fehlende Lizenzdateien lassen den Export scheitern statt still weiterzulaufen) und find_leaks() (strukturelle Prüfung des fertigen Export-Plans gegen Personalisierungsdateien, instructions/dev/, kb/- und raw/-Inhalte - bewusst kein Text-Muster-Scan, weil der eigene Hostname legitim in INSTALL.md/version.py steht). publish bekommt ein drittes Gate: das Publish-Remote-Gate prüft die aufgelöste Push-URL (nicht den Remote-Namen) gegen eine optionale, gitignorete .wikitool-remotes.json und hat als einziges der drei Gates keinen --confirm-Token - der Weg daran vorbei ist ein bewusster Edit der Datei durch den Nutzer, nie durch einen Agenten. doctor bekommt den publish-remotes-Check. Ein raw_dir-Testfixture löste config.ROOT gegen das echte Repo-Root statt die Fixture auf und bestand nur, weil zufällig ein Verzeichnis existierte, das der Korpus-Schnitt entfernte - in der Fixture geschlossen, nicht im einzelnen Test, aus demselben Grund wie Gitea #8. Siehe Chemenu, Mass-Update Gate, Delete Rather Than Anonymize, Dual Licensing by File Plan⁸
2026-09-01 - 2.0.0 (Commit 9a7abe6, 730 Tests grün): das Python-Paket heißt chemenu statt wiki_tools, das Kommando bleibt wikitool. Der Import-Name eines Pakets ist ein flacher globaler Namensraum ohne Kollisionsschutz, wiki_tools war dafür zu generisch; Distributionsname, Import-Name und Kommandoname sind drei unabhängige Dinge, und ein abweichender Kommandoname ist verbreitete Praxis. Unverändert bleiben damit auch .wikitool-release.json, .wikitool-kb.json und die WIKITOOL_*-Variablen - sie gehören zum Kommando, nicht zum Paket. Verzeichnet in CHANGES.md (2.0.0), Kontext in Chemenu.
2026-08-31 - 1.8.0 (Commit a243a4a): doctor bekommt den environment-Check, dist export liefert ENVIRONMENT.md.template über die Root-Allowlist aus, und docs verify prüft das zugehörige Ignore-Muster in beide Richtungen - die Datei muss ignoriert sein, ihr Template darf es nicht⁶
2026-08-31 - 1.7.1 (Commit 31c9b81, Tag v1.7.1, 702 Tests grün, 7 neue): die Testsuite läuft seither gegen eine absichtlich leere Maschine, Gitea-Issue #8 (prio/1). Eine autouse-Fixture in conftest.py setzt HOME je Test in dessen tmp_path, git-Konfiguration auf /dev/null und löscht die Tool- sowie die git-Identitätsvariablen; WIKI_TRACE_DIR bleibt als einziges gesetzt, weil zwei Telemetrie-Tests einen geschriebenen Trace behaupten. Anlass war default_author(), das per git config user.name die globale Konfiguration des Aufrufers las - vier Tests hingen nacheinander daran, zwei davon geschrieben, nachdem das Issue offen war. Die Wirkung ist nicht am grünen Lauf belegt (die Suite war unter der gehärteten Umgebung schon vorher grün), sondern an der Gegenprobe: dieselbe Funktion antwortet ohne Isolierung mit dem globalen git-Namen, mit Isolierung None. 702 Tests in vier Umgebungen - Entwickler-Shell, vergiftet, env -i, CI⁹. Siehe Ambient Environment Dependency und Structural Enforcement over Documented Rule
2026-08-31 - 1.6.0 (Commit ce03749, 689 Tests grün, 11 neue): drei Symptome mit einer Ursache, Gitea-Issue #18 (prio/1). xref_link_source schrieb nur die Zielseiten, nie die eigenen Arrays der Source-Seite - die waren nach new source unerreichbar. Das von xref add dort geschriebene related: deklariert types/source.md nicht, und strip_frontmatter_ref() räumte nur deklarierte Felder, also konnte xref remove es nicht entfernen. Seither schreibt link-source beide Richtungen, xref add prüft beide Seiten vorab und lehnt ein undeklariertes Feld ab, xref remove fegt Reste. Der Beleg für die Inversenbeziehung war eine Concept-Seite, die byteidentisch aus xref remove plus xref link-source zurückkam³. Siehe Command Round-Trip Integrity
2026-08-31 - 1.5.1 (Commit bb4123b): cite add löschte jeden Inhalt hinter dem Fußnotenblock, weil split_cite_block() alles von der Überschrift bis Dateiende als Block nahm und daraus nur die Zitatdefinitionen behielt; cite sync und rename teilten den Pfad, und eine nur hinter dem Block referenzierte Fußnote wäre von cite sync als verwaist gelöscht worden. Da xref add am Dateiende anhängt, entschied allein die Reihenfolge beider Kommandos über den Bestand der Querverweise. 8 Seiten mit 74 Zeilen standen in dieser Position; cite sync --all normalisierte elf Seiten auf 0 (Gitea-Issue #17, prio/1)³. Siehe Command Round-Trip Integrity und Green Suite Blind Spot
2026-08-31 - 1.5.0 (Commit 3166c31, 9 Dateien, 678 Tests grün): zwei Kalibrierungen aus einer Beobachtung, nicht aus einem Issue. publish nimmt generierte Dateien aus der Gate-Zählung heraus - is_generated() kannte die Liste und GATE_EXEMPT_PREFIXES/ counted_files() boten den Mechanismus, verbunden waren beide nie -, und das Kalibrierungsband für einen komplexen Multi-Tool-Workflow steigt in run_budget.py von 15-25 auf 20-35 Aufrufe. Beides ist an realen Läufen gemessen: drei Ingest-Changesets (14 → 9, 16 → 9, 11 → 5 gezählte Dateien) und vier Sitzungszähler aus tools/.wikitool_session/budget.json (30, 29, 26, 24 Aufrufe). Schwelle 10 und Budget-Obergrenze 60 blieben unverändert⁴
2026-08-31 - Gitea-Issues #12 und #13 behoben (1.2.0, Commit 40adbb7): Komma-Escape und Append-Semantik in parse_list(), Budget-Erstattung für abgelehnte Aufrufe, Obergrenze 60 und der immer geschriebene Lint-Report. Der End-to-End-Test deckte einen zweiten Defekt auf: dump_frontmatter schreibt Listen im Flow-Stil, _format_scalar entschied das Quoting aber über eine Round-Trip-Probe auf Dokumentebene, wo ein Komma gewöhnlich ist - innerhalb von [...] ist es ein Indikator. Behoben in frontmatter_io.py über _round_trips_as_string(text, flow=True) und einen _quote()-Helper, der sich vom Dumper eine einelementige Flow-Sequenz geben lässt und die Klammern abstreift, weil ein blanker Plain-Scalar aus safe_dump einen ...-Dokumentende-Marker mitbringt. Bestehende Ausgabe blieb unverändert. 658 Tests grün, auch in der gehärteten Umgebung, nachdem zwei neue Tests WIKI_AUTHOR selbst setzen¹
2026-08-31 - Gitea-Issue #14 geschlossen (1.4.0, Commit dbe2f73, 9 Dateien, 674 Tests grün): touch bekommt --set/--add/--remove. Der Schnitt blieb bewusst eng - die Dateiverschiebung bleibt zweistufig (git mv, dann touch --set raw_files=…), raw rename wurde als Issue #16 (prio/2, size/S) abgespalten. _coerce_set_value, _parse_set_fields und _check_raw_files_exist wanderten aus new_page.py nach commands/_util.py, damit touch --set den Komma-Defekt aus Issue #12 nicht am ersten Tag erbt. Als Nebenbefund fiel eine Testfalle: ein direkt aufgerufener Typer-Callback bekommt für jedes ausgelassene Argument ein OptionInfo-Objekt, worauf drei neue Optionen sieben Aufrufstellen in test_touch.py brachen; die Tests laufen jetzt über einen _touch(**overrides)-Helper²
2026-08-31 - Zuvor offene Lücke (Gitea-Issue #14): kein Befehl schreibt raw_files: auf einer bestehenden Seite. touch deckt die Felder ab, die die Seite beschreiben, xref die Seiten-Referenz-Arrays; raw_files: zeigt auf einen Pfad und ist keines von beidem. Vorgeschlagen sind sources relink oder ein raw rename, das git mv und jede referenzierende Source-Seite in einem Schritt erledigt. Siehe Detect-Repair Asymmetry¹
2026-08-30 - Befehlsgruppen version und migrate sowie dist export ergänzt; Stack- und KB-Version werden seither in getrennten Dateien geführt. Zwei Tests, die die Autor-Ermittlung über git config user.name prüfen sollten, hingen unbemerkt an der globalen git-Konfiguration der ausführenden Maschine und fielen im ersten CI-Lauf; behoben in den Tests, nicht durch eine git-Identität für CI⁵
2026-08-05 - Wechsel von skills sync/verify vom Kopieren von Skill-Verzeichnissen zu relativen Symlinks (Claude Codes eigene Dokumentation bestätigt, dass es symlinked Skill-Ordner folgt) - ein Symlink kann niemals veralten, im Gegensatz zu einer Kopie.
2026-08-04 - Befehle skills sync/skills verify hinzugefügt, um .agents/skills/ in .claude/skills/ für Claude-Code-Kompatibilität zu spiegeln, als Teil des Aufteilens von AGENTS.md-Workflows in diskrete Skills⁷.
2026-08-03 - Deterministische Provenance-Befehlsgruppe hinzugefügt und Wrapper-Pfadverhalten während der Conversation-Ingest/Provenance-Remediation-Arbeit gehärtet.
2026-08-03 - Seite während der Einspeisung der Codex-Analyse erstellt
2026-08-02 - Tool referenziert in wikitool-Lint-Verbesserungen (Log-Eintrag)
2026-07-26 - Anfängliche Implementierung als Teil der Wiki-Infrastruktur

27 KiB Raw Blame History