Erledigt (2026-09-26). Phase 1 ist umgesetzt und published: 26e1018 (Hauptänderung), b79f083 (Prosa-Nachzug in README/INSTALL/DEVELOPMENT/docs), 5ffab3a (prog_name, Hilfe-Kriterien als Tests), 2a60f3a (Export-Fix, siehe B9). Stand 7.1.0-beta.6 im laufenden Kandidaten. Folgepakete: #142 (redaktionelle Phase 2), #143 (Abhilfe in der Fehlerausgabe). Der ursprüngliche Stub steht wörtlich im ersten Kommentar.
Ein wikitool-Kommando wurde an mehreren Stellen beschrieben, alle von Hand gepflegt: im --help-Text, in den zwei Tabellen von tools/CONTRACT.md, und für einzelne Eigenschaften zusätzlich im Code (run_budget.py) und in AGENTS.md. Das verletzte AGENTS.md Invariante 8 (eine Regel, ein Ort) und das Kernprinzip „never re-derive, always compile“. Jetzt trägt jedes Kommando genau einen Datensatz im Code, aus dem alle Sichten erzeugt werden.
Befund (Ausgangslage, gegen den Baum geprüft 2026-09-25)
Zwei Beschreibungen je Kommando.--help trug Flags, Kurzbeschreibung und teils Begründung; tools/CONTRACT.md (471 Zeilen, 60 Kommandos) Signatur und Verhalten in § Commands, Exit 1/Atomarität/Retry in § Error contracts. docs verify prüfte nur die Anwesenheit des Kommandopfads.
Drift:xref add und xref link-source nahmen --dry-run, ihre Signatur nannte es nicht. Früher: #93, CHANGES.md 2.5.0.
Eigenschaften dreifach: Budget-Ausnahmen in run_budget.py (SKIP_COMMANDS, SKIP_COMMAND_PATHS, Sonderfall version regrade) und als Prosa in den Contract-Zeilen. Die AGENTS.md-Liste nicht-idempotenter Kommandos widersprach den Contract-Zeilen (version bump, version release, migrate done fehlten).
Nutzung: 109 wikitool … --help-Aufrufe in 43 von 96 Claude-Code-Sitzungen dieses Checkouts.
Darstellung: Rich-Rahmen verdoppelten die Länge, auch Usage-Fehler waren gerahmt; -h wurde von Click abgelehnt; die Usage-Zeile nannte python -m chemenu.cli; Issue-Nummern standen in ausgelieferter Hilfe (new, review, Gruppe task).
Ergebnis
Eine Quelle, drei Sichten. Neues Modul tools/chemenu/cli_contract.py: je Kommando ein CommandRecord, per @cli_contract.record(...) an der Kommandofunktion in ihrem eigenen Modul. Alle 61 Kommandos (60 bestehende + neues docs contract) tragen einen. Daraus entstehen:
wikitool <cmd> -h – der vollständige Datensatz als Klartext, mit und ohne TTY byte-gleich, -h und --help identisch, keine Rahmen.
Index – eine Zeile je Kommando mit festen Spalten (effect, idempotent, budget:, exit:, Zweck), in wikitool -h und oben in tools/CONTRACT.md.
tools/CONTRACT.md – die Region <!-- wikitool:commands --> ist generiert (wikitool docs contract [--apply]), je ###-Gruppe die Datensätze als #### <cmd>. Die beiden Tabellen und § Error contracts gibt es nicht mehr.
Abschnitte eines Datensatzes: NAME, SYNOPSIS (je Variante mit eigener Notiz), PROPERTIES (effect, idempotent, atomic, budget, network, gates), OPTIONS (live aus Click, nur in -h), EXIT STATUS, ON FAILURE, NOTES. EXAMPLES, NEVER und SEE ALSO sind im Modell vorhanden und bleiben leer bis #142.
Entscheidungen
D1 – Quelle ist der Code. Verworfen: Contract als Quelle mit Laufzeit-Parse, Trennung ohne Generator.
D2 – Kein Rahmen, eine Ausgabe für alle, Linux-Konventionen. Umgesetzt: Rich global aus, TTY-unabhängig. --json erst mit einem Konsumenten.
D3 – Man-Page-Datensatz mit typisierten Eigenschaften, Index-Zeile je Kommando.
D4 – Zwei Phasen. Phase 1 (dieses Issue) mechanisch; Phase 2 in #142.
D5 – Typisierte Eigenschaften sind die Quelle für Code und Kontrollebene.run_budget.py liest budget: aus dem Datensatz; AGENTS.md § Tool error contract verweist auf den Index statt eine eigene Liste zu führen.
Wie gebaut (Bauplan, mit den beim Bauen getroffenen Festlegungen)
B1 – Datenmodell in cli_contract.py: CommandRecord, Variant(usage, notes), Failure(label, exit_1, retry), Properties; Enums Effect, Idempotent, Budget (counted/exempt/exempt_without_args), Network. GROUPS als geordnete Konstante. Ein Kommando, das nie mit Exit 1 endet, trägt keine Failure; der alte Zellentext „Never fails“ steht dann in NOTES.
B2 – Docstrings.\f ist überall dort gesetzt, wo sonst eine Issue-Nummer oder Wartungstext im gerenderten Teil stünde; der Rest bleibt unterhalb als nie gerenderter Wartungstext. Nicht jeder Docstring im Repo wurde auf einen Satz gekürzt – da -h jetzt vollständig aus dem Datensatz rendert, zeigt sich der Docstring nur noch in Clicks Gruppenlisten.
B3 – SYNOPSIS handgeschrieben, Flags geprüft.docs verify vergleicht in beiden Richtungen; hidden=True zählt nicht; bei --push/--no-push genügt eine der beiden Schreibweisen.
B4 – Renderer:render_text, render_markdown_section, render_index_line/render_index, render_commands_region. OPTIONS mit fester Breite 80, damit die Ausgabe vom Terminal unabhängig bleibt.
B5 – Hilfe.typer.core.HAS_RICH = False beim Import von cli.py; -h per context_settings auf der Wurzel (vererbt sich auf alle Gruppen); prog_name="wikitool". Mechanik: ein globaler Patch auf typer._click.core.Command.format_help – typer 0.27 vendoriert einen eigenen Click-Fork, TyperCommand und TyperGroup fallen bei HAS_RICH = False beide dorthin durch. Weil das ein privates Modul ist, steht der Patch in try/except: fehlt es in einer künftigen typer-Version, bleibt die Hilfe ungerahmt, nur ohne Datensatz-Rendering. Eine reine Zwischengruppe (wikitool xref -h) hat keinen Datensatz und zeigt Clicks Standardliste.
B6 – tools/CONTRACT.md generiert. Handgeschrieben bleiben Einleitung (Grep-Rezept ersetzt durch -h, Index-grep und grep '^#### '), Setup, Usage, Design notes (dort steht weiterhin der Iteration-Budget-Eintrag), Tests, Maintenance schedule.
B7 – docs verify.check_cli_readme ersetzt durch check_command_contracts (Datensatz ↔ Registrierung ↔ GROUPS, beide Richtungen, keine Doppelung), check_commands_region, check_synopsis_flags, check_no_issue_references_in_help (Docstring oberhalb \f, Options-help=, und – nach dem Code-Review ergänzt – der eigene help=-Text jeder Typer-Gruppe).
B8 – run_budget.py liest den Datensatz; SKIP_COMMANDS/SKIP_COMMAND_PATHS sind entfernt. Ein flaches Kommando (search, doctor, review) wird vor jeder Unterkommando-Deutung gesucht, damit eine Suchanfrage wie status nicht als Unterkommando gelesen wird; bares wikitool version wird auf version show abgebildet.
B9 – Migration. Einmal-Skript im Scratchpad, nicht committet. Ergebnis im Kommentar vom 2026-09-25. Beim ersten Push fiel in CI auf, was keine lokale Prüfung sah: dist export entfernt dist:strip-Markerspannen aus ausgelieferten Dateien, und der dist export-Datensatz zitierte das Markerpaar wörtlich – der Export schnitt es aus tools/CONTRACT.md, die frische Instanz meldete ihre Region als veraltet. (Die alte Tabellenzeile wurde genauso verstümmelt, nur verglich das niemand.) Behoben in 2a60f3a, ein Test prüft seitdem, dass der Exportplan tools/CONTRACT.md byte-gleich ausliefert.
/code-review high lief vor dem Publish: 10 Funde, 6 behoben (u. a. fehlten Variant.notes im live -h; network: stand für review/task */doctor fälschlich auf no), 4 bewusst nicht (siehe Kommentar vom 2026-09-25).
Akzeptanzkriterien
Textbewahrung: Alle 250 Zellentexte der alten Tabellen gegen die Datensätze geprüft (Migrationsskript, Ergebnis im Kommentar). Der Wortinhalt ist vollständig erhalten; bei rund 16 Kommandos ist er auf summary und notes verteilt statt ein zusammenhängender Block. Bewusste Abweichungen: docs verify und docs toc beschreiben ihr neues Verhalten; xref add und xref link-source haben [--dry-run] in der SYNOPSIS gewonnen; der dist export-Datensatz nennt die Strip-Marker, ohne das Paar wörtlich zu zitieren.
Jedes nicht versteckte Flag steht in seiner SYNOPSIS, jedes genannte Flag existiert; Fixture-Tests für undokumentiertes Flag, Phantom-Flag, verstecktes Flag und Flag-Paar.
Handänderung in der Region, Kommando ohne Datensatz und GROUPS-Eintrag ohne Kommando lassen docs verify fehlschlagen (je ein Test, dazu doppelter GROUPS-Eintrag).
wikitool publish -h ist mit und ohne TTY byte-gleich, beginnt mit NAME, Abschnitte in Reihenfolge, EXIT STATUS nennt 1 und 42 (test_cli.py).
-h und --help sind für jedes Kommando identisch (test_cli.py, über alle 61).
Keine Hilfe-Ausgabe und keine Usage-Fehlermeldung enthält Rahmenzeichen; die Usage-Zeile beginnt mit wikitool (test_cli.py, unter dem echten Wrapper zusätzlich von Hand geprüft).
budget:exempt entspricht genau den alten Mengen einschließlich bare version; version regrade als einziges exempt_without_args (Paritätstests in test_run_budget.py).
run_budget.py enthält keine eigene Liste von Kommandonamen mehr.
AGENTS.md § Tool error contract verweist auf den Index; wikitool -h listet new, log append, publish, upstream merge, version bump, version release, migrate done als non-idempotent (Test). Dabei klargestellt: „sofort melden, kein Retry“ gilt nur für einen unklaren Ausgang (Fall 4); ein Validierungsfehler bekommt immer den einen Retry.
Keine gerenderte Hilfe enthält eine Issue-Nummer; docs verify prüft es.
Doku nachgezogen: tools/CONTRACT.md-Einleitung und § Usage, die generierten Datensätze für docs verify/docs contract, AGENTS.md § Routing, § Tool error contract und § Changelog, tools/README.md (wie ein Kommando seinen Datensatz bekommt), instructions/dev/doc-pull-through.md, instructions/dev/stack-close/SKILL.md; nach dem Publish zusätzlich README.md, INSTALL.md, DEVELOPMENT.md und docs/knowledge-and-commitment.md. AGENTS.md Invariante 1 nennt die Region nicht – wie die bestehende <!-- wikitool:toc -->-Region; docs verify hält sie.
docs verify, instructions verify, volle pytest-Suite (1512 Tests) grün; CI auf 2a60f3a grün (Läufe 370 und 371, inkl. Fresh-Instance-Schritt); die Fresh-Instance-Replay aus ci.yml lief zusätzlich lokal gegen einen frischen Export durch.
Außerhalb dieses Pakets
Redaktionelle Aufteilung, Beispiele, Verbote, Begründungen heraus: #142. Dort auch gut aufgehoben: eine Vorlage für die häufigen Properties(...)-Formen und der jetzt tote Docstring-Text unterhalb \f.
Rich-Ausgabe der Kommandos selbst (doctor, version, _util).
Sprechende Metavars (--page TITLE statt --page <str>).
Rund 76 Kommandozeilen mit Flags in 23 Instruction-Dateien bleiben ungeprüft; das ist #83.
network: ist ein Boolean, der Netzzugriff mancher Kommandos hängt aber an der Konfiguration (new nur für new project mit Tracker) – dort steht no.
**Erledigt (2026-09-26).** Phase 1 ist umgesetzt und published: `26e1018` (Hauptänderung), `b79f083` (Prosa-Nachzug in README/INSTALL/DEVELOPMENT/docs), `5ffab3a` (`prog_name`, Hilfe-Kriterien als Tests), `2a60f3a` (Export-Fix, siehe B9). Stand 7.1.0-beta.6 im laufenden Kandidaten. Folgepakete: #142 (redaktionelle Phase 2), #143 (Abhilfe in der Fehlerausgabe). Der ursprüngliche Stub steht wörtlich im ersten Kommentar.
Ein `wikitool`-Kommando wurde an mehreren Stellen beschrieben, alle von Hand gepflegt: im `--help`-Text, in den zwei Tabellen von `tools/CONTRACT.md`, und für einzelne Eigenschaften zusätzlich im Code (`run_budget.py`) und in `AGENTS.md`. Das verletzte AGENTS.md Invariante 8 (eine Regel, ein Ort) und das Kernprinzip „never re-derive, always compile“. Jetzt trägt jedes Kommando genau einen Datensatz im Code, aus dem alle Sichten erzeugt werden.
## Befund (Ausgangslage, gegen den Baum geprüft 2026-09-25)
- **Zwei Beschreibungen je Kommando.** `--help` trug Flags, Kurzbeschreibung und teils Begründung; `tools/CONTRACT.md` (471 Zeilen, 60 Kommandos) Signatur und Verhalten in § Commands, Exit 1/Atomarität/Retry in § Error contracts. `docs verify` prüfte nur die Anwesenheit des Kommandopfads.
- **Drift:** `xref add` und `xref link-source` nahmen `--dry-run`, ihre Signatur nannte es nicht. Früher: #93, `CHANGES.md` 2.5.0.
- **Eigenschaften dreifach:** Budget-Ausnahmen in `run_budget.py` (`SKIP_COMMANDS`, `SKIP_COMMAND_PATHS`, Sonderfall `version regrade`) und als Prosa in den Contract-Zeilen. Die AGENTS.md-Liste nicht-idempotenter Kommandos widersprach den Contract-Zeilen (`version bump`, `version release`, `migrate done` fehlten).
- **Nutzung:** 109 `wikitool … --help`-Aufrufe in 43 von 96 Claude-Code-Sitzungen dieses Checkouts.
- **Darstellung:** Rich-Rahmen verdoppelten die Länge, auch Usage-Fehler waren gerahmt; `-h` wurde von Click abgelehnt; die Usage-Zeile nannte `python -m chemenu.cli`; Issue-Nummern standen in ausgelieferter Hilfe (`new`, `review`, Gruppe `task`).
## Ergebnis
**Eine Quelle, drei Sichten.** Neues Modul `tools/chemenu/cli_contract.py`: je Kommando ein `CommandRecord`, per `@cli_contract.record(...)` an der Kommandofunktion in ihrem eigenen Modul. Alle 61 Kommandos (60 bestehende + neues `docs contract`) tragen einen. Daraus entstehen:
1. **`wikitool <cmd> -h`** – der vollständige Datensatz als Klartext, mit und ohne TTY byte-gleich, `-h` und `--help` identisch, keine Rahmen.
2. **Index** – eine Zeile je Kommando mit festen Spalten (`effect`, `idempotent`, `budget:`, `exit:`, Zweck), in `wikitool -h` und oben in `tools/CONTRACT.md`.
3. **`tools/CONTRACT.md`** – die Region `<!-- wikitool:commands -->` ist generiert (`wikitool docs contract [--apply]`), je `###`-Gruppe die Datensätze als `#### <cmd>`. Die beiden Tabellen und § Error contracts gibt es nicht mehr.
Abschnitte eines Datensatzes: NAME, SYNOPSIS (je Variante mit eigener Notiz), PROPERTIES (`effect`, `idempotent`, `atomic`, `budget`, `network`, `gates`), OPTIONS (live aus Click, nur in `-h`), EXIT STATUS, ON FAILURE, NOTES. EXAMPLES, NEVER und SEE ALSO sind im Modell vorhanden und bleiben leer bis #142.
## Entscheidungen
- **D1 – Quelle ist der Code.** Verworfen: Contract als Quelle mit Laufzeit-Parse, Trennung ohne Generator.
- **D2 – Kein Rahmen, eine Ausgabe für alle, Linux-Konventionen.** Umgesetzt: Rich global aus, TTY-unabhängig. `--json` erst mit einem Konsumenten.
- **D3 – Man-Page-Datensatz mit typisierten Eigenschaften, Index-Zeile je Kommando.**
- **D4 – Zwei Phasen.** Phase 1 (dieses Issue) mechanisch; Phase 2 in #142.
- **D5 – Typisierte Eigenschaften sind die Quelle für Code und Kontrollebene.** `run_budget.py` liest `budget:` aus dem Datensatz; AGENTS.md § Tool error contract verweist auf den Index statt eine eigene Liste zu führen.
- **D6 – Abhilfe in der Fehlerausgabe** ist #143.
## Wie gebaut (Bauplan, mit den beim Bauen getroffenen Festlegungen)
- **B1 – Datenmodell** in `cli_contract.py`: `CommandRecord`, `Variant(usage, notes)`, `Failure(label, exit_1, retry)`, `Properties`; Enums `Effect`, `Idempotent`, `Budget` (`counted`/`exempt`/`exempt_without_args`), `Network`. `GROUPS` als geordnete Konstante. Ein Kommando, das nie mit Exit 1 endet, trägt keine `Failure`; der alte Zellentext „Never fails“ steht dann in NOTES.
- **B2 – Docstrings.** `\f` ist überall dort gesetzt, wo sonst eine Issue-Nummer oder Wartungstext im gerenderten Teil stünde; der Rest bleibt unterhalb als nie gerenderter Wartungstext. Nicht jeder Docstring im Repo wurde auf einen Satz gekürzt – da `-h` jetzt vollständig aus dem Datensatz rendert, zeigt sich der Docstring nur noch in Clicks Gruppenlisten.
- **B3 – SYNOPSIS handgeschrieben, Flags geprüft.** `docs verify` vergleicht in beiden Richtungen; `hidden=True` zählt nicht; bei `--push/--no-push` genügt eine der beiden Schreibweisen.
- **B4 – Renderer:** `render_text`, `render_markdown_section`, `render_index_line`/`render_index`, `render_commands_region`. OPTIONS mit fester Breite 80, damit die Ausgabe vom Terminal unabhängig bleibt.
- **B5 – Hilfe.** `typer.core.HAS_RICH = False` beim Import von `cli.py`; `-h` per `context_settings` auf der Wurzel (vererbt sich auf alle Gruppen); `prog_name="wikitool"`. Mechanik: ein globaler Patch auf `typer._click.core.Command.format_help` – typer 0.27 vendoriert einen eigenen Click-Fork, `TyperCommand` und `TyperGroup` fallen bei `HAS_RICH = False` beide dorthin durch. Weil das ein privates Modul ist, steht der Patch in `try/except`: fehlt es in einer künftigen typer-Version, bleibt die Hilfe ungerahmt, nur ohne Datensatz-Rendering. Eine reine Zwischengruppe (`wikitool xref -h`) hat keinen Datensatz und zeigt Clicks Standardliste.
- **B6 – `tools/CONTRACT.md` generiert.** Handgeschrieben bleiben Einleitung (Grep-Rezept ersetzt durch `-h`, Index-`grep` und `grep '^#### '`), Setup, Usage, Design notes (dort steht weiterhin der Iteration-Budget-Eintrag), Tests, Maintenance schedule.
- **B7 – `docs verify`.** `check_cli_readme` ersetzt durch `check_command_contracts` (Datensatz ↔ Registrierung ↔ `GROUPS`, beide Richtungen, keine Doppelung), `check_commands_region`, `check_synopsis_flags`, `check_no_issue_references_in_help` (Docstring oberhalb `\f`, Options-`help=`, und – nach dem Code-Review ergänzt – der eigene `help=`-Text jeder Typer-Gruppe).
- **B8 – `run_budget.py`** liest den Datensatz; `SKIP_COMMANDS`/`SKIP_COMMAND_PATHS` sind entfernt. Ein flaches Kommando (`search`, `doctor`, `review`) wird vor jeder Unterkommando-Deutung gesucht, damit eine Suchanfrage wie `status` nicht als Unterkommando gelesen wird; bares `wikitool version` wird auf `version show` abgebildet.
- **B9 – Migration.** Einmal-Skript im Scratchpad, nicht committet. Ergebnis im Kommentar vom 2026-09-25. Beim ersten Push fiel in CI auf, was keine lokale Prüfung sah: `dist export` entfernt `dist:strip`-Markerspannen aus ausgelieferten Dateien, und der `dist export`-Datensatz zitierte das Markerpaar wörtlich – der Export schnitt es aus `tools/CONTRACT.md`, die frische Instanz meldete ihre Region als veraltet. (Die alte Tabellenzeile wurde genauso verstümmelt, nur verglich das niemand.) Behoben in `2a60f3a`, ein Test prüft seitdem, dass der Exportplan `tools/CONTRACT.md` byte-gleich ausliefert.
`/code-review high` lief vor dem Publish: 10 Funde, 6 behoben (u. a. fehlten `Variant.notes` im live `-h`; `network:` stand für `review`/`task *`/`doctor` fälschlich auf `no`), 4 bewusst nicht (siehe Kommentar vom 2026-09-25).
## Akzeptanzkriterien
- [x] **Textbewahrung:** Alle 250 Zellentexte der alten Tabellen gegen die Datensätze geprüft (Migrationsskript, Ergebnis im Kommentar). Der Wortinhalt ist vollständig erhalten; bei rund 16 Kommandos ist er auf `summary` und `notes` verteilt statt ein zusammenhängender Block. Bewusste Abweichungen: `docs verify` und `docs toc` beschreiben ihr neues Verhalten; `xref add` und `xref link-source` haben `[--dry-run]` in der SYNOPSIS gewonnen; der `dist export`-Datensatz nennt die Strip-Marker, ohne das Paar wörtlich zu zitieren.
- [x] Jedes nicht versteckte Flag steht in seiner SYNOPSIS, jedes genannte Flag existiert; Fixture-Tests für undokumentiertes Flag, Phantom-Flag, verstecktes Flag und Flag-Paar.
- [x] Handänderung in der Region, Kommando ohne Datensatz und `GROUPS`-Eintrag ohne Kommando lassen `docs verify` fehlschlagen (je ein Test, dazu doppelter `GROUPS`-Eintrag).
- [x] `wikitool publish -h` ist mit und ohne TTY byte-gleich, beginnt mit `NAME`, Abschnitte in Reihenfolge, EXIT STATUS nennt `1` und `42` (`test_cli.py`).
- [x] `-h` und `--help` sind für jedes Kommando identisch (`test_cli.py`, über alle 61).
- [x] Keine Hilfe-Ausgabe und keine Usage-Fehlermeldung enthält Rahmenzeichen; die Usage-Zeile beginnt mit `wikitool` (`test_cli.py`, unter dem echten Wrapper zusätzlich von Hand geprüft).
- [x] `budget:exempt` entspricht genau den alten Mengen einschließlich bare `version`; `version regrade` als einziges `exempt_without_args` (Paritätstests in `test_run_budget.py`).
- [x] `run_budget.py` enthält keine eigene Liste von Kommandonamen mehr.
- [x] AGENTS.md § Tool error contract verweist auf den Index; `wikitool -h` listet `new`, `log append`, `publish`, `upstream merge`, `version bump`, `version release`, `migrate done` als `non-idempotent` (Test). Dabei klargestellt: „sofort melden, kein Retry“ gilt nur für einen unklaren Ausgang (Fall 4); ein Validierungsfehler bekommt immer den einen Retry.
- [x] Keine gerenderte Hilfe enthält eine Issue-Nummer; `docs verify` prüft es.
- [x] Doku nachgezogen: `tools/CONTRACT.md`-Einleitung und § Usage, die generierten Datensätze für `docs verify`/`docs contract`, AGENTS.md § Routing, § Tool error contract und § Changelog, `tools/README.md` (wie ein Kommando seinen Datensatz bekommt), `instructions/dev/doc-pull-through.md`, `instructions/dev/stack-close/SKILL.md`; nach dem Publish zusätzlich README.md, INSTALL.md, DEVELOPMENT.md und `docs/knowledge-and-commitment.md`. AGENTS.md Invariante 1 nennt die Region nicht – wie die bestehende `<!-- wikitool:toc -->`-Region; `docs verify` hält sie.
- [x] `docs verify`, `instructions verify`, volle `pytest`-Suite (1512 Tests) grün; CI auf `2a60f3a` grün (Läufe 370 und 371, inkl. Fresh-Instance-Schritt); die Fresh-Instance-Replay aus `ci.yml` lief zusätzlich lokal gegen einen frischen Export durch.
## Außerhalb dieses Pakets
- Redaktionelle Aufteilung, Beispiele, Verbote, Begründungen heraus: #142. Dort auch gut aufgehoben: eine Vorlage für die häufigen `Properties(...)`-Formen und der jetzt tote Docstring-Text unterhalb `\f`.
- Abhilfe in der Fehlerausgabe: #143.
- Rich-Ausgabe der Kommandos selbst (`doctor`, `version`, `_util`).
- Sprechende Metavars (`--page TITLE` statt `--page <str>`).
- Rund 76 Kommandozeilen mit Flags in 23 Instruction-Dateien bleiben ungeprüft; das ist #83.
- `network:` ist ein Boolean, der Netzzugriff mancher Kommandos hängt aber an der Konfiguration (`new` nur für `new project` mit Tracker) – dort steht `no`.
Changelog: Stub ausgearbeitet und gegen den Baum geprüft (Stand 2026-09-25). Body neu geschrieben: Befund mit Messwerten (Drift heute und früher, --help-Nutzung aus Transkripten, Token-Kosten des Rich-Rahmens), vier offene Entscheidungen D1–D4 mit Vorschlag, vorläufige Akzeptanzkriterien, zwei Nebenbefunde. Titel präzisiert. Labels: area/process, kind/decision, prio/planned, size/L; status/incoming entfernt.
Ursprünglicher Stub im Wortlaut (Titel: „Tool contract nicht mehr duplizieren“):
Wikitool Hilfe Multi funktional für ki und für Mensch per Option. So haben wir immer die Zugriffe einmal in der Hilfe und einmal im k Kontakt, was einerseits driften kann und andererseits Resonanz ist. Teilweise Kammer ich auch das Gefühl, dass das LLM ohnehin immer wieder —help aufruft.
Das fühlt sich komisch an
Wir sollten hier einmal schauen, ob es bessere Möglichkeiten gibt.
Lesart (Diktat): „im k Kontakt“ = im Contract (tools/CONTRACT.md), „Resonanz“ = Redundanz, „Kammer ich“ = habe ich.
**Changelog:** Stub ausgearbeitet und gegen den Baum geprüft (Stand 2026-09-25). Body neu geschrieben: Befund mit Messwerten (Drift heute und früher, `--help`-Nutzung aus Transkripten, Token-Kosten des Rich-Rahmens), vier offene Entscheidungen D1–D4 mit Vorschlag, vorläufige Akzeptanzkriterien, zwei Nebenbefunde. Titel präzisiert. Labels: `area/process`, `kind/decision`, `prio/planned`, `size/L`; `status/incoming` entfernt.
Ursprünglicher Stub im Wortlaut (Titel: „Tool contract nicht mehr duplizieren“):
> Wikitool Hilfe Multi funktional für ki und für Mensch per Option. So haben wir immer die Zugriffe einmal in der Hilfe und einmal im k Kontakt, was einerseits driften kann und andererseits Resonanz ist. Teilweise Kammer ich auch das Gefühl, dass das LLM ohnehin immer wieder —help aufruft.
> Das fühlt sich komisch an
> Wir sollten hier einmal schauen, ob es bessere Möglichkeiten gibt.
Lesart (Diktat): „im k Kontakt“ = im Contract (`tools/CONTRACT.md`), „Resonanz“ = Redundanz, „Kammer ich“ = habe ich.
torben
changed title from Tool contract nicht mehr duplizieren to Kommandoreferenz nur einmal: `--help` und `tools/CONTRACT.md` aus einer Quelle2026-09-25 19:14:36 +00:00
Changelog: D2 geändert auf Betreibervorgabe („baue auch für den Menschen den Rahmen aus und mache aus den --help Seiten üblichere Layouts nach gängigen Linux Konventionen. Es geht um Praktikabilität und nicht um Schönheit.“): kein Rich mehr, eine TTY-unabhängige Ausgabe für alle mit vollem Vertrag. B6 neu gefasst als GNU-Layout (Usage · Zusammenfassung · Purpose · Options · Exit status · Atomic · Retry · See also), plus -h-Alias und ungerahmte Usage-Fehler. B2 angepasst (Docstring = ein Satz). Befund ergänzt: gerahmte Usage-Fehler, -h von cli.main() als Hilfe gezählt, von Click abgelehnt. Kriterien: TTY-Hinweiszeile entfällt, neu Byte-Gleichheit mit/ohne TTY, Abschnittsreihenfolge, -h, rahmenfreie Fehler. Metavars und Rich-Ausgabe der Kommandos selbst ausdrücklich außerhalb.
**Changelog:** D2 geändert auf Betreibervorgabe („baue auch für den Menschen den Rahmen aus und mache aus den --help Seiten üblichere Layouts nach gängigen Linux Konventionen. Es geht um Praktikabilität und nicht um Schönheit.“): kein Rich mehr, eine TTY-unabhängige Ausgabe für alle mit vollem Vertrag. B6 neu gefasst als GNU-Layout (Usage · Zusammenfassung · Purpose · Options · Exit status · Atomic · Retry · See also), plus `-h`-Alias und ungerahmte Usage-Fehler. B2 angepasst (Docstring = ein Satz). Befund ergänzt: gerahmte Usage-Fehler, `-h` von `cli.main()` als Hilfe gezählt, von Click abgelehnt. Kriterien: TTY-Hinweiszeile entfällt, neu Byte-Gleichheit mit/ohne TTY, Abschnittsreihenfolge, `-h`, rahmenfreie Fehler. Metavars und Rich-Ausgabe der Kommandos selbst ausdrücklich außerhalb.
torben
changed title from Kommandoreferenz nur einmal: `--help` und `tools/CONTRACT.md` aus einer Quelle to Ein Datensatz je Kommando: `-h`, Index und `tools/CONTRACT.md` aus einer Quelle (Phase 1)2026-09-25 20:37:07 +00:00
Changelog: Auf neues Zielbild umgeschrieben (Betreiber: „vom weißen Blatt“, was einem LLM das Lesen erleichtert). Neu: ein Datensatz je Kommando im Man-Page-Aufbau mit typisierten Eigenschaften; drei Sichten aus einer Quelle (-h, Index-Zeile je Kommando, generierte tools/CONTRACT.md); die Tabellenform entfällt (D3 neu). Neu D4 (zwei Phasen, Phase 2 → #142), D5 (run_budget.py und AGENTS.md lesen die Eigenschaften aus dem Datensatz), D6 (Abhilfe in der Fehlerausgabe → #143). Befund ergänzt: Budget-Ausnahmen dreifach gepflegt; AGENTS.md-Liste nicht-idempotenter Kommandos widerspricht den Contract-Zeilen (version bump, version release, migrate done fehlen). Akzeptanzkriterium „kein Byte an den Tabellenzeilen“ ersetzt durch wörtliche Textbewahrung je Zelle. Modellempfehlung an den Anfang gestellt: Sonnet high, Opus nur für Versionsstelle/Changelog/AGENTS.md/Abschluss. Titel angepasst.
**Changelog:** Auf neues Zielbild umgeschrieben (Betreiber: „vom weißen Blatt“, was einem LLM das Lesen erleichtert). Neu: ein Datensatz je Kommando im Man-Page-Aufbau mit typisierten Eigenschaften; drei Sichten aus einer Quelle (`-h`, Index-Zeile je Kommando, generierte `tools/CONTRACT.md`); die Tabellenform entfällt (D3 neu). Neu D4 (zwei Phasen, Phase 2 → #142), D5 (`run_budget.py` und AGENTS.md lesen die Eigenschaften aus dem Datensatz), D6 (Abhilfe in der Fehlerausgabe → #143). Befund ergänzt: Budget-Ausnahmen dreifach gepflegt; AGENTS.md-Liste nicht-idempotenter Kommandos widerspricht den Contract-Zeilen (`version bump`, `version release`, `migrate done` fehlen). Akzeptanzkriterium „kein Byte an den Tabellenzeilen“ ersetzt durch wörtliche Textbewahrung je Zelle. Modellempfehlung an den Anfang gestellt: Sonnet `high`, Opus nur für Versionsstelle/Changelog/AGENTS.md/Abschluss. Titel angepasst.
Umsetzung (B1–B9) fertig, Version 7.1.0-beta.4, noch nicht published.
Neues Modul tools/chemenu/cli_contract.py (Datensatz-Typ, Registry, drei Renderer, GROUPS-Konstante). Alle 61 Kommandos (60 bestehende + neues docs contract) tragen jetzt einen @cli_contract.record(...)-Decorator in ihrem eigenen Modul. wikitool <cmd> -h/--help rendern identisch und TTY-unabhängig aus dem Datensatz (Rich aus, -h-Alias, kein Rahmenzeichen – geprüft über alle 61 Kommandos plus Top-Level-Fehler). tools/CONTRACT.md trägt die generierte <!-- wikitool:commands -->-Region (wikitool docs contract [--apply]), die alten zwei Tabellen sind weg. run_budget.is_exempt liest budget: aus dem Datensatz statt aus SKIP_COMMANDS/SKIP_COMMAND_PATHS (entfernt); Paritätstest gegen die alten Mengen ist grün. docs verify hat drei neue Prüfungen: Datensatz↔Registrierung (beide Richtungen), SYNOPSIS-Flags gegen Click (beide Richtungen, --push/--no-push-Paare durch Alternativ-Schreibweise erfüllt), keine Issue-Nummer im gerenderten Hilfetext (Docstring oberhalb \f, Options-help=). AGENTS.md § Tool error contract verweist jetzt auf den Index statt eine eigene Liste zu führen.
Textbewahrung: Migrationsskript (Scratch, nicht committet) hat alle 250 Zellentexte der alten Tabellen gegen die neuen Datensätze geprüft (per cli_contract, nicht gegen den gerenderten Text, da einige Datensätze den ersten Satz bewusst als NAME-Zeile abspalten). Ergebnis: der Wortinhalt aller Zellen ist vollständig in den Datensätzen wiederzufinden. Bei rund 16 Kommandos liegt der Text nicht mehr als ein zusammenhängender Block vor, sondern auf summary/notes verteilt (Trennzeichen an der Naht teils : → .) – inhaltlich nichts verloren, aber nicht byte-genau. Zwei Ausnahmen sind bewusst: docs verify und docs toc beschreiben jetzt ihr neues Verhalten, nicht mehr das alte Zwei-Tabellen-Schema. Einzige inhaltliche Änderung wie im Bauplan vorgesehen: xref add und xref link-source haben [--dry-run] in der SYNOPSIS gewonnen (fehlte vorher, obwohl beide Kommandos die Option immer schon hatten).
Nicht gemacht / bewusst offen gelassen:
AGENTS.md Invariante 1 nennt die generierte Region nicht explizit – der bestehende Präzedenzfall (<!-- wikitool:toc -->) ist dort auch nicht genannt, gleiche Behandlung.
B2 (Docstring = ein Satz oberhalb \f) ist nur dort konsequent durchgezogen, wo es für die Issue-Nummer-Prüfung nötig war; nicht jeder Docstring im Repo wurde durchgesehen.
Migrationsskript wurde nicht als Datei abgelegt (lief nur im Scratchpad dieser Sitzung).
docs verify, instructions verify, volle pytest-Suite (1505 Tests) grün. /code-review high läuft parallel im Hintergrund; Ergebnis kommt als eigener Kommentar oder in die nächste Sitzung. Noch nicht: wikitool publish (Nutzer stoppt die Sitzung bewusst davor).
**Umsetzung (B1–B9) fertig, Version 7.1.0-beta.4, noch nicht published.**
Neues Modul `tools/chemenu/cli_contract.py` (Datensatz-Typ, Registry, drei Renderer, `GROUPS`-Konstante). Alle 61 Kommandos (60 bestehende + neues `docs contract`) tragen jetzt einen `@cli_contract.record(...)`-Decorator in ihrem eigenen Modul. `wikitool <cmd> -h`/`--help` rendern identisch und TTY-unabhängig aus dem Datensatz (Rich aus, `-h`-Alias, kein Rahmenzeichen – geprüft über alle 61 Kommandos plus Top-Level-Fehler). `tools/CONTRACT.md` trägt die generierte `<!-- wikitool:commands -->`-Region (`wikitool docs contract [--apply]`), die alten zwei Tabellen sind weg. `run_budget.is_exempt` liest `budget:` aus dem Datensatz statt aus `SKIP_COMMANDS`/`SKIP_COMMAND_PATHS` (entfernt); Paritätstest gegen die alten Mengen ist grün. `docs verify` hat drei neue Prüfungen: Datensatz↔Registrierung (beide Richtungen), SYNOPSIS-Flags gegen Click (beide Richtungen, `--push`/`--no-push`-Paare durch Alternativ-Schreibweise erfüllt), keine Issue-Nummer im gerenderten Hilfetext (Docstring oberhalb `\f`, Options-`help=`). AGENTS.md § Tool error contract verweist jetzt auf den Index statt eine eigene Liste zu führen.
**Textbewahrung:** Migrationsskript (Scratch, nicht committet) hat alle 250 Zellentexte der alten Tabellen gegen die neuen Datensätze geprüft (per `cli_contract`, nicht gegen den gerenderten Text, da einige Datensätze den ersten Satz bewusst als NAME-Zeile abspalten). Ergebnis: der Wortinhalt aller Zellen ist vollständig in den Datensätzen wiederzufinden. Bei rund 16 Kommandos liegt der Text nicht mehr als ein zusammenhängender Block vor, sondern auf `summary`/`notes` verteilt (Trennzeichen an der Naht teils `:` → `.`) – inhaltlich nichts verloren, aber nicht byte-genau. Zwei Ausnahmen sind bewusst: `docs verify` und `docs toc` beschreiben jetzt ihr neues Verhalten, nicht mehr das alte Zwei-Tabellen-Schema. Einzige inhaltliche Änderung wie im Bauplan vorgesehen: `xref add` und `xref link-source` haben `[--dry-run]` in der SYNOPSIS gewonnen (fehlte vorher, obwohl beide Kommandos die Option immer schon hatten).
**Nicht gemacht / bewusst offen gelassen:**
- AGENTS.md Invariante 1 nennt die generierte Region nicht explizit – der bestehende Präzedenzfall (`<!-- wikitool:toc -->`) ist dort auch nicht genannt, gleiche Behandlung.
- B2 (Docstring = ein Satz oberhalb `\f`) ist nur dort konsequent durchgezogen, wo es für die Issue-Nummer-Prüfung nötig war; nicht jeder Docstring im Repo wurde durchgesehen.
- Migrationsskript wurde nicht als Datei abgelegt (lief nur im Scratchpad dieser Sitzung).
`docs verify`, `instructions verify`, volle `pytest`-Suite (1505 Tests) grün. `/code-review high` läuft parallel im Hintergrund; Ergebnis kommt als eigener Kommentar oder in die nächste Sitzung. Noch nicht: `wikitool publish` (Nutzer stoppt die Sitzung bewusst davor).
/code-review high gelaufen, 10 Funde, 6 behoben. Version jetzt 7.1.0-beta.4 (Bump unverändert, das sind Korrekturen an derselben, noch nicht publizierten Änderung).
Behoben:
render_text() (das echte wikitool <cmd> -h) hat Variant.notes verschluckt, obwohl render_markdown_section() (die CONTRACT.md-Kopie) sie schon zeigte – new projects Gate-Erklärung (--resume, Exit 42, Human-Intervention) fehlte im live -h. Gefixt, Regressionstest ergänzt, an new -h live geprüft.
AGENTS.md § Tool error contract: der verallgemeinerte Satz "immediately, for a non-idempotent command" widersprach dem eigenen Retry-Text mehrerer als idempotent=no eingestufter Kommandos (raw accept, task new, upload accept, …). Klargestellt: das "sofort, nicht einmal der eine Retry"-Verhalten gilt nur für Fall 4 (unklarer Ausgang durch Absturz/Timeout), nicht für Fall 2 (Validierungsfehler bekommt immer den einen Retry, unabhängig von Idempotenz).
network: war für review/task new/task list/task close/doctorno, obwohl die alle tatsächlich den Tracker-Provider übers Netz ansprechen (CalDAV, Super Productivity API) – jetzt yes. (new bleibt no: dort ist der Netzzugriff nur für new project und nur bei konfiguriertem Tracker relevant, der Regelfall macht keinen.)
check_no_issue_references_in_help prüfte nur Leaf-Commands, nie einer Typer-Gruppe eigenen help=-Text (z. B. wikitool xref -h rendert xref.pys Gruppen-Hilfe, nicht die eines Unterkommandos). Neue Funktion _group_click_commands(), in die Prüfung eingehängt – lief bereits sauber gegen den echten Baum, keine Nachbesserung an Gruppen-Texten nötig.
_leaf_click_commands() baute den Click-Baum zweimal pro docs verify-Lauf neu auf (einmal je Prüfung). @functools.lru_cache – Tests, die die Funktion selbst durch ein Lambda ersetzen, umgehen den Cache ohnehin.
cli.pys Monkeypatch auf typer._click.core.Command.format_help (typer 0.27s privater, vendorierter Click-Fork, keine Versionsobergrenze in requirements.txt) hatte keinen Fallback. Jetzt in try/except (ImportError, AttributeError): schlägt der Zugriff fehl, bleibt nur Rich aus (schon vorher gesetzt), keine Contract-Rendering – degradiert statt kaputt.
Nicht behoben, bewusst:
GROUPS als eigene, zentrale Konstante (Doppelung zu path= im Decorator) ist genau das im Bauplan entschiedene Design (B1), keine Abweichung.
Toter Docstring-Text unterhalb \f ist genau das in B2 vorgesehene Verhalten ("Wartungstext, nie gerendert"), kein Aufräumen vorgesehen.
Fehlende Properties-Factory für wiederkehrende Properties(...)-Formen: stilistisch, Phase-2-Kandidat.
Die alte "Iteration Budget Gate / Loop-Breaker"-Pseudozeile aus der alten Fehlerkontrakt-Tabelle hat keine Entsprechung im neuen Modell (passt nicht zu "ein echter Kommandopfad") – bleibt weiterhin nur in AGENTS.md § Gates und den Design notes beschrieben.
**`/code-review high` gelaufen, 10 Funde, 6 behoben.** Version jetzt 7.1.0-beta.4 (Bump unverändert, das sind Korrekturen an derselben, noch nicht publizierten Änderung).
Behoben:
- `render_text()` (das echte `wikitool <cmd> -h`) hat `Variant.notes` verschluckt, obwohl `render_markdown_section()` (die CONTRACT.md-Kopie) sie schon zeigte – `new project`s Gate-Erklärung (`--resume`, Exit 42, Human-Intervention) fehlte im live `-h`. Gefixt, Regressionstest ergänzt, an `new -h` live geprüft.
- AGENTS.md § Tool error contract: der verallgemeinerte Satz "immediately, for a non-idempotent command" widersprach dem eigenen Retry-Text mehrerer als `idempotent=no` eingestufter Kommandos (`raw accept`, `task new`, `upload accept`, …). Klargestellt: das "sofort, nicht einmal der eine Retry"-Verhalten gilt nur für Fall 4 (unklarer Ausgang durch Absturz/Timeout), nicht für Fall 2 (Validierungsfehler bekommt immer den einen Retry, unabhängig von Idempotenz).
- `network:` war für `review`/`task new`/`task list`/`task close`/`doctor` `no`, obwohl die alle tatsächlich den Tracker-Provider übers Netz ansprechen (CalDAV, Super Productivity API) – jetzt `yes`. (`new` bleibt `no`: dort ist der Netzzugriff nur für `new project` und nur bei konfiguriertem Tracker relevant, der Regelfall macht keinen.)
- `check_no_issue_references_in_help` prüfte nur Leaf-Commands, nie einer Typer-Gruppe eigenen `help=`-Text (z. B. `wikitool xref -h` rendert `xref.py`s Gruppen-Hilfe, nicht die eines Unterkommandos). Neue Funktion `_group_click_commands()`, in die Prüfung eingehängt – lief bereits sauber gegen den echten Baum, keine Nachbesserung an Gruppen-Texten nötig.
- `_leaf_click_commands()` baute den Click-Baum zweimal pro `docs verify`-Lauf neu auf (einmal je Prüfung). `@functools.lru_cache` – Tests, die die Funktion selbst durch ein Lambda ersetzen, umgehen den Cache ohnehin.
- `cli.py`s Monkeypatch auf `typer._click.core.Command.format_help` (typer 0.27s privater, vendorierter Click-Fork, keine Versionsobergrenze in requirements.txt) hatte keinen Fallback. Jetzt in `try/except (ImportError, AttributeError)`: schlägt der Zugriff fehl, bleibt nur Rich aus (schon vorher gesetzt), keine Contract-Rendering – degradiert statt kaputt.
Nicht behoben, bewusst:
- `GROUPS` als eigene, zentrale Konstante (Doppelung zu `path=` im Decorator) ist genau das im Bauplan entschiedene Design (B1), keine Abweichung.
- Toter Docstring-Text unterhalb `\f` ist genau das in B2 vorgesehene Verhalten ("Wartungstext, nie gerendert"), kein Aufräumen vorgesehen.
- Fehlende Properties-Factory für wiederkehrende `Properties(...)`-Formen: stilistisch, Phase-2-Kandidat.
- Die alte "Iteration Budget Gate / Loop-Breaker"-Pseudozeile aus der alten Fehlerkontrakt-Tabelle hat keine Entsprechung im neuen Modell (passt nicht zu "ein echter Kommandopfad") – bleibt weiterhin nur in AGENTS.md § Gates und den Design notes beschrieben.
`pytest` (1506 Tests), `docs verify`, `instructions verify` grün. Noch nicht: `wikitool publish`.
Changelog: Body auf den Endstand umgeschrieben und geschlossen. Gegenüber dem Plan-Stand: „Zielbild“ → „Ergebnis“, Bauplan um die beim Bauen getroffenen Festlegungen ergänzt (B5-Mechanik, B8-Auflösung flacher Kommandos, B9-Exportfehler), alle Akzeptanzkriterien abgehakt mit Nachweis. Nach dem ersten Publish kamen drei Commits dazu: b79f083 (README/INSTALL/DEVELOPMENT/docs), 5ffab3a (prog_name="wikitool" fehlte noch; die B5-Kriterien waren nur von Hand geprüft und sind jetzt Tests), 2a60f3a (CI-Fresh-Instance-Schritt schlug fehl, weil dist export das zitierte Strip-Markerpaar aus dem dist export-Datensatz schnitt). CI auf 2a60f3a grün (Läufe 370, 371). Die Läufe 365/367/368 auf den Zwischenständen sind aus demselben Grund rot.
**Changelog:** Body auf den Endstand umgeschrieben und geschlossen. Gegenüber dem Plan-Stand: „Zielbild“ → „Ergebnis“, Bauplan um die beim Bauen getroffenen Festlegungen ergänzt (B5-Mechanik, B8-Auflösung flacher Kommandos, B9-Exportfehler), alle Akzeptanzkriterien abgehakt mit Nachweis. Nach dem ersten Publish kamen drei Commits dazu: `b79f083` (README/INSTALL/DEVELOPMENT/docs), `5ffab3a` (`prog_name="wikitool"` fehlte noch; die B5-Kriterien waren nur von Hand geprüft und sind jetzt Tests), `2a60f3a` (CI-Fresh-Instance-Schritt schlug fehl, weil `dist export` das zitierte Strip-Markerpaar aus dem `dist export`-Datensatz schnitt). CI auf `2a60f3a` grün (Läufe 370, 371). Die Läufe 365/367/368 auf den Zwischenständen sind aus demselben Grund rot.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Erledigt (2026-09-26). Phase 1 ist umgesetzt und published:
26e1018(Hauptänderung),b79f083(Prosa-Nachzug in README/INSTALL/DEVELOPMENT/docs),5ffab3a(prog_name, Hilfe-Kriterien als Tests),2a60f3a(Export-Fix, siehe B9). Stand 7.1.0-beta.6 im laufenden Kandidaten. Folgepakete: #142 (redaktionelle Phase 2), #143 (Abhilfe in der Fehlerausgabe). Der ursprüngliche Stub steht wörtlich im ersten Kommentar.Ein
wikitool-Kommando wurde an mehreren Stellen beschrieben, alle von Hand gepflegt: im--help-Text, in den zwei Tabellen vontools/CONTRACT.md, und für einzelne Eigenschaften zusätzlich im Code (run_budget.py) und inAGENTS.md. Das verletzte AGENTS.md Invariante 8 (eine Regel, ein Ort) und das Kernprinzip „never re-derive, always compile“. Jetzt trägt jedes Kommando genau einen Datensatz im Code, aus dem alle Sichten erzeugt werden.Befund (Ausgangslage, gegen den Baum geprüft 2026-09-25)
--helptrug Flags, Kurzbeschreibung und teils Begründung;tools/CONTRACT.md(471 Zeilen, 60 Kommandos) Signatur und Verhalten in § Commands, Exit 1/Atomarität/Retry in § Error contracts.docs verifyprüfte nur die Anwesenheit des Kommandopfads.xref addundxref link-sourcenahmen--dry-run, ihre Signatur nannte es nicht. Früher: #93,CHANGES.md2.5.0.run_budget.py(SKIP_COMMANDS,SKIP_COMMAND_PATHS, Sonderfallversion regrade) und als Prosa in den Contract-Zeilen. Die AGENTS.md-Liste nicht-idempotenter Kommandos widersprach den Contract-Zeilen (version bump,version release,migrate donefehlten).wikitool … --help-Aufrufe in 43 von 96 Claude-Code-Sitzungen dieses Checkouts.-hwurde von Click abgelehnt; die Usage-Zeile nanntepython -m chemenu.cli; Issue-Nummern standen in ausgelieferter Hilfe (new,review, Gruppetask).Ergebnis
Eine Quelle, drei Sichten. Neues Modul
tools/chemenu/cli_contract.py: je Kommando einCommandRecord, per@cli_contract.record(...)an der Kommandofunktion in ihrem eigenen Modul. Alle 61 Kommandos (60 bestehende + neuesdocs contract) tragen einen. Daraus entstehen:wikitool <cmd> -h– der vollständige Datensatz als Klartext, mit und ohne TTY byte-gleich,-hund--helpidentisch, keine Rahmen.effect,idempotent,budget:,exit:, Zweck), inwikitool -hund oben intools/CONTRACT.md.tools/CONTRACT.md– die Region<!-- wikitool:commands -->ist generiert (wikitool docs contract [--apply]), je###-Gruppe die Datensätze als#### <cmd>. Die beiden Tabellen und § Error contracts gibt es nicht mehr.Abschnitte eines Datensatzes: NAME, SYNOPSIS (je Variante mit eigener Notiz), PROPERTIES (
effect,idempotent,atomic,budget,network,gates), OPTIONS (live aus Click, nur in-h), EXIT STATUS, ON FAILURE, NOTES. EXAMPLES, NEVER und SEE ALSO sind im Modell vorhanden und bleiben leer bis #142.Entscheidungen
--jsonerst mit einem Konsumenten.run_budget.pyliestbudget:aus dem Datensatz; AGENTS.md § Tool error contract verweist auf den Index statt eine eigene Liste zu führen.Wie gebaut (Bauplan, mit den beim Bauen getroffenen Festlegungen)
cli_contract.py:CommandRecord,Variant(usage, notes),Failure(label, exit_1, retry),Properties; EnumsEffect,Idempotent,Budget(counted/exempt/exempt_without_args),Network.GROUPSals geordnete Konstante. Ein Kommando, das nie mit Exit 1 endet, trägt keineFailure; der alte Zellentext „Never fails“ steht dann in NOTES.\fist überall dort gesetzt, wo sonst eine Issue-Nummer oder Wartungstext im gerenderten Teil stünde; der Rest bleibt unterhalb als nie gerenderter Wartungstext. Nicht jeder Docstring im Repo wurde auf einen Satz gekürzt – da-hjetzt vollständig aus dem Datensatz rendert, zeigt sich der Docstring nur noch in Clicks Gruppenlisten.docs verifyvergleicht in beiden Richtungen;hidden=Truezählt nicht; bei--push/--no-pushgenügt eine der beiden Schreibweisen.render_text,render_markdown_section,render_index_line/render_index,render_commands_region. OPTIONS mit fester Breite 80, damit die Ausgabe vom Terminal unabhängig bleibt.typer.core.HAS_RICH = Falsebeim Import voncli.py;-hpercontext_settingsauf der Wurzel (vererbt sich auf alle Gruppen);prog_name="wikitool". Mechanik: ein globaler Patch auftyper._click.core.Command.format_help– typer 0.27 vendoriert einen eigenen Click-Fork,TyperCommandundTyperGroupfallen beiHAS_RICH = Falsebeide dorthin durch. Weil das ein privates Modul ist, steht der Patch intry/except: fehlt es in einer künftigen typer-Version, bleibt die Hilfe ungerahmt, nur ohne Datensatz-Rendering. Eine reine Zwischengruppe (wikitool xref -h) hat keinen Datensatz und zeigt Clicks Standardliste.tools/CONTRACT.mdgeneriert. Handgeschrieben bleiben Einleitung (Grep-Rezept ersetzt durch-h, Index-grepundgrep '^#### '), Setup, Usage, Design notes (dort steht weiterhin der Iteration-Budget-Eintrag), Tests, Maintenance schedule.docs verify.check_cli_readmeersetzt durchcheck_command_contracts(Datensatz ↔ Registrierung ↔GROUPS, beide Richtungen, keine Doppelung),check_commands_region,check_synopsis_flags,check_no_issue_references_in_help(Docstring oberhalb\f, Options-help=, und – nach dem Code-Review ergänzt – der eigenehelp=-Text jeder Typer-Gruppe).run_budget.pyliest den Datensatz;SKIP_COMMANDS/SKIP_COMMAND_PATHSsind entfernt. Ein flaches Kommando (search,doctor,review) wird vor jeder Unterkommando-Deutung gesucht, damit eine Suchanfrage wiestatusnicht als Unterkommando gelesen wird; bareswikitool versionwird aufversion showabgebildet.dist exportentferntdist:strip-Markerspannen aus ausgelieferten Dateien, und derdist export-Datensatz zitierte das Markerpaar wörtlich – der Export schnitt es austools/CONTRACT.md, die frische Instanz meldete ihre Region als veraltet. (Die alte Tabellenzeile wurde genauso verstümmelt, nur verglich das niemand.) Behoben in2a60f3a, ein Test prüft seitdem, dass der Exportplantools/CONTRACT.mdbyte-gleich ausliefert./code-review highlief vor dem Publish: 10 Funde, 6 behoben (u. a. fehltenVariant.notesim live-h;network:stand fürreview/task */doctorfälschlich aufno), 4 bewusst nicht (siehe Kommentar vom 2026-09-25).Akzeptanzkriterien
summaryundnotesverteilt statt ein zusammenhängender Block. Bewusste Abweichungen:docs verifyunddocs tocbeschreiben ihr neues Verhalten;xref addundxref link-sourcehaben[--dry-run]in der SYNOPSIS gewonnen; derdist export-Datensatz nennt die Strip-Marker, ohne das Paar wörtlich zu zitieren.GROUPS-Eintrag ohne Kommando lassendocs verifyfehlschlagen (je ein Test, dazu doppelterGROUPS-Eintrag).wikitool publish -hist mit und ohne TTY byte-gleich, beginnt mitNAME, Abschnitte in Reihenfolge, EXIT STATUS nennt1und42(test_cli.py).-hund--helpsind für jedes Kommando identisch (test_cli.py, über alle 61).wikitool(test_cli.py, unter dem echten Wrapper zusätzlich von Hand geprüft).budget:exemptentspricht genau den alten Mengen einschließlich bareversion;version regradeals einzigesexempt_without_args(Paritätstests intest_run_budget.py).run_budget.pyenthält keine eigene Liste von Kommandonamen mehr.wikitool -hlistetnew,log append,publish,upstream merge,version bump,version release,migrate donealsnon-idempotent(Test). Dabei klargestellt: „sofort melden, kein Retry“ gilt nur für einen unklaren Ausgang (Fall 4); ein Validierungsfehler bekommt immer den einen Retry.docs verifyprüft es.tools/CONTRACT.md-Einleitung und § Usage, die generierten Datensätze fürdocs verify/docs contract, AGENTS.md § Routing, § Tool error contract und § Changelog,tools/README.md(wie ein Kommando seinen Datensatz bekommt),instructions/dev/doc-pull-through.md,instructions/dev/stack-close/SKILL.md; nach dem Publish zusätzlich README.md, INSTALL.md, DEVELOPMENT.md unddocs/knowledge-and-commitment.md. AGENTS.md Invariante 1 nennt die Region nicht – wie die bestehende<!-- wikitool:toc -->-Region;docs verifyhält sie.docs verify,instructions verify, vollepytest-Suite (1512 Tests) grün; CI auf2a60f3agrün (Läufe 370 und 371, inkl. Fresh-Instance-Schritt); die Fresh-Instance-Replay ausci.ymllief zusätzlich lokal gegen einen frischen Export durch.Außerhalb dieses Pakets
Properties(...)-Formen und der jetzt tote Docstring-Text unterhalb\f.doctor,version,_util).--page TITLEstatt--page <str>).network:ist ein Boolean, der Netzzugriff mancher Kommandos hängt aber an der Konfiguration (newnur fürnew projectmit Tracker) – dort stehtno.Changelog: Stub ausgearbeitet und gegen den Baum geprüft (Stand 2026-09-25). Body neu geschrieben: Befund mit Messwerten (Drift heute und früher,
--help-Nutzung aus Transkripten, Token-Kosten des Rich-Rahmens), vier offene Entscheidungen D1–D4 mit Vorschlag, vorläufige Akzeptanzkriterien, zwei Nebenbefunde. Titel präzisiert. Labels:area/process,kind/decision,prio/planned,size/L;status/incomingentfernt.Ursprünglicher Stub im Wortlaut (Titel: „Tool contract nicht mehr duplizieren“):
Lesart (Diktat): „im k Kontakt“ = im Contract (
tools/CONTRACT.md), „Resonanz“ = Redundanz, „Kammer ich“ = habe ich.Tool contract nicht mehr duplizierento Kommandoreferenz nur einmal: `--help` und `tools/CONTRACT.md` aus einer QuelleChangelog: D1–D4 vom Betreiber entschieden (alle wie vorgeschlagen: Code als Quelle, implizite Agentenform, Migration 1:1, Tabellen bleiben generiert). Neu: Bauplan B1–B8, Reihenfolge, Akzeptanzkriterien als prüfbare Eigenschaften. Nebenbefunde (Issue-Nummern in
--help,prog_name,xref --dry-run) in den Bauplan übernommen.kind/decision→kind/build;size/Lbleibt (Migration über ~28 Module, voraussichtlich zwei Sitzungen).Changelog: D2 geändert auf Betreibervorgabe („baue auch für den Menschen den Rahmen aus und mache aus den --help Seiten üblichere Layouts nach gängigen Linux Konventionen. Es geht um Praktikabilität und nicht um Schönheit.“): kein Rich mehr, eine TTY-unabhängige Ausgabe für alle mit vollem Vertrag. B6 neu gefasst als GNU-Layout (Usage · Zusammenfassung · Purpose · Options · Exit status · Atomic · Retry · See also), plus
-h-Alias und ungerahmte Usage-Fehler. B2 angepasst (Docstring = ein Satz). Befund ergänzt: gerahmte Usage-Fehler,-hvoncli.main()als Hilfe gezählt, von Click abgelehnt. Kriterien: TTY-Hinweiszeile entfällt, neu Byte-Gleichheit mit/ohne TTY, Abschnittsreihenfolge,-h, rahmenfreie Fehler. Metavars und Rich-Ausgabe der Kommandos selbst ausdrücklich außerhalb.Kommandoreferenz nur einmal: `--help` und `tools/CONTRACT.md` aus einer Quelleto Ein Datensatz je Kommando: `-h`, Index und `tools/CONTRACT.md` aus einer Quelle (Phase 1)Changelog: Auf neues Zielbild umgeschrieben (Betreiber: „vom weißen Blatt“, was einem LLM das Lesen erleichtert). Neu: ein Datensatz je Kommando im Man-Page-Aufbau mit typisierten Eigenschaften; drei Sichten aus einer Quelle (
-h, Index-Zeile je Kommando, generiertetools/CONTRACT.md); die Tabellenform entfällt (D3 neu). Neu D4 (zwei Phasen, Phase 2 → #142), D5 (run_budget.pyund AGENTS.md lesen die Eigenschaften aus dem Datensatz), D6 (Abhilfe in der Fehlerausgabe → #143). Befund ergänzt: Budget-Ausnahmen dreifach gepflegt; AGENTS.md-Liste nicht-idempotenter Kommandos widerspricht den Contract-Zeilen (version bump,version release,migrate donefehlen). Akzeptanzkriterium „kein Byte an den Tabellenzeilen“ ersetzt durch wörtliche Textbewahrung je Zelle. Modellempfehlung an den Anfang gestellt: Sonnethigh, Opus nur für Versionsstelle/Changelog/AGENTS.md/Abschluss. Titel angepasst.Umsetzung (B1–B9) fertig, Version 7.1.0-beta.4, noch nicht published.
Neues Modul
tools/chemenu/cli_contract.py(Datensatz-Typ, Registry, drei Renderer,GROUPS-Konstante). Alle 61 Kommandos (60 bestehende + neuesdocs contract) tragen jetzt einen@cli_contract.record(...)-Decorator in ihrem eigenen Modul.wikitool <cmd> -h/--helprendern identisch und TTY-unabhängig aus dem Datensatz (Rich aus,-h-Alias, kein Rahmenzeichen – geprüft über alle 61 Kommandos plus Top-Level-Fehler).tools/CONTRACT.mdträgt die generierte<!-- wikitool:commands -->-Region (wikitool docs contract [--apply]), die alten zwei Tabellen sind weg.run_budget.is_exemptliestbudget:aus dem Datensatz statt ausSKIP_COMMANDS/SKIP_COMMAND_PATHS(entfernt); Paritätstest gegen die alten Mengen ist grün.docs verifyhat drei neue Prüfungen: Datensatz↔Registrierung (beide Richtungen), SYNOPSIS-Flags gegen Click (beide Richtungen,--push/--no-push-Paare durch Alternativ-Schreibweise erfüllt), keine Issue-Nummer im gerenderten Hilfetext (Docstring oberhalb\f, Options-help=). AGENTS.md § Tool error contract verweist jetzt auf den Index statt eine eigene Liste zu führen.Textbewahrung: Migrationsskript (Scratch, nicht committet) hat alle 250 Zellentexte der alten Tabellen gegen die neuen Datensätze geprüft (per
cli_contract, nicht gegen den gerenderten Text, da einige Datensätze den ersten Satz bewusst als NAME-Zeile abspalten). Ergebnis: der Wortinhalt aller Zellen ist vollständig in den Datensätzen wiederzufinden. Bei rund 16 Kommandos liegt der Text nicht mehr als ein zusammenhängender Block vor, sondern aufsummary/notesverteilt (Trennzeichen an der Naht teils:→.) – inhaltlich nichts verloren, aber nicht byte-genau. Zwei Ausnahmen sind bewusst:docs verifyunddocs tocbeschreiben jetzt ihr neues Verhalten, nicht mehr das alte Zwei-Tabellen-Schema. Einzige inhaltliche Änderung wie im Bauplan vorgesehen:xref addundxref link-sourcehaben[--dry-run]in der SYNOPSIS gewonnen (fehlte vorher, obwohl beide Kommandos die Option immer schon hatten).Nicht gemacht / bewusst offen gelassen:
<!-- wikitool:toc -->) ist dort auch nicht genannt, gleiche Behandlung.\f) ist nur dort konsequent durchgezogen, wo es für die Issue-Nummer-Prüfung nötig war; nicht jeder Docstring im Repo wurde durchgesehen.docs verify,instructions verify, vollepytest-Suite (1505 Tests) grün./code-review highläuft parallel im Hintergrund; Ergebnis kommt als eigener Kommentar oder in die nächste Sitzung. Noch nicht:wikitool publish(Nutzer stoppt die Sitzung bewusst davor)./code-review highgelaufen, 10 Funde, 6 behoben. Version jetzt 7.1.0-beta.4 (Bump unverändert, das sind Korrekturen an derselben, noch nicht publizierten Änderung).Behoben:
render_text()(das echtewikitool <cmd> -h) hatVariant.notesverschluckt, obwohlrender_markdown_section()(die CONTRACT.md-Kopie) sie schon zeigte –new projects Gate-Erklärung (--resume, Exit 42, Human-Intervention) fehlte im live-h. Gefixt, Regressionstest ergänzt, annew -hlive geprüft.idempotent=noeingestufter Kommandos (raw accept,task new,upload accept, …). Klargestellt: das "sofort, nicht einmal der eine Retry"-Verhalten gilt nur für Fall 4 (unklarer Ausgang durch Absturz/Timeout), nicht für Fall 2 (Validierungsfehler bekommt immer den einen Retry, unabhängig von Idempotenz).network:war fürreview/task new/task list/task close/doctorno, obwohl die alle tatsächlich den Tracker-Provider übers Netz ansprechen (CalDAV, Super Productivity API) – jetztyes. (newbleibtno: dort ist der Netzzugriff nur fürnew projectund nur bei konfiguriertem Tracker relevant, der Regelfall macht keinen.)check_no_issue_references_in_helpprüfte nur Leaf-Commands, nie einer Typer-Gruppe eigenenhelp=-Text (z. B.wikitool xref -hrendertxref.pys Gruppen-Hilfe, nicht die eines Unterkommandos). Neue Funktion_group_click_commands(), in die Prüfung eingehängt – lief bereits sauber gegen den echten Baum, keine Nachbesserung an Gruppen-Texten nötig._leaf_click_commands()baute den Click-Baum zweimal prodocs verify-Lauf neu auf (einmal je Prüfung).@functools.lru_cache– Tests, die die Funktion selbst durch ein Lambda ersetzen, umgehen den Cache ohnehin.cli.pys Monkeypatch auftyper._click.core.Command.format_help(typer 0.27s privater, vendorierter Click-Fork, keine Versionsobergrenze in requirements.txt) hatte keinen Fallback. Jetzt intry/except (ImportError, AttributeError): schlägt der Zugriff fehl, bleibt nur Rich aus (schon vorher gesetzt), keine Contract-Rendering – degradiert statt kaputt.Nicht behoben, bewusst:
GROUPSals eigene, zentrale Konstante (Doppelung zupath=im Decorator) ist genau das im Bauplan entschiedene Design (B1), keine Abweichung.\fist genau das in B2 vorgesehene Verhalten ("Wartungstext, nie gerendert"), kein Aufräumen vorgesehen.Properties(...)-Formen: stilistisch, Phase-2-Kandidat.pytest(1506 Tests),docs verify,instructions verifygrün. Noch nicht:wikitool publish.Changelog: Body auf den Endstand umgeschrieben und geschlossen. Gegenüber dem Plan-Stand: „Zielbild“ → „Ergebnis“, Bauplan um die beim Bauen getroffenen Festlegungen ergänzt (B5-Mechanik, B8-Auflösung flacher Kommandos, B9-Exportfehler), alle Akzeptanzkriterien abgehakt mit Nachweis. Nach dem ersten Publish kamen drei Commits dazu:
b79f083(README/INSTALL/DEVELOPMENT/docs),5ffab3a(prog_name="wikitool"fehlte noch; die B5-Kriterien waren nur von Hand geprüft und sind jetzt Tests),2a60f3a(CI-Fresh-Instance-Schritt schlug fehl, weildist exportdas zitierte Strip-Markerpaar aus demdist export-Datensatz schnitt). CI auf2a60f3agrün (Läufe 370, 371). Die Läufe 365/367/368 auf den Zwischenständen sind aus demselben Grund rot.torben referenced this issue2026-09-26 06:17:23 +00:00